@zalom/plastic 2.0.1 → 2.0.3

package/docs/help/roadmaps.md

@@ -7,19 +7,24 @@ 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`). Create one by hand from the template, then
-use `plastic roadmap show`, `next`, `log`, and `check` to read, drive, and audit it.
+use `plastic roadmap show`, `next`, `log`, `check`, and `migrate` to read, drive, audit, and
+upgrade 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
-root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
-`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
-in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
-a sibling subdirectory scaffolded once with a `.gitkeep`.
-
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Batches`, and an
-append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Batches` holds ordered batches; entries inside a batch are
-parallel-safe, batches run sequentially, top to bottom. A roadmap written before owner ruling 145
+root, `~/.plastic/stores/{slug}/roadmaps/`, beside `project.yml`; for the global store it is
+`~/.plastic/stores/global/roadmaps/`, beside its `INDEX.md`. Legacy homes keep their
+previous paths until `plastic migrate stores` moves them. `roadmaps/` lists only live (open or
+in-flight) roadmaps: once a roadmap's goal is reached, move it by hand to
+`roadmaps/archived/{slug}.md`. Its ledger and its screens still resolve it there.
+
+A roadmap file from the template has five sections, in order: a title/meta header, `## Goal`,
+`## Graph`, `## Batches`, and an append-only dated `## Log`.
+`## Goal` is a checkable prose condition read by a human or agent, not an executable checker.
+`## Graph` holds the `needs` edges between entries, and the batches are computed from them;
+`plastic roadmap migrate` writes a Graph section for a roadmap that has none, from its current
+batch order. `## Batches` holds ordered batches; entries inside a batch are parallel-safe,
+batches run sequentially, top to bottom. A roadmap written before owner ruling 145
 may instead use the legacy `## Waves` heading; the tooling accepts both, but never renames an
 existing roadmap file to migrate it.
 
@@ -38,7 +43,7 @@ next in under a minute.
 
 **Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
 loop is its runtime. Batches lay out the parallelism plan: what can run together, and in what order.
-Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
+Loop engineering (intent 69) is expected to consume that plan and supply the
 running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
 after a stop. This section only states the relationship and points to intent 69 as the future
 consumer; it does not change intent 69's own design.

package/docs/help/track-1-guided.md

@@ -12,11 +12,15 @@ end to end: a piece of work moved through What, Why, How, and Exec, with a finis
 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
-is never registered as a Plastic project. Pick a throwaway git repository if you have one
-handy, since the worked example edits its README: station 6's deliverable is that file edit.
-No repo handy? Station 6's deliverable becomes a short written note saved in the intent's own
-directory instead (see station 6). Either way, nothing in this track touches a real project.
+This track walks a graph intent: the plan is a `graph.md` of nodes that the runner dispatches.
+For the simpler checklist path, a small Ruby example taken from a new intent to merged code and
+a delivered close, run `plastic help tutorial` instead.
+
+Work in a sandbox. Run `plastic intent new` outside any registered project and the intent lands
+in the global store; run it inside a registered throwaway repository and it lands in that
+project's store, and the close can check the merge. The worked example edits the repository's
+README. With no repository, the deliverable is a short written note saved in the intent's own
+directory (see station 5). Either way, nothing in this track touches a real project.
 
 ## Stations
 
@@ -33,16 +37,15 @@ Checkpoint: open the new file. It already has a real id and a one-line descripti
 was hand-typed into it directly. That is the point: intents are always scaffolded by the
 tool, never written by hand.
 
-### 2. Board the intent
+### 2. Read where it stands
 
-Run `plastic continue` and name the intent.
+Run `plastic intent show ID`.
 
-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
-resumes at the last delivered station and asks nothing.
+Artifact: none. The command only reads. It prints the intent's state screen, and its `next:`
+line names the step to run: `plastic intent spec ID` while the intent has no spec or graph.
+`plastic continue` reads the same way for the whole project. Neither takes a lock.
 
-Checkpoint: explain in one sentence why the lock matters: it stops two
-sessions from editing the same intent at the same time.
+Checkpoint: name the step the `next:` line points at, and why.
 
 ### 3. Why, rulings one at a time
 
