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

# Phase Agent Lifecycle Guide

Use this guide when the user wants an agent to coordinate a full lifecycle at phase scope: verify the declared milestone set, create missing declared milestone artifacts, delegate each milestone through the milestone lifecycle, review phase evidence, and hand off the remaining work clearly.

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

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

- `.day-shift/workflows/02-plan-from-spec.md` owns phase-to-milestone planning and milestone scaffolding.
- `.day-shift/workflows/milestone.agent-lifecycle-guide.md` owns one milestone's full lifecycle.
- `.day-shift/workflows/04-summarize-and-reconcile.md` owns review-family boundaries and phase evidence review after milestone reconciliation exists.

The selected phase overview artifact remains the source of truth for the declared milestone set, milestone order, phase intent, acceptance criteria, upstream traceability, validation focus, and parent planning context. New phase scaffolds use `phase-overview.md`; supported legacy phases 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 phase and have it drive:

- phase startup and repository-state checks
- declared milestone-set verification
- milestone directory scaffolding for every declared milestone
- milestone-by-milestone execution using the milestone lifecycle guide
- phase evidence review from completed milestone reconciliations
- deterministic metadata-update recommendations or explicit updates when authorized
- final reporting of completed, blocked, deferred, and discovered work

## Inputs

Require these inputs before starting:

- phase overview path or phase directory path
- run mode: `scaffold-only`, `readiness-only`, `implement`, or `review`
- whether the agent may create missing milestone directories and paired milestone reconciliation placeholders
- whether the agent may perform approved milestone-scope code, doc, planning, or metadata edits through delegated milestone lifecycles
- whether phase or stale milestone status metadata may be updated after evidence review

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

When the user provides a phase directory, infer:

- phase overview: `<phase-directory>/phase-overview.md`, or `<phase-directory>/overview.md` for supported legacy artifacts
- milestone root: `<phase-directory>/milestones/`

## Canonical Surfaces

Use these surfaces intentionally rather than mixing ad hoc alternatives.

### CLI

- `<day-shift-cli> workflow explain --artifact <path>`
- `<day-shift-cli> planning next-action --artifact <path>`
- `<day-shift-cli> planning inventory --root <path>`
- `<day-shift-cli> planning gap-report --scope <path>`
- `<day-shift-cli> milestone new --phase-overview <path> --full-set`
- `<day-shift-cli> milestone review --milestone-overview <path>`
- `<day-shift-cli> phase review --phase-overview <path>`
- `<day-shift-cli> phase update --phase-overview <path> --field status=completed`
- `<day-shift-cli> milestone update --milestone-overview <path> --field status=completed`
- `<day-shift-cli> validation links-check --scope planning --artifact <path>`
- `<day-shift-cli> link materialize --dry-run --artifact <path>`
- `<day-shift-cli> link materialize --write --artifact <path>`
- `<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 phase or delegated milestone explicitly needs repository-wide evidence. For phase navigation and readiness decisions, prefer artifact-scoped validation against the selected phase overview or selected milestone overview.

### 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/milestone.agent-lifecycle-guide.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/workflow-guide.md`

### Prompts

