feat: add per-task build check after code-writer to catch type errors early (#66) (#66)

[jafreck]

Summary

This PR adds a per-task build/compile verification step that runs after each code-writer completes within the implementation phase. When the build fails, a fix-surgeon retry loop is triggered (up to a configurable maximum) before the task proceeds to test-writer. This catches TypeScript type errors and compilation failures in isolation, preventing them from compounding across subsequent tasks and reaching the integration checker with multiple accumulated failures.

Closes #66

Changes

• src/config/schema.ts: Added two new options fields — perTaskBuildCheck (boolean, default true) and maxBuildFixRounds (integer 1–5, default 2) — placed alongside the existing buildVerification and testVerification options.
• src/executors/implementation-phase-executor.ts: Added per-task build check between code-writer and test-writer. Imports execShell from ../util/process.js. When both commands.build and options.perTaskBuildCheck are truthy, runs the build and enters a fix-surgeon retry loop on failure. Throws an error after exhausting maxBuildFixRounds retries.
• src/agents/context-builder.ts: Extended the issueType union in buildForFixSurgeon to include 'build', enabling fix-surgeon to receive build-specific failure context.
• tests/config-schema.test.ts: Added test suites for perTaskBuildCheck and maxBuildFixRounds covering defaults, valid values, boundary conditions, and invalid inputs.
• tests/implementation-phase-executor.test.ts: Added a per-task build check describe block with 11 test cases covering all paths: skip when disabled, run when enabled, fix-surgeon invocation on failure, token recording, file writing, and error propagation after exhausting retries.

Implementation Details

The build check follows the same patterns already established in integration-phase-executor.ts: execShell for running the build command, writeFile to persist failure output, and buildForFixSurgeon to create the fix-surgeon context. The retry loop runs at most maxBuildFixRounds times; each iteration writes the combined stderr+stdout to a per-round file (build-failure-{taskId}-{round}.txt), launches fix-surgeon scoped to the task's files, and re-runs the build. If all rounds are exhausted with a non-zero exit code, an Error is thrown, which is caught by the outer task retry/block logic. The feature is gated by the perTaskBuildCheck config flag so teams with slow builds can opt out.

Testing

• All existing tests continue to pass (npx vitest run — 0 failures)
• New config schema tests assert default values, valid boundary values, and rejection of invalid types/out-of-range values
• New implementation executor tests cover: build skip when disabled, build run when enabled, fix-surgeon invocation on failure, 'build' issueType passed to context builder, failure output written to disk, token recording, re-run after each fix round, error thrown after exhausting retries, and fix-surgeon invoked exactly maxBuildFixRounds times

Integration Verification

• Build: pass (npm run build, exit code 0)
• Tests: pass (npx vitest run, exit code 0)
• Install: pass (npm install, exit code 0)

Notes

• The build timeout is hardcoded to 300,000ms (5 minutes). A future improvement could expose this as a config option.
• The build check runs only after code-writer; the issue mentioned "optionally after test-writer" but this was not implemented to keep the scope minimal.
• perTaskBuildCheck defaults to true, meaning existing projects that configure a build command will automatically get this behavior. Projects that lack a build command are unaffected (the check is skipped when commands.build is falsy).

Cadre Process Challenges

This section is required for all CADRE-generated PRs (dogfooding data).

• Issue clarity: The issue was clear about the core requirement and even provided a code sketch. The ambiguities (retry count N, whether to check after test-writer, how to scope files to fix-surgeon) required reasonable assumptions. A sentence or two in the issue specifying N and the exact scope model would have eliminated all three.
• Agent contracts: The buildForFixSurgeon signature in context-builder.ts needed to be extended to accept 'build' as an issueType, which was not mentioned in the issue. The code-writer had to discover this by reading adjacent code; it is not surfaced in the issue's "Affected Files" section.
• Context limitations: The implementation plan correctly identified that execShell, buildForFixSurgeon, and the writeFile pattern already existed in the integration executor — but this required the planner to read a sibling executor file that was not listed in "Affected Areas." Making the pattern-reference explicit in the plan would help the code-writer agent without requiring extra exploration.
• Git/worktree: No issues encountered. Worktree was clean and commits applied correctly.
• Parsing/output: No schema mismatches observed. All agent outputs parsed successfully.
• Retry behavior: No agent retries were required in this run.
• Overall: The biggest friction was the implicit dependency on context-builder.ts — a file not listed in the issue's affected areas — which required an unplanned edit to extend the issueType union. Listing all transitively affected files (even for small type changes) in the issue or analysis would eliminate this class of surprise mid-implementation edit.

Closes #66