@dzhechkov/skills-feature-adr 1.5.11 → 1.5.12

package/.dz-manifest.json

@@ -13,7 +13,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "889d62c5dfafb53c0664867f0882e5712e47eb8aa7a44c6db46d082e693ed58d"
+        "sha256": "e72e7ae2a5adc046598feb5de0bcac114d5aa961571f57d2aa530186c1dbb4b3"
       },
       {
         "path": "bin/cli.js",
@@ -25,7 +25,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "d13930ae60a1d849d08b798dbb3b3ed4fb5d0b50c4c3910fc76a455dd9e6ce31"
+        "sha256": "8b0f75ec75e5f2a4e121c65a625abe6c9a8fb4b12732349293b78232348b2234"
       },
       {
         "path": "src/cli.js",
@@ -121,7 +121,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",
@@ -149,15 +149,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",
@@ -249,7 +249,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",
@@ -317,7 +317,7 @@
       },
       {
         "path": "templates/.claude/workflows/feature-adr.js",
-        "sha256": "22416f105c1b988c07f6cb9002a507b54b07842b5b4bb109b7e300ff52272603"
+        "sha256": "8900ff6bc777a078aa4e37d8e28a2ffbc612187354995f726daf93e6f87d3109"
       },
       {
         "path": "templates/lib/memory-protocol.md",
@@ -329,5 +329,5 @@
       }
     ]
   },
-  "signature": "WT7wArJY3aKuIMMVgbBzFO+Rqw7qfcaVh8UQ9MENSltqdTJTFAr/0TBOS5A89UAfczkluCrkTtyUvPOTQvaNCw=="
+  "signature": "lPrCKcYVN87Vvd2+Xm6HFSVQdv8eu1AXQ1yGKm42Vad53oNafZvw3gF50Jm4pG1FkKd9vJ1SH/0zHJVNZi9bAQ=="
 }

package/README.md

@@ -1179,6 +1179,64 @@ pre-code probe that returns nothing no longer becomes an all-null baseline that
 "every target changed".
 
 
+`next` — **the plan inherits requirements by contract, not by goodwill** (feature `plan-inherits-requirements`,
+staged: not yet versioned or published). Two swarms plus a cross-family check measured that the implementation
+plan referenced only 95 of 339 requirement ids across 8 M/L features (28 %), lost one requirement without a trace
+and introduced one contradiction, while the norm "every FR-N → a task" lived only in the module text — neither
+the planner prompt nor the K2 gate enforced it. Now:
+
+- **C8 — requirement coverage.** The K2 gate reads `01_requirements.md`, extracts every id declared at line start
+  in the four corpus shapes (heading / bold / list / table; `FR-N`, `NFR-N`, `AC-N`, `C-N`, with an optional
+  letter group and dotted sub-number — measured over 394 requirement files) and checks each by word boundary in
+  the plan. By default a WARN with the exact count; under `--require-requirements` (which the pipeline passes)
+  every missing id is its own FAIL line. An absent `01_requirements.md` is a WARN naming the absence, never a
+  skip; a file declaring no ids in the contract shapes says so. NAMED LIMIT, in the same form as C1's: C8 is a
+  grep — a prose mention satisfies it; "mentioned but not tasked" is not caught.
+- **C1 counts decisions by heading, not by filename.** `# ADR-NNN` / `## ADR-NNN` headings inside each ADR file
+  are the decisions the plan owes a task; a file holding four decisions now yields four checks, not one. No
+  heading ⇒ filename prefix with a WARN.
+- **An unclosed code fence on the declaration side is NOT-ESTABLISHED.** Masking it silently dropped every id
+  after it (measured); restoring it silently established a heading that was only example code. Neither silent
+  reading is honest, so the gate refuses with the file named — close the fence, rerun. The corpus has 0 such
+  files out of 831.
+- **The Step-6 planner is told the inputs by NAME** (`01_requirements.md`, every `03_adr/*.md`,
+  `05_architecture.md`, `03.5_ideation_report.md` / `04_domain_model.md` when present) and the C8 contract in the
+  same clause as C1/C2/C4 — the lesson that a gate whose contract is not named in the authoring prompt produces
+  refusal after refusal.
+- **ONE automatic repair round.** A genuine script-verdict FAIL re-dispatches the planner with the FAIL lines
+  ("close EXACTLY these gaps, keep everything else"). Because that sentence is a prompt and not a guarantee, the
+  round is bracketed: the plan is backed up first (no backup ⇒ no repair; a stale `.pre-repair` or a symlinked
+  plan refuses), snapshots before/after compare byte length, every `EXPECTED_CODE_TARGETS` line and every task
+  heading line WITH multiplicity, a snapshot that did not complete REJECTS (never fails open), the re-gate runs
+  before the backup is archived, and a rejected or still-failing repair is restored from the backup with the
+  restore PROVEN by POSIX `cksum` + length. `planGateAttempts` counts gate runs; `planRepair` carries the
+  outcome; a `plan-repair` ledger row is written either way. NAMED LIMIT: task bodies are not proven preserved
+  by any metric — a repair that keeps every heading, every target and 80 % of the bytes while gutting prose is
+  undetectable by construction.
+- The pure halves (`shellQuote`, `planBackupCmd`, `planRestoreCmd`, `planArchiveBackupCmd`, `planSnapshotCmd`,
+  `snapshotBlock`, `snapshotNumber`, `parsePlanSnapshot`) live in `@dzhechkov/harness-core` and are body-pinned
+  against the inline copies by the drift guard. Three Codex review rounds (C, C, D) — every finding either fixed
+  or named above; the full account is in `features/plan-inherits-requirements/08_qe_report.md`.
+
+Also staged: **the coder now gets the same recall lane the planner already had** (feature
+`coder-reads-and-recall`). `1.5.9` wired advisory decision-point micro-recall into Step 3 (ADR
+selection) and Step 6 (plan routing) only — Step 7 (Code) never called `prepareDecisionRecall` at
+all, so any lesson reaching the coder was a night-shift human pasting it into the brief by hand.
+`drDecisionShape` now knows a third decision kind, `code-implementation` → `step-7` /
+`feature-adr-decision-code-implementation`, kept apart from the plan's own `step-6` bandit context.
+The call sits INSIDE the code stage's checkpoint, before any of the three places that read the
+coder's prompt (the Claude dispatch, the Codex dispatch, and the training-pair capture) — so a
+resumed stage neither re-spends the recall nor loses it, and all three see the identical
+recall-augmented text. Separately measured (Step 0 of this feature, instrument: host workflow
+records → the coding-stage agent's own tool-call transcript): a comment added 24.08 naming the plan,
+every ADR, the architecture doc, requirements and the domain model by file name moved how often
+Claude-family coders opened `01_requirements.md` from 39 % (11 of 28 runs) before the change to 71 %
+(5 of 7) after — a real jump, but on **n = 7**, not a controlled comparison, and it says nothing
+about Codex-family coders: they were 77 % of the post-change sample and are invisible to this
+instrument (a Codex coder's transcript carries exactly one entry, the dispatch itself). Full method,
+the two false reads caught before the number was trusted, and the raw counts are in
+`features/coder-reads-and-recall/00_complexity_assessment.md`.
+
 `1.5.3` — **the workflow stops crashing on the way into Step 7.** `1.5.2` shipped a workflow that
 CALLED three helpers it never defined — `changeSetProbeCmd`, `parseHashProbe`, `changedFromHashes`
 (5 call sites, 0 definitions). `QE_SCOPE` defaults to `uncommitted`, so the guarded branch was true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.5.11",
+  "version": "1.5.12",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"
@@ -15,6 +15,10 @@
     ".dz-manifest.json",
     "sbom.json"
   ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "prepack": "node -e \"const fs=require('fs');const bad=['.claude','.skills-feature-adr.json'].filter(p=>fs.existsSync(p));if(bad.length){console.error('prepack guard: stray init artifacts in package dir: '+bad.join(', ')+' — remove before packing');process.exit(1)}\""
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -59,8 +63,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "node --test \"test/**/*.test.js\""
   }
-}
+}

