@zalom/plastic 2.0.2 → 2.0.3

package/PLASTIC.md

@@ -11,7 +11,8 @@ Every command ends with two lines. The `next:` line names the command to run
 now, and you run it unless the person asks for something else. The `because:`
 line gives the rule that chose it.
 
-Add `--json` to any command to get the same result as data.
+Add `--json` to any command except the installer commands (`install`, `update`,
+`uninstall`, `rollback`) and `plastic hook` to get the same result as data.
 
 Exit codes: 0 succeeded, 1 failed, 2 called wrongly, 3 refused. Exit code 3
 means the step belongs to the owner. Report what was refused and stop. Never

package/README.md

@@ -40,18 +40,20 @@ Plastic keeps the shape of the work fixed and leaves the thinking to you and you
 | You want to | What Plastic does |
 |-------------|-------------------|
 | Start from a rough idea | Creates one intent directory with an id, a slug and a born-complete intent file |
-| Keep the reasons | Records each ruling in the intent, then consolidates them into `spec.md` |
-| Plan the work | Holds the plan as a graph of nodes, and names the next ready step |
+| Keep the reasons | Appends each ruling to the Insights section of the intent file |
+| Plan the work | Holds the plan as a checklist or as a graph of nodes, and names the next step |
 | Resume tomorrow | Prints where a project stands and the next action in one line |
 | Hand work to an agent team | Arms a delivery lock, briefs each role and reports the result |
-| Close the work | Generates `outcome.md` from the record and moves the intent to Completed |
+| Close the work | Checks the merge and the records, fills placeholder records, and moves the intent to Completed or Abandoned |
 | Find an old decision | Searches every store, ranked, with one excerpt for each match |
 | Run many projects | Keeps one store for each project, plus a global store, all in plain Markdown and Git |
 | Steer a long delivery | Reads a roadmap as a graph and names the entry most worth continuing |
-| Protect the record | Writes one archive of the three databases and the config |
+| Protect the record | Writes one archive of the three databases, as of the last `plastic sync`, with `config.yml`, `projects.yml`, and `INDEX.md` |
 
 Every result ends with a `next:` line and a `because:` line. The `--json` option prints the
-same result as data with stable keys.
+same result as data with stable keys. Every command takes it except the installer commands
+(`install`, `update`, `uninstall`, `rollback`) and `plastic hook EVENT`, which runs a hook
+script for the harness.
 
 ## How the record is built
 
@@ -88,9 +90,10 @@ mkdir -p ~/.local/bin
 ln -sf ~/.plastic/bin/plastic ~/.local/bin/plastic
 ```
 
-### Alpha channel
+### Other channels
 
-Plastic 2.0 is on the alpha channel.
+The stable channel carries Plastic 2.0. To install the alpha or beta channel, name it as the
+package version:
 
 ```bash
 npx -y @zalom/plastic@alpha install --claude
@@ -110,9 +113,9 @@ channel is stable; `PLASTIC_CHANNEL` picks another:
 curl -fsSL https://raw.githubusercontent.com/zalom/plastic/main/install.sh | PLASTIC_CHANNEL=alpha sh
 ```
 
-No stable 2.0 release carries the archive yet, so the default channel still installs the 1.x
-line. Use the alpha channel for the `plastic` command, or npm. To move an installed Plastic
-to another channel later, run `plastic update --beta` or `plastic update --alpha`.
+Every release that the publish workflow creates carries the archive, stable ones included. To
+move an installed Plastic to another channel later, run `plastic update --beta` or
+`plastic update --alpha`.
 
 ### A clean Mac
 
@@ -134,9 +137,9 @@ plastic doctor      # Checks the install and the stores
 
 ```bash
 # 1. Install for your agent
-npx -y @zalom/plastic@alpha install --claude    # Claude Code
-npx -y @zalom/plastic@alpha install --codex     # Codex CLI
-npx -y @zalom/plastic@alpha install --all       # Every supported agent
+npx -y @zalom/plastic install --claude    # Claude Code
+npx -y @zalom/plastic install --codex     # Codex CLI
+npx -y @zalom/plastic install --all       # Every supported agent
 
 # 2. See what is open
 plastic status
