@iceinvein/agent-skills 0.3.0 → 0.4.0

package/skills/migrate/docs/reference.md

@@ -16,7 +16,7 @@ For how it is built and how to extend it, see [architecture.md](architecture.md)
 | `0` | Success |
 | `1` | A content or domain failure in a well-formed request. The request was serviceable and the answer is no: a gate found violations, a census does not balance, a queue file is unparseable. |
 | `2` | A malformed or unusable request. The command could not begin: a missing flag value, an unknown phase, a file that is absent or not valid JSON, no store above the cwd, a config that will not load. |
-| `3` | The store lock is unavailable: another process holds it, a holder looks stale, or the lock file has failed to parse across five consecutive reads, and force-unlocking was not requested. `import`, `census`, `phase --status`, and `reset` can return this; retry, or pass `--force-unlock` once you have confirmed no other agent is writing. |
+| `3` | The store lock is unavailable: another process holds it, a holder looks stale, or the lock file has failed to parse across five consecutive reads, and force-unlocking was not requested. `import`, `census`, `phase --status`, `reset`, `adjudicate` and `handoff` can return this; retry, or pass `--force-unlock` once you have confirmed no other agent is writing. |
 
 The split matters because an orchestrating agent should be able to tell "your
 generator is broken" from "your numbers are wrong" from "try again" without
@@ -30,9 +30,10 @@ mirror them exactly so there is no serialization layer.
 resolves inside `source.path`, following symlinks and case-insensitive volumes,
 and exits 2.
 
