@dzhechkov/keysarium 1.7.5 → 1.7.6

package/.dz-manifest.json

@@ -5,7 +5,7 @@
     "files": [
       {
         "path": "README.md",
-        "sha256": "e2f661392b2862870ae3ab05892493e5a7ddcdb86360690d126525f08b6d87a1"
+        "sha256": "3b4f6570d8cebd26429409ed23da99ddd082c378946cf722fe62d5b405e288c2"
       },
       {
         "path": "README.ru.md",
@@ -17,7 +17,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "56048c9ebf810b35645674fe4a413112af02be6a53836583d3c80b0ad4047dde"
+        "sha256": "67d60a0ad58316ec7c0cd264683d6d17e5fe7f33c746f151b95c0def597037d6"
       },
       {
         "path": "src/cli.js",
@@ -353,7 +353,7 @@
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/00-complexity-router.md",
-        "sha256": "a1275bd960ddff1c61352f96d8b7a4249371190766f08d1778f5a54f98350950"
+        "sha256": "6a98ca7af49aabcb2e14a081815f1167740ac4dba2e0cbb938c87aceac47bfa3"
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/01-requirements.md",
@@ -381,15 +381,15 @@
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/06-implementation-plan.md",
-        "sha256": "c624e0ade0314ca07913ba64e092d4655f86201856e8188c3e616b2320226c1e"
+        "sha256": "5c8d4c79d5329702b8c75b9afb36ae335aa63c99e74045c0afa98e12658ee975"
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/07-code.md",
-        "sha256": "c427a0abacb4bc1d969d9f47739ce2aeff286a66da73eab67bf042d5c4dc9a59"
+        "sha256": "fb054591e86d55cee184eab96b5f0440053ada8fa9edf619e4a66ec5ac371587"
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/08-qe.md",
-        "sha256": "ea8fb546acb7f09816d2fc9f9189a86f2400b8cec91c9ba4b82b68a8e32920bb"
+        "sha256": "7973676cc9a5a6d8429c0bcdbe163bb5dc16e2d2f28a72698e44ad72d234e199"
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/09-fleet-qe.md",
@@ -481,7 +481,7 @@
       },
       {
         "path": "templates/.claude/skills/feature-adr/scripts/check-plan-completeness.mjs",
-        "sha256": "cbe70a524f6ce7987b5e3961ee412b92c24c00d84066d438c759659d656efaa2"
+        "sha256": "08e69d2e63350fe2dc64483226fcd30901b77a8e930ca6280ef71181c67675b4"
       },
       {
         "path": "templates/.claude/skills/feature-adr/scripts/markdown-masker.mjs",
@@ -989,5 +989,5 @@
       }
     ]
   },
-  "signature": "Ni8QtKUfWoED6GoaSA9ARScSXZdJxtM6FSWTILwzYsRLvgJ6fyCmHV9Vz0IriuT0E/NXt8YYp1Oo8Np1iBpVDg=="
+  "signature": "Ld7xkqWgfHmJp0Xv+wKYPylP5opGZmCfibsIDam0NS90aZ6R9oLfJVeRljITB25umc7/zHZMW1MWLbMornUgDQ=="
 }

package/README.md

@@ -450,6 +450,13 @@ changes. See `@dzhechkov/skills-feature-adr@1.5.3`.
 
 `1.5.38` — a fix to the bundled `feature-adr` gate script in `templates/`, no pipeline change.
 
+The bundled K2 plan-completeness gate (staged, not yet versioned or published) now also checks
+**requirement coverage (C8)** — every id declared in `01_requirements.md` must be referenced by the plan (WARN with
+a count by default, per-id FAIL under `--require-requirements`, which the bundled pipeline passes) — counts ADR
+decisions by in-file heading rather than by filename, and treats an unclosed code fence in a declaration input as
+NOT-ESTABLISHED. The bundled workflow gained ONE bracketed plan-repair round with a proven restore. See
+`@dzhechkov/skills-feature-adr` for the full account.
+
 The bundled K2 plan-completeness gate now tells an **ABSENT** `00_complexity_assessment.md` from a
 deliberate skip: a missing file is a WARNING that names the missing artifact, while a present file
 carrying no acid table is an honest SKIP. Both used to report as a clean skip, so the acid check

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.7.5",
+  "version": "1.7.6",
+  "scripts": {},
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, reward learning, and Cloud.ru AI Factory mapping (--ai-factory flag)",
   "main": "src/cli.js",
   "bin": {
@@ -51,6 +52,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {}
-}
+  }
+}