@@ -154,12 +157,12 @@ Restart your agent after the install. For the full path, read
 ## How it works
 
 ```
-  You or your agent                 plastic                        ~/.plastic
-  -----------------                 -------                        ----------
-  plastic intent new "..."   -->    creates the intent      -->    store/12--slug/12--slug.md
-  plastic intent rule 12     -->    records a ruling        -->    the intent file, then spec.md
-  plastic intent step 12     -->    runs the next node      -->    graph.md, nodes/, savepoint.md
-  plastic intent end 12      -->    generates the outcome   -->    outcome.md, INDEX.md
+  You or your agent              plastic                     ~/.plastic/stores/SLUG/store
+  -----------------              -------                     ----------------------------
+  plastic intent new "..."  -->  creates the intent     -->  12--slug/12--slug.md
+  plastic intent rule 12    -->  records a ruling       -->  Insights in 12--slug/12--slug.md
+  plastic intent step 12    -->  names the next step    -->  checklist.md, or graph.md and nodes/
+  plastic intent end 12     -->  closes the intent      -->  outcome.md, INDEX.md
 
         ^                                                              |
         |            next: one command       because: one reason       |
@@ -193,7 +196,7 @@ plastic intent show 12                # Print the state screen
 plastic intent spec 12                # State screen, then the speccing rules
 plastic intent rule 12 "TEXT"         # Record a ruling in Insights
 plastic intent note 12 "TEXT"         # Append a savepoint note
-plastic intent step 12                # Run the next ready step of the graph
+plastic intent step 12                # Name the next checklist item, or run the next graph step
 plastic intent answer 12 --node n3 --decision "TEXT"   # Answer a node that needs a decision
 plastic intent verify 12              # Run the merge-gate checks
 plastic intent end 12 --delivered --summary "TEXT"     # Close as delivered
@@ -257,7 +260,7 @@ plastic render FILE                   # Print one Markdown file as an HTML page
 ### Product
 ```bash
 plastic install --claude              # Install into Claude Code
-plastic install --reinstall --claude  # Repair an install
+npx -y @zalom/plastic install --reinstall --claude  # Repair an install
 plastic update                        # Next version on the current channel
 plastic update --alpha                # Move to the alpha channel
 plastic rollback                      # List the versions this machine has run
@@ -282,10 +285,10 @@ plastic feedback "TITLE" < report.md  # Save a problem report and print a link t
 ```bash
 --json          # Print the result as data with stable keys
 -h, --help      # Print the usage line of the command
---project SLUG  # On continue, next and search, name a project other than the current one
+--project SLUG  # Name a project other than the one the working directory is in
 ```
 
-The installer commands do not take `--json`. `plastic doctor` does, and prints its full
+The installer commands and `plastic hook EVENT` do not take `--json`. `plastic doctor` does, and prints its full
 report as the document.
 
 ## Examples
@@ -306,15 +309,15 @@ because: the working directory is inside shop
 $ plastic next
 next work  9  in Batch 2: checkout flow
 
-next: read ~/.plastic/projects/shop/store/9--checkout-flow/plan.md
-because: 9 is first on the frontier of the roadmap
+next: plastic intent show 9 --project shop
+because: 9 is the first active intent in shop
 ```
 
 **The installed version:**
 ```
 $ plastic version
-version  2.0.0-alpha.28
-source   ~/.local/share/plastic/package.json
+version  2.0.2
+source   ~/.plastic/VERSION
 
 next: plastic status
 because: the command line works, so read the work next
@@ -331,7 +334,7 @@ loads the conventions and prints the open items of the day. Each hook calls one
 plastic hook EVENT      # The agent calls this, not you
 ```
 
-Run `plastic install --reinstall --claude` when hooks do not fire.
+Run `npx -y @zalom/plastic install --reinstall --claude` when hooks do not fire.
 
 ## Supported AI tools
 
@@ -352,7 +355,6 @@ agents for work, verification and research, and two advisors for hard decisions.
 `~/.plastic/config.yml`:
 
 ```yaml
