---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: plan-from-spec
---

# Plan From Spec

Use this workflow to turn a spec in `.day-shift/specs/` into planning artifacts under `.day-shift/planning/`.

This workflow now describes the current end-to-end planning contract for slice, phase, milestone, and task artifacts, including ordered directory naming and the full task directory shape.

Primary audience: human operators and agents performing planning artifact creation from source specs. Responsibility: define the planning procedure and scaffold contract; route reusable planning-layer, registry, metadata, command, and prompt/template responsibility detail to `.day-shift/references/planning-layers.md`, `.day-shift/references/spec-registry.md`, `.day-shift/references/metadata.md`, `.day-shift/references/commands.md`, and `.day-shift/references/prompts-and-templates.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.

## Inputs

- Selected spec from `<day-shift-cli> spec list` or `<day-shift-cli> spec search <query>`
- The selected spec's registered `source.ref` and source metadata
- `.day-shift/agents.md`
- `.day-shift/state/structural-pressure.json`, if it exists and structural-pressure context is relevant
- Relevant prompt from `.day-shift/prompts/user/`
- Relevant template from `.day-shift/templates/`, which is the project-local working customization surface for this repository

## Evidence Navigation

Use the source artifacts and read-only command output as navigation evidence while planning. Do not replace them with a dashboard, aggregate status page, or prose-only summary.

- Source-spec evidence starts with the selected specification file and its entry in `.day-shift/specs/index.json`. The registry supplies implementation order, destination, source reference, and linked planning context; the specification remains the current requirement source.
- Parent planning evidence is the nearest existing overview artifact in the hierarchy: canonical `slice-overview.md`, `phase-overview.md`, or `milestone-overview.md`, with supported legacy `overview.md` artifacts still readable during migration. Read its `upstream` metadata, declared child list, dependencies, risks, and validation focus before creating the next layer.
- Child-artifact evidence is the concrete artifact path created by the current stage, such as a slice `slice-overview.md`, phase `phase-overview.md`, milestone `milestone-overview.md`, task `task-definition.md`, paired task `implementation-summary.md`, or milestone `reconciliation.md`.
- Review and validation evidence comes from read-only outputs such as `<day-shift-cli> validation links-check --scope planning --artifact <path>`, `<day-shift-cli> validation smoke --scope planning --artifact <path>`, `planning inventory`, `planning gap-report`, `planning next-action`, and `workflow explain`. These outputs report current evidence and likely next steps; they do not repair links, mutate metadata, create artifacts, complete summaries, or reconcile milestones.
- Link materialization is a separate explicit write surface. After creating a child planning layer from an existing parent planning artifact, run `<day-shift-cli> validation links-check --scope planning --artifact <parent-artifact-path>` on the previous layer, then run `<day-shift-cli> link materialize --dry-run --artifact <parent-artifact-path>` to preview clickable Markdown link updates for newly materializable child references. Use `<day-shift-cli> link materialize --write --artifact <parent-artifact-path>` only when the dry-run reports safe selected-artifact body-reference changes. Do not treat validation output alone as permission to rewrite links, mutate metadata, or create another planning layer.
- Completion evidence stays with task `implementation-summary.md` files and milestone `reconciliation.md` files. Planning guidance may point to them, but it should not summarize completion in a way that hides those source artifacts.

## Minimal Path

Use this checklist for ordinary planning before reading the full detailed contracts.

1. Resolve the active artifact: selected spec, slice overview, phase overview, or milestone overview.
2. Confirm whether the request is create, revise, review, or read-only navigation.
3. For source-spec creation or revision, stop after the source spec and registry entry unless the user explicitly asks to create the next planning layer.
4. For planning creation, use the command-supported scaffold for exactly one next layer or the explicitly requested declared full set.
5. For revision, update the existing artifact in place; preserve traceability, parent links, declared children unless intentionally changed, and user-authored content outside the requested scope.
6. Run focused artifact validation or links-check when traceability, parent links, or generated shape need evidence.
7. When a child planning layer was created from a parent planning artifact, run the parent artifact's links-check and selected-artifact link materialization preview/write sequence so the previous layer's newly resolvable child references are materialized as Markdown links when safe.
8. Report the created or revised artifact path, command provenance or manual exception, validation and materialization evidence, and the next valid workflow step.

## Lifecycle Advancement Gates

Creating or revising a source spec does not create planning artifacts. Stop after the source spec and registry entry unless the user explicitly asks to create the next planning layer.

Do not advance from spec to slice, slice to phase, phase to milestone, or milestone to task unless the user explicitly requested that lifecycle step or an existing workflow command selected it as the active write.

Use intent words as gates:

- Source-spec-only intent: `create spec`, `capture spec`, `draft spec`, `revise spec`, `update spec`.
- Planning-advancement intent: `plan from spec`, `create slice`, `start planning`, `create next planning layer`, `scaffold slice`.

Review and navigation are read-only by default. If the discussion is about whether a spec is complete, or the user asks for a `second pass`, `review`, `harden`, `hardening`, `improve`, `improvement`, or `completeness` pass, edit only the selected source spec or report findings unless the user explicitly asks for downstream planning artifacts. When planning advancement is intended, use `<day-shift-cli> slice new --spec-id <id>` through this workflow instead of creating downstream artifacts from the source-spec review pass.

## Create Vs Revise

Creation and revision use different authority boundaries:

- Create: start from an existing parent artifact or registered spec, scaffold the canonical child destination first, and initialize required paired artifacts such as task `implementation-summary.md` or milestone `reconciliation.md` when the layer contract requires them.
- Revise: start from the existing target artifact, edit it in place, and do not create sibling, child, paired, or alternate artifacts unless the user separately asks for that creation step.
- If a create request points to an artifact that already exists, treat it as a revise request only when the user confirms that intent or the workflow command reports an idempotent scaffold outcome that preserves existing content.
- If a revise request reveals missing required paired artifacts, report the missing artifact and use the relevant create/build workflow only when the current request explicitly authorizes that write.

## Starting Point

- Start from `<day-shift-cli> spec list` or `<day-shift-cli> spec search <query>` before reading `.day-shift/specs/index.json` directly.
- Work in implementation order unless the user chooses a different priority.
- Treat `.day-shift/` references in this workflow as relative to the effective workspace root selected for the current invocation; repository-root and non-root workspaces are both supported when a valid in-repository `.day-shift/config.toml` marker is present.
- Before creating or revising a slice from older active specs, recertify the selected spec or related spec set when implementation evidence, workflow direction, command names, path conventions, or downstream planning may have changed since the spec was written.
- Use `.day-shift/prompts/user/specification.recertify.md` for this pre-slice hygiene step, and apply any user-approved spec/index cleanup before using `.day-shift/prompts/user/specification.next.md`.
- Treat emergent work as a separate intake lane rather than ordinary backlog churn or scope creep.
- When an emergent spec is captured locally, it should live under `.day-shift/specs/00-emergent/`.
- Emergent planning slices should use the `00` ordering lane, typically with a slice directory such as `00-emergent-<slug>`.
- When several specs in one directory belong to one implementation slice, treat them as one planning slice instead of planning them independently.
- Treat the registered `source.ref` as a generic source-spec reference; it may point inside or outside `.day-shift/`.
- Prefer repository-relative paths throughout all generated artifacts.
- Treat strict-mode metadata expectations as artifact-specific: specifications should follow the shared schema discipline without being forced to carry planning-only fields that belong to downstream artifacts.
- Use standard-mode assumptions for draft artifact authoring, and reference strict-mode failure behavior only for explicit validation checkpoints.
- Keep upstream traceability shape consistent with the metadata contract: use `upstream.specs` for multi-spec planning artifacts, and keep parent references (`slice_overview`, `phase_overview`, `milestone_overview`, `task_definition`) explicit by artifact level.
- For source/upstream traceability update tasks, keep one shared mutation contract in planning guidance: apply intended values directly for `upstream.specs`, compatibility-sensitive `upstream.spec`, and specification-family `source` references, and reject incomplete or lossy partial rewrites.
- For parent-link mutation tasks, keep one shared update contract in planning guidance: mutate only explicit applicable parent-link fields (`slice_overview`, `phase_overview`, `milestone_overview`, `task_definition`) in coordinated repository-relative updates, and reject partial stale-link rewrites.
- For status-transition metadata-update tasks, keep one shared status contract in planning guidance: update shared `status` independently from family-specific status fields, enforce artifact-family applicability (`readiness`, `implementation_status`, `reconciliation_status`), and reject cross-family or unsupported-token requests instead of normalizing them.
- For planning-coordinate metadata-update tasks, keep one shared planning-field contract in planning guidance: allow `slice`/`phase`/`milestone`/`task` and `planning_depth` updates only in explicit coherent transition scenarios, require coordinated updates of applicable identity-bearing fields (plus applicable parent-link paths when affected), and reject partial or contradictory coordinate rewrites.
- For prompt-front-matter metadata-update tasks, keep one prompt-family contract in planning guidance: update `prompt_version`, `layer`, and `action` by direct intended value, keep prompt semantics separate from artifact-family status/planning transitions, and reject artifact-field crossover or lossy cross-family rewrites.
- For template-front-matter and manifest metadata-update tasks, keep one family-aware contract in planning guidance: treat template Markdown front matter and manifest JSON as separate mutation surfaces, apply direct intended-value updates to in-scope keys, preserve unaffected fields and file identity (`path`, `kind`, `artifact_type`, and `template_ref`/`template_refs` shape where applicable), keep scaffold `destination` routing explicit instead of inferred, use `<day-shift-cli> manifest update --manifest <path> --field <key=value>` as the explicit manifest write surface, and reject lossy partial or cross-family rewrites.
- For non-planning metadata command-contract tasks, keep one explicit command contract per family in planning guidance: `<day-shift-cli> prompt update` and `<day-shift-cli> template update` remain front-matter-only surfaces, `<day-shift-cli> manifest update` distinguishes entry patch from guarded entry replacement, and `<day-shift-cli> spec update` limits updates to mutable spec-index fields while rejecting identity-bearing rewrites.
- For template-manifest update-boundary tasks, keep one explicit mutation-lane contract in planning guidance: entry patches preserve untouched fields for one existing `path`, guarded replacements preserve identity-bearing plus existing unrelated fields, prompt-manifest `template_ref`/`template_refs` stay in prompt-family lanes instead of being normalized into template-manifest routing, and wrong-family/ambiguous/inconsistent/under-specified/lossy requests remain blocking no-write failures.
- For template-manifest validation/reporting tasks, keep one shared contract in planning guidance: document template-manifest integrity, missing-version, version-availability, and drift findings from the template-family spec/manifest/test surfaces, use `<day-shift-cli> templates list` as the read-only template-family inventory surface, keep `<day-shift-cli> validation ...` scoped to read-only planning validation evidence rather than template-manifest enforcement, and require read-only report surfaces plus write-attempt surfaces to reuse the same failure taxonomy without writes.
- For file-scoped metadata validation tasks, plan against the current CLI validation surfaces: use `<day-shift-cli> validation smoke --scope planning --artifact <path>` for selected planning artifacts, `<day-shift-cli> validation links-check --scope planning --artifact <path>` for local trace-link evidence, and `<day-shift-cli> validation rollup --scope planning --artifact <path>` for aggregate validation evidence. Preserve selected-artifact versus directory/root semantics explicitly; do not replace file-scoped evidence with broader recursive cleanup unless the task asks for it.
- For metadata-update utility integration tasks, keep one caller-to-helper seam in planning guidance: require callers to identify the metadata family first, pass direct intended-value updates, delegate execution to shared helpers, and treat helper rejection as a blocking no-write outcome without command-local fallback rewrites.
- For generic metadata-update command-contract tasks, keep one explicit command surface contract in planning guidance: `<day-shift-cli> metadata update` and `<day-shift-cli> metadata validate-update` share one direct intended-value request shape (`--artifact <path>` plus one or more `--field <key>=<value>` assignments), route by metadata family to shared helpers, and enforce validate-update as read-only with no writes.
- For active-artifact handoff command-contract tasks, keep the scope narrow: `--active-artifact <path>` is an optional stateless guard for update commands, must match the selected artifact argument after repository-relative normalization, and rejects mismatches as blocking no-write evidence without creating persistent session context.
- When a planning task defines review or validation guidance, keep one shared no-write contract across `metadata validate-update`, planning review commands, implementation-summary/reconciliation review, `validation links-check`, and `validation smoke`: findings are evidence only, and any later write must stay a separately named command.
- For unsafe-update detection/reporting tasks, keep one shared failure/reporting contract in planning guidance: classify wrong-family, ambiguous, inconsistent, under-specified, and lossy mutation requests as blocking no-write failures, require no partial-write allowance, and align reporting to existing RuntimeError and finding-oriented validation surfaces.
- When planning metadata-update tasks, use the shared read/parse contract consistently: identify metadata-bearing family first, parse metadata region separately from untouched remainder content, preserve repository-relative path text during read, and treat missing/malformed front matter, malformed JSON manifests, and unsupported families as blocking parse failures.
- Keep read/parse extraction guidance separate from write-policy or narrow-mutation policy in planning text.
- When planning-navigation or local trace-link command work is in scope, keep `<day-shift-cli> planning inventory`, `planning gap-report`, `workflow explain`, `planning next-action`, and `validation links-check` read-only, evidence-driven, and bounded by declared hierarchy plus existing artifact state.
- When trace-link lifecycle disposition evidence appears, treat it as read-only validation context unless a separate write-capable command is explicitly selected: `link disposition add/update/delete` record lifecycle decisions, `link disposition preview` reports proposed migrated-link updates without writes, and migrated-only `link disposition apply` is the explicit write path. Do not let planning, validation, inventory, or review guidance imply automatic repair, inferred replacement targets, retired/deleted rewrites, external-target resolution, or unsupported body-reference rewrites.
- When planning validation is used for a selected artifact, prefer `<day-shift-cli> validation smoke --scope planning --artifact <path>` so inventory and gap-report evidence are scoped to that artifact. Repository-wide smoke output may include unrelated historical warnings and should not drive fixes for the current planning step.
- If compatibility evidence shows that the resolved workspace is unsupported, malformed, or partially upgraded, stop planning writes and route through the explicit workspace migration preview or confirmed-apply flow instead of manually relocating `.day-shift/` assets.
- Missing or incomplete milestone reconciliation is allowed while planning or moving downstream until every task under that milestone has a truly completed, non-placeholder `implementation-summary.md`. Before that all-complete gate, treat reconciliation findings or placeholders as future review context, not current fix work.
- Across all planning layers, choose the minimum number of slices, phases, milestones, and tasks needed to fully implement the selected scope. Add child artifacts only for real implementation, sequencing, validation, rollback, ownership, or review boundaries, not to produce extra prose from inference.
- Default new task scaffolds to `execution_mode: runtime`. Switch a task to `contract` only when it can complete with contract, planning, or frozen-evidence work and no runtime behavior change is required. Switch a task to `hybrid` only when milestone completion requires both runtime implementation evidence and preserved contract or handoff evidence in the same task.

## From Spec To Slice

Use:

- Command: `<day-shift-cli> slice new --spec-id <id>` or `<day-shift-cli> slice new --slice-id <id>`
- Prompt: `.day-shift/prompts/user/specification.next.md`
- Template: `.day-shift/templates/slice-overview.md`

Handoff map:

- Input: selected spec evidence from `<day-shift-cli> spec list` or `<day-shift-cli> spec search <query>`, the registered `source.ref`, and any recertification notes from `.day-shift/prompts/user/specification.recertify.md`.
- Action: scaffold or revise the slice overview with the slice creation command, using `.day-shift/prompts/user/specification.next.md` only as the next execution surface when prompt-driven authoring is needed.
- Output: `.day-shift/planning/<implementation-order>-<slice-slug>/slice-overview.md` plus slice `decisions/` and `notes/` holding directories.
- Next consumer: `.day-shift/prompts/user/slice.next.md`, `<day-shift-cli> phase new --slice-overview <path>`, and artifact-scoped validation such as `<day-shift-cli> validation links-check --scope planning --artifact <slice-overview-path>`.
- Evidence to inspect: the selected source specification file, its `.day-shift/specs/index.json` entry, the generated slice `slice-overview.md`, and read-only links-check output for the slice overview when local trace-link evidence is needed.

Before this step, run a recertification pass with `.day-shift/prompts/user/specification.recertify.md` when the selected spec is not newly written, when related specs may now collapse into one slice, or when prior implementation may have made some requirements stale. Do not carry stale or already-implemented requirements into the new slice overview.

Create:

```text
.day-shift/planning/<implementation-order>-<slice-slug>/slice-overview.md
.day-shift/planning/<implementation-order>-<slice-slug>/decisions/.gitkeep
.day-shift/planning/<implementation-order>-<slice-slug>/notes/.gitkeep
```

Do not require `--slice-overview` as an input for the initial spec-to-slice step. At this layer, the slice overview is the artifact being created. Use `--slice-overview` only for downstream commands that read or update an existing slice overview, such as phase creation or slice metadata updates.

Infer the CLI selection from the selected spec source and registered spec context. If the source has a registered spec id, use `--spec-id <id>`; if the selected source is better represented by a linked slice id, use `--slice-id <id>`. Do not require the operator to provide both the spec source and a duplicate command selector when the registry already makes the selector unambiguous.

Derive this planning root from registered spec context: use the registered `implementation_order` as the ordered prefix and the selected slice context as the stable source of `<slice-slug>`.

For lightweight or emergent `00-*` specifications, derive the destination under `.day-shift/planning/` as a new ordered slice directory such as `.day-shift/planning/00-<slice-slug>/slice-overview.md`. The `00-` planning directory is created by this step; it is not a prerequisite and should not be requested as an existing relative reference.

Concrete shared-slice example: `.day-shift/specs/05-planning-artifacts/artifact-model.md`, `.day-shift/specs/05-planning-artifacts/project-phase-milestone.md`, and `.day-shift/specs/05-planning-artifacts/task-workflow.md` share one registered planning destination at `.day-shift/planning/05-planning-artifacts/slice-overview.md`; when planning this slice, preserve all three upstream entries under `upstream.specs`. Existing repository artifacts that still use `.day-shift/planning/05-planning-artifacts/overview.md` are supported legacy inputs, not a destination promise for new scaffolds.

For the first slice, `01-product-contract` is a reasonable planning directory for `.day-shift/specs/01-product-contract/overview.md`.

When one spec directory maps to one slice, include the ordered planning directory name explicitly, such as `01-foundation`.

Treat `slice-overview.md` as the stable generated slice overview path beneath that ordered slice directory, not as an operator-chosen filename or alternate location. Treat existing `overview.md` siblings as supported legacy artifacts until an explicit migration workflow is selected.

When turning a specification into a slice overview, treat creation of the ordered slice directory as part of the same step rather than as a separate prerequisite the user must request first.
For command-supported planning artifact creation, agents must use the CLI command for the initial scaffold when the selected spec or linked slice id is already known. Manual creation is allowed only when the CLI is unsupported for the requested step, the CLI failed, or manual recovery is required after a verified scaffold problem. Use the prompt and template only for content that still needs human or agent judgment after CLI scaffolding.

For standard slice overviews, declare downstream phases in `## Phases` using ordered phase slug declarations with short descriptions. Before link materialization, use raw backticked slug bullets, for example:

