@iceinvein/agent-skills 0.2.0 → 0.4.0

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,

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": {