---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: milestone-agent-lifecycle-guide
---

# Milestone Agent Lifecycle Guide

Use this guide when the user wants an agent to coordinate a full lifecycle at milestone scope: create the declared task directories, execute each task through the standard task lifecycle, and reconcile the milestone only after task execution evidence is complete.

Agent entrypoint route: read `.day-shift/agents.md` first, then use this guide for milestone-scope coordination. Human workflow files may orient the session, but this guide owns the full agent milestone lifecycle.

This guide is milestone-oriented orchestration. It composes existing Day Shift workflows instead of replacing them:

- `.day-shift/workflows/02-plan-from-spec.md` owns milestone-to-task planning and task scaffolding.
- `.day-shift/workflows/task.agent-lifecycle-guide.md` owns one task's implementation lifecycle.
- `.day-shift/workflows/04-summarize-and-reconcile.md` owns milestone reconciliation from completed task summaries.

The selected milestone overview artifact remains the source of truth for the declared task set, task order, milestone intent, acceptance criteria, upstream traceability, and parent planning context. New milestone scaffolds use `milestone-overview.md`; supported legacy milestones may still use `overview.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.

## Purpose

Point the agent at one milestone and have it drive:

- milestone startup and repository-state checks
- declared task-set verification
- task directory scaffolding for every declared task
- task-by-task implementation using the task lifecycle guide
- evidence capture in each task's paired `implementation-summary.md`
- milestone reconciliation from completed task summaries
- final reporting of completed, blocked, deferred, and discovered work

## Inputs

Require these inputs before starting:

- milestone overview path or milestone directory path
- run mode: `scaffold-only`, `readiness-only`, `implement`, or `reconcile`
- whether the agent may create missing task directories and paired task artifacts
- whether the agent may perform approved task-scope code/doc edits

Prefer repository-relative paths in all artifact references and outputs.

When the user provides a milestone directory, infer:

- milestone overview: `<milestone-directory>/milestone-overview.md`, or `<milestone-directory>/overview.md` for supported legacy artifacts
- reconciliation artifact: `<milestone-directory>/reconciliation.md`
- task root: `<milestone-directory>/tasks/`

## Canonical Surfaces

Use these surfaces intentionally rather than mixing ad hoc alternatives.

### CLI

- `<day-shift-cli> workflow explain`
- `<day-shift-cli> planning next-action`
- `<day-shift-cli> planning inventory`
- `<day-shift-cli> planning gap-report`
- `<day-shift-cli> task new --milestone-overview <path> --full-set`
- `<day-shift-cli> task readiness-review --task-definition <path>`
- `<day-shift-cli> task review --task-definition <path>`
- `<day-shift-cli> implementation-summary build --task-definition <path>`
- `<day-shift-cli> implementation-summary review --task-definition <path>`
- `<day-shift-cli> reconciliation build --milestone-overview <path>`
- `<day-shift-cli> reconciliation review --milestone-overview <path>`
- `<day-shift-cli> link materialize --dry-run --artifact <path>` for revision-bound link-gate validation and candidate preview
- `<day-shift-cli> link materialize --write --artifact <path> --validation-evidence-id <evidence-id>` for an authorized candidate write against that exact preview
- `<day-shift-cli> validation links-check --scope planning --artifact <path>` only for independent diagnostics or an exact required recheck
- `<day-shift-cli> validation smoke --scope planning --artifact <path>`

Note the option boundary: `planning gap-report` selects its artifact or directory with `--scope`, while validation commands such as `validation links-check` and `validation smoke` use `--artifact` for artifact-scoped review.

Use broader validation only when the milestone or task explicitly needs repository-wide evidence. For milestone navigation and readiness decisions, prefer artifact-scoped validation against the selected milestone overview or selected task definition.

### Workflow Files

- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/workflow-guide.md`

### Prompts