package/sbom.json

@@ -15,7 +15,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e2f661392b2862870ae3ab05892493e5a7ddcdb86360690d126525f08b6d87a1"
+          "content": "3b4f6570d8cebd26429409ed23da99ddd082c378946cf722fe62d5b405e288c2"
         }
       ]
     },
@@ -49,7 +49,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "56048c9ebf810b35645674fe4a413112af02be6a53836583d3c80b0ad4047dde"
+          "value": "67d60a0ad58316ec7c0cd264683d6d17e5fe7f33c746f151b95c0def597037d6"
         }
       ]
     },
@@ -889,7 +889,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a1275bd960ddff1c61352f96d8b7a4249371190766f08d1778f5a54f98350950"
+          "content": "6a98ca7af49aabcb2e14a081815f1167740ac4dba2e0cbb938c87aceac47bfa3"
         }
       ]
     },
@@ -959,7 +959,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c624e0ade0314ca07913ba64e092d4655f86201856e8188c3e616b2320226c1e"
+          "content": "5c8d4c79d5329702b8c75b9afb36ae335aa63c99e74045c0afa98e12658ee975"
         }
       ]
     },
@@ -969,7 +969,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c427a0abacb4bc1d969d9f47739ce2aeff286a66da73eab67bf042d5c4dc9a59"
+          "content": "fb054591e86d55cee184eab96b5f0440053ada8fa9edf619e4a66ec5ac371587"
         }
       ]
     },
@@ -979,7 +979,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ea8fb546acb7f09816d2fc9f9189a86f2400b8cec91c9ba4b82b68a8e32920bb"
+          "content": "7973676cc9a5a6d8429c0bcdbe163bb5dc16e2d2f28a72698e44ad72d234e199"
         }
       ]
     },
@@ -1209,7 +1209,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cbe70a524f6ce7987b5e3961ee412b92c24c00d84066d438c759659d656efaa2"
+          "content": "08e69d2e63350fe2dc64483226fcd30901b77a8e930ca6280ef71181c67675b4"
         }
       ]
     },

package/templates/.claude/skills/feature-adr/modules/00-complexity-router.md

@@ -103,19 +103,39 @@ Runs after tier classification, only when `{AGENTIC_QE_MODE}` = `direct` | `dire
 
 Step 1 folds `{LEARNED_PATTERNS}` into the requirements brief as "lessons from previous features" — advisory context only, never requirements themselves. Why here: Step 0 is the one point where recall can be keyed to the feature's phase and domain — per-prompt hook auto-injection cannot see which pipeline step is running.
 
+### 7. Task Kind Classification (experiment-envelope, ADR-001)
+
+Classify the feature as exactly ONE of the six task kinds below, and write `Task kind: <x>` as its
+own line in the artifact. This feeds the experiment envelope the conveyor builds after this step —
+downstream learning reads the kind, not a paraphrase, so the line must use one of the exact words.
+
+| Task kind | Criterion |
+|-----------|-----------|
+| `feature` | A genuinely new capability, adapter, command, or skill did not exist before this run. |
+| `bugfix` | The change corrects observed incorrect behavior in existing code — a defect, not an absence. |
+| `refactor` | Behavior is unchanged; the change restructures, renames, or simplifies existing code. |
+| `tooling` | The change is to build/CI/dev-tooling/scripts rather than to the product's own runtime behavior. |
+| `docs` | The change is documentation-only (README, ADR prose, comments) with no code delta. |
+| `research` | The deliverable is a finding or a design decision, not a shipped code change. |
+
+If `args.taskKind` was passed explicitly by the caller, it OVERRIDES this classification — record
+both: `Task kind: <forced value> (forced by the caller)` as the kind of record, and your own
+classification separately if it differs, the same pattern Step 0 already uses for a forced tier.
+
 ## Output
 
 Set the following variables:
 
 ```
 {COMPLEXITY_TIER} = S | M | L | XL