```text
- `01-runtime-and-context`: establish shared runtime and repository context behavior.
```

After link materialization, the same declaration may be a Markdown-link slug bullet such as `- [01-runtime-and-context](phases/01-runtime-and-context/phase-overview.md): establish shared runtime and repository context behavior.`.

Require every declared phase slug to match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, remain unique within the slice, and appear in ascending order. Do not save standard slice overviews with prose-only phase bullets or unresolved placeholder phase text.

For emergent work, prefer an ordered planning directory such as `00-emergent-login-timeout` so the intake lane remains visible and distinct from roadmap-planned work, while the registered spec file uses a `00-YYYY-MM-DD-<slug>.md` name under `.day-shift/specs/00-emergent/`.

Each slice directory should also preserve lightweight holding areas for slice-level notes and decisions:

```text
.day-shift/planning/<implementation-order>-<slice-slug>/decisions/.gitkeep
.day-shift/planning/<implementation-order>-<slice-slug>/notes/.gitkeep
```

Initialize these directories with `.gitkeep` so they remain available before any human-authored notes or decision records are added.

After creating or updating a slice overview, use `<day-shift-cli> validation links-check --scope planning --artifact <slice-overview-path>` when local trace-link evidence is needed. For spec-to-slice creation there is no previous planning-layer parent artifact, so run `<day-shift-cli> link materialize --dry-run --artifact <slice-overview-path>` and, when the dry-run reports safe selected-artifact body-reference changes, `<day-shift-cli> link materialize --write --artifact <slice-overview-path>` against the created slice overview itself. Treat links-check findings as read-only evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as source-link, metadata, or hierarchy repair.