- `.day-shift/prompts/user/phase.next.md`: canonical phase-to-milestone handoff prompt
- `.day-shift/prompts/user/phase.review.md`: canonical phase-layer review prompt
- `.day-shift/prompts/user/phase.recertify.md`: canonical phase-layer lifecycle hygiene prompt
- `.day-shift/prompts/user/milestone.next.md`: canonical milestone-to-task handoff prompt
- `.day-shift/prompts/user/milestone.review.md`: canonical milestone-layer review 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/implementation.next.md`: canonical implementation-to-reconciliation handoff 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 phase lifecycle should use phase-layer prompts first, milestone-layer prompts for the active milestone, and lower-layer prompts only through the delegated milestone lifecycle. Use recertify prompts when an existing artifact may be stale before advancing, reviewing, or relying on it; recertification remains read-only unless a separate explicit write request follows.

Mode-aware runtime evidence gate: preserve execution-mode evidence from task summaries through milestone reconciliation and phase review. Contract-only evidence may close contract-scope guidance or planning work, while runtime or hybrid phase acceptance requires reconciled Runtime Delta targets, runtime changed paths, executable validation evidence, or a structured validation exception for each blocked validation command. Phase review remains read-only evidence and does not authorize repairs, status mutation, or artifact creation without a separate explicit write command.

## Mode Semantics

Use the selected run mode to bound write authority before starting.

- `scaffold-only`: create missing declared milestone directories and paired milestone reconciliation placeholders, then stop. Do not complete milestone contracts, scaffold tasks, execute implementation work, reconcile milestones, run phase review, or update metadata.
- `readiness-only`: after milestone artifacts already exist or are explicitly scaffolded in the same request, check readiness without implementation writes. By default, check only the active milestone; run a phase-wide readiness sweep only when the user explicitly asks for one. Do not scaffold tasks, update implementation summaries, update reconciliations, or update metadata.
- `implement`: scaffold declared milestones when authorized, then run the active milestone as a full cycle before moving to the next milestone. Complete only the active milestone contract, scaffold only the active milestone's declared tasks, execute those tasks, complete implementation summaries, reconcile that milestone, then repeat for the next declared milestone.
- `review`: use only existing completed milestone reconciliations to run phase evidence review. Do not scaffold milestones or tasks, complete contracts, execute implementation work, reconcile milestones, or update metadata unless the user explicitly authorizes a separate metadata update after review evidence.

`Profile: full-cycle-strict` is compact invocation shorthand for `Mode: implement` plus the complete algorithm, stop conditions, delegated milestone lifecycle, safe-link gate, reconciliation re-open gate, and artifact contract in this guide. It does not add write authority; the invocation must still state whether phase metadata writes are authorized or read-only.

If the requested mode is ambiguous, infer the narrowest mode that satisfies the user request and report the assumption before any write-capable command.

## Legacy Runtime-Acceptance Compatibility

`runtime_acceptance` is newer planning metadata. An existing phase or milestone overview that omits it is a supported legacy input, not by itself an incompatible workspace or a reason to stop `milestone new`, `task new`, or the `full-cycle-strict` lifecycle. Do not invent a `runtime_acceptance` block merely because a lifecycle profile is strict, and do not describe the missing block as a required schema migration.

When the selected parent has no executable runtime evidence, continue the normal lifecycle with the legacy artifact unchanged. When its authored acceptance criteria, Runtime Delta, or other executable evidence makes runtime behavior genuinely in scope, stop before making a classification: whether runtime acceptance is required and which stable criterion IDs apply are product/planning decisions, not values the CLI can infer safely.

The current `metadata update` and layer-specific `phase update` / `milestone update` commands do not author nested `runtime_acceptance` structures, and `workspace migrate` only handles supported workspace-schema transitions. Do not recommend either command as a repair for a missing runtime-acceptance block. Request explicit authorization for a reviewed planning edit when that semantic decision is needed, then rerun the selected lifecycle command.

## Starting

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

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

Read broader surfaces only when phase 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 slice overview artifact
- `<day-shift-cli> workflow explain --artifact <phase-overview-path>`
- `<day-shift-cli> planning next-action --artifact <phase-overview-path>`
- `<day-shift-cli> planning inventory --root <phase-directory>`
- `<day-shift-cli> planning gap-report --scope <phase-overview-path>`
- `<day-shift-cli> validation links-check --scope planning --artifact <phase-overview-path>`
- `<day-shift-cli> validation smoke --scope planning --artifact <phase-overview-path>`

Use the selected phase overview to establish:

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

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

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

## Full-Cycle Algorithm

Run this loop for the selected phase.

For normal `implement` runs, use this minimum command spine. A phase overview or active milestone overview may add stricter validation or sequencing inside the active milestone, but it does not authorize task scaffolding or execution for later milestones before the active milestone is reconciled.

1. Inspect repository state and preserve unrelated user changes.
2. Confirm the phase overview has a valid ordered `## Milestones` section.
3. Run `<day-shift-cli> milestone new --phase-overview <path> --full-set` to create missing declared milestone directories and reconciliation placeholders.
4. After milestone scaffolding or any phase-overview body update, run the phase overview link-validation and materialization sequence: `<day-shift-cli> validation links-check --scope planning --artifact <phase-overview-path>`, then `<day-shift-cli> link materialize --dry-run --artifact <phase-overview-path>`, then `<day-shift-cli> link materialize --write --artifact <phase-overview-path>` when the dry-run reports `candidateCount > 0`, `previewChangedPaths` names the selected artifact, and the current run mode permits writes. Also run `<day-shift-cli> validation smoke --scope planning --artifact <phase-overview-path>` when declared-child, readiness, or local gap evidence is needed.
5. Pick the first declared milestone that is not already reconciled as completed.
6. Before completing the active milestone contract, read completed reconciliations from earlier declared milestones in the same phase when any exist, and check whether implementation decisions, deviations, discovered work, or validation findings require updating the active milestone's overview.
7. Complete only that active milestone's scaffolded milestone contract when the scaffold produced placeholders or prior reconciliation evidence changed its assumptions; do not complete later milestone contracts yet.
8. Run the active milestone lifecycle from `.day-shift/workflows/milestone.agent-lifecycle-guide.md` with `.day-shift/prompts/user/milestone.next.md`; that delegated milestone lifecycle owns scaffolding only that milestone's declared tasks, completing those task contracts, executing those tasks, completing implementation summaries, and reconciling that milestone.
9. Before leaving the active milestone, re-open its `reconciliation.md` and verify it is populated with concrete completed-task summary links, acceptance-criteria review, validation review, final notes, and a stated milestone verdict. Do not advance to the next milestone while the active milestone reconciliation still contains scaffold placeholder text.
10. After the active milestone has a completed, non-placeholder `reconciliation.md`, return to step 5 for the next declared milestone.
11. Stop at the first blocking milestone unless the user explicitly asked for a readiness sweep or independent-milestone continuation.
12. Run final phase inventory, gap-report, links-check, link-materialization dry-run, and smoke checks before phase review. Apply safe link materialization writes when the dry-run reports `candidateCount > 0`, `previewChangedPaths` stays inside the selected artifact scope, and the current request authorizes planning-artifact updates; otherwise report the dry-run output as administrative follow-up.
13. After every milestone has a completed, non-placeholder `reconciliation.md`, run `<day-shift-cli> phase review --phase-overview <path>`.
14. Treat phase review as read-only evidence unless the user explicitly authorized metadata updates.
15. If authorized and deterministic, update stale phase or milestone metadata with explicit `metadata sync-status-from-review`, `phase update`, or `milestone update` commands using `--active-artifact` when the handoff names the active artifact.
16. Report phase status, milestone outcomes, validation evidence, discovered work, and the next handoff only after every milestone reconciliation has been populated and reviewed, or report the first reconciliation blocker.