+{TASK_KIND} = feature | bugfix | refactor | tooling | docs | research
 {ACTIVE_STEPS} = [0, 1, 6, 7, 8]  # example for S
 {TIME_BUDGET} = { requirements: 2, planning: 0, implementation: 10, qe: 3 }
 {DIMENSION_SCORES} = { files: 1, domains: 1, integrations: 1, breaking: 1, models: 1, crosscutting: 1 }
 {LEARNED_PATTERNS} = [ ... ]  # top-3 by confidence from memory_query; [] in reference mode / no hits / error
 ```
 
-Create artifact: `features/<slug>/00_complexity_assessment.md`
+Create artifact: `features/<slug>/00_complexity_assessment.md`, including the `Task kind: <x>` line.
 
 ## Checkpoint 0 Format
 

package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md

@@ -127,7 +127,9 @@ For each group, identify:
 
 Before finalizing the plan, validate completeness:
 
-1. Cross-reference every `{REQUIREMENT}` (FR-N) → at least one TASK covers it
+1. Cross-reference every `{REQUIREMENT}` (FR-N) → at least one TASK covers it (C8 — the gate checks
+   this by identifier: WARN with a count by default, FAIL under `--require-requirements`, which the
+   pipeline passes)
 2. Cross-reference every `{ADR_DECISION}` → at least one TASK implements it
 3. Cross-reference every critical risk from `{QUALITY_RISKS}` → mitigation in some TASK
 4. Name every acid token `A<n>` from `00_complexity_assessment.md` VERBATIM in the plan (C4), each
@@ -233,11 +235,16 @@ C2 recognises JS/TS, pytest, Go, Rust, JVM and .NET test paths, extensible per p
 
 Never proceed on a non-zero exit, and never treat empty output as a pass — the last line
 (`K2 plan-completeness: PASS|FAIL|NOT-ESTABLISHED`) is the verdict, and its absence is not one.
-What it checks: C1 every ADR has a plan task citing it · C2 every ADR Confirmation test path is named
-in the plan · C3 the `EXPECTED_CODE_TARGETS:` block parses line by line · C4 the feature's declared
-acid corpus is named · C5 (WARN) the `Inputs read:` line. An S-tier run with no `03_adr/` skips C1/C2
-with a note (it cannot be failed for ADRs it never had) — unless the plan itself cites `ADR-<n>`,
-which is NOT-ESTABLISHED. C1 is a grep: it catches "forgot entirely", not "mentioned but not tasked".
+What it checks: C1 every ADR **decision** (a `# ADR-NNN` / `## ADR-NNN` heading INSIDE the file, not
+just the filename prefix — a file with several headings owes several plan citations) has a plan task
+citing it · C2 every ADR Confirmation test path is named in the plan · C3 the `EXPECTED_CODE_TARGETS:`
+block parses line by line · C4 the feature's declared acid corpus is named · C5 (WARN) the
+`Inputs read:` line · C8 every requirement id declared in `01_requirements.md` (`FR-N`, `NFR-N`,
+`AC-N`, `C-N`) is cited by the plan by word boundary — WARN with a count by default, FAIL per missing
+id under `--require-requirements` (the pipeline passes this flag; a bare interactive run of the
+script does not). An S-tier run with no `03_adr/` skips C1/C2 with a note (it cannot be failed for
+ADRs it never had) — unless the plan itself cites `ADR-<n>`, which is NOT-ESTABLISHED. C1 is a grep:
+it catches "forgot entirely", not "mentioned but not tasked".
 
 Pass the run's tier so the check cannot be dodged: `--tier=S|M|L|XL`. An M/L/XL feature with no
 `03_adr/` FAILS C1/C2 (an M+ feature owes ADRs); only `--tier=S` — or no tier at all, and then the

package/templates/.claude/skills/feature-adr/modules/07-code.md

@@ -20,6 +20,7 @@ opus (complex code generation)
 - `{ADR_DECISIONS}` from Step 3 (M+)
 - `{DOMAIN_MODEL}` from Step 4 (L/XL)
 - Codebase context (existing patterns, conventions)
+- {LEARNED_PATTERNS} for Step 7 — the decision-recall block (≤3 lessons), appended to the coder prompt by the pipeline
 
 ## Protocol
 

package/templates/.claude/skills/feature-adr/modules/08-qe.md