-project_roots: ~/.plastic/projects   # Where Plastic looks for projects
 stale_threshold_days: 3              # Age at which a future intent is shown for triage
 context_offer_tokens: 150000         # Context size at which the agent offers to compact
 context_insist_tokens: 250000        # Context size at which the agent insists
@@ -361,6 +363,10 @@ agent:
   parallel_mode: agent-teams         # agent-teams or linear
 ```
 
+The installer writes these keys and a few more. It does not write `project_roots`, the list of
+parent folders searched for this session's delivery locks. Without it, Plastic searches
+`~/.plastic/projects` and `~/.plastic/stores`.
+
 Install-time choices:
 
 ```bash
@@ -383,14 +389,15 @@ Your stores under `~/.plastic` stay.
 
 Plastic 2.0 moves from prose skills to one command with direct results.
 
-- **One `plastic` command.** More than 40 commands replace the skills. The package ships no skill directories.
-- **Direct results.** Every command ends with `next:` and `because:`, and takes `--json`.
+- **One `plastic` command.** More than 40 commands replace the former workflow skills, which no longer ship.
+- **Direct results.** Every command ends with `next:` and `because:`. Every command except the
+  installer commands and `plastic hook` takes `--json`.
 - **Plans are graphs.** An intent holds nodes and edges, and a ready set names what runs next.
 - **A ledger with refusals.** Node transitions are appended to `savepoint.md`, and an invalid transition is refused.
-- **Generated outcomes.** `outcome.md` is built from the graph, the nodes and the ledger at the close.
+- **Generated outcomes.** When a graph intent closes with `outcome.md` still a placeholder, the close builds it from the graph, the nodes and the ledger. An `outcome.md` you wrote is kept.
 - **Roadmaps are graphs too.** `plastic roadmap check` finds cycles and dangling ids.
 - **Search without a service.** One SQLite file holds a full-text index of every store.
-- **Three databases.** `work_graph.db`, `knowledge_graph.db` and `references.db` hold the record, and the files are a checkout of it.
+- **Three databases.** The Markdown files stay the record that commands write and read. `plastic sync` reads changed files into `knowledge_graph.db`, writes changed rows back out, refuses when both changed, and rebuilds `work_graph.db` and `references.db`. `plastic checkout` restores missing files from the databases and never overwrites a changed file.
 - **Backup and migrate.** One archive command, and a store move that runs behind a full copy of the home.
 - **Two advisors, medium effort by default.** Summon the Primary Advisor or the Secondary Advisor on purpose.
 - **Codex CLI as a second agent.** The same install, with OpenAI model ids for each role.

package/agents/plastic-enforcer.md

@@ -38,10 +38,11 @@ deliberately; the auto pipeline never dispatches them.
    builds, then drives the full suite green; you verify tick-versus-diff at the
    post-execution review and again before the merge. A mismatch is a review finding, not a
    cleanup you perform silently.
-5. **Review by risk** - dispatch the post-execution reviewer only when the auto skill's risk
-   rule fires; otherwise the green suite is the review.
-6. **Close** - `outcome.md`, then `plastic intent end`, which releases the worktree, clears
-   the lock, points the session back at the day ledger, and reindexes last.
+5. **Review by risk** - dispatch the post-execution reviewer only when a review rule that
+   `plastic auto report ID` prints fires; otherwise the green suite is the review.
+6. **Close** - merge the code branch first (Plastic never merges; a delivered close refuses
+   unmerged code), then `outcome.md`, then `plastic intent end ID --delivered --summary
+   "TEXT"`, which releases the worktree and clears the lock. It does not reindex QMD.
 
 **Dispatch-time model contract.** Each pinned agent carries its `model:` in frontmatter, and
 Claude Code reads it at dispatch. Because read-at-dispatch is a harness implementation detail
@@ -55,8 +56,9 @@ dispatch call's model parameter, alongside the spawn-preamble live-state injecti
 1. Take the intent; record the rulings in `## Context` + `### Decisions`; write `spec.md`.
 2. Write `plan.md`, the action files with their matrix, and `checklist.md`; dispatch the plan
    reviewer; merge the review findings.
