# Planning artifact contract
`plan.md` is authored source. `phase0.md`, topology, lane plans, and Critic reports are run-scoped evidence/projections. Native run state is outside this contract.
## `phase0.md`
Use these sections in order:
1. `# Orientation`.
2. `## Run and seed`: run id, verified seed path, seed hash, planted observation. Do not edit state.
3. `## Auditor briefs`: per question, the question, read scope, output path, budget, result hash, evidence, conflicts, disposition.
4. `## Discovery briefs`: the same plus cited sources. Each child is one regular non-symlink artifact with its path and SHA-256.
5. `## Assumptions and decisions`: id, statement, source, owner, blocking, evidence, disposition.
6. `## Coverage map`: each seed deliverable to source-plan nodes and acceptance evidence.
7. `## Self-review`: PASS/FAIL per gate and candidate hashes.
8. `## Critic loop`: candidate hashes, verdicts, findings, revisions, final GREEN evidence.
Before Critic dispatch root invokes `shepherd run orientation pre <run> --json`; native writes
`orientation-manifest.json` and `orientation-pre.json` from stopped Auditor/Discovery records,
and Critic receives the pre hash only once native returns `accepted == true`. After Critic stop,
`shepherd run orientation post <run> --json` writes `orientation-post.json`. Engineer writes
none of these. Missing evidence is unresolved.
## Execution mode shapes the plan
The workflow is identical under Spawn and Start; the allowances differ, so establish which is in
force before shaping lanes. Spawn runs lanes concurrently, so they are file-disjoint with their
own acceptance and gate. Start drives alone, so lanes order by dependency and scope acceptance
rather than isolate writers. A plan shaped for the wrong mode is structurally wrong.