@@ -311,6 +311,51 @@ Compile all findings into a structured report:
 ✅ READY FOR MERGE | ❌ NEEDS FIXES | ⚠️ CONDITIONAL APPROVAL
 ```
 
+### 7.1 Findings ledger (machine-readable)
+
+Prose is for people; `dz score`/`dz recap` need a machine-readable surface too (qe-findings-record,
+ADR-001). Write BOTH of these into `08_qe_report.md`, in addition to the prose report above:
+
+1. Exactly ONE line, in the PROSE body of the file (never inside a fenced code block, an indented
+   code block, a `>` blockquote, or an HTML comment — the parser masks all four before it looks):
+   `QE-VERDICT: <A|A-|A+|B|B+|B-|C|C+|C-|D>` — the letter grade you gave above, machine-parseable,
+   ASCII hyphen for the sign (the parser also accepts U+2212 as the same sign; write ASCII). Two such
+   lines make the report `ambiguous`, never "last wins" — write it once. A line that starts with
+   `QE-VERDICT` but gets the grammar wrong (wrong dash, trailing prose, wrong case, no colon) is worse
+   than writing nothing: the parser reports `invalid` and REFUSES to fall back to guessing a grade
+   from prose — get the one line right rather than close.
+2. A `## Findings ledger` section — this exact heading, occurring EXACTLY ONCE in the file, at the
+   top level (never inside a fence/indented block/blockquote/comment either) — with a table directly
+   under it, under this EXACT header (copy it verbatim):
+
+```markdown
+## Findings ledger
+
+| Finding | Severity | Status | Round | Author | Title |
+|---------|----------|--------|-------|--------|-------|
+| F1 | HIGH | fixed | 1 | codex | escaping bug in the token scanner |
+| F2 | MEDIUM | open | 1 | lead | style nit, not blocking |
+```
+
+A table found ANYWHERE else — before the heading, after the section ends at the next heading, with
+no heading in the file, or with the heading duplicated — is REFUSED as `outside ledger section`,
+never parsed as the real ledger; a second table found INSIDE the section is REFUSED as `duplicate
+table`. Both refusals name how many of the rejected table's rows were ignored.
+
+Closed dictionaries — a row using anything else is REFUSED by the parser, never coerced to the
+nearest known value:
+- **Severity**: `BLOCKER` `CRITICAL` `HIGH` `MEDIUM` `LOW` `INFO`
+- **Status**: `confirmed` `fixed` `partial` `refuted` `named-limit` `open`
+- **Round**: an integer ≥ 1 (which review round raised it)
+- **Author**: `codex` `claude` `lead`
+- **Finding**: a short id token with no spaces (`F1`, `R2-3`, …); **Title**: free text — a literal
+  `|` inside Title must be escaped as `\|`, or wrapped in inline code (`` `a|b` ``), or it fragments
+  the row into extra columns and the row is refused as malformed.
+
+An empty (header-only) table is read as `hollow: true` — worse than no table at all, because it
+claims a ledger exists and says nothing. If there are no findings, omit the section entirely rather
+than writing an empty table.
+
 ### 8. QE Pattern Store (Direct Mode only)
 
 When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, after the gap loop is closed and the verdict is set:

package/templates/.claude/skills/feature-adr/scripts/check-plan-completeness.mjs

@@ -3,10 +3,14 @@
 // Generalized from features/wave1-instrument-repair/check-plan-completeness.mjs (that copy is the
 // historical artifact of its run and stays untouched); this one is parameterized by feature dir.
 //
-// USAGE:  node .claude/skills/feature-adr/scripts/check-plan-completeness.mjs [<feature-dir>] [--tier=M] [--acid=A1,A2]
+// USAGE:  node .claude/skills/feature-adr/scripts/check-plan-completeness.mjs [<feature-dir>] [--tier=M] [--acid=A1,A2] [--require-requirements]
 //         <feature-dir> defaults to the current working directory.
 //         --tier=S|M|L|XL closes the ADR-less dodge (see S-TIER HONESTY); omitting it keeps the
 //         heuristic, and the skip note then names the dodge out loud.