-**The store lock.** `import`, `census`, `phase --status`, and `reset` each hold
-one lock (`.migrate/.lock`) across their read-modify-write of the store, so two
-agents writing at once cannot silently drop each other's rows. A waiting caller polls
+**The store lock.** `import`, `census`, `phase --status`, `reset`, `adjudicate`
+and `handoff` each hold one lock (`.migrate/.lock`) across their read-modify-write
+of the store, so two agents writing at once cannot silently drop each other's
+rows. A waiting caller polls
 with backoff for up to 30 seconds by default. A holder confirmed no longer
 running is reported as stale rather than waited out further; so is a lock file
 that fails to parse on five consecutive reads (a lock file that is merely
@@ -164,7 +165,7 @@ unsigned, which is what stops exclusions accreting silently.
 
 ### Capabilities
 
-`capabilities.jsonl` has **no import path in this milestone**. Write it
+`capabilities.jsonl` has **no import path**. Write it
 directly, one JSON object per line:
 
 ```json
@@ -484,7 +485,7 @@ Recommend (c); usage suggests it is deprecated.
   containing `##` lines. An unclosed fence is a loud error.
 - BOM and CRLF are handled.
 
-## The ten gates
+## The twelve gates
 
 `migrate check` reports violations grouped by gate, always in this order. Every
 message names the specific offending row, path or id; there is no aggregate
@@ -508,18 +509,26 @@ The summary line is always printed, passing or failing:
 | `leaks` | **Opt-in, `--leaks`.** No value from `.migrate/.env` appears in a committed artifact or anywhere in git history. Messages name the variable and file, never the value. |
 | `source` | The source checkout has no uncommitted changes, when it is a git repo. |
 | `run-state` | Every phase through the checked terminus must be `done` in `phases.json`; a phase `done` while its immediate predecessor is still `pending` fails regardless of terminus; a lens or closer census naming a `batch` that `phases.json` never recorded committing (in `enumerate` or `extract` respectively) fails by name. |
+| `adjudication` | **Phase-scoped, from `--phase adjudicate` onward.** Every queue item is `adjudicated` and carries a non-empty ruling. Names each item that is not, with its severity. |
+| `handoff` | **Phase-scoped, from `--phase handoff` onward.** `handoff.json` exists; every requirement appears in some work item's `frs`; every `frs` entry resolves to a requirement; every `dependsOn` resolves to another work item's key; `basis.emitted` and `basis.confirmed` match the store. |
 
 **`check` is strict mid-run by design.** The census gate wants a record for
 every declared surface and closer, so it does not pass until a run is finished.
 Grouping by gate is what lets you tell an expected mid-run gap from a real
 defect.
 
-**`--phase <p>` narrows only the run-state gate, not the other nine.** Without
+**Two gates are phase-scoped; the other ten always run.**
+`adjudication` and `handoff` describe phases 6 and 7, so they are skipped when
+the checked terminus has not reached them. Without that, `migrate check --phase
+queue` would be red for an entire mid-run campaign, which is exactly what the
+posture split exists to prevent. No other gate has an entry in that map.
+
+**`--phase <p>` otherwise narrows only the run-state gate.** Without
 `--phase`, `run-state` requires every phase through `handoff` to be `done`, so
 exit 0 means the whole migration is complete. With `--phase enumerate`, it
 requires only `probe` and `enumerate` to be `done`, which is the mid-run
 posture: a coverage or census gap past that point still fails on its own gate,
-exactly as it would without `--phase`, because those nine gates read the store,
+exactly as it would without `--phase`, because those gates read the store,
 not the phase you named. Verified against a fresh store: `check --phase probe`
 reports one `run-state` violation (`probe`); plain `check` reports eight, one
 per phase.
@@ -588,3 +597,39 @@ is escaped so free text containing pipes or newlines cannot break a table.
 **`migrate status`**
 Read-only. Phase state, store counts, the gate summary line, and a resume
 pointer naming the first non-done phase and its last recorded batch.
+
+**`migrate adjudicate [<id>] [--ruling <text>] [--force]`**
+With no id, prints the review sheet: every queue item, severity first, each
+carrying the first line of its recommendation, closing with an open count. With
+an id and a ruling, rewrites that item's frontmatter: `status` becomes
+`adjudicated`, `ruling` is set, `adjudicated` gets today's date. Keys the
+command does not own keep their position and the body round-trips byte for
+byte. Writes no row file: the ruling's consequence goes through `migrate
+import`, and the command prints that next step. Refuses an unknown id at 2, an
+unparseable file at 1, an already-ruled item at 1 without `--force` (printing
+the existing ruling), and a ruling containing a line break at 2.
+
+**`migrate handoff [--adapter <markdown|github|flow>] [--dry-run]`**
+Emits one work item per capability, in dependency order, through the configured
+adapter, and writes `.migrate/handoff.json`. Refuses while the gate (citations
+and leaks both on, bounded at `adjudicate`) has violations, while any queue item
+is open, or while any requirement is blocked by an open item, naming every
+blocker at once. `--dry-run` prints the plan and writes nothing at all,
+`handoff.json` included. Adapters are idempotent: a second run over an unchanged
+store reports everything `unchanged`.
+
+**`migrate coverage [--adapter <name>]`**
+Built over **confirmed** requirements, read back through the adapter, with the
+non-confirmed exclusions reported per capability and the evidence named. Exits 1
+when `handoff.json` is absent (handoff has not run), when the adapter reports no
+throughput (named, rather than reported as zero built), and when a completion
+names a requirement the store does not have (the emitted work and the store have
+diverged).
+
+**`migrate forecast [--adapter <name>]`**
+Projects remaining work from two measured velocities and an owner-attested
+`.migrate/forecast-assumptions.md`, which is required: it refuses without one.
+Each scenario is labelled measured (`as-is` or `active`, carrying an uncertainty
+band) or an owner target (carrying none). Every figure whose input is unmeasured
+prints as omitted rather than as a zero, and a finished campaign says so rather
+than omitting every date.

package/skills/migrate/fixtures/fake-gh.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+// A stateful stand-in for `gh`, covering exactly the six invocations the
+// github adapter makes. Magpie's fake-gh.sh is a static case statement, which
+// is right for a tool that only reads; this adapter creates issues and then
+// has to find them again on the next run, so idempotency cannot be tested
+// against a fixture that forgets what it was told.
+//
+// State lives at <cwd>/gh-state.json and the invocation log at
+// <cwd>/gh-log.txt. Both are keyed off the working directory rather than off
+// environment variables, because the adapter already runs gh with cwd set to
+// the target root and a spawned child does not reliably pick up an env var a
+// test set on its own process after startup.
+//
+// Nothing here validates arguments the way real gh does. It exists to record
+// what the adapter asked for and to answer consistently, not to be a
+// specification of gh.
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+type Milestone = { number: number; title: string; description: string }
+type Issue = {
+  number: number
+  title: string
+  body: string
+  state: 'OPEN' | 'CLOSED'
+  closedAt: string | null
+  milestone: string | null
+}
+type State = { milestones: Milestone[]; issues: Issue[] }
+
+const statePath = join(process.cwd(), 'gh-state.json')
+const logPath = join(process.cwd(), 'gh-log.txt')
+const argv = process.argv.slice(2)
+
+appendFileSync(logPath, `${argv.join(' ')}\n`)
+
+function load(): State {
+  if (!existsSync(statePath)) return { milestones: [], issues: [] }
+  return JSON.parse(readFileSync(statePath, 'utf8')) as State
+}
+function save(state: State): void {
+  writeFileSync(statePath, JSON.stringify(state, null, 2))
+}
+function flag(name: string): string | undefined {
+  const at = argv.indexOf(name)
+  return at === -1 ? undefined : argv[at + 1]
+}
+// `gh api -f key=value` repeated; returns the value for a given key.
+function field(key: string): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] !== '-f') continue
+    const pair = argv[i + 1] ?? ''
+    if (pair.startsWith(`${key}=`)) return pair.slice(key.length + 1)
+  }
+  return undefined
+}
+
+const state = load()
+const out = (v: unknown): void => {
+  process.stdout.write(`${typeof v === 'string' ? v : JSON.stringify(v)}\n`)
+}
+
+if (argv[0] === 'repo' && argv[1] === 'view') {
+  out({ nameWithOwner: 'acme/target' })
+} else if (argv[0] === 'api' && (argv[2] === '-X' ? argv[3] : '') === 'POST') {
+  const title = field('title') ?? ''
+  const description = field('description') ?? ''
+  const number = state.milestones.length + 1
+  state.milestones.push({ number, title, description })
+  save(state)
+  out({ number, title, description })
+} else if (argv[0] === 'api') {
+  out(state.milestones)
+} else if (argv[0] === 'issue' && argv[1] === 'list') {
+  out(
+    state.issues.map((i) => ({
+      number: i.number,
+      title: i.title,
+      body: i.body,
+      state: i.state,
+      closedAt: i.closedAt,
+    })),
+  )
+} else if (argv[0] === 'issue' && argv[1] === 'create') {
+  const number = 100 + state.issues.length
+  state.issues.push({
+    number,
+    title: flag('--title') ?? '',
+    body: flag('--body') ?? '',
+    state: 'OPEN',
+    closedAt: null,
+    milestone: flag('--milestone') ?? null,
+  })
+  save(state)
+  out(`https://github.com/acme/target/issues/${number}`)
+} else if (argv[0] === 'issue' && argv[1] === 'edit') {
+  const number = Number(argv[2])
+  const issue = state.issues.find((i) => i.number === number)
+  if (!issue) {
+    process.stderr.write(`no issue ${number}\n`)
+    process.exit(1)
+  }
+  const body = flag('--body')
+  if (body !== undefined) issue.body = body
+  const milestone = flag('--milestone')
+  if (milestone !== undefined) issue.milestone = milestone
+  save(state)
+  out(`https://github.com/acme/target/issues/${number}`)
+} else {
+  process.stderr.write(`fake-gh: unhandled invocation: ${argv.join(' ')}\n`)
+  process.exit(1)
+}