Metadata-hygiene recommendations from phase review are advisory evidence only. Do not apply recommended `metadata sync-status-from-review`, `phase update`, or `milestone update` commands unless the current request explicitly authorizes metadata writes. Do not hand-edit phase or milestone status metadata when one of those CLI commands can apply the deterministic transition.

Do not skip from milestone scaffolding to phase completion. Phase evidence review is eligible only after every declared milestone has completed reconciliation evidence, unless the user explicitly requested a readiness-only or partial review.

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 phase layer.

When phase work audits or adopts commands, use `commands search`, then `commands describe`; use `commands validate` for drift/input-coverage evidence and full inventory only for whole-surface audits. Fall back to command help when descriptor input coverage is missing.

When a phase or milestone validation command consumes compiled `dist/**` output, run the build or compile step before that validation. Do not parallelize `pnpm run build`, `pnpm run check`, or `pnpm exec tsc -p tsconfig.json` with tests or CLI commands that import `dist/**`; stale compiled output can create false failures or false passes.

Do not parallelize write-capable planning commands with evidence commands that are meant to observe the result of those writes. Run scaffold, build, update, or reconciliation writes first, then collect dependent status, inventory, validation, review, or diff evidence. This applies to commands such as `<day-shift-cli> milestone new`, `<day-shift-cli> task new`, `<day-shift-cli> implementation-summary build`, `<day-shift-cli> reconciliation build`, and explicit metadata update commands.

