Summarize and reconcile

Summarize And Reconcile

Use this workflow after implementation work changes the repository.

Primary audience: human operators and agents recording implementation evidence and reconciling completed milestones. Responsibility: define implementation-summary and milestone-reconciliation procedure; route full-cycle milestone orchestration to .day-shift/workflows/milestone.agent-lifecycle-guide.md and reusable validation, review, command, metadata, planning-layer, and structural-pressure detail to .day-shift/references/validation-and-review.md, .day-shift/references/commands.md, .day-shift/references/metadata.md, and .day-shift/references/planning-layers.md.

Agent Orientation Command

<day-shift-cli> agent is the read-only agent orientation command. Use it at the start of an automation-agent session to show the repository contract, entrypoint guidance, and command envelope before the agent chooses workflow-specific commands.

agent orient is the full-orientation alias, and agent remind is the shorter correction-focused reminder for sessions that have drifted from the repository contract.

Default review shape:

• update implementation-summary.md in each completed task directory
• reconcile at the milestone level once the milestone’s task slice reaches a review checkpoint
• treat the normal milestone reconciliation checkpoint as eligible only when all task implementation summaries under that milestone are truly complete, with implementation_status: completed, status: completed, and non-placeholder evidence
• use task-level reconciliation only when risk, drift, or review ownership justifies the extra artifact
• use <day-shift-cli> task readiness-review --task-definition <path> as read-only context when a review needs a quick reminder of unmet readiness evidence, but do not treat it as a writer for summary or reconciliation artifacts

Evidence Navigation

Use task implementation summaries, milestone reconciliation, review findings, validation output, and follow-up planning guidance as separate evidence surfaces. Do not collapse them into a dashboard, aggregate status page, or prose-only completion summary. Use .day-shift/references/planning-layers.md for reusable producer/consumer/evidence-handoff relationships and .day-shift/references/validation-and-review.md for validation/review no-write boundaries.

• For task closeout, inspect the originating task-definition.md, paired implementation-summary.md, task-scoped changed paths, validation output, and any read-only implementation-summary review findings. Verify that the intended code changes landed in the changed files without obvious errors, missing edits, or unintended drift from the task definition. The implementation summary records execution evidence; it does not replace the task definition.
• For milestone reconciliation, inspect the milestone overview artifact (milestone-overview.md for new canonical artifacts, or supported legacy overview.md), every declared task’s completed non-placeholder implementation-summary.md, the milestone reconciliation.md, and any read-only reconciliation review findings. The reconciliation artifact states the milestone verdict; it does not duplicate every task summary as a substitute for those source artifacts.
• Validation and review outputs are read-only evidence. They can report trace links, hierarchy state, readiness, inventory, gaps, likely next actions, blockers, warnings, and metadata-hygiene follow-ups, but any later write must be a separately named update, build, sync, or implementation step.
• Follow-up planning guidance belongs in reconciliation sections such as Discovered Work, Backlog Work, Accepted Residual Work, and Follow-Up Tasks until a separate planning workflow explicitly creates new artifacts.
• Runtime evidence rollup is mode-aware: contract summaries preserve frozen contract evidence without claiming runtime implementation, while runtime and hybrid summaries must retain Runtime Delta targets, runtime changed paths, executable validation evidence, or a structured validation exception for a blocked validation command before reconciliation treats runtime acceptance as complete.

Implementation Summary

Use:

• Prompt: .day-shift/prompts/user/implementation.build.md
• Template: .day-shift/templates/implementation-summary.md

Handoff map:

• Input: the originating task-definition.md, task-scoped repository changes, validation results, acceptance-criteria status, and any deviations, discovered work, or follow-up evidence from implementation.
• Action: update the paired task-local implementation-summary.md, using <day-shift-cli> implementation-summary build --task-definition <path> as the canonical refresh helper when command-supported and then manually completing evidence that the helper cannot infer.
• Output: a non-placeholder task-local implementation summary with implementation_status: completed and status: completed only when changed paths and validation evidence are recorded.
• Next consumer: <day-shift-cli> implementation-summary review --task-definition <path> for read-only evidence review, and milestone reconciliation after every declared sibling task summary is complete.

