@iceinvein/agent-skills 0.3.0 → 0.4.0

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

@@ -0,0 +1,220 @@
+# Phase 7: Handoff
+
+## Purpose
+
+Emit the mapped requirements into whatever a delivery team actually works
+from, in dependency order, and record what was emitted so progress can be
+read back. Exit condition: `.migrate/handoff.json` exists and accounts for
+every requirement, the adapter's artifacts are in the target, and `migrate
+phase handoff --status done` has run. After that, plain `migrate check`,
+with no `--phase`, exits 0, and that is what "the migration is mapped"
+means.
+
+This phase does not deliver anything. It hands over.
+
+## Inputs
+
+- `.migrate/requirements.jsonl` and `capabilities.jsonl`: what to emit and
+  how to group it.
+- `.migrate/config.toml`, `[handoff] adapter`: which medium. Overridable
+  per run with `--adapter`.
+- Whatever the chosen adapter reaches: the target repo for `markdown`,
+  `gh` for `github`, a flow target's own tree for `flow`.
+
+## Procedure
+
+**Choose the adapter once, in config, not per invocation.** `--adapter`
+exists for trying one out and for reading coverage back through a different
+medium than the one that emitted. Switching the configured adapter mid-run
+does not migrate anything that was already emitted; it emits again,
+somewhere else.
+
+| Adapter | Emits | Reads progress from |
+|---|---|---|
+| `markdown` | `docs/migrate/roadmap.md` plus one file per capability | ticked checkboxes in the roadmap, dated in the file |
+| `github` | a milestone per capability, an issue per requirement | closed issues, dated from `closedAt` |
+| `flow` | `docs/modernisation/capability-map/<slug>.md`, and a fenced block under `## Proposed` in `docs/WORK.md` when the target has one | `flow parity --json` in the target, undated |
+
+**Dry-run first.** `--dry-run` runs every refusal check and prints the plan
+without writing anything at all, `handoff.json` included:
+
+```
+migrate handoff --dry-run
+
+plan:
+  user-directory (3 requirement(s))
+handoff: dry run, 1 work item(s), nothing written
+```
+
+A capability appears after every capability it cites, which is what
+"dependency order" means here: capability A depends on B when a requirement
+in A carries a ledger citation to an element the seam assigned to B. If the
+graph has a cycle, its members are emitted in slug order and anything merely
+blocked by that cycle still sorts normally behind it. The cycle is broken rather
+than reported: `dependencyOrder` returns which capabilities were in one, but no
+caller prints it today, so a cyclic seam is resolved silently.
+
+**The refusals, and what each means.** Handoff will not emit while anything
+is unresolved, and it names every blocker at once rather than one per run:
+
+```
+migrate handoff
+
+handoff: [run-state] phase adjudicate is pending; every phase through adjudicate must be done
+handoff: [adjudication] q-mailer-unobservable [moderate] is still open; every queue item needs a ruling before handoff
+handoff: UD-003 blocked by q-mailer-unobservable
+handoff: refusing to emit with 3 blocker(s)
+```
+
+The gate run behind this has citations and leaks both switched on, because
+both are mandatory before handoff, and is bounded at `adjudicate` so that
+gate 12 (which wants the `handoff.json` this command has not written yet)
+cannot refuse the very run that would satisfy it.
+
+**"Blocked" is measured against open items, not against the confidence
+field.** A requirement blocks handoff when its `confidence` is `queued`, or
+its `parity` is a `rubric` below `high`, **and** the queue item it points at
+is still open. Once that item is adjudicated the decision is settled and the
+requirement stops blocking, even though its confidence still reads `queued`.
+This matters in practice: it means a ruling of "leave this one unconfirmed"
+does not oblige you to re-import the row before you can hand over.
+
+**Emit.**
+
+```
+migrate handoff
+
+handoff: adapter markdown, 1 work item(s), 3 requirement(s)
+  created   1
+  updated   0
+  unchanged 0
+next: mark the phase done with `migrate phase handoff --status done`, then read progress back with `migrate coverage`
+```
+
+Running it again over an unchanged store reports everything `unchanged` and
+writes nothing new. Every adapter is idempotent, and each achieves it
+differently: `markdown` compares rendered content, `github` finds its own
+issues by a `<!-- migrate:fr=... -->` marker at the start of the body, `flow`
+compares rendered content and then validates the result with the target's own
+`flow map --check`. A run that rewrote a shared file (the roadmap, `WORK.md`)
+reports its items `updated` rather than `unchanged`, so the status always
+reflects whether anything in the target moved.
+
+Each adapter owns only what it wrote. `github` regenerates the block above a
+closing fence in an issue body and leaves anything you add beneath it alone;
+`flow` rewrites only its own fenced block under `## Proposed` and never touches
+the rest of `WORK.md`. Editing a file somebody else writes in is the reason
+both boundaries are explicit rather than inferred from shape.
+
+**`handoff.json` is the record, and it carries no timestamps.**
+
+```jsonc
+{
+  "version": 1,
+  "adapter": "markdown",
+  "items": [
+    { "key": "user-directory", "title": "User Directory",
+      "frs": ["UD-001", "UD-002", "UD-003"], "dependsOn": [], "weight": 3 }
+  ],
+  "refs": { "user-directory": "docs/migrate/capabilities/user-directory.md" },
+  "basis": { "confirmed": 2, "emitted": 3, "order": ["user-directory"] }
+}
+```
+
+`emitted` is every requirement that reached a work item; `confirmed` is the
+denominator `migrate coverage` divides by, and the two differ by exactly the
+requirements handoff emits but parity does not hold the build to. The
+absence of dates is deliberate: every date this tool reports is read at read
+time from the adapter's medium, which is what lets two runs over one store
+produce identical bytes.
+
+**Using the `flow` adapter.** One constraint will catch you before anything
+else does. The flow target derives a requirement-id pattern from each
+capability's declared `ns` and rejects anything that does not match, so
+`plan()` refuses first, by name:
+
+```
+handoff: flow: 1 requirement id(s) do not match their capability's namespace pattern <ns>-NNN, which the flow target requires:
+  login-001 (capability user-management, ns UM)
+```
+
+Nothing is written when that fires. Fix the ids in the store (re-import with
+the corrected ids) rather than working around it: the alternative is a
+capability file the target cannot parse, in a repo this tool does not own.
+The adapter also translates on the way out, since the two vocabularies
+differ: `accidental-candidate` becomes `poss-accidental`, and the three
+confidence kinds become `Confirmed`, `Inferred` and `Speculative`.
+
+## The gate
+
+Gate 12, `handoff`, asks whether the requirements actually reached the
+emitted work. It checks that `handoff.json` exists and is well formed, that
+every requirement appears in exactly one work item, that every `frs` entry
+resolves to a requirement, that every `dependsOn` resolves to another work item
+and is not the item itself, that no work-item key repeats, that every item has
+a `refs` entry recording where it went, that `basis.order` and the work items
+name the same set, and that the basis counts match the store.
+
+Every requirement, not only the confirmed ones: an inferred requirement is
+something the build team must see and decide about, so handoff emits it.
+Confidence starts mattering at the coverage denominator, not here.
+
+Like gate 11 it is phase-scoped, so it does not fire below `--phase handoff`
+**unless `phases.json` already claims the phase is done**. A store whose own
+state file says it reached handoff cannot hide an unemitted handoff by being
+checked at an earlier terminus. Its honest limit is the same in kind as the run-state gate's: it
+proves the emitted work covers the store's requirements. It cannot prove the
+issues were read or the roadmap was believed.
+
+## Reading progress back
+
+`migrate coverage` divides built by confirmed and names its evidence:
+
+```
+built 2/2 confirmed requirements (100%)
+evidence: markdown roadmap checkboxes, dated in file
+excluded: 1 non-confirmed (user-directory 1)
+
+user-directory  2/2  done
+```
+
+`migrate forecast` needs an owner-attested `.migrate/forecast-assumptions.md`
+(copy `templates/forecast-assumptions.md`) and refuses without one. It
+projects from two measured velocities and labels every scenario as measured
+or as an owner target, so an aspiration never reads as a fact. Both commands
+are meant to be re-run as delivery proceeds; they are the only part of this
+tool that keeps working after the mapping run ends.
+
+## Degradation
+
+- **The adapter partially applied.** Re-run it. Every adapter is
+  idempotent, and finishing a partial apply by re-running is the designed
+  path. For `markdown` specifically, re-running preserves every ticked box
+  and its date, so picking up newly extracted requirements never costs the
+  owner their record of what was delivered.
+- **No flow CLI in the target.** The `flow` adapter still emits, and says on
+  stderr that the capability files were not validated against the target's
+  own parser. An unvalidated emission must not read as a checked one.
+- **`flow` coverage has no dates.** Expected. The flow target computes
+  covered from merged slices plus a baseline and keeps the dates in a slice
+  ledger this tool does not own, so every completion comes back undated.
+  Coverage still works; forecast's measured rows print `not projected` and
+  its target rows still project. Use `flow forecast` in the target for the
+  dated answer.
+- **An adapter with no throughput at all.** `coverage` names it rather than
+  reporting zero built. "This adapter cannot tell you" and "nothing has been
+  delivered" are very different claims.
+- **A completion naming a requirement the store does not have.** `coverage`
+  exits 1: the emitted work and the store have diverged, which is a real
+  problem rather than a degradation.
+
+## Commands
+
+```
+migrate handoff --dry-run
+migrate handoff [--adapter <markdown|github|flow>]
+migrate phase handoff --status done
+migrate check
+migrate coverage
+migrate forecast
+```

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

