# Planning Layers Reference

This reference is the compact responsibility map for Day Shift planning layers. It is documentation-only and does not change planning algorithms, scaffold destinations, metadata behavior, or review eligibility.

## Choose A Workflow Level

Workflow level controls planning organization. It does not choose the evidence profile, agent mode, action authority, validation strength, or safety boundary.

| Level | Choose it when | Canonical active shape |
| --- | --- | --- |
| Basic | One independent, implementation-sized task has known targets, resolved sequencing, and low coordination pressure. | `.day-shift/planning/basic/tasks/<task-id>/` with `task-definition.md` and `implementation-summary.md`. |
| Structured | Normal planned-feature work needs a shared specification, one overview, and one or more direct tasks without staged review layers. This is the default when valid specification input exists and no explicit level or parent context overrides it. | `.day-shift/planning/structured/<work-id>/overview.md` plus direct `tasks/` and an optional `project-review.md`. |
| Governed | Large, risky, long-running, cross-team, or formally reviewed work needs staged hierarchy and reconciliation. | `.day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md`, then phases, milestones, tasks, reconciliations, and project review. |

Specification creation, refinement, review, and planning-readiness disposition happen before and independently from workflow selection. Specifications remain canonical under `.day-shift/specs/`; planning and promotion reference them without moving them.

Basic is not “less safe,” and Governed does not grant an agent more authority. All three levels use explicit task scope, readiness, implementation evidence, read-only review, and separately authorized writes. Day Shift may recommend a level or promotion, but the user must explicitly select the level and apply any structural change.

## Layer Sequences

```text
Basic:     task definition -> implementation summary
Structured: specification -> work overview -> direct tasks -> project review/close
Governed:  specification -> numbered slice overview -> phase -> milestone -> task -> implementation summary -> reconciliation -> project review/close
```

The former top-level numbered planning layout and `planning_depth: lightweight|standard` remain compatibility inputs only. New work writes to `basic/`, `structured/`, or `governed/`; structural migration is explicit and preservation-first.

Review, validation, inventory, and navigation commands provide evidence about these layers. They do not create, repair, advance, promote, migrate, accept, or reconcile artifacts unless a separate write-capable command is explicitly invoked.

## Specification

Specifications describe source intent and are registered through `.day-shift/specs/index.json`. They may be external references or repo-local Markdown files.

- Producers: human operators, product or engineering planning sources, and recertification work that captures or refreshes source intent.
- Primary consumers: spec selection commands, slice planning, planning inventories, and downstream traceability checks.
- Parent dependencies: none inside the Day Shift planning hierarchy; external source material may remain the originating reference.
- Child dependencies: slice overviews consume registered specification identity, source references, intended planning depth, implementation order, and destination context.
- Downstream usage: specifications define why work exists, what is in scope, what is out of scope, and which outcomes downstream planning must preserve.
- Expected outputs: a registered spec entry and, when the source is repo-local, a specification Markdown artifact with one visible title, source metadata, goals, scope, non-goals, requirements, and acceptance criteria.
- Evidence handoff: downstream planning artifacts preserve source traceability through `upstream.specs` and should point readers back to the selected source spec instead of replacing source intent with status summaries.

## Slice Overview

Slice overviews are Governed planning artifacts. They group implementation order and scope and declare downstream phases.

- Producers: the specification-to-slice planning workflow after a registered source spec is selected and any needed recertification is complete.
- Primary consumers: phase planning, workflow navigation, validation, and documentation that needs the Governed slice-level boundary.
- Parent dependencies: registered specification metadata and source-spec content.
- Child dependencies: Governed slices declare ordered phase slugs.
- Downstream usage: the slice overview sets the implementation lane, desired outcome, major scope boundaries, planning depth, decisions, risks, and validation strategy for all child planning work.
- Expected outputs: `.day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md` plus stable slice holding areas such as `decisions/` and `notes/`.
- Evidence handoff: phase artifacts carry `upstream.slice_overview` so later implementation evidence can be traced back to the slice boundary.

## Phase Overview

Phase overviews group major work inside a slice and declare milestones in implementation order.

