@zalom/plastic 2.0.0-alpha.6 → 2.0.0-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,119 @@
1
+ #!/usr/bin/env ruby
2
+ # encoding: UTF-8
3
+ # frozen_string_literal: true
4
+
5
+ # report-screen - the three delivery-report screens (intent 317): mid-delivery
6
+ # state, post-delivery delivered, and delay. Each fills from the record via
7
+ # scripts/lib/report_screen.rb; no number here is written by eye.
8
+ #
9
+ # Usage:
10
+ # report-screen state <intent_dir> [--changed "<text>"] [--ansi]
11
+ # report-screen state --all <store_root> [--changed "<text>"] [--ansi]
12
+ # report-screen delivered <intent_dir> [--ansi]
13
+ # report-screen delay <intent_dir> [--ansi]
14
+ #
15
+ # --ansi delegates to 316a's renderer conventions when that file is present
16
+ # (D2) and prints plain otherwise, so this never blocks on 316a and never
17
+ # breaks when it lands; NO_COLOR forces plain regardless of --ansi.
18
+ #
19
+ # Exit codes:
20
+ # 0 - the screen is on stdout
21
+ # 2 - usage error, or the path/store is not what the verb expects (one line
22
+ # on stderr, stdout empty)
23
+
24
+ require_relative "lib/report_screen"
25
+ require_relative "lib/intent_screen"
26
+
27
+ def usage_abort(message)
28
+ warn "report-screen: #{message}"
29
+ exit 2
30
+ end
31
+
32
+ # The one place allowed to shell out (D2/D20): resolves the nearest git tag
33
+ # reachable from the repo this script lives in, so `render_delivered`'s
34
+ # version field and the `ship` evidence row are never invented. The pure
35
+ # module never reads git itself; this is injected as `tag_reader:`.
36
+ def git_tag_reader(repo_root)
37
+ lambda do |_intent_dir|
38
+ return nil unless File.exist?(File.join(repo_root, ".git"))
39
+ tag = `git -C #{repo_root} describe --tags --abbrev=0 2>/dev/null`.strip
40
+ tag.empty? ? nil : tag
41
+ end
42
+ end
43
+
44
+ args = ARGV.dup
45
+ verb = args.shift
46
+ changed = nil
47
+ ansi = false
48
+ template_path = nil
49
+ renderer_path = nil
50
+ positional = []
51
+
52
+ while (arg = args.shift)
53
+ case arg
54
+ when "--changed"
55
+ usage_abort("--changed needs a value") if args.empty?
56
+ changed = args.shift
57
+ when "--ansi"
58
+ ansi = true
59
+ when "--all"
60
+ positional << "--all"
61
+ when "--template"
62
+ template_path = args.shift or usage_abort("--template needs a path")
63
+ when "--renderer-path"
64
+ renderer_path = args.shift or usage_abort("--renderer-path needs a path")
65
+ else
66
+ usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--") && arg != "--all"
67
+ positional << arg
68
+ end
69
+ end
70
+
71
+ usage_abort("usage: report-screen state|delivered|delay <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
72
+
73
+ all_mode = positional.delete("--all") ? true : false
74
+ target = positional.first
75
+
76
+ renderer_path ||= File.expand_path("../lib/intent_screen_ansi.rb", __dir__)
77
+ ansi_enabled = ansi && ENV["NO_COLOR"].to_s.empty?
78
+
79
+ def paint(text, ansi_enabled, renderer_path)
80
+ ReportScreen.maybe_paint(text, renderer_path: renderer_path, enabled: ansi_enabled)
81
+ end
82
+
83
+ case verb
84
+ when "state"
85
+ if all_mode
86
+ usage_abort("usage: report-screen state --all <store_root>") unless target
87
+ store_root = File.expand_path(target)
88
+ usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
89
+ out = ReportScreen.render_roster(store_root, changed: changed)
90
+ $stdout.write paint(out, ansi_enabled, renderer_path)
91
+ else
92
+ usage_abort("usage: report-screen state <intent_dir> [--changed \"<text>\"]") unless target
93
+ intent_dir = File.expand_path(target)
94
+ usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
95
+ store_root = File.expand_path("../..", intent_dir)
96
+ template_path ||= File.expand_path("../templates/report-state.md", __dir__)
97
+ usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
98
+ out = ReportScreen.render_state(intent_dir: intent_dir, store_root: store_root, changed: changed,
99
+ template: File.read(template_path))
100
+ $stdout.write paint(out, ansi_enabled, renderer_path)
101
+ end
102
+ when "delivered"
103
+ usage_abort("usage: report-screen delivered <intent_dir>") unless target
104
+ intent_dir = File.expand_path(target)
105
+ usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
106
+ repo_root = File.expand_path("..", __dir__)
107
+ out = ReportScreen.render_delivered(intent_dir: intent_dir, tag_reader: git_tag_reader(repo_root))
108
+ $stdout.write paint(out, ansi_enabled, renderer_path)
109
+ when "delay"
110
+ usage_abort("usage: report-screen delay <intent_dir>") unless target
111
+ intent_dir = File.expand_path(target)
112
+ usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
113
+ out = ReportScreen.render_delay(intent_dir: intent_dir)
114
+ $stdout.write paint(out, ansi_enabled, renderer_path)
115
+ else
116
+ usage_abort("unknown verb #{verb.inspect} (use state|delivered|delay)")
117
+ end
118
+
119
+ exit 0
@@ -0,0 +1,67 @@
1
+ #!/usr/bin/env ruby
2
+ # encoding: UTF-8
3
+ # frozen_string_literal: true
4
+
5
+ # savepoint-note - the writer CLI for the two savepoint kinds intent 317 adds:
6
+ # Review (one line per plan-review or post-execution-review verdict) and
7
+ # Commit (one line per commit landing during Exec). D17: there is no automatic
8
+ # seam for either (session-commit writes the day ledger, not the intent
9
+ # ledger; the executor's own commits are plain git), so this is an explicit
10
+ # thin wrapper on Savepoint.append_review_savepoint / append_commit_savepoint.
11
+ #
12
+ # Usage:
13
+ # savepoint-note <intent_dir> --kind Review|Commit --text "<text>"
14
+ #
15
+ # --text is normalized (D21): runs of two or more spaces collapse to one, so a
16
+ # free-text kind that happens to contain a double space cannot key the dedup
17
+ # primitive's split(/\s{2,}/) on the prefix alone and silently drop a later
18
+ # line. A newline in --text is refused outright (exit 2, ledger unchanged)
19
+ # rather than silently splitting one entry into two malformed ledger lines.
20
+ #
21
+ # Exit codes:
22
+ # 0 - the line was appended (or was already recorded; both are success)
23
+ # 2 - usage error, bad --kind, missing --text, a newline in --text, or the
24
+ # path is not an intent directory (one line on stderr, ledger unchanged)
25
+
26
+ require_relative "lib/savepoint"
27
+
28
+ def usage_abort(message)
29
+ warn "savepoint-note: #{message}"
30
+ exit 2
31
+ end
32
+
33
+ args = ARGV.dup
34
+ kind = nil
35
+ text = nil
36
+ positional = []
37
+ while (arg = args.shift)
38
+ case arg
39
+ when "--kind"
40
+ kind = args.shift
41
+ when "--text"
42
+ text = args.shift
43
+ else
44
+ usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
45
+ positional << arg
46
+ end
47
+ end
48
+
49
+ usage_abort("usage: savepoint-note <intent_dir> --kind Review|Commit --text \"<text>\"") unless positional.length == 1
50
+
51
+ intent_dir = File.expand_path(positional.first)
52
+ usage_abort("#{intent_dir} is not an intent directory") unless File.exist?(Savepoint.intent_file(intent_dir))
53
+
54
+ KINDS = %w[Review Commit].freeze
55
+ usage_abort("--kind must be one of #{KINDS.join(', ')}, got #{kind.inspect}") unless KINDS.include?(kind)
56
+ usage_abort("--text is required") if text.nil? || text.empty?
57
+ usage_abort("--text must not contain a newline") if text.include?("\n")
58
+
59
+ normalized = text.gsub(/ {2,}/, " ").strip
60
+ usage_abort("--text is empty after normalization") if normalized.empty?
61
+
62
+ case kind
63
+ when "Review" then Savepoint.append_review_savepoint(intent_dir, normalized)
64
+ when "Commit" then Savepoint.append_commit_savepoint(intent_dir, normalized)
65
+ end
66
+
67
+ exit 0
@@ -24,6 +24,7 @@
24
24
 
25
25
  require_relative "lib/savepoint"
26
26
  require_relative "lib/worktree"
27
+ require_relative "lib/intent_screen"
27
28
 
28
29
  # Verbatim honoring instruction. Kept as one constant so the contract doc and the
29
30
  # test assert against the exact same string.
@@ -115,11 +116,17 @@ STAGE_LABELS = {
115
116
  "exec" => "Exec", "done" => "Done"
116
117
  }.freeze
117
118
 
119
+ # Intent 317, D6: a dispatched agent's "Current stage:" line must name the last
120
+ # LIFECYCLE line (What/Why/How/Exec/Done), never a trailing Lock/Review/Commit
121
+ # line - the bug spawn-preamble shared with IntentScreen.savepoint_fields
122
+ # before this guard (plan review finding B1).
118
123
  def current_stage(intent_dir)
119
124
  ledger = File.join(intent_dir, Savepoint::SAVEPOINT_FILE)
120
125
  if File.exist?(ledger)
121
- last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
122
- return last if last
126
+ lines = File.read(ledger).each_line.map(&:strip).reject(&:empty?)
127
+ lifecycle = lines.select { |l| IntentScreen.lifecycle_line?(l) }
128
+ return lifecycle.last if lifecycle.any?
129
+ return lines.last if lines.any?
123
130
  end
124
131
  STAGE_LABELS.fetch(Savepoint.derive_stage(intent_dir), Savepoint.derive_stage(intent_dir))
125
132
  end
@@ -200,9 +200,10 @@ Then How.
200
200
  into the spec, the matrix, and the tests; record what was dropped and why in the action
201
201
  file's review fold. A REVISE verdict is folded and not re-reviewed unless a finding changes
202
202
  a decision.
203
- 5. Notify the user (the one mid-flight briefing, per `references/human-report-contract.md`):
204
- State, the plan shape and what it builds; Risk, the riskiest row of the matrix; Call,
205
- proceeding to build. In auto mode this briefing informs; it does not wait.
203
+ 5. Print `ruby ~/.plastic/scripts/report-screen state <intent_dir> --changed "How written, plan review next"`
204
+ (D15; see `references/human-report-contract.md` for the full trigger list). This replaces
205
+ the old prose State/Risk/Call briefing at this boundary. In auto mode the screen informs;
206
+ it does not wait.
206
207
 
207
208
  Then Exec.
208
209
 
@@ -272,6 +273,8 @@ Read `../plastic-conventions/references/completion-and-done.md` for what "intent
272
273
  first, or pass `--discard-worktree-changes` deliberately); 3 means the lock survived the
