@dzhechkov/p-replicator 1.12.0 → 1.13.2

package/templates/.claude/skills/goap-research-ed25519/scripts/test_quote_provenance.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Quote-provenance tests, including the ADR-001 red-first A1 fixture."""
+
+import sys
+
+sys.dont_write_bytecode = True
+
+import hashlib
+import io
+import json
+import os
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+
+import check_report_evidence as gate
+import evidence_fetch as evidence_fetch
+import quote_provenance as quote_provenance
+
+
+def _record(body, content_type="text/plain; charset=utf-8"):
+    return evidence_fetch.FetchRecord(
+        url="https://example.test/source",
+        final_url="https://example.test/source",
+        status=200,
+        sha256_body=hashlib.sha256(body).hexdigest(),
+        bytes_len=len(body),
+        fetched_at="2026-09-02T00:00:00Z",
+        content_type=content_type,
+        witness=evidence_fetch._FETCH_WITNESS,
+    )
+
+
+def _fact(quote, body_hash, acquisition="raw-fetch", excerpt_id="excerpt.json"):
+    return {
+        "claim": quote,
+        "source_url": "https://example.test/source",
+        "evidence_class": "FETCH_VERIFIED",
+        "schema_version": 4,
+        "quote": quote,
+        "acquisition": acquisition,
+        "sha256_body": body_hash,
+        "locator": "paragraph 1",
+        "excerpt_id": excerpt_id,
+    }
+
+
+def _excerpt(text, body_hash, content_type="text/plain; charset=utf-8"):
+    return {
+        "sha256_body": body_hash,
+        "fetched_at": "2026-09-02T00:00:00Z",
+        "source_url": "https://example.test/source",
+        "excerpt": text,
+        "excerpt_offset": 0,
+        "radius_chars": 500,
+        "encoding": "utf-8",
+        "content_type": content_type,
+        "sha256_excerpt": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+    }
+
+
+class QuoteGateRedFirstTests(unittest.TestCase):
+    def test_report_quote_absent_from_source_body_is_named_violation(self):
+        body = b"The preserved source discusses iron status and recovery."
+        excerpt = body.decode("utf-8")
+        body_hash = hashlib.sha256(body).hexdigest()
+        excerpt_id = "a1.json"
+        quote = "The source explicitly recommends immediate supplementation"
+        fact = _fact(quote, body_hash, excerpt_id=excerpt_id)
+        report = (
+            'The source states "The source explicitly recommends immediate '
+            'supplementation" in its recommendation.'
+        )
+
+        with tempfile.TemporaryDirectory() as tmp:
+            with open(os.path.join(tmp, excerpt_id), "w", encoding="utf-8") as handle:
+                json.dump(
+                    _excerpt(excerpt, body_hash),
+                    handle,
+                )
+            findings, _ = gate.evaluate_quotes(report, [fact], tmp)
+
+            report_path = os.path.join(tmp, "report.md")
+            facts_path = os.path.join(tmp, "facts.json")
+            with open(report_path, "w", encoding="utf-8") as handle:
+                handle.write(report)
+            with open(facts_path, "w", encoding="utf-8") as handle:
+                json.dump([fact], handle)
+            output = io.StringIO()
+            with redirect_stdout(output):
+                exit_code = gate.main([
+                    "--report", report_path,
+                    "--facts", facts_path,
+                    "--excerpts", tmp,
+                    "--json",
+                ])
+
+        self.assertEqual([finding.kind for finding in findings], ["QUOTE_NOT_IN_SOURCE"])
+        self.assertIn(fact["quote"], findings[0].detail)
+        self.assertEqual(exit_code, 1)
+        payload = json.loads(output.getvalue())
+        self.assertIn("QUOTE_NOT_IN_SOURCE", [finding["kind"] for finding in payload["findings"]])
+        self.assertEqual(payload["counts"]["quote-not-in-excerpt"], 1)
+
+    def test_present_control_and_tool_summary_ceiling(self):
+        quote = "The source explicitly recommends gradual refeeding"
+        body = quote.encode("utf-8")
+        body_hash = hashlib.sha256(body).hexdigest()
+        excerpt = _excerpt(quote, body_hash)
+        with tempfile.TemporaryDirectory() as tmp:
+            for excerpt_id in ("present.json", "summary.json"):
+                with open(os.path.join(tmp, excerpt_id), "w", encoding="utf-8") as handle:
+                    json.dump(excerpt, handle)
+            present_findings, present_counts = gate.evaluate_quotes(
+                f'The report says "{quote}".',
+                [_fact(quote, body_hash, excerpt_id="present.json")],
+                tmp,
+            )
+            summary_findings, _ = gate.evaluate_quotes(
+                f'The report says "{quote}".',
+                [_fact(quote, body_hash, acquisition="tool-summary", excerpt_id="summary.json")],
+                tmp,
+            )
+        self.assertEqual(present_findings, [])
+        self.assertEqual(present_counts["quote-verbatim-confirmed"], 1)
+        self.assertEqual([finding.kind for finding in summary_findings], ["QUOTE_METHOD_INELIGIBLE"])
+        self.assertIn("tool-summary", summary_findings[0].detail)
+
+
+class QuoteRecordTests(unittest.TestCase):
+    def test_closed_acquisition_vocabulary_and_no_writable_verdict(self):
+        fields = quote_provenance.QuoteRecord.__dataclass_fields__
+        self.assertNotIn("verbatim_status", fields)
+        with self.assertRaisesRegex(ValueError, "closed set"):
+            quote_provenance.QuoteRecord("valid quote", "Raw-Download", "u", "a" * 64)
+        with self.assertRaisesRegex(ValueError, "closed set"):
+            quote_provenance.QuoteRecord("valid quote", "webfetch", "u", "a" * 64)
+        with self.assertRaisesRegex(ValueError, "non-blank"):
+            quote_provenance.QuoteRecord("  ", "raw-fetch", "u", "a" * 64)
+
+    def test_unknown_or_absent_method_is_honest_fifth_read_state(self):
+        for value in (None, "Raw-Fetch", "webfetch", ""):
+            with self.subTest(value=value):
+                self.assertEqual(quote_provenance.read_acquisition(value), "method-unknown")
+
+    def test_legacy_quote_is_denied_without_regrading_other_trust_fields(self):
+        quote = "A legacy quoted phrase long enough for the gate"
+        legacy = {
+            "claim": quote,
+            "source_url": "https://example.test/legacy",
+            "evidence_class": "FETCH_VERIFIED",
+            "trust_class": "SELF_ATTESTED",
+            "confidence": 0.4,
+            "schema_version": 3,
+            "quote": quote,
+        }
+        trust_before = {key: legacy[key] for key in ("evidence_class", "trust_class", "confidence")}
+        findings, counts = gate.evaluate_quotes(f'The report says "{quote}".', [legacy], "unused")
+        self.assertEqual([finding.kind for finding in findings], ["QUOTE_NO_EXCERPT"])
+        self.assertIn("unverified", findings[0].detail)
+        self.assertEqual(counts["quote-method-unknown"], 1)
+        self.assertEqual(
+            {key: legacy[key] for key in ("evidence_class", "trust_class", "confidence")},
+            trust_before,
+        )
+
+
+class VerbatimPolicyTests(unittest.TestCase):
+    def setUp(self):
+        self.text = 'The source says “iron\u00a0status & recovery” — exactly.'
+        self.body_hash = hashlib.sha256(self.text.encode("utf-8")).hexdigest()
+        self.excerpt = _excerpt(self.text, self.body_hash, "text/html; charset=utf-8")
+
+    def fact(self, **overrides):
+        fact = _fact('iron status & recovery" - exactly', self.body_hash, excerpt_id="x.json")
+        fact.update(overrides)
+        return fact
+
+    def test_closed_verdict_set_and_normalized_exact_match(self):
+        self.assertEqual(
+            quote_provenance.VERBATIM_VERDICTS,
+            ("verbatim-confirmed", "not-in-excerpt", "no-excerpt", "method-ineligible",
+             "hash-mismatch", "method-unknown"),
+        )
+        verdict = quote_provenance.verify_verbatim(
+            'iron status & recovery" - exactly', self.excerpt, self.fact()
+        )
+        self.assertEqual(verdict, "verbatim-confirmed")
+
+    def test_overlap_paraphrase_does_not_count_as_verbatim(self):
+        verdict = quote_provenance.verify_verbatim(
+            "iron status recovery was described exactly", self.excerpt, self.fact()
+        )
+        self.assertEqual(verdict, "not-in-excerpt")
+
+    def test_search_listing_and_manual_need_the_same_reconciliation(self):
+        span = 'iron status & recovery" - exactly'
+        for acquisition in ("search-listing", "manual"):
+            with self.subTest(acquisition=acquisition):
+                self.assertEqual(
+                    quote_provenance.verify_verbatim(
+                        span, self.excerpt, self.fact(acquisition=acquisition)
+                    ),
+                    "verbatim-confirmed",
+                )
+                self.assertEqual(
+                    quote_provenance.verify_verbatim(span, None, self.fact(acquisition=acquisition)),
+                    "no-excerpt",
+                )
+
+    def test_every_refusal_verdict_is_reachable(self):
+        cases = (
+            (None, self.fact(), "no-excerpt"),
+            (self.excerpt, self.fact(acquisition="tool-summary"), "method-ineligible"),
+            (dict(self.excerpt, sha256_excerpt="0" * 64), self.fact(), "hash-mismatch"),
+            (self.excerpt, self.fact(acquisition=None), "method-unknown"),
+        )
+        for excerpt, fact, expected in cases:
+            with self.subTest(expected=expected):
+                self.assertEqual(quote_provenance.verify_verbatim("anything at all", excerpt, fact), expected)
+
+    def test_quote_found_only_across_join_of_two_excerpts_is_rejected(self):
+        leaves = [
+            _excerpt("boundary phrase begins", self.body_hash),
+            _excerpt(" and ends here", self.body_hash),
+        ]
+        verdict = quote_provenance.verify_verbatim(
+            "phrase begins and ends", leaves, self.fact()
+        )
+        self.assertEqual(verdict, "not-in-excerpt", "a JOIN of excerpt leaves is never searched")
+
+
+class CaptureTests(unittest.TestCase):
+    def test_capture_round_trip_is_bounded_and_self_ignoring(self):
+        quote = "bounded phrase copied exactly from source bytes"
+        body = (("prefix " * 500) + quote + (" suffix" * 500)).encode("utf-8")
+        record = _record(body)
+        captured = quote_provenance.capture_excerpt(body, quote, record)
+        self.assertLessEqual(len(captured["excerpt"]), quote_provenance.EXCERPT_MAX_CHARS)
+        self.assertNotEqual(captured["excerpt"].encode("utf-8"), body)
+        fact = _fact(quote, record.sha256_body, excerpt_id=captured["excerpt_id"])
+        with tempfile.TemporaryDirectory() as tmp:
+            path = quote_provenance.write_excerpt(tmp, captured)
+            loaded = quote_provenance.load_excerpt(tmp, captured["excerpt_id"])
+            self.assertTrue(os.path.exists(os.path.join(tmp, ".gitignore")))
+            with open(os.path.join(tmp, ".gitignore"), encoding="utf-8") as handle:
+                self.assertEqual(handle.read(), "*\n")
+            self.assertEqual(path, os.path.join(tmp, captured["excerpt_id"]))
+        self.assertEqual(quote_provenance.verify_verbatim(quote, loaded, fact), "verbatim-confirmed")
+
+    def test_forged_excerpt_and_wrong_source_body_are_refused(self):
+        quote = "captured phrase"
+        body = quote.encode("utf-8")
+        record = _record(body)
+        with self.assertRaisesRegex(quote_provenance.ExcerptCaptureRefused, "hash-mismatch"):
+            quote_provenance.capture_excerpt(body + b" forged", quote, record)
+        captured = quote_provenance.capture_excerpt(body, quote, record)
+        captured["excerpt"] = "author supplied captured phrase"
+        fact = _fact(quote, record.sha256_body, excerpt_id=captured["excerpt_id"])
+        self.assertEqual(quote_provenance.verify_verbatim(quote, captured, fact), "hash-mismatch")
+
+    def test_non_text_and_undecodable_bodies_refuse_by_name(self):
+        pdf = b"%PDF-1.7 quoted phrase"
+        with self.assertRaisesRegex(quote_provenance.ExcerptCaptureRefused, "non-text"):
+            quote_provenance.capture_excerpt(pdf, "quoted phrase", _record(pdf, "application/pdf"))
+        invalid = b"quoted phrase \xff"
+        with self.assertRaisesRegex(quote_provenance.ExcerptCaptureRefused, "undecodable"):
+            quote_provenance.capture_excerpt(
+                invalid, "quoted phrase", _record(invalid, "text/plain; charset=ascii")
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/.claude/skills/goap-research-ed25519/scripts/test_suite_completeness.py

@@ -58,7 +58,8 @@ class SuiteCompletenessTests(unittest.TestCase):
         """The specific omission AM-14 caught, pinned by name so it cannot recur."""
         collected = _collected()
         for required in ("test_ed25519_verifier", "test_evidence_provenance", "test_goap_planner",
-                         "test_signature_v3", "test_population_match", "test_risk_absolute"):
+                         "test_signature_v3", "test_population_match", "test_quote_provenance",
+                         "test_risk_absolute"):
             self.assertIn(required, collected)
 
     def test_no_enumerated_run_command_is_reintroduced(self):

package/templates/.claude/skills/knowledge-extractor/SKILL.md

@@ -138,6 +138,10 @@ Read module: `modules/01-agent-review.md`
 
 **Goal:** Find all extractable knowledge in the project using parallel agents.
 
+Each extractor delivers a FILE at its own absolute `TRACE_PATH` (terminal `Status:` line last),
+never a reply — see `.claude/rules/swarm-file-evidence.md` and the assignment table in
+`modules/01-agent-review.md`. A dead extractor and a working one are both silent.
+
 **Swarm Strategy — 5 parallel extraction agents:**
 
 | Agent | Scope | What It Looks For |

package/templates/.claude/skills/pipeline-forge/SKILL.md

@@ -351,17 +351,10 @@ Context flow: [summary]
 - Use `templates/pipeline-template.md` for the orchestrator
 - Substitute `{{PLACEHOLDERS}}` with domain-specific content
 
-**Master Validation Checklist:**
-- [ ] Every skill has `SKILL.md` with name, description, triggers
-- [ ] Every skill has explicit input/output format
-- [ ] Every skill has anti-pattern warnings
-- [ ] Orchestrator references all skills by correct path
-- [ ] Quality gates have scoring systems and verdicts
-- [ ] Checkpoints have user commands documented
-- [ ] Context flow matches phase ordering
-- [ ] Git commits defined for each major phase
-- [ ] No circular dependencies in skill graph
-- [ ] All templates substituted (no `{{PLACEHOLDER}}` remaining)
+**Master Validation Checklist:** every skill has `SKILL.md` (name/description/triggers), explicit
+input/output format and anti-pattern warnings; orchestrator references correct paths; quality gates
+carry scoring + verdicts; checkpoints document user commands; context flow matches phase order;
+git commits per major phase; no circular dependencies; no `{{PLACEHOLDER}}` left unsubstituted.
 
 **Checkpoint:**
 ```
@@ -403,11 +396,18 @@ When designing pipelines, identify parallelism opportunities and use swarm agent
 **Swarm Design Pattern:**
 ```
 1. DECOMPOSE: Break task into independent subtasks
-2. SPAWN: Launch parallel agents via Task tool
-3. AGGREGATE: Collect results, merge, resolve conflicts
-4. VALIDATE: Cross-check aggregate for consistency
+2. ASSIGN:    One WORK_UNIT_ID + one absolute TRACE_PATH per subtask; record the launch instant
+3. SPAWN:     Launch parallel agents via Task tool, each carrying its assignment
+4. RECEIPT:   node .claude/hooks/check-swarm-receipts.cjs <manifest>  (0 ok / 1 undelivered / 2 not run)
+5. AGGREGATE: Collect results FROM THE FILES, merge, resolve conflicts
+6. VALIDATE:  Cross-check aggregate for consistency
 ```
 
+A forged pipeline that skips steps 2 and 4 cannot tell a dead agent from a working one — both are
+silent — so it will report a stage as running when nothing is. See
+`.claude/rules/swarm-file-evidence.md`; the full seam text to paste into the forged pipeline lives
+in `cc-toolkit-generator-enhanced/references/templates/swarm-file-evidence.md` (Section 2).
+
 **Swarm Agent Template:**
 ```markdown
 | Agent | Scope | Criteria | Independence |
@@ -467,15 +467,10 @@ Skills written for claude.ai use `/mnt/skills/user/` paths. For Claude Code port
 
 ## Anti-Patterns
 
-❌ **Monolithic Skills** — skills with 1000+ lines doing everything
-❌ **Implicit Dependencies** — skills that assume others exist without declaring
-❌ **Skipping Quality Gates** — generating toolkit from unvalidated documentation
-❌ **Hardcoded Paths** — using absolute paths instead of relative/mapped
-❌ **Duplicating Logic** — copying skill content instead of view() references
-❌ **No Checkpoints** — running entire pipeline without user feedback points
-❌ **No Error Recovery** — pipeline that can't resume from a failed phase
-❌ **Over-Engineering** — creating 20 skills when 5 would suffice
-❌ **No Fallbacks** — skills that crash when an optional dependency is missing
+❌ Monolithic skills (1000+ lines) · implicit undeclared dependencies · skipping quality gates
+(toolkit from unvalidated docs) · hardcoded absolute paths · duplicating logic instead of view() ·
+no checkpoints · no error recovery / resume · over-engineering (20 skills where 5 suffice) ·
+no fallbacks for optional dependencies
 
 ## Quality Standards
 

package/templates/.claude/skills/pipeline-forge/examples/replicate-analysis.md

@@ -140,9 +140,14 @@ Swarm: 5 parallel validators via Task tool
 ├── validator-pseudocode  → Story coverage, implementability
 └── validator-coherence   → Cross-document consistency
 
+Receipt: per .claude/rules/swarm-file-evidence.md — each validator writes its findings
+         to its own absolute TRACE_PATH,
+         terminal `Status: completed` / `Status: failed` last, then replies one line.
+         Aggregation reads the FILES and refuses to score a validator that delivered none —
+         a validator that died is silent exactly like one still working.
 Scoring: 0-100 per validator
-Aggregate: weighted average
-Blocking: score <50 = BLOCKED
+Aggregate: weighted average over terminal-completed receipts only
+Blocking: score <50 = BLOCKED; any missing receipt = BLOCKED
 Iterations: max 3
 
 Verdicts:

package/templates/.claude/skills/pipeline-forge/references/patterns-catalog.md

@@ -199,8 +199,26 @@ UNIFIED RESULT
 1. **Independence** — swarm agents must not depend on each other (or explicitly declare dependencies)
 2. **Clear scope** — each agent has a defined scope and criteria
 3. **Parallel execution** — use Task tool to launch agents concurrently
-4. **Aggregation** — orchestrator merges results, resolves conflicts
+4. **Aggregation** — orchestrator merges results FROM FILES, resolves conflicts
 5. **Iterative** — if aggregate fails quality gate, re-run with fixes (max N iterations)
+6. **Positive file receipt** — every agent's RESULT is a file at a named path, never its reply
+
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
+
+Why this belongs in the pattern and not in the orchestrator's good intentions: a worker that died
+looks exactly like a worker that is still running, because both are silent. The absence of a
+receipt is indistinguishable from unfinished work and therefore reads as progress.
 
 ### Swarm Design Template
 ```markdown

package/templates/.claude/skills/pipeline-forge/references/self-extracted-patterns.md

@@ -206,12 +206,23 @@ OUT: Verdict + score + gap register + iteration count
 ```
 IN:  Task definition + agent table (scope, criteria, independence, output format)
 DO:  1. DECOMPOSE into independent subtasks
-     2. SPAWN parallel agents via Task tool
-     3. Each agent: scoped input -> execute -> structured output
-     4. AGGREGATE: collect, deduplicate, resolve conflicts
-     5. VALIDATE aggregate for consistency
-     6. IF inconsistent: run cross-validation agent (reads all outputs)
-OUT: Unified result + conflict resolution notes
+     2. ASSIGN one WORK_UNIT_ID + one absolute TRACE_PATH per subtask; record launch instant
+     3. SPAWN parallel agents via Task tool, each carrying its assignment
+     4. Each agent: scoped input -> execute -> write substantive body + terminal
+        `Status: completed` / `Status: failed` to TRACE_PATH -> reply one line
+     5. RECEIPT CHECK before merge: regular, non-symlink, non-whitespace, post-launch, terminal
+        (node .claude/hooks/check-swarm-receipts.cjs <manifest>; 0 ok / 1 undelivered / 2 not run)
+     6. AGGREGATE from the files: collect, deduplicate, resolve conflicts
+     7. VALIDATE aggregate for consistency
+     8. IF inconsistent: run cross-validation agent (reads all outputs)
+OUT: Unified result + conflict resolution notes + valid/required receipt ratio
+```
+
+Narrative output and silence are never receipts, and an invalid receipt refuses merge, aggregation
+and completion — a dead agent and a live one are both silent, so only the file separates them. Full
+contract: `.claude/rules/swarm-file-evidence.md`.
+
+```
 ```
 
 **PU Unicorn Example:** `knowledge-extractor` Phase 1 runs 5 agents (extractor-patterns,

package/templates/.claude/skills/pipeline-forge/references/skill-anatomy.md

@@ -202,7 +202,6 @@ INPUT → PHASE 1 → PHASE 2 → ... → OUTPUT
 ```markdown
 ## Anti-Patterns
 
-❌ [What NOT to do — reason]
 ❌ [What NOT to do — reason]
 ```
 

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/templates/.claude/skills/reverse-engineering-unicorn/modules/025-cjm-prototype.md

@@ -144,7 +144,27 @@ const CJM_META = {
 // Lock result (✅)
 ```
 
-**Design адаптация под {INDUSTRY}:**
+**Design: откуда берётся облик. Порядок приоритета, и он не симметричен.**
+
+Прежде чем открывать таблицу ниже, ответьте на один вопрос: **воспроизводит ли проект НАЗВАННЫЙ
+существующий продукт, и снят ли его облик?**
+
+| Состояние источника | Откуда берётся палитра/типографика/тон |
+|---|---|
+| источник назван, облик **СНЯТ** | **из снятого облика источника** — таблица ниже НЕ применяется |
+| источник назван, облик **НЕ ИЗМЕРЕН** (не удалось снять) | таблица ниже — как **ФОЛБЭК**, и он подписывается словом «фолбэк» вместе с причиной, по которой облик не сняли |
+| **источника нет** (продукт не воспроизводится) | таблица ниже — как **ФОЛБЭК** по отрасли, и он тоже подписывается |
+
+Почему это не две равноправные ветви. Отраслевая палитра — это догадка о том, как продукт мог бы
+выглядеть. Когда есть живой источник, догадка не «одна из двух опций»: она хуже измерения ровно
+настолько, насколько выдуманное отличается от наблюдённого. Прототип, который тихо подставил
+Emerald, потому что проект про здоровье, читается точно так же, как прототип, у которого Emerald
+измерен у источника — и именно эта неразличимость и есть дефект.
+
+Подпись обязательна во всех состояниях, включая «источника нет»: неподписанная палитра и
+подписанная выглядят одинаково для следующего читателя, а значат разное.
+
+**Design адаптация под {INDUSTRY} — ФОЛБЭК, применяется только в двух нижних состояниях:**
 
 | Industry | Палитра | Иконки | Тон |
 |----------|---------|--------|-----|