- `.day-shift/prompts/user/milestone.next.md`: canonical milestone-to-task handoff prompt
- `.day-shift/prompts/user/milestone.recertify.md`: canonical milestone-layer lifecycle hygiene prompt
- `.day-shift/prompts/user/task.next.md`: canonical task-to-implementation handoff prompt
- `.day-shift/prompts/user/task.review.md`: canonical task-layer review prompt
- `.day-shift/prompts/user/task.recertify.md`: canonical task-layer lifecycle hygiene prompt
- `.day-shift/prompts/user/implementation.build.md`: canonical implementation-summary build prompt
- `.day-shift/prompts/user/implementation.next.md`: canonical implementation-to-reconciliation handoff prompt
- `.day-shift/prompts/user/implementation.review.md`: canonical implementation-summary review prompt
- `.day-shift/prompts/user/implementation.recertify.md`: canonical implementation-summary lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.build.md`: canonical reconciliation build prompt
- `.day-shift/prompts/user/reconciliation.review.md`: canonical reconciliation review prompt
- `.day-shift/prompts/user/reconciliation.recertify.md`: canonical reconciliation lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.next.md`: canonical reconciliation-to-follow-up prompt

The milestone lifecycle should use milestone-layer prompts first, task-layer prompts for each sibling task, implementation-layer prompts for milestone rollup, and reconciliation-layer prompts only for downstream follow-up planning. Use recertify prompts when an existing artifact may be stale before advancing, reviewing, implementing, reconciling, or relying on it; recertification remains read-only unless a separate explicit write request follows.

Mode-aware runtime evidence gate: preserve every task's `execution_mode` into milestone reconciliation. Newly scaffolded tasks default to `execution_mode: runtime`. Switch a task to `contract` only when the milestone can accept contract-only evidence for that task and no runtime behavior change is required. Switch a task to `hybrid` only when the task must carry both runtime implementation evidence and contract or handoff evidence to complete the milestone. Contract task summaries can satisfy contract-only acceptance criteria with frozen contract evidence, but they cannot satisfy acceptance criteria that still require runtime implementation. Runtime and hybrid task summaries must show Runtime Delta targets, runtime changed paths, executable validation evidence, or a structured validation exception for a blocked validation command before the milestone verdict treats runtime acceptance as complete.

## Run-Scoped Lifecycle Evidence

Reuse the `.day-shift/runs/run-<run-id>/run-context.json` manifest inherited from the phase lifecycle. When a Governed milestone is invoked directly, resolve or open that phase-owned manifest before the first transient readiness, review, reconciliation, validation, or other command result is emitted, then reuse it for the full milestone cycle.

Include `Run evidence directory: .day-shift/runs/run-<run-id>/` in every delegated task invocation so task execution does not create another run root. Bind each selected ordinary command with global `--format json --run-directory .day-shift/runs/run-<run-id> --run-gate <gate>` and pass `--run-artifact <path>` when attribution moves to a different task, milestone, or reconciliation artifact. The shared boundary writes the exact envelope once at a deterministic manifest-owned path such as `.day-shift/runs/run-<run-id>/evidence/0001-task-readiness-task-readiness-review-ok.json`; do not add an `--output-file`, redirect the result, or follow it with ordinary `resume run record`.

Global run binding constrains and records the invocation; it never authorizes the command. If `data.lifecycleRunCapture` reports `writeOutcome: partial-evidence`, preserve the returned envelope, do not rerun the completed command, inspect `resume run status`, and use `resume run record` only as a compatibility recovery import.

Do not write evidence files directly under `.day-shift/runs/`, and do not create unexpected sibling directories there; its direct children must remain canonical `run-<run-id>/` directories. Transient command output belongs in the selected run directory. Canonical milestone, task, implementation-summary, and reconciliation artifacts remain in `.day-shift/planning/`, while separately owned durable local evidence stores remain at their declared repository-local paths. Do not move either durable artifact class into `.day-shift/runs/`.

When a direct invocation inherits `sandbox/run-<run-id>/`, use the preview-bound `resume run migrate` transition and continue only from the emitted `.day-shift/runs/run-<run-id>/` destination. Legacy reads exist for compatibility; do not create another root run.

### Command Continuation And Evidence Inspection

