feat(tools): add PhaseGate hook and ReflectionDigest

[fabiendostie]

Summary

Two self-contained tools that address the top failure patterns from analyzing 49 Algorithm reflections:

• PhaseGate.hook.ts — Claude Code PostToolUse hook that warns when transitioning to THINK without ENVIRONMENT: check or BUILD without VALIDATE: entry in the PRD's ## Decisions section. Warning mode only — never blocks. Moves gate enforcement from text instructions (which the AI can rationalize past) to code hooks (which it cannot).

• ReflectionDigest.ts — CLI tool (bun ReflectionDigest.ts) that reads algorithm-reflections.jsonl, clusters failure patterns, identifies missed capabilities, and generates ranked heuristic rules. Closes the reflection-to-action loop so past failures drive behavioral change in future sessions.

Why these exist

Analysis of 49 Algorithm reflections + 40 research papers (2025-2026) revealed a fundamental architectural weakness: advisory gates don't constrain a generative model. The Algorithm has 8 gates labeled "HARD GATE" or "MANDATORY," but they're text instructions the AI reads and can skip. The top recurring failure patterns:

Pattern	Frequency	Root Cause
Build-before-validate	31%	AI builds complex systems without proving core assumption
Phantom capabilities	25%	AI lists skills but never invokes them via tool call
Environment assumptions	17%	AI assumes tools/libs work without 30-second check

PhaseGate moves the top 2 gates to code enforcement. ReflectionDigest ensures reflections become actionable heuristics instead of write-only logs.

Files changed

• Tools/PhaseGate.hook.ts — Self-contained hook (no lib/ dependencies)
• Tools/ReflectionDigest.ts — Self-contained CLI tool (no lib/ dependencies)
• Tools/README.md — Updated with documentation for both tools

Test plan

• bun Tools/PhaseGate.hook.ts with a PRD that has phase: build but no VALIDATE: in Decisions → should print warning to stderr
• bun Tools/PhaseGate.hook.ts with a PRD that has VALIDATE: in Decisions → should pass silently
• bun Tools/ReflectionDigest.ts --dry-run with existing reflections JSONL → should print digest
• Both tools exit with {"continue": true} / exit code 0
• Neither tool modifies any input files (read-only)

Co-Authored-By: Claude Opus 4.6 and Fabien Dostie