@@ -114,8 +114,8 @@ Running `migrate check --phase probe` here will not come back clean: the
 census gate reads the whole store regardless of `--phase`, so it reports
 every declared surface's lens record and every declared closer's record as
 missing, correctly, because none of them exist yet. That is not a probe
-defect; it is the same "other nine gates read the whole store" behavior
-`SKILL.md` describes, and it is why probe's own close is the status flip
+defect; it is the same "gates that are neither run-state nor phase-scoped
+read the whole store" behavior `SKILL.md` describes, and it is why probe's own close is the status flip
 above, not a clean `check`.
 
 ## Degradation

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

@@ -7,9 +7,9 @@ resolve on its own: evidence, the real options, and a recommendation.
 Exit condition: every item filed anywhere in the run so far is
 grammatically valid, every id the referential-integrity gate actually
 checks resolves to a real queue file, and `migrate phase queue --status
-done` has run. It is not "the queue is empty": nothing in this milestone
-adjudicates an item, so a healthy run through this phase still ends with
-open items, deliberately.
+done` has run. It is not "the queue is empty": nothing in *this* phase
+adjudicates an item, so a healthy run through phase 5 still ends with open
+items, deliberately. Phase 6 is where they get decided.
 
 ## Inputs
 
@@ -173,9 +173,12 @@ ambiguous-looking duplicate.
 
 ## What closes it
 
-There is no verb that empties the queue in this milestone; closing this
-phase means every item filed so far is well-formed and every reference the
-gate checks resolves, not that adjudication has happened. Run for real:
+No verb empties the queue here; closing this phase means every item filed so
+far is well-formed and every reference the gate checks resolves, not that
+adjudication has happened. `migrate adjudicate` is phase 6's verb, and the
+`adjudication` gate that requires a ruling on every item is phase-scoped, so
+it stays silent until the checked terminus reaches `adjudicate`. Run for
+real:
 
 ```
 migrate phase queue --status done