Create or update:

.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/tasks/<task-slug>/implementation-summary.md

Record:

• summary
• changed paths
• acceptance criteria results
• validation performed
• validation exceptions, including the planned command, blocker, substitute evidence, residual risk, and follow-up validation path when a runtime or hybrid validation command could not run
• runtime evidence boundary, including whether the originating task was contract, runtime, or hybrid and whether runtime changed paths were present
• scope classification
• residual structural pressure status, when applicable
• deviations
• risks and follow-ups
• open questions

When a task scope includes metadata, traceability-shape, status-transition, or planning-coordinate updates, summarize preservation and rejection evidence using the family boundaries in .day-shift/references/metadata.md.

implementation-summary.md is the paired task-local execution artifact. It records execution evidence and does not replace the originating task-definition.md, which remains the planning source of truth. <day-shift-cli> implementation-summary build refreshes the paired task-local execution artifact at tasks/<task-slug>/implementation-summary.md; <day-shift-cli> implementation-summary review evaluates the pair without writing or auto-advancing status. Use .day-shift/references/validation-and-review.md for the reusable gate and no-write boundary.

Advance implementation_status from pending to completed only after all required sections carry non-placeholder content, changed paths are listed, and at least one validation result is recorded. Set implementation-summary status to completed at the same time. Prefer <day-shift-cli> implementation-summary update for CLI-supported implementation-summary metadata transitions; use direct front matter edits only for unsupported command gaps or explicit manual exceptions. Do not advance implementation_status while any required section still contains placeholder tokens or validation evidence is absent. When task execution reaches completion, align task closeout with <day-shift-cli> metadata sync-status-from-review --task-definition <path> --active-artifact <path> or <day-shift-cli> task update --task-definition <path> --active-artifact <path> --field readiness=completed --field status=completed when supported, so completed work no longer remains in a ready-to-implement state. Completed task definitions should carry readiness: completed and status: completed; readiness: ready to implement is only the implementation handoff state before closeout. If the command cannot be used, record the manual exception before editing metadata directly.

Milestone Reconciliation

Use:

• Prompt: .day-shift/prompts/user/implementation.next.md
• Template: .day-shift/templates/milestone-reconciliation.md

Handoff map:

• Input: the milestone overview artifact, every declared task’s completed non-placeholder implementation-summary.md, and any implementation-summary review output needed to evaluate evidence quality.
• Action: update the milestone-level reconciliation.md, using <day-shift-cli> reconciliation build --milestone-overview <path> as the canonical refresh helper when command-supported and then completing review sections that require judgment.
• Output: a milestone reconciliation artifact that states the milestone verdict, acceptance-criteria review, completed task summaries, planned work, discovered work, backlog work, accepted residual work, validation review, follow-up tasks, review concerns, and final notes.
• Next consumer: <day-shift-cli> reconciliation review --milestone-overview <path> for read-only closure evidence, .day-shift/prompts/user/reconciliation.next.md for follow-up planning, and explicit metadata sync or update commands only after reconciliation is complete.

Create or update:

.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/reconciliation.md

When updating an existing reconciliation artifact, prefer in-place edits within the existing section headings instead of regenerating the whole file. Keep the document structure stable, replace only the sections whose content changes, and preserve the existing heading order so markdownlint remains predictable. Use <day-shift-cli> reconciliation update for CLI-supported reconciliation front matter metadata transitions when available; direct metadata edits require an explicit manual exception.

If the milestone-level reconciliation.md artifact is missing, create it from .day-shift/templates/milestone-reconciliation.md during this workflow instead of waiting for separate human intervention.

Planning artifacts may be untracked while active work is in progress. Do not treat git status ?? output for task, milestone, phase, or slice artifacts as noteworthy closeout information unless the user asks for git state, commit readiness, or PR preparation.

