@dzhechkov/p-replicator 1.13.1 → 1.13.2

package/templates/.claude/commands/feature.md

@@ -133,6 +133,17 @@ Run validation against INVEST + SMART + BDD scenario completeness.
 
 Output: `docs/features/<feature>/validation-report.md`
 
+The report carries the `Spec revision:` line and the `## Criterion scenarios` table (AC id → BDD
+scenario) in the exact format of
+`.claude/skills/requirements-validator/references/feature-report-contracts.md`. Then run:
+
+```bash
+bash "$CHECK_PIPELINE_GAPS" "${CLAUDE_PROJECT_DIR:-.}" --report-revision --criterion-scenarios
+```
+
+Same exit semantics as the Phase 1 gate: `0` advances; `1` (stale revision, AC id without a scenario
+row) returns to Phase 2; `2` stops.
+
 ### Phase 3: IMPLEMENT (parallel agents)
 
 1. Read SPARC docs from Phase 1
@@ -178,11 +189,39 @@ substantive, post-launch file with a terminal status. Narrative/chat/silence is
 invalid receipt MUST block merge/completion. Full rule and bounded exception:
 `.claude/rules/swarm-file-evidence.md`.
 
+#### Threshold tests pin the number (layer-2 rule)
+
+A test of a THRESHOLD asserts the literal number; a test of a DERIVED value calls the production
+implementation. A test that computes its expectation from the production constant is green for any
+value and proves nothing.
+
+#### Blocking criterion-coverage gate
+
+`05_completion.md` MUST carry the `## Criterion coverage` table (AC id → test file → test title; format
+in `feature-report-contracts.md`). At the end of Phase 3 run:
+
+```bash
+bash "$CHECK_PIPELINE_GAPS" "${CLAUDE_PROJECT_DIR:-.}" --completion
+```
+
+`0` advances; `1` (an AC without a test, a row whose file or title does not exist) returns to
+Phase 3; `2` stops. Never downgrade either non-zero status to a warning.
+
 ### Phase 4: REVIEW (brutal-honesty-review)
 
 Read: `.claude/skills/brutal-honesty-review/SKILL.md`
 
-Findings classified by severity. Critical (blocker | high) MUST be fixed.
+Specification contract: the review receives `01_specification.md` + `validation-report.md` (a review
+not given the specification is incomplete by construction and says so) and writes
+`docs/features/<feature>/review-report.md` — `Reviewer family:` (disclosure) and `Spec revision:` in the
+first 20 lines, an AC-by-AC `## Spec conformance` table — per `feature-report-contracts.md`. Then run:
+
+```bash
+node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/check-review-contract.cjs" "${CLAUDE_PROJECT_DIR:-.}" "<feature>"
+```
+
+`0` advances; `1` (named contract gaps) returns to Phase 4; `2` stops. Findings classified by
+severity. Critical (blocker | high) MUST be fixed.
 
 ## Final Steps
 
@@ -196,8 +235,11 @@ Skip per-phase user confirmations. Auto-decisions:
 - Phase 1: proceed if all docs exist
 - Phase 1 traceability: proceed only when `check-pipeline-gaps.sh` exits `0`; preserve exit `1`/`2`
 - Phase 2: proceed if 🟢 or 🟡; auto-retry once on 🔴
+- Phase 2 report revision + criterion scenarios: proceed only when `--report-revision --criterion-scenarios` exits `0`; preserve exit `1`/`2`
 - Phase 3: proceed if tests + lint + build green
+- Phase 3 criterion coverage: proceed only when `--completion` exits `0`; preserve exit `1`/`2`
 - Phase 4: auto-fix `high` if straightforward; halt on `blocker`
+- Phase 4 review contract: proceed only when `check-review-contract.cjs` exits `0`; preserve exit `1`/`2`
 
 ## Related
 

