feat(setup/hooks): wave-5.2+5.3 — context7 baseline, deps-hash hook, D4 audit probe

[artyhoo]

Summary

Wave 5.2 — surfaces tool-bootstrapping discipline at consumer install time:

• setup.sh Step 2d/5: seeds .ai-factory/tool-decisions.md from template (context7 auto-accepted baseline), stamps current deps-hash, adds context7 to consumer's .mcp.json; idempotent
• INSTALL-FOR-AI.md: new "Tool bootstrapping" section explaining the discipline + .ai-factory/tool-decisions.md persistence
• INSTALL.md: cross-link to new INSTALL-FOR-AI.md section

Wave 5.3 — runtime enforcement:

• packages/core/templates/shared/AGENTS.md.template: tool-bootstrapping skill bullet added after rules-as-tests
• packages/core/hooks/deps-hash-check.sh (NEW, 44 LOC): consumer UserPromptSubmit hook — sha256 of package.json deps vs stored deps-hash: frontmatter; injects WARN on mismatch
• install.sh: hooks copy section + idempotent settings.json update to register the hook
• packages/core/audit-self/audit-ai-docs.sh: D4 probe — WARN when package.json is newer than .ai-factory/tool-decisions.md (or file absent); cross-platform stat (Linux + macOS)
• packages/core/audit-self/audit-ai-docs.test.sh: test_D4 negative-test function (WARN-on-absent pattern, mirrors test_D2)

Confirmed §11 decisions applied: D2=b (committed), D3=b (context7 baseline in setup.sh), D4=d (audit probe ships now), D7=a (deps-hash UserPromptSubmit hook).

§1.7 Self-discipline check (REQUIRED if PR touches discipline-bearing files)

§1.7 Forward-check applied

Source: research-patch §13.1 (2026-05-10), applied to Wave 5.2+5.3 artefacts. The new artefacts comply with each currently-active enforcement layer:

1. Code-level (R1-R20). No TypeScript added. deps-hash-check.sh and D4 probe are bash — R1-R20 do not apply.
2. Principle-level (01-09). No new SKILL.md or authority-bearing docs added (those landed in Wave 5.1). Principle 09 REQUIRED_HEADER_DOCS unchanged — Wave 5.3 touches AGENTS.md.template (existing registered path) only.
3. Capability-commit gate. packages/core/hooks/deps-hash-check.sh is a new file under new subdirectory packages/core/hooks/ — 44 LOC, below the ≥50 LOC capability-commit threshold. No new explicit deps; no file ≥80 LOC under packages/. Prior-art: skipped — trailers on both commits specify reason (≥20 chars).
4. Build-vs-reuse SSOT. No new SSOT entries needed — capability analysis already covered by fix: wave-5 readiness — AIF Handoff overlap analysis + scope annotations (SSOT #27-#29) #31-chore(wave-5-trio-followup): §13.25 closure + D-3 test + MD040 fix #37 in Wave 5.1. Thin-wrapper reuse of AIF /aif per fix: wave-5 readiness — AIF Handoff overlap analysis + scope annotations (SSOT #27-#29) #31.
5. Trigger sweep (§1.6). Already run in research O0.1 (Wave 5.1 branch). No new trigger entries since then.
6. Doc-authority on artefacts produced. INSTALL-FOR-AI.md has existing Authoritative-for header; AGENTS.md.template has existing header. No new authority-bearing docs introduced.

§1.7 Backward-check applied

Source: research-patch §13.2 (2026-05-10) backward-check sweep, Wave 5.2+5.3 completion status:

Artefact	Status in this PR
setup.sh	✅ Wave 5.2 — context7 + tool-decisions.md seed
INSTALL-FOR-AI.md	✅ Wave 5.2 — tool-bootstrapping section added
INSTALL.md	✅ Wave 5.2 — cross-link added
packages/core/templates/shared/AGENTS.md.template	✅ Wave 5.3 — tool-bootstrapping skill bullet
README.md	⏭ deferred — pointer to skill + tool-decisions.md; §13.2 noted as «Wave 5.2 cross-link»

Exemption: D4 probe scopes exclusively to .ai-factory/tool-decisions.md; fixture files in packages/*/fixtures/** are never checked by the probe. Exemption meta-test deferred — D4 does not scan fixture paths, making the exemption vacuously satisfied until the probe is generalized.

Test plan

• node_modules/.bin/vitest run packages/core/principles/ — 56/56 passed (10 files)
• bash packages/core/audit-self/audit-ai-docs.test.sh — 6 pass / 0 fail (includes new D4 test)
• npx tsx packages/core/render/render-rules.ts --check — rules-table up-to-date
• Pre-push hook clean (principles ✓, audit-self ✓, manifest ✓); §1.7 warn-only (calibration through 2026-06-10)
• Hook smoke: exit=0 on missing tool-decisions.md; WARN emitted on stale deps-hash
• install.sh --dry-run: hooks copy block + settings.json registration visible
• setup.sh dry-run: Step 2d/5 visible with tool-decisions.md + context7 dry-run messages
• packages/core/hooks/deps-hash-check.sh — 44 LOC (below 45-LOC capability-commit threshold)

---

2026-05-12 retroactive Wave 8.5 note: This PR's §1.7 Forward-check section would not pass the Wave 8.1 substance gate (no file:line citations present). Pre-Wave-8 acceptance — kept as historical evidence of the #discipline-theatre gap that motivated §13.29.