Preserve reconciliation creation or scaffold provenance in front matter unless an explicit metadata update command changes it. reconciliation build and reconciliation review are closeout evidence commands; record their results in reconciliation body sections such as Validation Review, Review Concerns, or Final Notes instead of overwriting workflow_cli_command when that field records the artifact’s scaffold command.

For completed milestone reconciliations, use review-section wording that matches the status. If reconciliation_status: completed, ## Review Concerns should be None. or should clearly state that listed concerns are accepted and non-blocking. Do not leave phrases such as “requires explicit human review”, “unresolved”, “still needs disposition”, or “should not be fixed inside this milestone” in ## Review Concerns; reconciliation review treats that wording as unresolved closeout evidence.

Keep unrelated validation failures out of milestone-owned remaining-work sections unless the milestone owns the repair. When a full-suite command fails outside the milestone scope, record the exact command, failing file or finding, and why it is unrelated in Final Notes or the phase/final report. Use Discovered Work, Backlog Work, Accepted Residual Work, and Follow-Up Tasks only for work that should remain attached to this milestone’s verdict.

Record:

• review status
• milestone intent
• completed task summaries
• acceptance criteria review
• planned work
• discovered work
• backlog work
• accepted residual work
• validation review
• follow-up tasks
• review concerns
• final notes

Use the milestone overview plus the completed task implementation-summary.md files as the review inputs. The implementation summaries remain the source of truth for code changes, while the milestone reconciliation answers whether the combined task outcomes satisfied the milestone intent. Before building or completing milestone reconciliation, confirm every task under the milestone has a completed, non-placeholder implementation-summary.md. If any task summary is missing, pending, draft, or placeholder-heavy, stop reconciliation and report the next task or summary closeout step instead of repairing the reconciliation placeholder. When reconciliation touches metadata-update integration or unsafe-update reporting guidance, use .day-shift/references/metadata.md for helper rejection and no-partial-write boundaries. <day-shift-cli> reconciliation build refreshes the milestone reconciliation artifact at milestones/<milestone-slug>/reconciliation.md; <day-shift-cli> reconciliation review evaluates milestone closure evidence without writing or auto-accepting closure.

Prompt Handoff Examples

To create or revise a task’s implementation summary for upward handoff:

Prompt: .day-shift/prompts/user/implementation.build.md
Task definition: [Relative Path To Task Definition]
Implementation summary: [Relative Path To Implementation Summary]

Create or update the implementation summary from the completed or partial implementation, mapping results back to acceptance criteria and validation evidence.

To review a task implementation summary before milestone reconciliation:

Prompt: .day-shift/prompts/user/implementation.review.md
Implementation summary: [Relative Path To Implementation Summary]

Review the implementation summary against its task definition and observed changes, and say whether reconciliation can proceed.

To recertify a task implementation summary before milestone reconciliation:

Prompt: .day-shift/prompts/user/implementation.recertify.md
Task definition: [Relative Path To Task Definition]
Implementation summary: [Relative Path To Implementation Summary]

Recertify this implementation summary against the paired task definition, current changed files, validation evidence, and milestone reconciliation state. Recommend whether it remains accurate, needs correction, needs revalidation, is superseded, or is closeout-ready. Stop after recertification unless a separate write request follows.

To reconcile one milestone from its milestone directory using completed task summaries:

Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Prompt: .day-shift/prompts/user/implementation.next.md
Milestone directory: [Relative Path To Milestone Directory]

Review the milestone, use the completed task `implementation-summary.md` files under that milestone as the implementation source of truth, and update milestone-level `reconciliation.md` with acceptance-criteria review, validation review, discovered work, and follow-up tasks.

To reconcile partial milestone progress without marking the milestone accepted:

Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Prompt: .day-shift/prompts/user/implementation.next.md
Milestone directory: [Relative Path To Milestone Directory]

Review the milestone, keep the reconciliation status accurate, record residual risk, unfinished tasks, and cross-task gaps, and do not mark the milestone accepted without review evidence.

To review a milestone reconciliation artifact for closure quality:

Prompt: .day-shift/prompts/user/reconciliation.review.md
Reconciliation artifact: [Relative Path To Reconciliation Artifact]

