@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/{skills/auto/references → docs/help}/agent-architecture.md

@@ -28,13 +28,14 @@ in 2.0, intent 304; the lead writes the Why and How record itself):
   reviewed before code; dispatches the executor; applies the risk rule; closes.
 - **plastic-executor** (Exec): commits the matrix's tests red, writes the code, checks off
   `checklist.md`, appends `## Insights`, and drives the suite green.
-- **the plan reviewer**: a fresh agent on `plastic-intent-executing`'s
-  `plan-reviewer-prompt.md`, dispatched once before any code exists.
-- **the post-execution reviewer**: a fresh agent on `code-quality-reviewer-prompt.md`,
+- **the plan reviewer**: a fresh agent on the auto skill's
+  `references/plan-reviewer-prompt.md`, an optional dispatch before any code exists.
+- **the post-execution reviewer**: a fresh agent on `references/code-quality-reviewer-prompt.md`,
   dispatched only when the auto skill's risk rule fires; never the maker.
 
-Two agent boots is the normal delivery (the plan reviewer, the executor); the post-execution
-reviewer is the third only when risk calls for it.
+One agent boot (the executor) is the minimum delivery; the plan reviewer is a second,
+optional boot when the lead calls for review before code, and the post-execution reviewer is
+a third only when risk calls for it.
 
 ### Handoff Contracts
 
@@ -44,8 +45,8 @@ the code, the red and green commits, a checked-off checklist, `## Insights`, and
 report. Dispatch is sequential on a single branch, because the deliverables share files.
 
 The chain: intent `## Intent` / `## Context`, then enriched `## Context` plus `### Decisions`,
-then `spec.md`, then `plan.md` plus `actions/` plus `checklist.md`, then the plan review, then
-the code changes plus a checked-off checklist plus `## Insights`.
+then `spec.md`, then `plan.md` plus `actions/` plus `checklist.md`, then an optional plan
+review, then the code changes plus a checked-off checklist plus `## Insights`.
 
 ### Spawn Preamble (L2 live-state injection)
 
@@ -88,9 +89,10 @@ not revoke the registered delegate's authorization.
 
 ### Review Ownership
 
-The lead owns every review decision: it dispatches the plan reviewer before code, folds the
-findings itself, and decides from the risk rule whether the post-execution reviewer runs. It
-never delegates that decision, and neither reviewer is ever the maker of what it reviews.
+The lead owns every review decision: it dispatches the plan reviewer before code when one
+runs, takes the review into its own record, and decides from the risk rule whether the
+post-execution reviewer runs. It never delegates that decision, and neither reviewer is ever
+the maker of what it reviews.
 Nothing blocks a write in 2.0 (the gate hooks were removed, intent 302); the lock, the
 worktree, and the record are how the team keeps one delivery in one place.
 
