Evidence review and reconciliation

This workflow continues from From intake to implementation after every relevant task has produced a completed implementation summary. It turns execution records into reviewable milestone evidence without treating a finding, recommendation, or classification as an implicit write.

This page is the human decision and recovery path. Give agents the reusable review-boundary protocol and stop-and-escalate protocol. Behavioral compliance depends on the connected agent or integration. The core CLI cannot force an unsupported agent to comply.

Know which artifact owns the evidence

The task definition remains the approved scope: objective, targets, acceptance criteria, execution mode, validation, and recovery. Its paired implementation summary records what changed, acceptance results, validation evidence, deviations, discovered work, and review concerns. Milestone reconciliation consumes all completed task summaries and decides whether their combined evidence satisfies the milestone. Parent milestone, phase, and slice reviews then evaluate closure at their own layer without duplicating task execution detail.

Producers must keep these status families separate. Task readiness and task status describe planning and closeout; implementation_status belongs to the summary; reconciliation_status belongs to reconciliation. A review can recommend a transition, but only a separately selected task update, implementation-summary update, reconciliation update, or metadata sync-status-from-review write performs it.

1. Complete implementation evidence

Run implementation-summary build --task-definition <path> to refresh the paired summary after implementation and validation. Build is an explicit artifact write, not acceptance. Use its current-attempt candidatePaths and rendered candidate Markdown, inspect every excluded-path reason, and write each Changed Paths entry as exactly - \repository/relative/path`with no descriptive suffix. Complete every required section with concrete changed paths, acceptance results, commands and outcomes, deviations, discovered work, follow-ups, and review concerns. If Changed Paths parsing fails withwriteOutcome: no-writes`, correct the summary and retry; the rejected bytes do not replace the lifecycle run’s last accepted active-artifact revision.

Evidence must match execution_mode. Runtime and hybrid tasks need runtime changed paths plus executable validation, or a structured validation exception naming the planned command, blocker, substitute evidence, residual risk, and follow-up validation path. A contract task may close on frozen contract evidence only when no acceptance criterion requires runtime behavior. Pending, placeholder-heavy, validation-free, or mode-inadequate summaries cannot satisfy reconciliation eligibility.

For a runtime or hybrid task, capture task baseline only after readiness succeeds and before implementation writes. Give it a stable task-cycle ID and readiness checkpoint ID. The baseline preserves declared-target hashes, dirty-state classifications, and explicit adoption evidence for any intentional pre-staged target. At closeout, the paired summary must preserve that identity, list only fresh runtime-eligible paths, record the commands actually executed, leave ineligible paths empty, and repeat every inherited runtime-acceptance ID exactly. A generic dirty diff, a pre-existing file, or a completed status alone is not runtime proof.

2. Review and close each task

Run implementation-summary review and, when useful, task review. Both are read-only evidence surfaces. Errors block closeout; warnings require review or explicit acceptance. Neither command repairs prose, changes metadata, or marks work complete.

Apply an approved repair as a separate scoped implementation or artifact update, rerun validation, rebuild the summary when evidence changed, and review again. task implementation-complete records implementation completion without accepting or closing the task. A fresh zero-blocker review receipt can then authorize task disposition; after an accepted disposition, re-review and use task close for the receipt-bound terminal pair write. The task definition remains the scope record; the summary remains the canonical technical evidence record.

The current-attempt sequence is therefore explicit: readiness review, readiness authorization, attempt open, Runtime or Hybrid baseline, implementation, validation execution or import, summary build, implementation completion, read-only review, disposition, and closeout. Manual, CI, imported, and command-owned validation results retain different provenance. A waiver stays attached to its validation identity and never turns missing Runtime proof into a pass.

3. Check reconciliation eligibility

For a standard milestone, every declared task must have a completed, non-placeholder implementation summary. Preserve declared order and stop at the first missing or inadequate summary. A pending reconciliation scaffold is not actionable repair work before this gate passes.

Lightweight planning retains the same evidence-quality rule but uses the reconciliation path declared by the selected lightweight slice. Emergent work still begins as specification intake; urgency does not turn an incomplete summary into acceptable evidence.

4. Build, complete, and review reconciliation

Run reconciliation build --milestone-overview <path> only after eligibility passes. The build gathers completed summary links and baseline acceptance and validation evidence into the canonical milestone reconciliation.md. It is a draft rollup write, not the milestone verdict.

