@iceinvein/agent-skills 0.21.4 → 0.22.0

package/skills/migrate/evals/rules.json

@@ -0,0 +1,160 @@
+{
+  "rules": [
+    {
+      "id": "resume-reads-status-and-never-inits",
+      "states": "SKILL.md: Starting",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "resume-reads-status-first"
+      ]
+    },
+    {
+      "id": "probe-asks-for-the-target-before-init",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "probe-asks-for-the-target"
+      ]
+    },
+    {
+      "id": "low-q-seam-escalates-to-the-owner",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "seam-low-q-escalates"
+      ]
+    },
+    {
+      "id": "vertical-slice-offered-never-picked",
+      "states": "references/phases/seam.md: Procedure",
+      "origin": "commit:dc245b9",
+      "cases": [
+        "seam-low-q-escalates"
+      ]
+    },
+    {
+      "id": "shared-element-queued-in-no-capability",
+      "states": "references/phases/seam.md: Procedure",
+      "origin": "commit:02cf0e4",
+      "cases": [
+        "seam-shared-element-queued"
+      ]
+    },
+    {
+      "id": "queue-item-filed-in-the-pass-that-names-it",
+      "states": "SKILL.md: 3. Extract",
+      "origin": "commit:f2620ca",
+      "cases": [
+        "extract-files-queue-in-same-pass"
+      ]
+    },
+    {
+      "id": "disposition-written-back-by-import",
+      "states": "SKILL.md: 3. Extract",
+      "origin": "commit:13a517e",
+      "cases": [
+        "extract-files-queue-in-same-pass"
+      ]
+    },
+    {
+      "id": "sub-high-rubric-parity-carries-a-filed-queue-id",
+      "states": "SKILL.md: 4. Parity",
+      "origin": "commit:f2620ca",
+      "cases": [],
+      "unpinned": "No case runs the parity phase."
+    },
+    {
+      "id": "review-sheet-before-any-ruling",
+      "states": "SKILL.md: 6. Adjudicate",
+      "origin": "commit:5a3dd21",
+      "cases": [
+        "adjudicate-drafts-not-decides"
+      ]
+    },
+    {
+      "id": "adjudication-drafts-and-the-owner-rules",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "adjudicate-drafts-not-decides"
+      ]
+    },
+    {
+      "id": "ruling-consequence-goes-through-import",
+      "states": "SKILL.md: 6. Adjudicate",
+      "origin": "commit:5a3dd21",
+      "cases": [],
+      "unpinned": "The only adjudicate case stops before any ruling is approved, so no consequence is ever imported."
+    },
+    {
+      "id": "blocked-handoff-reports-its-blockers",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "handoff-blocked-reports-blockers"
+      ]
+    },
+    {
+      "id": "forecast-assumptions-are-the-owners",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "forecast-refuses-without-attestation"
+      ]
+    },
+    {
+      "id": "live-lock-is-never-forced",
+      "states": "SKILL.md: Where you stop",
+      "origin": "docs/specs/2026-10-04-migrate-evals-and-gates.md",
+      "cases": [
+        "stale-lock-not-forced"
+      ]
+    },
+    {
+      "id": "check-after-every-batch",
+      "states": "SKILL.md: Checking as you go",
+      "origin": "commit:9148961",
+      "cases": [],
+      "unpinned": "`extract-files-queue-in-same-pass` checks that migrate check ran at least once, not once per batch."
+    },
+    {
+      "id": "mapped-means-plain-check-passes",
+      "states": "SKILL.md: Checking as you go",
+      "origin": "commit:9148961",
+      "cases": [
+        "done-means-plain-check"
+      ]
+    },
+    {
+      "id": "read-the-phase-manual-before-dispatching",
+      "states": "SKILL.md: Phase walkthrough",
+      "origin": "commit:9148961",
+      "cases": [],
+      "unpinned": "No grader checks which reference files a run read."
+    },
+    {
+      "id": "fan-out-one-agent-per-unit",
+      "states": "SKILL.md: Phase walkthrough",
+      "origin": "commit:9148961",
+      "cases": [],
+      "unpinned": "No grader counts Task dispatches, and the extract case asks for a single capability."
+    },
+    {
+      "id": "commit-after-every-import",
+      "states": "references/run-ops.md: The batch checkpoint loop",
+      "origin": "commit:7efe061",
+      "cases": [],
+      "unpinned": "The child's git fails in the eval sandbox, so fixtures make every commit and no grader asks the run to commit."
+    },
+    {
+      "id": "env-file-never-committed",
+      "states": "SKILL.md: Aborting",
+      "origin": "commit:9148961",
+      "cases": [],
+      "unpinned": "No fixture has a runtime lens write .migrate/.env, and no run can commit in the sandbox."
+    }
+  ],
+  "sandboxSensitive": [],
+  "vacuousWithout": [],
+  "unclaimed": []
+}

