docs(skills): verification-first loop, hallucination defense, scope lens (U17/U18/U19 — O10/O15/O17)

.claude/skills/builder/SKILL.md

@@ -11,7 +11,7 @@ Translate plans into working, tested, production-ready code.
 
 ## Method
 
-Follow the `testing` skill for TDD/coverage methodology. For root-cause investigation, follow `.claude/rules/debugging-protocol.md` (always loaded — three-before-one, root-cause mandate, escalation). This entry point adds the plan-governance workflow and GitHub-MCP dependency checking below.
+Follow the `testing` skill for TDD/coverage methodology. For root-cause investigation, follow `.claude/rules/debugging-protocol.md` (always loaded — three-before-one, root-cause mandate, escalation). This entry point adds the plan-governance workflow, hallucination defense, and GitHub-MCP dependency checking below.
 
 ## MCP Tools
 
@@ -28,6 +28,16 @@ Follow the `testing` skill for TDD/coverage methodology. For root-cause investig
 4. **Integrate** — Use Grep to verify integration points
 5. **Test** — Run tests to verify functionality
 
+Step 5 runs on `testing`'s red-green-observe loop: run the failing regression test and observe it fail before fixing a bug, state a falsifiable "done when" before implementing a feature, and close with cited evidence (test output, SHA) — never narration.
+
+## Hallucination Defense
+
+Concretizes CLAUDE.md Core Principle 1 ("Understand First") with a when-and-how for the two moments implementation-time hallucination actually bites:
+
+(a) **Verify unfamiliar APIs** — before calling an API you haven't used before (a new library, an uncommon method, a version-sensitive signature), check whether it's already used elsewhere in this repo via Grep first. "Unfamiliar" means not found by that Grep, not just "I don't remember it." If it isn't already in use here, verify the call against Context7 or the library's official docs before writing it.
+
+(b) **Verify new dependencies exist before installing** — before adding a dependency that isn't already in the manifest, confirm the package name exists in its official registry (`npm view <pkg>`, `pip index versions <pkg>`/the PyPI page, crates.io, pkg.go.dev) before running the install command. Hallucinated package names are deterministic enough across models that attackers pre-register them (slopsquatting) — a name that "sounds right" is not verification. Registry existence is not a vulnerability scan; auditing installed dependencies for known CVEs is tracked separately (O7, not yet implemented).
+
 ## Focus
 - Implement from approved plans/specs
 - Write tests alongside code (TDD)

.claude/skills/code-check/SKILL.md

@@ -74,6 +74,9 @@ Use language-appropriate detection tools:
 
 Verify findings before deletion (false positives with dynamic imports).
 