Review the reconciliation artifact for status accuracy, closure quality, traceability, review concerns, and whether the work should be accepted, deferred, or reviewed further.

To recertify a reconciliation artifact after repository state changes:

Prompt: .day-shift/prompts/user/reconciliation.recertify.md
Reconciliation artifact: [Relative Path To Reconciliation Artifact]

Recertify this reconciliation artifact against parent planning context, implementation summaries, current validation evidence, accepted residual work, and follow-up planning state. Recommend whether it remains accurate, needs correction, needs revalidation, is superseded, or has follow-up work ready for a separate planning action.

To turn milestone reconciliation into explicit follow-up planning work:

Prompt: .day-shift/prompts/user/reconciliation.next.md
Reconciliation artifact: [Relative Path To Reconciliation Artifact]

Review the reconciliation artifact and report follow-up tasks, backlog candidates, planning updates, validation actions, and items that still need user decisions. Do not create follow-up artifacts in this pass.

Follow-up extraction is read-only by default. If the follow-up requires new phases, milestones, or tasks, report the candidate artifact structure and stop unless a separate explicit planning prompt or approved scaffold plan asks for those writes.

Build And Review Command Boundary

Treat build and review command surfaces as assistive planning/review utilities, not lifecycle mutation commands.

• Build commands refresh paired artifacts only at canonical destinations and preserve template shape.
• Review commands are read-only and findings-oriented; they do not perform status transitions.
• Explicit update/sync commands remain the only status-mutation surfaces.
• After a completed phase evidence review, use <day-shift-cli> metadata sync-status-from-review, <day-shift-cli> phase update --phase-overview <path> --field status=completed, or <day-shift-cli> milestone update --milestone-overview <path> --field status=completed to advance stale phase or milestone overview metadata. Do not hand-edit those overview status fields when the CLI can apply the deterministic update.
• Planning artifacts may be untracked during active review and closeout. Treat untracked task, milestone, phase, slice, source, or test evidence as an administrative handoff risk only when the user asks for git state, commit readiness, PR preparation, or preservation checks; it is not an acceptance blocker by itself when direct artifact evidence is present.

Planning Review Command Family

The broader planning review family should stay aligned with the same read-only, findings-oriented posture used by implementation-summary review and reconciliation review.

• <day-shift-cli> task readiness-review remains the focused pre-implementation gate for deciding whether a task definition is ready to start.
• <day-shift-cli> task review evaluates a task definition against its paired execution artifacts for readiness, completion evidence, and closeout consistency.
• <day-shift-cli> milestone review evaluates a milestone overview against completed task summaries and milestone reconciliation state.
• <day-shift-cli> phase review evaluates a phase overview against milestone overviews plus milestone reconciliation evidence.
• All planning review commands should separate blockers, warnings, and metadata-hygiene follow-ups without writing files or auto-advancing lifecycle metadata.
• When those review commands emit structured output, keep the shared findings taxonomy explicit: blocking evidence in findings as error, warnings as warning, and metadata-hygiene follow-ups as informational.
• Keep any recovery guidance evidence-only and point to later explicit commands only when the next step is already deterministic from repository context.
• Review findings, recommendations, and next-step guidance across the whole planning review family are advisory evidence only; they may point to a later explicit update/build/sync command, but they do not authorize that write implicitly.

Planning Navigation And Trace-Link Command Family

The planning-navigation and trace-link command family should complement review commands by helping operators discover structure, likely next steps, and local trace-link evidence without mutating artifacts.