package/skills/migrate/skill.json

@@ -1,11 +1,15 @@
 {
   "name": "migrate",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Source-agnostic legacy migration mapping. Walks a legacy codebase through probe, enumerate, seam, extract, parity, queue, adjudicate and handoff, building an auditable requirements ledger with mandatory citations and a `migrate check` gate in place of self-reported completeness. Use when the user asks to migrate, re-specify, replatform, or map a legacy system onto a new stack, to hand mapped requirements to a delivery team, or to resume, check, report, or forecast a mapping run already under way.",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude"],
-  "files": { "prompt": "SKILL.md" },
+  "tools": [
+    "claude"
+  ],
+  "files": {
+    "prompt": "SKILL.md"
+  },
   "bundle": {
     "include": [
       "bin",
@@ -20,7 +24,9 @@
       "README.md",
       "docs/reference.md"
     ],
-    "exclude": ["scripts/__tests__/"]
+    "exclude": [
+      "scripts/__tests__/"
+    ]
   },
   "install": {
     "claude": {

package/skills/scope-estimate/README.md

@@ -0,0 +1,173 @@
+# scope-estimate
+
+Scopes and estimates a rebuild or respec of an existing system for a proposal.
+From notes, client documents and the legacy repos it produces a capability
+map, functional requirements, build slices and work packages, a build
+schedule for an agent-driven team (engineers x worktrees), architecture pages
+and a review of any proposal, with every figure coming from one reproducible
+scheduler run.
+
+Use `migrate` instead when the requirements must become a gated ledger and
+delivery work items for a migration already under way.
+
+## Quick reference
+
+```
+/scope-estimate            start or resume a run in this folder
+/scope-estimate --help     this quick reference
+```
+
+**Give it:** an engagement folder with `inputs/` (notes, client PDFs,
+proposals) and `repos/` (clones; read only, never run).
+
+**It stops for you at:** intake (stack, repo shape, infrastructure tool,
+scope, team; default 2 engineers x 3 worktrees, 5 days a week), each
+architecture fork, and before publishing or editing anyone else's document.
+
+**Phases:** 1 discovery, 2 capability map, 3 requirements, 4 slices and
+schedule, 5 architecture and proposal review, then `handback.md`.
+
+**Outputs:** `intake.md`, `decisions.md`, `handback.md`, `capability-map/`,
+`build-plan/` (requirements, `plan.json`, `schedule.json`, slices page),
+`architecture/`.
+
+**Come back when:** a decision lands ("we're going with Better Auth"), the
+team changes, calibration rates are in, or a proposal quotes the estimate.
+It updates the requirements, re-runs the scheduler and every page that quotes
+a figure.
+
+**Scheduler on its own:**
+`bun .claude/skills/scope-estimate/scripts/schedule.ts build-plan/requirements build-plan/plan.json --json build-plan/schedule.json`
+(`--help` lists the `plan.json` fields).
+
+**Say when presenting:** status is from reading code, not running it; rates
+are uncalibrated until the two-week calibration; requirement granularity
+moves the estimate by about 20%, so quote the fast to floor range next to the
+planning figure.
+
+## Install
+
+```
+bunx @iceinvein/agent-skills install scope-estimate        # this project
+bunx @iceinvein/agent-skills install scope-estimate -g     # every project
+```
+
+Needs [Bun](https://bun.sh) for the scheduler. Claude Code only.
+
+## Starting a run
+
+Lay out the engagement folder:
+
+```
+<engagement>/
+  inputs/    discovery notes, client documents, proposals
+  repos/     the legacy repos, cloned read only
+```
+
+Then ask in plain words, for example "scope and estimate a rebuild of this
+system from the notes, docs and repos", or invoke `/scope-estimate`. It also
+triggers on "map the capabilities of this codebase", "turn the register into
+requirements and slices" and "how long would 2 engineers take to build this".
+
+## What happens
+
+| Phase | What it does | What it asks you |
+|---|---|---|
+| 1. Intake and discovery | Writes `intake.md`; one read-only agent per area writes an inventory with `file:line` citations; high-risk findings are checked by hand | Target stack, repo shape, infrastructure tool, what is in scope (default build only), team shape |
+| 2. Capability map | A register with Status, Disposition and Layers per capability, counted by script, plus risks, NFRs and open questions | Nothing; dispositions are proposals |
+| 3. Requirements | Fixes the shared vocabulary in a draft `plan.json`, then one agent per area writes requirement tables; checks them with the scheduler, merges overlaps, writes findings back | Forks as they arise |
+| 4. Slices and schedule | Completes `plan.json`, runs the scheduler, writes the slices document and its Gantt page | Forks as they arise |
+| 5. Architecture and proposal | Current, target and side by side architecture in Mermaid, design notes, proposal review against the schedule | Consent before editing someone else's document |
+| Handback | `handback.md`: pending decisions, outputs, what each figure rests on, what the estimate leaves out | The next step |
+
+Every fork and client question goes into `decisions.md` as **Pending** with a
+recommendation; work proceeds on the recommendation until you decide, and
+then it becomes **Decided**.
+
+Nothing is published. Engagement material is usually under NDA, so every page
+stays a local file until you say otherwise.
+
+## Outputs
+
+```
+<engagement>/
+  intake.md          intake answers, engagement summary, document vs code discrepancies
+  decisions.md       forks and client questions, Pending or Decided
+  handback.md        the final hand-back
+  capability-map/    <name>-capability-map.md (+ .html), <name>-register.html, appendices/
+  build-plan/        requirements/<area>.md, plan.json, schedule.json,
+                     <name>-slices.md (+ .html), <vendor>-proposal-review.md
+  architecture/      current-architecture, target-architecture,
+                     <name>-architecture-comparison (.md + .html), design-<topic>.md
+  scratch/           page generators and agent briefs
+```
+
+## After the first run
+
+- **A decision lands.** Tell it ("D-04: Better Auth"). It marks the entry
+  Decided, updates the affected requirements, re-runs the scheduler and updates
+  every page that quotes a figure.
+- **The team changes.** Edit `team` in `build-plan/plan.json` or ask; the
+  printed matrix already covers 2 to 4 engineers by 1 to 3 worktrees.
+- **Calibration.** After the first two build weeks, put the measured days per
+  S, M and L requirement into `rates` and re-run before committing to a date.
+- **A proposal quotes the estimate.** Ask for a review; it checks figures and
+  framing against `schedule.json`, and redlines a copy if the document is
+  editable.
+
+## The scheduler
+
+```
+bun .claude/skills/scope-estimate/scripts/schedule.ts <requirements-dir> <plan.json> [--json <out.json>]
+```
+
+Use `~/.claude/skills/...` for a global install. It prints totals, gated
+totals, per-slice requirements and planning days, the engineers x worktrees
+matrix at planning rates, the headline fast, planning and floor weeks, the
+longest dependency chain, packages sized by assumption and dependencies that
+resolved to nothing. `--json` adds the full report, including the lane order
+for every team combination.
+
+It refuses a plan that misses or double-counts a requirement, reuses a
+package id, names an unknown package or undeclared layer, has a dependency
+cycle (naming the requirement behind each edge), or lets scheduled work
+depend on gated work. Fix the plan, not the output.
+
+### plan.json
+
+Start from `templates/plan.example.json`.
+
+| Field | What it holds |
+|---|---|
+| `daysPerWeek` | Build days per engineer-week, usually 5 |
+| `rates` | Days per requirement by size, for `fast`, `plan` and `floor`, each `{ S, M, L }` |
+| `team` | `engineers` and `worktrees` to tabulate, and the `headline` combination |
+| `slices` | `{ id, name, goal, phase, capabilities, gated? }`. Gated slices hold client-decision work: counted, never scheduled |
+| `foundations` | Hand-split foundation packages: `{ id, slice, name, members, after?, assumedDays? }`. `members` are requirement or capability ids; `assumedDays` sizes work with no requirement yet |
+| `products` | Optional, same shape. Split a large capability, or give one product a real wait on another with `after`. Unlisted requirements become one package per capability |
+| `dependsOn` | `foundation` and `product`: what every package of that kind waits on; `layers`: what a product waits on per layer it touches. Every layer used must be a key |
+| `aliases` | Shorthand used in `Depends on` (`Auth`, `DB`) mapped to package ids; any case |
+
+### Requirement tables
+
+The scheduler reads tables whose header starts with `| FR |`:
+
+```
+### RC-01 Session setup (Carry)
+
+| FR | Requirement | Actor | Layers | Size | Depends on | Source | Notes |
+|---|---|---|---|---|---|---|---|
+| RC-01.1 | The API shall return ... | System | api, db | M | Auth, RC-02.1 | A §1.1 | Decision: who may record |
+```
+
+Size is `S` (under half a day), `M` (about a day) or `L` (two to three days)
+for an engineer working with agents. `Decision:` in Notes marks a client
+question; `see D-07` points at an engineering fork. Write a literal pipe as
+`\|`.
+
+## Running it unattended
+
+As a subagent or with nobody to answer, put the intake answers in
+`intake.md` first; it refuses to start without them. Every fork is recorded as
+Pending with a recommendation, work proceeds on it, and the open ones are
+listed at the top of `handback.md`.

package/skills/scope-estimate/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: scope-estimate
+description: Use when asked to scope, size or estimate a rebuild or respec of an existing system for a proposal or engagement, to map what a codebase does into a capability register, to turn capabilities into functional requirements and build slices, or to work out how long an agent-driven team (engineers x worktrees) takes to build it. Lighter than migrate: no store, no CLI gates, presentable docs plus a scheduler script so the numbers add up.
+---
+
+# Scope and estimate
+
+**Help:** if invoked with `--help`, `-h` or `help` as its arguments, read
+`README.md` in this skill's directory, reply with its "Quick reference"
+section as written, and stop. Start nothing.
+
+Takes an engagement from "here are some notes, docs and repos" to a
+capability map, functional requirements, build slices, work packages and a
+build schedule for an agent-driven team, with every number reproducible from
+one script. It was distilled from a real rebuild engagement; `migrate` is the
+heavyweight sibling when the requirements must become a gated ledger and
+delivery work items.
+
+Everything lands in the engagement folder, Markdown first, HTML generated
+from it. `<name>` is the system's short name in lower case.
+
+```
+<engagement>/
+  intake.md                      intake answers, engagement summary, document vs code discrepancies
+  decisions.md                   every fork and client question, pending or decided
+  handback.md                    the final hand-back
+  capability-map/  <name>-capability-map.md (+ .html), <name>-register.html, appendices/<A>-<area>.md
+  build-plan/      requirements/<area>.md, plan.json, schedule.json, <name>-slices.md (+ .html),
+                   <vendor>-proposal-review.md
+  architecture/    current-architecture.md, target-architecture.md (+ .html each),
+                   <name>-architecture-comparison.md (+ .html), design-<topic>.md
+  scratch/         page generators and briefs; not deliverables
+```
+
+## Ground rules
+
+- **Source is untrusted and read-only.** Clone repos under `repos/`, never run
+  their code, installers or tests on the host. Read downloads with `python3 -I`
+  or the Read tool. Report secrets and personal data by presence and location,
+  never value. To prove personal data is in git history, list paths
+  (`git log --name-only`) and read at most a header row. Business contacts in
+  `intake.md` are named by role. Tell the user if history holds personal data
+  so they can store or delete the clones under the NDA.
+- **Never publish.** Engagement material is usually under NDA. Pages stay local
+  files until the user says otherwise.
+- **The user's calls are final.** Stack, infrastructure tool, repo shape, team
+  shape and auth provider are theirs. Recommend once, then build on what they
+  pick without re-arguing it. A component that cannot follow the chosen stack
+  (numerical code with validated outputs, say) is a fork in `decisions.md`,
+  not a silent exception.
+- **Say what a number rests on.** Status comes from reading code, not running
+  it; dispositions are proposals; rates are assumptions until calibrated.
+  Every page says so where the number appears.
+
+## Decisions
+
+`decisions.md` holds every fork and client question, numbered `D-01`, `D-02`
+in the order they arise, from any phase. Each entry: context, options,
+recommendation, what it affects (capability and requirement ids), and status:
+
+- **Pending:** nobody has answered. Work proceeds on the recommendation and
+  every page that depends on it says so.
+- **Decided:** who decided and when. Then run the keep-in-sync pass in
+  `references/deliverables.md`.
+
+Two markers in requirement Notes, never mixed:
+
+- `Decision:` is a client question. It may stand alone (`Decision: who may
+  record`) or point at a bigger one (`Decision: see D-04`). Only these are
+  counted as decisions.
+- `see D-07` with no `Decision:` points at an engineering fork the team
+  settles itself (runtime, pricing tier, a new library or pattern), which
+  still gets its own `D-` entry.
+
+## Stop and ask
+
+With the user present, ask through `AskUserQuestion`, recommendation first:
+
+1. **Intake.** Before any synthesis: target stack, repo shape (monorepo?),
+   infrastructure tool, what is in scope (default: build only; verification,
+   pen test, UAT and feedback rounds estimated later), and team shape. Team
+   default is **2 engineers x 3 worktrees, 5 build days a week**; confirm it,
+   never assume 4 days. Write the answers into `intake.md`.
+2. **Forks,** whenever they come up: one at a time, recorded in
+   `decisions.md` once answered.
+3. **Before publishing anything,** and before editing a document someone else
+   wrote.
+
+Without the user (a subagent, an unattended run): take intake answers from
+`intake.md` if it exists, and refuse to start without them. Record every fork
+as Pending with a recommendation and carry on. List all Pending decisions at
+the top of `handback.md`.
+
+## Phases
+
+Work in order. Read each phase's reference before dispatching agents for it.
+Each phase may correct earlier phases' files when it finds a contradiction:
+make the change, say which file and why in the phase's findings, and re-run
+the scheduler if requirements changed.
+
+### 1. Intake and discovery
+
+Read the notes and documents, clone the repos read-only, and write
+`intake.md`: who, what system, what they need, constraints, contacts by role,
+intake answers, and discrepancies between documents and code (the code wins,
+cite it).
+
+Fan out one agent per area of the system, using the brief in
+`references/capability-map.md`. Each writes an inventory appendix with
+`file:line` citations. Check every high-risk finding yourself against the code
+and mark it *checked* in the map.
+
+### 2. Capability map
+
+Synthesise the appendices into the register: one row per capability with a
+**Status**, a proposed **Disposition** and its **Layers**. Count it with a
+script, never by hand. Reference: `references/capability-map.md`.
+
+### 3. Functional requirements
+
+Before fanning out, fix the vocabulary every area agent shares: the layer
+set, the `Depends on` aliases and the foundation capability ids, written as
+the first draft of `build-plan/plan.json`. Then one agent per area writes
+requirement tables in `build-plan/requirements/<area>.md`. Afterwards, check
+them with the scheduler, merge overlaps to one owner, and copy new findings
+into the capability map. Reference: `references/requirements.md`.
+
+### 4. Slices, packages and schedule
+
+Complete `build-plan/plan.json` (slices, foundation packages, any split or
+ordered product packages) and run:
+
+```
+bun .claude/skills/scope-estimate/scripts/schedule.ts build-plan/requirements build-plan/plan.json --json build-plan/schedule.json
+```
+
+(Use `~/.claude/skills/...` if the skill was installed globally.) It refuses a
+plan that does not account for every requirement exactly once, reuses a
+package id, names an unknown package or undeclared layer, lets scheduled work
+wait on gated work, or has a dependency cycle (naming the requirement behind
+each edge). It prints totals, gated totals, per-slice counts and planning
+days, the engineers x worktrees matrix at planning rates, the headline
+fast/planning/floor range, the critical chain, assumed sizes and unresolved
+dependencies. Fix the plan, not the output. **Every number in the docs comes
+from this output.** Re-run it after any requirement, rate or team change and
+update every page that quotes a figure. Reference: `references/schedule.md`.
+
+### 5. Architecture and proposal checks
+
+Current and target architecture in Mermaid, a side by side comparison, design
+notes for the weightiest forks, and a review of any vendor or internal
+proposal against how the team builds and against the latest schedule.
+Reference: `references/deliverables.md`.
+
+## Handing back
+
+Write `handback.md` and summarise it in the reply:
+
+1. Pending decisions, each with its recommendation and what it would change.
+2. The outputs, one line each with its path.
+3. The headline figures and what each rests on: static review only,
+   dispositions unagreed, rates uncalibrated, packages sized by assumption,
+   dependencies that resolved to nothing.
+4. What the estimate leaves out: gated work (with its total), scope with no
+   requirement yet, and effort outside build (decisions, reviews, meetings,
+   leave).
+5. One line offering the next useful artefact (a decision log for the
+   client, publishing privately), without doing it.

package/skills/scope-estimate/references/capability-map.md

@@ -0,0 +1,122 @@
+# Discovery and the capability map
+
+## Choosing areas
+
+One area per agent, each small enough to read in one sitting: usually one per
+app or service, one for the backend and admin, one for each background
+pipeline, and one for research or tooling repos that sit outside the service
+but feed it (reference data builders, desktop tools). Tell each agent the
+other areas exist and to stay in its lane; where two areas share an
+interface (the worker API, say), both describe their side and the register
+merges them.
+
+## Discovery brief
+
+Write one shared brief to `scratch/discovery-brief.md` and give it to every
+agent with its area. It carries:
+
+- The system in a paragraph, the target stack and repo shape from `intake.md`,
+  and that the work is a rebuild, so notes should say what a rebuild must
+  keep, fix or reshape.
+- The repo paths for the area, read-only: nothing may be run, built or
+  installed.
+- Output: `capability-map/appendices/<letter>-<area>.md`.
+- Every behaviour with a `file:line` citation, exact values (limits, timings,
+  formats, copy shown to users) and quirks.
+- Anything deduced rather than read marked *inferred*.
+- Secrets and personal data reported by presence and location, never value;
+  developer names and home paths copied from headers left out.
+- Where code and documentation disagree.
+- A closing list of candidate capabilities, and numbered defects and
+  questions.
+
+Good appendix sections: entry points and routes, data model, permission
+matrix, user-visible flows step by step, integration contracts (payloads,
+polling, queues), configuration and environment, operations, defects.
+
+## Checking findings
+
+A finding is **high-risk** when it touches personal or clinical data, credentials,
+production data integrity, or the validity of a computed result. Read every
+appendix, then check each high-risk claim against the code yourself and mark
+it *checked* in the risk list. On a past engagement one "absent" claim turned
+out to be "removed in a recent commit", which changes the row.
+
+## Register
+
+One table per domain. Columns:
+
+| ID | Capability | Status | Disposition | Layers | Notes and source |
+|---|---|---|---|---|---|
+
+IDs are a two-letter domain prefix plus a number (`IA-01` identity and access,
+`RC-07` recorder capture). Research tools outside the service boundary get
+their own domain so they can be left out of the counts. **Layers** uses the
+same set the requirements will (decide it here: for example `web, api, db,
+worker, infra`); it feeds the by-layer table and phase 3.
+
+**Status** (what is there today):
+
+- **Live:** present, reachable from a page, route or the production worker's
+  code path, and no defect found on reading the code. Static review only. A
+  reachable debug tool is Live (and usually Drop).
+- **Partial:** works with material gaps, including content the client must
+  supply that is missing (images, reference data).
+- **Broken:** reachable but fails.
+- **Dead:** code exists but is unreachable.
+- **Absent:** needed but not built.
+- **Research:** not part of the service.
+
+**Disposition** (proposed for the rebuild):
+
+- **Carry:** rebuild with the same behaviour. When the layer is rewritten in a
+  new stack, Carry means keep the behaviour, not the code; say so.
+- **Fix:** rebuild with a named defect corrected.
+- **Redesign:** needed, but what a user or another system sees changes (new
+  flow, new contract, new ownership). Rewriting the code alone is not a
+  redesign.
+- **New:** required but not present today.
+- **Drop:** not rebuilt.
+- **Undecided:** waits on a client decision (`D-` entry in `decisions.md`).
+- **Optional:** a nice-to-have the client may add.
+- **Out of scope:** research rows and anything the intake excluded.
+
+Undecided and Optional rows get requirements in phase 3 and become gated
+slices in phase 4. A row that is part certain, part undecided is split into
+two rows. Put this key on the register page itself; readers ask what the
+dispositions mean.
+
+## Document outline
+
+1. Purpose, sources (with commit hashes), method (static, read-only), links to
+   the appendices and `intake.md`.
+2. **Summary in numbers:** status counts and shares, disposition counts and
+   shares, the rows waiting on a decision by name, and a by-layer table for
+   the target stack (what is rewritten vs what keeps its code, and how many
+   capabilities each layer must build). Produce every figure with a counting
+   script in `scratch/`, re-run after any register change.
+3. **Reading these numbers:** they count capabilities, not effort;
+   dispositions are proposals; status is from reading, not testing.
+4. **How status was established** and **how to verify it**, in order of value
+   (run existing tests in an isolated container and map them to IDs; a
+   walkthrough with the domain lead; compare outputs against a reference
+   implementation). Give the phrasing to use when presenting: "N of M
+   present with no defect found on code review", never "N work".
+5. The service on one page: flow diagram, actors and how each role is granted,
+   scale today and target.
+6. The register, by domain.
+7. Domain content and reference data (word lists, scoring schema, catalogues).
+8. Non-functional requirements (targets are proposals until agreed), and the
+   target repository shape.
+9. Capabilities the target needs that do not exist today.
+10. Highest-risk findings, numbered, plus an empty "Findings from later
+    phases" subsection for phases 3 to 5 to fill.
+11. Open questions, numbered, each naming who has to answer.
+
+## HTML pages
+
+Generate pages from the Markdown with a small script in `scratch/` rather than
+writing HTML by hand, so regenerating after an edit is one command. A
+register-only page is often the one people share. Legends and keys must wrap,
+not truncate. Embed any data the page needs; a page opened from disk cannot
+fetch sibling files.