@iceinvein/agent-skills 0.3.0 → 0.5.0

package/README.md

@@ -28,7 +28,7 @@ Auto-detects Claude Code, Cursor, Codex, or Gemini CLI. Use `--tool claude` to t
 
 | Skill | What it does |
 |-------|--------------|
-| **migrate** | Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue: measured surface coverage, an empirically derived capability seam, cited requirements, a parity plan, and a batch decision queue. Bundles a Bun CLI that enforces the coverage arithmetic and phase ordering instead of trusting it. |
+| **migrate** | Walks a legacy codebase through probe, enumerate, seam, extract, parity, queue, adjudicate and handoff: measured surface coverage, an empirically derived capability seam, cited requirements, a parity plan, a batch decision queue, and work items emitted to markdown, GitHub or a flow target with coverage and forecast read back. Bundles a Bun CLI that enforces the coverage arithmetic and phase ordering instead of trusting it. |
 
 ### Code Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -225,9 +225,9 @@
   },
   {
     "name": "migrate",
-    "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, or to resume, check, or report on a mapping run already under way.",
+    "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, queue, adjudicate and handoff, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, to hand mapped requirements to a delivery team, or to resume, check, report, or forecast a mapping run already under way.",
     "type": "prompt",
-    "version": "0.2.0"
+    "version": "0.3.0"
   },
   {
     "name": "module-secret-auditor",
@@ -283,7 +283,7 @@
     "name": "sluice",
     "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what every dispatched agent cost. Claude Code only; conflicts with the superpowers plugin.",
     "type": "prompt",
-    "version": "0.1.1"
+    "version": "0.2.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/migrate/README.md

@@ -8,9 +8,9 @@ directions per lens, derives a capability seam empirically rather than by
 guesswork, extracts cited functional requirements, plans parity against the
 source, and routes every ambiguity to a batch decision queue for a human to
 adjudicate. The coverage arithmetic, citation resolution, and phase ordering
-are enforced by a bundled Bun CLI instead of being self-reported. Two more
-phases, adjudicate and handoff, complete the walkthrough but ship no CLI verb
-yet; see the phases table below.
+are enforced by a bundled Bun CLI instead of being self-reported. Adjudicate
+and handoff complete the walkthrough, and `migrate coverage` and `migrate
+forecast` read delivery back through the medium handoff emitted into.
 
 ## Using it
 
@@ -31,14 +31,16 @@ that phase is current so a run never pays for prose it does not need yet.
 | 3 | Extract | `references/phases/extract.md` | `requirements.jsonl`, attribute/rule-sweep/closer census records, terminal element dispositions |
 | 4 | Parity | `references/phases/parity.md` | `deltas.jsonl` and a parity plan on every non-queued requirement |
 | 5 | Queue | `references/phases/queue.md` | Queue items carrying evidence, options and a recommendation for anything ambiguous |
-| 6 | Adjudicate | none yet | No verb ships in this version; `migrate status` and `migrate queue list` are the terminus |
-| 7 | Handoff | none yet | Same as adjudicate: no verb yet |
-
-A run in this version stops at the queue. `adjudicate` and `handoff` have no
-CLI verbs to complete them, so `migrate check --phase queue` is the
-practical terminus: its exit 0 is what "done, for now" means. Plain `migrate
-check` gates every phase through `handoff` and cannot pass yet for the same
-reason. `references/run-ops.md` covers what applies across every phase
+| 6 | Adjudicate | `references/phases/adjudicate.md` | A ruling on every queue item, recorded in its own frontmatter |
+| 7 | Handoff | `references/phases/handoff.md` | Work items in a delivery medium, plus `handoff.json` recording what was emitted |
+
+A run goes probe through handoff, and plain `migrate check`, with no
+`--phase`, gates every one of them: its exit 0 is what "the migration is
+mapped" means. `migrate check --phase <p>` is the mid-run form, and the two
+gates that describe phases 6 and 7 are phase-scoped so they stay silent
+until the checked terminus reaches them. Once handoff has run, `migrate
+coverage` and `migrate forecast` read delivery back through the same adapter
+that emitted the work. `references/run-ops.md` covers what applies across every phase
 rather than any one of them: subagent dispatch, the batch-checkpoint
 discipline, and what happens when two agents contend for the store lock.
 
@@ -69,10 +71,11 @@ directory. See `references/recipes/README.md` for the exact file shape.
 migrate check --phase <current-phase>
 ```
 
-bounds the run-state gate at that phase; the other nine gates always read
-the whole store, so a coverage or census gap past your current phase still
-fails on its own gate regardless of `--phase`. Citations are checked by
-default; pass `--no-citations` to skip that gate.
+bounds the run-state gate at that phase, and skips the two gates that
+describe phases the terminus has not reached (`adjudication` and `handoff`).
+The remaining nine always read the whole store, so a coverage or census gap
+past your current phase still fails on its own gate regardless of `--phase`.
+Citations are checked by default; pass `--no-citations` to skip that gate.
 
 ## Fixtures
 
@@ -92,12 +95,14 @@ end:
 
 `scripts/__tests__/e2e-express.test.ts` and
 `scripts/__tests__/e2e-webforms.test.ts` copy the respective fixture to a
-temp directory and drive the real CLI as a subprocess, probe through queue,
-through `init`, `import`, `census`, `phase`, `queue add`, `queue list`, and
-`check`, reconciling every row against the fixture's ground truth. Both end at
-`migrate check --phase queue` on exit 0, and then show plain `migrate check`
-failing on exactly `adjudicate` and `handoff`, the two phases with no verb in
-this version.
+temp directory and drive the real CLI as a subprocess through `init`,
+`import`, `census`, `phase`, `queue add`, `queue list`, and `check`,
+reconciling every row against the fixture's ground truth.
+`e2e-webforms.test.ts` runs probe through queue against the `aspnet` recipe.
+`e2e-express.test.ts` carries on past it, through `adjudicate`, `handoff`,
+`coverage` and `forecast`, and closes on plain `migrate check` at exit 0:
+the whole point of the unbounded gate is that some real run has to be able
+to reach it.
 
 Both show gates in both directions. Failing before they pass: the mid-run check
 after enumerate names the three closer records extract has not written yet, and
@@ -110,7 +115,7 @@ asserts the gate that should catch it does.
 
 - **[docs/reference.md](docs/reference.md)** is what you need to drive the CLI:
   the batch-file and census formats with worked examples, the row schemas and
-  their grammars, what each of the ten gates enforces, and the exit-code
+  their grammars, what each of the twelve gates enforces, and the exit-code
   convention. Ships with the installed skill.
 - **[docs/architecture.md](docs/architecture.md)** is for working on the skill
   itself: the module map, the rule that decides what belongs in the CLI rather
@@ -133,6 +138,8 @@ The store lives at `.migrate/` in the target repo and is committed.
 | `.migrate/phases.json` | object | per-phase status, batches, resume pointers |
 | `.migrate/seam.md` | prose | validator scripts and their raw output |
 | `.migrate/parity-basis.md` | prose | runnable-versus-source-only detection evidence |
+| `.migrate/handoff.json` | What handoff emitted, the refs that make a re-run idempotent, and the forecast basis |
+| `.migrate/forecast-assumptions.md` | Owner-attested forecast inputs; `migrate forecast` refuses without it |
 | `.migrate/queue/q-<slug>.md` | prose | evidence, options, recommendation |
 | `.migrate/.env` | secrets | runtime-lens credentials, gitignored |
 | `docs/migrate/*.md` | generated | human-readable views, written by `migrate report` |
@@ -151,6 +158,10 @@ The store lives at `.migrate/` in the target repo and is committed.
 | `migrate check [--phase <p>] [--no-citations] [--leaks]` | Runs the gates |
 | `migrate status` | Phase state, counts, resume pointer |
 | `migrate reset --phase <phase>` | Clears one phase's derived rows and returns it to `pending` |
+| `migrate adjudicate [<id>] [--ruling <text>] [--force]` | Prints the review sheet, or records one ruling |
+| `migrate handoff [--adapter <name>] [--dry-run]` | Emits the requirements as work items |
+| `migrate coverage [--adapter <name>]` | Built versus confirmed, read back through the adapter |
+| `migrate forecast [--adapter <name>]` | Projects remaining work from measured throughput |
 | `migrate report [--out <dir>]` | Renders markdown views |
 
 Run `migrate --help` for the same list from the CLI itself.
@@ -163,7 +174,8 @@ list at the same time. `import` and `census` touch `phases.json` incidentally,
 each moving a phase to `running` (unless it is already `done`) when they record
 a batch. Nothing else writes it at all.
 
-A lock failure on `import`, `census`, `phase --status`, or `reset` exits `3`;
+A lock failure on `import`, `census`, `phase --status`, `reset`, `adjudicate`
+or `handoff` exits `3`;
 pass `--force-unlock` once you have confirmed no other agent is actually
 writing.
 

package/skills/migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate
-description: Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, and queue, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, or to resume, check, or report on a mapping run already under way.
+description: Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, queue, adjudicate and handoff, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, to hand mapped requirements to a delivery team, or to resume, check, report, or forecast a mapping run already under way.
 ---
 
 # migrate
@@ -129,29 +129,89 @@ migrate phase queue --status done
 
 ### 6. Adjudicate
 
-A run stops at the queue in this version of the tool: `adjudicate` has no verb
-yet, so nothing here can move a queue item's status past `open`. `migrate
-status` and `migrate queue list` are the terminus; adjudication arrives with
-its verb in the next milestone.
+Produces a ruling on every queue item: `status: adjudicated` plus a `ruling`
+line, written into the item's own frontmatter.
+
+Read `references/phases/adjudicate.md` before dispatching anything.
+
+```
+migrate adjudicate
+migrate adjudicate <id> --ruling "<text>"
+migrate import <elements|reqs|deltas> <batch.json>
+migrate phase adjudicate --status done
+```
+
+Run `migrate adjudicate` with no arguments first: it prints the review sheet,
+severity first, each item carrying the first line of its recommendation, which
+is what makes one pass over the whole queue possible.
+
+The verb writes queue frontmatter and nothing else. A ruling's consequence in
+the store (an element's disposition, a requirement's confidence or parity) goes
+through `migrate import`, exactly as in phases 3 and 4, so the row files keep
+one writer and one validation path. The command prints that next step on every
+success because it is easy to believe the ruling did it for you.
 
 ### 7. Handoff
 
-`handoff` has no verb yet either, for the same reason. `migrate status` and
-`migrate queue list` remain the terminus; handoff arrives with its verb in the
-next milestone.
+Produces the requirements as work items in whatever the delivery team uses,
+one work item per capability in dependency order, plus `.migrate/handoff.json`
+recording what was emitted and the forecast basis.
+
+Read `references/phases/handoff.md` before dispatching anything.
+
+```
+migrate handoff --dry-run
+migrate handoff [--adapter <markdown|github|flow>]
+migrate phase handoff --status done
+```
+
+Three adapters: `markdown` (the default, a roadmap plus a file per capability),
+`github` (a milestone per capability, an issue per requirement), and `flow`
+(a Nexus `stack` target's capability map, and `docs/WORK.md` where it exists).
+
+Handoff refuses while anything is unresolved and names every blocker at once:
+the gate with citations and leaks both on, any queue item still open, and any
+requirement blocked by one. Blocked means a `queued` confidence or a sub-high
+`rubric` parity whose queue item is **still open**; once that item is
+adjudicated the requirement stops blocking, even though its confidence field
+still reads `queued`.
+
+`--dry-run` writes nothing at all, `handoff.json` included, so it is safe to
+run against a store you are still working on.
+
+## Reading progress back
+
+Once handoff has run, these two re-read delivery through the same adapter that
+emitted the work. They are the only part of this tool meant to be run
+repeatedly after the mapping run ends.
+
+```
+migrate coverage
+migrate forecast
+```
+
+`coverage` divides built by **confirmed** requirements, reports the
+non-confirmed exclusions separately, and names the evidence it read. `forecast`
+needs an owner-attested `.migrate/forecast-assumptions.md`, copied from
+`templates/forecast-assumptions.md`, and refuses without one; it labels every
+scenario as measured or as an owner target so an aspiration never reads as a
+fact.
 
 ## Checking as you go
 
 Run `migrate check --phase <current>` after every batch. It bounds the
-run-state gate at that phase; the other nine gates always read the whole
-store, so a coverage or census gap past your current phase still fails on its
-own gate regardless of `--phase`.
+run-state gate at that phase; the nine gates that are neither run-state nor
+phase-scoped always read the whole store, so a coverage or census gap past
+your current phase still fails on its own gate regardless of `--phase`.
 
 Run plain `migrate check` only when claiming the whole migration is complete:
-with no `--phase`, it gates every phase through `handoff`. In this version
-that cannot pass, because `adjudicate` and `handoff` have no verbs to complete
-them. `migrate check --phase queue` is the practical terminus for this
-milestone; its exit 0 is what "done, for now" means.
+with no `--phase`, it gates every phase through `handoff`, and its exit 0 is
+what "the migration is mapped" means.
+
+Two of the twelve gates are phase-scoped. `adjudication` and `handoff` describe
+phases 6 and 7, so they stay silent until the checked terminus reaches them;
+that is what keeps `migrate check --phase queue` usable for a whole mid-run
+campaign instead of red from the first batch.
 
 ```
 migrate check --phase queue

package/skills/migrate/bin/migrate.ts

@@ -18,12 +18,20 @@ Subcommands:
   queue add <file.md>             Add a queue item
   queue list [--open]             List queue items, severity first
   queue show <id>                 Print one queue item
+  adjudicate [<id>] [--ruling <text>] [--force] [--force-unlock]
+                                  Print the review sheet, or record one ruling
   check [--phase <p>] [--no-citations] [--leaks]
                                   Run the gates; without --phase, exit 0 means
                                   the whole migration is complete
   status                          Phase state, counts, resume pointer
   reset --phase <phase> [--force-unlock]
                                   Clear one phase's derived rows
+  handoff [--adapter <name>] [--dry-run] [--force-unlock]
+                                  Emit the ratified requirements as work items
+  coverage [--adapter <name>]     Built versus confirmed, read back through
+                                  the adapter that emitted the work
+  forecast [--adapter <name>]     Project remaining work from measured
+                                  throughput and attested assumptions
   report [--out <dir>]            Render markdown views
   --version                       Print the migrate version
   --help                          Show this message`
@@ -166,6 +174,38 @@ const HANDLERS: Record<string, Handler> = {
     const { runQueue } = await import('../scripts/queue-cmd.ts')
     return runQueue({ root, args })
   },
+  adjudicate: async (args) => {
+    const ruling = readFlag(args, '--ruling')
+    if (ruling.error) {
+      process.stderr.write(`adjudicate: ${ruling.error}\n`)
+      return 2
+    }
+    // Same rule as `phase`: a flag sitting in the first positional slot leaves
+    // the id undefined, which would silently downgrade a write to a listing
+    // nobody asked for. Any write-intent flag with no id to apply it to is
+    // that mistake, so it is refused rather than serviced.
+    const id = args[0]?.startsWith('--') ? undefined : args[0]
+    if (!id && (ruling.value !== undefined || args.includes('--force'))) {
+      process.stderr.write(
+        'adjudicate: want <id> before --ruling/--force, as in `adjudicate q-x --ruling "..."`\n',
+      )
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('adjudicate: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runAdjudicate } = await import('../scripts/adjudicate-cmd.ts')
+    return runAdjudicate({
+      root,
+      ...(id ? { id } : {}),
+      ...(ruling.value !== undefined ? { ruling: ruling.value } : {}),
+      ...(args.includes('--force') ? { force: true } : {}),
+      ...(args.includes('--force-unlock') ? { forceUnlock: true } : {}),
+    })
+  },
   check: async (args) => {
     const phase = readFlag(args, '--phase')
     if (phase.error) {
@@ -227,6 +267,56 @@ const HANDLERS: Record<string, Handler> = {
     const { runReset } = await import('../scripts/reset-cmd.ts')
     return runReset({ root, phase, ...(forceUnlock ? { forceUnlock: true } : {}) })
   },
+  handoff: async (args) => {
+    const adapter = readFlag(args, '--adapter')
+    if (adapter.error) {
+      process.stderr.write(`handoff: ${adapter.error}\n`)
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('handoff: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runHandoff } = await import('../scripts/handoff-cmd.ts')
+    return runHandoff({
+      root,
+      ...(adapter.value ? { adapter: adapter.value } : {}),
+      ...(args.includes('--dry-run') ? { dryRun: true } : {}),
+      ...(args.includes('--force-unlock') ? { forceUnlock: true } : {}),
+    })
+  },
+  coverage: async (args) => {
+    const adapter = readFlag(args, '--adapter')
+    if (adapter.error) {
+      process.stderr.write(`coverage: ${adapter.error}\n`)
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('coverage: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runCoverage } = await import('../scripts/coverage-cmd.ts')
+    return runCoverage({ root, ...(adapter.value ? { adapter: adapter.value } : {}) })
+  },
+  forecast: async (args) => {
+    const adapter = readFlag(args, '--adapter')
+    if (adapter.error) {
+      process.stderr.write(`forecast: ${adapter.error}\n`)
+      return 2
+    }
+    const { findStoreRoot } = await import('../scripts/paths.ts')
+    const root = await findStoreRoot(process.cwd())
+    if (!root) {
+      process.stderr.write('forecast: no .migrate store found above the cwd\n')
+      return 2
+    }
+    const { runForecast } = await import('../scripts/forecast-cmd.ts')
+    return runForecast({ root, ...(adapter.value ? { adapter: adapter.value } : {}) })
+  },
   report: async (args) => {
     const result = readFlag(args, '--out')
     if (result.error) {

package/skills/migrate/docs/architecture.md

@@ -7,9 +7,9 @@ file formats and gate behaviour, see [reference.md](reference.md).
 
 Three parts, one rule that decides which part gets a given piece of work.
 
-- **The skill** (`SKILL.md`, plus the six phase manuals under
-  `references/phases/` and the cross-cutting `references/run-ops.md`, all
-  landed in Milestone 2) holds judgment: what to look for in a legacy codebase,
+- **The skill** (`SKILL.md`, plus the eight phase manuals under
+  `references/phases/` and the cross-cutting `references/run-ops.md`) holds
+  judgment: what to look for in a legacy codebase,
   how to decide a requirement is confirmed rather than inferred, when to
   escalate to the queue.
 - **The CLI** (`bin/`, `scripts/`) holds anything that must not be
@@ -40,14 +40,22 @@ scripts/
   config.ts            config.toml load and write, TOML escaping
   store.ts             JSONL read, atomic write, id upsert, file readers
   lock.ts              store lock: serialises the read-modify-write in import,
-                       census, phase --status and reset
+                       census, phase --status, reset, adjudicate and handoff
   phases.ts            phases.json state and committed batches
   validate.ts          per-row shape validation shared by import and check
   census.ts            census kinds, balance and bounds invariants, subject identity
   citations.ts         resolves src refs against the source tree
   leaks.ts             scans artifacts and git history for env values
   queue.ts             queue item parsing and grammar
-  check.ts             composes the ten gates into a violation list
+  check.ts             loads the store once, runs GATE_ORDER, applies the
+                       phase-scope rule; holds no gate logic itself
+  gates/context.ts     GateContext: everything a gate may read
+  gates/<gate>.ts      one module per gate, twelve of them
+  handoff.ts           adapter contract, dependency order, preflight, handoff.json
+  adapters/*.ts        markdown, github, flow: one per delivery medium
+  coverage.ts          built over confirmed, per capability
+  assumptions.ts       parses and validates forecast-assumptions.md
+  forecast.ts          measured velocities, demand, scenario projection
   report.ts            markdown rendering
   *-cmd.ts             one per subcommand; argument handling and orchestration
 ```
@@ -109,7 +117,7 @@ and `init` shipped exactly that bug in Milestone 2.
 renames, and cleans up the temp file on failure without masking the original
 error. A fixed temp name was tried first and lost data under concurrent writes.
 
-**The read-modify-write around a store file is lock-serialised.** Four commands
+**The read-modify-write around a store file is lock-serialised.** Six commands
 do one. `import` and `census` each read a whole store file, upsert or replace
 rows, and rewrite the whole file; both also commit a batch into `phases.json`,
 via `recordBatch`, inside the same lock. `phase --status` does its own
@@ -127,7 +135,7 @@ one rename can still discard the other's rows.
 section must not take it. That is why `savePhases` and `recordBatch` are
 lock-free while `setPhaseStatus` is not, and why `reset-cmd.ts` calls
 `savePhases` rather than `setPhaseStatus` to move its phase back to `pending`.
-Check this before adding a call inside any of the four.
+Check this before adding a call inside any of them.
 
 `census-cmd.ts` orders its two writes deliberately: it commits the batch into
 `phases.json` first, and writes `census.jsonl` second. If the process is
@@ -139,7 +147,7 @@ orphan census row would be worse: a record naming a batch that was never
 actually committed, which is exactly the mismatch the run-state gate exists to
 catch.
 
-`lock.ts`'s `withStoreLock` wraps each of these four write paths in one lock
+`lock.ts`'s `withStoreLock` wraps each of these write paths in one lock
 file for the whole store (`.migrate/.lock`, `O_EXCL` create, bounded retry with
 backoff). It distinguishes a lock file that is merely absent or momentarily
 empty (never counted against a corruption budget) from one that is genuinely
@@ -180,20 +188,43 @@ store.
 
 ### Add a gate
 
-Gates live in `check.ts` and push `{ gate, message }` onto one list.
-
-1. Add the gate name to `GATE_ORDER`, which fixes its position in the report.
-2. Push violations that name the specific offending row, path or id. An
+Gates live one per module under `scripts/gates/`, each exporting
+`export const gate: Gate` over the shared `GateContext` that `check.ts` builds
+once per run. A gate is a pure function of that record: it may not read the
+store itself, which is what keeps the store parsed exactly once no matter how
+many gates consult it, and what stops a gate depending on another having run
+first. Add the name to `GATE_ORDER`, the module to `GATES`, and, only if the
+gate describes work a mid-run terminus has not reached, an entry to
+`GATE_PHASE`.
+
+1. Write `scripts/gates/<name>.ts` exporting `export const gate: Gate`, and
+   add the name to `GATE_ORDER`, which fixes its position in the report, and
+   the module to `GATES`.
+2. Return violations that name the specific offending row, path or id. An
    aggregate "check failed" is never acceptable; the message is what an agent
    acts on without a human.
-3. If the gate is expensive, make it opt-in behind a flag like `--leaks`, and
-   have `check-cmd.ts` pass it through. If it is cheap enough to want on by
-   default instead, follow citations: on unless the caller passes
-   `--no-citations`, so an orchestrator does not have to remember to ask for
-   it.
-4. Add tests for both directions. A gate that produces false failures is worse
+3. If the gate is expensive, make it opt-in behind a flag like `--leaks`, read
+   off `GateContext`, and have `check-cmd.ts` pass it through. If it is cheap
+   enough to want on by default instead, follow citations: on unless the caller
+   passes `--no-citations`.
+4. Only if the gate describes work a mid-run terminus has not reached, add an
+   entry to `GATE_PHASE`. This is a narrow escape hatch, not the norm: nine of
+   the twelve gates read the whole store regardless of `--phase`, and a tenth,
+   run-state, is bounded by the terminus rather than skipped. A defect is a
+   defect whenever it is found.
+5. Add tests for both directions. A gate that produces false failures is worse
    than no gate, because it makes `check` ignorable.
 
+### Add a handoff adapter
+
+`scripts/adapters/<name>.ts` exporting an `Adapter`, registered in the
+`ADAPTERS` map in `handoff-cmd.ts`, `coverage-cmd.ts` and `forecast-cmd.ts`.
+An adapter reaches the world only through `HandoffInput`'s `root`, `gitBin` and
+`ghBin`, which is what makes `github` testable against `fixtures/fake-gh.ts`
+and `flow` against `fixtures/flow-target/`. `apply()` must be idempotent, and
+must not destroy progress the medium is carrying: the markdown adapter reads
+its own roadmap before regenerating it for exactly that reason.
+
 ### Add a census kind
 
 1. Add the variant to the `Census` union in `types.ts`.
@@ -219,7 +250,7 @@ This is the main source-genericity lever: a COBOL source declares `programs`,
 `bun run typecheck` (tsc). All three must be clean.
 
 **A test that passes against a broken implementation is treated as a defect**,
-not a minor style issue. Two shipped during this milestone and both were caught
+not a minor style issue. Two shipped during Milestone 2 and both were caught
 only by mutation. When you add a regression test, verify it fails against the
 unfixed code: revert the source file with
 `git checkout <sha> -- <path>`, run the test, observe the failure, then restore
@@ -254,13 +285,17 @@ too:
   surfaces, three elements) and shows the gate failing on unaccounted elements
   before it passes. That arc is the point: a test that only demonstrates the
   passing state would be worth much less.
-- `e2e-express.test.ts` and `e2e-webforms.test.ts` drive the whole of each
-  fixture probe through queue: `init`, `import`, `census`, `phase`, `queue
-  add`, `queue list`, and `check`, ending green at `migrate check --phase
-  queue` and then asserting plain `migrate check` fails on exactly `adjudicate`
-  and `handoff`. Both parse `GROUND-TRUTH.md` for their element rows rather
-  than hand-copying them, so fixture and test cannot drift, and both close on a
-  mutation showing the terminus assertion is load-bearing.
+- `e2e-webforms.test.ts` drives the whole of `tiny-webforms` probe through
+  queue: `init`, `import`, `census`, `phase`, `queue add`, `queue list`, and
+  `check`, ending green at `migrate check --phase queue`.
+- `e2e-express.test.ts` carries on past that terminus through `adjudicate`,
+  `handoff`, `coverage` and `forecast`, and closes on plain `migrate check` at
+  exit 0. Some real run has to be able to reach the unbounded gate, or it
+  asserts nothing.
+
+Both parse `GROUND-TRUTH.md` for their element rows rather than hand-copying
+them, so fixture and test cannot drift, and both close on a mutation showing the
+terminus assertion is load-bearing.
 
 When you change a fixture, the tests that read it will tell you; when you
 change a manual the tests follow (`seam.md`'s clustering procedure,