Complete the reconciliation’s acceptance-criteria review, validation review, work classifications, accepted residuals, review concerns, final notes, and explicit verdict. Re-open the saved file and reject placeholder phrases such as “Pending” or “Pending milestone review.” Then run reconciliation review; it is read-only and cannot repair the artifact, accept residuals, or advance status. Resolve blocking findings through a separate edit or supported update and repeat review before an explicit reconciliation or milestone status transition.

When the review receipt is current and has no blockers, reconciliation accept performs the dedicated acceptance write. A receipt proves that exact mutation; it is not a second authority and cannot authorize task closure, generic repair, or broader metadata changes. If administrative overview status remains behind accepted evidence, preview and apply metadata sync-status-from-review separately under the selected metadata posture.

5. Read validation as evidence

validation smoke, validation links-check, rollup, diff checks, impact analysis, readiness reviews, and planning reviews report evidence and recovery guidance. They do not materialize links, write checkpoints, repair metadata, create follow-up tasks, or advance lifecycle state. Use the matching explicit command only after selecting its write boundary: for example, a safe link materialize --write after a matching dry-run, or a checkpoint command after consciously accepting a forward-only baseline.

Keep unrelated suite failures in final notes with the exact command, failing surface, and why ownership lies elsewhere. Do not place unrelated failures in milestone remaining-work sections merely to make the reconciliation look comprehensive.

6. Respond to structural pressure

Structural pressure appears when evidence shows that a task is too large, crosses ownership boundaries, has ambiguous acceptance criteria, or cannot produce coherent validation inside its approved targets. Stop implementation and record the evidence. Route back to the appropriate selected planning artifact for explicit decomposition or contract correction.

Do not silently widen the task, rename planned work as discovered work, create undeclared children, or use reconciliation to approve scope creep. Review and planning guidance can recommend a repair; a separate authorized planning action owns the write.

7. Recover a documentation-loop blocker

When milestone or phase review reports that runtime acceptance is still pending after contract work, do not repeatedly rerun the same review. Preserve declared task order and use this sequence:

1. Detect: run the read-only review and identify the selected task or milestone whose structured mode-balance evidence requires a runtime or hybrid breakout.
2. Execute: implement only the already declared breakout through the task workflow; do not scaffold or reorder tasks.
3. Verify freshness: run implementation-summary review and require matching task-cycle identity, fresh runtime paths, executable validation, empty ineligible paths, and exact inherited acceptance IDs.
4. Rebuild: run reconciliation build --milestone-overview <path> for the selected milestone only after freshness clears.
5. Rerun milestone review: use the read-only milestone review against the rebuilt reconciliation.
6. Rerun phase review: use the read-only phase review only after the milestone review has no blocking findings.

This recovery protocol never turns an advisory review finding into permission to mutate a different artifact, change status, or widen scope.

8. Classify remaining work

• Planned work is declared milestone work and must be complete or explicitly incomplete before a verdict.
• Discovered work was revealed during execution or review and remains attached to the evidence until disposition.
• Backlog work is valid but out of the current acceptance boundary and belongs to a later owning workstream.
• Accepted residual work is a consciously accepted gap with rationale and residual risk; it is not the same as an unnoticed failure.
• Follow-up work is the concrete next action selected from reconciliation evidence. Reporting it is read-only until a separate planning request creates or updates artifacts.
• Emergent work is a priority-interrupting report captured as a specification before normal planning; it is not ordinary discovered or backlog work.

Classification does not itself create a task, revise a milestone, or authorize implementation. If no remaining work exists, record None. rather than leaving placeholder language.

A complete milestone closeout

An agent validates each runtime task, builds its summary, completes the evidence, runs read-only summary review, and explicitly closes the task. Once all declared summaries qualify, the agent builds reconciliation, completes the judgment-heavy sections, re-opens it to verify concrete evidence and a verdict, and runs read-only reconciliation review. A current blocker-free receipt authorizes the separate reconciliation accept write; any administrative metadata sync-status-from-review remains another explicit preview/apply boundary.

For a Governed slice, closeout continues through a read-only work review, explicit work project-review create persistence, and a fresh read-only project review before the separate work close terminal write. A generic recommendation apply, repair, or follow-up creation requires its own exact receipt and authority; project-review acceptance never performs it implicitly. Partial completion, waivers, deferred work, exceptions, accepted residuals, and discovered work remain visible in their canonical evidence instead of being converted into completion. Stale receipts or changed artifacts require a fresh matching review. See Governed reconciliation and closeout for the advanced recovery contract.

Any follow-up is reported first and scaffolded only under a separate authorized planning action.

The next journey covers resume, trace-link maintenance, archival, and release handoff. Detailed command flags and output formats remain in Reference; troubleshooting starts in Guides.