@iceinvein/agent-skills 0.2.0 → 0.4.0

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
+```

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.