@iceinvein/agent-skills 0.1.40 → 0.2.0

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

@@ -0,0 +1,275 @@
+# Phase 4: Parity
+
+## Purpose
+
+Assign an oracle to every requirement whose confidence is not `queued`, and
+maintain the sanctioned-difference catalog for whatever legitimately cannot
+match. Exit condition: no unsigned delta in `deltas.jsonl`, every non-queued
+requirement carries a parity value, and `migrate phase parity --status
+done` has run.
+
+## Inputs
+
+- `config.toml`: `target.parity_test_path`, the template every parity `ref`
+  must be built from by hand. Its shipped default is
+  `tests/parity/{capability}/{fr_slug}.test.ts`; probe.md is where an
+  operator would have hand-edited it to something else, so read it, never
+  assume the default.
+- `.migrate/parity-basis.md`: hand-written prose from probe, carrying
+  whether the source is `runnable` or `source-only` and the detection
+  evidence behind that call. This phase does not redetect it; it reads what
+  probe already decided.
+- The store: `requirements.jsonl` (every non-queued row needs a plan),
+  `deltas.jsonl` (existing sanctioned differences, checked before writing a
+  new rubric or a new delta rather than after).
+
+## Procedure
+
+**The three parity kinds, stated once, before anything is assigned.**
+`parity.kind` is `golden-master`, `differential`, or `rubric`.
+
+- **`golden-master`.** Capture the legacy system's actual output for a
+  fixed input once, and assert the target reproduces it exactly. Fits a
+  deterministic, replayable behavior: the same request into the same state
+  gets the same response every time, so one captured snapshot is a
+  reusable oracle.
+- **`differential`.** Run both systems side by side on the same input and
+  diff the two live results, rather than trusting one frozen capture. Fits
+  a behavior whose *exact* output legitimately varies (a token, a
+  timestamp, a generated id) while the comparison that actually matters
+  (did both systems accept, reject, and decide the same way) still
+  automates cleanly.
+- **`rubric`, with a `level` of `high`, `moderate`, `low`, or `unknown`.**
+  For when no automatable oracle exists at all: a `source-only` basis with
+  nothing to run, or a behavior that crosses a boundary neither capture nor
+  live diffing can reach (an external mail send, a third-party callback).
+  **Only `level: high` needs no queue id; `moderate`, `low`, and `unknown`
+  each require one**, because a rubric below `high` is itself a claim that
+  something is not fully known, and that claim needs an owner's eyes, not a
+  guess standing in for one.
+
+A worked example, run against a real store, assigning all three kinds
+across the requirements extract.md mined:
+
+```json
+{ "id": "UM-001", "parity": { "kind": "differential", "ref": "tests/parity/user-management/login.test.ts" } }
+{ "id": "UM-002", "parity": { "kind": "golden-master", "ref": "tests/parity/user-management/list-users.test.ts" } }
+{ "id": "UM-003", "parity": { "kind": "rubric", "level": "moderate", "queue": "q-parity-um-003-reset-flow" } }
+```
+
+(each shown here trimmed to its `id` and `parity` field; the real batch
+carries every other required field for each row unchanged). UM-001 gets
+`differential`: both systems get the same credentials, and while the issued
+token differs, whether the attempt succeeds and what it rejects must match.
+UM-002 gets `golden-master`: a `GET` with no side effects and no
+input-dependent branching is exactly the deterministic case golden-master
+fits. UM-003 gets `rubric:moderate`: its confidence was already `inferred`
+in extract.md, since nothing in the source shows what happens when a reset
+token is actually submitted, so no automated oracle has anything to run
+against, and the `moderate` level needs the queue id it names.
+
+`migrate import reqs batch.json` accepts this and prints `import reqs: 0
+added, 3 updated, batch b-reqs-parity-001`: this is the write-back
+`SKILL.md` calls out as load-bearing, in the same shape as extract's
+disposition write-back. This import is the only writer of a *resolved*
+`parity` value; the phase-status flip at the end of this phase does not
+touch it, and neither does anything else short of `migrate reset --phase
+parity`, which clears it back to `null` rather than resolving it.
+
+**A sub-high rubric's queue id is checked by the refs gate, so file it in
+the same pass, before any check that would otherwise name it dangling.**
+UM-003's `moderate` level named `q-parity-um-003-reset-flow`; file it now:
+
+```markdown
+---
+id: q-parity-um-003-reset-flow
+severity: moderate
+status: open
+---
+
+## Evidence
+
+`UM-003` (password reset) has `confidence: inferred`: the source shows a
+link is emailed and that account existence is not leaked, but nothing in
+`AuthController.cs` shows what the token looks like, how long it lives, or
+what happens when it is submitted. There is no fixture that can play back a
+real reset end-to-end, so neither `golden-master` nor `differential` has
+anything to run against.
+
+## Options
+
+(a) Ship a `rubric:low` plan now and revisit once the token-verification
+question resolves. (b) Block parity on this FR until that question
+resolves. (c) Ship `rubric:moderate`: enough is observable (email is sent,
+no account-existence leak) to check by hand, but not enough for an
+executable oracle.
+
+## Recommendation
+
+Recommend (c); `rubric:moderate` matches what is actually known today.
+```
+
+`migrate queue add q-parity-um-003-reset-flow.md` accepts this and prints
+`queue add: q-parity-um-003-reset-flow [moderate]`.
+
+**Show the substitution, because nothing else will.** `{capability}` is the
+capability's own `slug` from `capabilities.jsonl`, already known.
+`{fr_slug}` has no deriving code anywhere in this CLI: it is a short,
+kebab-case name you choose by hand for what the requirement actually is
+(`login`, `list-users`), not the arbitrary FR id (`UM-001` tells a reader of
+the test tree nothing). This is hand work the same way writing
+`capabilities.jsonl` itself is hand work in seam.md: nothing imports a
+parity plan's `ref` against the template, checks that it resolves to a real
+file, or even checks that it looks like the template at all. Verified on a
+disposable copy of the store, not the running example (overwriting UM-001's
+real plan here just to prove this point would only recreate the exact kind
+of drift this manual exists to prevent): a `golden-master` row with
+`"ref": "this/path/does/not/exist/anywhere.test.ts"`, matching neither the
+template nor any real file, imports cleanly and passes `migrate check`
+without a single violation. The convention is entirely this manual's
+discipline; get the substitution right by hand, because no gate is behind
+you if you do not.
+
+**Deltas exist to record sanctioned differences, never to silence a real
+failure.** State this before writing one, not after: a delta is a *reason*
+a difference is acceptable, backed by a rationale a reviewer can check, not
+a lever for making an inconvenient test pass. If a parity test fails and
+the honest cause is "the requirement was wrong" or "the target has a bug,"
+the fix is to correct the requirement or the target, never to paper over
+the failure with a delta whose rationale was written after the fact to fit.
+A delta's `parity_exclusion` field says precisely what a parity test may
+not assert on, not that the whole area is exempt from comparison.
+
+A worked example, run against a real store. The target sends password-reset
+emails through an async queue; the legacy system sent them synchronously in
+the request, so response timing between the two systems now legitimately
+differs for reasons that have nothing to do with correctness.
+
+```json
+{
+  "id": "delta-async-email-delivery",
+  "scope": "Password reset email delivery timing (UM-003)",
+  "rationale": "The target sends reset emails through an async queue instead of synchronously in the request, so response timing legitimately differs from the legacy system.",
+  "parity_exclusion": "The UM-003 parity check must not assert on how soon the email was actually sent, only that a send was enqueued.",
+  "validation": "A separate async-delivery test in the greenfield-only suite confirms the queued job eventually sends the email; the parity suite does not re-prove it.",
+  "owner_signed": null
+}
+```
+
+`migrate import deltas batch.json` accepts this (`owner_signed: null` is a
+valid value while a delta is proposed but not yet ratified) and prints
+`import deltas: 1 added, 0 updated, batch b-deltas-001`. Unsigned, it fails
+its own gate; `migrate check --phase parity`, run for real right now,
+reports:
+
+```
+  deltas:
+    delta-async-email-delivery is not owner-signed
+```
+
+Re-import the same id with `"owner_signed": "2026-08-07"` once an owner has
+actually looked at it, and the gate clears; `deltas` never appears again in
+the same store's `check` output.
+
+### The split-suite discipline
+
+Three suites, kept apart on purpose:
+
+- **parity.** Tests whose whole job is proving the target matches the
+  legacy system, one per requirement's `parity.ref`. This is the only suite
+  a delta's `parity_exclusion` ever narrows.
+- **greenfield-only.** Tests for target-only behavior with no legacy
+  analog: the async email queue itself, from the delta above, is exactly
+  this. Nothing here compares against the legacy system, because there is
+  nothing on the legacy side to compare against.
+- **legacy-only.** Behavior deliberately not carried forward. An
+  `out-of-scope` element (`route-get-legacy-admin-tool`, from extract.md)
+  gets no parity test at all; there is no requirement to assign one to, and
+  writing one would imply a comparison this run explicitly decided not to
+  make.
+
+### Parity coverage
+
+**Every requirement whose confidence is not `queued` must carry a parity
+value; a `queued` requirement is exempt.** The exemption exists because a
+queued requirement's entire content, not just its oracle, is still
+provisional: assigning it a parity plan before an owner has even confirmed
+the requirement is real would be planning a test for something that might
+not exist. Verified on a disposable copy of the store, using an extra
+requirement never added to the running example: a requirement with
+`confidence: {kind: queued, ...}` and `parity: null` produces no `parity`
+gate violation; the same row with `confidence: confirmed` and
+`parity: null` produces exactly one, naming the requirement's id. The
+running example already shows this in the other direction, without needing
+a separate copy: extract.md's own "What closes it" transcript names
+`UM-001`, `UM-002`, and `UM-003` under `parity`, one line each, at the point
+where all three are `confirmed` or `inferred` (never `queued`) and none yet
+has a plan.
+
+**The honest limit: a parity plan on record is a commitment, not a proof.**
+`check`'s parity gate is satisfied once `parity` is a well-formed value; it
+never runs `target.commands.test`, never opens the file the `ref` names,
+and never confirms the test that file describes actually exists or passes.
+Writing `{"kind": "golden-master", "ref": "..."}` and later writing the test
+file at that path are two separate acts, and only the manual's own
+discipline connects them.
+
+## What closes it
+
+`migrate check --phase parity` mid-run reads the same way extract's did:
+noisy on the surfaces this scratch run never enumerated, and quiet on
+everything parity itself owns once every non-queued requirement has a plan,
+`q-parity-um-003-reset-flow` is filed (above), and every delta is signed.
+Skip filing that queue item and `refs` reappears here, naming `UM-003` via
+`parity.queue`, the same way `q-legacy-admin-tool` reappears in extract.md's
+own check if that one is skipped. Run for real, right after the delta above
+was signed:
+
+```
+4/5 mapped, 1 out-of-scope, 0 unaccounted
+
+Violations (7):
+  census:
+    declared surface jobs has no lens census record; the lens did not run or did not close
+    declared surface reports has no lens census record; the lens did not run or did not close
+    declared surface screens has no lens census record; the lens did not run or did not close
+    declared surface integrations has no lens census record; the lens did not run or did not close
+    declared surface workflows has no lens census record; the lens did not run or did not close
+    declared surface settings has no lens census record; the lens did not run or did not close
+  run-state:
+    phase parity is running; every phase through parity must be done
+```
+
+Neither `deltas` nor `parity` appears: both are already clean at this
+point. Flip the phase:
+
+```
+migrate phase parity --status done
+```
+
+## Degradation
+
+- **`source.basis` is `source-only`.** No live legacy system to run a
+  `differential` against, and often nothing to capture a fresh
+  `golden-master` from either, unless an existing fixture or recorded
+  output in the source already plays that role. When neither is possible,
+  `rubric` is what remains; expect more `moderate`, `low`, and `unknown`
+  levels, and more queue items, on a `source-only` run than on a `runnable`
+  one.
+- **The target's test command is still `init`'s placeholder.** A parity
+  plan can still be recorded (the gate only checks the value's shape); the
+  test itself has nowhere real to run yet. This is exactly the "commitment,
+  not proof" limit above, sharpest right after probe when `target.commands`
+  has not been wired up.
+- **Genuinely unclear which rubric level applies.** Use `unknown` rather
+  than guessing a specific level to avoid a queue id; `unknown` still needs
+  one, so nothing is gained by picking a falsely specific level instead.
+
+## Commands
+
+```
+migrate import deltas <batch.json>
+migrate import reqs <batch.json>
+migrate queue add <item.md>
+migrate phase parity --status done
+```

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

@@ -0,0 +1,135 @@
+# Phase 0: Probe
+
+## Purpose
+
+Detect the source stack, detect whether the source is runnable, interview for
+the target profile, and confirm the surface set this run will enumerate.
+Write `.migrate/config.toml` and `.migrate/parity-basis.md`. Every later phase
+reads `config.toml`; deciding the runtime basis here means the enumerate
+phase never has to re-check it, and no phase after this one probes the
+source's runnability again.
+
+Exit condition: `config.toml` exists, `parity-basis.md` carries the
+detection evidence as prose, and `migrate phase probe --status done` has
+run.
+
+## Inputs
+
+There is no `config.toml` and no store yet; this phase writes the first one.
+`migrate init` refuses at exit 1 if `.migrate/config.toml` already exists, so
+re-running probe on a live store means editing the file directly, not
+re-running `init`.
+
+What you read instead:
+
+- The source checkout itself (read-only): manifest and build files,
+  dependency lockfiles, a `.git` directory or its absence, README and any
+  docs tree.
+- The target repo: it must already be a git working copy (the store commits
+  inside it), and whatever `.gitignore` it already has.
+- The operator: the target profile is an interview, not something detectable
+  from the source.
+
+## Procedure
+
+1. **Detect the source stack.** Read the manifest and build files. If
+   nothing in the checkout names a stack you can commit to, record
+   `unknown` rather than guessing. `unknown` is a valid value, not a failure:
+   it is what routes the enumerate phase into contract-only mode instead of
+   into the wrong stack's recipe, which is worse than no recipe at all.
+
+2. **Detect whether the source is runnable.** Try to install dependencies,
+   build, and start it, in whatever order the stack suggests. Write every
+   probe command you ran and its actual output to `.migrate/parity-basis.md`
+   as prose, along with any dependency gap or environmental blocker you hit.
+   This is prose, not a census record, because it is an argument for the
+   basis you are about to declare, not a count anything can balance. Decide
+   `runnable` or `source-only` from that evidence and pass it to `--basis`.
+
+3. **Interview for the target profile.** Ask for: a name, the target stack,
+   the layout (which directories hold which part of the target), the
+   commands that test, lint, and build it, and `parity_test_path` (the path
+   template later phases will write parity tests under, for example
+   `tests/parity/{capability}/{fr_slug}.test.ts`).
+
+4. **Confirm or replace the default surface set.** The default is
+   `["routes", "tables", "jobs", "reports", "screens", "integrations",
+   "workflows", "settings"]`. This is written by `migrate init` and is not
+   yours to change through a flag: `init` takes no surface-set argument at
+   all. If the default fits the source, leave it. If it does not, this is
+   the single largest source-genericity lever in the whole tool, and it
+   costs one config key. A COBOL source, for example, declares:
+
+   ```toml
+   [surfaces]
+   types = ["programs", "copybooks", "jcl-jobs", "bms-maps", "datasets"]
+   ```
+
+   Hand-edit `[surfaces].types` in `config.toml` to replace it. Every
+   downstream gate reads the declared set, not the default, so this one edit
+   is what makes the rest of the run track a non-.NET source honestly
+   instead of forcing it through a shape that does not fit.
+
+   Element ids derive from the surface name with a trailing `s` stripped
+   (`tables` -> `table-...`). If a declared surface is already singular but
+   ends in `s` anyway (`status`, stripped naively to `statu-...`), add an
+   entry to `[surfaces.singular]` to override it, for example
+   `status = "status"`. `enumerate.md`'s Inputs section reads this table
+   when it derives ids; probe is the only phase that ever writes
+   `config.toml`, so an override missed here has no later phase to catch it
+   in.
+
+   `[target.layout]` and `[target.commands]` have the same property:
+   `init` writes them as an empty table and three placeholder `echo`
+   commands respectively, and nothing else fills them in. Hand-edit the
+   interview answers from step 3 into both before enumerate starts.
+   `target.parity_test_path` is different: `init` already writes a real
+   default, `tests/parity/{capability}/{fr_slug}.test.ts`, not a
+   placeholder, so it needs no edit when the operator's answer matches it.
+   When it does not (a different path convention, a different test file
+   extension), hand-edit `target.parity_test_path` in `[target]` the same
+   way, since nothing else will. Neither `SKILL.md` nor `docs/reference.md`
+   names this field, so this paragraph is its only documented home; the
+   parity phase is what reads it back.
+
+## What closes it
+
+There is no census kind for probe; it is not a lens, an attribute, a
+rule-sweep, or a closer, so nothing balances here. The phase closes on the
+artifacts existing and the status flip:
+
+```
+migrate init --source /abs/path/to/legacy --scope "user management module" \
+  --name nexus-workforce --source-stack aspnet-webforms \
+  --target-stack "dotnet-10 + vue3" --basis runnable
+migrate phase probe --status done
+```
+
+`init` exits 1 if `config.toml` already exists, and 2 if `--source` is
+missing, is not a directory, or `--basis` is not `runnable` or
+`source-only`. Confirm the write with `migrate status`, which prints the
+detected stack and basis on its first line.
+
+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
+above, not a clean `check`.
+
+## Degradation
+
+| Absent | Record |
+|---|---|
+| No VCS in the source | `vcs = "none"`. `init` detects this from the absence of `.git` and writes it for you; nothing to hand-edit. |
+| No runnable environment | `basis = "source-only"`, plus the blocking evidence (missing SDK, a dependency that will not install, an environment nothing here can reach) written to `parity-basis.md`. This is the fact the runtime lens and the parity phase both read later: getting it right once here is the point of moving basis detection to phase 0 at all. |
+| No documentation | Note it in `parity-basis.md` now (no `docs/` tree, no wiki export, nothing beyond a generated README). This does not close anything by itself, but it means the enumerate phase's docs lens can open with `not-applicable:no-documentation` immediately instead of re-discovering the same absence. |
+
+## Commands
+
+```
+migrate init --source <path> --scope "<text>" --name <target> \
+  [--source-stack <s>] [--target-stack <s>] [--basis <runnable|source-only>]
+migrate phase probe --status done
+```

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

@@ -0,0 +1,242 @@
+# Phase 5: Queue
+
+## Purpose
+
+Carry forward, for an owner to adjudicate, everything any phase could not
+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.
+
+## Inputs
+
+- The store: `.migrate/queue/`, already holding whatever `migrate queue
+  add` has filed from any earlier phase. This phase reads what already
+  exists; it does not start a new file of its own the way `elements.jsonl`
+  or `requirements.jsonl` does.
+- `templates/queue-item.md`: the skeleton every filed item should start
+  from. It carries the same three fields and three headings this manual's
+  grammar section states below, no more and no fewer.
+
+## Procedure
+
+**The queue is cross-cutting, populated from any phase, not a phase that
+runs once.** Every earlier manual in this set files items directly:
+enumerate.md's zero-modularity escalation, extract.md's attribute and
+rule-sweep and closer findings, parity.md's sub-high rubrics. This phase's
+job is not to invent new items; it is to make sure everything already filed
+is well-formed and everything the gate can check actually resolves, and
+then to close.
+
+**The grammar, stated once, before any example.** A queue item is a
+markdown file whose stem matches its own `id`. Frontmatter carries `id`
+(`q-` plus a lowercase kebab-case slug), `severity` (`critical`,
+`moderate`, or `minor`), and `status` (`open`, or `adjudicated` with a
+`ruling`). The body carries exactly three level-two headings, in any
+order, case-sensitive and line-anchored (`## Evidence`, `## Options`,
+`## Recommendation`), and **all three sections must be non-empty**. Missing
+and empty are reported as distinguishable errors, not folded into one
+generic complaint, so the fix is obvious from the message alone.
+
+A worked example, the same file extract.md filed (built, in turn, on
+`templates/queue-item.md`), run against a real store:
+
+```markdown
+---
+id: q-reset-token-verify-missing
+severity: critical
+status: open
+---
+
+## Evidence
+
+`read-write-symmetry` checked every write path against a matching read
+path. `ResetPassword` writes a reset token via `GenerateResetToken` and
+emails it, but no controller in the source reads or verifies a submitted
+token: there is no `POST /api/password-reset/confirm` or equivalent. Either
+the verification endpoint exists somewhere this pass did not look, or reset
+tokens are issued and never checked.
+
+## Options
+
+(a) Widen the search (other controllers, an area folder, a separate
+service) before concluding it is missing. (b) Treat it as a real gap and
+flag it for the target to fix, not replicate. (c) Ask the operator directly
+whether reset ever worked end-to-end in production.
+
+## Recommendation
+
+Recommend (c); a write with no matching read is exactly what this closer
+exists to catch, and only the operator can say whether it is a real defect
+or evidence this pass has not looked far enough yet.
+```
+
+`migrate queue add q-reset-token-verify-missing.md` accepts this and prints
+`queue add: q-reset-token-verify-missing [critical]`.
+
+### What the grammar rejects
+
+Each of these, run against a real store, is refused before the file is ever
+copied into `.migrate/queue/`; a rejected `queue add` never leaves a
+half-written file behind.
+
+- **Filename does not match `id`.** A file named `q-bad-mismatch.md` whose
+  frontmatter says `id: q-something-else`:
+  `filename q-bad-mismatch does not match id q-something-else`, exit 1.
+- **A section is missing entirely.** No `## Options` heading anywhere in
+  the body: `missing ## Options section (a line reading exactly "##
+  Options", case-sensitive)`, exit 1.
+- **A section is present but empty.** A `## Options` heading with nothing
+  before the next heading: `## Options section is empty`, exit 1.
+- **No frontmatter block at all.** A file that never opens with `---\n`:
+  `missing --- frontmatter block`, exit **2**, not 1. This is the one
+  grammar failure that is a usage error rather than a content failure: the
+  file never resolved to a queue item in the first place, the same class as
+  a missing file or an unreadable one.
+- **An invalid severity.** `severity: urgent`: `severity must be one of
+  critical, moderate, minor, got urgent`, exit 1.
+
+Two more exist that are just as real but need a longer setup to trigger
+faithfully rather than trust secondhand: an `id` that is not `q-` plus a
+lowercase kebab-case slug, and a duplicate `## Evidence` heading (reported
+as a duplicate, never silently taking the first and dropping the rest).
+Both are enforced the same way, by name, before the file is copied.
+
+### Severity, and why the list is ordered
+
+**`queue list` sorts by severity first (`critical`, `moderate`, `minor`, in
+that order), then by id.** This is not cosmetic: the queue is meant to be
+adjudicated top to bottom in one sitting, and an owner working that way
+should see the item that most needs a decision first, every time, not
+whatever happened to be filed most recently. Write each item short enough
+that one pass through the whole list is actually plausible; a queue item
+that takes a page to explain a one-line decision has failed its own point
+just as much as one with no evidence at all.
+
+A worked example: `migrate queue list`, run against a real store with five
+items filed across extract.md and parity.md's examples, prints:
+
+```
+q-reset-token-verify-missing	critical	open
+q-account-lockout-scope	moderate	open
+q-parity-um-003-reset-flow	moderate	open
+q-users-islocked-semantics	moderate	open
+q-legacy-admin-tool	minor	open
+5 item(s)
+```
+
+The three `moderate` items sort by id alone (`account-lockout-scope` before
+`parity-um-003-reset-flow` before `users-islocked-semantics`), since
+severity does not separate them. When genuinely unsure which severity
+fits, lean toward the one that puts the item in front of the owner sooner:
+a real ambiguity mislabeled `minor` can sit unread far longer than the same
+ambiguity mislabeled one tier too high ever costs.
+
+### Referential integrity
+
+**The gate checks exactly three fields against real queue files, by name,
+and no others: `confidence.queue` on a requirement whose `confidence.kind`
+is `queued`; `disposition.queue` on an element whose `disposition.kind` is
+`out-of-scope`; and `parity.queue` on a requirement whose `parity.kind` is
+`rubric` at any level below `high`.** State this before relying on it for
+anything else, because the obvious-sounding generalization is wrong: a
+census record's own `queued` array (on a `lens`, `attribute`, `rule-sweep`,
+or `closer` record) is never cross-checked against a real queue file by any
+gate. Verified on a disposable copy of the store, taken before extract.md's
+own queue items were filed: a census record whose `queued` array names an
+id with no file behind it still passes `migrate check` with zero `refs`
+violations for that id, on that copy. Filing the file anyway is still this
+manual's discipline, exactly as extract.md says, even though nothing
+downstream will ever catch you if you skip it there.
+
+A worked example of what the gate does check, run on a disposable copy so
+the extra requirement and queue item below never enter the running example
+(which by this point already has all five of its own items filed and would
+otherwise read as six): a requirement with `confidence: {"kind": "queued",
+"queue": "q-bulk-import-scope"}` and no such file on disk yet.
+
+```
+  refs:
+    UM-005 references queue item q-bulk-import-scope via confidence.queue, which does not exist
+```
+
+`migrate queue add q-bulk-import-scope.md`, on that same disposable copy,
+files the missing item; the very next `migrate check` no longer names it,
+with no other change to that copy. The message names which field the
+reference came from (`disposition.queue`, `confidence.queue`, or
+`parity.queue`) precisely so that one requirement dangling from two
+different fields at once reads as two separate things to fix, not one
+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:
+
+```
+migrate phase queue --status done
+phase: queue is now done
+
+migrate check --phase queue
+4/5 mapped, 1 out-of-scope, 0 unaccounted
+
+Violations (6):
+  census:
+    declared surface jobs has no lens census record; the lens did not run or did not close
+    declared surface reports has no lens census record; the lens did not run or did not close
+    declared surface screens has no lens census record; the lens did not run or did not close
+    declared surface integrations has no lens census record; the lens did not run or did not close
+    declared surface workflows has no lens census record; the lens did not run or did not close
+    declared surface settings has no lens census record; the lens did not run or did not close
+```
+
+The six remaining lines are the same census noise every earlier manual in
+this set already explains, not a queue defect: those six surfaces were
+never enumerated in this scratch run. Closed for real, on the same store
+with a zero-finding lens record recorded for each: `migrate check --phase
+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:
+
+```
+  run-state:
+    phase adjudicate is pending; every phase through handoff must be done
+    phase handoff is pending; every phase through handoff must be done
+```
+
+`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`.
+
+## Degradation
+
+- **One malformed item among many well-formed ones.** `queue list`,
+  `queue show`, `check`, and `status` all keep going past it and report the
+  rest; one bad file never hides an entire directory's worth of good ones.
+- **Genuinely unsure which severity to file under.** Covered above: lean
+  toward escalating rather than downgrading when truly unsure, since the
+  cost of a false escalation (an owner glances at it sooner than strictly
+  needed) is smaller than the cost of a false de-escalation (a real problem
+  waits at the bottom of the list).
+- **A census record's own `queued` ids with no queue file behind them.**
+  Not caught by any gate, covered above; file them anyway, since a reviewer
+  reading this run against this manual will expect to find one.
+
+## Commands
+
+```
+migrate queue add <item.md>
+migrate queue list [--open]
+migrate queue show <id>
+migrate phase queue --status done
+```