- Producers: the slice-to-phase planning workflow from a standard slice overview.
- Primary consumers: milestone planning, phase review, workflow navigation, and later documentation cleanup that needs phase-level grouping.
- Parent dependencies: the parent slice overview, its source-spec traceability, and the ordered phase declaration in the slice.
- Child dependencies: phase overviews declare ordered milestone slugs with enough context to size acceptance checkpoints.
- Downstream usage: phases separate major work streams while preserving one slice-level intent, making milestone sequencing and reference or workflow cleanup boundaries explicit.
- Expected outputs: `.day-shift/planning/governed/<NN>-<slice-slug>/phases/<phase-id>/phase-overview.md` with purpose, scope, declared milestones, acceptance criteria, dependencies, risks, validation focus, and open questions.
- Evidence handoff: milestone overviews carry `upstream.phase_overview`, while phase review later reads milestone and reconciliation evidence without replacing those artifacts.

## Milestone Overview

Milestone overviews define an acceptance checkpoint and declare implementation-sized tasks. Milestone reconciliation remains pending until every task summary is complete.

- Producers: the phase-to-milestone planning workflow from a standard phase overview.
- Primary consumers: task planning, task execution ordering, milestone reconciliation, milestone review, and downstream workflow handoff cleanup.
- Parent dependencies: the parent phase overview, inherited source-spec and slice traceability, and the ordered milestone declaration in the phase.
- Child dependencies: milestone overviews declare ordered task slugs and preserve a milestone-level reconciliation placeholder as the default later rollup path.
- Downstream usage: the milestone defines the review checkpoint that tasks collectively satisfy. It is the source of truth for declared task order, milestone intent, acceptance criteria, dependencies, risks, and validation focus.
- Expected outputs: a milestone `milestone-overview.md`, a pending milestone `reconciliation.md`, and later a `tasks/` directory containing only declared task workspaces.
- Evidence handoff: task definitions carry `upstream.milestone_overview`; completed implementation summaries later feed milestone reconciliation.

## Task Definition

Task definitions are the source of truth for one implementation task's objective, target paths, acceptance criteria, dependencies, constraints, validation, and closeout expectations.

- Producers: the milestone-to-task planning workflow from a milestone overview, followed by contract completion when scaffolding initially creates placeholders.
- Primary consumers: task implementation agents, read-only readiness review, implementation-summary build and review, task review, and milestone reconciliation.
- Parent dependencies: the parent milestone overview, concrete dependency artifacts named by the task, and any earlier sibling task outputs required before implementation.
- Child dependencies: the paired implementation summary in the same task directory is the required execution-evidence artifact.
- Downstream usage: the task definition bounds implementation scope, target paths, validation commands, rollback expectations, assumptions, and open questions for one independently closable change.
- Expected outputs: `tasks/<task-slug>/task-definition.md` with implementation-ready scope and a paired `implementation-summary.md` initialized as pending before work starts.
- Evidence handoff: the paired implementation summary records what actually changed and whether the task satisfied the definition; the task definition remains the planning contract rather than the execution record.

## Implementation Summary

Implementation summaries are paired task-local execution artifacts. They record changed paths, validation, acceptance results, deviations, discovered work, follow-up work, and review evidence.

- Producers: the task implementation lifecycle after scoped work and validation have been performed.
- Primary consumers: read-only implementation-summary review, task review, milestone reconciliation, later phase or slice review, and future agents deciding whether work is complete.
- Parent dependencies: the paired task definition, scoped implementation changes, validation output, and any accepted deviations or discovered work from execution.
- Child dependencies: milestone reconciliation consumes completed implementation summaries; task-level reconciliation is an explicit exception, not the default child layer.
- Downstream usage: implementation summaries are the task-local evidence handoff. They tell reviewers which paths changed, which criteria passed or were deferred, which validation ran, and what follow-up remains.
- Expected outputs: `implementation-summary.md` with `implementation_status: completed`, `status: completed`, changed paths, acceptance results, validation evidence, scope classification, deviations, risks or follow-ups, and open questions.
- Evidence handoff: milestone reconciliation is eligible only after every declared task has a completed, non-placeholder implementation summary. Status fields alone are insufficient without body evidence.
- Metadata ownership: apply CLI-supported lifecycle metadata transitions through the matching update or sync command instead of inferring and hand-editing front matter.

## Reconciliation

Milestone reconciliation reviews completed task summaries against the milestone acceptance criteria. It records the deduped milestone verdict, validation review, discovered work, backlog work, accepted residual work, follow-up tasks, and review concerns.