@@ -202,21 +205,25 @@ queue` exits 0 with no violations at all, confirming this phase's own
 gates (`queue`, and the three `refs` fields above) were clean the whole
 time and only the unrelated census gap was ever holding exit 0 back.
 
-Plain `migrate check`, with no `--phase`, still cannot reach exit 0 in this
-version, exactly as `SKILL.md` says: `adjudicate` and `handoff` have no
-verb yet, so their phases stay `pending` forever this milestone, and
-`run-state` names both by hand:
+Plain `migrate check`, with no `--phase`, still fails here, and should:
+phases 6 and 7 have not run, so `run-state` names both, the `adjudication`
+gate names every item nobody has ruled on, and the `handoff` gate reports
+that nothing has been emitted.
 
 ```
   run-state:
     phase adjudicate is pending; every phase through handoff must be done
     phase handoff is pending; every phase through handoff must be done
+  adjudication:
+    q-reset-token-verify-missing [critical] is still open; every queue item needs a ruling before handoff
+  handoff:
+    no handoff.json in the store; handoff has not run, so nothing has reached a delivery medium
 ```
 
-`migrate check --phase queue` is the real terminus this milestone offers;
-`migrate status` afterward is the plainer read, and it is what actually
-hands off to phase 6: `5 open queue item(s) of 5`, `resume: adjudicate, no
-batches yet`.
+`migrate check --phase queue` is this phase's terminus; plain `migrate
+check` becomes reachable once phase 7 closes. `migrate status` afterward is
+the plainer read, and it is what actually hands off to phase 6: `5 open
+queue item(s) of 5`, `resume: adjudicate, no batches yet`.
 
 ## Degradation
 

package/skills/migrate/references/run-ops.md

@@ -118,10 +118,12 @@ resuming a crashed run a read rather than a recollection.
 
 Enforced. Every claim in this section was run.
 
-`import`, `census`, `phase --status`, and `reset` each take one lock over the
-whole store (`.migrate/.lock`) for the length of their read-modify-write. Those
-four are the whole set; every other command either only reads the store, or
-does not touch it. Without
+`import`, `census`, `phase --status`, `reset`, `adjudicate` and `handoff` each
+take one lock over the whole store (`.migrate/.lock`) for the length of their
+read-modify-write. Those six are the whole set for the read-modify-write over a
+whole store file. Every other command either only reads the store, or writes a
+file nothing else contends for: `init` creates `config.toml`, `queue add` copies
+one item in. Without
 it, two agents importing at once each read the same base file, and whichever
 one rewrites last silently discards the other's rows. The default wait is 30
 seconds, polling with backoff (25ms, growing by roughly 1.5x each attempt, up
@@ -135,7 +137,7 @@ and the answer is no) and `2` (a malformed request: a bad flag, a missing
 file). A lock failure says the request itself was fine; there is nothing
 about your `batch.json`, or about the `--phase` you named, to go back and
 inspect, regardless of which of the three ways below the lock failed. (Three
-ways the lock can fail, not three commands that take it: four commands do,
+ways the lock can fail, not three commands that take it: six commands do,
 listed above.)
 
 That said, "retry" resolves the three underlying causes differently, and only
@@ -162,8 +164,8 @@ message text is exact):
 import: waiting for store lock (held by pid 51234 since 2026-08-07T09:14:02.001Z)
 ```
 