### 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 phase overview exists and is readable
- verify parent traceability paths are present when they define phase scope
- verify the phase's milestone list uses ordered milestone slug declarations in ascending order; accept raw backticked slug bullets and materialized Markdown-link slug bullets
- verify declared milestone slugs match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`
- verify existing milestone directories match the declared milestone set or identify drift before proceeding
- verify the phase does not require missing planning artifacts before milestone 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 phase 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 phase, active milestone artifacts, active task artifacts, and expected implementation paths when known
- identify the last completed lifecycle gate: milestone scaffold, milestone readiness, task execution, milestone reconciliation, phase review, or metadata update
- inspect partially edited files for the active milestone or 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 active milestone's review or readiness checks before executing tasks if no implementation edits were completed yet
- rerun the active milestone's reconciliation review before marking a partially completed milestone as done
- preserve the declared milestone order after resuming; do not skip ahead because a later milestone looks easier
- report any ambiguous resume state as blocked instead of claiming phase completion from uncertain evidence

### 2. Scaffold Declared Milestones

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

Canonical invocation:

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

Create all milestones listed in the phase overview by iterating the standard milestone-creation contract for each listed milestone, creating that directory if needed, using ordered milestone directory names and keeping traceability back to the source specs and parent planning artifacts.
```

Milestone scaffolding rules:

- create only milestones already declared in the phase overview
- preserve the declared milestone order
- use `<day-shift-cli> milestone new --phase-overview <path> --full-set` as the first choice
- create the phase `milestones/` directory if needed
- create one milestone directory per declared milestone slug
- create both `milestone-overview.md` and `reconciliation.md` in each milestone directory for new canonical artifacts
- support legacy `overview.md` milestone artifacts when they are the selected existing artifacts
- initialize milestone reconciliations as pending placeholders
- preserve upstream traceability to source specs and parent slice and phase artifacts
- do not mark newly scaffolded milestones as completed during phase-to-milestone planning
- do not create task definitions or implementation summaries during phase-to-milestone planning

Manual milestone 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 Only The Active Milestone Contract

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

After the phase-level milestone scaffold exists, do not complete every milestone overview up front. Complete one milestone contract at a time, immediately before that milestone enters its delegated lifecycle. This preserves phase order and avoids spending context on later milestones before earlier milestone evidence is complete.

For milestone 2 and later, contract completion must first review completed reconciliations from earlier milestones in the same phase. If prior implementation decisions, accepted deviations, discovered work, validation findings, or follow-up notes change the active milestone's assumptions, update only the active milestone overview before task scaffolding. Do not proactively update later milestone overviews.

When the phase overview names an earlier phase as a dependency, read that dependency phase's completed milestone reconciliations before completing the first active milestone contract in the selected phase. Treat accepted residual work, discovered work, implementation decisions, and validation findings from dependency phases as active-milestone contract input. If dependency phase evidence is missing, contradictory, or not completed enough to establish the active phase boundary, stop and report the sequencing blocker.

Before the active milestone is considered ready for the milestone lifecycle, its milestone overview must have:

- no unresolved scaffold placeholder tokens or default incomplete-status sentences
- a concrete purpose and scope
- a valid ordered `## Tasks` section
- concrete acceptance criteria
- concrete repository-relative dependencies
- concrete validation focus
- no planning-blocking open questions

If the active scaffolded milestone overview is a placeholder, refine only that declared milestone overview from the phase overview, upstream artifacts, prior completed milestone reconciliations when present, and existing repository context. Then run focused validation or review after refinement, not before, and treat a placeholder-heavy active milestone as not ready for the milestone lifecycle.

Do not scaffold, complete, review, or execute task artifacts for later milestones while the active milestone is unreconciled.