+//         --require-requirements promotes C8 (below) from a WARN-with-count to a per-id FAIL; the
+//         pipeline passes this flag, so the check is introduced two-shot (ADR-001 plan-inherits-
+//         requirements): WARN first so the corpus can be measured without repainting every green
+//         fixture red, FAIL once the planner prompt names the contract (feature-adr.js Step 6).
 //
 // VERDICT CONTRACT (unchanged from the proven copy — never a silent pass):
 //   PASS            exit 0   last line: `K2 plan-completeness: PASS (...)`
@@ -21,6 +25,12 @@
 // 3dbd2851-adjacent) must parse task structure. Kept honest here: C1 catches "forgot entirely",
 // not "mentioned but not tasked".
 //
+// KNOWN LIMITATION (fix round 1, 2026-09-16, same class as C1 above): C8 is also a grep — a PROSE
+// mention of "FR-3" satisfies it exactly like a task reference. Kept honest here too: C8 catches
+// "forgot entirely", not "mentioned but not tasked". Masking the PLAN side (not just the 01/ADR
+// side) for C1 and C8 together, so a prose mention stops satisfying either check, is a separate
+// backlog item — filed by the lead, not chased here.
+//
 // Checks:
 //  C1  every ADR file in 03_adr/ has >=1 task line in 06_implementation_plan.md citing it (ADR-00N)
 //  C2  every Confirmation-numbered check in each ADR is named in the plan (by its test-file path)
@@ -29,6 +39,23 @@
 //      — SFDIPOT condition: line-level validation, reject-with-reason, not just block presence
 //  C4  the plan names the feature's OWN acid corpus (see "acid corpus" below)
 //  C5  the plan has an 'Inputs read:' line naming 03_adr, 05_architecture (wave-2 seam, cheap here)
+//  C8  every requirement id DECLARED in 01_requirements.md (FR-N, NFR-N, AC-N, C-N, with an optional
+//      letter group FR-AN and an optional fraction FR-N.N) is CITED by the plan, by word boundary —
+//      set difference over identifiers, exactly like C1, never text similarity. WARN with a count by
+//      default; FAIL per missing id under --require-requirements (see USAGE above). 01 absent or
+//      declaring no ids in the four contract shapes ⇒ WARN, same honesty discipline as C4's absent
+//      00_complexity_assessment.md.
+//      NAMED LIMIT (C-1, measured over 394 corpus files 2026-09-16): forms outside FR|NFR|AC|C — bare
+//      `RN`/`QN` registries, an id with no hyphen (`FR1`) — are NOT caught. Minority forms in the
+//      corpus; widening the regex "just in case" would manufacture false WARN/FAIL on real plans, so
+//      the limit is named here rather than chased.
+//      NAMED LIMIT (fix round 1, 2026-09-16): the `C-N` shape is read as a Constraint requirement id
+//      by this regex — the repo convention this gate trusts. A defect table uses `D-N` (`| D1 |`),
+//      never `C-N`; a table of open defects mislabeled with `C-N` rows would be misread as
+//      requirement ids. That is a corpus-naming-convention limit, not a bug this gate works around.
+//      Declared ids are read from 01 THROUGH `maskMarkdown` (fenced code and HTML comments stripped
+//      first, same reader C6 already uses below), so an id quoted inside an example or a comment is
+//      never mistaken for a declaration.
 //
 // S-TIER HONESTY (no 03_adr/): an S-tier run legitimately has no ADR files, and forcing it to fail a
 // plan gate it can never satisfy would make the gate a nuisance to route around. So:
@@ -60,9 +87,11 @@ const acidArg = argv.find((a) => a.startsWith('--acid='));
 const tierArg = argv.find((a) => a.startsWith('--tier='));
 const TIER = tierArg ? tierArg.slice('--tier='.length).trim().toUpperCase() : null;
 const TIER_REQUIRES_ADR = TIER === 'M' || TIER === 'L' || TIER === 'XL';
+const REQUIRE_REQUIREMENTS = argv.includes('--require-requirements');
 const dirArg = argv.find((a) => !a.startsWith('--'));
 const FDIR = resolve(dirArg && dirArg !== '' ? (isAbsolute(dirArg) ? dirArg : join(process.cwd(), dirArg)) : process.cwd());
 const planPath = join(FDIR, '06_implementation_plan.md');
+const requirementsPath = join(FDIR, '01_requirements.md');
 const adrDir = join(FDIR, '03_adr');
 const complexityPath = join(FDIR, '00_complexity_assessment.md');
 