@@ -50,17 +53,20 @@ Run `plastic intent spec` (say "grill me" for a harder, interview-style pass ove
 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 spec`
-next, it does not write `spec.md` itself.
+Artifact: each ruling lands as its own `## Insights` entry the moment it is made, never batched
+for later, through `plastic intent rule ID "TEXT"`, stamped with the time, the `Why` stage and
+the `human` author. `intent rule` writes nothing else: the agent edits `## Context` and any
+`### Decisions` list by hand. This station's product is the enriched Why; neither command
+writes `spec.md`.
 
 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.
+is already sitting in `## Insights`, in writing.
 
 ### 4. How, write the graph
 
-Ask the same conversation (`plastic intent spec`) to turn the rulings into the graph.
+In the same conversation, the agent turns the rulings into the graph. It writes `graph.md` from
+`templates/graph.md`. No command creates it; once it exists, the runner behind
+`plastic intent step` and `plastic intent answer` updates it.
 
 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
@@ -70,35 +76,47 @@ Checkpoint: open `graph.md` and point at the one node this worked example needs.
 
 ### 5. Exec, drive the runner loop
 
-Run `plastic intent step`.
+Run `plastic intent step ID`.
+
+Graph execution needs the delivery lock. Without it, `intent step` names
+`plastic auto take ID` as the next step. From a conversation session, `auto take` refuses with
+exit 3 unless the owner approves `--allow-inline`; stop and report the refusal.
 
-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.
+Teach the loop: `plastic intent step ID` runs the internal `runner step`, which computes which
+nodes are ready and prints a spawn block to dispatch. Pass a returned node back with
+`plastic intent step ID --return NODE=PATH`. `plastic intent answer ID --node NODE --decision
+"TEXT"` closes a node that waits on an owner's ruling. The internal
+`ruby ~/.plastic/scripts/runner status <intent_dir>` reads the ledger (running, done, blocked,
+or waiting on a decision); no public command wraps it. 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 every node in
 `graph.md` at a terminal status.
 
 Checkpoint: run `runner status` and confirm no node is left running or blocked, before
-moving to station 6.
+moving to station 6. When the graph is complete, `intent step` names `plastic intent verify ID`.
 
 ### 6. End
 
-Run `plastic intent end`.
+Run `plastic intent end ID --delivered --summary "TEXT"`. Add `--dry-run` first to see what
+the close would do without writing anything.
+
+When the intent has a code branch or worktree, merge the branch yourself first. Plastic does
+not merge, and a delivered close refuses unmerged code with exit 1.
 
-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.
+Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups) generated from
+`graph.md` and the ledger (the same model as the internal `scripts/outcome-report`), the
+intent moved from `## Active` to `## Completed` in `INDEX.md`, the terminal savepoint line,
+and the lock and worktree released.
 
 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, graph, runner step, end. Read
+That is the full cycle once: create, graph, runner step, end. Run `plastic help tutorial` for
+the checklist path with a merged code change. 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/docs/help/track-2-auto.md

@@ -3,7 +3,7 @@
 ## Who it is for and what you will have done
 
 For someone who has seen the stages once (track 1) and now wants to hand the work to the
-agent, watch it move through the gates and reports on its own, and learn how to check in on
+agent, watch it move through the stages and reports on its own, and learn how to check in on
 it and step back in later. After this track, one small intent will have been delivered by the
 agent end to end, and pausing and resuming that delivery will feel familiar.
 
@@ -22,12 +22,26 @@ track touches a real project.
 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.
+Artifact: the delivery lock arms (`delivery.lock` in the intent directory) and the code
+worktree is made at `<repo>/.claude/worktrees/ID--slug` on branch `plastic/ID--slug`. The
+command prints both:
 
