roadmap

name	roadmap
position	end
description	Plan the product's vertical slices into a build sequence — order the slices /shape produced across all domains, resolve their dependencies, and estimate each one's effort, writing only the plan onto each slice. The planning play in the ProductOS command model, after /shape. Reads the slices to judge order and effort but writes only the plan (order, effort, dependencies). Opens no delivery issue.
user-invocable	true

roadmap

Take the vertical slices /shape produced and turn the pile into a plan. /roadmap reads every slice across every shaped domain and lays out the build sequence: the order to build them, the dependencies between them (within and across domains), and an effort estimate for each. It writes that plan onto each slice's spine index entry — order, effort, resolved depends_on, and the status flip to planned — and touches nothing else: the slice records (composition) and every other part of the model stay byte-identical. One run plans the whole set, because order only means something by comparison. Convention: a lower order number means sooner.

Pipeline position: end. /roadmap CLOSES the strategy pipeline: after the ordering is persisted and verified, the D2 rule injects the close sequence commit-change → propose-change → review-change → merge-change, so the strategy change is committed, raised, reviewed, and merged. No start-change head — /vision opened the pipeline. It runs after /shape, since slices must exist before they can be planned. (#437)

Compiled From

This play was compiled from the roadmap ICE (reference/ice.md) by play-editor (#466 Batch C; #467 Batch B — the checkpoint upgraded to a conditional learned gate, see standards/rules/gate-config.md). Intent defines constraints (C1–C9) and failure conditions (F1–F10); the expectation defines success scenarios (S1–S6), a Done means (D1–D3, baked to stop-condition.yaml), and one recovery entry per failure condition. To modify this play, update reference/ice.md and recompile with play-editor. Do NOT edit this file manually — it is a compiled artifact.

Role

You are the orchestrator. You own the workflow and the step order. You delegate the judgment — effort, resolving dependencies, and a value preference — to the product-os-keeper agent via a JSON contract over files on disk, and you run every mechanical part (the snapshot, the ordering math, the allowlisted persist, and the post-apply checks) through bundled scripts. You never write slice YAML by hand, you never assign the order numbers yourself, and you never persist before the single checkpoint (C8) resolves — a typed approval, a recorded config skip, or a recorded policy auto-pass.

Forbidden: hand-writing slice/plan YAML; assigning order numbers in prose instead of via scripts/compute_plan.py; writing anything other than the plan fields (order/effort/depends_on/status) on a slice's spine entry; editing a slice's composition (its record); persisting by any route other than scripts/apply_roadmap.py; persisting before Step 4 approval; touching the grounding docs, the node tree, the profile, the lenses, decisions, or the _deferred bucket (C2).

Agent boundaries:

Agent	Domain	Skill it invokes	Phases
product-os-keeper	Read /shape's slices and judge the plan inputs — estimate effort per slice, resolve dependency_notes (+ shared functionalities + their spine depends_on) into concrete depends_on, propose a value order	author-roadmap	Draft

product-os-keeper is the single domain agent this play uses (1 of the ≤5 budget). No utility agents are needed — git/issue machinery is absent (position none). /roadmap does not ground in the KB: planning is a judgment over the slices the model already holds, not a placement question.

Pre-flight

Check	Constraint	Action on Failure
Resolve config + product_base (.garura/core/config.yaml)	—	Hard halt
The product model holds ≥1 slice to plan	C1	Graceful exit

Resolve config mechanically with the bundled resolver; /roadmap has no branch or issue (position none):

python3 scripts/preflight.py --play roadmap --config .garura/core/config.yaml
python3 scripts/snapshot_model.py --product-base <product_base> --probe

preflight.py returns config facts (product_base, stm_base, evidence_record). snapshot_model.py --probe reports slice_count without writing anything. If slice_count is 0, exit gracefully: there is nothing to plan — run /shape first to create slices. The probe is write-free, so re-entering pre-flight on a resume is safe; the actual before-picture is captured at Step 1.

<working> is the run's STM working root, {stm_base}_shaping/roadmap/ — the baked stop condition's relative paths resolve against it.

Right after the resolver, record the session identity stamp's start marker (#463 — soft-fail, never a halt):

python3 scripts/session_stamp.py --phase start \
    --marker "{stm_base}_shaping/roadmap/status/session-stamp-roadmap.json" \
    --cwd "$(pwd)" --branch "$(git branch --show-current)"

Resume check: if {stm_base}_shaping/roadmap/status.json exists, resume — skip completed steps (Step 1's snapshot is therefore preserved), reset any in-progress step to pending, continue from the first incomplete.

Task DAG

Create ALL tasks immediately after resolving config — before any domain work. The play owns this DAG; the agent must not edit its top-level tasks.

[T1] Capture snapshot   blockedBy: []
[T2] Draft plan         blockedBy: [T1]
[T3] Compute plan       blockedBy: [T2]
[T4] Checkpoint (approval) blockedBy: [T3]
[T5] Apply plan         blockedBy: [T4]
[T6] Verify persisted   blockedBy: [T5]
[TE1] commit-change   (injected — end #1)  blockedBy: [T6]
[TE2] propose-change  (injected — end #2)  blockedBy: [TE1]
[TE3] review-change   (injected — end #3)  blockedBy: [TE2]
[TE4] merge-change    (injected — end #4)  blockedBy: [TE3]
[T7] Scenario Validation blockedBy: [TE4]
[T8] Close              blockedBy: [T7]

Mark each task in-progress before its step and completed right after its eval passes. No runtime reordering. On resume, skip completed and reset in-progress to pending.

Workflow

Phase: Snapshot

Step 1 — Capture snapshot · Owner: play · Depends on: pre-flight Take the pre-apply "before" picture — the spine and every slice across every shaped domain (id, domain_ref, bundled functionalities, dependency_notes, current plan fields) and a path→hash census of every file under product-os except _spine.yaml (the only file /roadmap writes). Gated step, so a resume preserves it:

python3 scripts/snapshot_model.py --product-base <product_base> --out <working>/snapshot.json

SE (no eval here): Step 1 only records state; it is exercised by Step 3's plan and proven by Step 6's non-destructive check.

Phase: Draft

Step 2 — Draft plan · Owner: product-os-keeper · Depends on: Step 1 The agent invokes author-roadmap to estimate each slice's effort, resolve its dependencies into concrete depends_on slice ids, and propose a value order — drafting plan-draft.yaml to STM:

{
  "task":    "for every slice in the snapshot, estimate effort, resolve depends_on (from dependency_notes + shared functionalities + their spine depends_on), and propose a value order; draft only",
  "inputs":  { "snapshot_path": "<working>/snapshot.json",
               "product_base":  "<product_base>" },
  "outputs": { "plan_draft":    "<working>/plan-draft.yaml" }
}

The skill reads the slices + their functionalities' grounding read-only and writes only the draft. It assigns no order numbers and runs no topological sort — those are Step 3's deterministic job. It returns the contract with the output path on disk — never inline content.

Phase: Compute

Step 3 — Compute plan · Owner: play · Depends on: Step 2 Turn the draft into a coherent, dependency-correct global plan:

python3 scripts/compute_plan.py --snapshot <working>/snapshot.json \
        --plan-draft <working>/plan-draft.yaml --out <working>/plan.json

compute_plan.py topologically orders all slices so dependencies precede dependents (value order breaks ties), assigns the distinct integer order 1..N across every domain, carries each slice's effort, and detects cycles. It writes the machine coherence field into the plan record (C9/#464): plan.json carries orders_coherent: true|false — this field, not prose, is what the close's stop-condition gate (D3) reads. SE-3 (F3/C3): within the computed plan, no slice precedes one it depends_on. SE-4 (F4/C4): every slice in the plan has an integer order and a non-empty effort; the orders are distinct and form 1..N. SE-5 (F5/C5): the script exits 0 (no cycle) and the plan spans every shaped domain's slices; on a non-zero exit (cycle or a slice missing from the draft) apply REC4/REC5 and re-run before the checkpoint.

Phase: Checkpoint (conditional gate, C8)

Step 4 — Human review (class: standard, conditional) · Owner: play · Depends on: Step 3 This is the single checkpoint (C8). It is a conditional gate (#467) per standards/rules/gate-config.md — /roadmap is one of the eleven conditional document plays. Resolve it first match wins: pinned (n/a here) → gates.plays.roadmap → the learned policy → gates.classes.standard → gates.default (absent ⇒ on). For the policy lookup, classify the draft-vs-live change shape first (<working> is /roadmap's draft root — it holds plan-draft.yaml and plan.json):

python3 scripts/classify_change.py --play roadmap --draft <working> \
        --live <product_base> --out <working>/shape.json

Look the shape key up in the config-resolved policy (gates.conditional.policy): auto-pass iff the shape is in the policy's auto: block AND not in never_auto: AND Step 3 stands with no blocking finding (a compute_plan.py non-zero exit or a cycle anomaly in plan.json — /roadmap's lint-equivalent). On auto-pass, do NOT wait: record gate auto-passed by learned policy (shape: <shape-key>, policy v<version>) as a Checkpoint Decisions row, include the draft's diff summary in the run record, append the crossing's live-eval ledger line, and proceed to Step 5:

python3 scripts/gate_eval.py append --ledger <gates.conditional.ledger> --play roadmap \
        --issue <strategy issue> --shape <shape-key> --predicted auto --human auto_pass \
        --policy-version <policy version> --ts <run ts>

Anything else resolves the gate on (an explicit gates.plays.roadmap: off instead records gate skipped by config (<resolution path>) as a Checkpoint Decisions row and proceeds on the computed plan). When on, present the plan inline — the slices in order, each with its effort and its resolved dependencies, plus any cycle anomalies for the human to break — render the approval prompt (standards/templates/approval-prompt.md) and wait for the typed response. Approve → continue to persist; cancel → halt with no plan written. Then append the crossing's live-eval ledger line with the human's real action:

python3 scripts/gate_eval.py append --ledger <gates.conditional.ledger> --play roadmap \
        --issue <strategy issue> --shape <shape-key> --predicted gate \
        --human <approved_clean|approved_edited|rejected> --ts <run ts>

<strategy issue> is the strategy-pipeline issue the run's branch carries (opened by /vision's start-change). <gates.conditional.ledger> / <gates.conditional.policy> resolve from config gates.conditional (defaults .garura/core/gate-evals.jsonl / .garura/core/gate-policy.yaml); <policy version> is the policy file's version: field. <run ts> is the run's own UTC timestamp, derived the same way the close derives ts (date -u), passed by the orchestrator. SE-8 (F8/C8): the plan is persisted only after this gate resolves — a typed approval, a recorded config skip, or a recorded policy auto-pass — Step 5 is the sole writer and depends on this step; no slice's plan fields change before Step 5. SE-10 (F10): every crossing of this gate appended exactly one live-eval ledger line (shape, predicted gate|auto, the human's real action or auto_pass), and an auto-pass fired only for a shape the policy lists in auto: (and not in never_auto:) with no blocking finding standing.

Phase: Apply

Step 5 — Apply plan · Owner: play · Depends on: Step 4 Persist on the fixed allowlist. apply_roadmap.py read-modify-writes the spine slices index: it changes only order, effort, depends_on, and status on each planned slice's spine entry, preserving every other part of the spine, and never opens the slice records, the grounding docs, the node tree, the profile, the lenses, or decisions:

python3 scripts/apply_roadmap.py --plan <working>/plan.json \
        --snapshot <working>/snapshot.json --product-base <product_base> \
        --out-manifest <working>/apply-manifest.json

SE-1 (F1/C1): the apply manifest's changes are all on spine slice entries — no non-slice entry received a plan. SE-2 (F2/C2): each change touches only the plan fields (order/effort/depends_on/ status) on the spine — no slice record (composition), grounding doc, or other artifact appears.

Step 6 — Verify persisted · Owner: play · Depends on: Step 5 Prove the persisted model against the snapshot and the plan:

python3 scripts/validate_roadmap.py --snapshot <working>/snapshot.json \
        --plan <working>/plan.json --apply-manifest <working>/apply-manifest.json \
        --product-base <product_base>

SE-6 (F6/C6): non-destructive — every file under product-os except _spine.yaml is byte-identical to the snapshot, and within the spine only the slices' plan fields changed (domains, capabilities, functionalities, profile, epics, and each slice's non-plan fields unchanged); nothing added or removed. SE-7 (F7/C7): every slice spine entry the run wrote conforms to the spine schema — order an integer, status planned, effort non-empty, depends_on resolving to real slices. SE-9 (F9/C9): the Done means holds as machine state — plan-draft.yaml and plan.json exist and plan.json reads orders_coherent: true — and the close's stop-condition verdict reads held before the run may close COMPLETED; coherence asserted only in prose fails this eval (REC9: re-run the draft and compute_plan.py, then re-evaluate). (SE-1…SE-5 are re-asserted here against the persisted model.) On any GAP, apply the matching recovery (REC1–REC7, REC9) and re-run.

Phase: End sequence (injected — D2 position: end)

The persisted ordering is a durable model change; the standard end sequence closes the strategy pipeline (#437). Each member runs as a sub-play dispatched with parent_run_id (emits only its own C1 evidence; this play's close absorbs it). Each member resolves its own context from the branch and config; this play passes no hand-rolled git/PR/merge logic.

Step E1 — commit-change · Owner: commit-change (sub-play) · Depends on: Step 6 — commit the strategy-pipeline changes grouped by concern; no push.

Step E2 — propose-change · Owner: propose-change (sub-play) · Depends on: Step E1 — self-review, push the branch, open the PR.

Step E3 — review-change · Owner: review-change (sub-play) · Depends on: Step E2 — diff-scoped review, approve/reject verdict. A reject stops the sequence before merge.

Step E4 — merge-change · Owner: merge-change (sub-play) · Depends on: Step E3 (approve verdict) — merge the PR, switch to main and pull, delete the feature branch.

{
  "play":          "<commit-change | propose-change | review-change | merge-change>",
  "parent_run_id": "<this run id>",
  "inputs":  {},
  "outputs": { "result": "{stm_base}_roadmap/end/<member>.json" }
}

Phase: Scenario Validation

Step 7 — Scenario evals · Owner: play · Depends on: Step 6

• SCE-1 (S1 — planner, first plan): every non-deferred slice's spine entry has an integer order and a non-empty effort; orders are distinct 1..N; every other part of the spine and every other product-model file is byte-identical; the entries conform to the spine schema.
• SCE-2 (S2 — architect, dependencies): for every resolved A depends_on B, order(B) < order(A); any cycle is in the checkpoint anomaly list and no order persisted for it.
• SCE-3 (S3 — delivery lead, effort): every planned slice carries an effort estimate.
• SCE-4 (S4 — product manager, cross-domain): the orders form a single 1..N spanning slices from every shaped domain, not a per-domain sequence.
• SCE-5 (S5 — product owner, re-run non-destructive): on an unchanged model every product-model file is byte-identical; on a changed model only the plan fields differ on any slice, and no non-slice file changed.
• SCE-6 (S6 — reviewer, the checkpoint): the checkpoint showed the ordered slices with effort and dependencies and any anomalies, before any write — or, on the auto-pass path (a policy-listed shape), the gate resolved with no wait and the recorded auto-pass, the appended ledger line, and the diff summary stand in the approval's place.

Phase: Evidence & Close

Step 8 — Close · Owner: play · Depends on: Step 7 Run the Standard Play Close. /roadmap is a product-scoped play (no issue) — use the product-scoped evidence base and slug. Evidence recording is play-only and config-gated per the D1 evidence rule (standards/rules/evidence-recording.md).

# --- Standard Play Close (canonical; see standards/rules/play-close.md) ---
# Path tokens resolved at pre-flight (resolve here if not already):
#   ltm_project_target  = yq '.ltm.project-target' .garura/core/config.yaml
#   evidence_base, slug:
#     project-scoped play : evidence_base="${stm_base}${issue}/evidence/roadmap/"  ; slug="#${issue}"
#     product-scoped play : evidence_base="${product_base}_evidence/roadmap/"        ; slug="${product_slug}"
evidence_template=$(cat "${ltm_project_target}standards/templates/evidence-file.md")
delivery_template=$(cat "${ltm_project_target}standards/templates/delivery-report.md")
ts=$(date -u +%Y%m%d-%H%M%S)
evidence_dest="${evidence_base}${ts}.md"
mkdir -p "$(dirname "$evidence_dest")"
# Session identity stamp (#463) — close phase; start phase ran at pre-flight
session_stamp=$(python3 scripts/session_stamp.py --phase close \
    --marker "${stm_base}_shaping/roadmap/status/session-stamp-roadmap.json")
# Stop-condition gate (#464) — Step C0: this play carries a baked manifest, so the
# gate is LIVE. Evaluate the Done means against the run's STM working root as the
# close's authoritative input.
python3 scripts/check_stop_condition.py \
    --manifest "<play-dir>/stop-condition.yaml" \
    --base "${stm_base}_shaping/roadmap/" \
    --out "${stm_base}_shaping/roadmap/status/stop-condition-roadmap.yaml"
sc_exit=$?   # 0 held · 1 unmet · 2 error
# Conditional-gate policy refresh (#467) — soft: a distill failure never blocks the close
python3 scripts/distill_gate_policy.py --ledger "<gates.conditional.ledger>" --policy "<gates.conditional.policy>" --streak <gates.conditional.streak> --project "<project name from config>" || true

/roadmap is product-scoped: evidence_base="${product_base}_evidence/roadmap/" and slug="${product_slug}" (the product, since one run plans the whole set).

Step C0 — bind the verdict. sc_exit == 0 (held) permits status: COMPLETED. Anything else closes HALTED with exit_reason: stop_condition_unmet and the evidence's Stop Condition section names every unmet clause. An unevaluable verdict is never a pass.

Step C1 — Write evidence file. Gated by the resolved evidence.record flag (global

• per-play evidence.plays.roadmap; first match wins, absent ⇒ record). When false, skip the write and record evidence skipped (record=false) in the report's pointer line. Otherwise fill the evidence-file.md slots (play roadmap, run_id roadmap-${ts}, product_slug, started_at/completed_at, status per C0, exit_reason; artifacts produced: the plan draft, the plan, the apply manifest, the slices planned, the stop-condition verdict; step and scenario eval results SE-1…SE-10 / SCE-1…SCE-6; checkpoint decision from Step 4 including the order and any anomalies (incl. any gate skipped by config / gate auto-passed by learned policy row) plus the gate ledger line(s) appended this run; the session identity stamp fields from $session_stamp (#463): session_id, ledger_file, ledger_start_offset, ledger_end_offset (null when unresolved — never blocks the close); and stop_condition per C0 with the Stop Condition section filled) and write to $evidence_dest. Do NOT hand-author the body.

Step C2 — Render delivery report. Also render the Next line: resolve this play in standards/rules/pipeline-next.md and emit **Next:** /<command> — <why>. Or run /next to see all recommended actions. (only /next pointer, or omit, when the mapped command is null), per play-close.md. Fill the delivery-report.md slots and output the report: ## roadmap Delivered — ${product_slug}, the Run Summary table, the Pipeline Steps table from the task DAG, the Artifacts Produced table (the ordered slices with effort + dependencies, any anomalies), Next Steps (run /grill on the top-ordered slice's functionalities to cut epics), and a pointer to $evidence_dest. Always emitted; never gated.

# --- end Standard Play Close ---

Scenario Validation

Scenario	Persona	Eval
S1 — first plan	planner	SCE-1
S2 — dependencies	architect	SCE-2
S3 — effort	delivery lead	SCE-3
S4 — cross-domain	product manager	SCE-4
S5 — re-run non-destructive	product owner	SCE-5
S6 — the checkpoint	reviewer	SCE-6

Recovery

For	Trigger	Direction	Handoff
F1	a plan was written onto a non-slice artifact	revert it; /roadmap plans only /shape slices	autonomous
F2	a write touched a slice's composition (record) or another part of the model	revert the out-of-scope write; /roadmap writes only order/effort/depends_on/status on the spine slices	autonomous
F3	a slice is ordered ahead of one it depends_on	re-sort so dependencies precede dependents before persisting	autonomous
F4	a planned slice lacks order or effort, or the orders aren't a coherent 1..N	recompute a complete, coherent plan — an integer order and an effort for every planned slice	autonomous
F5	a dependency cycle, or a domain's slices left unplanned	surface the cycle at the checkpoint for a human to break, and include every shaped domain's slices in the single plan	human
F6	a non-plan slice field changed, or a non-spine product-model file changed	restore the changed content and re-apply only the plan fields, after a human confirms the restore	human
F7	a written slice spine entry fails the spine schema	re-emit the failing entry to conform before the play completes	autonomous
F8	a plan was persisted before the checkpoint gate resolved (no typed approval, no recorded config skip, and no recorded policy auto-pass)	revert the premature write and re-present the checkpoint; persist only after the gate resolves	human
F9	the run is about to close COMPLETED with the Done means unmet (a missing plan draft or computed plan record, or orders_coherent not true)	produce the missing artifact — re-run the draft and compute_plan.py so the plan record carries the machine order fields — then re-evaluate the stop condition; the close stays HALTED until the verdict reads held	autonomous
F10	a conditional-gate crossing left no live-eval ledger line, or an auto-pass fired for a shape the policy does not list as auto (or that carried a blocking finding)	re-append the missing ledger line for the recorded crossing; when the auto-pass was unearned, re-run the gate as a live wait — render the approval prompt and wait for the typed response — before proceeding	autonomous

Pause and Resume

Steps run top to bottom. On entry, resolve config, run the write-free pre-flight probe, check the status marker ({stm_base}_shaping/roadmap/status.json), skip completed steps, reset any in-progress step to pending, and continue. The pre-apply snapshot is captured at Step 1 (a gated step) and preserved on resume, so the non-destructive comparison always diffs against true pre-apply state. A fresh start with no marker runs everything and creates the marker at Step 1.

Compilation Metadata

Field	Value
fingerprint	sha256:e5fdd938574e720154ce938a20cc9eee1790aa7d6b761814f5c247e7046b4c91 (of reference/ice.md)
compiled_by	play-editor (#467 Batch B); prior: play-editor (#466 Batch C)
pipeline_position	end (commit-change → propose-change → review-change → merge-change tail; opened by /vision)
workflow_structure	A (single checkpoint, class standard, conditional gate per gate-config.md #467)
stop_condition	stop-condition.yaml (D1–D3), gate live at Step C0
domain_agents	1 (product-os-keeper)
utility_agents	0
skills_used	author-roadmap
scripts	10 (preflight.py, snapshot_model.py, compute_plan.py — writes the machine orders_coherent field, apply_roadmap.py, validate_roadmap.py, classify_change.py — #467 shape classifier, gate_eval.py — #467 live-eval ledger, distill_gate_policy.py — #467 policy learner, check_stop_condition.py — Done-means gate, session_stamp.py — #463 identity stamp)
step_evals	10 (SE-1…SE-10)
scenario_evals	6 (SCE-1…SCE-6)
recovery_entries	10 (one per failure condition; 7 autonomous / 3 human)

Recompiled note (#467 Batch B): checkpoint upgraded to a conditional learned gate; see gate-config.md.