# plan-issue docs
## Purpose
Crate-local documentation for `nils-plan-issue`.
The default lifecycle for new issue-backed plan records is the
**v3 issue-backed plan record lifecycle** owned by the
`plan-issue record ...` surface. That surface opens provider issues,
posts canonical lifecycle comments, audits and repairs dashboards, and
performs strict provider-verified closeout. See
[issue-backed plan record contract v2](specs/issue-backed-plan-record-contract-v2.md)
and [plan-issue state machine v2](specs/plan-issue-state-machine-v2.md)
for the normative spec.
For the next state payload replacement, the active contract is new-format-only:
the new accumulative state task-ledger payload replaces the old v2/current-only
state semantics. `record audit`, `record repair-dashboard`, `tracking status`,
and `tracking close-ready` do not promise a long-term old-payload reader or
mixed old/new reconciliation path.
The prior `start-plan` / `start-sprint` Task Decomposition runtime is
retained for existing dispatch flows that have not migrated yet. Its
state machine, gate invariants, and runtime-truth row model live in the
v1 specs and the
[plan-issue CLI contract v2](specs/plan-issue-contract-v2.md). New
work should not target the Task Decomposition runtime.
Current runtime ownership:
- `plan-tooling` continues to own plan parsing, validation, split modeling,
and PR grouping primitives.
- `plan-issue record` owns the v3 issue-backed plan record lifecycle:
open, post, audit, repair-dashboard, and close.
- Prior `plan-issue start-plan` / `start-sprint` commands continue to
materialize Task Decomposition runtime metadata for in-flight dispatch
flows.
- `forge-cli` and provider adapters own general provider operations that
are not part of the issue-backed plan record lifecycle.
- markdown table cell canonicalization is provided by `nils-common::markdown`.
## Specs
- [issue-backed plan record contract v2 (current)](specs/issue-backed-plan-record-contract-v2.md)
- [plan-issue state machine v2 (current)](specs/plan-issue-state-machine-v2.md)
- [plan-issue CLI contract v2 (Task Decomposition runtime metadata)](specs/plan-issue-contract-v2.md)
- [plan-issue state machine v1 (Task Decomposition runtime)](specs/plan-issue-state-machine-v1.md)
- [plan-issue gate matrix v1](specs/plan-issue-gate-matrix-v1.md)
## Runbooks
- [Provider routing runbook](runbooks/provider-routing-runbook.md)
## Links
- Back to crate README: [`../README.md`](../README.md)