• <day-shift-cli> planning inventory reports observed planning hierarchy and paired execution/review artifacts for the selected scope.
• <day-shift-cli> planning gap-report reports expected-but-missing or incomplete downstream artifacts based on declared hierarchy and current artifact state.
• <day-shift-cli> workflow explain identifies which workflow and prompt apply to the selected artifact and evidence state.
• <day-shift-cli> planning next-action suggests the most likely valid next planning or review step while remaining advisory-only.
• <day-shift-cli> validation links-check --scope planning --artifact <path> reports local trace-link, hierarchy, and disposition-backed lifecycle evidence for planning artifacts without repairing links.
• <day-shift-cli> validation smoke --scope planning --artifact <path> reports focused planning-validation evidence for the selected artifact; repository-wide smoke is broad context only when that broader scope is intended.
• All planning-navigation, trace-link, and validation-smoke outputs remain read-only evidence and guidance; they do not create artifacts, close reviews, repair links, complete summaries, accept reconciliation, or authorize later writes automatically.
• Disposition-backed lifecycle evidence can identify retired, deleted, migrated, malformed-storage, or applied-migration state and recommend preview/apply commands. Record that evidence in validation review or final notes; do not treat it as permission for reconciliation to infer replacement targets, rewrite body references, mutate disposition storage, or apply migrated links.

structural-pressure.json Update Point

If .day-shift/state/structural-pressure.json exists, milestone reconciliation is the default point where it may be updated.

Use .day-shift/references/commands.md for the command-family boundary and .day-shift/references/validation-and-review.md for structural-pressure report/sync policy. A missing .day-shift/state/structural-pressure.json file is allowed before integration; task 20 owns the first-write behavior for that derived state surface.

Read It Before Updating

Read the existing JSON file before writing only when the milestone touched structurally relevant files or families.

Use the read to determine:

• whether a file or family already has an active entry
• whether the milestone changed that entry’s classification
• whether a prior entry can remain unchanged and simply be left in place

Write It Only After Reconciliation

Update .day-shift/state/structural-pressure.json only after the milestone reconciliation has established the deduped current-state verdict.

Write updates only when at least one of the following is true:

• a file receives its first structural-pressure classification
• a file changes status between resolved, acceptable-for-now, and follow-up-candidate
• a file’s severity or summary materially changes
• a file is no longer an active concern and should be cleared or reduced
• a family-level current-state summary must be updated to reflect the latest milestone outcome

Do Not Write It For

• every task touch
• repeated touches that did not change structural status
• planning-only expectations
• duplicated rationale already preserved in Markdown artifacts

Source Of Truth Rule

• implementation-summary.md captures task-local deltas
• reconciliation.md captures the deduped milestone verdict
• .day-shift/state/structural-pressure.json mirrors only the latest active current state for lookup and cross-workflow continuity
• Markdown planning artifacts remain the canonical source of truth when JSON and Markdown ever disagree

Residual Structural Pressure Classification

When implementation touched a structurally large file, changed module boundaries, or deferred part of a refactor seam, classify the post-change result explicitly instead of treating the work as simply done or not done.

Use these statuses:

• resolved: the hotspot pressure is materially improved or intentionally unchanged and no longer needs first-pass follow-up
• acceptable-for-now: some pressure remains, but the current boundary is coherent enough to defer without opening immediate new work
• follow-up-candidate: enough size, cohesion, or coupling pressure remains that later planning should revisit it explicitly

When To Apply It

Apply residual classification when any of the following is true:

• the task or milestone touched a file already known to be large or structurally awkward
• the implementation extracted helpers or split one module into several files
• the implementation deliberately left residual pressure in place to keep scope narrow
• review evidence shows improvement but not full structural resolution

How To Record It

• In task summaries, note the residual status for the touched hotspot surfaces when that helps explain follow-up work.
• In milestone reconciliation, keep resolved, acceptable-for-now, and follow-up-candidate outcomes distinct.
• Carry only follow-up-candidate items forward as explicit backlog or later-planning work.
• Do not silently convert acceptable-for-now items into backlog unless later evidence shows the deferral is no longer sound.

Dedupe And Transition-Only Reporting

When multiple tasks in the same milestone touch the same file or file family, reconciliation should report the current state once rather than replay every touch event.

Task Summary Dedupe

• Keep task summaries focused on structural deltas introduced by that task.
• If a task inherits an existing hotspot classification without changing it, reference that prior state briefly instead of re-arguing it in full.

Milestone Reconciliation Dedupe