Under strict lifecycle execution, an execution-surface response that includes a live process or continuation handle is `running`, not successful, failed, or timed out. Retain that handle and poll the same invocation until it reaches a terminal result; do not launch a duplicate command solely because the initial call yielded. A poll or caller wait budget ending while the handle remains live leaves the command in `running` state.

Use command states consistently:

- `running`: the original invocation has a live handle and no terminal result
- `timed out`: the command itself reached a terminal deadline outcome and is no longer running
- `interrupted`: the process or session ended without a command-owned terminal result; inspect possible side effects and freshness before an intentional retry
- `failed`: the invocation returned a terminal unsuccessful result
- `completed`: the invocation returned a terminal successful result with complete required output

While an invocation is `running`, poll its existing handle and provide user-visible progress at least once every 60 seconds without changing command identity. A retry is a new execution and is eligible only after the earlier invocation is known to be terminal and the lifecycle permits retrying it.

Inspect authored evidence with bounded, structure-aware reads. For Markdown, separate front matter from the authored body and select the named body section before searching; exclude serialized attempts, validation records, review receipts, and disposition payloads from body searches by default. For JSON or YAML, select exact structured fields. Bound the file set, match count, surrounding context, and output size before broadening scope, and do not begin with an unbounded repository-wide recursive text search over planning artifacts.

When serialized lifecycle metadata is the selected evidence source, parse it explicitly and inspect only the relevant attempt, validation, receipt, or disposition fields with bounded output. The default body-search exclusion keeps serialized payloads from flooding authored evidence; it does not discard them.

Pass the inherited directory plus global `--run-gate` binding on every selected
lifecycle command. For lifecycle-managed `milestone update`, `phase update`, or
shared metadata update, place the single `--run-directory` value at the writer's
command-specific option position; the shared boundary consumes that same raw
value for capture, so never repeat the option.
The writer must match the run's active artifact and gate and must reject stale
or incomplete run evidence before planning a change. A `read-only` run rejects
lifecycle status and readiness fields with a typed no-write result and routes
the operator to the applicable read-only milestone or phase review.
`sync-on-clean-review` permits only the exact `status=completed` transition in a
current indexed clean phase-review receipt; it does not permit unrelated fields
or turn run history into authority. A standalone explicit update may omit
`--run-directory` only when it is operator-selected outside a lifecycle run.

## Starting

Start with the minimum context required to coordinate the selected milestone safely:

- the selected milestone overview artifact
- existing milestone `reconciliation.md`, if present
- the milestone `tasks/` directory, if present
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/prompts/user/milestone.next.md`
- `.day-shift/prompts/user/task.next.md`
- `.day-shift/prompts/user/implementation.next.md`
- upstream specs, parent overviews, decisions, manifests, prompts, templates, or dependency artifacts named by the milestone when they specify contract truth, validation semantics, or scope boundaries

Read broader surfaces only when milestone context, trace links, or workflow choice is unclear:

- `.day-shift/agents.md`
- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/workflow-guide.md`
- parent phase and slice overview artifacts
- `<day-shift-cli> workflow explain`
- `<day-shift-cli> planning next-action`
- `<day-shift-cli> planning inventory`
- `<day-shift-cli> planning gap-report`
- `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>`
- `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>`

Use the selected milestone overview to establish:

- milestone intent
- acceptance criteria
- declared task slugs and task order
- target task count and decomposition rationale
- upstream traceability
- validation expectations
- reconciliation expectations
- parent slice and phase context

Before creating or implementing anything, confirm the milestone path is the active source of truth.

- Infer the milestone directory from the selected milestone overview artifact.
- Use the existing sibling `reconciliation.md` if present.
- Use existing task directories under the same milestone directory only if they match declared task slugs or are explicitly identified as legacy/adopted task artifacts.
- If chat context or prior summaries disagree with the repository tree, trust the repository tree and re-resolve from the milestone overview before editing anything.
- If the milestone depends on a later milestone, missing parent artifact, or missing producer artifact, stop and report the sequencing blocker.

## Full-Cycle Algorithm

Run this loop for the selected milestone.

For normal `implement` runs, use this minimum command spine unless the milestone overview or a task definition gives a stronger task-specific sequence:

