# Methodology

The Corviduo preferred development pipeline for non-trivial work:

```
(optional) Vor → (required) Contract → branch (direct or AFK TDD) → verify against contract → merge/commit
```

Each step front-loads work into the cheapest place to do it:

- **Vor** front-loads ambiguity-resolution so the contract is sharp.
- **Contract** front-loads design so implementation is mechanical.
- **TDD** binds the contract to executable verification, vertical slice first.
- **Audit** closes the loop: code is checked against the spec, not the spec against the code.
- **Commit** lands the artifact + the supporting record together.

The contract is the load-bearing artifact in every path. Vor sharpens it; TDD executes against it; the audit verifies against it; the commit ships it.

---

## 1. Vor (optional)

When the ask carries ambiguity, run `/vor <ask>` before drafting the
contract. Vor routes through the Vor UI sidecar and produces a
structured response file: assumptions, questions with recommendations,
devil's-advocate pushback.

The `/vor` skill carries a built-in fuzziness gate that helps decide
whether to invoke. Unambiguous asks (concrete verb + noun + scope)
skip Vor and go straight to the contract.

A contract whose ambiguity was resolved via Vor is **Vor-graduated**:
`vor_graduated: true` in frontmatter. Sleipnir's INV-032 reads this
flag at intake and skips the plan-converge phase in AFK dispatch,
since the design questions are already resolved.

## 2. Contract (required)

Before any non-trivial implementation. The contract is the source of
truth that code is written to satisfy — not documentation of existing
code.

- Format spec: [`docs/contracts/CONTRACT-FORMAT.md`](contracts/CONTRACT-FORMAT.md) (v2.1 current).
- Module contracts: `docs/contracts/<module>.contract.md`.
- Issue-scoped contracts: `docs/contracts/issues/<N>.contract.md`, which
  additionally require a populated `prd:` block pinning the issue body
  + lock-in comment SHA hashes.

Function blocks carry `FN / BRIEF / PRE / POST / ERRORS / STATE / STEPS / TESTS`.
The TESTS section is the load-bearing artifact for step 3 — TDD reads
from there.

Skip the contract for: bug fixes that don't change signatures or
behavior, trivial helpers, config changes, doc-only changes (per
`CLAUDE.md` § Contract-first workflow).

## 3. Branch — direct or AFK TDD

From the contract, two execution paths. Both run red-green-refactor
against the contract's TESTS section per the `tdd` skill's
vertical-slice discipline — tracer bullet first, then incremental loop.
Never write all tests then all code (produces tests of *imagined*
behavior).

### Direct TDD

The developer writes the code RGR locally.

### AFK TDD (sleipnir-shaped)

For issue-scoped work, AFK dispatch via Sleipnir:

1. `/sleipnir-preflight <N>` validates the contract's `prd:` pin via
   `scripts/contract_drift_check.py`, posts the canonical agent
   preamble as a Gitea comment + pins it to the contract, then applies
   the `ready-for-agent` label via `tea`.
2. Sleipnir's daemon picks up the labelled issue, spawns an agent into
   a per-issue git worktree, drives plan → implement → review → fixup
   → merge → done → corpus.
3. Vor-graduated contracts skip the plan-converge phase per INV-032.

Pre-dispatch policy is hard: see `CLAUDE.md` § Issue → AFK dispatch
hygiene.

## 4. Verify against contract

The audit pass. `CONTRACT-FORMAT.md` § 6 (Audit protocol) defines the
nine-point structured verification:

1. Signature match
2. PRE enforcement
3. POST satisfaction
4. Step coverage
5. Error handling
6. Invariant preservation
7. Test coverage
8. Resume correctness
9. No extra behavior

- **Direct path**: the developer audits their own work, or a sibling
  pass (codex-via-Volva, peer-review-via-althing) performs the audit.
- **AFK path**: Sleipnir's review phase invokes the audit
  automatically; verdict gates fixup/merge.

## 5. Merge / commit

Audit-clean work merges to the project's main branch. Per `CLAUDE.md`
§ Persistent-memory + housekeeping commit-along rule,
`persistent-memory.md` rides with the merge if dirty. Same for any
housekeeping files where they exist (`HANDOFF-SUMMARY.md`,
`NEXT-STEPS.md`, `README.md`, `State-Of-Development.md`).

Atomic commits: one logical change per commit; new code + new tests +
doc updates ride together where they form a coherent unit. No
backwards-compat shims, deprecation periods, or rename aliases until
v1.x — when something is redesigned, the old code is deleted and all
references are updated in the same commit.

---

## What this file is, and isn't

This file describes the *pipeline*. Each step delegates to the
canonical that owns its mechanics:

| Step | Owned by |
|---|---|
| Vor | `/vor` skill (lives in Galdrabok) |
| Contract format | [`docs/contracts/CONTRACT-FORMAT.md`](contracts/CONTRACT-FORMAT.md) |
| TDD discipline | `tdd` skill |
| Sleipnir AFK | `/sleipnir-preflight`, `/sleipnir-scaffold` skills + Sleipnir daemon |
| Audit | `CONTRACT-FORMAT.md` § 6 |
| Commit hygiene | `PRACTICES.md` (slated to migrate from Galdrabok); `CLAUDE.md` § Persistent-memory commit-along |
| Principles | [`PRINCIPLES.md`](../PRINCIPLES.md) (what to optimize for across all of the above) |

This file is canonical at `corviduo-project-template/docs/methodology.md`
and pinned via `.corviduo-canonicals.toml`. When a derivative Corviduo
project seeds from the template, this file copies in alongside the rest
and is kept in sync by `scripts/canonical_sync.py` /
`scripts/canonical_drift.py`.