---
title: PH Spec Contract — sprints/
type: contract
tags: [ph, spec]
---

# Contract

## Directory Purpose
- Path (handbook instance): `PH_ROOT/sprints/`
- Summary: Active sprint workspaces (by sprint id) plus a `sprints/current` pointer to the currently-open sprint.

## Ownership
- Owner: Shared.
- Content artifacts (project-owned; human/agent-authored, often scaffolded/filled via `ph` inputs):
  - `YYYY/SPRINT-*/plan.md` body
  - `YYYY/SPRINT-*/tasks/**` task docs
- Derived/internal artifacts (CLI-authored; safe to regenerate):
  - `current` (directory link pointer)
- Overwrite rules:
  - The CLI MUST NOT overwrite an existing sprint directory or its `plan.md` without explicit `--force`.
- Mutability:
  - Human-edited: sprint `plan.md` content and task docs under `tasks/`.
  - CLI-managed: directory scaffolding and `sprints/current` pointer updates.

## Creation
- Created/updated by:
  - `ph sprint plan [--sprint SPRINT-...]` (creates a new sprint directory and seeds `plan.md`, updates `sprints/current`)
  - `ph sprint open --sprint SPRINT-...` (updates `sprints/current` pointer)
  - `pnpm make -- sprint-plan [sprint=SPRINT-...]` (creates a new sprint directory and seeds `plan.md`, updates `sprints/current`)
  - `pnpm make -- sprint-open sprint=SPRINT-...` (updates `sprints/current` pointer)
- Non-destructive: sprint scaffolding MUST NOT overwrite an existing sprint directory or its `plan.md` unless an explicit force mode is provided by the caller.

## Required Files and Directories
- Required directories:
  - `archive/`
- Required pointer:
  - `current` (MUST behave like a directory link to the current sprint directory, when present)
    - POSIX: symlink
    - Windows: directory junction (preferred) or symlink (if permitted)
    - If neither is possible, `ph sprint plan|open` MUST fail with remediation (see CLI contract).
- Sprint directory layout (canonical):
  - Date/ISO-week ids:
    - `YYYY/SPRINT-<...>/`
      - `plan.md`
      - `tasks/`
  - Sequence ids (legacy `id_scheme=sequence`):
    - `SEQ/SPRINT-SEQ-####/`
      - `plan.md`
      - `tasks/`

## Schemas
- `YYYY/SPRINT-*/plan.md` MUST be Markdown with YAML front matter containing at least:
  - `title: <string>`
  - `type: sprint-plan`
  - `date: YYYY-MM-DD`
  - `sprint: SPRINT-...` (matching the directory name)
  - `mode: bounded|timeboxed`
- Sprint plan front matter MAY include:
  - `tags: [sprint, planning, ...]`
  - `release: <string|null>`
  - `release_sprint_slot: <int|null>` (when using sprint-slot releases)
  - `start: YYYY-MM-DD` (required when `mode: timeboxed`)
  - `end: YYYY-MM-DD` (required when `mode: timeboxed`)
- Task directories under `YYYY/SPRINT-*/tasks/` (created by `ph task create`) MUST have this shape:
  - `TASK-###-<slug>/`
    - `task.yaml`
    - `README.md`
    - `steps.md`
    - `commands.md`
    - `checklist.md`
    - `validation.md`
    - `references.md` (legacy; optional but commonly scaffolded)
    - `source/` (optional; for attachments/snippets; never executed by `ph`)
- `task.yaml` MUST be YAML and include at least:
  - `id: TASK-###`
  - `title: <string>`
  - `feature: <string>`
  - `lane: <string|null>` (legacy)
  - `decision: <string>` (ADR-/DR-/FDR- id)
  - `session: <string>` (legacy; e.g. `task-execution`, `research-discovery`)
  - `owner: <string>`
  - `status: <string>`
  - `story_points: <int>`
  - `depends_on: [<TASK-###|FIRST_TASK>, ...]`
  - `prio: P0|P1|P2|P3|P4`
  - `due: YYYY-MM-DD`
  - `release: <vX.Y.Z | current | null>` (legacy)
  - `release_gate: <boolean>` (legacy)
  - `acceptance: [<string>, ...]`
  - `links: [<string>, ...]`
- Task Markdown files (`README.md`, `steps.md`, `commands.md`, `checklist.md`, `validation.md`) MUST include YAML front matter with at least:
  - `title: <string>`
  - `type: task|implementation|commands|checklist|validation` (as appropriate)
  - `date: YYYY-MM-DD`
  - `task_id: TASK-###`
- YAML front matter MAY include additional keys; unknown keys MUST be preserved.

## Invariants
- If `sprints/current` exists, it MUST resolve to an existing sprint directory.
- For date/ISO-week ids, the sprint directory year partition `YYYY/` MUST equal the year segment in the sprint id (`SPRINT-YYYY-...`).
- A sprint directory MUST contain:
  - `plan.md`
  - `tasks/` (may be empty)

## Validation Rules
- For every sprint directory `YYYY/SPRINT-*`:
  - `plan.md` MUST exist and satisfy the sprint-plan front matter requirements above
  - `tasks/` MUST exist (may be empty)
- If `sprints/current` exists, it MUST resolve to an existing sprint directory under `sprints/YYYY/SPRINT-*`.
- Task directories under `tasks/` MUST satisfy the task file + front matter requirements above.

## Examples Mapping
- `examples/2026/SPRINT-2026-01-11/plan.md` demonstrates a valid sprint plan with bounded planning metadata.
- `examples/scaffold/2026/SPRINT-2026-01-11/plan.md` demonstrates the sprint plan scaffold shape generated by tooling.