1. Inspect repository state, preserve unrelated user changes, and reuse the inherited `.day-shift/runs/run-<run-id>/` evidence directory or establish it before writing any transient lifecycle result.
2. Confirm the milestone overview has a valid ordered `## Tasks` section.
3. Run `<day-shift-cli> task new --milestone-overview <path> --full-set` to create missing declared task directories and paired implementation-summary placeholders.
4. Complete scaffolded task contracts when the scaffold produced placeholders, then rerun readiness review only after every task definition is implementation-ready.
5. After task scaffolding or any milestone-overview body update, run `<day-shift-cli> link materialize --dry-run --artifact <milestone-overview-path>` as the combined revision-bound link-validation and materialization preview. A clean zero-candidate result with `reusableAsLifecycleLinkGate: true` satisfies the milestone link gate without a standalone links-check. Reuse it only while repository, artifact, planning scope, selected revision digest, candidate state, and finding state match exactly. When `candidateCount > 0`, `previewChangedPaths` names only the selected artifact, and the current run mode permits writes, run `<day-shift-cli> link materialize --write --artifact <milestone-overview-path> --validation-evidence-id <evidence-id>` and use its current `postWriteValidationEvidence`; if that proof is absent, run only its exact `requiredRecheck`. Stale or differently scoped evidence fails closed. Also run `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` when declared-child, readiness, or local gap evidence is needed. Use `.day-shift/references/validation-and-review.md` for reusable no-write validation semantics.
6. For each declared task in milestone order, pass the selected run evidence directory and run the task lifecycle from `.day-shift/workflows/task.agent-lifecycle-guide.md` with `.day-shift/prompts/user/task.next.md`.
7. Stop at the first blocking task unless the user explicitly asked for a readiness sweep or independent-task continuation.
8. Run final diff sanity checks, a milestone link-materialization dry-run, and focused smoke evidence after task closeout and before milestone reconciliation. Treat the dry-run's revision-bound validation evidence as the link gate under the exact reuse rules from step 5. Apply a safe candidate write only with that preview's `evidenceId`, then rely on its post-write evidence or exact required recheck; otherwise report the dry-run output as administrative follow-up.
9. After every task has a completed, non-placeholder `implementation-summary.md`, run `<day-shift-cli> reconciliation build --milestone-overview <path>` as a required closeout write.
10. Re-open the written `reconciliation.md` and verify that the placeholder body was replaced with concrete completed-task summary links, acceptance-criteria review, validation review, final notes, and a stated milestone verdict.
11. Complete or correct `reconciliation.md` body evidence manually when the build command cannot supply final review evidence by itself; use `<day-shift-cli> reconciliation update` for CLI-supported reconciliation metadata transitions when available.
12. Run `<day-shift-cli> reconciliation review --milestone-overview <path>` in a repair loop until blocking findings are gone or a real blocker is reported.
13. Report milestone status, task outcomes, validation evidence, discovered work, and the next handoff only after reconciliation is populated and reviewed, or report the exact reconciliation blocker.

Treat `reconciliation build` as a required draft rollup command for eligible full-milestone closeout. It gathers completed task-summary evidence, but the agent still owns final acceptance-criteria review, validation review, accepted residual classification, review concerns, and final notes before reconciliation review. CLI-supported reconciliation status metadata transitions are command-owned; use the relevant update command instead of hand-editing front matter when available.

Do not mark a full milestone run complete while `reconciliation.md` is still a scaffold placeholder. Placeholder lines such as `Pending.`, `Pending milestone review.`, `Pending review after task implementation summaries are available.`, or `Pending. Add completed task implementation summaries as milestone execution work finishes.` are closeout blockers after every task summary is completed.

When milestone work discovers an unsupported command gap, record it as discovered or backlog work instead of presenting the behavior as command-supported. Manual artifact edits remain exception-only and should name `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification`.

Do not skip from task scaffolding to reconciliation. Milestone reconciliation is eligible only after every task under the milestone has a completed, non-placeholder implementation summary.

Use the shared Safe Link Materialization Gate in `.day-shift/references/validation-and-review.md`; do not redefine or broaden its write boundary at the milestone layer.