-3. Dispatch the executor through `plastic intent step` with the whole consolidated action
-   pasted in; require the red commit before the code and a green suite after it. Sequential,
+3. Dispatch the executor through your harness's agent dispatch with the whole consolidated
+   action pasted in (on a graph intent, `plastic intent step ID` prints the spawn block; on a
+   checklist intent it prints the next item and dispatches nothing); require the red commit before the code and a green suite after it. Sequential,
    one team per intent, on one branch when files are shared.
 4. Apply the risk rule; when it fires, dispatch the reviewer and re-dispatch the executor for
    the fixes.
@@ -73,10 +75,10 @@ you consume that report to write the human briefing, and the two never merge.
 
 ## Constraints
 
-- Nothing blocks a write in 2.0: the lock, the worktree, and the record are how the team keeps
-  one delivery in one place, not fences. Verify state from the files (`plastic-lock status`,
+- No hook blocks a write based on lock ownership or stage in 2.0: the lock, the worktree, and the record are how the team keeps
+  one delivery in one place, not fences. Verify state from the files (`plastic auto lock status ID`,
   `savepoint.md`, the diff), never from a hook you assume fired.
 - The plan reviewer and the post-execution reviewer are fresh agents, never you and never the
   executor.
-- Dispatch through `plastic intent step`, Plastic's own engine. On a harness with no agent
-  dispatch, walk the five steps yourself and say so in `## Insights`.
+- On a graph intent, dispatch through `plastic intent step`, Plastic's own engine. On a harness
+  with no agent dispatch, walk the five steps yourself and say so in `## Insights`.

package/agents/plastic-executor.md

@@ -24,7 +24,8 @@ valid lifecycle artifacts. Honor it as your live state; do not re-derive or cont
 3. **Tick with the commit** - commit after each logical unit of work, and in the same step
    tick the checklist item that unit lands: mark its box `[x]` and move the line to
    `## Completed`, then append the savepoint `Commit` line
-   (`scripts/savepoint-note <intent_dir> --kind Commit --text "<sha> <what it proves>"`). A
+   (`scripts/savepoint-note <intent_dir> --kind Commit --text "<sha> <what it proves>"`, or its
+   public wrapper `plastic intent note ID "<sha> <what it proves>" --kind Commit`). A
    commit without its tick is incomplete.
 4. **Record insights** - capture durable discoveries and report them in the `insights:` field;
    persist each to `## Insights` via the `insight-append` helper

package/agents/plastic-primary-advisor.md

@@ -51,5 +51,5 @@ winner before answering; spend care where reversal is expensive; always end with
 kill criteria, the observation that means the caller should abandon this plan and
 return. No shape stated: answer as one bounded decision and say so.
 
-Plain language, no em-dashes. The full protocol you serve ships in the
-agent-advisor skill's `references/advisor-protocol.md`.
+Plain language, no em-dashes. The full protocol you serve is the help chapter
+that `plastic help advisor-protocol` prints.

package/agents/plastic-secondary-advisor.md

@@ -53,8 +53,8 @@ winner before answering; spend care where reversal is expensive; always end with
 kill criteria, the observation that means the caller should abandon this plan and
 return. No shape stated: answer as one bounded decision and say so.
 
-Plain language, no em-dashes. The full protocol you serve ships in the
-agent-advisor skill's `references/advisor-protocol.md`.
+Plain language, no em-dashes. The full protocol you serve is the help chapter
+that `plastic help advisor-protocol` prints.
 
 ---
 

package/docs/help/agent-architecture.md

@@ -28,10 +28,11 @@ 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 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.
+- **the plan reviewer**: a fresh agent on the prompt that `plastic help plan-reviewer-prompt`
+  prints, an optional dispatch before any code exists.
+- **the post-execution reviewer**: a fresh agent on the prompt that
+  `plastic help code-quality-reviewer-prompt` prints, dispatched only when a review rule from
+  `plastic auto report ID` fires; never the maker.
 
 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
@@ -99,21 +100,21 @@ worktree, and the record are how the team keeps one delivery in one place.
 ### The risk list
 
 The post-execution reviewer runs when the executor's diff touches any of these paths, or when
-the auto skill's other two risk clauses fire:
+one of the other two review rules that `plastic auto report ID` prints fires:
 
 - `hooks/`, `scripts/hook-*`, `scripts/lib/hook_registry.rb`
 - `scripts/lib/lock.rb`, `scripts/lib/arm.rb`, `scripts/plastic-lock`, `scripts/end-intent`
 - `scripts/lib/installer_core.rb`, `scripts/install*`, `scripts/update.rb`
 - `package.json`, `.claude-plugin/*.json`, `CHANGELOG.md`
 
-Grow this list here, not in the skill body.
+Grow this list here and in the `REVIEW_RULES` text of `plastic auto report`.
 
 ### Headless Note
 
 In a headless or background run the session id may be unset. `plastic-lock arm` then keys the
 lock by a derived session key, the record hook still writes the savepoint ledger from the
-written path, and the lead verifies state from the files (`plastic-lock status`,
-`savepoint.md`, the diff) rather than from a hook it assumes fired.
+written path, and the lead verifies state from the files (`plastic auto lock status ID`,
+which wraps `plastic-lock status`, `savepoint.md`, the diff) rather than from a hook it assumes fired.
 
 ### Delegation
 

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

@@ -47,15 +47,17 @@ Every role report, whatever the stage, carries these fields:
 
 ## Per-role payload
 
-Multi-item payload fields (ordered actions, insights, checklist deltas) default to tables per
-`PLASTIC.md` (## Tabular-First Reporting, intent 160); single fields stay prose.
+Multi-item payload fields (ordered actions, insights, checklist deltas) default to tables;
+single fields stay prose.
 
 Each role appends a payload that fulfils its place in the What, Why, How, Exec cycle (decision
 D2). The payload is what makes the report useful to the orchestrator beyond the envelope.
 
 The stage-agent role sections (brainstorming, spec-specialist, planner) were removed in 2.0
 (intent 304): the orchestrator writes the Why and How artifacts itself and reports nothing to
-itself. Two dispatched roles remain.
+itself. The lead dispatches three roles: the plan reviewer, the executor, and the
+post-execution reviewer. The plan reviewer returns the shape in `plastic help
+plan-reviewer-prompt`; the other two carry the payloads below.
 
 ### executor (Exec)
 - Actions implemented this turn, mapped to checklist items checked off (checked / total).
@@ -64,7 +66,7 @@ itself. Two dispatched roles remain.
 - Insights reported in the `insights:` field (each with the `(autonomous)` marker); the
   executor or the orchestrator persists them to `## Insights` via the `insight-append` helper.
 
-### final reviewer (final gate)
+### post-execution reviewer
 - Verdict: `pass` or `blockers found`.
 - Each acceptance criterion checked, with the evidence that confirms or refutes it.
 - Gaps or risks found, ranked, with a recommended disposition.

package/docs/help/completion-and-done.md

@@ -18,21 +18,26 @@ header. The delivered path authors it with the result; the abandoned path author
 the abandonment reason and no longer leaves the scaffolded placeholder sentinel in place.
 
 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.
+savepoint line -> commit -> disarm (Worktree.release -> Lock.release)`. `plastic intent end`
+runs all of it through `scripts/end-intent`. The close does not reindex QMD: no public close
+path calls `qmd-sync`, so the QMD index catches up only when you run `qmd-sync` yourself.
 
 `scripts/end-intent` never merges code. Before a delivered close writes anything, it checks
 that the intent's code is already merged into the current branch of the repo checkout. It
 checks the commit the code worktree is on, even when that worktree is on a renamed branch or
 a detached HEAD, and it checks the code branch after the worktree is gone. The repo checkout
 must be on the branch you release from, not detached and not on the code branch. If the code
-isn't merged, or Git can't tell, the close exits 9 and changes nothing: INDEX, the savepoint, the
-lock, and the worktree all stay as they were. `--dry-run` refuses the same way. The refusal
+isn't merged, or Git can't tell, the script exits 9 and changes nothing: INDEX, the savepoint, the
+lock, and the worktree all stay as they were. `plastic intent end` reports that refusal as exit 1
+with a named message. `--dry-run` refuses the same way. The refusal
 names the merge to run, for example `git -C <repo> merge plastic/<id>--<slug>`. Run that
 ordinary merge, or release the work through your usual process, and then run the close
 again. An abandoned close and an intent with no code repository skip this check.
 
+A delivered close also refuses, as exit 1, an untouched scaffold (script exit 8) and a hollow
+report whose `## Delivered` rows do not match the action files (script exit 7). A live foreign
+lock is script exit 4, which `plastic intent end` reports as exit 3.
+
 `scripts/end-intent` performs this order's disarm step (verify the code worktree is clean,
 then remove the worktree, then clear the lock) as its own step 5, mechanically, since
 intent 188: a session no longer needs a separate one-liner for it, and the script's own

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

@@ -25,29 +25,31 @@ written by eye:
   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.
+  intent. It is not a delivery trigger. When a prompt is the single word `continue`, the
+  capture hook runs `dashboard.rb continue` and adds its board to the agent's context; the
+  `plastic continue` command prints its own rows and no screen.
 
 ## 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.
+and trigger. The commands run their verb themselves; the lead and the agent run theirs. 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` |
+| `plastic intent show` | any invocation | `report-screen state` |
+| `plastic intent spec` | any invocation | `report-screen state`, then the speccing rules |
+| `plastic roadmap show` | any invocation | `report-screen roadmap ... state` |
+| `plastic status` | any invocation | in-process (`Scope#stores`) |
+| `plastic continue` | any invocation | in-process rows: project, root, active, roadmap |
 | 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` |
+| the agent | "where are we" (an unnamed status ask) | `report-screen session` |
+| the agent | "why so long" | `report-screen delay` |
+
+`plastic intent end` and `plastic intent step` print no screen of their own.
 
 ## A roadmap's own three reports (intent 331c)
 
@@ -87,8 +89,8 @@ 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.
+painted rendering of that same output, never a different one, and no script branches on
+harness name to decide.
 
 ## Depth for small work
 
@@ -101,15 +103,16 @@ 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
+from `graph.md`, `nodes/`, and the ledger when the intent has one, intent 339; written by the
+agent before the close otherwise, and backfilled from the record by `plastic intent end` when
+it is still missing or a placeholder) and one `delivered` screen at the End stage. No stage
+restates a delivery already written to `outcome.md`; point at it instead. A reply does not
+open with a banner that 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,
+Intent 74's report contract (`plastic help agent-report-contract`) 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

package/docs/help/knowledge-graph.md

@@ -1,6 +1,6 @@
 # Knowledge Graph
 
-This chapter holds the linking doctrine from Frontmatter and the branch-vs-root directory semantics from Directory Naming.
+This chapter holds the linking rules for an intent's frontmatter and the branch-versus-root rule for intent ids.
 
 - `sources` (formative, must-load, acyclic) and `chain` (forward + relational, lighter,
   may cycle) form the directed knowledge graph. Reciprocity is one-directional: every
@@ -18,7 +18,7 @@ This chapter holds the linking doctrine from Frontmatter and the branch-vs-root
   It equals the projection of `sources` (first) then `chain`. Never hand-write or hand-edit a
   `## Links` line, and never auto-delete one. The edge lives in the frontmatter graph; the
   section is regenerated from it (doctor `graph_links_projection` enforces this identity). To
-  add a link, add the frontmatter edge, then reproject.
+  add a link, add the frontmatter edge, then run `plastic project links` to reproject.
 
 - Links are decided by CONTEXT INFLUENCE, not by shared files, shared symbols, or a topic
   similarity score. The question is whether one intent's context actually informed another.

package/docs/help/lifecycle-and-savepoints.md

@@ -16,8 +16,10 @@ happened:
 - the commits on the intent's branch.
 
 The four judgment documents (spec.md, plan.md, actions/, outcome.md) are written when
-there is something to say. In thinking mode an agent writes them during Why and How. In
-direct mode they usually stay as the scaffold placeholder until the close, and
+there is something to say. In thinking mode an agent writes them during Why and How; the
+`plastic intent` Next row asks for `spec.md`, then `plan.md` and `checklist.md`, before it
+points at execution. In direct mode they usually stay as the scaffold placeholder until the
+close, and
 `scripts/end-intent` then backfills each one still missing or still a placeholder from
 the live record (intent 308): `## Problem` from `## Intent`, `## Decisions` from
 `### Decisions`, `## Acceptance Criteria`, `## Steps`, `## Items`, `## Delivered`, and
@@ -32,7 +34,7 @@ for the doctor fix hint `backfilled_complete`.
 The close never refuses for a document it can write itself. Doctor's per-intent structure
 check runs after the backfill as a report: an unchecked box, a malformed intent file, or
 a wrong-disposition outcome.md is named on stderr, the close proceeds, and
-`/plastic-doctor --intent <id>` keeps reporting it until fixed.
+`plastic intent verify <id>` keeps reporting it until fixed.
 
 ## Insights from a writer that cannot write the file
 
@@ -41,5 +43,7 @@ each nugget home in the completion report's `insights:` field, and the orchestra
 agent that can write the file) persists it via the helper. A session that cannot write the
 intent file still returns its report, so the insight survives.
 
