@zalom/plastic 2.0.0-alpha.17 → 2.0.0-alpha.19

package/scripts/report-screen

@@ -17,6 +17,7 @@
 #   report-screen session <tier_root> [--session <id>] [--since <iso>]
 #                                     [--ledger-root <dir>] [--ansi]
 #   report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]
+#   report-screen archive <store_root> [--ansi]
 #
 # --ansi delegates to ScreenPaint (intent 317a, D1), the parser/re-layouter
 # in the shared TUI core. Selection is by capability, never by harness:
@@ -267,8 +268,14 @@ when "roadmap"
   roadmap_store_root = store_root_flag ? File.expand_path(store_root_flag) : nil
   out = ReportScreen.render_roadmap(path: roadmap_path, verb: sub_verb, store_root: roadmap_store_root)
   $stdout.write paint(out, ansi_enabled)
+when "archive"
+  usage_abort("usage: report-screen archive <store_root>") unless target
+  store_root = File.expand_path(target)
+  usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+  out = ReportScreen.render_archive(store_root)
+  $stdout.write paint(out, ansi_enabled)
 else
-  usage_abort("unknown verb #{verb.inspect} (use plan|state|delivered|delay|session|roadmap)")
+  usage_abort("unknown verb #{verb.inspect} (use plan|state|delivered|delay|session|roadmap|archive)")
 end
 
 exit 0

package/scripts/roadmap-savepoint

@@ -18,6 +18,7 @@
 # rebuilds an empty ledger.
 
 require_relative "lib/roadmap_savepoint"
+require_relative "lib/guarded_append"
 
 def opt(args, name)
   (i = args.index(name)) && args[i + 1]
@@ -47,6 +48,12 @@ when "append"
   rescue ArgumentError => e
     warn "append: #{e.message}"
     exit 2
+  rescue GuardedAppend::Unavailable => e
+    # Intent 335 (spec D14): the write guard could not be taken; nothing was written. Exit 4
+    # rather than let a backtrace reach the six skill recipes that drive this CLI - it rescues
+    # ArgumentError alone today and would otherwise print one straight to the terminal.
+    warn "append: #{e.message}"
+    exit 4
   end
 
 when "rebuild"

package/scripts/validate-work-graph

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# validate-work-graph - deterministic CLI over WorkGraphValidator (intent 334, n4).
+#
+# Checks whether one intent directory's graph.md and nodes/ form a valid work
+# graph: needs targets resolve, node files reconcile with the declared graph,
+# per-kind body sections are present, and (above the trivial bar) a verify
+# node gates two or more work nodes with a failure-mode matrix per work node.
+# Modelled on scripts/validate-intent: errors to stderr, same exit-code shape.
+#
+# Usage:
+#   validate-work-graph <intent_dir>
+#
+# Exit codes: 0 (valid), 1 (invalid or unreadable; report on stderr),
+# 2 (usage - no argument given).
+
+require_relative "lib/work_graph_validator"
+
+intent_dir = ARGV.find { |a| !a.start_with?("--") }
+
+if intent_dir.nil?
+  warn "usage: validate-work-graph <intent_dir>"
+  exit 2
+end
+
+dir = File.expand_path(intent_dir)
+result = WorkGraphValidator.validate(dir)
+
+if result[:ok]
+  puts "OK: #{dir}"
+  exit 0
+end
+
+warn "INVALID: #{dir}"
+result[:missing].each { |m| warn "missing: #{m}" }
+result[:errors].each { |e| warn e }
+exit 1

package/skills/auto/SKILL.md

@@ -169,6 +169,7 @@ ledger is missing (then rebuild it with `Savepoint.rebuild_savepoint`).
 | `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Exec (verify plan, matrix, checklist) |
 | `Exec  outcome.md created` | Exec done; complete the intent |
 | `Done  delivered|abandoned` | Terminal; do not resume |
+| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye |
 
 Filesystem fallback, in order: `checklist.md` with items checked means resume Exec from the
 first unchecked item; `plan.md` plus `checklist.md` means enter Exec; `spec.md` alone means
@@ -184,9 +185,7 @@ Announce which stage you are entering and why.
 3. Decide: pick the best option per gap, record it in `## Context > ### Decisions` with the
    rationale, and log it in `## Insights` with the `(autonomous)` marker through
    `scripts/insight-append`.
-4. Write `spec.md`.
-
-Then How.
+4. Write `spec.md`. Then How.
 
 ## How (the lead), then the plan review
 

package/skills/auto/references/human-report-contract.md

@@ -102,8 +102,9 @@ A delivery still ends with `outcome.md` plus one `delivered` screen.
 
 ## One report per audience
 
-A delivery produces exactly two artifacts: `outcome.md` (authored by `plastic-intent-ending`)
-and one `delivered` screen at the End stage. No stage or skill restates a delivery already
+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-ending` 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.

package/skills/intent-continuing/references/boarding-matrix.md

@@ -13,6 +13,7 @@ Classify from the last line alone, then verify only that line's artifact is real
 | `How  checklist.md created` / `Exec  started` | How | **Exec** | do the work, check off the checklist |
 | `Exec  outcome.md created` | Exec | **ready to complete** | the ending procedure (`plastic-intent-ending`) |
 | `Done  delivered` / `Done  abandoned` | terminal | **report only** | immutable; ask what is next |
+| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec | **Exec** | a graph delivery is in progress; read node status through `NodeLedger.status`, never re-derive it by eye |
 
 ## Per-stage behaviour (what "continue" means)
 

package/skills/intent-ending/SKILL.md

@@ -51,28 +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`. `## 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 that owns the matrix table (`### S1 - ...` with a
-table beneath it proves row S1; 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). 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

package/skills/intent-executing/SKILL.md

@@ -75,7 +75,7 @@ Apply the auto skill's risk rule to the executor's return and the diff: a matrix
 
 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` heading that carries that row's label as a standalone token AND owns the matrix table (322 D1r) - `### Row A -` with a table beneath it proves row A, `### S1 -` proves row S1; a heading that only names the label, with no table under it, is skipped. Write action-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.
+**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:

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/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/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

@@ -9,12 +9,14 @@ disposition: delivered|abandoned
 ## 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 heading
-that owns the matrix table (for example "### S1 - ..." with a table beneath
-it proves row S1); that heading's matrix rows become the row's Proven-by
-cell on the delivered screen (intent 317 D19, 317a, 322 D1r). 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'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 | ... |