273
274
  disarm (`/plastic-doctor check the lock status`); 6 means the structure check refused. Never
274
275
  leave an orphaned worktree; run `git worktree prune` on a stale reference.
276
+ 6. Print `ruby ~/.plastic/scripts/report-screen delivered <intent_dir>` once (D15): this is the
277
+ owner report at End, replacing the old prose Done briefing.
275
278
 
276
279
  ## Error Handling
277
280
 
@@ -284,8 +287,8 @@ leaves the project broken.
284
287
 
285
288
  - Read `references/agent-architecture.md` for the team model, the risk list, the headless note,
286
289
  and the solo fallback when dispatching or when a harness has no agent dispatch.
287
- - Read `references/human-report-contract.md` for the State/Risk/Call briefing before sending the
288
- How briefing.
290
+ - Read `references/human-report-contract.md` for the three report screens and the five
291
+ triggers before printing the How or Completion screen above.
289
292
  - Read `references/agent-report-contract.md` for the completion report format when reading a
290
293
  dispatched agent's return or synthesizing one.
291
294
  - Read `references/end-tail.md` for what `Arm.disarm` does at the End tail and why the reindex
@@ -1,72 +1,78 @@
1
- # Human Report Contract (per-stage EM-to-CTO briefing)
2
-
3
- This doc defines how the orchestrator briefs the human at each of the five stage boundaries
4
- (What, Why, How, Exec, Done) in auto mode; for small work only the How boundary fires (see
5
- `## Depth for small work`). It is the outward, human-facing counterpart to the
6
- internal report contract in `references/agent-report-contract.md`. Voice: an engineering
7
- manager briefing a CTO. Lead with impact, name the risk, leave the decision.
8
-
9
- ## The skeleton
10
-
11
- One fixed 3-line shape, reused at every stage:
12
-
13
- 1. **State**: what happened and what it means, impact first, one line.
14
- 2. **Risk**: the one thing that could bite, or "nothing flagged."
15
- 3. **Call**: the decision left to you, or the go-ahead I am taking.
16
-
17
- This is a shape, not a rigid template. Keep the order (State, then Risk, then Call) and keep it
18
- short. The words can flex to fit the stage.
19
-
20
- ## Per-stage content
21
-
22
- - **What**: State = the work I picked up and why it matters now. Risk = scope uncertainty.
23
- Call = confirm this is worth doing, or I proceed.
24
- - **Why**: State = the approach I chose, one line. Risk = the main trade-off. Call = the one
25
- decision I need (approve, or pick an option).
26
- - **How**: State = the plan shape (task count and what it builds). Risk = the riskiest task or
27
- dependency. Call = approve the plan to build.
28
- - **Exec**: State = what got built and the test result. Risk = residual failures or deviations.
29
- Call = go to review, or done.
30
- - **Done**: State = the delivered impact. Risk = residual risk. Call = the decision left to you
31
- (merge, release, accept).
1
+ # Human Report Contract (the three report screens, intent 317)
2
+
3
+ D15: the prose EM-to-CTO briefing this doc used to define is retired. The orchestrator now
4
+ prints one of three report screens, filled from the record by `scripts/report-screen`, never
5
+ written by eye:
6
+
7
+ - **`report-screen state <intent_dir> [--changed "<text>"]`** - the mid-delivery report. One
8
+ intent's field table (Store, Status, Stage, Savepoint, Progress, Next, Insight) plus a
9
+ `Changed` row naming what caused the print, and its Steps table.
10
+ - **`report-screen state --all <store_root>`** - the roster across every in-delivery intent,
11
+ most recently changed first, then one collapsed block (Stage, Next, Changed, first three
12
+ open steps) per intent.
13
+ - **`report-screen delivered <intent_dir>`** - the post-delivery report, printed once at close:
14
+ Asked, Delivered (with a Proven-by column), Evidence, Needs you.
15
+ - **`report-screen delay <intent_dir>`** - printed only on request ("why did X take so long"):
16
+ the delivery as a timeline plus the derived `Where the time went` line.
17
+
18
+ ## The five triggers for `state`
19
+
20
+ Print `state` (one intent, or `--all` for the roster) on any of these; a checklist tick alone,
21
+ an executor's intermediate commit, or an agent going idle is NOT one of them:
22
+
23
+ | Trigger | Scope |
24
+ |---|---|
25
+ | A savepoint line lands (a stage boundary: Why, How, Exec started, outcome written, Done) | that intent |
26
+ | A review verdict returns (plan review or post-execution review), naming what it changed | that intent |
27
+ | A blocker or needs-input is logged | that intent |
28
+ | A merge or a release lands | that intent |
29
+ | The owner asks ("where are we", "state of X", "continue X") | all in delivery, or the one named |
30
+
31
+ `delivered` prints exactly once, at Completion. `delay` prints only when the owner asks why a
32
+ delivery took long.
33
+
34
+ Every verb prints the same plain Markdown on every harness (owner ruling 2026-08-31); where a
35
+ harness can paint it (Claude Code, through 316a's message-display hook), it substitutes a
36
+ painted rendering of that same output, never a different one, and no skill or script branches
37
+ on harness name to decide.
32
38
 
33
39
  ## Depth for small work
34
40
 
35
- For small work in auto mode the mid-flight briefings collapse to one. Only the How briefing fires, and
36
- it folds in what the What and Why briefings would have said: the work picked up and the approach
37
- chosen go into its State line. The Exec briefing folds into the final owner report at End. Larger
38
- work sends all four. The shape does not change: still State, then Risk, then Call, and the per-stage
39
- content above still says what each line covers. This is a depth cut, not a new report. A delivery
40
- still ends with `outcome.md` plus one owner report.
41
+ For small work in auto mode, only the How-boundary `state` screen prints mid-flight (its
42
+ `Changed` row names what the What and Why steps did, since there is no separate briefing per
43
+ stage any more). Larger work prints `state` at every trigger in the table above. This is a
44
+ depth cut, not a different report: the screen's shape never changes, only how often it fires.
45
+ A delivery still ends with `outcome.md` plus one `delivered` screen.
41
46
 
42
47
  ## One report per audience
43
48
 
44
49
  A delivery produces exactly two artifacts: `outcome.md` (authored by `plastic-intent-ending`)
45
- and one EM-to-CTO owner report at the End stage. No stage or skill restates a delivery
46
- already written to `outcome.md`; point at it instead. Skills do not open with a banner that
47
- names the skill or restates the intent id and name the owner just typed. Announce only what
48
- the reader cannot already know: an error, a result, a choice with its reason, or a handoff.
50
+ and one `delivered` screen at the End stage. No stage or skill restates a delivery already
51
+ written to `outcome.md`; point at it instead. Skills do not open with a banner that names the
52
+ skill or restates the intent id and name the owner just typed. Announce only what the reader
53
+ cannot already know: an error, a result, a choice with its reason, or a handoff.
49
54
 
50
55
  ## Boundary vs intent 74
51
56
 
52
57
  Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
53
58
  machine-checked handoff from a dispatched specialist back to the orchestrator: a structured
54
- envelope plus a per-role payload. This contract is the OUTWARD human briefing, orchestrator to
55
- user, in prose. Different direction, different audience, different form. The orchestrator
56
- CONSUMES the intent 74 report to WRITE the human briefing defined here. The two never merge.
59
+ envelope plus a per-role payload. This contract is the OUTWARD screen shown to the owner.
60
+ Different direction, different audience, different form. The orchestrator reads the intent 74
61
+ report and reflects it into the record (savepoint, outcome.md) that `report-screen` then
62
+ renders. The two never merge.
57
63
 
58
64
  ## Brevity: point, don't repeat
59
65
 
60
- Surface rules are owned by the `writing-style` skill. This contract does not restate them, in full
61
- or in summary. It defines the report's shape only: what to say, in what order, and when to stop.
62
- Apply the `writing-style` skill for the wording.
66
+ Surface rules are owned by the `writing-style` skill. This contract does not restate them. Its
67
+ job is naming which screen prints when, not the wording inside it - `report-screen` derives
68
+ every cell from the record (D14), so there is no prose left to style here.
63
69
 
64
70
  ## Emission: guided vs auto
65
71
 
66
- In guided mode, the briefing lands at each stage boundary and the human acts on the Call line
67
- before the next stage starts.
72
+ In guided mode, `state` prints at each stage boundary and the human decides before the next
73
+ stage starts.
68
74
 
69
- In auto mode, for larger work the orchestrator still emits the briefing at each boundary, as a
70
- running EM-to-CTO account. For small work only the How briefing fires; see `## Depth for small work` above for what it
71
- folds in. The Call line becomes the go-ahead the orchestrator takes itself and moves on, except at
72
- the existing hard stops (destructive action without a safe alternative, project-path confirm).
75
+ In auto mode, `state` prints at every trigger for larger work; for small work only the How
76
+ boundary prints (see `## Depth for small work` above). The orchestrator takes the go-ahead
77
+ itself and moves on, except at the existing hard stops (destructive action without a safe
78
+ alternative, project-path confirm).
@@ -103,20 +103,25 @@ For a live intent's directory:
103
103
  the next thing the stage needs (see the matrix). The newest `## Insights` entry supplies
104
104
  the human-readable context; an entry marked `(autonomous)` means an auto team was
105
105
  delivering it, so say so and offer to hand back to `plastic-auto`.
106
- 5. **Print the intent screen as the first thing in the reply, then continue at that stage.**
106
+ 5. **Print the report screen as the first thing in the reply, then continue at that stage.**
107
107
  The screen must open the message with nothing before it. On Claude Code, a fail-open
108
108
  `MessageDisplay` hook recognizes a reply that opens this way and substitutes a styled ANSI
109
109
  rendering for it there; the transcript and every other harness keep exactly this plain
110
- form, and nothing about how the screen is printed here ever changes. Run
111
- `ruby ~/.plastic/scripts/intent-screen <intent_dir>` and print its output as it is: the
112
- title, the field table, and the Steps table come from the record, never by eye. Under it
110
+ form. For "where are we" on one named intent, run
111
+ `ruby ~/.plastic/scripts/report-screen state <intent_dir>` and print its output as it is:
112
+ the title, the field table, the `Changed` row, and the Steps table come from the record,
113
+ never by eye. For "where are we" with no intent named, run
114
+ `ruby ~/.plastic/scripts/report-screen state --all <store_root>` for the roster across every
115
+ in-delivery intent. Route "why did X take so long" to
116
+ `ruby ~/.plastic/scripts/report-screen delay <intent_dir>` instead - every verb prints the
117
+ same plain screen on any harness, painted only where the harness supports it, with no
118
+ branching on harness name. Under the `state` screen
113
119
  write **What this means** as two to four bullets in plain words (what the intent is for,
114
- what has landed, what is left, any defect named by step), then close with
115
- **needs input:** naming the first open step. The screen's shape is
116
- `~/.plastic/templates/intent-screen.md`; the script fills it, the session never edits the numbers.
117
- Then continue the work in the session's current mode. In auto mode the running team
118
- already holds the delivery lock; if a lock is held by a session that is gone, the
119
- `plastic-doctor` skill's lock section repairs or reclaims it.
120
+ what has landed, what is left, any defect named by step), then close with **needs input:**
121
+ naming the first open step. Then continue the work in the
122
+ session's current mode. In auto mode the running team already holds the delivery lock; if a
123
+ lock is held by a session that is gone, the `plastic-doctor` skill's lock section repairs or
124
+ reclaims it.
120
125
 