### 3. Check Active Milestone Readiness

After milestone artifacts exist, confirm the active milestone can enter the milestone lifecycle. A phase-wide readiness sweep is optional and read-only; it does not authorize task scaffolding or task execution for later milestones.

For the active milestone:

- read the milestone overview
- read completed reconciliations from earlier declared milestones in the same phase when any exist
- verify prior reconciliation decisions do not require active milestone contract updates, or make those active milestone updates before task scaffolding
- verify the milestone's `## Tasks` section is concrete, ordered, and implementation-oriented
- verify dependencies point to concrete repository-relative artifacts
- verify validation focus is clear
- verify open questions are not planning-blocking
- verify the milestone does not depend on a later-numbered sibling or missing producer artifact
- verify the milestone no longer contains scaffold placeholders before trusting readiness status
- use `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>` or `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` when local evidence is needed

If `links-check` reports hierarchy mismatches because a new canonical artifact uses `slice-overview.md`, `phase-overview.md`, or `milestone-overview.md` while the checker still expects a supported legacy `overview.md` path, do not rewrite canonical trace links by hand. Confirm the explicit links resolve locally, run focused `validation smoke --scope planning --artifact <phase-or-milestone-overview>`, record the links-check result as a validation-tool compatibility warning, and continue only when smoke/review evidence has no blocking findings.

In `readiness-only` mode, stop after the active-milestone readiness check and report:

- active milestone readiness status
- missing evidence
- first recommended next step
- whether phase review is premature

If the user explicitly requested a phase-wide readiness sweep, keep it read-only and instead report:

- ready milestones
- blocked milestones
- missing evidence
- first recommended next milestone
- whether phase review is premature

Do not update milestone reconciliations, task summaries, or phase metadata during readiness-only runs.

### 4. Execute The Active Milestone

For the active ready milestone, invoke the milestone lifecycle directly. Return here for the next milestone only after the current milestone has completed reconciliation evidence.

Canonical invocation:

```md
Prompt: .day-shift/prompts/user/milestone.next.md
Workflow: .day-shift/workflows/milestone.agent-lifecycle-guide.md
Milestone overview: <relative-path-to-milestone-overview>

Execute this milestone as a full cycle: scaffold declared tasks, complete task contracts, execute each task in order, capture implementation evidence, reconcile the milestone, and hand off clearly.
```

The milestone guide owns task scaffolding, execution, validation, task closeout metadata, touched-path accounting, and reconciliation. The phase layer adds only these orchestration constraints:

- execute declared milestones in order and complete one reconciliation before advancing
- preserve phase and milestone scope and unrelated user changes
- feed prior reconciliations into the next active milestone contract
- record discovered work rather than silently expanding scope
- return to the phase layer only after reconciliation review and re-open verification
- before phase review, investigate unexplained deletions, file-type changes, or test-coverage shrinkage across the combined milestone changes

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

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

Do not silently reorder phase milestones to keep momentum.

### 5. Gate Phase Review

Before starting phase evidence review, confirm every declared milestone under the phase has:

- a present milestone overview
- a present `reconciliation.md`
- `reconciliation_status: completed`
- `status: completed` in the reconciliation front matter
- completed task implementation summaries for every declared task under that milestone
- non-placeholder reconciliation evidence
- validation evidence or an explicit validation exception
- acceptance-criteria review or an explicit deferral

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

Treat scaffold placeholder text inside milestone reconciliation as a phase blocker after that milestone's tasks are completed. Do not accept a phase run as complete when any milestone `reconciliation.md` still says `Pending.`, `Pending milestone review.`, `Pending review after task implementation summaries are available.`, or `Pending. Add completed task implementation summaries as milestone execution work finishes.`.

If milestone reconciliations are complete but final diff sanity evidence is missing for high-risk changes, stop before phase acceptance and close the evidence gap first.

The phase overview may still carry stale `status` metadata at this point. Do not treat stale phase metadata as a blocker when downstream evidence is clear; treat it as a metadata-hygiene follow-up unless the user authorized the explicit update.

### 6. Review The Phase