### 1. Startup Preflight

Confirm the local session is safe to begin.

- inspect current repository state before editing, using scoped changed-path accounting rather than broad unrelated-dirty-state narration
- preserve unrelated user changes
- verify the milestone overview exists and is readable
- verify parent traceability paths are present when they define milestone scope
- verify the milestone's task list uses ordered task slug declarations in ascending order; accept raw backticked slug bullets and materialized Markdown-link slug bullets
- verify declared task slugs match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`
- verify existing task directories match the declared task set or identify drift before proceeding
- verify the milestone does not require missing planning artifacts before task creation or execution can proceed
- use planning inventory, gap-report, next-action, workflow explain, or artifact-scoped validation when directory shape or trace links are suspect

If startup evidence is contradictory or incomplete, stop before editing.

### Resume / Interruption Recovery

When resuming a milestone after an interruption, aborted tool call, context compaction, or explicit user "proceed" request, re-establish the lifecycle boundary before continuing.

- run `git status --short` with a scope that includes the selected milestone, active task artifacts, and expected implementation paths
- identify the last completed lifecycle gate: scaffold, task readiness, task implementation, task summary review, reconciliation build, or reconciliation review
- inspect partially edited files for the active task before assuming prior edits completed
- when a resumed write-capable update should verify the same active artifact selected by the lifecycle handoff, pass that repository-relative path through `--active-artifact` and stop on mismatch rather than guessing which artifact is current
- rerun the current task's readiness review before implementation if no implementation edits were completed yet
- rerun the current task's declared validation or implementation-summary review before marking a partially completed task as done
- preserve the declared task order after resuming; do not skip ahead because a later task looks easier
- report any ambiguous resume state as blocked instead of reconciling from uncertain evidence

### 2. Scaffold Declared Tasks

Use `.day-shift/workflows/02-plan-from-spec.md` and `.day-shift/prompts/user/milestone.next.md` for milestone-to-task creation.

Canonical invocation:

```md
Workflow: .day-shift/workflows/02-plan-from-spec.md
Prompt: .day-shift/prompts/user/milestone.next.md
Milestone overview: <relative-path-to-milestone-overview>

Create all tasks listed in the milestone overview by iterating the standard task-creation contract for each listed task, creating that directory if needed, using ordered task directory names and keeping traceability back to the source specs and index metadata.
```

Task scaffolding rules:

- create only tasks already declared in the milestone overview
- preserve the declared task order
- use `<day-shift-cli> task new --milestone-overview <path> --full-set` as the first choice
- create the milestone `tasks/` directory if needed
- create one task directory per declared task slug
- create both `task-definition.md` and `implementation-summary.md` in each task directory
- initialize implementation summaries as pending placeholders
- preserve upstream traceability to source specs and parent slice, phase, and milestone artifacts
- do not mark newly scaffolded tasks as ready or completed during milestone-to-task planning
- do not update or complete milestone reconciliation during task scaffolding

Manual task creation is allowed only for the named exceptions in `02-plan-from-spec.md`: `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification`. Record workflow provenance when manual creation is used.

### 2a. Complete Task Contracts After Scaffolding

Generated task artifacts may be placeholders. Treat task scaffolding and task contract completion as separate gates.

Before any task is considered ready for implementation, each declared task definition must have:

- no unresolved scaffold placeholder tokens or default incomplete-status sentences
- no placeholder validation command such as `# Pending`
- a concrete objective and desired behavior
- concrete implementation target paths, or explicitly justified creatable target paths
- concrete implementation target paths for lifecycle planning artifacts the task will update during closeout. This commonly includes the active `task-definition.md`, paired `implementation-summary.md`, and any milestone evidence artifact created by the task.
- concrete repository-relative dependencies in `## Dependencies`
- concrete validation commands or inspection steps
- no implementation-blocking open questions

Use `## Dependencies` only for artifacts that must already exist before the task starts. If task `02` depends on a source file that task `01` is explicitly expected to create, reference task `01`'s `task-definition.md` or implementation-summary evidence as the dependency and keep the future file in `## Implementation Target Paths`. Otherwise readiness review will correctly report the future file as a missing dependency.