## From Slice To Phase

Use:

- Command: `<day-shift-cli> phase new --slice-overview <path> --phase-slug <slug>` or `<day-shift-cli> phase new --slice-overview <path> --full-set`
- Prompt: `.day-shift/prompts/user/slice.next.md`
- Template: `.day-shift/templates/phase-overview.md`

Handoff map:

- Input: an existing standard slice overview with ordered phase declarations, upstream spec traceability, and enough scope evidence to choose a single phase or the declared full phase set.
- Action: scaffold phase overview artifacts with the phase creation command, using `.day-shift/prompts/user/slice.next.md` only when the generated phase content needs prompt-guided refinement.
- Output: `.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/phase-overview.md` for each selected phase.
- Next consumer: `.day-shift/prompts/user/phase.next.md`, `<day-shift-cli> milestone new --phase-overview <path>`, and focused links-check evidence for each created phase overview.
- Evidence to inspect: the parent slice overview artifact, generated phase `phase-overview.md` files, each phase `upstream.slice_overview` link, and read-only validation output for any phase whose trace links or hierarchy need confirmation.

Create:

```text
.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/phase-overview.md
```

Create the phase only from an existing slice overview under the same ordered slice directory.
Agents must use the CLI command to scaffold one phase or the full declared phase set before refining generated content manually, unless one of the allowed manual exceptions applies.

Use ordered phase slugs when execution order matters, such as `01-runtime-and-context`.

Create the slice `phases/` directory first when it does not exist yet, then create the phase directory beneath it.

Keep parent traceability explicit in generated phase metadata by setting `upstream.slice_overview` to the repository-relative parent slice overview path.

If the slice overview declares `planning_depth: lightweight`, explain that a phase should not be created unless the work has grown beyond lightweight planning.

Each generated phase overview must declare downstream milestones in `## Milestones` using ordered milestone slug declarations with short descriptions. Before link materialization, use raw backticked slug bullets, for example:

```text
- `01-license-payload-contract`: define signed payload parsing and canonicalization behavior.
```

After link materialization, the same declaration may be a Markdown-link slug bullet such as `- [01-license-payload-contract](milestones/01-license-payload-contract/milestone-overview.md): define signed payload parsing and canonicalization behavior.`.

Require every declared milestone slug to match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, remain unique within the phase, and appear in ascending order. Do not save phase overviews with prose-only milestone bullets or unresolved placeholder milestone text.

For lightweight slices, the next planning layer is a direct task layer under the slice, not a phase. Use phase creation only after the lightweight boundary fails and the work is promoted to standard planning.

When creating several phases across one slice, use the phase sequence already declared in the slice overview instead of inventing a new ordering.

After creating phase overviews, run `<day-shift-cli> validation links-check --scope planning --artifact <slice-overview-path>` on the previous planning layer, then run `<day-shift-cli> link materialize --dry-run --artifact <slice-overview-path>` and, when the dry-run reports safe selected-artifact body-reference changes, `<day-shift-cli> link materialize --write --artifact <slice-overview-path>` so newly created phase references in the slice overview become clickable Markdown links. Use `<day-shift-cli> validation links-check --scope planning --artifact <phase-overview-path>` when local trace-link evidence is also needed for each child phase. Treat links-check findings as read-only evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as parent-link, metadata, or hierarchy repair.

## From Slice To Task For Lightweight Planning

Use this lightweight path only when a slice overview declares `planning_depth: lightweight` and the hard boundary in `.day-shift/workflows/lightweight-workflow-guide.md` still holds.

Use:

- Command: `<day-shift-cli> task new --lightweight --slice-overview <path> --task-slug <slug>`
- Prompt: `.day-shift/prompts/user/task.build.md`
- Templates:
  - `.day-shift/templates/lightweight-task-definition.md`
  - `.day-shift/templates/lightweight-implementation-summary.md`

Handoff map:

- Input: a lightweight slice overview whose target paths, dependencies, sequencing, and implementation risk still justify skipping phase and milestone layers.
- Action: scaffold the direct task directory under the lightweight slice with the task creation command, using `.day-shift/prompts/user/task.build.md` only when generated content needs prompt-guided refinement.
- Output: `.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/task-definition.md` and the paired lightweight `implementation-summary.md` placeholder.
- Next consumer: `.day-shift/prompts/user/task.next.md`, `.day-shift/workflows/03-implement-from-task.md`, task readiness review, and selected-artifact validation for the created task definition.
- Evidence to inspect: the lightweight slice overview artifact, the direct task `task-definition.md`, the paired lightweight `implementation-summary.md`, and read-only task readiness or validation output before implementation starts.

Create:

```text
.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/task-definition.md
.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/implementation-summary.md
```

Create the lightweight `tasks/` directory beneath the slice directory when it does not exist yet, then create one implementation-sized task directory beneath it.

Use ordered task slugs when execution order matters, such as `01-implement-emergent-slice-routing`.

Keep parent traceability explicit in generated lightweight task metadata by setting `upstream.slice_overview` to the repository-relative parent slice overview path. Do not invent `phase`, `milestone`, `phase_overview`, or `milestone_overview` fields for lightweight tasks because those parent artifacts do not exist.

Each lightweight task directory should include the paired task artifacts from the lightweight templates:

```text
.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/task-definition.md
.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/implementation-summary.md
```

When lightweight task directories require manual recovery after scaffold verification, initialize:

- `task-definition.md` from `.day-shift/templates/lightweight-task-definition.md`
- `implementation-summary.md` from `.day-shift/templates/lightweight-implementation-summary.md`

Record `workflow_provenance: manual-exception`, the intended task creation command, and the applicable `workflow_manual_exception` only when the CLI failed or manual recovery after scaffold verification is required.

Set `planning_depth: lightweight` in both paired task artifacts.

Set `readiness: needs more evidence` in lightweight task definitions unless all readiness evidence is present and no implementation-blocking questions remain.

Initialize `implementation-summary.md` as a pending placeholder so later implementation-summary build, review, and manual evidence completion have a stable task-level execution artifact to update.

After creating lightweight task artifacts, run `<day-shift-cli> validation links-check --scope planning --artifact <slice-overview-path>` on the previous planning layer, then run `<day-shift-cli> link materialize --dry-run --artifact <slice-overview-path>` and, when the dry-run reports safe selected-artifact body-reference changes, `<day-shift-cli> link materialize --write --artifact <slice-overview-path>` so newly created lightweight task references in the slice overview become clickable Markdown links. Use `<day-shift-cli> validation links-check --scope planning --artifact <task-definition-path>` when local trace-link evidence is also needed for the created task definition. Treat links-check findings as read-only evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as parent-link, metadata, or hierarchy repair.

For strict readiness-review parser conformance, keep `## Open Questions` in lightweight task definitions in one of these shapes:

- unresolved questions exist: one bullet per unresolved question
- no unresolved questions: exactly one non-empty line `- None currently.`

Do not append assumptions to the "none" line; record them in a dedicated `## Assumptions` section instead.

Do not create phase, milestone, or reconciliation artifacts on the lightweight path. Promote to standard planning first if the task no longer has clear target paths, resolved sequencing, low implementation risk, and low coordination pressure.

## From Phase To Milestone

Use:

- Command: `<day-shift-cli> milestone new --phase-overview <path> --milestone-slug <slug>` or `<day-shift-cli> milestone new --phase-overview <path> --full-set`
- Prompt: `.day-shift/prompts/user/phase.next.md`
- Templates:
  - `.day-shift/templates/milestone-overview.md`
  - `.day-shift/templates/milestone-reconciliation.md`

Handoff map:

- Input: an existing phase overview with ordered milestone declarations, parent slice traceability, and enough scope evidence to choose one milestone or the declared full milestone set.
- Action: scaffold milestone overview artifacts and their default milestone-level reconciliation placeholders with the milestone creation command, using `.day-shift/prompts/user/phase.next.md` only for prompt-guided milestone authoring.
- Output: `.day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/milestone-overview.md` and the sibling pending `reconciliation.md`.
- Next consumer: `.day-shift/prompts/user/milestone.next.md`, `<day-shift-cli> task new --milestone-overview <path>`, focused validation, and later `.day-shift/workflows/04-summarize-and-reconcile.md` after task summaries are complete.
- Evidence to inspect: the parent phase overview artifact, generated milestone `milestone-overview.md`, pending milestone `reconciliation.md`, declared task list, and read-only validation output for the milestone overview. The reconciliation placeholder is future review evidence, not a current repair target.

Create:

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

Create the milestone only from an existing phase overview under the same ordered phase directory.
Agents must use the CLI command to scaffold one milestone or the full declared milestone set before refining milestone content manually, unless one of the allowed manual exceptions applies.

Use ordered milestone slugs when execution order matters, such as `01-cli-runtime-baseline`.

Create the phase `milestones/` directory first when it does not exist yet, then create the milestone directory beneath it.

Keep parent traceability explicit in generated milestone metadata by setting `upstream.slice_overview` and `upstream.phase_overview` to repository-relative parent overview paths.

Preserve upstream source metadata from the selected phase overview when creating milestone artifacts. Do not reclassify `upstream.specs[*].source_type` from the source file extension or current artifact path; inherit the registered source type already carried by the parent planning artifact unless the source registry itself is intentionally revised.

Use the ordered milestone slug for filesystem identity and metadata identity. For visible H1 text, omit the leading ordered numeric slug prefix unless the number is part of the milestone's semantic title.

For CLI-created artifacts, record the actual scaffold command that created the artifact in `workflow_cli_command`. When a `--full-set` command creates several artifacts, each created child artifact should record that `--full-set` command rather than an equivalent per-child command.

Initialize milestone `reconciliation.md` from `.day-shift/templates/milestone-reconciliation.md` as a pending placeholder so later review can roll up completed task summaries in one place.

Each generated milestone overview must declare downstream tasks in `## Tasks` using ordered task slug declarations with short descriptions. Before link materialization, use raw backticked slug bullets, for example:

```text
- `01-implement-license-status-output`: implement human-readable and JSON license status reporting.
```

