diff --git a/.claude/skills/builder/SKILL.md b/.claude/skills/builder/SKILL.md index dd3d188..b81efd7 100644 --- a/.claude/skills/builder/SKILL.md +++ b/.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 `, `pip index versions `/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) diff --git a/.claude/skills/code-check/SKILL.md b/.claude/skills/code-check/SKILL.md index 4e2c63c..656ad3c 100644 --- a/.claude/skills/code-check/SKILL.md +++ b/.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 diff --git a/.claude/skills/core-engineering/dependency-upgrade/SKILL.md b/.claude/skills/core-engineering/dependency-upgrade/SKILL.md index ba2072a..f102be0 100644 --- a/.claude/skills/core-engineering/dependency-upgrade/SKILL.md +++ b/.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: diff --git a/.claude/skills/core-engineering/testing/SKILL.md b/.claude/skills/core-engineering/testing/SKILL.md index 6abedb2..59320e9 100644 --- a/.claude/skills/core-engineering/testing/SKILL.md +++ b/.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): diff --git a/.claude/skills/swarm-review/SKILL.md b/.claude/skills/swarm-review/SKILL.md index 9246832..e94435c 100644 --- a/.claude/skills/swarm-review/SKILL.md +++ b/.claude/skills/swarm-review/SKILL.md @@ -42,6 +42,10 @@ 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 @@ -49,6 +53,7 @@ Launch worker-reviewer agents for each perspective: - "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?" diff --git a/CHANGELOG.md b/CHANGELOG.md index dcf2bfc..42a2bf4 100644 --- a/CHANGELOG.md +++ b/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-