-`phase --status` is the one that does not print this line. It waits on the
-same lock with the same backoff, silently: run against a scratch store with a
+`phase --status`, `adjudicate` and `handoff` do not print this line. All three
+wait on the same lock with the same backoff, silently: run against a scratch store with a
 live holder released two seconds in, `migrate phase enumerate --status running`
 printed nothing at all until it succeeded, 1.85 seconds later. `reset` does
 print it, verified the same way against a live holder released two seconds in:
@@ -172,7 +174,7 @@ print it, verified the same way against a live holder released two seconds in:
 reset: waiting for store lock (held by pid 74987 since 2026-08-08T00:00:00.000Z)
 ```
 
-If the wait for any of the four ends in a timeout instead, all four report it
+If the wait ends in a timeout instead, every lock-taker reports it
 the same way, with their own command name prefixed:
 
 ```
@@ -213,10 +215,12 @@ what you read here matches what you'll see on screen exactly.
 
 **`--force-unlock` is only appropriate after confirming the named pid is not
 running and no other agent is mid-write.** It exists on `import`, `census`,
-`phase`, and `reset`, the same four commands that take the lock at all.
-Verified against a scratch store holding a dead holder's lock: each of the four
-exits `3` without the flag and `0` with it. `reset` matters most here of the
-four, since it is the one whose whole job is deleting rows. What it actually
+`phase`, `reset`, `adjudicate` and `handoff`, the same commands that take the
+lock at all. Verified against a scratch store holding a dead holder's lock:
+each of the original four exits `3` without the flag and `0` with it, and
+`adjudicate` and `handoff` were brought onto the same exit code afterwards, so
+all six behave alike. `reset`
+matters most of them, since it is the one whose whole job is deleting rows. What it actually
 does is blunt: it unlinks the lock file
 unconditionally, before this process even checks who, if anyone, holds it.
 The CLI does not verify staleness for you when you pass this flag; the
@@ -277,4 +281,4 @@ itself is being validated against a benchmark rather than run against a live
 migration, the agent producing the mapping and the agent scoring it against
 ground truth must not be the same agent, and must not share context that
 would let one see the other's answer. This is a v1 documented discipline,
-not a CLI verb; `migrate` has no benchmark command in this milestone.
+not a CLI verb; `migrate` has no benchmark command.

package/skills/migrate/scripts/__tests__/adapter-flow.test.ts