@@ -78,6 +107,23 @@ const out = (s) => console.log(s);
 const notEstablished = (why) => { out(`K2 plan-completeness: NOT-ESTABLISHED — ${safe(why)}`); process.exit(3); };
 let failures = [], warnings = [], skips = [];
 
+// Lead delta after Codex rounds 2+3 (2026-09-16, plan-inherits-requirements): on the DECLARATION side
+// (01_requirements.md ids, ADR headings) an UNCLOSED fence is AMBIGUOUS INPUT — CommonMark reads it as
+// code to EOF, a human reads it as prose that forgot a backtick. Round 2 measured that masking it
+// silently DROPPED every id after it (FR-2 vanished, no line said so); round 3 showed that restoring
+// it silently ESTABLISHED a heading that was only example code. Neither silent reading is honest, so
+// the gate does what it does for every other input it cannot read: NOT-ESTABLISHED, naming the file —
+// "close the fence" is a one-character fix, and the corpus has ZERO such files today (MEASURED
+// 2026-09-16 11:58 UTC over 831 requirements/ADR files). The detector is the two masking modes
+// disagreeing: an unclosed fence with an empty or whitespace-only tail changes no id and needs no
+// verdict — a NAMED LIMIT of the proxy, not a gap in it.
+function maskDeclarations(text, label) {
+  const strict = maskMarkdown(text, { unclosed: 'mask' });
+  const restored = maskMarkdown(text, { unclosed: 'restore' });
+  if (strict !== restored) notEstablished(`${label} has an UNCLOSED code fence — an ambiguous declaration input establishes nothing (close the fence and rerun)`);
+  return strict;
+}
+
 if (!existsSync(FDIR)) notEstablished(`feature dir absent: ${FDIR}`);
 if (!existsSync(planPath)) notEstablished('06_implementation_plan.md absent');
 const plan = readFileSync(planPath, 'utf-8');
