spec-ctx 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quach Hoanh Son
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+# spec-ctx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+spec-ctx ticks an [OpenSpec](https://github.com/Fission-AI/OpenSpec) task only after its Verify command passes and hands the agent one task of spec text, a context ratio of 0.0518 (`docs/metrics/2026-10-25.md`).
+
+```bash
+npx -y github:sonqh/spec-ctx#4490d188ad48 init --all
+npx -y github:sonqh/spec-ctx#4490d188ad48 task next
+npx -y github:sonqh/spec-ctx#4490d188ad48 task start add-mfa/1.3
+```
+
+```text
+$ specctx task start add-mfa/1.3
+-- REQ-UA-004 | openspec/changes/add-mfa/specs/user-auth/spec.md:5 | active | requested
+### Requirement: REQ-UA-004 Second factor
+The system SHALL ask for a TOTP code after a valid password.
+
+#### Scenario: SCN-UA-004-1 Valid code
+- **WHEN** the user enters the current TOTP code
+- **THEN** the system opens a session
+
+#### Scenario: SCN-UA-004-2 Expired code
+- **WHEN** the user enters a code older than 30 seconds
+- **THEN** the system rejects it
+```
+
+## Why
+
+- Checkboxes lie. `task done` runs Verify and writes evidence, and 70 of 86 tasks hold it (evidence ratio 0.81).
+- Context overflows. A bundle holds 0.0518 of the spec text on average (27 tasks).
+- Evidence goes stale. The check caught 36 stale results in 59 reopens.
+
+## Demo
+
+![One task loop: status, task next, task start, an edit, task done, stats](docs/demo/loop.svg)
+
+<details>
+<summary>Transcript of the demo</summary>
+
+```text
+$ specctx status
+index rebuilt
+add-mfa  done 2  open 1
+uncovered active REQs in main: 5
+next: specctx task next
+$ specctx task next
+add-mfa/1.3  Add the TOTP prompt to the login form.
+reqs: REQ-UA-004
+verify: grep -q totp src/login.ts
+$ specctx task start add-mfa/1.3 | head -12
+-- REQ-UA-004 | openspec/changes/add-mfa/specs/user-auth/spec.md:5 | active | requested
+### Requirement: REQ-UA-004 Second factor
+The system SHALL ask for a TOTP code after a valid password.
+
+#### Scenario: SCN-UA-004-1 Valid code
+- **WHEN** the user enters the current TOTP code
+- **THEN** the system opens a session
+
+#### Scenario: SCN-UA-004-2 Expired code
+- **WHEN** the user enters a code older than 30 seconds
+- **THEN** the system rejects it
+
+$ printf '// REQ-UA-004\nexport const prompt = "totp";\n' > src/login.ts
+$ specctx task done add-mfa/1.3
+index rebuilt
+done add-mfa/1.3. Evidence: .ctx/evidence/add-mfa/1.3.json
+$ specctx stats --change add-mfa
+index rebuilt
+change   context_ratio  evidence_ratio  stale_catches  cycle_time_median_s  debt
+add-mfa  0.2950 (n=1)   1.00 (1/1)      n/a            6 (n=1)              2
+total    0.2950 (n=1)   1.00 (1/1)      n/a            6 (n=1)              13 (0 baselined + 13 new)
+gate_runs n/a
+gate_pass_rate n/a
+gate_failures_caught n/a
+context_ratio = bundle chars / chars of all specs. Lower is better.
+```
+
+</details>
+
+The demo runs on a copy of `tests/fixtures/no-id-repo` after `specctx adopt`. `bash docs/demo/record.sh` records it again.
+
+## What it does
+
+spec-ctx is a deterministic context engine and task workflow for OpenSpec projects. The CLI is `specctx`.
+
+OpenSpec gives you a proposal, specs, a design, and tasks. spec-ctx adds what an AI agent needs to work on them without reading the whole tree:
+
+- Stable IDs on every requirement, scenario, decision, and task.
+- An index that links each ID to code, tests, and other IDs.
+- `bundle`: the few kilobytes of spec that one task needs, with the file and line of each block.
+- `task next`, `task start`, `task done`: the checkbox changes only after the `Verify:` command of the task exits 0, and the evidence stays beside the tree.
+- A generated handoff, so the next session starts with one command.
+
+No LLM call. No daemon. The same files give the same bytes.
+
+## Install
+
+spec-ctx needs Node 22. Run it in a project after `openspec init`.
+
+```bash
+npx -y github:sonqh/spec-ctx#4490d188ad48 init --all    # from git, works today
+npx spec-ctx init --all                                # from npm, after the 0.1.0 publish
+```
+
+The git form builds the package on install with Node only. Pin a commit SHA. A branch name such as `main` also works, but it moves.
+
+The command writes `spec-ctx.toml`, installs the `spec-driven-ids` schema into `openspec/schemas/`, adds its rules to `openspec/config.yaml`, and installs three skills into `.claude/skills/` and `.agents/skills/`.
+
+The examples below use `specctx`. With `npx`, write the `npx` form in its place. After the publish, `npm install -g spec-ctx` puts `specctx` on your path. Each GitHub release also carries a single binary for Linux and macOS.
+
+## Two paths
+
+### Fresh project
+
+```bash
+npx -y @fission-ai/openspec@latest init
+npx spec-ctx init --all
+specctx gate --strict
+```
+
+### Existing OpenSpec project
+
+```bash
+npx spec-ctx init --all
+specctx adopt --dry-run                 # the ID that each header gets. Writes nothing.
+specctx adopt                           # writes the IDs into main specs and active deltas
+specctx task backfill --manual "adopted"
+specctx baseline write
+specctx gate --strict
+```
+
+- `adopt` gives an ID to every requirement and scenario header without one, in `openspec/specs/` and in the deltas of active changes. A delta header gets the main ID by its text or through its RENAMED line. A delta header that matches neither keeps its text and goes into `adopt-report.md`.
+- `adopt` derives a capability code from each folder name, for example `UA` for `user-auth`. It writes the codes into `spec-ctx.toml`. Rename a code there before the IDs spread.
+- `adopt` runs `check` before and after the write. A finding that the write added undoes every file. A second run prints `nothing to adopt`.
+- `task backfill` writes manual evidence for every ticked task that has none.
+- `baseline write` records the debt of the day in `.ctx/baseline.json`: untested requirements and scenarios, tasks without evidence, and legacy tasks without a citation or a Verify code span. `check` hides that debt and prints `baselined: <n>`. New debt still shows.
+- Legacy tasks stay in the baseline until an agent adds `[REQ-...]` citations and a `Verify:` code span. `specctx baseline prune` then drops them. No command adds a single entry.
+
+Both paths have an end to end test: `tests/paths/fresh.sh` and `tests/paths/existing.sh`.
+
+## The loop
+
+```bash
+specctx status                 # active changes, current task, open questions
+specctx task next              # the next open task, its REQ IDs, and its Verify command
+specctx task start 001/1.1     # the spec bundle for that task
+specctx task done 001/1.1      # run Verify, write evidence, set the checkbox
+specctx check --strict         # IDs, links, coverage, and evidence
+specctx handoff write          # .ctx/handoff.md for the next session
+```
+
+The skills `specctx-bootstrap`, `specctx-next`, and `specctx-done` teach an agent this loop. Install them alone with `npx skills add sonqh/spec-ctx` or `specctx init --skills`.
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `build` | Write `.ctx/index.json`. Every other command rebuilds a stale index first. |
+| `status` | Active changes with task counts, the current task, and open questions. |
+| `query <term...>` | Entries that hold every term. Flags: `--kind`, `--change`, `--limit`, `--all`. |
+| `related <ID>` | Linked entries with the reason for each link. Flags: `--depth`, `--all`. |
+| `bundle <ID...>` | Spec text of the IDs, their scenarios, decisions, and neighbors. Flags: `--budget`, `--depth`, `--all`. |
+| `check` | ID and link integrity. `--strict` adds test coverage and evidence. |
+| `id new`, `id retire` | Allocate and retire IDs. |
+| `task next`, `start`, `verify`, `done`, `reopen` | The task state machine. |
+| `handoff write`, `ask`, `resolve` | The session handoff and its open questions. |
+| `init` | Config file, schema bundle, and skills. Flags: `--schema`, `--skills`, `--all`, `--force`. |
+| `adopt` | IDs for a project without them. `--dry-run` writes nothing. |
+| `baseline write`, `prune` | The debt ratchet in `.ctx/baseline.json`. |
+| `task backfill` | Manual evidence for ticked tasks without it. |
+| `gate` | `check`, both markdown linters, `openspec validate`, and the 500 character length check on active deltas. |
+| `lint tells`, `lint ste` | The two markdown linters. Flags: `--baseline`, `--disable`, `--json`, `--selftest`. |
+| `help <command>` | The page of one command. `specctx <command> --help` prints the same page. |
+
+Every command takes `--root <path>` and `--json`. A task ID takes the change key, such as `008/1.1` or `add-mfa/1.1`, or the full folder name. Outside an OpenSpec project every command but `init` exits 2. Exit codes: 0 for success, 1 for findings or a failed Verify command, 2 for a usage error, 3 for an internal error.
+
+## Config reference
+
+`spec-ctx.toml` sits at the project root. Every key is optional.
+
+```toml
+[scan]
+specs = ["openspec/specs/**/*.md"]      # main specs
+changes = ["openspec/changes/**/*.md"]  # active and archived changes
+decisions = ["decisions/*.md"]          # decision records
+code = ["src/**"]                       # files with code tags
+tests = ["tests/**"]                    # files with Covers tags and scenario IDs
+ignore = []                             # globs that the scan skips
+
+[ids]
+caps = []                               # capability codes. Empty means any code is valid.
+task_pattern = '\d+\.\d+'               # the task number in a tasks.md checkbox
+
+[ids.paths]
+UA = "user-auth"                        # capability path of each code. adopt writes the derived ones.
+
+[bundle]
+budget = 8000                           # characters
+depth = 1
+
+[verify]
+timeout_s = 600
+```
+
+One environment variable changes the engine:
+
+| Variable | Effect |
+| --- | --- |
+| `SPECCTX_OPENSPEC` | The command that `gate` runs for `openspec validate`. The default is `npx -y @fission-ai/openspec@latest`. Tests and offline machines set it. |
+
+## Markdown linters
+
+`specctx lint tells` and `specctx lint ste` replace `scripts/tells-lint.py` and `scripts/ste-lint.py` from the ste-humanize skill. They take the same flags and give the same output and exit codes. They need Node only.
+
+```bash
+# before
+python3 scripts/tells-lint.py --baseline 0 README.md
+python3 scripts/ste-lint.py --baseline 0 --disable synonym-rotation README.md
+# after
+npx spec-ctx lint tells --baseline 0 README.md
+npx spec-ctx lint ste --baseline 0 --disable synonym-rotation README.md
+```
+
+## GitHub Action
+
+```yaml
+- uses: sonqh/spec-ctx@v0
+  with:
+    version: latest   # npm version, or a git spec such as github:sonqh/spec-ctx#main
+    strict: true
+```
+
+The action runs `specctx gate`: `check --strict`, both markdown linters, `openspec validate --all --strict`, and the length check.
+
+## Status
+
+- Archived: 001 engine port, 002 IDs and tasks, 004 adopt existing, 005 metrics, 006 polish, 007 README and demo, 008 first run UX.
+- Open: 003 distribution. Only the npm publish of `0.1.0` waits.
+- Until the publish, install from git with `npx -y github:sonqh/spec-ctx#4490d188ad48`. The npm forms `npx spec-ctx` and `npm install -g spec-ctx` work after it.
+
+## Contribute
+
+`docs/CONTRIBUTING.md` holds the build steps, the layout, the ID scheme, and the gate steps.
+
+## License
+
+MIT.

