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.

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. Complete every required section with concrete changed paths, acceptance results, commands and outcomes, deviations, discovered work, follow-ups, and review concerns.

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.

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. Only after the summary is concrete and accepted should explicit update or sync commands set the summary and task to completed. The task definition remains the scope record; the summary remains the execution record.

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.

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. 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. The coordinator then uses an explicit update or sync command for deterministic status changes. 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.