---
prompt_version: 1
layer: phase
action: next
---

# Prompt: Phase To Milestone Overview

Use the selected phase overview to create the next milestone under that phase's `milestones/` directory, or iterate that same milestone-creation contract across all milestones declared in the phase overview when the user asks for the full set.

## Instructions

- Command placeholder: Expand `<day-shift-cli>` to the resolved session invocation. Use `day-shift` for installed/user mode after verification, and use `node dist/cli/index.js` in repository development mode when compiled `dist` output is current.
- Prefer command-supported scaffold, review, validation, update, and sync surfaces before inference or manual artifact edits. When no suitable command owns the needed change, record `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification` instead of inventing command behavior.
- When phase-to-milestone planning needs command evidence, use `<day-shift-cli> commands search <intent> --format json`, then `commands describe <exact-command> --format json`. Use `commands validate` for drift/input-coverage evidence and reserve `commands inventory` for whole-surface audits.
- This prompt is the canonical `next` action for the `phase` layer: it advances only from a phase overview into milestone planning. Do not reuse it as `build`, `review`, or as permission to skip directly to task, implementation, or reconciliation work.
- When this prompt is shown through a rendered prompt surface, keep generated context, agent entrypoint guidance, warnings, and prompt instructions as separate visible lanes in that order.
- Before relying on the rendered body, verify generated context identifies the requested prompt path, resolved layer and repository-relative path, source family, fallback trace, and user-layer destination; another source copy's presence is not active-prompt delivery evidence.
- Block child scaffolding unless the selected phase states `Target milestone count: N` and an authored `Decomposition rationale:` whose count matches the declared milestones and whose implementation, dependency, validation, rollback, or ownership boundary is not pattern-derived.
- Before invoking milestone creation, require one reviewed `## Scaffold Evidence` block per selected declared milestone with phase-ordered `criterion_ids`, concrete `ownership`, positive `target_task_count`, authored `decomposition_rationale`, and exactly that many ordered nested task entries.
- Require every nested task to carry child-specific `criterion_ids`, `current_behavior`, `desired_behavior`, repository-relative `dependency`, executable `target`, `validation`, and `rollback` evidence, plus an `adapter` path for command-facing behavior. The nested task union must exactly cover its milestone subset, and the selected milestone union must cover the phase criteria without unknown, omitted, or unreviewed overlapping IDs.
- If this pre-scaffold contract is incomplete, stop before `<day-shift-cli> milestone new`. After an authorized phase-body repair, rerun selected-phase link validation, safe materialization, and the same contract review in the current run evidence directory. Treat refinement-required command findings as atomic no-write evidence and resume through the same public command; never hand-create milestone artifacts as a workaround.
- Require each generated milestone with declared tasks to state `Target task count: N` plus its own authored, boundary-based decomposition rationale. Never invent either value from neighboring milestone shapes; one child is valid when one real boundary is sufficient.
- Before saving any generated milestone, run the canonical pre-save authoring audit. Reserve `define` for a named durable contract consumed downstream, use implementation verbs for executable outcomes, and treat a single/full-set rejection as atomic no-write evidence.
- For runtime-sensitive acceptance, make the milestone's declared order place a runtime or hybrid breakout early enough to preserve mode balance; a contract-first exception must satisfy the explicit dependency and rollback evidence rather than a naming convention.
- Choose a milestone slug and title that represent a meaningful checkpoint.
- Use an ordered milestone slug when sequence matters.
- Use the ordered milestone slug for path and metadata identity. In the visible H1 title, omit the leading ordered numeric slug prefix unless the number is part of the milestone's semantic title.
- Keep the milestone focused on acceptance criteria, task candidates, dependencies, risks, and validation focus.
- Create the minimum number of milestones needed to fully implement the phase; a phase may legitimately need one milestone when that milestone is enough.
- Do not create a prose-only milestone just to elaborate inferred phase detail. Keep that detail in the phase unless it creates a real acceptance, implementation, validation, rollback, or review boundary.
- When drafting the milestone `Tasks` section, default to `implement-*` task candidates that change code, runtime behavior, file outputs, or other executable repository behavior.
- Preserve execution-mode and Runtime Delta expectations across milestone planning. Contract milestones can freeze policy or template evidence, but any later runtime or hybrid milestone that implements that contract must reference the frozen contract and require Runtime Delta targets, runtime changed paths, executable validation evidence, or structured validation exceptions for blocked validation commands.
- In a generated milestone overview, `## Tasks` must declare at least one ordered task slug with a short description. Before link materialization, use raw backticked slug bullets such as ``- `01-implement-license-status-output`: implement human-readable and JSON license status reporting.``. After link materialization, the same declaration may be a Markdown link bullet such as `- [01-implement-license-status-output](tasks/01-implement-license-status-output/task-definition.md): implement human-readable and JSON license status reporting.`.
- Task slugs declared in milestone overviews must match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, be unique, and appear in ascending order.
- Do not leave prose-only task bullets or placeholder task text such as `To be planned.`, `TBD`, `TODO`, or `Pending.` in saved milestone overviews.
- Add a `document-*` task candidate only when later implementation would otherwise be blocked by a missing written contract, unresolved boundary, required shared decision, or evidence record that cannot safely live inside the implementation task.
- Do not create repeated `document-*` lanes by default. Allow at most one supporting `document-*` task per downstream implementation lane unless repository evidence shows multiple independent blockers with different target-path, validation, or rollback boundaries.
- Do not let a milestone that is expected to land executable behavior close out with documentation-only task candidates unless the user explicitly wants a documentation-only checkpoint.
- Draft task candidates as implementation-sized units: one coherent repository change that a standard implementation agent can complete, validate, and roll back independently.
- Give each task candidate one primary outcome and bounded likely target-path groups; split candidates when the work would require multiple independent outcomes, unrelated path groups, separate validation strategies, separate rollback paths, mixed readiness states, or more than one unresolved implementation decision.
- A milestone may declare one task when it has one coherent implementation outcome. Do not create a fixed number of task candidates by pattern; use only the number required by implementation, validation, rollback, readiness, and ownership boundaries.
- Merge trivial mechanical edits into the nearest related task candidate when they have no meaningful behavioral, contract, validation, or artifact impact, unless sequencing or rollback isolation requires a separate candidate.
- Do not write implementation instructions yet.
- Label assumptions explicitly instead of silently inventing scope, sequence, task decomposition, or validation detail.
- Create the phase `milestones/` directory first when it does not exist yet, then create the milestone directory beneath it.
- Use `.day-shift/templates/` as the project-local working customization surface for milestone scaffolding, without redefining packaged-default template-family membership in prompt text.
- Treat any prompt `template_ref` or `template_refs` metadata as source-template and output-shape guidance only; do not treat those references as permission to inline template bodies or infer scaffold destinations.
- Initialize a milestone-level `reconciliation.md` placeholder from `.day-shift/templates/milestone-reconciliation.md` so later review can roll up completed task summaries in one place.
- Treat that milestone-level reconciliation artifact as the default downstream review rollup, and do not imply that task-level reconciliation is created by default during milestone planning.
- The initialized milestone reconciliation is expected to remain incomplete during phase-to-milestone planning. Missing or incomplete reconciliation is not actionable until all task implementation summaries under that milestone are completed and non-placeholder.
- If CLI scaffolding is followed by manual edits, revise one file at a time: re-read the current file before patching it and avoid one bundled patch that mixes unrelated file bodies or stale context.
- Preserve traceability to the phase, slice, and source spec.
- Keep parent traceability explicit in milestone metadata by setting `upstream.slice_overview` and `upstream.phase_overview` to repository-relative parent overview paths.
- Keep upstream traceability shape aligned with the metadata contract (`upstream.specs` for multi-spec inputs, and explicit parent links such as `slice_overview` and `phase_overview`).
- Inherit `upstream.specs[*].source_type` from the parent phase overview or registered spec metadata. Do not recalculate it from the physical source-spec file type during milestone scaffolding.
- Record the actual CLI scaffold command in `workflow_cli_command`. If a `--full-set` command created the milestone, keep that `--full-set` command as the provenance instead of replacing it with an equivalent per-milestone command.
- Keep validation guidance aligned with the artifact-type matrix and strict-versus-standard boundaries from `.day-shift/specs/05-planning-artifacts/artifact-model.md`; do not invent new validation semantics.
- Preserve the canonical artifact-shape contract from `.day-shift/specs/06-templates-and-prompts/templates.md`: one visible H1, the required H2 section names in order, parser-safe `Open Questions` none-state, and no leaked scaffolding prose or unresolved placeholders in the saved artifact.
- When several milestones are created across one phase, use the phase's declared milestone sequence.
- For explicit full-set requests, iterate the same standard milestone-creation contract for each declared child milestone in order rather than inventing a separate batch contract.
- Full-set requests at the phase layer are layer-local: create milestone overviews and their required milestone-level reconciliation placeholders only. Do not create task definitions, implementation summaries beyond those required by a separate milestone-to-task request, or nested child scaffolds beneath those milestones unless a separate explicit programmatic nested-scaffold request names those layers.
- Wording such as `move downstream`, `plan next work`, `identify follow-up work`, or `suggest next step` is read-only by default at this layer; report candidate milestones and stop unless the user explicitly asks to create the milestone layer.
- Do not scaffold a later declared milestone while earlier declared milestones remain incomplete unless the user explicitly names that skip-ahead exception.
- Treat any future wizard-generated milestone suggestion as assistive guidance only; suggestion output does not authorize artifact-creating writes unless the user explicitly asks for creation.
- Do not invent additional milestones that are not already declared in the phase overview unless the user explicitly asks to revise the phase overview first.
- Reject undeclared milestones during full-set expansion instead of synthesizing new hierarchy.
- After creating milestone artifacts, run the previous planning layer's link validator: `<day-shift-cli> validation links-check --scope planning --artifact <phase-overview-path>`. Then run `<day-shift-cli> link materialize --dry-run --artifact <phase-overview-path>` and use `<day-shift-cli> link materialize --write --artifact <phase-overview-path> --validation-evidence-id <evidence-id>` only when the dry-run reports safe selected-artifact body-reference changes for newly resolvable milestone links, using the exact `validationEvidence.evidenceId` returned by that dry run. `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>` may also be used as read-only local trace-link evidence for each child milestone, and `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` may be used as focused read-only readiness/gap evidence for that milestone and to check the `declared-child-slugs` lane for task declaration syntax; that lane accepts both raw backticked slug bullets and materialized Markdown-link slug bullets. Treat validation findings as evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as permission to mutate metadata, create tasks, or update reconciliation.
- If focused validation says milestone reconciliation is premature and recommends advancing the next task, continue the requested downstream planning step instead of editing the reconciliation placeholder.
- If prompt-coverage validation evidence says the relevant layer/action contract is missing, contradictory, or unsupported, stop and surface that as explicit evidence instead of inventing fallback prompt semantics.
- Stop and report instead of guessing when the selected artifact and upstream evidence conflict materially.
- Use repository-relative paths throughout the artifact.

## Template Reference

Use these artifact shapes:

- `.day-shift/templates/milestone-overview.md`
- `.day-shift/templates/milestone-reconciliation.md`

## Required Output

Create:

- a milestone overview artifact with the canonical heading order from the template contract:

  - Purpose
  - Scope
  - Tasks
  - Acceptance Criteria
  - Dependencies
  - Risks
  - Validation Focus
  - Open Questions
- a pending milestone-level `reconciliation.md` placeholder initialized from `.day-shift/templates/milestone-reconciliation.md`
- both artifacts under `.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/`
