feat: 5-layer defense against worktree isolation type divergence

[andyzengmath]

Summary

• Problem: Parallel worktree execution causes type divergence (70% of post-merge issues), destructive merges (20%), and as any bypasses (10%) because isolated agents cannot see each other's work. Documented in the March 18 post-mortem.
• Solution: 5-layer Progressive Materialization defense system — prevention (L1+L2), resolution (L3), and detection (L4+L5) with a self-healing feedback loop.
• Scope: 22 stories, 5,144 lines across 13 files, 191 passing tests.

The 5 Layers

Layer	What	File
L1: Structural contracts	ql-plan generates type shapes + definitions, not just names	skills/ql-plan/SKILL.md, references/contract-shapes.md
L2: Contract materialization	Writes real interface files before each wave so agents can import them	lib/materialize.sh (new, 541 lines)
L3: Merge conflict escalation	Fails story on conflict instead of silent data loss	lib/monitor.sh (enhanced)
L4: Post-merge typecheck gate	Runs project-wide typecheck after each merge, reverts on regression	lib/monitor.sh (new function)
L5: Wave-end type audit	Grep-based duplicate scan → agent consolidation → feedback to L2	lib/type-audit.sh (new, 365 lines), agents/type-auditor.md (new)

Key Design Decisions

• Language-agnostic from day one — auto-detects TS/Python/Go from project files
• Escalate-on-conflict — fails stories on merge conflict instead of smart merging; retry with full context
• Self-healing feedback loop — L5 discovers missed types at wave-end, L2 materializes them for the next wave
• Backward compatible — all new quantum.json fields are optional; existing files work unchanged

Test plan

• 73 tests for lib/materialize.sh (detect_language, infer_shared_types_dir, generate_definition_file, materialize_contracts)
• 14 tests for merge escalation (lib/monitor.sh)
• 21 tests for typecheck gate (lib/monitor.sh)
• 83 tests for type audit (lib/type-audit.sh)
• All 191 tests passing
• End-to-end validation on a real project with deliberate type divergence traps

🤖 Generated with Claude Code

[andyzengmath]

Soliton PR Review — ql/progressive-materialization

Risk Score: 53/100 (MEDIUM) | 16 files | 6,533 additions | AI-Authored: HIGH

Agents Dispatched

correctness, security, consistency, test-quality (4/4 completed)

Findings Summary

14 findings: 3 critical, 8 improvements, 3 nitpicks

Critical Issues (all fixed in 07704f2)

1. 🔴 [security] Command injection via typecheckCommand — lib/monitor.sh:248
   Denylist regex missed redirect operators, newlines, brace expansion. Zero test coverage for the rejection path.
   Fix: Replaced denylist with allowlist of known-safe prefixes + array-based execution (no bash -c). Added 6 injection tests.

2. 🔴 [security] Path traversal via definitionFile — lib/materialize.sh:130-196
definitionFile from quantum.json used in mkdir -p + file write with no validation that path stays within repo root.
   Fix: Added .. pattern rejection + resolved path validation. Added 2 path traversal tests.

3. 🔴 [correctness] git revert -m 1 fails on non-merge commits — lib/monitor.sh:325-337
merge_worktree_branch() could fast-forward (no merge commit), making the revert silently fail.
   Fix: Added --no-ff to merge + parent count check before revert + canonical argument order.

Important Fixes (also in 07704f2)

• Baseline write now uses write_quantum_json() instead of manual tmp+mv
• write_quantum_json() return value checked in materialize_contracts()
• Python error count: head -1 → tail -1 (final summary, not per-file count)
• printf '%b' → '%s' (no escape sequence interpretation on agent content)
• tc_exit initialized to 0 explicitly
• Header comment lists json-atomic.sh in Requires

Test Results After Fixes

Suite	Tests
test_materialize.sh	76/76 ✅
test_merge_escalation.sh	14/14 ✅
test_typecheck_gate.sh	33/33 ✅
test_type_audit.sh	83/83 ✅
Total	206/206 ✅

Notable Outside-PR-Scope Findings

• quantum-loop.sh:555 — testCommand executed via eval with zero sanitization (same threat model as typecheckCommand)
• lib/spawn.sh:97 — agents spawned with --dangerously-skip-permissions (architectural risk)

Strengths

• Comprehensive test coverage (206 tests for ~1,100 lines of production shell code)
• Consistent atomic JSON writes via write_quantum_json()
• Safe file generation (refuses to overwrite existing files with different content)
• Clean 5-layer composition with correctly wired L5→L2 feedback loop
• Defensive input validation on all public functions

🤖 Reviewed by Soliton PR Review (correctness + security + consistency + test-quality)