If the scaffolded task definitions are placeholders, refine only the declared task definitions from the milestone overview, upstream artifacts, and existing code context. Then run `<day-shift-cli> task readiness-review --task-definition <path>` after refinement, not before, and treat any remaining placeholder-heavy task as not ready.

### 3. Check Task Readiness Across The Milestone

After task artifacts exist, confirm each declared task can enter the task lifecycle.

For each task in milestone order:

- read the task `task-definition.md`
- run `<day-shift-cli> task readiness-review --task-definition <path>` when command-supported
- verify dependencies point to concrete repository-relative artifacts
- verify implementation target paths are clear
- verify validation commands or inspection steps are concrete
- verify open questions are not implementation-blocking
- verify the task does not depend on a later-numbered sibling or missing producer artifact
- verify the task no longer contains scaffold placeholders before trusting readiness status

In `readiness-only` mode, stop after this sweep and report:

- ready tasks
- blocked tasks
- missing evidence
- first recommended next task
- whether milestone reconciliation is premature

Do not update task implementation summaries or milestone reconciliation during readiness-only runs.

### 4. Execute Each Task

For each ready task, invoke the task lifecycle directly.

Canonical invocation:

```md
Prompt: .day-shift/prompts/user/task.next.md
Workflow: .day-shift/workflows/task.agent-lifecycle-guide.md
Task definition: <relative-path-to-task-definition>
Run evidence directory: .day-shift/runs/run-<run-id>/

Execute this task as a full cycle: start cleanly, implement within task scope, capture evidence, and close out the paired task artifacts.
```

Task execution rules:

- execute tasks in the order declared by the milestone overview
- keep each task inside its declared implementation target paths unless the task definition is updated to reflect a justified deviation
- preserve unrelated user changes across task boundaries
- run each task's declared validation commands or record why they were skipped, substituted, blocked, or inconclusive
- update each task's paired `implementation-summary.md`
- use the supported metadata sync/update command when task completion status changes. Completed task definitions should carry both `status: completed` and `readiness: completed` when paired implementation evidence is complete, but those front matter transitions should not be hand-edited when `<day-shift-cli> metadata sync-status-from-review` or `<day-shift-cli> task update` can apply them.
- run implementation-summary review before treating a task as complete when evidence sufficiency is uncertain
- record discovered work in the task summary instead of expanding the active task silently
- maintain per-task touched-file accounting:
  - expected target paths from the active `task-definition.md`
  - actual changed paths after implementation
  - any paths outside the expected targets and the task-definition deviation that justifies them
- before closing a task, compare actual changed paths with expected target paths and record deviations in both the task definition and implementation summary when scope changed
- when task validation touches CLI tests or command state, use isolated local state paths such as `DAY_SHIFT_STATE_DIR`, `XDG_CONFIG_HOME`, and explicit license-path environment variables rather than shared user state

Stop at the first implementation blocker unless one of these is true:

- the user requested `readiness-only`
- the user explicitly requested a full readiness sweep
- the blocked task is documented as independent and the user explicitly authorized continuing to later tasks

Do not silently reorder milestone tasks to keep momentum.

### 4a. Diff Sanity And Validation Quality Gate

Before marking a task complete, and again before starting milestone reconciliation, run a diff sanity pass over the task scope and any broad files touched by validation or test work.

Minimum evidence:

```sh
git diff --stat -- <task-and-implementation-paths>
git diff --numstat -- <task-and-implementation-paths>
wc -l <large-or-high-risk-changed-files>
```

Use targeted path arguments rather than broad repository output when possible. Include the selected milestone task artifacts and the implementation paths touched by the active task.

If task-scoped files are untracked, ordinary `git diff --stat` and `git diff --numstat` will not show their contents. In that case, record scoped `git status --short -- <task-and-implementation-paths>` plus `wc -l` for the untracked files, and use `git diff --no-index /dev/null <file>` only when content-level evidence for a new untracked file is needed. Do not treat empty `git diff` output as sufficient diff sanity when scoped status shows untracked task files.

Investigate before closeout when any of these appear:

