* feat: harness engineering improvements — post-merge test gate, shared file isolation, behavioral verification
Three improvements inspired by Anthropic's harness engineering research
(March 2026) and real-world pain points from parallel worktree execution:
1. Post-merge test gate (execute-phase.md)
- Run project test suite after merging each wave's worktrees
- Catches cross-plan integration failures that individual Self-Checks miss
- Addresses the Generator self-evaluation blind spot (agents praise own work)
2. Shared file isolation (execute-phase.md)
- Executors no longer modify STATE.md or ROADMAP.md in parallel mode
- Orchestrator updates tracking files centrally after merge
- Eliminates the #1 source of merge conflicts in parallel execution
3. Behavioral verification (verify-phase.md)
- Verifier runs project test suite and CLI commands, not just grep
- Follows Anthropic's Generator/Evaluator separation principle
- Tests actual behavior against success criteria, not just file existence
Real-world evidence: In a session executing 37 plans across 8 phases with
parallel worktrees, we observed:
- 4 test failures after merge that all Self-Checks missed (models.py type loss)
- STATE.md/ROADMAP.md conflicts on every single parallel merge
- Verifier reporting PASSED while merged code had broken imports
References:
- Anthropic Engineering Blog: Harness Design for Long-Running Apps (2026-03-24)
- Issue #1451: Massive git worktree problem
- Issue #1413: Autonomous execution without manual context clearing
* fix: address review feedback — test runner detection, parallel isolation, edge cases
- Replace hardcoded jest/vitest with `npm test` (reads project's scripts.test)
- Add Go detection to post-merge test gate (was only in verify-phase)
- Add 5-minute timeout to post-merge test gate to prevent pipeline stalls
- Track cumulative wave failures via WAVE_FAILURE_COUNT for cross-wave awareness
- Guard orchestrator tracking commit against unchanged files (prevent empty commits)
- Align execute-plan.md with parallel isolation model (skip STATE.md/ROADMAP.md
updates when running in parallel mode, orchestrator handles centrally)
- Scope behavioral verification CLI checks: skip when no fixtures/test data exist,
mark as NEEDS HUMAN instead of inventing inputs
* fix: pass PARALLEL_MODE to executor agents to activate shared file isolation
The executor spawn prompt in execute-phase.md instructed agents not to
modify STATE.md/ROADMAP.md, but execute-plan.md gates this behavior on
PARALLEL_MODE which was never defined in the executor context. This adds
the variable to the spawn prompt and wraps all three shared-file steps
(update_current_position, update_roadmap, git_commit_metadata) with
explicit conditional guards.
* fix: replace unreliable PARALLEL_MODE env var with git worktree auto-detection
Address PR #1486 review feedback (trek-e):
1. PARALLEL_MODE was never reliably set — the <env> block instructed the LLM
to export a bash variable, but each Bash tool call runs in a fresh shell
so the variable never persisted. Replace with self-contained worktree
detection: `[ -f .git ]` returns true in worktrees (.git is a file) and
false in main repos (.git is a directory). Each bash block detects
independently with no external state dependency.
2. TEST_EXIT only checked for timeout (124) — test failures (non-zero,
non-124) were silently ignored, making the "If tests fail" prose
unreachable. Add full if/elif/else handling: 0=pass, 124=timeout,
else=fail with WAVE_FAILURE_COUNT increment.
3. Add Go detection to regression_gate (was missing go.mod check).
Replace hardcoded npx jest/vitest with npm test for consistency.
4. Renumber steps from 4/4b/4c/5/5/5b to 4a/4b/4c/4d/5/6/7/8/9.
* fix: address remaining review blockers — timeout, tracking guard, shell safety
- verify-phase.md: wrap behavioral_verification test suite in timeout 300
- execute-phase.md: gate tracking update on TEST_EXIT=0, skip on failure/timeout
- Quote all TEST_EXIT variables, add default initialization
- Add else branch for unrecognized project types
- Renumber steps to align with upstream (5.x series)
* fix: rephrase worktree success_criteria to satisfy substring test guard
The worktree mode success_criteria line literally contained "STATE.md"
and "ROADMAP.md" inside a prohibition ("No modifications to..."), but
the test guard in execute-phase-worktree-artifacts.test.cjs uses a
substring check and cannot distinguish prohibition from requirement.
Rephrase to "shared orchestrator artifacts" so the substring check
passes while preserving the same intent.
dcb503961a