@@ -0,0 +1,290 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { flow } from '../adapters/flow.ts'
+import type { Config } from '../config.ts'
+import { buildWorkItems, type HandoffInput } from '../handoff.ts'
+import type { Capability, Requirement } from '../types.ts'
+
+const FIXTURE = join(import.meta.dir, '..', '..', 'fixtures', 'flow-target')
+
+let root: string
+
+const config = (): Config => ({
+  source: {
+    path: join(root, 'legacy'),
+    scope: 'x',
+    stack: 'unknown',
+    vcs: 'none',
+    basis: 'source-only',
+  },
+  target: {
+    name: 'target',
+    stack: 'unknown',
+    parity_test_path: 'tests/parity/{capability}/{fr_slug}.test.ts',
+    layout: {},
+    commands: {},
+  },
+  surfaces: ['routes'],
+  surfaceSingular: {},
+  closers: [],
+  handoff: { adapter: 'flow' },
+})
+
+function cap(slug: string, title: string, ns: string, elements: string[]): Capability {
+  return { slug, title, ns, elements }
+}
+
+function req(
+  id: string,
+  capSlug: string,
+  text: string,
+  over: Partial<Requirement> = {},
+): Requirement {
+  return {
+    id,
+    cap: capSlug,
+    requirement: text,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence: { kind: 'confirmed' },
+    citations: [],
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-1',
+    ...over,
+  }
+}
+
+const CAPS = [
+  cap('billing', 'Billing', 'BI', ['el-b']),
+  cap('user-management', 'User management', 'UM', ['el-u']),
+]
+const REQS = [
+  req('UM-001', 'user-management', 'Authenticate a user'),
+  req('UM-002', 'user-management', 'Lock an account', {
+    confidence: { kind: 'inferred' },
+    origin: 'accidental-candidate',
+  }),
+  req('BI-001', 'billing', 'Raise an invoice'),
+]
+
+function input(caps = CAPS, reqs = REQS): HandoffInput {
+  return {
+    requirements: reqs,
+    capabilities: caps,
+    deltas: [],
+    config: config(),
+    root,
+    gitBin: 'git',
+    ghBin: 'gh',
+  }
+}
+
+const capPath = (slug: string): string =>
+  join(root, 'docs', 'modernisation', 'capability-map', `${slug}.md`)
+
+async function flowCli(args: string[]): Promise<{ code: number; out: string; err: string }> {
+  const proc = Bun.spawn(['bun', join(root, 'tools', 'flow', 'src', 'cli.ts'), ...args], {
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  await proc.exited
+  return { code: proc.exitCode ?? -1, out, err }
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-flow-adapter-'))
+  await cp(FIXTURE, root, { recursive: true })
+  await Bun.write(join(root, 'legacy', 'app.js'), '// legacy\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+test('apply emits capability files the target parser accepts', async () => {
+  const result = await flow.apply(buildWorkItems(CAPS, REQS), input())
+  expect(result.created.sort()).toEqual(['billing', 'user-management'])
+
+  // The oracle: the target's own checker, run over what the adapter just wrote.
+  const check = await flowCli(['map', '--check'])
+  expect(check.err).toBe('')
+  expect(check.code).toBe(0)
+})
+
+// --- grammar conformance, one assertion per rule in the target's parser ---
+// Each row cites quartex/Nexus at c2464ac,
+// plugins/stack/templates/tools/flow/src/capability.ts.
+
+test('capability.ts:43 every required frontmatter field is present', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('billing'), 'utf8')
+  for (const field of ['cap:', 'ns:', 'title:', 'status:']) {
+    expect(text).toContain(field)
+  }
+})
+
+test('capability.ts:3 status is one the target admits', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('billing'), 'utf8')
+  expect(text).toContain('status: todo')
+})
+
+test('capability.ts:44 all three required sections are emitted', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('billing'), 'utf8')
+  expect(text).toContain('## Functional requirements')
+  expect(text).toContain('## Built')
+  expect(text).toContain('## Remaining')
+})
+
+test('capability.ts:6 confidence is mapped into the target vocabulary', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('user-management'), 'utf8')
+  expect(text).toContain('| Confirmed |')
+  expect(text).toContain('| Inferred |')
+  expect(text).not.toContain('confirmed |')
+})
+
+test('capability.ts:9 accidental-candidate is mapped to poss-accidental', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('user-management'), 'utf8')
+  expect(text).toContain('poss-accidental')
+  expect(text).not.toContain('accidental-candidate')
+})
+
+test('capability.ts:74 every FR row has exactly seven cells', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const text = await readFile(capPath('user-management'), 'utf8')
+  const rows = text
+    .split('\n')
+    .filter((l) => l.startsWith('| UM-'))
+    .map((l) => l.split('|').slice(1, -1))
+  expect(rows).toHaveLength(2)
+  for (const row of rows) expect(row).toHaveLength(7)
+})
+
+test('capability.ts:48 no "## " line is emitted inside a table cell', async () => {
+  // A requirement whose text would open a section if it reached line start.
+  const sneaky = [req('BI-001', 'billing', 'Handle the\n## Built case')]
+  await flow.apply(
+    buildWorkItems([CAPS[0] as Capability], sneaky),
+    input([CAPS[0] as Capability], sneaky),
+  )
+  const check = await flowCli(['map', '--check'])
+  expect(check.code).toBe(0)
+})
+
+test('capability.ts:42 an FR id that does not match its namespace refuses before writing', async () => {
+  const bad = [req('login-001', 'user-management', 'Authenticate a user')]
+  const caps = [CAPS[1] as Capability]
+  await expect(flow.plan(input(caps, bad))).rejects.toThrow(/login-001/)
+  // Nothing was written: the refusal happens in plan(), not part way through apply().
+  expect(await Bun.file(capPath('user-management')).exists()).toBe(false)
+})
+
+// --- WORK.md ---
+
+test('apply appends under an existing ## Proposed section and creates it when absent', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const first = await readFile(join(root, 'docs', 'WORK.md'), 'utf8')
+  expect(first).toContain('## Proposed')
+  expect(first).toContain('- [billing] Billing (1 FRs)')
+  expect(first).toContain('- [user-management] User management (2 FRs)')
+  // The team's own sections survive.
+  expect(first).toContain('- [W01] Wire the deployment pipeline')
+
+  // Re-running does not stack a second copy of the same lines.
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const second = await readFile(join(root, 'docs', 'WORK.md'), 'utf8')
+  expect(second.match(/- \[billing\]/g)).toHaveLength(1)
+})
+
+// --- throughput and degradation ---
+
+test('throughput reads coveredIds from the target parity command, undated', async () => {
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  // The target records delivery in the capability file's Built section.
+  const text = await readFile(capPath('billing'), 'utf8')
+  await writeFile(capPath('billing'), text.replace('## Built\n\n(none)', '## Built\n\nBI-001'))
+
+  const t = await flow.throughput?.(input())
+  expect(t?.completions).toEqual([{ fr: 'BI-001', doneAt: null }])
+  expect(t?.basis).toContain('flow parity')
+})
+
+test('a target with no flow CLI reports that the emission was not validated', async () => {
+  await rm(join(root, 'tools'), { recursive: true, force: true })
+  const result = await flow.apply(buildWorkItems(CAPS, REQS), input())
+  expect(result.created.sort()).toEqual(['billing', 'user-management'])
+  expect(result.refs['billing']).toContain('capability-map/billing.md')
+})
+
+test('a capability file the target rejects fails apply with the target’s own message', async () => {
+  // The fixture CLI is the oracle; break its input and the adapter must
+  // surface the failure rather than reporting a clean emission.
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  await writeFile(capPath('billing'), '---\ncap: billing\n---\n\nnothing else\n')
+  const check = await flowCli(['map', '--check'])
+  expect(check.code).toBe(1)
+  expect(check.err).toContain('missing field')
+})
+
+test("the team's own lines under ## Proposed survive a handoff", async () => {
+  // The previous version stripped every `- [something]` line under the
+  // heading before adding its own, on the assumption that shape meant
+  // ownership. `- [W07]` is exactly the notation the target's own WORK.md
+  // teaches, so a team keeping a shortlist there lost it on the first run.
+  const workPath = join(root, 'docs', 'WORK.md')
+  await writeFile(
+    workPath,
+    [
+      '# Work',
+      '',
+      '## Proposed',
+      '',
+      '- [W07] Replace the auth provider',
+      '- [W08] Split the reporting service',
+      '',
+      'Notes: W07 is blocked until Q3.',
+      '',
+      '### Detail',
+      '',
+      'Some prose.',
+      '',
+      '# Appendix',
+      '',
+      '- [A1] An appendix item',
+      '',
+    ].join('\n'),
+  )
+
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const after = await readFile(workPath, 'utf8')
+
+  for (const kept of [
+    '- [W07] Replace the auth provider',
+    '- [W08] Split the reporting service',
+    'Notes: W07 is blocked until Q3.',
+    '### Detail',
+    '# Appendix',
+    '- [A1] An appendix item',
+  ]) {
+    expect(after).toContain(kept)
+  }
+  expect(after).toContain('- [billing] Billing (1 FRs)')
+
+  // And a second run replaces only its own fenced block rather than stacking.
+  await flow.apply(buildWorkItems(CAPS, REQS), input())
+  const twice = await readFile(workPath, 'utf8')
+  expect(twice.match(/- \[billing\]/g)).toHaveLength(1)
+  expect(twice).toContain('- [W07] Replace the auth provider')
+})