- large unexpected deletions
- high-deletion changes in test files
- changed test files that shrink substantially while validation still passes
- file type changes, binary/text classification changes, or suspicious `file <path>` output
- generated fixtures or snapshots replacing broad hand-authored test coverage
- validation that could have passed because assertions, tests, or coverage were removed

When a large deletion or test shrinkage is intentional, record the reason in the task implementation summary. Otherwise repair the diff before treating validation as meaningful. Passing tests are not sufficient evidence when the diff suggests coverage may have been deleted.

### 5. Gate Milestone Reconciliation

Before starting milestone reconciliation, confirm every task under the milestone has:

- a present `task-definition.md`
- a present `implementation-summary.md`
- `implementation_status: completed`
- `status: completed`
- non-placeholder implementation evidence
- validation evidence or an explicit validation exception
- acceptance-criteria review or an explicit deferral
- final diff sanity evidence for each completed task or a documented reason it was not applicable

If any task summary is missing, pending, draft, blocked, or placeholder-heavy, stop reconciliation and report the next task or task-summary closeout step.

If task summaries are complete but diff sanity evidence is missing for high-risk changes, stop before reconciliation and close the evidence gap first.

The pending milestone `reconciliation.md` placeholder is expected before this gate. Do not treat its incomplete state as a defect while task execution is still in progress.

### 6. Reconcile The Milestone

Use `.day-shift/workflows/04-summarize-and-reconcile.md` and `.day-shift/prompts/user/implementation.next.md` for implementation-to-reconciliation handoff.

Canonical invocation:

```md
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.
```

Reconciliation rules:

- use the milestone overview plus completed task implementation summaries as the review inputs
- keep task implementation summaries as the source of truth for code and documentation changes
- create missing milestone `reconciliation.md` from `.day-shift/templates/milestone-reconciliation.md` if needed
- update existing reconciliation sections in place rather than regenerating the whole file
- record acceptance-criteria review, validation review, planned work, discovered work, backlog work, accepted residual work, follow-up tasks, review concerns, and final notes
- set `reconciliation_status` and `status` consistently with the review outcome
- preserve scaffold/create provenance in reconciliation front matter unless an explicit metadata update command changes it; record `reconciliation build` and `reconciliation review` evidence in body sections such as validation review, final notes, or review status rather than replacing the original `workflow_cli_command`
- run `<day-shift-cli> reconciliation review --milestone-overview <path>` after reconciliation when command-supported
- if reconciliation review reports blocking findings, repair reconciliation body evidence directly when needed, but apply CLI-supported status metadata repairs through `<day-shift-cli> reconciliation update` and rerun review until blocking findings are gone
- after each build or repair pass, re-open `reconciliation.md` and confirm every required section is populated with concrete milestone evidence rather than scaffold placeholder text before reporting success
- record remaining advisory reconciliation warnings explicitly as warnings, discovered work, backlog work, or accepted residual work with non-blocking rationale
- use CLI-compatible no-concern wording for completed reconciliations; prefer `None.` or a clearly accepted disposition in `## Review Concerns`, and do not describe unresolved concerns while `reconciliation_status: completed`
- keep unrelated full-suite failures out of `Discovered Work`, `Backlog Work`, `Accepted Residual Work`, and `Follow-Up Tasks` unless this milestone owns the fix; put unrelated validation notes in `Final Notes` or the final user report so reconciliation review does not treat them as unresolved milestone work
- do not create follow-up task artifacts unless a separate explicit planning prompt or user request invokes that layer

## Stop Conditions

Stop and report instead of improvising when any of these are true:

- the milestone overview is missing, unreadable, or not the active source of truth
- the milestone task list is missing, prose-only, unordered, duplicated, or contains invalid slugs
- task scaffolding would require inventing undeclared tasks
- required upstream specs, parent overviews, or producer artifacts are absent
- existing task directories conflict materially with the declared task set
- a task depends on a later-numbered sibling without an explicit approved exception
- a task is not ready to implement
- task implementation would require broad opportunistic cleanup outside declared task scope
- task validation cannot meaningfully confirm the task's acceptance criteria
- final diff sanity reveals unexplained high-deletion changes, file-type changes, or test coverage shrinkage
- not all task summaries are completed and non-placeholder when reconciliation is requested
- reconciliation evidence conflicts with completed task summaries
- reconciliation review has blocking findings after build or manual correction

