Validation Gates
Evidence required before harness work can close
Validation gates match changed surfaces to proof.
They keep agent activity from being mistaken for engineering work. A run can close only when the changed surface has matching evidence: tests, typecheck, build, browser observation, runtime logs, review findings, docs ingest, or a specific no-op reason.
A docs change needs routed page checks, metadata, links, and an ingest decision. A UI change needs browser evidence. A runtime bug needs logs, repro steps, traces, screenshots, or observed behavior. Package behavior needs source inspection when docs are not enough. A shared contract change needs tests across the consumers it affects.
Public Surface Proof
Validation should prove the surface being trusted. Running a command is weak evidence when the command does not match the change.
A docs-only change can need route and link evidence more than a broad test suite. A UI change can pass typecheck while the actual workflow is broken. A runtime bug can pass unit tests while the reproduced log path still fails.
Gate Types
- Requirements gate: unresolved intent stays in
requirements-grill; accepted outcomes move to an EPIC plus child stories or sub-issues through Brainstorming, Requirements, Backlog. - Planning gate:
create-planmust name dependency order, owned paths, validation commands, review mode, open questions, the target EPIC, and the child stories or sub-issues covered by each task for Implementation or AFK Implementation. - Test gate: behavior changes need TDD or focused regression coverage when practical.
- Static gate: typecheck, lint, build, or package checks must match the repo surface.
- Browser gate: routed or interactive UI changes need browser validation through the configured browser tool.
- Review gate: coding work runs findings-first review before closeout.
- Debug gate: runtime failures enter Debugging only with evidence such as logs, repro steps, traces, screenshots, or observed timing.
- Docs gate: behavior, architecture, setup, contracts, operator workflow, or source knowledge changes trigger Docs Update.
Comprehensive Behavior Contract
Repository architecture work uses the Comprehensive Behavior Contract Validation flow as one local-and-CI gate. Its current inventory is 12 participating workspaces, 11 testable workspaces, 20 classified public seams, and eight deterministic/real adapter families. The sole non-testable workspace, packages/config, still participates through static and consumer proof.
The contract distinguishes six byte-for-byte locked seams, 13 semantically equivalent seams, and one intentionally changed seam. Repetition, supported concurrency, cleanup, and uncached timing evidence establish determinism without turning timing into an acceptance threshold.
A successful repeat report or review does not independently close the gate. Required CI, the full local closeout command, durable docs, and tracker evidence must also be complete.
Phase Wrapper Boundary
Phases wrap strong validation gates and automatic checks, but the inner skills keep their proof standards. The wrapper provides order and evidence reporting. The delegated skills define what counts as proof for requirements, planning, implementation, review, debugging, docs ingest, or debt resolution.
Manual E2E Checklist
When implementation touches behavior a human should inspect, closeout includes a manual E2E checklist. The checklist names what to open, what to click or run, which states to inspect, and which outcome should be observed.
This checklist is part of the artifact trail. It is especially important for manual HITL flow because it bridges autonomous implementation and human confidence.
No-Op Handling
Skipping a gate requires a reason. Good no-op reasons are specific: docs-only change, no runtime surface, existing test covers the path, browser target unavailable with blocker recorded, or docs ingest considered with no knowledge change.
Vague no-op reasons weaken the trust model. "Not needed" is not enough.
Done Signal
The run can close when relevant gates have evidence, skipped gates have specific no-op reasons, and remaining risks are visible in the final report.