@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/skills/intent-ending/SKILL.md

@@ -51,21 +51,39 @@ on disk is what the record becomes, so before the call:
    reported gap that lands verbatim in the backfilled `## Follow-ups`.
 2. Confirm every acceptance criterion in spec.md is verifiable (tests pass,
    or the manual check described in its HOW line was actually run).
-3. Decide what you have to say. A spec.md, plan.md, action file, or outcome.md
-   left as the scaffold placeholder is written from the record by
-   `scripts/end-intent` (the intent file's `## Intent`, `### Decisions`, and
-   `## Insights`, the checklist, the diff on the intent's own worktree). A
-   file you wrote, even under a still-present sentinel, is never touched.
-   Write outcome.md yourself when the summary deserves more than the
-   `--outcome-summary` line; otherwise let the backfill carry it.
+3. Decide what you have to say. For an intent with a `graph.md`, `outcome.md` is
+   GENERATED by `scripts/end-intent` itself, through `scripts/lib/outcome_report.rb`
+   (`scripts/outcome-report` is its standalone CLI, useful for checking the
+   generated text before the close): `## Delivered`, `## Verification`,
+   `## Graph diff`, and `## Findings` are read straight from `graph.md`, `nodes/`,
+   and the ledger every time, never hand-typed. `## Summary`, `## Needs you`, and
+   `## Follow-ups`, and every frontmatter key but `disposition`, are preserved
+   byte for byte when you author them and generated as plain facts otherwise, so
+   writing a summary yourself still works exactly as before. For an intent with
+   no `graph.md`, or when the generated text would be refused by the close's own
+   gates, a spec.md, plan.md, action file, or outcome.md left as the scaffold
+   placeholder is written from the record by `scripts/end-intent` (the intent
+   file's `## Intent`, `### Decisions`, and `## Insights`, the checklist, the
+   diff on the intent's own worktree). A file you wrote, even under a
+   still-present sentinel, is never touched.
 
 ### Step 1-5. Run `scripts/end-intent`
 
-Author outcome.md yourself when it deserves prose: copy `templates/outcome.md`,
-set the frontmatter to `disposition: delivered` or `disposition: abandoned`, and
-fill `## Summary`, `## Delivered`, `## Verification`, `## Follow-ups`. On
-abandon, `## Summary` states the abandonment reason and the trail (see Pivot
-below). A placeholder outcome.md is backfilled from the record instead, with the
+Author outcome.md yourself when the summary deserves more prose than the generator's
+plain facts: copy `templates/outcome.md`, set the frontmatter to `disposition: delivered`
+or `disposition: abandoned`, and fill `## Summary`, `## Delivered`, `## Verification`,
+`## Follow-ups`. `## Delivered` is a `| Row | What |` table: one row per thing delivered,
+in plain wording a reader recognizes, not a method name or an implementation summary
+(that detail belongs in `## Summary`). Each row's label must appear as a standalone token
+in an action-file heading (or a node-file heading, for an intent whose graph replaces
+actions/ with nodes/) that owns the matrix table (`### S1 - ...` or
+`## n1 failure-mode matrix` with a table beneath it proves that row; a table-less
+heading naming the label is skipped); that heading's matrix rows become the row's
+Proven-by cell on `report-screen delivered`'s post-delivery screen. `## Needs you` is
+the literal None or a `| N | What | Why |` table. On abandon, `## Summary` states the
+abandonment reason and the trail (see Pivot below). An intent with a `graph.md` and no
+hand-written outcome.md gets one generated instead (Step 0.3 above); a placeholder
+outcome.md on an intent with no `graph.md` is backfilled from the record, with the
 close's disposition and the `--outcome-summary` line as its summary. Also author
 the rich INDEX entry note now (a short line in the store's existing
 Completed/Abandoned convention: mode, what shipped or why it was
@@ -138,11 +156,13 @@ ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
 No-op when QMD is absent. Runs in the background so it never blocks the
 turn.
 
-### Step 7. EM-to-CTO report
+### Step 7. Print `delivered`
 
-Brief the human like an engineering manager to a CTO: impact and risk first,
-in plain language, the decision left to them (merge, release, or accept).
-See `outcome.md` for the details; do not restate it verbatim.
+Print `ruby ~/.plastic/scripts/report-screen delivered <intent_dir>` as the first characters
+of the reply: nothing before it, no fence, or the hook cannot paint it. Asked, Delivered (with
+its Proven-by column), Evidence, and Needs you come straight from the record - the EM-to-CTO
+report, impact and risk first, in plain language, with the decision left to the human (merge,
+release, or accept). See `outcome.md` for the details; do not restate it verbatim.
 
 ## Abandoned is the same procedure
 

package/skills/intent-executing/SKILL.md

@@ -61,6 +61,10 @@ Run Step 0 (Sync Worktree First) before this step.
 
 Dispatch ONE executor subagent and give it the whole delivery: every task's full text from `plan.md` (pasted in, never a file reference), every action file with its failure-mode matrix, the checklist items it must tick, the project context from CLAUDE.md, the active intent context from `{ID}--{slug}.md`, and the worktree path. In auto mode this is the `plastic-executor` agent; elsewhere use the `implementer-prompt.md` template. The executor writes the matrix's tests and commits them red, implements the consolidated action in order, ticks each item as it lands (see `## Tick-as-you-land`), and drives the test suite green.
 
+After each commit lands (the red commit and every commit after it), append a `Commit` line to the savepoint ledger: `ruby ~/.plastic/scripts/savepoint-note <intent_dir> --kind Commit --text "<sha> <what it proves>"` (intent 317, D17). This is what feeds `report-screen delay`; a commit with no line is a gap the delay report cannot explain.
+
+Print `ruby ~/.plastic/scripts/report-screen state <intent_dir> --changed "<what just landed>"` as the first characters of the reply, nothing before it, no fence, right after the red commit and again once the suite goes green (intent 331f).
+
 Read its response by code:
 - DONE or DONE_WITH_CONCERNS → proceed to Step 3.
 - NEEDS_CONTEXT → provide the missing context, re-dispatch the executor.
@@ -69,6 +73,10 @@ Read its response by code:
 ### Step 3: Review by Risk
 Apply the auto skill's risk rule to the executor's return and the diff: a matrix row no test could prove, a diff touching a hook, the lock, the worktree code, the installer, or a release file, a DONE_WITH_CONCERNS or a deviation from the matrix, or an owner-facing surface no test pins. When a rule fires, dispatch the post-execution reviewer with `code-quality-reviewer-prompt.md` (a separate agent with fresh context, never the maker); if it returns changes, re-dispatch the executor to fix them, then run the suite once more. When no rule fires, the green suite is the review.
 
+Whenever a review verdict returns - the plan review before code, or the post-execution review above - the lead appends a `Review` line: `ruby ~/.plastic/scripts/savepoint-note <intent_dir> --kind Review --text "<verdict, what changed>"` (intent 317, D17). This is the other half of what `report-screen delay` reads.
+
+**The D19 heading convention.** An action file's `## Delivered` row (in `outcome.md`) is proven by the first `actions/ACTION_N.md` OR `nodes/*.md` heading that carries that row's label as a standalone token AND owns the matrix table (322 D1r, 334 D10r) - `### Row A -` with a table beneath it proves row A, `### S1 -` proves row S1, `## n1 failure-mode matrix` proves row n1; a heading that only names the label, with no table under it, is skipped. Readers check `actions/` first, then `nodes/` (334 D15r). Write action-file or node-file section headings so the label they prove is unambiguous (never a substring another label could also match, like `A` inside `AB`); `report-screen delivered`'s Proven-by column renders `not recorded` when no heading owns a matching table and no matrix row cell carries the label either.
+
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
@@ -102,11 +110,15 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 
 ## Tick-as-you-land
 
-As each task lands, in the same edit: move its checklist item from `## In
-Progress` to `## Completed` in `checklist.md`, and add one `## Session Log`
-row (Date, Items Completed, Notes). Do not batch several tasks' worth of
-checklist updates into one later edit; tick the moment the task is verified,
-before moving to the next task.
+A tick is two edits, made together: mark the item's box `[x]`, and move its
+checklist item from `## In Progress` to `## Completed` in `checklist.md`;
+then add one `## Session Log` row (Date, Items Completed, Notes). The box is
+the half the state screen's Progress bar reads: `IntentScreen::ITEM_RE` and
+`progress_fields` count `[x]`, not which section the line sits in, so a line
+moved to `## Completed` with its box left unmarked still reads as zero
+progress. Do not batch several tasks' worth of checklist updates into one
+later edit; tick the moment the task is verified, before moving to the next
+task.
 
 ## Verify before every owner review
 

package/skills/intent-executing/implementer-prompt.md

@@ -20,12 +20,17 @@ You are implementing a specific task from a plan. You have been given the full t
 2. Implement exactly what the task specifies — nothing more, nothing less.
 3. Write tests first when the task includes test steps (TDD).
 4. Follow the file paths specified in the task exactly.
-5. Commit after each logical unit of work.
+5. 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
+   commit without its tick is incomplete.
 6. When done, self-review against this checklist:
    - [ ] All steps in the task are completed
    - [ ] Tests pass
    - [ ] Code is clean and follows project conventions
    - [ ] No unrelated changes
+   - [ ] Every landed unit's checklist item is ticked
 
 ## Report Format
 

package/skills/intent-speccing/SKILL.md

@@ -111,10 +111,13 @@ When the rulings are enough to build from:
    rulings say more than the record already does.
 3. **Self-verify.** Read `references/self-verify-checklist.md` before presenting; fix any
    failing check and re-verify from the top.
-4. **Present and hand off.** Present `spec.md` and the action files. Then offer the routes:
-   run it now inline when the work is small enough for direct mode; hand to `plastic-auto`
-   when the owner says auto and the checklist above passes (all decisions resolved, scope
-   bounded, dependencies named, success criteria defined); or keep thinking.
+4. **Present and hand off.** Print `ruby ~/.plastic/scripts/report-screen plan <intent_dir>` as
+   the first characters of the reply: nothing before it, no fence, or the hook cannot paint it.
+   It carries Asked, Decisions, Steps, Mode, Reviewer, then the Steps and Risks tables, filled
+   from `spec.md` and the action files just written, never restated by eye. Then offer the
+   routes: run it now inline when the work is small enough for direct mode; hand to
+   `plastic-auto` when the owner says auto and the checklist above passes (all decisions
+   resolved, scope bounded, dependencies named, success criteria defined); or keep thinking.
 
 Report, in this order: which files were written (`spec.md` new or rewritten, the action
 files), the count of acceptance criteria, which `## Insights` rulings superseded an earlier

package/skills/releasing/SKILL.md

@@ -206,6 +206,45 @@ The dist-tag is derived from the version string in `package.json`:
 - Contains `-beta` → `--tag beta`
 - No pre-release suffix → no `--tag` flag (publishes to `latest`)
 
+#### `npm_publish_workflow`
+
+The tag pushed in step 6 starts the project's publish workflow (GitHub Actions, keyed on the
+workflow file `publish.yml`) instead of a local `npm publish`. The workflow runs with a
+short-lived, per-run OIDC credential, so no npm token exists in this session or on this
+machine.
+
+1. **Confirm a run exists for the tag.** A tag cut from a ref that does not carry the
+   workflow starts no run at all, and silence would read as success:
+
+   ```bash
+   gh run list --workflow publish.yml --limit 5
+   ```
+
+2. **Follow the run.**
+
+   ```bash
+   gh run watch <run-id>
+   ```
+
+3. **Verify the registry, not just the run.** The release is not done until the new version
+   shows up on the expected channel:
+
+   ```bash
+   npm view <package> dist-tags
+   ```
+
+The dist-tag is derived from the version string in `package.json`, the same rule
+`ReleaseGuard.dist_tag` implements:
+
+| Version contains | dist-tag |
+| --- | --- |
+| `-alpha` | `alpha` |
+| `-beta` | `beta` |
+| no pre-release suffix | `latest` |
+
+Do not run `npm whoami` on this path. npm documents that `whoami` does not reflect OIDC
+authentication, so on a workflow-published project it can only mislead.
+
 #### Other values
 
 If `on_green` contains an action not listed above, log it:

package/skills/releasing/references/promotion-and-tagging.md

@@ -34,18 +34,22 @@ cleared is a no-op.
 ## Promotion
 
 Promotion is not a CLI flag; there is no `--promote` command. It is a set of steps the
-agent performs during the releasing workflow, reusing the normal release mechanics
-(version bump, tag, `npm publish` with the channel's dist-tag, GitHub release):
+agent performs during the releasing workflow, reusing the normal release mechanics (version
+bump, tag, GitHub release). For a project on the `npm_publish_workflow` post-push action,
+the tag push itself starts the publish; there is no local publish command to run.
 
 ```bash
-# Promote alpha → beta: set version files from -alpha.N to -beta.1, commit, tag, then
-npm publish --access public --tag beta
+# Promote alpha → beta: set version files from -alpha.N to -beta.1, commit, tag, push.
+# The publish workflow reads the new version and publishes to the beta dist-tag.
 
 # Promote beta → stable: strip the pre-release suffix (e.g., 1.0.0-beta.3 → 1.0.0),
-# commit, tag, then
-npm publish --access public          # no --tag flag publishes to latest
+# commit, tag, push. The publish workflow reads the new version and publishes to latest.
 ```
 
+A project still on the `npm_publish` action (publishing locally from the session) runs
+`npm publish --access public --tag <channel>` at this point instead, per that action's own
+section in SKILL.md.
+
 **Promotion rules:**
 - Linear only: alpha → beta → stable. Cannot skip channels.
 - Version files are bumped and committed as in a normal release.

package/skills/releasing/references/release-lines.md

@@ -78,7 +78,7 @@ re-deriving this decision.
 of 1.1.0, versioned `1.2.0-beta.1` (`c48601a`). There is nothing left to execute on the git side;
 this playbook describes what happens next, not a pending action.
 
-**Preconditions**, both required before any npm publish of `1.2.0-beta.1`:
+**Preconditions**, both required before any publish of `1.2.0-beta.1`:
 
 - (a) One documentation pass over beta-line skills and docs for the hybrid savepoint contract:
   on beta, only the terminal Done bookend still writes a live `savepoint.md`; every other

package/skills/roadmap/SKILL.md

@@ -43,10 +43,36 @@ See `references/file-format.md` for the exact entry-line shape, status vocabular
 format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
 verb above.
 
+## Graph (intent 337)
+
+A roadmap may carry an optional `## Graph` section - the same `needs` edge grammar as an
+intent's own `graph.md` (`- <id> needs <id> <id>`, or `- <id> needs nothing` for a root). When
+present, batches are computed from it (`roadmap-graph check`/`render`), not hand-ordered; the
+template scaffolds a fenced example so a new roadmap starts with the section already in place.
+Three verbs, all `--dry-run`-able:
+
+| Verb | What it does |
+|------|--------------|
+| `roadmap-graph check <roadmap.md>` | Prints the computed batches, the ready set, and any dangling id (a graph names it, no batch lists it); exits 1 on a cyclic graph or a dangling id. |
+| `roadmap-graph render <roadmap.md>` | Writes `## Tree` (a box-drawing render of the graph) and regroups the batch/wave section from the computed batches, entry lines carried over verbatim. |
+| `roadmap-graph migrate <roadmap.md>` | Derives a conservative `## Graph` for a graphless roadmap from its existing batch order (batch N needs every entry of batch N-1); never overwrites an existing graph. |
+
+A roadmap with no `## Graph` section keeps working exactly as before (wave-order dispatch); the
+graph is additive, never required.
+
 Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
 semantics, and the status-mirror rule that this skill's own file-format reference builds on. This
 path resolves relative to this skill's own installed directory.
 
+## Reports (intent 331f)
+
+Each verb prints its report screen as the first characters of the reply: nothing before it, no
+fence, or the hook cannot paint it.
+
+- Create prints `ruby ~/.plastic/scripts/report-screen roadmap <roadmap.md> plan`.
+- Read / consume prints `ruby ~/.plastic/scripts/report-screen roadmap <roadmap.md> state`.
+- Close / archive prints `ruby ~/.plastic/scripts/report-screen roadmap <roadmap.md> delivered`.
+
 ## Notes
 
 - File location and the four-section shape are identical across tiers; do not invent a different

package/skills/roadmap/references/file-format.md

@@ -96,6 +96,16 @@ The ledger is derived and rebuildable (`ruby ~/.plastic/scripts/roadmap-savepoin
 roadmaps/{slug}.md`, reconstructing it from `## Log`), never a status source: `INDEX.md` stays the
 single writer of intent status, exactly as for the roadmap file itself.
 
+## Screens read this format (intent 331c)
+
+`report-screen roadmap <roadmap.md> plan|state|delivered` reads exactly the shapes above and
+nothing else: `## Goal`'s first sentence, the `## Batches` (or legacy `## Waves`) grouping and its
+entries (through `RoadmapQueue`'s own reconciled reader - INDEX still wins), and the events from
+the savepoint ledger, falling back to `## Log` classified through the same keyword vocabulary when
+no ledger file exists (an archived roadmap moved before intent 134 shipped, `manual-first.md`
+among them). A screen never invents a status, a time, or a merge sha the file, `INDEX.md`, or the
+ledger did not already carry - the same `not recorded` floor the intent screens use.
+
 ## Worked example
 
 ```

package/templates/dashboard-screen.md

@@ -0,0 +1,22 @@
+## ▶ {{scope}} · dashboard
+
+| | | |
+| --- | --- | --- |
+| **Active**      | {{active}} | intents |
+| **In delivery** | {{in_delivery}} | with a fresh lock |
+| **Delivered**   | {{delivered}} | in the last 7 days |
+| **Roadmap**     | {{roadmap}} | frontier batch |
+| **Sessions**    | {{sessions}} | alive |
+| **Changed**     | {{changed}} | newest savepoint |
+
+**Where we are**
+
+| Graph ID | Intent | Stage | Progress | Lead |
+| --- | --- | --- | --- | --- |
+{{where_we_are.rows}}
+
+**Where we go next**
+
+| Rank | Graph ID | Intent | Reason |
+| --- | --- | --- | --- |
+{{where_we_go_next.rows}}

package/templates/display-fixture.md

@@ -0,0 +1,21 @@
+<!-- Doctor's display self-test fixture (intent 331e). Replayed through the
+     installed MessageDisplay hook by `display_hook_paints` to prove painting
+     still works; this is NOT a report-screen scaffold (no {{...}} mustache
+     placeholders) and ships no data of its own. -->
+
+## ▶ 331e · Doctor display check
+
+| | | |
+| --- | --- | --- |
+| **Store**     | project:plastic                | the plastic project store |
+| **Status**    | Active                          | listed under ## Active in INDEX.md |
+| **Stage**     | Exec                            | What, Why, How, Exec delivered; the work is open |
+| **Progress**  | ██████████░░░░░░░░░░ 3 / 6      | 3 steps open |
+
+**Steps**
+
+| Step | Status | What |
+| --- | --- | --- |
+| S1 | done | Tests red |
+| S2 | done | check_display_registration in doctor_core.rb |
+| S3 | open | The three full-run checks in doctor.rb |

package/templates/graph.md

@@ -0,0 +1,16 @@
+# Graph: <intent name>
+
+## Goal
+<What this intent's graph delivers once every node reaches done.>
+
+## Decisions
+- D1 <first ruling made while building this graph>
+
+## Graph
+Edges, `needs` only; the head needs the tail done. The literal target `nothing` declares a root.
+- n1 needs nothing
+
+## Status
+| Node | State | Detail |
+| --- | --- | --- |
+| n1 | planned |  |

package/templates/intent-screen.md

@@ -0,0 +1,17 @@
+## ▶ {{id}} · {{name}}
+
+| | | |
+| --- | --- | --- |
+| **Store** | {{store}} | {{store.note}} |
+| **Status** | {{status}} | {{status.note}} |
+| **Stage** | {{stage}} | {{stage.note}} |
+| **Savepoint** | {{savepoint}} | {{savepoint.note}} |
+| **Progress** | {{progress.bar}} {{progress.done}} / {{progress.total}} | {{progress.note}} |
+| **Next** | {{next}} | {{next.note}} |
+| **Insight** | {{insight}} | {{insight.note}} |
+
+**Steps**
+
+| Step | Status | Detail |
+| --- | --- | --- |
+{{steps.rows}}

package/templates/node-decision.md

@@ -0,0 +1,11 @@
+---
+node: d1
+kind: decision
+files: []
+budget: 20000
+---
+# d1 - <the decision to make>
+
+## Question
+<The question needing an owner ruling, framed so a yes/no answer or a pick
+from a short list settles it.>

package/templates/node-research.md

@@ -0,0 +1,11 @@
+---
+node: r1
+kind: research
+files: []
+budget: 60000
+---
+# r1 - <what to find out>
+
+## Deposit
+<Where the finding lands: a resources/ file, an artifact URL, or a ruling
+recorded in the intent's ## Decisions.>

package/templates/node-verify.md

@@ -0,0 +1,13 @@
+---
+node: v1
+kind: verify
+files: []
+budget: 40000
+---
+# v1 - <what this node verifies>
+
+<What this node checks, and why it gates the work nodes it needs.>
+
+## Criteria
+- <acceptance criterion one>
+- <acceptance criterion two>

package/templates/node-work.md

@@ -0,0 +1,22 @@
+---
+node: n1
+kind: work
+files: [path/to/file.rb, test/path_to_file_test.rb]
+budget: 100000
+---
+# n1 - <one-line description of what this node builds>
+
+<Why this node exists and what it changes, in a sentence or two.>
+
+## n1 failure-mode matrix
+| Operation | Failure mode | Test |
+| --- | --- | --- |
+| <operation> | <what goes wrong without this code, and its consequence> | `some_test#test_name` |
+
+## Steps
+1. Red: the matrix's tests above, committed before any code.
+2. Write the code that makes them pass.
+3. Green, then the whole suite at its baseline.
+
+## Proven by
+(filled at close from the ledger: commit, suite counts, review verdict)

package/templates/outcome.md

@@ -7,10 +7,28 @@ disposition: delivered|abandoned
 (what was delivered)
 
 ## Delivered
-- ...
+<!-- One row per thing delivered, in plain wording a reader recognizes, not
+an implementation summary; the technical detail belongs in ## Summary. Each
+row's label must appear as a standalone token in an actions/*.md OR
+nodes/*.md heading that owns the matrix table (for example "### S1 - ..."
+with a table beneath it proves row S1, or "## n1 failure-mode matrix" proves
+row n1); that heading's matrix rows become the row's Proven-by cell on the
+delivered screen (intent 317 D19, 317a, 322 D1r, 334 D10r). Readers resolve
+actions/ first, then nodes/ (334 D15r). A label with no owning heading falls
+back to a matrix row cell that carries it, when one under a heading named
+"matrix" exists (322 D3r). -->
+| Row | What |
+| --- | --- |
+| S1 | ... |
 
 ## Verification
 - <acceptance criterion> — verified by ... → result
 
+## Needs you
+<!-- The literal None, or a table shaped | N | What | Why | with one row per
+open owner action. Prose is tolerated by the reader but renders as a single
+untyped row - write the table. -->
+None
+
 ## Follow-ups
 None

package/templates/report-plan.md

@@ -0,0 +1,15 @@
+## ▶ {{id}} · {{name}} · plan
+
+| | | |
+| --- | --- | --- |
+{{fields.rows}}
+
+**Steps**
+
+| Step | Action | Detail |
+| --- | --- | --- |
+{{steps.rows}}
+
+**Risks**
+
+{{risks.block}}

package/templates/report-roadmap-delivered.md

@@ -0,0 +1,10 @@
+## ✔ {{slug}} · roadmap · delivered
+{{meta}}
+
+**Delivered**
+
+{{delivered.table}}
+
+**Log**
+
+{{log.table}}

package/templates/report-roadmap-plan.md

@@ -0,0 +1,9 @@
+## ▶ {{slug}} · roadmap · plan
+
+| | | |
+| --- | --- | --- |
+{{fields.rows}}
+
+**Batches**
+
+{{entries.table}}{{tree}}

package/templates/report-roadmap-state.md

@@ -0,0 +1,9 @@
+## ▶ {{slug}} · roadmap
+
+| | | |
+| --- | --- | --- |
+{{fields.rows}}
+
+**Batches**
+
+{{entries.table}}

package/templates/report-state.md

@@ -0,0 +1,11 @@
+## ▶ {{id}} · {{name}}
+
+| | | |
+| --- | --- | --- |
+{{fields.rows}}
+
+**Steps**
+
+| Step | Status | Detail |
+| --- | --- | --- |
+{{steps.rows}}

package/templates/roadmap.md

@@ -9,6 +9,19 @@ roadmap's goal is reached, move this file from `roadmaps/{slug}.md` to
 (a checkable prose condition — one or a few sentences a human or coordinator reads to decide the
 roadmap is done. Not an executable checker.)
 
+## Graph
+Edges, `needs` only; the head needs the tail done. The literal target `nothing` declares a root
+(an entry needing nothing). Batches below are computed from these edges, not hand-ordered; run
+`roadmap-graph check <this file>` to see the computed batches and `roadmap-graph render <this
+file>` to write them back, or `roadmap-graph migrate <this file>` on an existing graphless
+roadmap to derive edges from its current batch order instead of hand-writing them here.
+
+Grammar (fenced below so this example is never read as a real edge):
+```
+- <intent-id> needs nothing
+- <intent-id> needs <intent-id>
+```
+
 ## Batches
 Entries in a batch are parallel-safe; batches run top to bottom. The checkbox is checked once an
 entry is delivered, unchecked otherwise; the trailing token after the em-dash is the precise