When stopping, report the exact milestone or task, the blocking condition, and the next explicit artifact or decision needed to resume.

## Artifact Contract

This workflow may update only these artifact classes by default:

- declared task directories under the selected milestone
- task `task-definition.md` files under the selected milestone
- paired task `implementation-summary.md` files under the selected milestone
- repository code or docs within the active task's declared implementation target paths
- the selected milestone `reconciliation.md`

Derived state files under `.day-shift/state/` may be written only by explicit state, checkpoint, or sync commands named by the task, reconciliation workflow, or user. Do not hand-edit derived state as part of ordinary milestone execution.

This workflow must not automatically:

- invent undeclared tasks
- reorder milestone tasks silently
- skip blocked tasks to implement later siblings
- mark blocked tasks as completed
- update milestone reconciliation before all task summaries are complete
- create follow-up planning artifacts from reconciliation findings
- absorb unrelated cleanup outside task scope
- treat advisory review or validation output as authorization to write
- create alternate task-summary or reconciliation destinations

When CLI, workflow, and prompt surfaces disagree, prefer them in this order:

1. the selected milestone overview and its upstream contract artifacts
2. the selected task definition during that task's execution
3. the command-specific CLI contract for the exact operation being used
4. the workflow file governing the current stage
5. the matching layer/action prompt
6. prior summaries or conversational assumptions

## Output Contract

For successful full-cycle milestone completion, keep the final response concise and include:

- completed status or blocked status for the milestone
- task outcomes in milestone order
- changed paths, grouped by task when useful
- validations run and results
- validation commands skipped, substituted, blocked, or inconclusive
- milestone reconciliation status
- discovered work
- follow-up work
- next handoff

Detailed acceptance-criteria mapping should live in task implementation summaries and milestone reconciliation. Summarize only material deviations, unmet criteria, or unresolved review concerns in the final response.

Do not include unrelated dirty worktree state as its own final-report note unless it materially affected task scope, validation, reconciliation, or review risk.

If the run stopped early, say so explicitly and identify the first blocker.

Name the CLI commands, workflow files, and prompts actually used whenever they materially shaped the lifecycle outcome.

## Promptable Invocation

Use this invocation shape when you want the agent to run the full milestone lifecycle directly:

```md
Use `.day-shift/workflows/milestone.agent-lifecycle-guide.md`.
Also use:
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/prompts/user/milestone.next.md`
- `.day-shift/prompts/user/task.next.md`
- `.day-shift/prompts/user/implementation.next.md`

Milestone: <path-to-milestone-overview-or-directory>
Mode: implement
Constraints:
- scaffold only declared tasks
- complete scaffolded task contracts before readiness review when placeholders remain
- execute tasks in declared order
- stop on readiness or implementation blockers
- keep each task within its declared target paths
- account for expected versus actual touched files per task and record justified deviations
- run diff sanity checks before task closeout and before milestone reconciliation, including `git diff --stat`, `git diff --numstat`, and targeted `wc -l` for large changed files
- investigate unexplained large deletions, file-type changes, and test coverage shrinkage before treating validation as meaningful
- use isolated CLI state environment variables for command tests that touch user-local state
- update paired task implementation summaries and task closeout metadata
- reconcile only after every task summary is completed and non-placeholder
- run reconciliation review in a repair loop until blocking findings are gone or a blocker is reported
- do not report the full milestone complete until milestone-level `reconciliation.md` is populated, non-placeholder, reviewed, and either metadata-completed or explicitly blocked with the missing closeout evidence named
- report blocked or discovered work explicitly
- state the next handoff after the milestone
```

For task creation without implementation, set `Mode: scaffold-only`.

For read-only task readiness review, set `Mode: readiness-only` and keep the workflow read-only after task artifacts already exist.

For milestone closeout after tasks are already complete, set `Mode: reconcile`.
