# Work Package And Milestone Orchestration

Use work packages when a goal is larger than one safe chunk, when humans should review meaningful milestones instead of every chunk, or when chunk-level automation needs a parent policy.

For approved work packages, `ai/standards/chunk-autopilot.md` is the default execution model unless the work package explicitly disables it.
That standard is the canonical full-show lifecycle owner. This file owns the
work-package model and planning boundaries; it intentionally does not duplicate
the detailed autopilot continuation policy.

## Work Package Model

A work package defines:

- approved requirements source or explicit human-provided scope.
- work package goal.
- planning path used.
- milestones.
- chunks per milestone.
- automation policy.
- Chunk Autopilot setting.
- stop milestones.
- approved chunk queue.
- stop conditions.
- milestone human review requirements.
- final human review requirements.
- progress tracking.
- commit policy.

Work packages coordinate chunks; they do not replace chunk-level `## Execution Notes`, `## QA Review`, `## Pass History`, `## Test Impact`, or readiness gates.
They also do not replace the carry-forward registry. Milestone and final
work-package summaries should project relevant registry/Runtime
carry-forward state and classify items as blocking or non-blocking.

Work packages are Orchestrator-owned lifecycle artifacts. Humans approve
requirements, approve the chunk plan/work package, review configured milestones,
and review final summaries. Humans should not need to manually update work
package progress or archive completed packages during normal operation.

## Planning Paths

### Path A: Rough Idea

Rough idea -> Requirements Intake -> Requirements Review -> Chunk Planner -> Work Package -> Orchestrator.

Use this for normal product work, ambiguous work, user-facing behavior, auth/security/data changes, integrations, or anything likely to span multiple chunks.

### Path B: Human-Provided Requirements

Human-provided requirements -> Chunk Planner -> Work Package -> Orchestrator.

Use this when the human gives explicit requirements that are complete enough to review and chunk, but not already in a requirements lifecycle file.

### Path C: Human-Provided Chunk List

Human-provided chunk list -> Chunk Planner formalizes the queue -> Orchestrator executes planned backlog chunks.

Use this when the human already provided chunk boundaries, dependencies, validation expectations, and out-of-scope items. Orchestrator may still create a lightweight work package for milestone tracking, but autonomous or multi-chunk execution must preserve Chunk Planner output, backlog/planning artifacts, and canonical activation before implementation.

### Path D: Small Explicit Fix

Small explicit fix -> Orchestrator creates one chunk directly.

Use this only when scope is narrow, explicit, single-chunk, and has no product ambiguity. If the work becomes multi-chunk, autonomous queue work, or a live follow-up sequence, switch to Path B or C and create backlog/planning artifacts before activation. If scope becomes unclear, stop and route to Requirements Intake or human questions.

## Requirements Policy

- Normal product work starts with Requirements Intake and Requirements Review.
- Product/security/auth/data decisions require approved requirements or explicit human approval.
- Small workflow/tooling fixes may start from the prompt when scope is explicit and narrow.
- Orchestrator may create chunks directly only when no product ambiguity exists.
- If requirements are unclear, Orchestrator must ask focused questions or route to Requirements Intake.

## Chunk Autopilot Policy

After requirements and the final chunk plan/work package are approved, default to
the full-show lifecycle in `ai/standards/chunk-autopilot.md`. In short,
Orchestrator should run the approved queue continuously through Developer, QA,
completion/archive, safe commit, and next-chunk continuation until a configured
stop milestone, safety stop condition, or final work-package review boundary.

Autopilot must not start from unmanaged active chunks. The approved queue should
point to draft/backlog chunk artifacts, and each implementation chunk is
activated through the canonical lifecycle transition. Emergency/live fixes need
their own backlog/planning artifact before activation unless they clearly fit
the current active chunk's scope and validation, or unless a future canonical
emergency transition explicitly replaces that rule.

Humans may provide stop milestones by chunk number or milestone name. If no stop milestones are provided, there are no intermediate stop points. End of queue is always a stop point.

## Automation Policy

- Auto-run Developer pass: allowed inside approved chunk scope.
- Auto-run QA pass: allowed after `ai/commands/workflow-state.sh --ready-for-qa` passes.
- Auto-run focused Developer retry: allowed only when `ai/standards/orchestrator-retry-policy.md` classifies blockers as retry-safe/fixable.
- Auto-complete/archive chunk: default yes when Chunk Autopilot is enabled and `ai/commands/workflow-state.sh --ready-to-complete` passes.
- Auto-commit chunk: default yes when Chunk Autopilot is enabled, QA PASS and completion gate pass, no manual intervention is required, git status contains only approved paths, and commit message is meaningful.
- Auto-merge/release: never allowed by default.

Automation permission is scoped to the work package. If no work package exists, default to human review before completion and commit.

## Milestone Review Policy

- Human review is required at configured stop milestones. If no stop milestones are configured, do not stop between chunks merely because a milestone label changes.
- Human review is required at the end of the approved chunk queue.
- Human review is required before merge or release.
- Human review is required for product, security, auth, data, destructive, credential, or production-impacting decisions.
- Human review is required when Orchestrator detects ambiguity, scope change, retry limit reached, unexpected git state, helper contradiction, or unavailable required validation.
- Milestone review should use `ai/commands/workflow-summary.sh` plus milestone progress notes.

## Stop Conditions

Stop automation and require human intervention when:

- requirements ambiguity exists.
- product/security/auth/data decision is needed.
- scope expansion is required.
- QA blocker is not retry-safe.
- retry limit is reached.
- runtime smoke is required but unavailable.
- destructive data risk exists.
- production credential risk exists.
- unexpected git state appears.
- helper state contradicts markdown notes.
- validation fails without accepted rerun/justification.
- a chunk would require app source or dependency changes outside approved scope.
- configured stop milestone or work package boundary is reached.

## Commit Policy

Work packages may choose one of:

- `manual`: humans commit after each reviewed chunk or milestone.
- `chunk_auto_commit`: Orchestrator may complete/archive and commit passing chunks inside a milestone.
- `milestone_auto_commit`: Orchestrator may commit only after all chunks in a milestone pass.

For approved work packages, `chunk_auto_commit` is the Chunk Autopilot default unless the work package disables it. Auto-commit still requires:

- QA PASS.
- completion readiness passed.
- no manual intervention state.
- no `.env` or `.tmp` paths.
- meaningful commit message derived from chunk or milestone context.
- git status reviewed against the package scope.

## Progress Tracking

Track milestone status as:

- `Not Started`
- `In Progress`
- `Blocked`
- `Ready For Human Review`
- `Approved`
- `Completed`

Track chunk status by path and canonical state. Completed chunks should remain immutable history.

The Orchestrator owns progress updates. When all planned chunks are complete,
the Orchestrator records the final report path and moves the work package from
`ai/work-packages/active` to `ai/work-packages/completed`.

Final work-package reports should use the sortable report naming convention in
`ai/reports/README.md`.

## Human Review Boundary

When a chunk reaches `ready_to_complete` but human review is required, use the
field semantics and command categories from
`ai/standards/workflow-handoff.md`. In work-package context this means human
review remains distinct from lifecycle transition, and staging/commit guidance
uses trusted operator-daemon requests unless the action is explicitly outside
the registered daemon action set.