@@ -166,9 +212,35 @@ if (adrFiles.length === 0 && TIER_REQUIRES_ADR) {
   skips.push(`C1: no 03_adr/ and the plan claims no ADR work — ADR-coverage check SKIPPED${TIER === 'S' ? ' (--tier=S, the legitimate S-tier shape)' : ' (NO --tier supplied: an M/L/XL run that simply never wrote 03_adr/ would dodge C1/C2 here — pass --tier to close it)'}`);
   skips.push('C2: no 03_adr/ — Confirmation-test coverage check SKIPPED');
 } else {
-  // C1 — ADR ids referenced by plan tasks
+  // C1 — ADR ids referenced by plan tasks (FR-4). Decisions are counted by HEADING inside the file
+  // (`# ADR-NNN` / `## ADR-NNN`, multiline), not by the filename prefix: a file named `001-004-*.md`
+  // that actually contains four decisions used to be checked as ONE. A file with no such heading
+  // falls back to the old filename-prefix path, WARNed so the fallback is never silent.
+  // Fix round 1 (2026-09-16): the file is read THROUGH `maskMarkdown` first (fenced code and HTML
+  // comments blanked, positions preserved) — a heading printed inside a ```-fenced example is not a
+  // real decision. Up to 3 leading spaces of indentation are tolerated (CommonMark's own limit for a
+  // line to still be a heading; 4+ spaces is indented code and is already blanked by the mask).
+  // NAMED LIMIT: a nested `### ADR-002` heading cited INSIDE ADR-001's own file as a cross-reference
+  // (rather than living in ADR-002's own file) is still counted as a decision owed a task — a corpus
+  // rarity, and telling "own decision" from "cross-reference" needs semantic parsing, the same class
+  // of limit the C1 grep above already accepts.
+  const ADR_HEADING_RE = /^ {0,3}#{1,6}\s*ADR-(\d+)\b/gm;
   for (const f of adrFiles) {
+    let adrTextForHeadings = null;
+    try { adrTextForHeadings = maskDeclarations(readFileSync(join(adrDir, f), 'utf-8'), `C1: ${safe(f)}`); } catch { adrTextForHeadings = null; }
+    const headingNums = adrTextForHeadings === null
+      ? []
+      : [...new Set([...adrTextForHeadings.matchAll(ADR_HEADING_RE)].map((mm) => mm[1]))];
+    if (headingNums.length > 0) {
+      for (const n of headingNums) {
+        const id = `ADR-${n}`;
+        const re = new RegExp(`ADR-0*${Number(n)}\\b`);
+        if (!re.test(plan)) failures.push(`C1: ${id} (${safe(f)}) has NO task in the plan referencing it`);
+      }
+      continue;
+    }
     const m = f.match(/^(\d{3})-/); if (!m) { warnings.push(`C1: unparseable ADR filename ${safe(f)}`); continue; }
+    warnings.push(`C1: ${safe(f)} has no ADR-NNN heading — falling back to the filename prefix`);
     const id = `ADR-${m[1]}`;
     const re = new RegExp(`ADR-0*${Number(m[1])}\\b`);
     if (!re.test(plan)) failures.push(`C1: ${id} (${safe(f)}) has NO task in the plan referencing it`);
@@ -432,6 +504,42 @@ else for (const t of acidTokens) if (!new RegExp(`\\b${t.replace(/[.*+?^${}()|[\
   }
 }
 
+// ── C8 requirement-id coverage (FR-1/2/3, ADR-001 plan-inherits-requirements) ───────────────────
+// Set difference over IDENTIFIERS, exactly like C1 — never text similarity. Declared id forms are
+// measured from the corpus (see the USAGE-block comment above for the named C-1 limit): `FR-N`,
+// `NFR-N`, `AC-N`, `C-N`, an optional letter group (`FR-AN`) and an optional fraction (`FR-N.N`),
+// declared at the START of a line as a heading, a bold run, a list item, or a table cell.
+{
+  const REQ_ID_DECL_RE = /^\s*(?:#{1,6}\s*|[-*]\s+|\|\s*)?\**\s*((?:FR|NFR|AC|C)-[A-Z]?\d+(?:\.\d+)?)\b/gm;
+  const escapeReqId = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  if (!existsSync(requirementsPath)) {
+    warnings.push('C8: 01_requirements.md is ABSENT — requirement coverage had no input to read');
+  } else {
+    // Fix round 1 (2026-09-16): masked THROUGH maskMarkdown first, exactly like C1's heading scan —
+    // an id inside a ```-fenced example or an HTML comment is not a declaration.
+    const requirementsText = maskDeclarations(readFileSync(requirementsPath, 'utf-8'), 'C8: 01_requirements.md');
+    const reqIds = [...new Set([...requirementsText.matchAll(REQ_ID_DECL_RE)].map((mm) => mm[1]))];
+    if (reqIds.length === 0) {
+      warnings.push('C8: 01_requirements.md declares NO requirement ids in the contract shapes (FR-N / NFR-N / AC-N / C-N at line start) — nothing to cover');
+    } else {
+      const missing = reqIds.filter((id) => !new RegExp('\\b' + escapeReqId(id) + '\\b').test(plan));
+      if (missing.length === 0) {
+        // Silence is not a verdict (K7): a check that ran and found nothing wrong must still print,
+        // or a reader cannot tell "C8 ran clean" from "C8 never ran". Deliberately NOT a PASS/FAIL/
+        // NOT-ESTABLISHED word — parsePlanGateVerdict anchors on the LAST such word, and a stray one
+        // mid-stream is exactly the G-F1 forgery class this script's `safe()` already defends against.
+        out(`NOTE  C8: all ${reqIds.length} requirement ids referenced`);
+      } else if (REQUIRE_REQUIREMENTS) {
+        for (const id of missing) failures.push(`C8: ${id} (01_requirements.md) is not referenced by the plan`);
+      } else {
+        const shown = missing.slice(0, 12);
+        const more = missing.length > 12 ? `, …and ${missing.length - 12} more` : '';
+        warnings.push(`C8: ${missing.length} of ${reqIds.length} requirement ids are not referenced by the plan: ${shown.join(', ')}${more}`);
+      }
+    }
+  }
+}
+
 // C5 — Inputs read line
 if (!/Inputs read:/i.test(plan)) warnings.push('C5: no "Inputs read:" line (wave-2 seam, WARN only)');
 else for (const need of ['03_adr','05_architecture']) if (!plan.includes(need)) warnings.push(`C5: Inputs read line missing ${need}`);