package/action.yml

@@ -0,0 +1,33 @@
+name: spec-ctx check
+description: Run specctx check, the markdown linters, and openspec validate on an OpenSpec project.
+branding:
+  icon: check-square
+  color: blue
+inputs:
+  version:
+    description: Version of the spec-ctx npm package, or a git spec such as github:sonqh/spec-ctx#main.
+    default: latest
+  strict:
+    description: Run check and validate in strict mode.
+    default: "true"
+  markdown:
+    description: Globs of the markdown files that the linters read, separated by spaces.
+    default: "openspec/**/*.md decisions/*.md *.md"
+  specctx:
+    description: Command that runs specctx. Empty means npx with the version input.
+    default: ""
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22
+    - name: spec-ctx gates
+      shell: bash
+      run: bash "$GITHUB_ACTION_PATH/action/run.sh"
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+        INPUT_STRICT: ${{ inputs.strict }}
+        INPUT_MARKDOWN: ${{ inputs.markdown }}
+        INPUT_SPECCTX: ${{ inputs.specctx }}
+        SPECCTX_ACTION_PATH: ${{ github.action_path }}

package/dist/adopt/config-write.js

@@ -0,0 +1,59 @@
+// REQ-ADOPT-004 write derived codes into spec-ctx.toml under [ids] caps and [ids.paths]. Comments stay.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+import { CONFIG_FILE, INIT_TEXT } from "../config.js";
+/** The new text of spec-ctx.toml with the codes added. Codes already listed stay as they are. */
+export function withCaps(text, caps) {
+    const cur = parse(text);
+    const have = new Set(cur.ids?.caps ?? []);
+    const paths = cur.ids?.paths ?? {};
+    const addCaps = caps.filter((c) => !have.has(c.code)).map((c) => c.code);
+    const addPaths = caps.filter((c) => paths[c.code] === undefined);
+    let lines = text.split("\n");
+    const sectionAt = (name) => lines.findIndex((l) => l.trim() === `[${name}]`);
+    if (addCaps.length) {
+        let ids = sectionAt("ids");
+        if (ids < 0) {
+            lines.push("", "[ids]");
+            ids = lines.length - 1;
+        }
+        let end = lines.findIndex((l, i) => i > ids && /^\s*\[/.test(l));
+        if (end < 0)
+            end = lines.length;
+        const at = lines.findIndex((l, i) => i > ids && i < end && /^caps\s*=/.test(l));
+        const all = [...(cur.ids?.caps ?? []), ...addCaps];
+        const line = `caps = [${all.map((c) => JSON.stringify(c)).join(", ")}]`;
+        if (at >= 0 && /\]\s*(#.*)?$/.test(lines[at]))
+            lines[at] = line;
+        else if (at >= 0) {
+            // a caps list over several lines: replace it up to the closing bracket
+            let close = at;
+            while (close < end && !/\]/.test(lines[close]))
+                close++;
+            lines.splice(at, close - at + 1, line);
+        }
+        else
+            lines.splice(ids + 1, 0, "# Capability codes. adopt added the derived ones.", line);
+    }
+    if (addPaths.length) {
+        let sec = sectionAt("ids.paths");
+        if (sec < 0) {
+            lines = [...lines.join("\n").replace(/\n*$/, "").split("\n"), "", "[ids.paths]", "# Capability path of each code. adopt wrote the derived ones. Rename a code here before the IDs spread."];
+            sec = lines.length - 1;
+        }
+        let end = lines.findIndex((l, i) => i > sec && /^\s*\[/.test(l));
+        if (end < 0)
+            end = lines.length;
+        while (end > sec + 1 && lines[end - 1].trim() === "")
+            end--;
+        lines.splice(end, 0, ...addPaths.map((c) => `${c.code} = ${JSON.stringify(c.path)}`));
+    }
+    const out = lines.join("\n").replace(/\n*$/, "\n");
+    parse(out);
+    return out;
+}
+export function configText(root) {
+    const p = join(root, CONFIG_FILE);
+    return existsSync(p) ? readFileSync(p, "utf8") : INIT_TEXT;
+}

package/dist/adopt/plan.js

@@ -0,0 +1,276 @@
+// REQ-ADOPT-001 REQ-ADOPT-004 the adopt plan: which header gets which ID. It reads files and writes nothing.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { retiredAll } from "../ids/ids.js";
+import { cmpStr, splitLines } from "../util/pystr.js";
+const REQ_HDR = /^### Requirement:[ \t]*(.*)$/s;
+const SCN_HDR = /^#### Scenario:[ \t]*(.*)$/s;
+const HAS_REQ = /^REQ-([A-Z]{2,6})-(\d{3})(?:[ \t]|$)/;
+const HAS_SCN = /^SCN-([A-Z]{2,6})-(\d{3})-(\d+)(?:[ \t]|$)/;
+const RENAME = /^- (FROM|TO):[ \t]*`### Requirement:[ \t]*(.*)`[ \t]*$/s;
+function listSpecs(root, base) {
+    const out = [];
+    const walk = (abs, rel) => {
+        if (!existsSync(abs))
+            return;
+        for (const n of readdirSync(abs).sort(cmpStr)) {
+            const p = join(abs, n);
+            const r = `${rel}/${n}`;
+            if (statSync(p).isDirectory())
+                walk(p, r);
+            else if (n === "spec.md")
+                out.push(r);
+        }
+    };
+    walk(join(root, base), base);
+    return out;
+}
+function splitId(text, re) {
+    const m = re.exec(text);
+    if (!m)
+        return { id: null, name: text.trim() };
+    const id = m[0].trim();
+    return { id, name: text.slice(m[0].length).trim() };
+}
+function parse(root, rel, cap) {
+    const lines = splitLines(readFileSync(join(root, rel)).toString("utf8"));
+    const blocks = [];
+    const renames = [];
+    let section = "";
+    let fence = false;
+    let req;
+    let from = null;
+    lines.forEach((line, i) => {
+        const t = line.trim();
+        if (t.startsWith("```") || t.startsWith("~~~"))
+            fence = !fence;
+        if (fence)
+            return;
+        if (line.startsWith("## ")) {
+            section = line.slice(3).trim().split(" ")[0].toUpperCase();
+            return;
+        }
+        let m = REQ_HDR.exec(line);
+        if (m) {
+            const { id, name } = splitId(m[1], HAS_REQ);
+            req = { kind: "req", line: i + 1, raw: line, name, id, section };
+            blocks.push(req);
+            return;
+        }
+        m = SCN_HDR.exec(line);
+        if (m) {
+            const { id, name } = splitId(m[1], HAS_SCN);
+            blocks.push({ kind: "scn", line: i + 1, raw: line, name, id, req, section });
+            return;
+        }
+        m = RENAME.exec(line);
+        if (m && section === "RENAMED") {
+            const { id, name } = splitId(m[2], HAS_REQ);
+            const item = { line: i + 1, name, id, raw: line };
+            if (m[1] === "FROM")
+                from = item;
+            else if (from) {
+                renames.push({ from, to: item });
+                from = null;
+            }
+        }
+    });
+    return { rel, cap, lines, blocks, renames };
+}
+/** REQ-ADOPT-004 candidate codes in order: the base code, then two and three letters of the first segment, then a suffix letter. */
+export function codeCandidates(path) {
+    const segs = path.split(/[/-]/).map((x) => x.toUpperCase().replace(/[^A-Z]/g, "")).filter(Boolean);
+    if (!segs.length)
+        return [];
+    const rest = segs.slice(1).map((x) => x[0]).join("");
+    const base = segs.length === 1 ? segs[0].slice(0, 3) : segs.map((x) => x[0]).join("").slice(0, 6);
+    const out = [base, (segs[0].slice(0, 2) + rest).slice(0, 6), (segs[0].slice(0, 3) + rest).slice(0, 6)];
+    for (let c = 66; c <= 90; c++)
+        out.push((base.slice(0, 5) + String.fromCharCode(c)));
+    return [...new Set(out.filter((x) => /^[A-Z]{2,6}$/.test(x)))];
+}
+export function deriveCode(path, taken = new Set()) {
+    const code = codeCandidates(path).find((c) => !taken.has(c));
+    if (!code)
+        throw new UsageExit(`no free capability code for ${path}. Add one under [ids.paths] in spec-ctx.toml`);
+    return code;
+}
+export function planAdopt(root, cfg) {
+    const mains = listSpecs(root, "openspec/specs");
+    const changesDir = join(root, "openspec/changes");
+    const deltas = [];
+    if (existsSync(changesDir)) {
+        for (const c of readdirSync(changesDir).sort(cmpStr)) {
+            if (c === "archive" || !statSync(join(changesDir, c)).isDirectory())
+                continue;
+            deltas.push(...listSpecs(root, `openspec/changes/${c}/specs`));
+        }
+    }
+    const capOf = (rel) => rel.replace(/^openspec\/(changes\/[^/]+\/)?specs\//, "").replace(/\/spec\.md$/, "");
+    const files = [...mains, ...deltas].map((r) => parse(root, r, capOf(r)));
+    const mainFiles = files.filter((f) => f.rel.startsWith("openspec/specs/"));
+    const deltaFiles = files.filter((f) => !f.rel.startsWith("openspec/specs/"));
+    // the code of each capability: config paths, then an ID already in its spec, then derived
+    const paths = cfg.ids.paths ?? {};
+    const codeOfPath = new Map();
+    for (const [code, p] of Object.entries(paths))
+        codeOfPath.set(p, code);
+    // on a collision the shorter path keeps the base code: user-auth keeps UA, upload-api takes UPA
+    const capList = [...new Set(files.map((f) => f.cap))].sort((a, b) => a.length - b.length || cmpStr(a, b));
+    const taken = new Set([...cfg.ids.caps, ...codeOfPath.values()]);
+    const caps = [];
+    for (const cap of capList) {
+        let code = codeOfPath.get(cap);
+        let derived = false;
+        if (!code) {
+            const existing = files.filter((f) => f.cap === cap).flatMap((f) => f.blocks).find((b) => b.kind === "req" && b.id);
+            if (existing)
+                code = HAS_REQ.exec(existing.id)[1];
+        }
+        if (!code) {
+            code = deriveCode(cap, taken);
+            derived = true;
+            taken.add(code);
+        }
+        caps.push({ code, path: cap, derived });
+    }
+    caps.sort((a, b) => cmpStr(a.path, b.path));
+    const codeFor = new Map(caps.map((c) => [c.path, c.code]));
+    // next free number per code: every ID in the tree, the archive, and the retired list
+    const used = new Map();
+    const bump = (code, n) => {
+        used.set(code, Math.max(used.get(code) ?? 0, n));
+    };
+    const allIds = [...retiredAll(root)];
+    for (const f of files)
+        for (const b of f.blocks)
+            if (b.id)
+                allIds.push(b.id);
+    const archive = join(root, "openspec/changes/archive");
+    if (existsSync(archive)) {
+        const walk = (abs) => {
+            for (const n of readdirSync(abs)) {
+                const p = join(abs, n);
+                if (statSync(p).isDirectory())
+                    walk(p);
+                else if (n.endsWith(".md"))
+                    for (const m of readFileSync(p, "utf8").matchAll(/\bREQ-([A-Z]{2,6})-(\d{3})\b/g))
+                        allIds.push(m[0]);
+            }
+        };
+        walk(archive);
+    }
+    for (const id of allIds) {
+        const m = /^REQ-([A-Z]{2,6})-(\d{3})$/.exec(id);
+        if (m)
+            bump(m[1], Number(m[2]));
+    }
+    const nextReq = (code) => {
+        const n = (used.get(code) ?? 0) + 1;
+        if (n > 999)
+            throw new UsageExit(`no free REQ number for ${code}`);
+        used.set(code, n);
+        return `REQ-${code}-${String(n).padStart(3, "0")}`;
+    };
+    const scnUsed = new Map();
+    for (const f of files)
+        for (const b of f.blocks) {
+            if (b.kind === "scn" && b.id) {
+                const m = HAS_SCN.exec(b.id + " ");
+                const key = `REQ-${m[1]}-${m[2]}`;
+                scnUsed.set(key, Math.max(scnUsed.get(key) ?? 0, Number(m[3])));
+            }
+        }
+    const nextScn = (reqId) => {
+        const n = (scnUsed.get(reqId) ?? 0) + 1;
+        scnUsed.set(reqId, n);
+        return `SCN-${reqId.slice(4)}-${n}`;
+    };
+    const edits = [];
+    const unmatched = [];
+    const reqHeader = (id, name) => `### Requirement: ${id} ${name}`;
+    const scnHeader = (id, name) => `#### Scenario: ${id} ${name}`;
+    // main spec: requirement id by name, and scenario id by requirement and name
+    const mainReq = new Map();
+    const mainScn = new Map();
+    for (const f of mainFiles) {
+        const code = codeFor.get(f.cap);
+        const seen = new Set();
+        for (const b of f.blocks) {
+            if (b.kind !== "req")
+                continue;
+            if (seen.has(b.name))
+                throw new UsageExit(`${f.rel}:${b.line} repeats the header "${b.name}". Give one of the two requirements another name, then run adopt again`);
+            seen.add(b.name);
+        }
+        for (const b of f.blocks) {
+            if (b.kind === "req") {
+                const id = b.id ?? nextReq(code);
+                if (!b.id)
+                    edits.push({ file: f.rel, line: b.line, old: b.raw, new: reqHeader(id, b.name) });
+                mainReq.set(`${f.cap}\u0000${b.name}`, id);
+                b.id = id;
+            }
+            else if (b.req?.id) {
+                const id = b.id ?? nextScn(b.req.id);
+                if (!b.id)
+                    edits.push({ file: f.rel, line: b.line, old: b.raw, new: scnHeader(id, b.name) });
+                mainScn.set(`${b.req.id}\u0000${b.name}`, id);
+                b.id = id;
+            }
+        }
+    }
+    // deltas: the same ID as the main header, through text match or the RENAMED mapping
+    for (const f of deltaFiles) {
+        const code = codeFor.get(f.cap);
+        const renamedTo = new Map();
+        for (const r of f.renames) {
+            const id = r.from.id ?? mainReq.get(`${f.cap}\u0000${r.from.name}`) ?? null;
+            if (!id) {
+                unmatched.push({ file: f.rel, line: r.from.line, header: r.from.raw });
+                continue;
+            }
+            renamedTo.set(r.to.name, id);
+            if (!r.from.id)
+                edits.push({ file: f.rel, line: r.from.line, old: r.from.raw, new: `- FROM: \`${reqHeader(id, r.from.name)}\`` });
+            if (!r.to.id)
+                edits.push({ file: f.rel, line: r.to.line, old: r.to.raw, new: `- TO: \`${reqHeader(id, r.to.name)}\`` });
+        }
+        for (const b of f.blocks) {
+            if (b.kind === "req") {
+                if (b.id)
+                    continue;
+                let id = null;
+                if (b.section === "ADDED")
+                    id = nextReq(code);
+                else
+                    id = renamedTo.get(b.name) ?? mainReq.get(`${f.cap}\u0000${b.name}`) ?? null;
+                if (!id) {
+                    unmatched.push({ file: f.rel, line: b.line, header: b.raw });
+                    continue;
+                }
+                edits.push({ file: f.rel, line: b.line, old: b.raw, new: reqHeader(id, b.name) });
+                b.id = id;
+            }
+            else {
+                if (b.id || !b.req?.id)
+                    continue;
+                const id = mainScn.get(`${b.req.id}\u0000${b.name}`) ?? nextScn(b.req.id);
+                edits.push({ file: f.rel, line: b.line, old: b.raw, new: scnHeader(id, b.name) });
+                b.id = id;
+            }
+        }
+    }
+    edits.sort((a, b) => cmpStr(a.file, b.file) || a.line - b.line);
+    return { edits, caps, unmatched };
+}
+export function planLines(p) {
+    const out = p.edits.map((e) => `${e.file}:${e.line}  ${e.old}  ->  ${e.new}`);
+    const derived = p.caps.filter((c) => c.derived);
+    if (derived.length)
+        out.push(...derived.map((c) => `cap: ${c.code} ${c.path}`));
+    for (const u of p.unmatched)
+        out.push(`unmatched: ${u.file}:${u.line}  ${u.header}`);
+    return out;
+}