-Checkpoint: name the one precondition auto needs before it will start: an active intent must
-already exist for the intent you name. (Say "auto" with nothing named, and it can pick a
-queued intent from the dashboard's queue itself.)
+```text
+intent    2--shout
+lock      acquired by auto-9184f6c4fa, auto mode
+worktree  /home/you/greeter/.claude/worktrees/2--shout
+```
+
+Run from inside a conversation session, `plastic auto take` refuses with exit 3: an intent is
+not delivered inline. The owner may approve an inline take with `--allow-inline`. Otherwise
+the harness spawns the team, and the team takes the intent. Exit 3 means stop and report; never
+retry with another flag on your own.
+
+`plastic auto brief ID` prints the preamble the spawned lead starts from, and
+`plastic auto lock status ID` shows who holds the lock.
+
+Checkpoint: name the one precondition auto needs before it will start: the intent you name
+must already exist in the store the command resolves to.
 
 ### 2. What auto does, and what stays with the user
 
@@ -39,7 +53,7 @@ working copy with the main line before touching anything, ticks each task the mo
 lands rather than batching several into one later edit, and independently verifies its own
 work (running the test suite, or checking the changed file) before presenting anything back
 to you. For a task shaped like an audit or a sweep, checking many files rather than building
-one artifact, it also drops a short methods report into `resources/` before the gate, so you
+one artifact, it also drops a short methods report into `resources/` before the close, so you
 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
@@ -76,13 +90,24 @@ line.
 
 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
-starting over.
+Artifact: where the project stands and a `next:` line naming what runs next. `plastic
+continue` only reads: it takes no lock and changes no file. To resume one intent, run
+`plastic intent show ID`; its Next row names the step it resumes at, read from the files on
+disk.
 
 Checkpoint: after stepping away and running this command, name the stage the intent resumed
 at and how that matched what was actually on disk.
 
+### 6. The close
+
+The lead closes the intent with `plastic intent end ID --delivered --summary "TEXT"`. The
+close checks that the code branch is merged and refuses with exit 1 when it is not; Plastic
+does not merge. It also refuses to deliver an untouched scaffold. On success it writes
+`outcome.md` from the record, moves the intent to `## Completed`, and releases the lock and
+the worktree.
+
+Checkpoint: open `outcome.md` and read its Summary.
+
 ## Wrap and where to go next
 
 Auto keeps the same stages and the same record as thinking; the only difference is who steers.

package/docs/help/track-3-projects-and-roadmaps.md

@@ -20,8 +20,8 @@ one this tutorial keeps or ships.
 
 ### 1. Start from a founding implementation intent
 
-Create and board an intent the same way as track 1, stations 1 and 2: `plastic intent new`,
-then `plastic continue`. Describe something meant to grow into a small real project,
+Create an intent and read where it stands, the same way as track 1, stations 1 and 2:
+`plastic intent new`, then `plastic intent show ID`. Describe something meant to grow into a small real project,
 for example "build a personal todo app."
 
 Then type `plastic intent spec` and record a couple of real rulings on this founding
@@ -66,8 +66,10 @@ and an append-only, dated `## Log`. `INDEX.md` stays the single source of truth
 intent's status; the roadmap only mirrors it. List the two or more intents from station 3
 across one or more batches.
 
-Run `plastic roadmap check <slug>` to confirm the file parses, then `plastic roadmap show
-<slug>` to see it rendered as a report.
+Run `plastic roadmap check <slug>` to confirm the file parses. A roadmap copied from the
+template may have no `## Graph` section yet; `check` then exits 1 and names
+`plastic roadmap migrate <slug>`, which writes the section from the batches. Then run
+`plastic roadmap show <slug>` to see it rendered as a report.
 
 Artifact: a new `roadmaps/<slug>.md` file, sitting next to the project's `INDEX.md`, listing
 the two or more intents from station 3 across one or more batches.
@@ -101,13 +103,14 @@ sections you turned into the condition above.
 No command run here; describe the step instead. Each delivered intent's code merges to main
 as it lands. When the batch (or a meaningful slice of it) is ready to ship, cutting a release
 is a push to `alpha`, `beta`, or `main`: the version files are bumped in that push, and CI
-tags, publishes, and completes the intents it collects.
+tags and publishes. CI never sees your stores, so it closes no intent: each intent is closed
+with `plastic intent end ID --delivered --summary "TEXT"` after its code is merged.
 
 Releases and any npm publish step are described here, not run: this walkthrough stays in a
 sandbox and never touches a real package registry.
 
-Checkpoint: explain why a release completes the intents it collects, rather than an intent
-waiting on a release to exist first.
+Checkpoint: explain why an intent closes when its code is merged, rather than waiting on a
+release to exist first.
 
 ## Wrap and where to go next