phase-workflow

name	phase-workflow
description	Phase transition rules, post-phase verification steps, peer review validation, and commit-gate approval flow.

Phase Workflow — Post-Phase Verification

Standardized steps to complete after each build phase, regardless of stack.

Spec Artifact Verification

Post-Plan Verification

After Plan phase completes, verify:

• specs/<feature-id>/plan.md exists with spec_mode in YAML frontmatter
• If spec_mode is full or lightweight: spec.md exists in the same directory
• No unresolved [NEEDS CLARIFICATION] markers remain in spec.md

Pre-Build Check

Before Build phase starts, verify based on spec_mode:

• full: spec.md present, no unresolved [NEEDS CLARIFICATION], plan.md approved
• lightweight: spec.md present, no unresolved [NEEDS CLARIFICATION], plan.md approved
• none: plan.md present and approved — no further spec artifacts required

Phase Completion Integrity

Rules preventing false completion claims. Derived from a real incident where Claude marked a phase complete with major deliverables missing, then suggested experimental work.

No partial completion

Never mark a phase as complete when deliverables are missing. If a phase has two deliverable clusters (e.g., auth middleware + chat UI) and only one is built, the phase is partially complete. Report exactly what is done and what remains.

No summary laundering

When presenting phase status, compare against the latest approved plan/spec (plan.md, spec.md, and tasks.md when present) — not your memory of what was built. If the approved plan says "Auth/RBAC + UI Split into Chat UI and Admin Console" and you only built auth, do not rewrite the summary as "Role-based auth middleware, CORS preflight." Report the gap.

No stretch before core

Never suggest experimental, nice-to-have, or post-plan work when core deliverables from the current or earlier phases are incomplete. If the plan has sequencing prerequisites (e.g., "only pursue after Phase N gates are met"), enforce them.

Regression detection on removal

When existing functionality is removed or replaced during a phase (e.g., replacing a Dash app with FastAPI), verify the replacement is functional before closing the phase. A regression from "working app" to "no app" is a hard blocker — not a separate bug to fix later.

Post-Phase Steps (Every Phase)

1. Type/lint check. Run the project's type checker and linter. Zero errors required before proceeding.

   • Examples: tsc --noEmit, mypy src/, mvn compile, go vet ./...
   • Examples: npm run lint, ruff check ., mvn checkstyle:check

2. Dependency verification. After any dependency change, run the full install + build cycle. Static analysis doesn't catch missing runtime packages.

   • Examples: npm install && npm run build, pip install -r requirements.txt, mvn dependency:resolve

2.5. Infrastructure verification. After any phase that creates or modifies Docker, Compose, or CI workflow files — run the artifact to verify it works. This is NOT optional. If you introduced a Dockerfile, run docker build. If you introduced a compose file, run docker compose up --build and verify health. If you introduced a CI workflow, validate the YAML syntax. See infra-verification.md for the full command reference. - Infrastructure verification failures block the commit, just like test failures. - Environment issues are diagnosed and fixed, not worked around.

3. Build verification. Run the dev server or build command. This catches missing dependencies, import resolution issues, and config errors that static analysis misses.

   • Examples: npm run dev, python manage.py runserver, mvn spring-boot:run, go run .

4. Integration smoke test. For phases that touch auth, API routes, or database access — verify the integration works with a real request, not just a type check. Auth issues caught late cost hours.

5. Present summary. List files created/modified, key decisions made, and any deviations from the plan.

6. Manual testing gate. User verifies UI, interactive features, and business logic. Automated tests don't replace human judgment on UX.

7. Dependency audit. Review console output for errors. Check for missing runtime dependencies, unresolved peer dependencies, or deprecation warnings.

8. Commit gate. Ask the user before committing. Suggest a conventional commit message with context. Keep commits granular — one phase per commit, not multiple phases bundled together.

9. Wait for approval. Do not start the next phase until the user confirms this one is complete.

10. Origin alignment gate. Before peer review, run scripts/check-origin-alignment.sh <feature-id>. Exit 0 or 1 proceeds. Exit ≥ 2 aborts the phase with the three-resolution escalation prompt (rescope / restart / document divergence). This gate is independent of peer review: peer review scores implementation quality; this gate scores origin alignment. See origin-confirmation.md for the full contract.

