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:

.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:

- `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:

.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:

.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:

- `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:

.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:

.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:

.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:

- `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:

.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:

.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:

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