package/skills/migrate/fixtures/flow-target/docs/WORK.md

@@ -0,0 +1,12 @@
+# Work
+
+The delivery ledger for this target. `migrate handoff --adapter flow` appends
+capabilities under `## Proposed`; everything else here belongs to the team.
+
+## In progress
+
+- [W01] Wire the deployment pipeline
+
+## Done
+
+- [W00] Repository scaffolding

package/skills/migrate/fixtures/flow-target/tools/flow/src/cli.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env bun
+// A faithful subset of the flow target's own capability parser, standing in
+// for `tools/flow/src/cli.ts` in a real Nexus `stack` target.
+//
+// This is NOT the target. It is a vendored subset of the rules in
+// quartex/Nexus at c2464ac, plugins/stack/templates/tools/flow/src/
+// capability.ts, reproduced so the migrate flow adapter has something to be
+// checked against. Every rule below cites the line it came from, and the
+// conformance test in scripts/__tests__/adapter-flow.test.ts asserts each one
+// independently, so a rule drifting in the real target shows up as a test that
+// no longer describes reality rather than as silence.
+//
+// Commands: `map` (no-op regeneration), `map --check` (validate every
+// capability file), `parity --json` (emit CapabilityCoverage[]).
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CAP_STATUSES = ['done', 'partial', 'minimal', 'todo'] // capability.ts:3
+const CONFIDENCES = ['Confirmed', 'Inferred', 'Speculative'] // capability.ts:6
+const ORIGINS = ['intended', 'poss-accidental', 'cruft'] // capability.ts:9
+const REQUIRED_FRONTMATTER = ['cap', 'ns', 'title', 'status'] // capability.ts:43
+const REQUIRED_SECTIONS = ['Functional requirements', 'Built', 'Remaining'] // capability.ts:44
+
+const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+// capability.ts:42
+const frIdPattern = (ns: string): RegExp => new RegExp(`^${escapeRegex(ns)}-\\d{3}$`)
+
+type Fr = { id: string; conf: string; origin: string }
+type Capability = { cap: string; ns: string; title: string; status: string; frs: Fr[]; built: string }
+
+function parseFrontmatter(raw: string): { data: Record<string, string>; body: string } {
+  const lines = raw.split('\n')
+  if (lines[0]?.trim() !== '---') return { data: {}, body: raw }
+  const close = lines.findIndex((l, i) => i > 0 && l.trim() === '---')
+  if (close === -1) return { data: {}, body: raw }
+  const data: Record<string, string> = {}
+  for (const line of lines.slice(1, close)) {
+    const at = line.indexOf(':')
+    if (at === -1) continue
+    data[line.slice(0, at).trim()] = line.slice(at + 1).trim()
+  }
+  return { data, body: lines.slice(close + 1).join('\n') }
+}
+
+// capability.ts:48. Sections are split on a line beginning '## ', which is why
+// an emitter must never put '## ' at the start of a line inside a table.
+function extractSections(body: string): Record<string, string> {
+  const sections: Record<string, string> = {}
+  const parts = body.split(/\n## /).map((p, i) => (i === 0 ? p : `## ${p}`))
+  for (const part of parts) {
+    const m = part.match(/^## (.+)\n/)
+    if (!m?.[1]) continue
+    sections[m[1].trim()] = part.slice(m[0].length).trim()
+  }
+  return sections
+}
+
+function parseFrTable(block: string, path: string, ns: string): Fr[] {
+  const frId = frIdPattern(ns)
+  const lines = block
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith('|'))
+  const seen = new Set<string>()
+  return lines.slice(2).map((line) => {
+    const cells = line
+      .split('|')
+      .slice(1, -1)
+      .map((c) => c.trim())
+    const [id, , , , , conf, origin] = cells
+    if (cells.length !== 7 || !id) throw new Error(`malformed FR row: ${id ?? line} in ${path}`) // capability.ts:74
+    if (!frId.test(id)) throw new Error(`invalid FR id: ${id} in ${path}`)
+    if (seen.has(id)) throw new Error(`duplicate FR id: ${id} in ${path}`)
+    seen.add(id)
+    if (!CONFIDENCES.includes(conf ?? '')) throw new Error(`invalid confidence: ${conf} in ${path}`)
+    if (!ORIGINS.includes(origin ?? '')) throw new Error(`invalid origin: ${origin} in ${path}`)
+    return { id, conf: conf ?? '', origin: origin ?? '' }
+  })
+}
+
+export function parseCapability(raw: string, path: string): Capability {
+  const { data, body } = parseFrontmatter(raw)
+  for (const field of REQUIRED_FRONTMATTER) {
+    if (!data[field]) throw new Error(`missing field: ${field} in ${path}`)
+  }
+  if (!CAP_STATUSES.includes(data.status ?? '')) {
+    throw new Error(`invalid status: ${data.status} in ${path}`)
+  }
+  const sections = extractSections(body)
+  for (const name of REQUIRED_SECTIONS) {
+    if (sections[name] === undefined) throw new Error(`missing section: ${name} in ${path}`)
+  }
+  return {
+    cap: data.cap ?? '',
+    ns: data.ns ?? '',
+    title: data.title ?? '',
+    status: data.status ?? '',
+    built: sections.Built ?? '',
+    frs: parseFrTable(sections['Functional requirements'] ?? '', path, data.ns ?? ''),
+  }
+}
+
+function loadAll(cwd: string): Capability[] {
+  const dir = join(cwd, 'docs/modernisation/capability-map')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((n) => n.endsWith('.md') && n !== 'pre-ledger-baseline.md')
+    .sort()
+    .map((n) => parseCapability(readFileSync(join(dir, n), 'utf8'), n))
+}
+
+const argv = process.argv.slice(2)
+const cwd = process.cwd()
+
+try {
+  if (argv[0] === 'map' && argv[1] === '--check') {
+    loadAll(cwd)
+    process.stdout.write('map: ok\n')
+  } else if (argv[0] === 'map') {
+    loadAll(cwd)
+    process.stdout.write('map: ok (regenerated)\n')
+  } else if (argv[0] === 'parity' && argv[1] === '--json') {
+    // The real computeParity (parity.ts:17) derives covered ids from merged
+    // slices plus a baseline, which needs a slice ledger this fixture has no
+    // reason to carry. The emitted shape is the real one; the derivation reads
+    // the `## Built` section instead, so a test can drive coverage.
+    const caps = loadAll(cwd)
+    process.stdout.write(
+      `${JSON.stringify(
+        caps.map((c) => {
+          const built = new Set(c.built.split(/[\s,]+/).filter((t) => t.length > 0))
+          const confirmed = c.frs.filter((f) => f.conf === 'Confirmed')
+          return {
+            cap: c.cap,
+            ns: c.ns,
+            title: c.title,
+            status: c.status,
+            confirmedTotal: confirmed.length,
+            covered: confirmed.filter((f) => built.has(f.id)).length,
+            coveredIds: confirmed.filter((f) => built.has(f.id)).map((f) => f.id),
+            uncoveredIds: confirmed.filter((f) => !built.has(f.id)).map((f) => f.id),
+          }
+        }),
+        null,
+        2,
+      )}\n`,
+    )
+  } else {
+    process.stderr.write(`flow: unhandled command: ${argv.join(' ')}\n`)
+    process.exit(1)
+  }
+} catch (e) {
+  process.stderr.write(`${(e as Error).message}\n`)
+  process.exit(1)
+}

package/skills/migrate/package.json

@@ -1,6 +1,6 @@
 {
   "name": "migrate",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "scripts": {

package/skills/migrate/references/phases/adjudicate.md

@@ -0,0 +1,161 @@
+# Phase 6: Adjudicate
+
+## Purpose
+
+Get an owner's decision on every open queue item, in one pass, and record
+each ruling where the gate reads it. Exit condition: every item in
+`.migrate/queue/` has `status: adjudicated` with a non-empty `ruling`, every
+downstream consequence of those rulings has been imported into the store,
+and `migrate phase adjudicate --status done` has run.
+
+This is the phase where the run stops being a mapping exercise. Nothing
+before it needed a human to decide anything; nothing after it can proceed
+until they have.
+
+## Inputs
+
+- `.migrate/queue/*.md`, everything filed by any earlier phase. Phase 5
+  made sure they are well-formed; this phase gets them decided.
+- The store, because most rulings have a consequence in it: an element's
+  `disposition`, a requirement's `confidence`, a requirement's `parity`.
+- The owner. This is the one phase whose input is not in the repository.
+
+## Procedure
+
+**Read the whole list before ruling on anything.** `migrate adjudicate` with
+no arguments prints the review sheet: every item, severity first, with the
+first line of its recommendation alongside. That last part is what makes one
+sitting possible, and it is the reason to start here rather than opening
+files:
+
+```
+migrate adjudicate
+
+q-mailer-unobservable [moderate] open - Recommend (b): nothing in the checkout shows this ever delivered mail.
+
+1 open
+```
+
+Items are ordered `critical`, `moderate`, `minor`, then by id, the same
+order `queue list` uses. Work down it.
+
+**Draft a ruling for each, then present them together.** The agent's job is
+to draft, not to decide. A drafted ruling that the owner accepts unchanged
+is a good outcome; a drafted ruling nobody read is the failure this phase
+exists to prevent. Present the whole set at once so the owner sees the
+shape of what they are agreeing to, rather than being walked through four
+separate decisions with no view of how they interact.
+
+**Record each approved ruling.** One command per item:
+
+```
+migrate adjudicate q-mailer-unobservable \
+  --ruling "out of scope until an operator confirms delivery ever worked"
+
+adjudicate: q-mailer-unobservable
+  status  open -> adjudicated
+  ruling  recorded
+next: apply the consequence with `migrate import`
+```
+
+The file's frontmatter afterwards, with the body untouched:
+
+```
+---
+id: q-mailer-unobservable
+severity: moderate
+status: adjudicated
+ruling: out of scope until an operator confirms delivery ever worked
+adjudicated: 2026-08-13
+---
+```
+
+Three things about that write are worth knowing before you rely on them.
+Keys the command does not own keep their position, so an item carrying its
+own extra frontmatter is not reordered. The body round-trips byte for byte,
+because it is the audit record of *why* the ruling was made and a rewrite
+that reflows it destroys the thing being audited. And the ruling is a
+single frontmatter line, so a ruling containing a newline is refused at
+exit 2 rather than written into a block it would corrupt. Keep rulings to
+one sentence; the reasoning belongs in the body, which already has it.
+
+**The verb does not touch the row files.** This is the part most likely to
+catch you out. `adjudicate` writes queue frontmatter and nothing else. A
+ruling that puts an element out of scope, or settles a requirement's
+confidence, or fixes a parity plan, is applied by `migrate import`, exactly
+as in phases 3 and 4. That is why the command prints `next: apply the
+consequence with 'migrate import'` on every success, and why this phase is
+not finished when the last item flips to `adjudicated`.
+
+Worked through: the ruling above says the mailer requirement is out of
+scope until someone confirms delivery. `UD-003` currently carries
+`confidence: {"kind": "queued", "queue": "q-mailer-unobservable"}`. The
+ruling does not change that by itself. If the decision is to leave the
+requirement recorded but unconfirmed, nothing further is needed and it
+simply stays outside the confirmed denominator that `migrate coverage`
+divides by. If the decision is that it is now settled, re-import the row
+with the confidence the ruling gives it.
+
+**Re-ruling refuses.** An item that already carries a ruling is not
+silently overwritten:
+
+```
+migrate adjudicate q-mailer-unobservable --ruling "changed my mind"
+
+adjudicate: q-mailer-unobservable is already adjudicated: out of scope until an operator confirms delivery ever worked
+adjudicate: pass --force to replace it
+```
+
+Exit 1, and the existing ruling is printed so you can see what `--force`
+would have replaced. An owner's recorded decision is not something a re-run
+that meant no harm should be able to discard.
+
+## The gate
+
+Gate 11, `adjudication`, checks exactly one thing: every queue item is
+`adjudicated` and carries a non-empty ruling. It names each item that is
+not, with its severity.
+
+The gate is phase-scoped: it does not fire when the checked terminus is below
+`adjudicate`, so `migrate check --phase queue` stays clean for a run that has
+not reached this phase yet. From `migrate check --phase adjudicate` onward it
+applies, and it also applies at any terminus once `phases.json` marks the
+adjudicate phase done, so a store cannot claim the phase and then be checked
+below it.
+
+An open item on a store that is otherwise complete reads:
+
+```
+  adjudication:
+    q-mailer-unobservable [moderate] is still open; every queue item needs a ruling before handoff
+```
+
+## Degradation
+
+- **The owner is unavailable.** Do not rule on their behalf and do not mark
+  the phase done. There is no partial-credit state here: an unruled item
+  blocks handoff, which is the correct outcome, because handing a build team
+  work whose open questions nobody answered is what this gate exists to
+  stop. Leave the phase `running` and say so in the handoff notes.
+- **An item turns out to need no decision.** It still needs a ruling. Record
+  the reason it needed nothing (`no action: the endpoint was removed before
+  this run started`); the gate wants a decision recorded, not a change made.
+- **A ruling that changes an earlier phase's output.** Apply it with the
+  same `migrate import` that phase used, then re-run `migrate check --phase
+  adjudicate`. Re-importing is an upsert by id, so it updates rather than
+  duplicating.
+- **A queue file that will not parse.** `adjudicate <id>` on it exits 1 and
+  names the grammar failure; fix the file with phase 5's grammar and try
+  again. An id with no file at all is exit 2, a different class: the request
+  never resolved to an item.
+
+## Commands
+
+```
+migrate adjudicate
+migrate adjudicate <id> --ruling "<text>"
+migrate adjudicate <id> --ruling "<text>" --force
+migrate import <elements|reqs|deltas> <batch.json>
+migrate check --phase adjudicate
+migrate phase adjudicate --status done
+```