-For the stage table (What/Why/How/Exec, deliverable, owning skill), see PLASTIC.md's Lifecycle
-Stages section; each named skill's own `references/` holds that stage's own depth.
+The stages map to commands: What is `plastic intent new`, Why is `plastic intent spec` and
+`plastic intent rule`, How is the spec, plan and checklist (or `graph.md`) the agent writes,
+and Exec is `plastic intent step`, `plastic intent verify` and `plastic intent end`.
+`plastic help tutorial` walks all of them once.

package/docs/help/locks-and-worktrees.md

@@ -31,7 +31,8 @@ delivery, delegate registration authorizes a child session, and a claim selects
 writer for one artifact. Disarm clears the lock; the End tail is ordered: verify, merge and
 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
+fix, release, reclaim, delegate) and the public `plastic auto lock status|fix|release ID`
+commands that wrap it, so repair
 self-heals. `who` is read-only and reports the controller, mtime heartbeat, delegates, and
 claims from durable files. This is mandatory for auto teams, not a convention.
 
@@ -94,12 +95,12 @@ what gets written down.
 
 | 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 | savepoint confirms the boarding station |
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm (`plastic auto take ID`, the only public entry) 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`, 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 |
+| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify the code is merged (Plastic never merges it), remove the worktree, disarm clears `delivery.lock`; no QMD reindex runs; `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/docs/help/maintenance-and-revisions.md