package/templates/.claude/hooks/check-review-contract.cjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Validate the feature review's binding to the specification it judged.
+ *
+ * Usage: node check-review-contract.cjs <project-root> <feature-slug>
+ * Exit 0: contract passes; 1: named contract gaps; 2: inputs could not be established.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const AC_ID_SOURCE = 'AC-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*-[0-9]+';
+const AC_HEADING = new RegExp('^###\\s+(' + AC_ID_SOURCE + ')(?:\\s|$)');
+const FAMILIES = new Set(['claude', 'codex', 'human', 'unknown']);
+const VERDICTS = new Set(['met', 'not met', 'unverifiable']);
+
+function say(line) { process.stdout.write(line + '\n'); }
+
+function cannotCheck(reason) {
+  say('NOT-ESTABLISHED review contract: ' + reason);
+  process.exit(2);
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== '' && relative !== '..' && !relative.startsWith('..' + path.sep)
+    && !path.isAbsolute(relative);
+}
+
+function projectRoot(input) {
+  let root;
+  try { root = fs.realpathSync(path.resolve(input)); } catch (error) {
+    cannotCheck('project root is missing or unreadable: ' + ((error && error.message) || error));
+  }
+  let stat;
+  try { stat = fs.statSync(root); } catch (error) {
+    cannotCheck('project root cannot be inspected: ' + ((error && error.message) || error));
+  }
+  if (!stat.isDirectory()) cannotCheck('project root is not a directory: ' + root);
+  return root;
+}
+
+function safeRead(root, relative, label) {
+  const candidate = path.resolve(root, relative);
+  if (!isInside(root, candidate)) cannotCheck(label + ' escapes the project root: ' + relative);
+
+  let current = root;
+  const parts = path.relative(root, candidate).split(path.sep);
+  for (let index = 0; index < parts.length; index++) {
+    current = path.join(current, parts[index]);
+    let stat;
+    try { stat = fs.lstatSync(current); } catch (error) {
+      cannotCheck(label + ' is missing or unreadable: ' + current + ' ('
+        + ((error && error.message) || error) + ')');
+    }
+    if (stat.isSymbolicLink()) cannotCheck(label + ' is a symlink: ' + current);
+    if (index < parts.length - 1 && !stat.isDirectory()) {
+      cannotCheck(label + ' has a non-directory path component: ' + current);
+    }
+    if (index === parts.length - 1) {
+      if (!stat.isFile()) cannotCheck(label + ' is not a regular file: ' + current);
+      if ((stat.mode & 0o444) === 0) cannotCheck(label + ' is unreadable: ' + current);
+    }
+  }
+
+  let real;
+  try { real = fs.realpathSync(candidate); } catch (error) {
+    cannotCheck(label + ' cannot be resolved: ' + ((error && error.message) || error));
+  }
+  if (!isInside(root, real)) cannotCheck(label + ' resolves outside the project root: ' + real);
+
+  try { return fs.readFileSync(real); } catch (error) {
+    cannotCheck(label + ' is unreadable: ' + ((error && error.message) || error));
+  }
+}
+
+function specificationIds(buffer) {
+  const lines = buffer.toString('utf8').split(/\n/).map((line) => line.replace(/\r$/, ''));
+  const ids = [];
+  let fence = '';
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const marker = line.trimStart().match(/^(```|~~~)/);
+    if (marker) {
+      if (!fence) fence = marker[1][0];
+      else if (marker[1][0] === fence) fence = '';
+      continue;
+    }
+    if (fence) continue;
+    if (!/^###\s+AC-/.test(line)) continue;
+    const match = line.match(AC_HEADING);
+    if (!match) cannotCheck('malformed AC heading at specification line ' + (index + 1));
+    ids.push(match[1]);
+  }
+  if (fence) cannotCheck('specification has an unclosed fenced code block');
+  const duplicate = [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))];
+  if (duplicate.length) cannotCheck('specification has duplicate AC id: ' + duplicate.join(', '));
+  return ids;
+}
+
+function reportRows(lines, gaps) {
+  const section = lines.findIndex((line) => line.trim() === '## Spec conformance');
+  if (section < 0) {
+    gaps.push('GAP Spec conformance section missing');
+    return [];
+  }
+
+  let header = -1;
+  for (let index = section + 1; index < lines.length; index++) {
+    if (/^##\s+/.test(lines[index])) break;
+    if (lines[index].trim() === '| Criterion | Verdict | Evidence |') {
+      header = index;
+      break;
+    }
+  }
+  if (header < 0 || !/^\|\s*-+\s*\|\s*-+\s*\|\s*-+\s*\|$/.test((lines[header + 1] || '').trim())) {
+    gaps.push('GAP Spec conformance table missing or malformed');
+    return [];
+  }
+
+  const rows = [];
+  for (let index = header + 2; index < lines.length; index++) {
+    const line = lines[index];
+    if (!line.trim()) break;
+    if (/^##?\s+/.test(line)) break;
+    if (!line.trimStart().startsWith('|')) break;
+    const match = line.match(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|\s*$/);
+    if (!match) cannotCheck('malformed Spec conformance row at report line ' + (index + 1));
+    rows.push({ id: match[1].trim(), verdict: match[2].trim(), evidence: match[3].trim() });
+  }
+  return rows;
+}
+
+function validateReport(specification, report, slug) {
+  const ids = specificationIds(specification);
+  const idSet = new Set(ids);
+  const lines = report.toString('utf8').split(/\n/).map((line) => line.replace(/\r$/, ''));
+  const firstTwenty = lines.slice(0, 20);
+  const gaps = [];
+
+  const familyLine = firstTwenty.find((line) => /^Reviewer family:/.test(line));
+  if (familyLine === undefined) gaps.push('GAP Reviewer family line missing');
+  else {
+    const family = familyLine.replace(/^Reviewer family:\s*/, '').trim();
+    if (!FAMILIES.has(family)) gaps.push('GAP Reviewer family invalid value=' + (family || '<empty>'));
+  }
+
+  const revisionLines = firstTwenty.filter((line) => /^Spec revision:/.test(line));
+  if (revisionLines.length !== 1) {
+    cannotCheck('first 20 report lines require exactly one Spec revision line');
+  }
+  const revision = revisionLines[0].match(/^Spec revision: sha256:([a-f0-9]{64})$/);
+  if (!revision) cannotCheck('malformed Spec revision line in first 20 report lines');
+  const actual = crypto.createHash('sha256').update(specification).digest('hex');
+  if (revision[1] !== actual) {
+    gaps.push('GAP Spec revision mismatch report=' + revision[1].slice(0, 12)
+      + ' specification=' + actual.slice(0, 12));
+  }
+
+  const rows = reportRows(lines, gaps);
+  const counts = new Map();
+  for (const row of rows) counts.set(row.id, (counts.get(row.id) || 0) + 1);
+
+  for (const id of ids) {
+    if (!counts.has(id)) gaps.push('GAP ' + id + ' has no Spec conformance row');
+  }
+  for (const row of rows) {
+    if (!idSet.has(row.id)) gaps.push('GAP ' + row.id + ' row id is not in the specification');
+    if ((counts.get(row.id) || 0) > 1 && rows.findIndex((item) => item.id === row.id) === rows.indexOf(row)) {
+      gaps.push('GAP ' + row.id + ' duplicate Spec conformance row');
+    }
+    if (!VERDICTS.has(row.verdict)) {
+      gaps.push('GAP ' + row.id + ' verdict invalid value=' + (row.verdict || '<empty>'));
+    }
+    if ((row.verdict === 'met' || row.verdict === 'not met') && !row.evidence) {
+      gaps.push('GAP ' + row.id + ' evidence empty for verdict=' + row.verdict);
+    }
+  }
+
+  if (gaps.length) {
+    for (const gap of gaps) say(gap);
+    process.exit(1);
+  }
+  say('PASS review-contract feature=' + slug + ' AC-ids=' + ids.length + ' rows=' + rows.length);
+  process.exit(0);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length !== 2) cannotCheck('usage: node check-review-contract.cjs <project-root> <feature-slug>');
+  const [rootInput, slug] = args;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) cannotCheck('malformed feature slug: ' + slug);
+  const root = projectRoot(rootInput);
+  const base = path.join('docs', 'features', slug);
+  const specification = safeRead(root, path.join(base, '01_specification.md'), 'specification');
+  const report = safeRead(root, path.join(base, 'review-report.md'), 'review report');
+  validateReport(specification, report, slug);
+}
+
+try { main(); } catch (error) {
+  cannotCheck('internal error: ' + String((error && error.message) || error));
+}

package/templates/.claude/hooks/statusline.cjs

@@ -245,7 +245,7 @@ function parseExpectedToolkit() {
     commandsExpected: 11,
     agentsExpected: 4,    // pre-shipped only (project agents are extra)
     rulesExpected: 13,    // pre-shipped only (project rules are extra)
-    hooksExpected: 24,    // 4 event hooks + statusline + state-update + writer + 14 checks + 1 capture
+    hooksExpected: 25,    // 4 event hooks + statusline + state-update + writer + 15 checks + 1 capture
   };
 }
 

package/templates/.claude/rules/replicate-pipeline.md

@@ -215,14 +215,14 @@ are project-agnostic and can be enhanced (read by Phase 3) but never recreated.
 [`incoming-webhooks`](incoming-webhooks.md), [`long-running-job`](long-running-job.md),
 [`model-call-cost`](model-call-cost.md)
 
-**Hooks (24 files in `.claude/hooks/`, cross-platform Node).** Only four are wired to an
+**Hooks (25 files in `.claude/hooks/`, cross-platform Node).** Only four are wired to an
 event in `.claude/settings.json`; the rest are utilities you invoke deliberately, and the
 difference matters — a hook of this package is NON-BLOCKING by contract and can only print.
 
 *Wired to an event (4):* `session-insights.cjs` (SessionStart) · `autocommit-roadmap.cjs`,
 `autocommit-insights.cjs`, `autocommit-plans.cjs` (Stop)
 
-*Invoked deliberately, wired to nothing (20):* `statusline.cjs` (a statusLine, not a hook) ·
+*Invoked deliberately, wired to nothing (21):* `statusline.cjs` (a statusLine, not a hook) ·
 `state-update.cjs` (argv utility) · `write-insight.cjs` (harvest carrier writer) ·
 `check-ports.cjs` (docker-ports Правило №0, exits 0/1/2) ·
 `check-docs-complete.cjs` (are the Phase-1 documents written, exits 0/1/2) ·
@@ -234,7 +234,8 @@ difference matters — a hook of this package is NON-BLOCKING by contract and ca
 `check-webhook-contract.cjs` (is the incoming webhook signed, deduplicated by a named repeat key and
 safe against reordering, exits 0/1/2)
 `check-job-contract.cjs` (does long-running work have a handle, three states and a resuming retry, exits 0/1/2)
-`check-model-cost.cjs` (does every external model call name a binding spend ceiling, exits 0/1/2)
+`check-model-cost.cjs` (does every external model call name a binding spend ceiling, exits 0/1/2) ·
+`check-review-contract.cjs` (does review-report.md answer every AC id and name the spec revision it judged, exits 0/1/2)
 `check-canon.cjs` (before a WRITING fan-out: is the shared canon named and pinned, exits 0/1/2)
 `check-file-ownership.cjs` (one writer per file, and a split-born file owned at creation, exits 0/1/2)
 `check-source-version.cjs` (does every edit and verdict declare the source version it was built on, exits 0/1/2)

package/templates/.claude/skills/requirements-validator/SKILL.md

@@ -65,11 +65,14 @@ Always flag these terms and suggest specific replacements:
 **Score <50 = BLOCKED from development.** Provide rewrite suggestions.
 
 **Blocking floor — the weakest link decides, never the average.** Independently of the score, a
-requirement is BLOCKED if `Testable = 0` (no acceptance criteria) or `Completeness = 0` (rubric "No
-AC"). A story can total 72/100 with neither, and 72 reads as "minor fixes" in the table above. A non-zero `Testable` or `Completeness` REQUIRES quoting the acceptance criteria it scores — no quote
-means 0, because the agent that scores is the agent the floor binds. The
-floor is closed at those two: `Measurable` and `Traceability` are deliberately excluded — see
-`references/scoring-system.md` → "Blocking floor" for the worked case and the reason.
+requirement is BLOCKED if `Testable = 0` (no acceptance criteria), `Completeness = 0` (rubric "No
+AC"), or `Traceability = 0` (no AC has a named scenario in the Criterion scenarios table). A story can
+total 72/100 with no acceptance criteria, and 72 reads as "minor fixes" in the table above. A
+non-zero `Testable` or `Completeness` REQUIRES quoting the acceptance criteria it scores; a non-zero
+`Traceability` REQUIRES quoting the Criterion scenarios table or referencing its document and heading.
+No artifact means 0, because the agent that scores is the agent the floor binds. The floor is closed
+at those three; `Measurable` is deliberately excluded — see `references/scoring-system.md` →
+"Blocking floor" for the worked cases and the reason.
 
 ## Output Format
 
@@ -77,6 +80,7 @@ floor is closed at those two: `Measurable` and `Traceability` are deliberately e
 
 ```markdown
 # Requirements Testability Analysis
+Spec revision: sha256:<digest of 01_specification.md>
 
 ## Summary
 - Stories analyzed: X
@@ -90,6 +94,11 @@ floor is closed at those two: `Measurable` and `Traceability` are deliberately e
 | US-001 | ... | 92/100 | 6/6 ✓ | 5/5 ✓ | READY |
 | US-002 | ... | 45/100 | 3/6 ✗ | 2/5 ✗ | BLOCKED |
 
+## Criterion scenarios
+| Criterion | Scenario |
+|-----------|----------|
+| AC-example-1 | Successful example flow |
+
 ## Detailed Analysis: US-002 (BLOCKED)
 
 ### INVEST Analysis
@@ -110,6 +119,10 @@ floor is closed at those two: `Measurable` and `Traceability` are deliberately e
 - Add AC: "Given X, when Y, then Z within 200ms"
 ```
 
+Compute the revision line from the specification bytes with
+`sha256sum docs/features/<f>/01_specification.md`. The `## Criterion scenarios` table is the artifact
+the Traceability score keys on: it maps each AC id to a named scenario.
+
 ### Security Acceptance Criteria (scoring: +5 present / -10 missing, see Scoring Bonus below)
 
 When requirements involve authentication, data storage, external APIs, or multi-tenancy,

package/templates/.claude/skills/requirements-validator/references/feature-report-contracts.md

@@ -0,0 +1,67 @@
+# Feature report contracts (`/feature`, Phases 2–4)
+
+Byte-level formats that the packaged gates enforce. Read this when WRITING one of the three reports;
+the gates are the machine half: `scripts/check-pipeline-gaps.sh` (`--report-revision`,
+`--criterion-scenarios`, `--completion`) and `.claude/hooks/check-review-contract.cjs`. Exit codes
+everywhere: `0` pass · `1` named gap(s), one line each · `2` could not establish (missing, unreadable,
+symlinked or malformed input). Neither non-zero status is ever a warning.
+
+## Shared keys
+
+- **AC ids** are `### AC-<slug>-<n>` headings in `docs/features/<f>/01_specification.md`
+  (`(FR|NFR|AC)-[A-Za-z0-9]+(-[A-Za-z0-9]+)*-[0-9]+`; fenced code blocks are ignored). FR/NFR stay under
+  the Phase 1 specification↔pseudocode gate; the three contracts below key on **AC-** ids only.
+- **Spec revision line** — `Spec revision: sha256:<64 lowercase hex>`, the SHA-256 of the BYTES of
+  `01_specification.md` (`sha256sum docs/features/<f>/01_specification.md`), within the first 20 lines
+  of `validation-report.md` and of `review-report.md`. A report is bound to the revision it judged;
+  editing the specification afterwards makes the report stale by construction.
+
+## validation-report.md (Phase 2)
+
+```markdown
+# Requirements Testability Analysis
+Spec revision: sha256:<digest of 01_specification.md>
+
+## Criterion scenarios
+| Criterion | Scenario |
+|-----------|----------|
+| AC-example-1 | Successful example flow |
+```
+
+`## Criterion scenarios` maps every AC id to the named BDD scenario that covers it — the artifact the
+`Traceability` blocking floor keys on (`references/scoring-system.md`). It is NOT the algorithm-level
+`## Scenario Coverage` block that `sparc-prd-mini` writes into `02_pseudocode.md`. An AC id without a
+row, an undeclared id, or an empty scenario cell is a named gap; a missing table cannot be established.
+
+## 05_completion.md (Phase 3)
+
+```markdown
+## Criterion coverage
+| Criterion | Test file | Test title |
+|-----------|-----------|------------|
+| AC-example-1 | tests/example.test.js | rejects an invalid request |
+```
+
+One row per AC id. `Test file` is relative to the project root and must be a regular file inside it
+(absolute, `..`-escaping and symlinked paths are refused); `Test title` must occur verbatim in that
+file. Both directions compare: an AC id without a row and a row whose id is not in the specification
+are gaps. A table of names is not evidence — the gate opens the file.
+
+## review-report.md (Phase 4)
+
+```markdown
+Reviewer family: claude|codex|human|unknown
+Spec revision: sha256:<64 lowercase hex>
+
+## Spec conformance
+| Criterion | Verdict | Evidence |
+|-----------|---------|----------|
+| AC-example-1 | met | tests/example.test.js — rejects an invalid request |
+```
+
+Input contract: the review receives `01_specification.md` and `validation-report.md`; a review that
+was not given the specification is incomplete by construction and must say so instead of grading code
+quality alone. Output contract: both header lines within the first 20 lines (`Reviewer family:` is a
+DISCLOSURE — the package refuses silence but cannot verify which family reviewed); every AC id exactly
+once in `## Spec conformance`; `Verdict` is exactly `met`, `not met` or `unverifiable` (lowercase);
+a `met` or `not met` row carries non-empty evidence; a `not met` row ideally carries a reproducer.

package/templates/.claude/skills/requirements-validator/references/scoring-system.md

@@ -31,7 +31,7 @@ Total Score = INVEST Score (50%) + SMART Score (30%) + Quality Score (20%)
 
 | Criterion | Weight | Points | Calculation |
 |-----------|--------|--------|-------------|
-| Traceability | 10% | 0-10 | 10 if linked to tests, 5 if partial, 0 if none |
+| Traceability | 10% | 0-10 | 10 if every AC id has a named scenario in the Criterion scenarios table; 5 if some do (the uncovered AC ids MUST be listed by name); 0 if none do, or the block is absent ⇒ the floor applies |
 | Completeness | 10% | 0-10 | See completeness rubric below |
 
 ### Completeness Rubric
@@ -56,12 +56,13 @@ Total Score = INVEST Score (50%) + SMART Score (30%) + Quality Score (20%)
 ### Blocking floor (overrides the total, both directions)
 
 **The weakest link decides, never the average.** A requirement is BLOCKED — whatever its total says —
-if either of these is zero:
+if any of these is zero:
 
 | Criterion | Zero means | Why it vetoes |
 |-----------|-----------|---------------|
 | `Testable` (INVEST, 8) | no acceptance criteria exist | the gate exists to block untestable requirements |
 | `Completeness` (Quality, 10) | "No AC" on the rubric above | nothing states what "done" is |
+| `Traceability` (Quality, 10) | no AC has a named scenario in the Criterion scenarios table | a story can otherwise pass validation with no scenario or test on any criterion |
 
 Without this floor the total alone lets an untestable requirement through. Worked case: a story with
 NO acceptance criteria and NO test links loses `Testable` 8, `Completeness` 10 and `Traceability` 10,
@@ -76,10 +77,18 @@ criteria AND is bound by the floor, so a score is not evidence of anything — r
 > the actual text, with its document and heading. `Testable = 4` means the AC exist and are vague:
 > quote them. **No quote ⇒ the score is 0 ⇒ the floor applies.**
 
-**The floor is CLOSED at these two.** `Measurable` and `Traceability` are deliberately NOT on it: a
-requirement with no number is often correct ("the user can export the report as PDF" is specific,
-testable and unmeasurable), so vetoing on `Measurable` would turn a false pass into a false block.
-Widening this list needs the same kind of worked case as the one above.
+> A non-zero `Traceability` REQUIRES the Criterion scenarios table (AC id → named scenario) quoted,
+> or referenced by document and heading. **No table ⇒ the score is 0 ⇒ the floor applies.**
+
+Measured worked case: story FR-009 had 27 criteria with no IDs, more than 10 of them uncovered by
+any scenario, and passed validation. Its validation report 3.1 was written against document revision
+2; only a human noticed. With no named AC-id → scenario artifact, `Traceability = 0` and the floor
+blocks that contour instead of letting its total hide the missing coverage.
+
+**The floor is CLOSED at these three.** `Measurable` is deliberately NOT on it: a requirement with no
+number is often correct ("the user can export the report as PDF" is specific, testable and
+unmeasurable), so vetoing on `Measurable` would turn a false pass into a false block. Widening this
+list needs the same kind of worked case as the ones above.
 
 ## Quality Gate Rules
 

package/tests/e2e/feature-contour.test.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// Assert lifecycle contract content, not a template hash: a sha256 pin detects any change but
+// cannot distinguish a defect from an intentional edit that preserves every required gate.
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const FIXTURE = path.join(PACKAGE_ROOT, 'tests', 'fixtures', 'feature-contour');
+const CHECKER = path.join(PACKAGE_ROOT, 'scripts', 'check-pipeline-gaps.sh');
+const REVIEW_HOOK = path.join(
+  PACKAGE_ROOT, 'templates', '.claude', 'hooks', 'check-review-contract.cjs',
+);
+const FEATURE_TEMPLATE = path.join(
+  PACKAGE_ROOT, 'templates', '.claude', 'commands', 'feature.md',
+);
+
+// The fixture ships only the consumer's OWN files (docs/, tests/). The two shipped templates the
+// checker reads for its role maps are materialised from templates/ at run time, byte-identical:
+// a stub copy inside the fixture would be a third copy of a canonical skill and trip no-skill-drift.
+const TEMPLATE_FILES = [
+  ['commands', 'feature.md'],
+  ['skills', 'sparc-prd-mini', 'SKILL.md'],
+];
+
+function project(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'feature-contour-e2e-'));
+  fs.cpSync(FIXTURE, root, { recursive: true });
+  for (const parts of TEMPLATE_FILES) {
+    const target = path.join(root, '.claude', ...parts);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(path.join(PACKAGE_ROOT, 'templates', '.claude', ...parts), target);
+  }
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  return root;
+}
+
+function execute(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, encoding: 'utf8', timeout: 10000 });
+  return {
+    status: result.status,
+    signal: result.signal,
+    output: `${result.stdout || ''}${result.stderr || ''}`,
+  };
+}
+
+function checker(root, flags = [
+  '--traceability', '--completion', '--report-revision', '--criterion-scenarios',
+]) {
+  return execute('bash', [CHECKER, root, ...flags], root);
+}
+
+function hook(root) {
+  return execute(process.execPath, [REVIEW_HOOK, root, 'demo-gate'], root);
+}
+
+function replace(root, relative, transform) {
+  const target = path.join(root, relative);
+  fs.writeFileSync(target, transform(fs.readFileSync(target, 'utf8')));
+}
+
+function phase(text, number, nextNumber) {
+  const start = text.indexOf(`### Phase ${number}:`);
+  assert.notEqual(start, -1, `Phase ${number} heading missing`);
+  const end = nextNumber === undefined ? text.length : text.indexOf(`### Phase ${nextNumber}:`, start);
+  assert.notEqual(end, -1, `Phase ${nextNumber} heading missing`);
+  return text.slice(start, end);
+}
+
+describe('feature contour consumer contract', () => {
+  test('green fixture binds specification, validation, completion, review, and executable evidence', (t) => {
+    const root = project(t);
+    const specification = fs.readFileSync(path.join(
+      root, 'docs', 'features', 'demo-gate', '01_specification.md',
+    ));
+    const validation = fs.readFileSync(path.join(
+      root, 'docs', 'features', 'demo-gate', 'validation-report.md',
+    ), 'utf8');
+    const expectedDigest = crypto.createHash('sha256').update(specification).digest('hex');
+    assert.match(validation, new RegExp(`^Spec revision: sha256:${expectedDigest}$`, 'm'),
+      'the checked-in fixture revision must match the specification bytes');
+
+    const gate = checker(root);
+    assert.equal(gate.status, 0, gate.output);
+    assert.match(gate.output, /VERDICT traceability=PASS/);
+    assert.match(gate.output, /VERDICT completion=PASS/);
+    assert.match(gate.output, /VERDICT report-revision=PASS/);
+    assert.match(gate.output, /VERDICT criterion-scenarios=PASS/);
+
+    const review = hook(root);
+    assert.equal(review.status, 0, review.output);
+    const fixtureTests = execute(process.execPath, ['--test', 'tests/demo.test.js'], root);
+    assert.equal(fixtureTests.status, 0, fixtureTests.output);
+  });
+
+  test('deleting AC-demo-gate-2 coverage is a named completion gap', (t) => {
+    const root = project(t);
+    replace(root, 'docs/features/demo-gate/05_completion.md', (body) =>
+      body.replace(/^\| AC-demo-gate-2 .*\n/m, ''));
+    const result = checker(root, ['--completion']);
+    assert.equal(result.status, 1, result.output);
+    assert.match(result.output,
+      /GAP contour=demo-gate completion AC-demo-gate-2 has no row in Criterion coverage/);
+  });
+
+  test('changing specification bytes invalidates both report revision contracts', (t) => {
+    const root = project(t);
+    fs.appendFileSync(path.join(
+      root, 'docs', 'features', 'demo-gate', '01_specification.md',
+    ), '\n');
+    const revision = checker(root, ['--report-revision']);
+    assert.equal(revision.status, 1, revision.output);
+    assert.match(revision.output,
+      /GAP contour=demo-gate report-revision validation-report\.md sha256:.* != specification sha256:/);
+
+    const review = hook(root);
+    assert.equal(review.status, 1, review.output);
+    assert.match(review.output, /GAP Spec revision mismatch report=.* specification=/);
+  });
+
+  test('removing Reviewer family is a named review-contract gap', (t) => {
+    const root = project(t);
+    replace(root, 'docs/features/demo-gate/review-report.md', (body) =>
+      body.replace(/^Reviewer family:.*\n/m, ''));
+    const review = hook(root);
+    assert.equal(review.status, 1, review.output);
+    assert.match(review.output, /GAP Reviewer family line missing/);
+  });
+
+  test('changing a test title breaks completion evidence by name', (t) => {
+    const root = project(t);
+    replace(root, 'tests/demo.test.js', (body) =>
+      body.replace('rejects an invalid value', 'declines an invalid value'));
+    const result = checker(root, ['--completion']);
+    assert.equal(result.status, 1, result.output);
+    assert.match(result.output,
+      /AC-demo-gate-2 test file tests\/demo\.test\.js does not contain title "rejects an invalid value"/);
+  });
+
+  test('deleting AC-demo-gate-1 scenario is a named traceability-floor gap', (t) => {
+    const root = project(t);
+    replace(root, 'docs/features/demo-gate/validation-report.md', (body) =>
+      body.replace(/^\| AC-demo-gate-1 .*\n/m, ''));
+    const result = checker(root, ['--criterion-scenarios']);
+    assert.equal(result.status, 1, result.output);
+    assert.match(result.output,
+      /GAP contour=demo-gate criterion-scenarios AC-demo-gate-1 has no scenario row/);
+  });
+
+  test('feature template carries each blocking gate in its owning phase and AUTO mode', () => {
+    const template = fs.readFileSync(FEATURE_TEMPLATE, 'utf8');
+    const phase2 = phase(template, 2, 3);
+    const phase3 = phase(template, 3, 4);
+    const phase4 = phase(template, 4);
+    assert.match(phase2, /--report-revision/);
+    assert.match(phase2, /--criterion-scenarios/);
+    assert.match(phase3, /--completion/);
+    assert.match(phase3, /## Criterion coverage/);
+    assert.match(phase4, /check-review-contract\.cjs/);
+
+    const autoStart = template.indexOf('## AUTO mode');
+    const autoEnd = template.indexOf('\n## Related', autoStart);
+    assert.notEqual(autoStart, -1, 'AUTO mode heading missing');
+    assert.notEqual(autoEnd, -1, 'AUTO mode boundary missing');
+    const auto = template.slice(autoStart, autoEnd);
+    assert.match(auto, /--report-revision/);
+    assert.match(auto, /--criterion-scenarios/);
+    assert.match(auto, /--completion/);
+  });
+});