@@ -116,14 +118,14 @@ written path, and the lead verifies state from the files (`plastic-lock status`,
 ### Delegation
 
 The roles are thin handoff contracts, not a spawning engine. Dispatch runs through Plastic's
-own engine, `plastic-intent-executing`: one executor for the consolidated action, the two
+own engine, `plastic intent step`: one executor for the consolidated action, the two
 reviewer prompts as fresh agents. The team model defines who hands what to whom and where the
 reviews sit; the engine does the actual spawning.
 
 ### Fallback by Case
 
 If the harness supports agent dispatch, auto mode dispatches through
-`plastic-intent-executing`. If the harness has no agent dispatch at all (Codex CLI today), the
+`plastic intent step`. If the harness has no agent dispatch at all (Codex CLI today), the
 lead walks the five steps itself: it still writes the matrix and the tests first, and reviews
 its own plan against the matrix before code, saying so in `## Insights`.
 
@@ -145,8 +147,8 @@ tests first, one suite run per intent.
 ## Autonomous Delivery
 
 Human owns What and Why for human-initiated intents. The team assists (research, exploration)
-but the human drives until handoff. When Why is complete, or the human triggers `plastic-auto`,
-the auto team takes over How and Exec autonomously.
+but the human drives until handoff. When Why is complete, or the human runs
+`plastic auto take ID`, the auto team takes over How and Exec autonomously.
 
 - **Safe-by-default:** the executor always prefers non-destructive routes (rename vs delete,
   additive migrations, backups before changes). Destructive actions on existing projects

package/{skills/conventions/references → docs/help}/completion-and-done.md

@@ -1,26 +1,26 @@
-# Completion and Done
+# Completion and the End Tail
 
 This chapter holds what "intent done" means and the End-stage tail.
 
 #### What "intent done" means (intent 93)
 
-Done is one law with three signals, and they must agree. INDEX `## Completed` /
+Completion is one law with three signals, and they must agree. INDEX `## Completed` /
 `## Abandoned` is the single canonical terminal marker: it is the store-wide ledger a fresh
 session reads first, so it wins on any conflict. `outcome.md` is the "deliverable exists"
-signal, and the savepoint `Done delivered|abandoned` line is the audit echo. All three must
-agree; when they disagree, INDEX is authoritative and `doctor` flags the mismatch (the
+signal, and the savepoint's terminal `delivered|abandoned` line is the audit echo. All three
+must agree; when they disagree, INDEX is authoritative and `doctor` flags the mismatch (the
 `done_signals` check: `outcome.md` real but still under `## Active`, or terminal without a
-real `outcome.md`, or a terminal intent whose savepoint carries no `Done` line).
+real `outcome.md`, or a terminal intent whose savepoint carries no terminal disposition line).
 
 `outcome.md` is mandatory at every terminal transition, delivered and abandoned alike. It
 self-declares its disposition through a `disposition: delivered|abandoned` frontmatter
 header. The delivered path authors it with the result; the abandoned path authors it with
 the abandonment reason and no longer leaves the scaffolded placeholder sentinel in place.
 
-The canonical End tail runs in this order, and the QMD reindex is always LAST, after the
-purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Worktree.release
--> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
-ever referencing a bridge or lock that disarm is about to remove.
+The canonical End tail runs in this order: `outcome.md -> INDEX terminal -> the terminal
+savepoint line -> commit -> disarm (Worktree.release -> Lock.release) -> QMD reindex`, the
+reindex always LAST. Running the reindex last keeps the index from ever referencing a lock
+that disarm just removed.
 
 `scripts/end-intent` performs this order's disarm step (verify the code worktree is clean,
 then merge/remove worktrees, then clear the lock) as its own step 5, mechanically, since
@@ -31,13 +31,12 @@ foreign session, reclaims a stale one with an audit line), and a dirty code work
 refuses before removal rather than force-discarding uncommitted changes.
 
 The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