- Producers: the implementation-to-reconciliation workflow after all declared task summaries under the milestone are completed and non-placeholder.
- Primary consumers: milestone review, phase review, slice-level rollup, structural-pressure sync when applicable, and follow-up planning.
- Parent dependencies: the milestone overview and every completed task implementation summary in the milestone's declared task set.
- Child dependencies: follow-up planning may use reconciliation findings, but reconciliation itself does not create new tasks unless a later explicit planning workflow is invoked.
- Downstream usage: reconciliation answers whether the combined task outcomes satisfied the milestone intent and acceptance criteria, records validation sufficiency, dedupes discovered or backlog work, and names any review concerns.
- Expected outputs: milestone-level `reconciliation.md` with `reconciliation_status: completed` and `status: completed` only when all criteria have been reviewed against task-summary evidence and no placeholder review content remains.
- Evidence handoff: reconciliation points to completed task summaries and validation or review evidence so downstream readers can inspect the supporting artifacts instead of relying on a status-only verdict.
- Metadata ownership: use the supported reconciliation update command for CLI-owned reconciliation status transitions; direct metadata edits require an explicit manual exception.

## Canonical Sources

- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/milestone.agent-lifecycle-guide.md`

## Canonical Path And Compatibility Rules

- Persist repository-relative POSIX paths, even when the operator supplies Windows or WSL input.
- Use `.day-shift/planning/basic`, `.day-shift/planning/structured`, and `.day-shift/planning/governed` as the only active roots for new work.
- Treat former nested Governed containers and older top-level numbered roots as legacy read or explicit structural-migration inputs, never as new destinations.
- Use shared specifications, dependency links, project views, or optional non-hierarchical `initiative_id` metadata to group multiple Governed slices; never create a shared lifecycle-directory parent.
- Keep canonical authored state separate from generated indexes, user-local selection/resume state, and operational transaction state.
- Use project-aware discovery/configuration for monorepos; a project view filters one repository planning root and does not create an independent hidden hierarchy.
- Apply promotion or migration only from an exact preview/plan identity through the repository transaction boundary. On conflict or incomplete state, stop and follow the reported recovery action instead of moving files manually.

## Template Shape Links

Templates define artifact shape. They do not decide when a workflow should create, update, review, or reconcile an artifact.

- Specification template: `.day-shift/templates/specification.md`
- Slice overview template: `.day-shift/templates/slice-overview.md`
- Phase overview template: `.day-shift/templates/phase-overview.md`
- Milestone overview template: `.day-shift/templates/milestone-overview.md`
- Task definition template: `.day-shift/templates/task-definition.md`
- Implementation summary template: `.day-shift/templates/implementation-summary.md`
- Milestone reconciliation template: `.day-shift/templates/milestone-reconciliation.md`

## Workflow And Prompt Links

Workflow docs own procedure. Prompt files own reusable handoff instructions. This reference owns the conceptual relationship map.

- Specification, slice, phase, milestone, and task planning procedure: `.day-shift/workflows/02-plan-from-spec.md`
- Task implementation procedure: `.day-shift/workflows/03-implement-from-task.md`
- Implementation-summary and milestone-reconciliation procedure: `.day-shift/workflows/04-summarize-and-reconcile.md`
- Task agent lifecycle: `.day-shift/workflows/task.agent-lifecycle-guide.md`
- Milestone agent lifecycle: `.day-shift/workflows/milestone.agent-lifecycle-guide.md`
- Milestone-to-task prompt: `.day-shift/prompts/user/milestone.next.md`
- Task-to-implementation prompt: `.day-shift/prompts/user/task.next.md`
- Implementation-to-reconciliation prompt: `.day-shift/prompts/user/implementation.next.md`

## Adjacent References

Related reference pages own adjacent detail that should not be repeated here:

- Command-family write and read-only boundaries: `.day-shift/references/commands.md`
- Spec registry fields and linked-slice metadata: `.day-shift/references/spec-registry.md`
- Metadata families, status fields, and parent-link mutation boundaries: `.day-shift/references/metadata.md`
- Prompt/template responsibilities and artifact-shape cleanup boundaries: `.day-shift/references/prompts-and-templates.md`
- Validation, review, implementation-summary gates, reconciliation gates, and structural-pressure policy: `.day-shift/references/validation-and-review.md`