package/sbom.json

@@ -35,7 +35,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "889d62c5dfafb53c0664867f0882e5712e47eb8aa7a44c6db46d082e693ed58d"
+          "content": "e72e7ae2a5adc046598feb5de0bcac114d5aa961571f57d2aa530186c1dbb4b3"
         }
       ]
     },
@@ -69,7 +69,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "d13930ae60a1d849d08b798dbb3b3ed4fb5d0b50c4c3910fc76a455dd9e6ce31"
+          "value": "8b0f75ec75e5f2a4e121c65a625abe6c9a8fb4b12732349293b78232348b2234"
         }
       ]
     },
@@ -309,7 +309,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a1275bd960ddff1c61352f96d8b7a4249371190766f08d1778f5a54f98350950"
+          "content": "6a98ca7af49aabcb2e14a081815f1167740ac4dba2e0cbb938c87aceac47bfa3"
         }
       ]
     },
@@ -379,7 +379,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c624e0ade0314ca07913ba64e092d4655f86201856e8188c3e616b2320226c1e"
+          "content": "5c8d4c79d5329702b8c75b9afb36ae335aa63c99e74045c0afa98e12658ee975"
         }
       ]
     },
@@ -389,7 +389,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c427a0abacb4bc1d969d9f47739ce2aeff286a66da73eab67bf042d5c4dc9a59"
+          "content": "fb054591e86d55cee184eab96b5f0440053ada8fa9edf619e4a66ec5ac371587"
         }
       ]
     },
@@ -399,7 +399,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ea8fb546acb7f09816d2fc9f9189a86f2400b8cec91c9ba4b82b68a8e32920bb"
+          "content": "7973676cc9a5a6d8429c0bcdbe163bb5dc16e2d2f28a72698e44ad72d234e199"
         }
       ]
     },
@@ -629,7 +629,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cbe70a524f6ce7987b5e3961ee412b92c24c00d84066d438c759659d656efaa2"
+          "content": "08e69d2e63350fe2dc64483226fcd30901b77a8e930ca6280ef71181c67675b4"
         }
       ]
     },
@@ -799,7 +799,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "22416f105c1b988c07f6cb9002a507b54b07842b5b4bb109b7e300ff52272603"
+          "content": "8900ff6bc777a078aa4e37d8e28a2ffbc612187354995f726daf93e6f87d3109"
         }
       ]
     },

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}`);