@@ -87,7 +87,7 @@ relocation holds itself to the identical rule.
 
 Doctor stays a detector: core and full checks, every installed agent, both global and project
 stores. It gains no write path of its own. The "Fix all" prompt
-(`skills/doctor/SKILL.md`) is a ROUTER: for each fixable finding it dispatches to the tool
+(the retired `skills/doctor/SKILL.md`; in 2.0 each `plastic doctor` finding names its own repair) is a ROUTER: for each fixable finding it dispatches to the tool
 that already owns that class of repair (`project-links`, `rebuild-graph`,
 `restore-intent-v1`, or the curator, via `scripts/maintenance-run` where applicable), and
 those tools perform the mutation and write the `revisions.md` receipt - never doctor itself.
@@ -176,7 +176,7 @@ meant to catch).
 (intent 274) is the one narrow exception to the "every maintenance action is recorded in
 `revisions.md`" rule above. It populates each store's `doctor-exclusions` file (the per-store
 record of knowingly-exempt `(intent_id, rule)` pairs `doctor`'s `savepoint_operational` check
-honors - see `skills/doctor/SKILL.md`) by computing violations through
+honors) by computing violations through
 `Doctor#done_signal_findings_for_dir` directly, the same function `check_done_signals` itself
 calls, so the registry can never disagree with the checker about what counts as a violation.
 

package/docs/help/roadmaps.md

@@ -7,20 +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/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, 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
+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.
 
@@ -39,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.