• Collapse repeated mentions of the same file into one milestone-level current-state verdict.
• Prefer the latest supported classification for that file: resolved, acceptable-for-now, or follow-up-candidate.
• Update the rationale only when the file’s status changed, improved materially, or was newly identified as a residual concern.

Higher-Level Rollup Guidance

• At phase or slice review level, prefer family-level summaries before path-by-path repetition.
• Carry forward only what still matters in the current state.
• If nothing changed since the earlier classification, cite the prior decision instead of duplicating the full reasoning block.

Task-Level Reconciliation Exception

Use only when one task needs its own review boundary, such as:

• unusually risky implementation
• substantial scope drift inside one task
• separate reviewer ownership for one task
• partial delivery that should not wait for the full milestone to close

Use:

• Prompt: .day-shift/prompts/user/reconciliation.build.md
• Template: .day-shift/templates/reconciliation.md

Create or update:

.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/tasks/<task-slug>/reconciliation.md

When updating an existing task-level reconciliation artifact, apply the same in-place editing approach: patch the relevant headings and their contents rather than rewriting the entire file from scratch.

Closure Rules

• Do not mark work accepted without review evidence.
• Separate discovered work from backlog work.
• Preserve trace links to the task definition and upstream artifacts.
• Leave user decisions explicit.
• When milestone-level reconciliation is the default review path and the artifact is missing, create it before finishing the review.
• If implementation was partial, keep implementation_status: pending and describe the partial state in the Deviations or Risks and Follow-Ups section; implementation_status uses only pending or completed.
• Set reconciliation_status based on review completeness: use pending when review has not started or is still in progress with placeholder content; use partial when review is underway but some acceptance criteria remain unreviewed or task summaries are missing or incomplete; use blocked only for review-side blockers (missing review evidence, unresolved concerns, or reviewer unavailability — not for implementation-side failure, which stays partial); use completed only when all criteria are reviewed against task summary evidence, a milestone verdict is stated, and no placeholder review content remains.
• Keep reconciliation_status and status independent: reconciliation_status records review state; status records artifact lifecycle state. Advance status to completed at the same time as reconciliation_status: completed, using <day-shift-cli> reconciliation update when the metadata transition is supported.

Metadata Sync And Inventory After Reconciliation

After reconciliation reaches reconciliation_status: completed, the following commands are available as mechanical follow-up steps.

Metadata handoff:

• Input: a completed non-placeholder reconciliation artifact and any read-only reconciliation review output that confirms closure evidence is sufficient.
• Action: run explicit metadata sync or inventory commands only when the completed review evidence makes the transition deterministic.
• Output: metadata inventory evidence, or explicitly synced status fields when metadata sync-status-from-review is eligible and accepted.
• Next consumer: downstream phase or slice review, release planning, or follow-up task planning. Metadata inventory remains read-only evidence and does not itself authorize status changes.

Metadata Sync-Status-From-Review

<day-shift-cli> metadata sync-status-from-review --task-definition <path> propagates deterministic status signals from completed review artifacts to paired task definitions without requiring manual metadata edits. When the current CLI supports milestone or phase selectors, use the corresponding metadata sync-status-from-review --milestone-overview <path> or --phase-overview <path> form for deterministic overview status sync.

• Use it only when the cited review artifact is fully completed with no placeholder sections and the resulting status transition is within the artifact-model eligibility contract.
• Do not use it when the review is ambiguous, partially complete, or involves human judgment beyond reading a completed status field.
• If the command rejects the sync request, treat the rejection as evidence that the review artifact needs attention before metadata can be advanced.
• Sync behavior does not replace task closeout review; it supplements manual closeout by propagating mechanical evidence when eligibility is unambiguous.

Metadata Inventory

<day-shift-cli> metadata inventory is available at any point during or after reconciliation as a read-only check for stale metadata pairings, helper adoption status, and notable metadata state.

• Inventory output is operator-visible evidence only; it does not write files and does not authorize automated updates.
• Use inventory findings to decide whether metadata sync-status-from-review or artifact-specific update commands are warranted, not as automation triggers.