## `plan.md`
Use this shape:
```markdown
# Plan: <run>
## Scope contract
- Schema: shepherd.plan/2
- Run: <run-id>
- Seed: <run-relative path>
- Mesh: <run-relative path>
- Planning evidence: <run-relative path>
- Goal: <one measurable goal>
- Deliverables: <stable ids>
- Lanes: <stable lane ids>
- Root roles: [shepherd, planter]
- Child lead roles: [engineer, conductor]
- Planning lead: engineer
- Engineer count: 1
- Review rejection limit: 3
- Fourth rejection: malignant-revoke-quarantine-preserve-evidence-no-resume-root-lineage-replacement
- Root continuation: fresh-root-preferred-new-run-binding-clears-child-authority
- Exclusions: <explicit exclusions>
## Assumptions and decisions
| id | statement | source | owner | blocking | evidence/disposition |
## Interfaces
| id | version | producer | consumers | acceptance |
## Phases
| phase | predecessor frontier | node ids | disjointness proof |
## Capacity
```yaml
logical_lane_limit: <logical ready-lane ceiling>
host_process_ceiling: <measured host ceiling>
project_spawn_max_parallel: <verified project setting>
plan_process_ceiling: <plan ceiling>
parent_role_cap: <parent or role ceiling>
run_budget: <run ceiling>
simultaneous_process_ceiling: <minimum of the five ceilings above and live_concurrency_ceiling>
per_lane_child_wave_ceiling: <positive integer>
disk_min_mib: <at least 1024>
model_quota: <positive integer at least the live ceiling>
live_concurrency_ceiling: <measured live descendant ceiling>
retained_descendant_slots: <descendant slots retained in one capacity epoch>
lifetime_descendant_slots: <positive integer or none>
completed_session_reclamation: immediate|turn-boundary|never
interrupted_session_reclamation: immediate|turn-boundary|never
turn_reset_behavior: reclaims-terminal|preserves-terminal
reusable_sessions: true|false
nested_dispatch: true|false
persistent_agent_cost: <positive slots per persistent lane lead>
independent_reviewer_reachable: true|false
capability_source: <named adapter evidence source>
capability_evidence_sha256: <lowercase SHA-256 of the validated measurement artifact>
turn_strategy: same-turn|reset-between-phases|fresh-root-session-between-phases
backpressure: queue|queue-fair
cargo_targets: [<lane>=<unique-target>, ...]
conductors: [<lane>=conductor, ...]
schedule: [<lane+lane>@<process-slots>, ...]
scale_outcome: <verified-seed-outcome-or-none>
```
## Nodes
### <stable-node-id>
```yaml
id: <lowercase-kebab-id>
seed_deliverables: [<ids>]
lane: <lane-id>
role: coder|worker|engineer|auditor|critic|discovery|conductor
work_kind: production|artifact|planning|review|research|coordination
outcome: <observable result>
owns: [<exact relative paths>]
forbidden: [<exact paths or bounded roots>]
consumes: [<interface-id@version>]
produces: [<interface-id@version>]
depends_on: [<node-ids>]
red: {command: <argv>, expects: <failure>, reason: <reason>}
green: {command: <argv>, expects: <success>, reason: <reason>}
eval: {command: <command-or-none>, threshold: <integer-or-none>}
evidence: <run-relative path>
review: <role: predicate>
failure_route: <route>
rollback: <boundary>
```
## Node rules
Mutation `owns` is exact/nonempty, excluding native state, repository roots, and other results.
Interfaces have one producer and versioned consumers; dependencies are reasoned, roots use baseline.
RED/GREEN commands are bounded argv-safe checks. Judgment requires eval/threshold; every node
needs review/failure_route/rollback. Timestamps, random ids, model prose, commit/tree hashes,
and placeholders require checked evidence.

Roots: Shepherd and root-local Planter. Other roles are sprint-bounded children; only
Engineer/Conductor lead. One active Engineer; one persistent Conductor per verified lane.
A Conductor node is coordination only and cannot plan, rescope, or implement.
Allow three redos; fourth rejection triggers Native malignant revocation/quarantine,
preserved evidence, no resume, and root-owned lineage-bound replacement.

2-6 Conductor lanes cover 99%: two routine, 3-4 beefy, 4-6 mega, 6-8 exceptional OS-scale.
These overlapping bands impose no global cap; minimize lanes. Four or more require a complete
non-overlapping resource schedule; six or more require verified seed-outcome reason and capacity
proof. Logical concurrency differs from live process ceiling, exactly
`min(host, project spawn.max_parallel, plan, parent/role cap, run budget, lifecycle live)`.

Capacity facts describe capabilities, not provider names. Descendant ceilings exclude the root.
Persistent Conductors, a worker, and an independent Auditor must remain reachable. If completed
or interrupted sessions retain a slot, `same-turn` also budgets the completed planning Critic and
worker. `reset-between-phases` is valid only when adapter evidence says a turn boundary reclaims
both completed and interrupted sessions through an origin-authenticated host channel. A raw turn
identifier is correlation, never reclamation authority. When that channel is unavailable,
`fresh-root-session-between-phases` requires every prior-root descendant to become terminal and
then binds a new root session before opening the next three-slot capacity epoch. Unsupported
capability evidence fails closed; do not invent reclamation, reuse, nested dispatch, or reviewer
reachability.

`per_lane_child_wave_ceiling` bounds logically ready children, not resident processes; tens of
ready tasks are possible, never required. Optional schedules for one to three lanes still cover
each lane exactly once with safe slots. One lane can budget one Conductor plus two children
at a live ceiling of three, queuing other leads. Repository `spawn.max_parallel` remains 3
unless its configuration authority changes it.

Every repository path uses one portable normalized relative grammar; `shepherd_core::dispatch`
is its definition and the only authority. Environment checks accept closed read-only argv shapes
and execute without a shell. Arbitrary Cargo commands are not nonmutating: build scripts and
tests execute code.
## Native readiness and execution boundary
1. Read authoring-worktree seed, mesh, and plan. Native held `RunState` supplies identity,
   planted status, and pointers, never shadow `run.json`. Planted-only seed verification binds exact bytes.
2. `shepherd plan materialize --run <run>` generates projections; `--check` compares them.
   Legacy `plan validate` only inspects. Never edit projections independently.
3. Root authors canonical `.shepherd/runs/<run>/plan-probes.json`: `shepherd.plan-probes/1`,
   current Git `baseline`, observed `worktree_identity`, and `probes`. Every owned path needs
   one unique path probe: `expectation: create|modify`, `path_kind: file|directory`. Create
   requires absence; modify requires regular kind. Optional symbol/interface/command probes
   require exact counts/versions/exits/markers. Only closed read-only Git/rg argv executes.
   Empty, missing, duplicate, uncovered, aliased, stale, unknown-field or forged-success inputs fail.
4. `shepherd plan verify --run <run> --json` checks opened artifacts, source, identity, baseline,
   disk, host, project limit, and actual `SHEPHERD_MODEL_QUOTA`. Never invent quota.
   `plan check --probes <path>` is diagnostic, not canonical proof or execution authority.
5. Native `run transition <run> --to planned` validates orientation against identical seed/phase0,
   reruns readiness under the held lock, and issues authenticated `shepherd.plan-readiness/2`.
   `run_artifacts` hashes plan/seed/mesh/phase0/probes/topology/all lane plans; `source_artifacts`
   hashes opened probe inputs. Worktree identity/baseline are bound. Engineer never writes proof.
6. `sprint open --run <run>` and direct executing transition authenticate incarnation/epoch,
   checkpoint, plan pointer, all artifacts, and fresh probes without faking planted state.
   Native initializes pending lanes with exact `lanes/<lane>/plan.md`, preserving pristine
   matching registrations only. Unknown/duplicate/nonpending, accepted, merged, or wrong-plan
   rows fail atomically. Empty lane inventories cannot close a sprint.
7. Executing dispatch reopens checkpoint and planning bytes in that exact worktree, never
   freezing implementation source or rerunning probes. Identical bytes cannot authorize another
   worktree. Native separately measures live reservations and capacity.
## Lane plan
Each `lanes/<lane>/plan.md` is derived from source sections:
```markdown
# Lane: <lane-id>
## Outcome and non-goals
## Inputs and predecessor contracts
## Owned paths
### Allowed
### Forbidden
## Ordered nodes
| order | node id | role | outcome | red | green | evidence |
## Coder briefs
## Worker briefs
## Review points and bounded redo
## Local gate and integration handoff
## Risks and stop conditions
## Rollback boundary
```
The lane copies source node/interface fields and adds no unowned task. Coder briefs may name production/config/build/test paths; Worker briefs only non-code deliverables. Every brief has one result path and acceptance predicate.