121
126
  ## Roadmap route: resume the mid-flight roadmap
122
127
 
@@ -63,8 +63,11 @@ on disk is what the record becomes, so before the call:
63
63
 
64
64
  Author outcome.md yourself when it deserves prose: copy `templates/outcome.md`,
65
65
  set the frontmatter to `disposition: delivered` or `disposition: abandoned`, and
66
- fill `## Summary`, `## Delivered`, `## Verification`, `## Follow-ups`. On
67
- abandon, `## Summary` states the abandonment reason and the trail (see Pivot
66
+ fill `## Summary`, `## Delivered`, `## Verification`, `## Follow-ups`. Each
67
+ `## Delivered` row is one thing delivered in plain wording a reader recognizes,
68
+ not a method name or an implementation summary (that detail belongs in
69
+ `## Summary`) - it becomes a row of `report-screen delivered`'s post-delivery
70
+ screen. On abandon, `## Summary` states the abandonment reason and the trail (see Pivot
68
71
  below). A placeholder outcome.md is backfilled from the record instead, with the
69
72
  close's disposition and the `--outcome-summary` line as its summary. Also author
70
73
  the rich INDEX entry note now (a short line in the store's existing
@@ -61,6 +61,8 @@ Run Step 0 (Sync Worktree First) before this step.
61
61
 
62
62
  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.
63
63
 
64
+ 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.
65
+
64
66
  Read its response by code:
65
67
  - DONE or DONE_WITH_CONCERNS → proceed to Step 3.
66
68
  - NEEDS_CONTEXT → provide the missing context, re-dispatch the executor.
@@ -69,6 +71,10 @@ Read its response by code:
69
71
  ### Step 3: Review by Risk
70
72
  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.
71
73
 
74
+ 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.
75
+
76
+ **The D19 heading convention.** An action file's `## Delivered` row (in `outcome.md`) is proven by whichever `actions/ACTION_N.md` heading carries that row's label as a standalone token - `### Row A -` proves row A, `### S1 -` proves row S1. 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 matches.
77
+
72
78
  ### Step 4: Update Intent and Complete
73
79
  Capture observations in `## Insights`. When ALL checklist items are checked:
74
80
 
@@ -7,10 +7,15 @@ disposition: delivered|abandoned
7
7
  (what was delivered)
8
8
 
9
9
  ## Delivered
10
+ <!-- One row per thing delivered, in plain wording a reader recognizes, not
11
+ an implementation summary; the technical detail belongs in ## Summary. -->
10
12
  - ...
11
13
 
12
14
  ## Verification
13
15
  - <acceptance criterion> — verified by ... → result
14
16
 
17
+ ## Needs you
18
+ None
19
+
15
20
  ## Follow-ups
16
21
  None
@@ -0,0 +1,11 @@
1
+ ## ▶ {{id}} · {{name}}
2
+
3
+ | | | |
4
+ | --- | --- | --- |
5
+ {{fields.rows}}
6
+
7
+ **Steps**
8
+
9
+ | Step | Status | What |
10
+ | --- | --- | --- |
11
+ {{steps.rows}}