After link materialization, the same declaration may be a Markdown-link slug 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.`.

Require every declared task slug to match `^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$`, remain unique within the milestone, and appear in ascending order. Do not save milestone overviews with prose-only task bullets or unresolved placeholder task text.

Use the minimum number of task candidates needed to make implementation, validation, and rollback boundaries clear. A milestone may have one task when it has one coherent implementation outcome; split tasks when likely changes have independent runtime outcomes, unrelated target-path groups, separate validation strategies, separate rollback paths, mixed readiness states, or more than one unresolved implementation decision.

When creating several milestones across one phase, use the milestone sequence already declared in the phase overview instead of inventing a new ordering.

After creating milestone artifacts, run `<day-shift-cli> validation links-check --scope planning --artifact <phase-overview-path>` on the previous planning layer, then run `<day-shift-cli> link materialize --dry-run --artifact <phase-overview-path>` and, when the dry-run reports safe selected-artifact body-reference changes, `<day-shift-cli> link materialize --write --artifact <phase-overview-path>` so newly created milestone references in the phase overview become clickable Markdown links. Use `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>` when local trace-link evidence is also needed for the created milestone overview. Use `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` when you need the current readiness/gap signal for that milestone only. Treat links-check findings as read-only evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as parent-link, metadata, reconciliation, or hierarchy repair.

The pending milestone `reconciliation.md` placeholder is expected at this point. Do not update or complete it during phase-to-milestone planning, and do not treat its incomplete status as actionable until every task implementation summary under the milestone is complete.

## From Milestone To Task

Use:

- Command: `<day-shift-cli> task new --milestone-overview <path> --task-slug <slug>` or `<day-shift-cli> task new --milestone-overview <path> --full-set`
- Prompt: `.day-shift/prompts/user/milestone.next.md`
- Templates:
  - `.day-shift/templates/task-definition.md`
  - `.day-shift/templates/implementation-summary.md`

Handoff map:

- Input: an existing milestone overview with ordered task declarations, parent phase and slice traceability, and a pending milestone `reconciliation.md` placeholder.
- Action: scaffold each declared task directory with the task creation command, then refine placeholder task definitions before readiness review when generated content is not implementation-ready.
- Output: `tasks/<task-slug>/task-definition.md` plus the paired pending `tasks/<task-slug>/implementation-summary.md` for each selected declared task.
- Next consumer: `.day-shift/prompts/user/task.next.md`, `.day-shift/workflows/03-implement-from-task.md`, `<day-shift-cli> task readiness-review --task-definition <path>`, and implementation-summary closeout after task execution.
- Evidence to inspect: the milestone overview artifact, each generated task `task-definition.md`, each paired pending `implementation-summary.md`, the milestone `reconciliation.md` placeholder, and read-only task readiness or planning validation output. Completed implementation summaries, not task-directory presence, are the evidence that later makes milestone reconciliation eligible.

Create:

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

Use ordered task slugs when execution order matters, such as `01-document-runtime-entrypoint-contract`.

Create the milestone `tasks/` directory first when it does not exist yet, then create the task directory beneath it.

Each task directory should include:

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

When task directories are created by hand, initialize:

- `task-definition.md` from `.day-shift/templates/task-definition.md`
- `implementation-summary.md` from `.day-shift/templates/implementation-summary.md`

Agents must use the CLI command when creating one task or the declared full task set from a milestone overview. Fall back to hand-created task directories only when one of these named exceptions applies:

- `unsupported by CLI`
- `CLI failed`
- `manual recovery after scaffold verification`

Set `readiness: needs more evidence` in task definitions unless all readiness evidence is present and no implementation-blocking questions remain.

For strict readiness-review parser conformance, keep `## Open Questions` in task definitions in one of these shapes:

- unresolved questions exist: one bullet per unresolved question
- no unresolved questions: exactly one non-empty line `- None currently.`

Do not append assumptions to the "none" line; record them in a dedicated `## Assumptions` section instead.

Treat lightweight task handling as the direct task path for lightweight slices. Use lightweight task handling only when target paths are already clear, dependency and sequencing blockers are resolved, implementation risk remains low, and cross-artifact coordination pressure is minimal; otherwise promote the work into the standard phase, milestone, and task hierarchy.

When planning promotion-path tasks, document one canonical destination under the existing milestone `tasks/<task-slug>/` shape, preserve task-definition plus implementation-summary content expectations, require path-bearing metadata alignment, and make dry-run expectations explicit (source path, destination path, and front-matter changes with no writes).
When planning template- or prompt-command behavior, document one explicit no-write default, one explicit force boundary, visible dry-run or read-only reporting for `create` / `keep` / force-gated `overwrite` outcomes, and recovery guidance that stays evidence-only. Keep template workspace overwrite rules separate from prompt user-layer replacement semantics, and keep `<day-shift-cli> prompt init` scoped to one declared prompt identity materialized into `.day-shift/prompts/user/` rather than a bulk prompt bootstrap.
When template-command bootstrap work is in scope, keep the bootstrap contract explicit: `.day-shift/templates/` remains the local working customization surface, manifest `path` remains the identity-bearing workspace source path, and only scaffold/support entries with explicit `destination` metadata may install an additional output outside that workspace.

For read-only validation/review planning, keep findings, warnings, metadata-hygiene follow-ups, and recovery guidance separate. Use `.day-shift/references/validation-and-review.md` for reusable no-write boundaries and findings taxonomy, and `.day-shift/references/metadata.md` for selected-file versus directory metadata-validation boundaries.
For prompt/template command planning, keep source, destination, render mode, fallback, overwrite, degraded-mode, placeholder, and adjacent-family evidence lanes visible without authorizing cross-family writes. Use `.day-shift/references/prompts-and-templates.md` for prompt/template identity, source-template relationships, artifact-shape cleanup, and scaffold/support routing boundaries.
Treat prompt `template_ref` and `template_refs` as source-template and output-shape metadata only; they do not inline template bodies, select scaffold destinations, or authorize template-family writes.
When planning shared reporting-alignment coverage, require one reusable evidence model: selected family, surface mode, shared findings taxonomy, no-write state, version/drift/fallback/overwrite/degraded/placeholder evidence lanes, and adjacent-family context must stay visible as separate lanes without authorizing cross-family writes.
When template-command list/reporting work is in scope, keep the list contract explicit: role classification comes from the manifest-backed inventory contract, `destination` appears only for eligible scaffold/support entries, family-level `template_version` availability stays separate from per-entry `version` availability, and adjacent manifest-integrity or drift findings stay in their own visible lanes.
When planning single-template materialization work, keep one canonical command contract in guidance: `day-shift template materialize` takes exactly one `--template <manifest-path>` source selector plus exactly one destination lane (`--destination <repository-relative-path>` or `--manifest-destination` for entries that already declare explicit manifest routing), reports source and destination in separate visible lanes, and never falls back to `init`, prompt-family, or paired-build semantics.
When single-template materialization work is in scope, keep the command contract explicit: `day-shift template materialize` stays in the singular `template` command family, `--template <manifest-path>` selects the identity-bearing source entry, only `--destination <repository-relative-path>` or `--manifest-destination` may select the write target, and source-versus-destination reporting stays separate with no guessed routing from `artifact_type`, prompt metadata, or directory membership.
When planning single-template rendering behavior, keep one explicit placeholder contract in guidance: materialization must declare `--mode raw` or `--mode rendered`, rendered mode may accept only repeated `--placeholder <snake_case>=<value>` assignments, unresolved canonical placeholders stay blocking no-write evidence for rendered output, and dry-run/read-only reporting must show mode, provided inputs, unresolved tokens, source path, and destination path without mutating files.
When single-template rendering work is in scope, keep placeholder handling explicit: `--mode raw` is a verbatim source-copy lane, `--mode rendered` is the only finalized-output lane, repeated `--placeholder <snake_case>=<value>` assignments are the only allowed render inputs, and unresolved canonical placeholders remain blocking no-write evidence rather than permission to guess missing values.
When template- or prompt-diff/reporting work is in scope, keep one explicit read-only comparison contract in planning guidance: template diff preserves separate family-level `template_version` baseline drift and per-entry `version` drift lanes, prompt diff preserves requested prompt, resolved active-source path, resolved layer, source family, fallback trace, and user-layer destination alongside prompt-family version lanes, preserve any `create` / `keep` / force-gated `overwrite` state as explicit evidence lanes, and keep adjacent template-family findings as adjacent evidence rather than mutation authority.

Initialize `implementation-summary.md` as a pending placeholder so later implementation-summary build, review, and manual evidence completion have a stable task-level execution artifact to update.

When creating several tasks across one milestone, use the task sequence already declared in the milestone overview instead of inventing a new ordering.

After creating standard task artifacts, run `<day-shift-cli> validation links-check --scope planning --artifact <milestone-overview-path>` on the previous planning layer, then run `<day-shift-cli> link materialize --dry-run --artifact <milestone-overview-path>` and, when the dry-run reports safe selected-artifact body-reference changes, `<day-shift-cli> link materialize --write --artifact <milestone-overview-path>` so newly created task references in the milestone overview become clickable Markdown links. Use `<day-shift-cli> validation links-check --scope planning --artifact <task-definition-path>` when local trace-link evidence is also needed for the created task definition. Use `<day-shift-cli> validation smoke --scope planning --artifact <milestone-overview-path>` when you need milestone-level next-step guidance after task scaffolding. Treat links-check findings as read-only evidence only; treat link materialization as an explicit selected-artifact body-link write only, not as parent-link, metadata, implementation-summary, reconciliation, or hierarchy repair.

Each milestone directory should also preserve a milestone-level reconciliation artifact:

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

Initialize milestone `reconciliation.md` from `.day-shift/templates/milestone-reconciliation.md` as a pending placeholder so the default review rollup path exists before task implementation begins.

## Full-Set Creation Patterns