Use `.day-shift/prompts/user/phase.review.md` and the planning review command family for phase closeout evidence.

Canonical invocation:

```md
Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Prompt: .day-shift/prompts/user/phase.review.md
Phase overview: <relative-path-to-phase-overview>

Review the phase against completed milestone overviews and milestone reconciliation evidence. Report blockers, warnings, metadata-hygiene follow-ups, administrative follow-ups, user decisions needed, and the suggested next step.
```

Phase review rules:

- use the phase overview plus completed milestone overviews and reconciliations as the review inputs
- keep milestone reconciliations as the source of truth for milestone-level acceptance, validation, discovered work, and follow-up evidence
- run `<day-shift-cli> phase review --phase-overview <path>` when command-supported
- keep phase review read-only by default
- separate blocking issues, missing evidence, warnings, satisfaction status, metadata-hygiene follow-ups, administrative follow-ups, user decisions needed, and suggested next steps
- treat metadata-hygiene recommendations as explicit commands to consider, not as authorization to write
- treat advisory review warnings as evidence only; they do not authorize writes or lifecycle changes by implication
- do not create follow-up phases, milestones, or tasks unless a separate explicit planning prompt or user request invokes that layer
- do not update phase or milestone metadata unless the current request explicitly authorizes metadata updates

When the user explicitly authorizes phase-completion metadata writes after an evidence review:

- use `<day-shift-cli> metadata sync-status-from-review --phase-overview <path>` or `<day-shift-cli> metadata sync-status-from-review --milestone-overview <path>` when the current CLI supports deterministic review-driven overview status sync
- use `<day-shift-cli> phase update --phase-overview <path> --field status=completed` for the selected phase when evidence deterministically supports completion
- use `<day-shift-cli> milestone update --milestone-overview <path> --field status=completed` for any stale milestone overview whose reconciliation or task evidence already proves completion
- include `--active-artifact <same-repository-relative-path>` when the handoff names an active artifact and the command supports active-artifact validation
- do not rewrite traceability, provenance, or reconciliation bodies during metadata-hygiene updates unless a separate explicit command requires it
- if a direct metadata edit appears necessary where a CLI sync or update command exists, stop before editing and report the command considered, why it cannot be used, the manual exception, and the artifact fields that would change

## Stop Conditions

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

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

When stopping, report the exact phase or milestone, 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 milestone directories under the selected phase
- milestone overview files under the selected phase
- milestone `reconciliation.md` files under the selected phase
- declared task directories and paired task artifacts under the active delegated milestone only
- repository code or docs within active delegated task implementation target paths

Phase metadata may be updated only when the user explicitly authorizes phase-completion or metadata-hygiene writes after evidence review. Derived state files under `.day-shift/state/` may be written only by explicit state, checkpoint, or sync commands named by delegated task or reconciliation workflows or explicitly requested by the user. Do not hand-edit derived state as part of ordinary phase execution.

This workflow must not automatically:

- invent undeclared milestones
- reorder phase milestones silently
- skip blocked milestones to implement later siblings
- scaffold task artifacts for later milestones while the active milestone is unreconciled
- complete later milestone contracts before prior milestone reconciliations have been reviewed for active-milestone impact
- mark blocked milestones as completed
- update phase metadata before milestone evidence is complete
- create follow-up planning artifacts from phase review findings
- absorb unrelated cleanup outside delegated task scope
- treat advisory review or validation output as authorization to write
- create alternate milestone, task-summary, reconciliation, or phase-review destinations

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

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

## Output Contract

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

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

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

Do not include unrelated dirty worktree state as its own final-report note unless it materially affected phase 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 compact invocation; the workflow owns the `full-cycle-strict` profile defined by its algorithm and artifact contract:

```md
Workflow: `.day-shift/workflows/phase.agent-lifecycle-guide.md`
Phase: <path-to-phase-overview-or-directory>
Mode: implement
Profile: full-cycle-strict
Phase metadata writes: authorized | read-only
```

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

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

For phase closeout after milestones are already reconciled, set `Mode: review`.