-the completing session keeps full read and write access to the terminal directory and no
-purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
-Once the lock is released the window closes: the bridge becomes purge-eligible and the
-directory is frozen. A crash mid-tail is recovered by stale-lock reclaim plus finishing the
-tail; `doctor` surfaces this as a "stalled completion" (terminal in INDEX but the lock is
-still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
+the completing session keeps full read and write access to the terminal directory (108's
+lock-held keep-guard holds it open while `delivery.lock` exists). Once the lock is released
+the window closes and the directory is frozen. A crash mid-tail is recovered by stale-lock
+reclaim plus finishing the tail; `doctor` surfaces this as a "stalled completion" (terminal in
+INDEX but the lock is still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
 a done intent is never moved back to `## Active`.
 
 One report per audience: a delivery produces `outcome.md` plus one EM-to-CTO owner report, and
-no other step restates either (see `skills/auto/references/human-report-contract.md`).
+no other step restates either (see `plastic help human-report-contract`).

package/docs/help/human-report-contract.md

@@ -0,0 +1,152 @@
+# Human Report Contract (the report screens, intent 317)
+
+D15: the prose EM-to-CTO briefing this doc used to define is retired. The orchestrator now
+prints one of these report screens, filled from the record by `scripts/report-screen`, never
+written by eye:
+
+- **`report-screen plan <intent_dir>`** - the pre-delivery report (intent 331b), printed once
+  at the How boundary, before the executor is dispatched: Asked, Decisions, Steps, Mode,
+  Reviewer, then the Steps table (Step, Action, What) and the Risks table.
+- **`report-screen state <intent_dir> [--changed "<text>"]`** - the mid-delivery report. One
+  intent's field table (Store, Status, Stage, Savepoint, Progress, Next, Insight) plus a
+  `Changed` row naming what caused the print, and its Steps table.
+- **`report-screen state --all <store_root>`** - the roster across every in-delivery intent,
+  most recently changed first, then one collapsed block (Stage, Next, Changed, first three
+  open steps) per intent.
+- **`report-screen delivered <intent_dir>`** - the post-delivery report, printed once at close:
+  Asked, Delivered (with a Proven-by column), Evidence, Needs you.
+- **`report-screen delay <intent_dir>`** - printed only on request ("why did X take so long"):
+  the delivery as a timeline plus the derived `Where the time went` line.
+- **`report-screen session <tier_root>`** - the answer to an UNNAMED status ask ("where are we
+  with delivery", "what is the status"): one `delivered` screen per intent this session
+  completed, oldest first, then the `state --all` roster. Intent 330's ruling: a status ask
+  answers with what actually shipped, not the in-flight roster alone.
+- **`dashboard.rb continue|project <slug> --screen`** - the dashboard screen (intent 331d):
+  Active, In delivery, Delivered, Roadmap, Sessions, Changed, then the Where-we-are and
+  Where-we-go-next tables. A separate script from the other four (`dashboard.rb`, not
+  `report-screen`), since it aggregates across a whole store or project rather than one
+  intent; it prints on `continue` and on loading a project, not as a delivery trigger.
+
+## Binding table (intent 331f)
+
+Every command or lead role that shows state names its own report verb, one row per binding
+and trigger. Each one carries the SAME rule next to its verb: print the screen as the first
+characters of the reply, nothing before it, no fence, or the hook cannot paint it.
+
+| Command or lead | Trigger | Verb |
+|---|---|---|
+| `plastic continue` | project route (continue, load project) | `dashboard.rb ... --screen` |
+| `plastic continue` | a named intent | `report-screen state` |
+| `plastic continue` | "where are we" (a status ask) | `report-screen session` |
+| `plastic continue` | "why so long" | `report-screen delay` |
+| `plastic continue` | a roadmap route | `report-screen roadmap ... state` |
+| the auto team's lead | the How boundary, before the executor | `report-screen plan` |
+| the auto team's lead | each of the five triggers | `report-screen state` |
+| the auto team's lead | close | `report-screen delivered` |
+| `plastic intent end` | the close | `report-screen delivered` |
+| `plastic intent spec` | the action files are written | `report-screen plan` |
+| `plastic roadmap show` | any invocation | `report-screen roadmap ... state` |
+| `plastic status` | any invocation | in-process (`Scope#stores`) |
+| `plastic intent step` | after the red commit, and after the suite | `report-screen state` |
+
+## A roadmap's own three reports (intent 331c)
+
+A roadmap gets the same pre-, in-, and post-delivery shape as an intent, through
+`report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]`:
+
+- **`roadmap plan`** - the pre-delivery report: the Goal's first sentence, the batch (or legacy
+  wave) count and intent count, the batch order, and when the roadmap was created; then the
+  full entries table.
+- **`roadmap state`** - the in-delivery report: Goal, a Progress bar over intents delivered of
+  intents total (never batches), the frontier batch, who is delivering it and their lead, the
+  next queued entry, and the last ledger event; then the entries table with each entry's own
+  checklist progress and lead.
+- **`roadmap delivered`** - the post-delivery report: a meta line (closed time, or `in progress`
+  when the goal is not yet reached; intent count; duration) directly under the title, the
+  delivered table with each entry's merge sha, and the `## Log` table.
+
+Every cell traces to the roadmap file, `INDEX.md` (which always wins on status), the roadmap's
+own savepoint ledger, or (falling back when no ledger file exists) the roadmap's `## Log` -
+never a second parser: `RoadmapQueue`'s own public `roadmap` reader supplies every entry.
+
+## The five triggers for `state`
+
+Print `state` (one intent, or `--all` for the roster) on any of these; a checklist tick alone,
+an executor's intermediate commit, or an agent going idle is NOT one of them:
+
+| Trigger | Scope |
+|---|---|
+| A savepoint line lands (a stage boundary: Why, How, Exec started, outcome written, End) | that intent |
+| A review verdict returns (plan review or post-execution review), naming what it changed | that intent |
+| A blocker or needs-input is logged | that intent |
+| A merge or a release lands | that intent |
+| The owner asks ("where are we", "state of X", "continue X") | all in delivery, or the one named |
+
+`delivered` prints exactly once, at Completion. `delay` prints only when the owner asks why a
+delivery took long.
+
+Every verb prints the same plain Markdown on every harness (owner ruling 2026-08-31); where a
+harness can paint it (Claude Code, through 316a's message-display hook), it substitutes a
+painted rendering of that same output, never a different one, and no skill or script branches
+on harness name to decide.
+
+## Depth for small work
+
+For small work in auto mode, only the How-boundary `plan` screen prints mid-flight (intent
+331f moved this print off `state`, since there is no separate briefing per stage any more).
+Larger work prints `state` at every trigger in the table above. This is a
+depth cut, not a different report: the screen's shape never changes, only how often it fires.
+A delivery still ends with `outcome.md` plus one `delivered` screen.
+
+## One report per audience
+
+A delivery produces exactly two artifacts: `outcome.md` (generated by `scripts/end-intent`
+from `graph.md`, `nodes/`, and the ledger when the intent has one, intent 339; hand-authored
+by `plastic intent end` otherwise) and one `delivered` screen at the End stage. No stage or skill restates a delivery already
+written to `outcome.md`; point at it instead. Skills do not open with a banner that names the
+skill or restates the intent id and name the owner just typed. Announce only what the reader
+cannot already know: an error, a result, a choice with its reason, or a handoff.
+
+## Boundary vs intent 74
+
+Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
+machine-checked handoff from a dispatched specialist back to the orchestrator: a structured
+envelope plus a per-role payload. This contract is the OUTWARD screen shown to the owner.
+Different direction, different audience, different form. The orchestrator reads the intent 74
+report and reflects it into the record (savepoint, outcome.md) that `report-screen` then
+renders. The two never merge.
+
+## Brevity: point, don't repeat
+
+Surface rules are owned by the `plain-writing` skill. This contract does not restate them. Its
+job is naming which screen prints when, not the wording inside it - `report-screen` derives
+every cell from the record (D14), so there is no prose left to style here.
+
+## Emission: guided vs auto
+
+In guided mode, `state` prints at each stage boundary and the human decides before the next
+stage starts.
+
+In auto mode, `state` prints at every trigger for larger work; for small work only the How
+boundary's `plan` screen prints (see `## Depth for small work` above). The orchestrator takes
+the go-ahead itself and moves on, except at the existing hard stops (destructive action without
+a safe alternative, project-path confirm).
+
+## Column vocabulary (D5, intent 331f)
+
+Owner ruling 2026-09-05 11:05 UTC: "What" is never a column name, because What is a stage, not
+a value. The id column reads `Graph ID`; the title column reads `Intent`. Every Steps table
+reads `Step | Status | Detail` (the plan screen's own Steps table reads
+`Step | Action | Detail`); every Risks table reads `N | Risk`; the Delivered/Evidence/Needs-you
+tables on the `delivered` screen read `Row | Detail | Proven by`, `Kind | Detail | Source`, and
+`N | Need | Reason`. The plan screen's Asked row prints the intent title before its first
+colon, never the whole intent line. This applies to every screen the family prints: `state`,
+`roster`, `session`, `delivered`, `delay`, `plan`, `roadmap` (`plan`/`state`/`delivered`), and
+`dashboard`. `outcome.md`'s own `| Row | What |` heading is an AUTHORING convention inside the
+file a human writes, never a rendered header, and stays unchanged.
+
+## Width bound (D7, intent 331f)
+
+No rendered row passes 115 visible columns. A long cell (the roadmap Goal, an intent title, an
+Asked line) truncates on a word boundary with a single ellipsis; `ReportScreen.fit_screen`
+shrinks a table's widest column first, floor 8, before it ever truncates a whole row.

package/{skills/conventions/references → docs/help}/knowledge-graph.md

@@ -45,3 +45,12 @@ This chapter holds the linking doctrine from Frontmatter and the branch-vs-root
   the relation on the PREDECESSOR's `chain` (and mirror it as a
   `[[id--slug|<target's full intent: text>]]` wikilink in `## Links`).
 - **Rule of thumb:** if the intent could exist without its parent, it's a root.
+
+## Naming
+
+A thing is named after the concept family it lives under. A node is a graph-engineering
+concept, so its name comes from graph engineering (node, edge, ready set, critical path),
+from the Plastic concepts coined on top of it (intent, ledger, node input, lease, gate, runner),
+and from the software and AI engineering concepts those rest on (review, fix, test, verify,
+dispatch, executor, reviewer). A name from outside that stack is refused. Where no existing
+concept fits, that is a design finding to raise, not a word to coin.

package/{skills/conventions/references → docs/help}/locks-and-worktrees.md

@@ -4,10 +4,10 @@ This chapter holds the delivery lock, claims, worktrees, the fail-safe doctrine,
 
 ### Delivery Isolation and the Single-Owner Lock
 
-Locks and worktrees exist only for auto teams. An interactive session working direct or
-thinking takes no lock: it records into the day ledger, or into the intent its per-session
-pointer names (`~/.plastic/store/.tmp/<session>/current`, where `<session>` is the first eight
-characters of the session id; the file holds today's day id or an intent id).
+The delivery lock names the session delivering an intent, as its owner or a delegate. Locks
+and worktrees exist only for auto teams: an interactive session working direct or thinking
+takes no lock and records into its day ledger instead (the oldest day in the last seven whose
+checklist carries the session's line, else today).
 
 For an auto team, exactly one team develops an intent's delivery at a time. Ownership is
 session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
@@ -17,9 +17,7 @@ but never grants access and is never inferred from transcripts or filesystem pat
 fields on legacy locks display as `Unknown`. Liveness is a lease: the record hook refreshes
 the lock file's mtime on every write the owning session makes, and that mtime is the sole
 heartbeat truth. The lock counts as stale only when the mtime is older than the TTL. No
-process id is consulted anywhere. The pointer file is a cache of which intent a session
-records into; the lock file is the truth of who owns a delivery, and wins on any
-disagreement. Another team that finds a fresh lock backs off; a stale lock is reclaimed only
+process id is consulted anywhere. The lock file is the truth of who owns a delivery. Another team that finds a fresh lock backs off; a stale lock is reclaimed only
 by explicit takeover, which replaces the lock and appends an audit line to the intent's
 savepoint.md. Rearming the same session preserves its acquired identity and refreshes known
 provenance; an explicit takeover replaces the controller and starts new provenance.
@@ -31,7 +29,7 @@ retained as descriptive history, bounded to the 20 most recent terminal entries.
 a delegate, and an artifact claim are distinct evidence: controller ownership authorizes the
 delivery, delegate registration authorizes a child session, and a claim selects one current
 writer for one artifact. Disarm clears the lock; the End tail is ordered: verify, merge and
-remove worktrees, clear the lock, and only then is the session pointer purge-eligible. Repair
+remove worktrees, then clear the lock. Repair
 is one idempotent function with two entry points: the `plastic-lock` command (`who`, status,
 fix, release, reclaim, delegate) and the `plastic-doctor` skill's lock section, so repair
 self-heals. `who` is read-only and reports the controller, mtime heartbeat, delegates, and
@@ -84,24 +82,24 @@ Provisioning fails open for intents that touch no project code (pure research or
 intents in the global store, or a non-git repo): those get the lock only, and the worktree
 block stays unprovisioned. The fail-open path is always logged, never silent.
 
-Cleanup is part of Done: the End tail merges the branch, then removes the worktree. Never leave
+Cleanup is part of the End tail: it merges the branch, then removes the worktree. Never leave
 an orphaned worktree behind, and clear a stale worktree reference with `git worktree prune`.
 
 
 #### Intent delivery, station by station
 
-How one auto-team intent travels from boarding to Done, and what the lock, the pointer, and
+How one auto-team intent travels from boarding to the End tail, and what the lock and
 the record hook do at each station. Nothing in the third column blocks; the fourth column is
 what gets written down.
 
-| Station | Delivered artifact | Lock and pointer steps | Record |
+| Station | Delivered artifact | Lock steps | Record |
 |---|---|---|---|
-| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree, writes the session pointer | savepoint confirms the boarding station |
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree | savepoint confirms the boarding station |
 | What (create) | `<id>--<slug>.md`, born complete | no lock yet; `new-intent` validates the file it writes (`scripts/validate-intent`) | savepoint `What` line; intent listed in INDEX `## Active` |
 | Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | savepoint `Why started`, `Why spec.md created` |
 | How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
 | Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock | checklist boxes; savepoint milestones; the day-ledger line promotes when a project file lands |
-| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the pointer is purge-eligible, and the QMD reindex runs LAST (after purge); `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
+| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, and the QMD reindex runs LAST; `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | the savepoint's terminal `delivered` (or `abandoned`) line; takeover audits, if any, remain in savepoint.md |
 | Maintenance (Future, Terminal, or Active-with-a-stale-or-no-lock) | `revisions.md` move-and-record entries | detects (never acquires) `delivery.lock`; defers and reports while the target's lock is FRESH (`Lock.fresh?`); a stale or absent lock is not-active, maintenance proceeds | append-only, rule-tagged `revisions.md` entry written in the same operation as the change, or the change is refused; lands via a fresh branch off store main merged back as one closed op, never `git add -A` |
 
 ## The write guard is not residue

package/{skills/conventions/references → docs/help}/maintenance-and-revisions.md

@@ -8,7 +8,7 @@ Plastic separates two different things an earlier doctrine blurred under one wor
 "immutable." WORK is the delivered CONTENT an intent produced: the code and project files a
 delivery changed, the research it recorded, the outcome it wrote. Once the intent is terminal
 (Completed or Abandoned), that content is immutable - the only way to change it is another
-intent that continues or reverts it. Editing a Done intent's own artifacts so it looks like it
+intent that continues or reverts it. Editing a terminal intent's own artifacts so it looks like it
 delivered something different, or that parts are missing, is forbidden (the book analogy:
 never rewrite the text on the pages of an old, valuable book).
 

package/{skills/conventions/references → docs/help}/roadmaps.md

@@ -6,8 +6,8 @@ This chapter holds the full roadmap file format and its relationship to INDEX.md
 
 Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
 is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
-release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
-close, and consume one.
+release (completion-side, tracked in `CHANGELOG.md`). Create one by hand from the template, then
+use `plastic roadmap show`, `next`, `log`, and `check` to read, drive, and audit it.
 
 File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
 inside `store/` (store holds intent directories, not project artifacts). For a project that is its

package/{skills/tutorial/references → docs/help}/track-1-guided.md

@@ -9,7 +9,7 @@ end to end: a piece of work moved through What, Why, How, and Exec, with a finis
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: this track always creates a global-store intent; the throwaway repo below
@@ -22,7 +22,7 @@ directory instead (see station 6). Either way, nothing in this track touches a r
 
 ### 1. Create the intent
 
-Type `/plastic-intent-creating` and describe the work in plain words, for example "add a
+Run `plastic intent new` and describe the work in plain words, for example "add a
 short Usage section to this project's README."
 
 Artifact: a new intent directory, `{id}--slug.md`, plus the sentinel placeholder lifecycle
@@ -35,7 +35,7 @@ tool, never written by hand.
 
 ### 2. Board the intent
 
-Type `/plastic-intent-continuing` and name the intent.
+Run `plastic continue` and name the intent.
 
 Artifact: a delivery lock (a `delivery.lock` file in the intent directory) naming this
 session as the one owner, and a line in `savepoint.md` recording the stage. The agent then
@@ -46,78 +46,59 @@ sessions from editing the same intent at the same time.
 
 ### 3. Why, rulings one at a time
 
-Type `/plastic-intent-speccing` (say "grill me" for a harder, interview-style pass over
+Run `plastic intent spec` (say "grill me" for a harder, interview-style pass over
 the same ground). It asks conversational prose questions, one at a
 time, never a multiple-choice menu, and answers them one at a time in return.
 
 Artifact: `## Context` and `### Decisions` in the intent file fill in as each answer lands, and
 each ruling also lands as its own `## Insights` entry the moment it is made, never batched for
-later. This station's product is the enriched Why; it hands off to `/plastic-intent-speccing`
+later. This station's product is the enriched Why; it hands off to `plastic intent spec`
 next, it does not write `spec.md` itself.
 
 Checkpoint: after two or three answers, look at the intent file. Every ruling given out loud
 is already sitting in `### Decisions` and in `## Insights`, in writing.
 
-### 4. Consolidate the spec
+### 4. How, write the graph
 
-Type `/plastic-intent-speccing`.
+Ask the same conversation (`plastic intent spec`) to turn the rulings into the graph.
 
-Artifact: `spec.md`, its eight sections filled from the rulings recorded in station 3.
+Artifact: `graph.md` (nodes, edges, dispatch policy) and one `nodes/N.md` file per node this
+small delivery needs. A delivery this size is one node; many independent tasks instead get
+one node each, dispatched in parallel by the runner.
 
-Checkpoint: point at one sentence in `spec.md` that traces back to an answer given in
-station 3.
+Checkpoint: open `graph.md` and point at the one node this worked example needs.
 
-### 5. Plan
+### 5. Exec, drive the runner loop
 
-Ask the same conversation to write the action files and the plan.
+Run `plastic intent step`.
 
-Artifact: `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md`. A small
-delivery like this one consolidates the whole delivery into a single `actions/ACTION_1.md`
-(the ordered steps plus the exact changes); many independent tasks, dispatched in parallel,
-instead get one `actions/ACTION_N.md` file per task. `checklist.md` follows a fixed form: tasks start under `## In Progress`, move to
-`## Completed` as they land, and a `## Session Log` table records what happened each session.
-A task that depends on an owner decision landing first (a destructive step, a structural
-ruling) gets an `[ORCHESTRATOR]` prefix and blocks every other item until that decision is
-made; this worked example has none.
-
-Checkpoint: open `checklist.md`. Every task in `plan.md` has a matching checkbox under
-`## In Progress`; that checklist, not `plan.md` itself, is what gets ticked off and moved to
-`## Completed` during Exec.
-
-### 6. Exec, verify before you report
-
-Type `/plastic-intent-executing`.
-
-Teach the order: first the agent syncs its working copy with the main line, so no edit lands
-on a path a merged change upstream has already touched or removed. Then it makes the change,
-runs whatever verifies it (a test suite, or a manual check for a docs change like this one),
-and only then ticks the checklist box, moving the task from `## In Progress` to
-`## Completed` and adding a `## Session Log` row, before moving to the next task. Verifying
-always comes before checking a box, never after, and each task is ticked the moment it lands,
-never batched for later.
+Teach the loop: `ruby scripts/runner step <intent_dir>` computes which nodes are ready and
+prints a spawn block to dispatch, `ruby scripts/runner status <intent_dir>` reads the
+ledger (running, done, blocked, or waiting on a decision), and `ruby scripts/runner answer`
+closes a node that needs an owner's ruling. Call `step` again after each dispatched node
+returns, until the graph is empty.
 
 Artifact: the actual change on disk (the new README Usage section, or, in the global-store
-fallback, a short written note saved as the intent's deliverable) and a fully ticked
-`checklist.md`.
+fallback, a short written note saved as the intent's deliverable) and every node in
+`graph.md` at a terminal status.
 
-Checkpoint: find the new Usage section in the README (or the written note) and confirm every
-box in `checklist.md` is checked and moved to `## Completed`, with a `## Session Log` row for
-this session, before moving to station 7.
+Checkpoint: run `runner status` and confirm no node is left running or blocked, before
+moving to station 6.
 
-### 7. Done
+### 6. End
 
-Type `/plastic-intent-ending`.
+Run `plastic intent end`.
 
-Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups), the intent
-moved from `## Active` to `## Completed` in `INDEX.md`, and a closing `Done` line in
-`savepoint.md`.
+Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups) generated by
+`scripts/outcome-report` from `graph.md` and the ledger, the intent moved from `## Active`
+to `## Completed` in `INDEX.md`, and the terminal savepoint line.
 
 Checkpoint: open `outcome.md` and read its Summary. It should describe, in a sentence or
 two, exactly the README section (or note) just delivered.
 
 ## Wrap and where to go next
 
-That is the full cycle once: create, board, decide, spec, plan, build, done. Read
+That is the full cycle once: create, graph, runner step, end. Read
 [`your-first-intent-in-10-minutes.md`](https://github.com/zalom/plastic/blob/main/docs/guides/your-first-intent-in-10-minutes.md) for the same path condensed to a single
 read, and [`reading-the-ledgers.md`](https://github.com/zalom/plastic/blob/main/docs/guides/reading-the-ledgers.md) for where each station wrote its
 work down.

package/{skills/tutorial/references → docs/help}/track-2-auto.md

@@ -9,7 +9,7 @@ agent end to end, and pausing and resuming that delivery will feel familiar.
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: a throwaway git repository, or a global-store intent. Nothing in this
@@ -19,8 +19,8 @@ track touches a real project.
 
 ### 1. Board a small intent and choose auto
 
-Start from an active intent (create one first with `/plastic-intent-creating` if none
-exists, the same way as track 1 station 1). Type `/plastic-auto`.
+Start from an active intent (create one first with `plastic intent new` if none
+exists, the same way as track 1 station 1). Run `plastic auto take ID`.
 
 Artifact: the delivery lock arms, and the agent announces it is taking over the intent for
 autonomous delivery.
@@ -33,7 +33,7 @@ queued intent from the dashboard's queue itself.)
 
 No new command at this station. Watch how the work splits.
 
-Auto owns How (the plan, the checklist, the action files) and Exec (the code, the tests, the
+Auto owns How (`graph.md`, `nodes/`) and Exec (the code, the tests, the
 mechanical close) from here on. Inside Exec it follows a few fixed habits: it syncs its
 working copy with the main line before touching anything, ticks each task the moment it
 lands rather than batching several into one later edit, and independently verifies its own
@@ -45,7 +45,7 @@ can review how it checked, not just what it found.
 The user keeps two things: the rulings made along the way, and the review points, moments
 auto is built to pause for, such as confirming a project path or stopping before a
 destructive action with no safe way back. When auto tells you to run a command yourself
-("run /plastic-intent-speccing"), that is an instruction for you to type; it is a different
+("run plastic intent spec"), that is an instruction for you to type; it is a different
 thing from the prompts auto hands to its own dispatched subagents, and the two are never
 mixed up in what it tells you.
 
@@ -63,18 +63,18 @@ Checkpoint: open the intent's `savepoint.md` and name the stage its last line re
 
 ### 4. Reading the per-stage reports
 
-No new command. At each stage boundary (What, Why, How, Exec, Done) the agent briefs in a
+No new command. At each stage boundary (What, Why, How, Exec) the agent briefs in a
 fixed three-line shape: State (what happened and why it matters), Risk (the one thing that
 could bite, or "nothing flagged"), and Call (the decision left to the user, or the call the
 agent is taking on its own). That is the depth for a medium or large intent. A small intent
-gets one briefing, at How, folding in what the earlier stages would have said.
+gets one briefing, at How, merging in what the earlier stages would have said.
 
 Checkpoint: in the most recent report, point at the State line, the Risk line, and the Call
 line.
 
 ### 5. Continue and where-was-I after time away
 
-Type `/plastic-intent-continuing`.
+Run `plastic continue`.
 
 Artifact: the current state, presented and then the session stops. If a specific intent is
 named, the agent reads its stage and savepoint and resumes exactly there, rather than