Use these conventions when the user wants more than the next single artifact:

- Canonical declared-child expansion contract: for explicit full-set requests, iterate only children already declared in the selected parent artifact, preserve that declared order, apply the same standard next-layer creation contract for each child, and reject undeclared children instead of synthesizing them.
- Full-set creation must preserve the parent's minimal decomposition: scaffold the declared children needed to implement the parent outcome, and revise the parent first if the declared child set looks over-split, prose-only, or pattern-driven.
- Mandatory CLI-first preflight for `.day-shift` planning work:
  - identify which `day-shift` command supports the requested step
  - confirm whether that command was run
  - if it was not run, record which allowed manual exception applies

- From a spec directory, create the linked slice overview first if it does not exist yet.
- From a slice overview, the user may ask for the next phase or for all phases listed in the slice overview; use `<day-shift-cli> phase new --slice-overview <path> --full-set` when the full set should be scaffolded. This creates phase overviews only.
- From a phase overview, the user may ask for the next milestone or for all milestones listed in the phase overview; use `<day-shift-cli> milestone new --phase-overview <path> --full-set` when the full set should be scaffolded. This creates milestone overviews plus required milestone-level reconciliation placeholders only.
- From a milestone overview, the user may ask for the next task or for all tasks listed in the milestone overview; use `<day-shift-cli> task new --milestone-overview <path> --full-set` when the full set should be scaffolded. This creates task definitions plus paired implementation-summary placeholders only.
- Full-set language is layer-local: one selected parent artifact, one child layer. It does not authorize nested expansion across phases, milestones, and tasks in one pass.
- Nested scaffolding requires an explicit programmatic request that names every layer to expand and should go through a read-only scaffold-plan preview before writes once that tooling exists. Until then, report the proposed nested structure and stop for confirmation instead of inferring approval.
- Wording such as `move downstream`, `plan next work`, `identify follow-up work`, `suggest next step`, or `continue planning` is read-only by default: report candidate next artifacts and stop unless the user explicitly asks to create or scaffold the specific layer.
- Treat any future wizard or CLI suggestion as assistive scaffolding only; suggestion output is read-only and does not authorize any artifact-creating write unless the user explicitly asks for that creation.
- When creating a full set, iterate the standard next-layer creation contract for each child artifact instead of inventing a separate batch-only contract.
- When a full-set command performs the scaffold, record that exact `--full-set` command in each generated child's `workflow_cli_command`; use an equivalent per-child command only when that per-child command was the command actually run.
- Use the sequence already declared in the parent artifact instead of inventing a new ordering.
- Do not invent additional phases, milestones, or tasks that are not already declared in the parent artifact unless the user explicitly asks to revise the parent artifact first.
- If the parent artifact indicates that the next planning layer should be skipped, such as `planning_depth: lightweight`, stop at the highest appropriate layer and explain why the full-set request should not expand further yet.
- If read-only guidance is sufficient before creation work starts, prefer `<day-shift-cli> planning inventory`, `planning gap-report`, `workflow explain`, `planning next-action`, or `validation links-check` to inspect the current hierarchy and trace links instead of inferring missing artifacts from directory reads alone.
- For focused validation during full-set creation, prefer `<day-shift-cli> validation smoke --scope planning --artifact <selected-parent-or-child-overview>` over repository-wide smoke. When it recommends advancing the next task because reconciliation is premature, continue the requested planning/scaffolding step instead of repairing the placeholder reconciliation.

## Prompts And Templates

- Prompts tell the agent what to do.
- Templates specify the artifact shape.
- For artifact creation, use both.
- Treat `.day-shift/templates/` as the project-local working customization surface, and use `.day-shift/references/prompts-and-templates.md` for prompt/template identity, `template_ref` and `template_refs` boundaries, manifest-backed template roles, scaffold/support routing, render lanes, and adjacent-family findings.
- Use `.day-shift/specs/06-templates-and-prompts/templates.md` as the canonical artifact-shape contract for visible H1 usage, required H2 names and order, parser-sensitive none-state formatting, and cleanup expectations.
- Use the canonical Day Shift double-brace placeholder form with lowercase snake_case names when describing unresolved-token checks or replacement expectations.
- When a prompt-facing surface renders planning guidance, keep four visible lanes distinct in this order: generated context, agent entrypoint guidance, warnings, then prompt instructions. Treat `.day-shift/agents.md` as the agent-entrypoint source and fail by default when that agent entrypoint is missing unless an explicit degraded mode is requested.
- Prompt-facing surfaces that require `.day-shift/agents.md` should fail by default when that agent entrypoint is missing; `--no-agent` is the only explicit degraded rendering escape hatch and must emit a visible warning lane.
- When prompt-show/rendering work is in scope, keep one explicit read-only rendering contract in planning guidance: preserve the four visible lanes in order, keep fallback evidence separate from degraded-mode warnings, require missing-agent failure by default, and treat `--no-agent` as the only explicit degraded render escape hatch.
- Treat templates as output shape only; keep all instructional policy in prompts/workflows and do not preserve scaffolding prose in rendered artifacts.
- Preserve milestone-level reconciliation as the default review rollup path, and treat task-level reconciliation as an explicit exception path only when later review needs a documented task-local artifact that milestone-level reconciliation cannot satisfy. Require explicit exception justification plus the evidence lanes for source task definition, paired implementation summary, parent milestone overview, and parent milestone reconciliation relationship; reject task directory presence, path-only inference, or incomplete milestone evidence as standalone eligibility signals.
- When manual edits are still needed after CLI scaffolding, edit one file at a time: read the current file immediately before patching it, keep each patch scoped to that file's live contents, and avoid bundling unrelated file bodies or stale context into one patch.
- For supported planning layers, `<day-shift-cli>` scaffolding commands are the mandatory first choice. Manual directory or placeholder creation requires one named manual exception and should record workflow provenance.
- For command-supported planning artifacts, record workflow provenance in front matter:
  - `workflow_provenance: cli` plus the actual scaffold command in `workflow_cli_command: "day-shift ..."` when the CLI created the artifact
  - `workflow_provenance: manual-exception` plus the skipped `workflow_cli_command` and one allowed `workflow_manual_exception` value when manual creation is justified
- Doctor enforcement: missing provenance is blocking for non-grandfathered artifacts. Legacy planning artifacts committed before 2026-06-17 are grandfathered as warnings until backfilled.
- Review prompts do not need template references unless they create follow-up artifacts.

## Post-render Cleanup

After generating or revising any planning artifact from a template, perform this required cleanup before saving:

- Preserve exactly one visible H1 and the canonical ordered H2 sections for the artifact family specified in `.day-shift/specs/06-templates-and-prompts/templates.md`.
- No unresolved placeholder tokens remain, including canonical double-brace lowercase snake_case tokens.
- Treat unresolved placeholder detection as a blocking completeness signal, not as permission to guess replacement values or continue with partial writes.
- No template-note scaffold prose remains.
- No generic instruction phrases remain from scaffolded template guidance.
- Any manual patch follow-up was applied file-by-file against current file contents rather than through one bundled multi-file context rewrite.
- In `## Open Questions`, none-state is exactly one non-empty line: `- None currently.`
- In `## Assumptions` (where required), none-state is exactly one non-empty line: `- None currently.`
- Parser-sensitive formatting rules are enforced from prompt/workflow contract text rather than stored as instructional prose in artifact sections.

Prompt layer matrix:

- `specification`
  - Prompt family role: planning entrypoint from source specification to slice intent.
  - Primary artifact relationship: reads specification context and creates or updates the slice overview.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/specification.next.md` -> `.day-shift/templates/slice-overview.md`
- `slice`
  - Prompt family role: expand one slice overview into phase planning.
  - Primary artifact relationship: reads a slice overview and creates or updates phase overviews.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/slice.next.md` -> `.day-shift/templates/phase-overview.md`
- `phase`
  - Prompt family role: expand one phase overview into milestone planning.
  - Primary artifact relationship: reads a phase overview and creates or updates milestone overviews plus milestone reconciliation placeholders.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/phase.next.md` -> `.day-shift/templates/milestone-overview.md`, `.day-shift/templates/milestone-reconciliation.md`
- `milestone`
  - Prompt family role: expand one milestone overview into implementation-sized task directories.
  - Primary artifact relationship: reads a milestone overview and creates or updates task definitions plus paired implementation summaries.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/milestone.next.md` -> `.day-shift/templates/task-definition.md`, `.day-shift/templates/implementation-summary.md`