11. Peer review (if active). If CCT_PEER_REVIEW_ENABLED is true, the Build agent must complete the review loop via /review-submit before running /phase-complete. The stop hook validates that loop-summary.json exists with PASS or approved bypass — it does not initiate review. Plan-phase review is advisory and single-round. See review-loop.md for the full protocol.

Autonomy Profiles (auto-build-loop)

When a feature runs under scripts/auto-build-loop.sh (see auto-build-loop.md), the human gates above are not bypassed — they are converted into explicit, configured state transitions under an opt-in autonomy profile declared in specs/<feature-id>/automation.json:

Gate (step)	advisory	pr	merge
Manual testing (6)	deferred to milestone checkpoint	deferred to milestone	deferred to milestone
Commit gate (8)	driver auto-commits, local only, isolated branch	auto-commit	auto-commit
Wait-for-approval (9)	auto-advance; hard pause every N phases	same	same
Origin gate exit >= 2 (10)	always escalate to human	always escalate	always escalate
Peer review (11)	driver-run and gating; driver independently verifies PASS	same	same + green CI
Push / PR / merge	never / never / never	auto / auto / never	auto / auto / gated auto

The driver runs build sessions with CCT_PEER_REVIEW_ENABLED=false because it owns the review gate itself (the stop hook validates completion, not initiation). Milestone checkpoints batch steps 6 and 9: the human manually tests, records retro notes, and signs off with an approved-by: line before the loop resumes. Origin escalation semantics are unchanged — the driver never resolves rescope/restart/divergence on the user's behalf.

Phase 1 Checklist (Scaffolding)

• Package/dependency installation completes without errors
• Type checker passes
• Linter passes
• Environment config created (.env, application.yml, etc.) from example/template
• Dev server builds and runs successfully
• All config files valid (build config, lint config, test config, etc.)
• If auth is included: auth flow verified end-to-end (login, protected routes, logout)

Phase N Checklist (General Build Phase)

• All agents completed successfully
• All new dependencies installed and verified (install → build → run)
• Type checker passes across the entire codebase
• Linter passes
• Dev server builds and serves without crashes
• Browser console has no errors (check for missing modules, hydration mismatches)
• Manual smoke test completed (if applicable)
• Integration between agents verified (e.g., frontend calls backend APIs)
• Infrastructure files verified — all Docker/Compose/CI files introduced in this phase have been executed successfully
• Docker healthchecks use proper probes — not business endpoints
• Demo endpoints return meaningful data — no empty stubs ([], null, {})
• Commit is granular — one phase's worth of changes, not multiple phases bundled
• Ready for commit

Session Boundary Rule

Start a new session after each completed phase. Do not run Phases 1 through 4 in a single session — context exhaustion degrades quality in later phases. Commit, rename the session, and start fresh.

Pre-Build Verification

Rules for verifying that changes compile, build, and run after every significant modification.

After Every Dependency Change

When any agent adds, removes, or modifies a dependency:

1. Install immediately. Run the package manager install command. Don't defer.
2. Build. Run the project's build/compile step. Catch type errors and missing peer deps now.
3. Run the dev server. Static analysis doesn't catch missing runtime packages. The dev server does.
4. Check for peer dependency warnings. These often surface as runtime crashes, not compile errors.

# Generic pattern — adapt to your stack:
# 1. Install
# 2. Type check / compile
# 3. Run dev server
# 4. Verify no console errors

If any step fails, fix it before proceeding. Do not move forward with a broken build.

After Every Agent Completes

When a sub-agent returns from a delegated task:

1. Run the type checker across the entire codebase (not just the agent's files).
2. Run the linter.
3. Start the dev server and verify no runtime errors in the console.
4. If the agent touched API routes or services, make a test request.

After Parallel Agents Complete

When multiple agents finish concurrent work:

1. Run all verification steps above.
2. Check for integration issues between agents:
   • Do frontend calls match backend API signatures?
   • Are shared types consistent across modules?
   • Are imports resolving correctly across file boundaries?
3. Check for duplicate work — two agents may have created overlapping implementations.

Why Pre-Build Verification Matters

From real-world experience: missing runtime dependencies (packages imported in code but never installed) are the single most common build failure in multi-agent workflows. Static analysis (type checkers, linters) does NOT catch these. Only actually running the application reveals missing packages.

The cost of catching a missing dependency immediately: 30 seconds. The cost of discovering it 3 phases later: potentially hours of debugging cascading failures.