+### Scope Adherence
+Applies `swarm-review`'s Scope adherence review lens (unrequested refactors, drive-by edits, orphaned dead code) across the whole codebase instead of one diff at a time — see that skill for the full perspective and adversarial question; this entry exists so the audit checklist doesn't have a gap, not to restate the lens.
+
 ## Output Format
 
 ```markdown

.claude/skills/core-engineering/dependency-upgrade/SKILL.md

@@ -9,6 +9,8 @@ metadata:
 
 A version string is a claim, not a fact — verify it before you pin it. Isolate majors so a bad one is a one-line revert. Read the changelog before the diff, not after something breaks.
 
+A brand-new dependency's registry-existence check is `builder`'s Hallucination Defense step, not this skill's — this protocol begins once the dependency is already in the manifest and due for a version change.
+
 ## Order of Operations
 
 Work the queue in this order, not commit-arrival order:

.claude/skills/core-engineering/testing/SKILL.md

@@ -9,6 +9,12 @@ description: Write effective tests for code quality and reliability. Use when im
 
 Give every change a check it can run before calling it done: red-then-green for new logic, a failing-then-passing regression test for bug fixes, or the existing suite for anything else. No change ships without one.
 
+**Red-green-observe, not red-green-assume**: "confirm it fails" (the Regression workflow item below, and TDD's "watch it fail" step) means actually *run* the test and *read* the failure output before touching the fix or the implementation — never reason your way to "this must fail" and skip the run.
+
+**Falsifiable done-when**: before writing a feature's implementation, state one concrete, checkable condition that defines done — not "should work now," a condition a test or command can confirm or refute.
+
+**Evidence over narration**: a completion claim is only as good as what it cites — a pasted test-run result, a real exit code, a pushed commit SHA. Describing what the code should now do is not evidence; re-running the check and quoting its output is.
+
 ## MCP Tools
 
 **Chrome DevTools** (E2E testing):

.claude/skills/swarm-review/SKILL.md

@@ -42,13 +42,18 @@ Launch worker-reviewer agents for each perspective:
 - Architecture review — See `code-quality.md` for SOLID principles
 - Test coverage review
 - Code quality review
+- Scope adherence review — does this diff exceed its stated task?
+  - Flag unrequested refactors, drive-by edits outside the task/plan's acceptance criteria, and dead code left behind
+  - Compare the diff against the task/plan's AC and the PR template's stated scope and Risk Tier field
+  - Cite the `diff-size` CI job's >400-LOC advisory (`framework-invariants.yml`) as the size signal — a mechanized proxy, not a substitute for reading the diff
 
 ## Adversarial Questions
 
 **Challenge Assumptions**
 - "What if this assumption is wrong?"
 - "Under what conditions would this fail?"
 - "What edge cases weren't considered?"
+- "What in this diff did nobody ask for?" (scope adherence — see Parallel Review Perspectives)
 
 **Question Design**
 - "Why this approach over alternatives?"

CHANGELOG.md

@@ -39,6 +39,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `pre-commit-verification.sh` rewritten from advisory-only to enforcing (jq present): on `git commit`, runs every gate `gate-lib.sh` detects, each under `timeout "${CLAUDE_GATE_TIMEOUT_SECS:-120}"` from the project dir, logging to `.claude/hooks/.state/gate-<label>.log`. All green writes a hook-authored evidence stamp (`.claude/hooks/.state/commit-verified`, `{epoch, tree-hash}`) trusted on a later commit only when BOTH ≤5 minutes old AND its tree-hash matches the current `git write-tree` output — content-bound, not time-only (review F8), so an edit staged seconds ago forces a re-run despite an otherwise-fresh stamp. A red gate denies the commit, naming the gate, its log, and the existing anti-test-deletion sentence; a gate that exceeds its budget asks instead of silently killing or hanging, and writes no stamp. No gates detected → falls back to the original advisory text, unchanged. `CLAUDE_SKIP_GATE_HOOK=1` escape hatch allows unconditionally with the skip always disclosed in context; the jq-absent path is unchanged (silent fail-open). `settings.json`'s registration for this hook is raised from 5s to 300s to fit real gate runs (per-gate defaults sum safely under it). New `scripts/hook-tests.d/30-gates-lane.sh` covers the red/green/timeout/escape-hatch/cache-invalidation matrix against three fixtures — `scripts/fixtures/failing-project/` and `.../slow-gate/` each gain an (empty) `package-lock.json` so `gate-lib.sh` picks npm over pnpm (GitHub-hosted ubuntu-latest ships the former, not the latter, keeping the fixtures CI-executable); new sibling fixture `scripts/fixtures/passing-project/` covers the green/stamp path. `docs/hooks.md` gains a "Quality Gates" subsection documenting the stamp, `CLAUDE_GATE_TIMEOUT_SECS`, and the escape hatch (unit U5b)
 - `.claude/hooks/gate-lib.sh` gains `gate_lib_timeout_bin`: the portable timeout-binary resolution (`timeout`/`gtimeout`/unbounded) `pre-commit-verification.sh` (U5b) used inline, now shared verbatim with the new `task-quality-gate.sh` — DRY, the same justified pattern `gate_lib_detect` itself set in U5a. `pre-commit-verification.sh` calls the new helper instead of resolving the binary inline; behavior is unchanged (verified: the full `30-gates-lane.sh` matrix passes unmodified against the refactored hook)
 - New `.claude/hooks/task-quality-gate.sh`, registered by **default** under `hooks.TaskCompleted` in `.claude/settings.json` (timeout 120s) — the framework's only true completion-time quality gate no longer ships disabled (unit U5c; decision record: `artifacts/adr_default_quality_gate.md`, Decision D1). Runs the same `gate-lib.sh`-detected gates `pre-commit-verification.sh` runs at commit time, but at task-completion time — a second, independent checkpoint. A red gate blocks via exit code 2 (the platform's documented `TaskCompleted` mechanism), naming the gate, its log (`.claude/hooks/.state/taskgate-<label>.log`, a separate namespace from the commit gate's), and the same anti-test-deletion reminder. A gate exceeding its `${CLAUDE_GATE_TIMEOUT_SECS:-90}`-second budget is treated as non-blocking (allows, with an honest stderr note) rather than the commit gate's `ask`, since a task completion should not hard-fail on slowness alone. `CLAUDE_SKIP_GATE_HOOK=1` — the same variable the commit gate honors — disables it, disclosed on stderr, never silent. No detectable stack or `jq` absent → silent allow. New `scripts/hook-tests.d/60-taskgate.sh` covers the red/green/no-stack/escape-hatch/jq-absent matrix against the existing `failing-project`/`passing-project` fixtures; `scripts/test-hooks.sh`'s `run_case` gains `exit2-stderr-contains:`/`exit0-stderr-contains:` expectation forms for TaskCompleted's exit-code-plus-stderr contract (documented in the runner's own header). `docs/hooks.md` gains a "Quality Gates (task-quality-gate.sh)" subsection beside the commit gate's, a Built-in Hooks table row, and its opt-in-recipes preamble is rewritten so "ships disabled by default" accurately scopes to the recipes that remain opt-in (the forced-eval skill-activation hook, `docs/examples/worker-budget-hook.sh`) instead of contradicting the newly-shipped default; `artifacts/adr_default_quality_gate.md` records the context, the decision, the rejected keep-opt-in-but-prominent alternative, the reversal path, and consequences (MIGRATION.md entry, below)
+- Verification-first implementation loop (U17/O10): `testing/SKILL.md`'s Verification Loop First section gains red-green-observe discipline — a bug fix's regression test must be run and its failure observed (not assumed) before the fix, a feature states a falsifiable "done when" before implementation, and a completion claim cites evidence (test output, pushed SHA) rather than narrating it; extends the skill's existing regression-test-per-bug content instead of duplicating it. `builder/SKILL.md` gains a 2-line cross-reference from its Implementation Workflow into this loop, keeping `testing` the single policy home. `docs/hooks.md`'s opt-in recipes gain a short paragraph on mechanical TDD enforcement — teams wanting a hard `PreToolUse` block can adopt an external TDD-Guard-style hook (`nizos/tdd-guard` cited as the worked example, not vendored); it composes with the shipped commit/task quality gates rather than replacing them
+- Implementation-time hallucination defense (U18/O15): `builder/SKILL.md` gains a Hallucination Defense section, concretizing CLAUDE.md Core Principle 1 with two named workflow steps — (a) before calling an API not already used elsewhere in this repo (checked via Grep first), verify it against Context7 or official docs; (b) before adding a dependency not already in the manifest, confirm the package exists in its official registry (`npm view <pkg>`, `pip index versions <pkg>`/PyPI, crates.io, pkg.go.dev) before installing, since hallucinated package names are deterministic enough across models to be pre-registered by attackers (slopsquatting) — registry existence is not a vulnerability scan, which is tracked separately as the unselected O7. `core-engineering/dependency-upgrade/SKILL.md` gains a one-line cross-reference beside its "a version string is a claim" rule pointing at builder's new-dependency existence check rather than restating it
+- Scope-adherence review lens (U19/O17): `swarm-review/SKILL.md`'s Parallel Review Perspectives gain a Scope adherence review — does this diff exceed its stated task? Flags unrequested refactors, drive-by edits outside the task/plan's acceptance criteria, and dead code left behind; compares the diff against the task/plan's AC and the PR template's stated scope and Risk Tier field; cites the `diff-size` CI job's >400-LOC advisory (`framework-invariants.yml`) as the size signal. Adversarial Questions' Challenge Assumptions gains one matching question ("What in this diff did nobody ask for?"). `code-check/SKILL.md`'s Audit Dimensions gains a matching Scope Adherence entry cross-referencing swarm-review's lens rather than restating it
 
 ## [4.0.0] - 2026-07-23
 

docs/hooks.md

@@ -212,7 +212,7 @@ See `.claude/rules/security.md` for the full ladder and rationale. In short: not
 
 ## Opt-in recipes
 
-These recipes are **not enabled by default** — narrower guardrails whose cost/benefit is genuinely project-specific, so wiring one in is a per-project choice, not something this framework turns on for you. (The `TaskCompleted` quality-gate hook used to be documented here as an opt-in recipe; it now ships registered by default instead, because the evidence showed opt-in guardrails don't get adopted — see the "Quality Gates (task-quality-gate.sh)" subsection above and `artifacts/adr_default_quality_gate.md` for the full decision.) What remains genuinely opt-in: the forced-eval skill-activation hook below, and `docs/examples/worker-budget-hook.sh` (a concurrent-worker-budget warning documented in `docs/examples/README.md`).
+These recipes are **not enabled by default** — narrower guardrails whose cost/benefit is genuinely project-specific, so wiring one in is a per-project choice, not something this framework turns on for you. (The `TaskCompleted` quality-gate hook used to be documented here as an opt-in recipe; it now ships registered by default instead, because the evidence showed opt-in guardrails don't get adopted — see the "Quality Gates (task-quality-gate.sh)" subsection above and `artifacts/adr_default_quality_gate.md` for the full decision.) What remains genuinely opt-in: the forced-eval skill-activation hook below, the mechanical-TDD-enforcement recipe below, and `docs/examples/worker-budget-hook.sh` (a concurrent-worker-budget warning documented in `docs/examples/README.md`).
 
 ### Forced-eval skill-activation hook
 
@@ -236,6 +236,10 @@ Install (add to `.claude/settings.json`):
 
 Evidence: single disclosed-methodology test, N=50, 84% vs 20% activation (MEDIUM confidence). This is one internal test, not a peer-reviewed benchmark — treat the effect size as directional, not a guarantee, and re-validate against your own prompt mix before relying on it.
 
+### Mechanical TDD enforcement (opt-in, external)
+
+Teams that want the *hard* version of the `testing` skill's red-green-observe discipline — not just the documented workflow, but a `PreToolUse` hook that blocks an implementation edit lacking a preceding failing test — can wire one in as a project-specific choice. [nizos/tdd-guard](https://github.com/nizos/tdd-guard) is a worked external example of this pattern; this repo does not vendor it — evaluate and adopt independently. It composes with, rather than replaces, the shipped commit-time and task-completion quality gates (`pre-commit-verification.sh`, `task-quality-gate.sh`): those confirm tests *pass*, a TDD-enforcement hook additionally confirms a test *failed first*.
+
 ---
 
 [← Back to README](../README.md)