- `task`
  - Prompt family role: hand one task definition into implementation execution.
  - Primary artifact relationship: reads the selected `task-definition.md` and updates the canonical paired `implementation-summary.md`.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/task.next.md` -> `.day-shift/templates/implementation-summary.md`
- `implementation`
  - Prompt family role: hand completed task execution evidence into milestone review rollup.
  - Primary artifact relationship: reads milestone context plus completed task implementation summaries and updates milestone `reconciliation.md` as the default downstream review surface.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/implementation.next.md` -> `.day-shift/templates/milestone-reconciliation.md`
- `reconciliation`
  - Prompt family role: turn review evidence into follow-up planning guidance.
  - Primary artifact relationship: reads reconciliation artifacts, defaulting to milestone review after implementation handoff and using task-level reconciliation only as an explicit exception boundary.
  - Canonical prompt/template pairing: `.day-shift/prompts/user/reconciliation.next.md` with follow-up planning output rather than a default new artifact template

Prompt action matrix:

- `build`
  - Supported layers: `specification`, `slice`, `phase`, `milestone`, `task`, `implementation`, `reconciliation`
  - Canonical action meaning: create or refresh the canonical artifact for the selected layer while preserving artifact-family shape and the downstream handoff contract.
  - Unsupported use: invented action synonyms, automatic lifecycle advancement because a build happened, or using `build` as a stand-in for review.
- `next`
  - Supported layers: `specification`, `slice`, `phase`, `milestone`, `task`, `implementation`, `reconciliation`
  - Canonical action meaning: advance exactly one declared handoff for the selected layer, including implementation handoff at `task`, milestone reconciliation handoff at `implementation`, and follow-up extraction at `reconciliation`.
  - Unsupported use: skipping declared intermediate layers, inventing undeclared children or alternate destinations, or collapsing downstream `task` / `implementation` / `reconciliation` responsibilities into one generic action.
- `review`
  - Supported layers: `specification`, `slice`, `phase`, `milestone`, `task`, `implementation`, `reconciliation`
  - Canonical action meaning: perform a read-only readiness or evidence evaluation for the selected layer.
  - Unsupported use: automatic artifact writes, automatic status-transition writes, or treating task-level reconciliation as the default downstream review rollup.
- `recertify`
  - Supported layers: `specification`, `slice`, `phase`, `milestone`, `task`, `implementation`, `reconciliation`
  - Canonical action meaning: perform read-only lifecycle hygiene for the selected layer by comparing current artifact intent, metadata, traceability, upstream context, downstream evidence, workflow direction, and repository behavior before deciding whether active scope should stay current, update, collapse, split, defer, close, supersede, or leave active input.
  - Unsupported use: scaffolding the next layer, implementing work, writing reconciliation, or silently mutating metadata without an explicit write request.

Prompt coverage validation and reporting:

- Evaluate prompt coverage against the canonical prompt layer matrix and prompt action matrix, not against filename guessing alone.
- Surface missing layer coverage, unsupported layer/action combinations, and review-path drift as explicit findings-oriented evidence.
- Treat milestone reconciliation as the default downstream review rollup and task-level reconciliation as an explicit exception path when evaluating review-handoff consistency.
- Keep prompt-coverage findings separate from template-manifest integrity, prompt-version metadata, and prompt-resolution precedence findings even when nearby commands or reviews report those other contracts too.
- Keep prompt-coverage validation/reporting read-only unless a separate direct update/write surface is explicitly invoked.
- Never treat missing or contradictory prompt coverage as permission to invent fallback prompt semantics, undeclared prompt surfaces, or alternate hierarchy.

## Planning Rules

Use action verbs to make the intended layer explicit before work starts and to keep phase, milestone, and task titles aligned.

| Verb | Use for | Avoid when |
| --- | --- | --- |
| `document` | Authoring or finalizing a written contract, rule, boundary, interface, decision, or evidence without changing executable behavior. | The work is executable or changes runtime behavior. |
| `capture` | Recording facts, observations, decisions, evidence, or context without changing behavior. | The artifact must establish or revise a contract. |
| `implement` | Code, runtime behavior, or other executable changes. | The request is documentation-only. |
| `review` | Evaluation, readiness checks, and gap detection rather than artifact creation. | The work is meant to create or revise the primary artifact. |
| `revise` / `update` | Changing an existing artifact in place. | The work is creating a new artifact from scratch. |
| `validate` / `verify` | Confirming behavior or contract evidence with tests, inspection, or review. | The work is primarily documentation or implementation. |
| `reconcile` | Rolling implementation evidence back up into milestone or phase status. | The work is still at the task-definition or implementation stage. |
| `plan` | Decomposing scope into the next artifact level. | The work is already implementation-sized and ready to build. |

Use `define` only for contract-setting work that creates or revises a durable boundary, schema, vocabulary, policy, rule, interface, or decision consumed by later work. Do not use `define` when the intended action is to initialize or scaffold an artifact, implement executable behavior, document explanatory prose, record evidence, review readiness, or validate behavior. Avoid mixed wording such as `implement or define`; choose the verb that owns the concrete deliverable.

When a request needs both documentation and implementation, split the work or say so explicitly. Use `document-*` for written contract or evidence work and `implement-*` for executable behavior changes.

When decomposing a milestone into tasks, default to `implement` task names and executable task scopes unless there is a compelling dependency reason to create a documentation-only task first. A `document-*` task is justified only when later implementation would otherwise be blocked by a missing written contract, unresolved boundary, required shared decision, or evidence record that cannot safely be absorbed into the code task itself.

When a milestone is expected to land repository code, runtime behavior, file outputs, or executable workflow behavior, do not create `document-*` task sequences merely to restate the milestone in smaller prose artifacts. If the intended next step changes executable behavior, make the task an `implement-*` task by default.

- For planning directories created from registered specs, prefix the slice directory with the spec's `implementation_order`.
- If several specs are planned as one slice, use the shared implementation-order prefix and one stable slice slug.
- Use `00` for emergent planning slices that were introduced by user testing, environment failure, production failure, or another externally surfaced priority interruption.
- Use ordered phase, milestone, and task directory names where ordering improves traceability.
- Use the minimum viable hierarchy: one slice can contain one phase, one phase can contain one milestone, and one milestone can contain one task when that is enough to fully implement the scope with clear validation and rollback.
- Split into more phases, milestones, or tasks only for meaningful differences in implementation outcome, dependency order, validation strategy, rollback path, ownership boundary, risk, or readiness state.
- Merge trivial, prose-only, or purely inferred child artifacts back into the nearest implementation-bearing parent or sibling unless keeping them separate is required for sequencing, reviewability, or rollback isolation.
- Each slice directory should preserve stable artifact paths for `slice-overview.md`, `decisions/.gitkeep`, and `notes/.gitkeep`.
- Each phase directory should preserve stable artifact paths for `phase-overview.md` and its `milestones/` container.
- Keep slice artifacts about intent and boundaries.
- Keep phase artifacts about major slices of work.
- Keep milestone artifacts about acceptance checkpoints.
- Keep task artifacts implementation-sized.
- Use the declared `planning_depth` consistently in downstream planning artifact metadata and stop expanding the plan when the source indicates the next layer should be skipped.
- Do not put implementation results into task definitions.
- Do not over-plan tiny changes.
- Do not skip task evidence for code changes.
- Each task directory should preserve stable artifact paths for definition and implementation summary.
- Each milestone directory should preserve stable artifact paths for `milestone-overview.md`, task directories, and milestone-level reconciliation.
- Use `needs more evidence` until readiness evidence is present.
- Use repository-relative paths.
- Preserve aligned upstream traceability wording in generated guidance and task artifacts so `upstream.spec` versus `upstream.specs` usage remains intentional rather than ad hoc.

## Overview Update Guidance

When planning changes to existing slice, phase, or milestone overview artifacts, use the corresponding `<day-shift-cli> slice update`, `<day-shift-cli> phase update`, or `<day-shift-cli> milestone update` commands rather than hand-editing YAML front matter.

### Slice Overview Updates

Use `<day-shift-cli> slice update --slice-overview <path> --field status=<value> --field planning_depth=<value>` to update slice-level metadata directly.

- Apply updates to `status` and `planning_depth` fields.
- Reject requests to change `readiness`, `implementation_status`, or `reconciliation_status` on slice overviews (these fields do not apply).
- If `slice` identity must change, ensure the update includes explicit hierarchy context; partial rewrites will be rejected.
- Preserve upstream specification traceability (`upstream.specs`) and unaffected metadata during updates.

### Phase Overview Updates

Use `<day-shift-cli> phase update --phase-overview <path> --field status=<value> --field planning_depth=<value> --field phase=<value>` to update phase-level metadata.

- Apply updates to `status`, `planning_depth`, and `phase` fields.
- Reject requests to change `readiness`, `implementation_status`, or `reconciliation_status` on phase overviews (these fields do not apply).
- If `phase` identity changes, require explicit parent-slice context or coherent hierarchy transition story.
- Validate `planning_depth` changes for consistency with phase context.
- Preserve upstream specification traceability and unaffected metadata during updates.

### Milestone Overview Updates

Use `<day-shift-cli> milestone update --milestone-overview <path> --field status=<value> --field planning_depth=<value> --field milestone=<value>` to update milestone-level metadata.

- Apply updates to `status`, `planning_depth`, and `milestone` fields.
- Reject requests to change `readiness`, `implementation_status`, or `reconciliation_status` on milestone overviews (these fields do not apply).
- If `milestone` identity changes, require explicit parent-hierarchy context and coordinated parent-link updates; partial rewrites will be rejected as inconsistent.
- Validate `planning_depth` changes for consistency with milestone context.
- Preserve upstream specification traceability and unaffected metadata during updates.

## Structural Pressure Checks

Use lightweight structural-pressure review during planning when a spec, slice, phase, milestone, or task is expected to touch existing large modules or introduce module-splitting work. Use `.day-shift/references/validation-and-review.md` for classification meanings, sync policy, and the Markdown-versus-derived-JSON source-of-truth rule.

### When To Apply It

Apply this check when any of the following is true:

- the planned work touches an already-large file
- the planned work proposes extraction from one module into several helpers
- the planned work crosses orchestration, validation, or contract-heavy module boundaries
- the planned work looks like readability or navigability work even if the user did not ask for a dedicated refactor slice

### What To Record

At the planning layer that is sizing the work, record whether the touched surface is an existing hotspot, whether the planned work reduces or preserves pressure, whether the boundary is local-first, and whether residual pressure needs follow-up.

### When To Read `structural-pressure.json`

Read `.day-shift/state/structural-pressure.json` during planning only when at least one of the following is true:

- the planned work touches a known large or mixed-responsibility file
- the planned work appears to revisit a previously deferred structural concern
- the user asks whether the work is reopening an existing hotspot or follow-up candidate

When read, use it to identify the active status, latest classification, and prior artifact that recorded the classification.

### When Not To Write It

Do not update `.day-shift/state/structural-pressure.json` while creating or revising planning artifacts.

- Planning may reference the current-state index, but should not mutate it before implementation and reconciliation confirm the current state.
- If planning reveals a likely future status change, record that expectation in the planning artifact instead of pre-writing the state file.

### Planning Guidance

- Prefer responsibility-first reasoning over line count alone.
- Treat soft size thresholds as planning signals, not mandatory split points.
- Prefer family-local extractions before introducing new shared utility layers.
- If the work primarily lands product behavior but also touches a structural hotspot, absorb the structural-pressure note into the existing planning artifact instead of creating a separate refactor slice by default.
- Create a dedicated structural slice only when the work spans many unrelated modules, lacks a stable baseline, or needs repository-wide prioritization before safe implementation can start.

### Task Decomposition Guidance

When turning a milestone into tasks and structural pressure is present:

- keep tasks narrow enough that behavior-preservation checks remain credible
- separate producer tasks from consumer or repointing tasks when a new module boundary must land first
- name explicit follow-up work when a file will remain intentionally large or mixed after the current task
- avoid documentation-only planning churn when the structural improvement can be safely absorbed into one implementation-sized task

## Directory Handoff Notes

- Treat relative path placeholders as either existing references or destination targets depending on command context.
- Existing-reference placeholders must point to artifacts or directories that already exist before the workflow step starts.
- Destination placeholders name artifacts or directories the current creation step should write, so they do not need to exist yet; their parent context must still be derivable from an existing source artifact, index entry, or explicit command input.
- For spec-to-slice creation, prefer a concrete existing `Spec source:` path and infer the `slice new` selector plus planning destination from registered metadata. Do not ask for a slice overview relative reference before the slice overview exists.
- `[Relative Path To Spec File]`: source spec file, such as `.day-shift/specs/01-product-contract/overview.md`.
- `[Relative Path To Spec Directory]`: source spec directory, such as `.day-shift/specs/01-product-contract/`.
- `[Planning Slice Directory Name]`: ordered slice directory name under `.day-shift/planning/`, such as `01-product-contract` or `02-foundation`.
- `[Relative Path To Slice Overview]`: existing slice overview when the workflow reads or revises one.
- `[Relative Path To Slice Overview Destination]`: repository-relative output path for a slice overview being created; the path may be missing before creation.
- `[Relative Path To Phase Overview]`: existing phase overview.
- `[Relative Path To Phase Overview Destination]`: repository-relative output path for a phase overview being created.
- `[Relative Path To Phase Milestones Directory]`: phase milestone container directory.
- `[Relative Path To Milestone Overview]`: existing milestone overview.
- `[Relative Path To Milestone Overview Destination]`: repository-relative output path for a milestone overview being created.
- `[Relative Path To Milestone Directory]`: milestone directory.
- `[Relative Path To Task Directory]`: standard task directory.
- `[Relative Path To Lightweight Task Directory]`: lightweight task directory.
- `[Relative Path To Task Definition]`: task `task-definition.md`.
- `[Relative Path To Implementation Summary]`: task `implementation-summary.md`.
- `[Relative Path To Reconciliation Artifact]`: milestone or task `reconciliation.md`.

- If the user points to a spec directory, include the intended ordered slice directory if it is already known.
- When the work comes from specs, prefer names like `01-product-contract` or `02-foundation` so planning stays in implementation order.
- When creating a new slice directory from a spec, prefer `<day-shift-cli> slice new ...`; the resulting slice should still preserve `decisions/` and `notes/` directories initialized with `.gitkeep`.
- If the work is emergent, say so explicitly and keep the planning directory in the `00-emergent-<slug>` lane unless the user chooses a different naming convention.
- If multiple specs in the directory belong to one planning slice, say that they should be planned together.
- If the user wants a specific phase, say whether the slice overview already exists or whether it should be created first.
- When one spec directory maps to one slice, include the ordered planning directory name such as `01-foundation` so slice creation and phase creation stay aligned.
- If the user wants the whole phase set, use the phases listed in the slice overview.
- Each phase directory should preserve `phase-overview.md` and its `milestones/` container so milestone planning has a stable home.
- If the user wants the whole milestone set, point to the phase overview and use the milestones listed there.
- When creating milestones from a phase, keep milestone names and ordering aligned with the phase overview instead of improvising new checkpoints.
- If the user wants the whole task set, point to the milestone overview and use the tasks listed there.
- When creating tasks from a milestone, use ordered task directory names so the task sequence is visible in the filesystem as well as in the milestone overview.
- Each task directory should include `task-definition.md` and `implementation-summary.md` so implementation has stable artifact paths; `<day-shift-cli> task new ...` should be the first choice when it can create that shape directly.
- Each milestone directory should include `milestone-overview.md` and milestone-level `reconciliation.md` so review has a stable rollup path across related tasks.
- When standard milestone and task directories are created by hand, initialize `implementation-summary.md` from `.day-shift/templates/implementation-summary.md` and milestone `reconciliation.md` from `.day-shift/templates/milestone-reconciliation.md`; prefer the CLI scaffold first where supported.
- If phase naming is not obvious, propose the phase slug and title from the slice scope while preserving ordered naming.

## Index Updates

When a spec gets a linked slice, update `.day-shift/specs/index.json` with the planning path or linked slice metadata if it helps traceability.
