@zalom/plastic 1.0.0-beta.31 → 1.0.0-beta.33

package/PLASTIC.md

@@ -150,6 +150,28 @@ agent that can write the file) persists it via the helper. A session that cannot
 intent file still returns its report, so the insight survives.
 For full lifecycle detail, the skills in the Detail column have references/.
 
+## Tiers (proportional auto sizing)
+
+Auto mode sizes every intent S/M/L at Why: S = single mechanism or file cluster (hours);
+M = one subsystem (about a day); L = cross-cutting or novel design.
+
+Speed comes from two levers only: artifact content depth and agent topology. The
+same-structure invariant holds: same file set, stage order, gates, and savepoint ledger at
+every tier and in both modes.
+
+S/M collapse the topology (one thinker agent writes spec.md then plan.md plus
+checklist.md in one context; actions/ only for L; a sonnet executor implements). L keeps
+the full team.
+
+Never cut at any tier: the independent reviewer, outcome.md as truth of delivery, the
+delivery lock, worktree isolation, intent creation via skill, INDEX as status truth, the
+QMD reindex at End.
+
+Tier is recorded as a `Tier: S|M|L` line at the top of spec.md. It is convention-only,
+read by the orchestrator, not enforced by any gate or by doctor.
+
+Guided mode is unchanged: full-depth artifacts, the human at every gate.
+
 ## Agent Models and Dispatch (intent 116)
 
 Every lifecycle stage has exactly one dispatchable background agent, plus the enforcer that
@@ -300,6 +322,45 @@ One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>]
 The title is the title, not a summary: aim for about 80 characters, no multi-sentence
 descriptions. This is a self-check, not a gate.
 
+## Roadmaps
+
+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`). Use `plastic-roadmap` to create, order,
+close, and consume one.
+
+File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
+inside `store/` (store holds intent directories, not project artifacts). For a project that is its
+root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
+`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
+in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
+a sibling subdirectory scaffolded once with a `.gitkeep`.
+
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
+append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
+an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
+waves run sequentially, top to bottom.
+
+Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
+on any conflict INDEX wins and the roadmap entry is corrected to match.
+
+**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
+checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
+line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
+engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
+or codenames, ending with a link
+to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
+opening the file with no other context can tell what shipped, what is running now, and what is
+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. Waves 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
+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.
+
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -512,3 +573,4 @@ Detailed conventions live inside the skills that use them, not in this file.
 | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
 | Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
 | Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
+| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |

package/agents/plastic-brainstorming.md

@@ -19,7 +19,13 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code
 2. **Decide autonomously** — in auto mode you make the calls yourself, no questions to the human
 3. **Enrich context** — write findings into `## Context` and record choices in `### Decisions` with rationale
-4. **Hand off** — leave the Why stage ready for the spec-specialist to consolidate into a spec
+4. **Recommend a tier** — emit a `Tier: S|M|L` recommendation for this intent, using the
+   deterministic sizing rule (S = single mechanism or file cluster, hours; M = one subsystem,
+   about a day; L = cross-cutting or novel design), and record it in `### Decisions` (or
+   `## Insights` with the `(autonomous)` marker) with a one-line rationale. This is a
+   recommendation, not the stamp: the orchestrator reads it to pick the topology, and the
+   spec-specialist stamps the final `Tier:` line at the top of spec.md.
+5. **Hand off** — leave the Why stage ready for the spec-specialist to consolidate into a spec
 
 ## How You Work
 
@@ -36,6 +42,7 @@ END your turn with a structured completion report as your final message, per the
 - Decisions recorded in `### Decisions`, each with its one-line rationale
 - Context enriched: what was researched and the key findings
 - Open questions resolved, and any deliberately left for the spec
+- Tier recommendation (`S|M|L`) and its one-line rationale
 
 ## Constraints
 

package/agents/plastic-enforcer.md

@@ -21,8 +21,23 @@ subagents keep their pinned tier and never resolve to Fable.
 ## Your Responsibilities
 
 1. **Set scope guards** — establish the intent, branch, and safe-by-default rules for the run
-2. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
-3. **Sequence the team** — dispatch ONE specialist per stage (brainstorming, spec-specialist, planner, executor) with a constructed context bundle
+2. **Size the intent at Why** — deterministically size S/M/L (S = single mechanism or file
+   cluster, hours; M = one subsystem, about a day; L = cross-cutting or novel design), then
+   pick the per-tier topology BEFORE How begins. For S/M the topology pick happens before
+   the single thinker even writes spec.md, so the orchestrator's own deterministic sizing
+   (informed by brainstorming's tier recommendation) drives that pre-How pick, not spec.md.
+   The `Tier: S|M|L` line stamped at the top of spec.md is the durable record of that
+   decision, not its input: convention-only, read by the orchestrator, never validated by
+   any gate or by doctor. Deterministic sizing keeps the two in agreement.
+3. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
+4. **Sequence the team** — dispatch specialists per the chosen topology with a constructed
+   context bundle:
+   - S/M: ONE thinker agent, one boot, two stations — it writes spec.md, then plan.md +
+     checklist.md, in a single context. Sections may be one line each; plan.md carries the
+     checklist rationale inline; `actions/` files appear only for L. S may skip the QMD
+     discovery deposit when chain and sources are both empty. A sonnet executor implements.
+   - L: today's full team, one specialist per stage (brainstorming, spec-specialist, planner,
+     executor), each in a fresh context.
 
 **Dispatch-time model contract (belt-and-braces).** Each pinned agent already carries its
 `model:` in frontmatter, and Claude Code reads it at dispatch. Because read-at-dispatch is a
@@ -32,8 +47,13 @@ agents.models.<basename> --project <repo>`: project override, then global, then
 tier default) and pass it explicitly as the dispatch call's model parameter, alongside the
 spawn-preamble live-state injection. Never rely on the dispatched role's frontmatter alone. A
 resolved subagent model is never Fable.
-4. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
-5. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
+5. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
+6. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
+
+Never-cut list at any tier: the independent reviewer (a separate agent, fresh context, never
+the maker), `outcome.md` as truth of delivery, the delivery lock, worktree isolation, intent
+creation via skill, INDEX as status truth, the QMD reindex at End. Lightness collapses
+ceremony, never these guarantees.
 
 ## How You Work
 

package/agents/plastic-executor.md

@@ -23,7 +23,11 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## How You Work
 
-1. Receive (input handoff): `plan.md`, `checklist.md`, and `actions/` from the planner
+1. Receive (input handoff): `plan.md` and `checklist.md` from the planner (plus
+   `ACTION_N.md` files inside `actions/` at L; at S/M the `actions/` directory exists but
+   stays empty, so read the tier fork from the inline plan-as-checklist in plan.md
+   instead). For S/M intents you run on the sonnet default, the collapsed topology's
+   implementer; behavior is otherwise unchanged.
 2. Work one action at a time, preferring safe, non-destructive routes
 3. Edit project code (the gate is open now that plan and checklist exist)
 4. Run the full suite, iterate to zero failures and zero errors

package/agents/plastic-planner.md

@@ -18,8 +18,14 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Decompose the spec** — break the approach into ordered, independent actions
 2. **Write the plan** — produce `plan.md` with numbered tasks and verification
-3. **Write self-contained actions** — one `actions/ACTION_N.md` per task, each runnable on its own
-4. **Write the checklist** — `checklist.md` as the execution registry covering every action
+3. **Write self-contained actions, tier-forked**:
+   - S/M: `plan.md` carries the checklist rationale INLINE; do NOT write
+     `actions/ACTION_N.md` files. Sections may be one line each.
+   - L: keep today's shape — one self-contained `actions/ACTION_N.md` per task.
+4. **Write the checklist** — `checklist.md` as the execution registry covering every action.
+   `checklist.md` exists at every tier: the file set does not change by tier, only depth
+   (inline vs action files) and agent topology do. plan.md + checklist.md are the two files
+   that open the code gate at every tier.
 
 ## How You Work
 
@@ -36,6 +42,7 @@ END your turn with a structured completion report as your final message, per the
 - The ordered actions, one line each: what the action does and how it is verified
 - Decomposition rationale: why this order, and why the actions are independent
 - Checklist coverage: the item count, and that every action plus suite-green is covered
+- Which tier shape was produced: inline plan-as-checklist (S/M) or full `actions/` (L)
 
 The plan is an argument; the orchestrator gates on whether that argument is sound before any code is written, so make the report make that case.
 
@@ -45,3 +52,5 @@ The plan is an argument; the orchestrator gates on whether that argument is soun
 - You write only intent-store files (`plan.md`, `actions/`, `checklist.md`); no project code
 - The code gate stays closed until `plan.md` and `checklist.md` exist, so produce both
 - Keep each action self-contained so the executor can run them one at a time
+- The `actions/` empty-directory git-tracking edge (present only within one same-session
+  local delivery) is out of scope; do not add a `.gitkeep` or a guard for it here

package/agents/plastic-spec-specialist.md

@@ -18,8 +18,16 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec
 2. **Follow the template** — produce `spec.md` with Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria
-3. **Make it the contract** — the spec is what the planner and executor build against
-4. **Hand off** — leave a complete `spec.md` ready for the planner
+3. **Stamp the tier** — write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
+   Spec:` heading, taking the value from the orchestrator's sizing / the brainstorming
+   recommendation. This line is convention-only: read by the orchestrator, never validated by
+   any gate or by doctor. It is an extra top line, not a template field, so no template changes.
+4. **Accept collapsed sections at S/M** — a spec.md whose Problem, Goals, Non-Goals, Approach,
+   Decisions, or Acceptance Criteria sections are a single line each is still a complete
+   spec.md under the same-structure invariant; do not pad it. The gates check file existence
+   and realness, not artifact depth, so a collapsed-but-real spec passes.
+5. **Make it the contract** — the spec is what the planner and executor build against
+6. **Hand off** — leave a complete `spec.md` ready for the planner
 
 ## How You Work
 
@@ -36,6 +44,7 @@ END your turn with a structured completion report as your final message, per the
 - The spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria)
 - How the recorded decisions resolved into the chosen approach
 - The acceptance-criteria count, so the planner knows the surface to cover
+- The stamped `Tier:` value
 
 ## Constraints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.31",
+  "version": "1.0.0-beta.33",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/lib/bridge.rb

@@ -491,19 +491,45 @@ module Bridge
     append_savepoint_line(intent_dir, "Done", disposition, now)
   end
 
+  # --- Tier convenience line (intent 130, D-A) ------------------------------
+  #
+  # spec.md's top `Tier: S|M|L` line is the single authoritative record of an
+  # intent's proportional-auto-sizing tier (see PLASTIC.md `## Tiers`). This
+  # reads that line only; it never validates or enforces it (convention-only,
+  # matching the skill and agent contracts). Returns nil when spec.md is
+  # absent, empty, or its first line does not match, so a missing/malformed
+  # Tier line changes nothing about existing rebuild behavior.
+  def self.savepoint_tier(intent_dir)
+    path = File.join(intent_dir, "spec.md")
+    return nil unless File.exist?(path)
+    first = File.open(path, &:gets)
+    return nil if first.nil?
+    m = first.chomp.strip.match(/\ATier:\s*(S|M|L)\z/)
+    m && m[1]
+  end
+
   # Reconstruct the ledger from files on disk (timestamps from mtimes), in
   # stage order, overwriting savepoint.md. Returns the number of lines written.
+  # When spec.md carries a Tier line, one convenience `Tier  <value>` line is
+  # echoed right after the spec.md milestone line (same mtime), so the tier
+  # survives a rebuild without becoming a new source of truth.
   def self.rebuild_savepoint(intent_dir)
     ordered = [
       File.basename(intent_file(intent_dir)),
       "spec.md", "plan.md", "checklist.md", "outcome.md",
     ]
-    lines = ordered.filter_map do |basename|
+    lines = ordered.flat_map do |basename|
       path = File.join(intent_dir, basename)
-      next unless stage_file_present?(path)
+      next [] unless stage_file_present?(path)
       stage, milestone = savepoint_milestone(intent_dir, basename)
-      next unless milestone
-      "#{File.mtime(path).utc.iso8601}  #{stage}  #{milestone}\n"
+      next [] unless milestone
+      stamp = File.mtime(path).utc.iso8601
+      entry = "#{stamp}  #{stage}  #{milestone}\n"
+      if basename == "spec.md" && (tier = savepoint_tier(intent_dir))
+        [entry, "#{stamp}  Tier  #{tier}\n"]
+      else
+        [entry]
+      end
     end
     File.write(File.join(intent_dir, SAVEPOINT_FILE), lines.join)
     lines.length
@@ -1003,10 +1029,15 @@ module Bridge
 
   # Redirections: `> path` / `>> path`, but not fd dups (`2>&1`) or /dev/null.
   # A leading digit (fd number) before > is fine; `>&` is a dup and excluded.
+  # Quote- and heredoc-aware: a `>` inside a single/double-quoted span or inside a
+  # heredoc body is NOT a redirect. Fails OPEN (returns []) on an ambiguous parse
+  # (unbalanced quote or unterminated heredoc) rather than guessing a target.
   def self.bash_redirect_targets(command)
+    return [] unless command.is_a?(String)
+    scannable = scannable_redirect_text(command)
+    return [] if scannable.nil? # ambiguous parse -> fail open
     targets = []
-    # Match optional leading fd digits, then > or >>, not followed by & , then path.
-    command.scan(/\d*>>?(?!&)\s*([^\s;|&<>]+)/) do |m|
+    scannable.scan(/\d*>>?(?!&)\s*([^\s;|&<>]+)/) do |m|
       path = m[0]
       next if path.nil? || path.empty?
       next if dev_null?(path)
@@ -1015,6 +1046,76 @@ module Bridge
     targets
   end
 
+  # Return a copy of `command` in which single-quoted spans, double-quoted spans,
+  # and heredoc bodies are blanked to spaces, so the redirect regex only ever sees
+  # operators that are genuinely outside quotes and heredoc bodies. Returns nil on
+  # an ambiguous parse (a line ends inside a quote, or a heredoc is never closed).
+  def self.scannable_redirect_text(command)
+    out = +""
+    pending = [] # queue of {word:, dash:} heredoc terminators awaiting bodies
+    command.split("\n", -1).each do |line|
+      if pending.any?
+        term = pending.first
+        probe = term[:dash] ? line.sub(/\A\t+/, "") : line
+        pending.shift if probe == term[:word]
+        out << "\n" # heredoc body/terminator line contributes nothing scannable
+        next
+      end
+      masked, openers, balanced = mask_redirect_line(line)
+      return nil unless balanced # unbalanced quote on this line -> ambiguous
+      out << masked << "\n"
+      pending.concat(openers)
+    end
+    return nil if pending.any? # unterminated heredoc -> ambiguous
+    out
+  end
+
+  # Walk one normal (non-heredoc-body) line, masking quoted spans to spaces and
+  # recognizing heredoc openers. Returns [masked_line, [heredoc_openers], balanced?].
+  def self.mask_redirect_line(line)
+    out = +""
+    openers = []
+    state = :normal
+    i = 0
+    n = line.length
+    while i < n
+      c = line[i]
+      case state
+      when :single
+        out << " "
+        state = :normal if c == "'"
+        i += 1
+      when :double
+        if c == "\\" && i + 1 < n
+          out << "  "
+          i += 2
+        else
+          out << " "
+          state = :normal if c == '"'
+          i += 1
+        end
+      else # :normal
+        if c == "'"
+          out << " "; state = :single; i += 1
+        elsif c == '"'
+          out << " "; state = :double; i += 1
+        elsif c == "<" && line[i + 1] == "<"
+          m = line[i..].match(/\A<<(-?)\s*("|')?([A-Za-z_][A-Za-z0-9_]*)\2?/)
+          if m
+            openers << { word: m[3], dash: m[1] == "-" }
+            out << (" " * m[0].length)
+            i += m[0].length
+          else
+            out << "<<"; i += 2 # here-string / no valid word: leave as-is
+          end
+        else
+          out << c; i += 1
+        end
+      end
+    end
+    [out, openers, state == :normal]
+  end
+
   def self.bash_utility_targets(segment)
     tokens = segment.strip.split(/\s+/)
     return [] if tokens.empty?

package/scripts/update.rb

@@ -53,18 +53,22 @@ class Update < InstallerCore
       end
       puts "\u{2b06}\u{fe0f}  Updating Plastic #{iv} \u{2192} #{res[:target]}"
       exit_code = perform_switch(res[:target], agent_args(argv))
-      run_post_update_doctor if exit_code == 0
+      run_post_update_doctor(full: argv.include?("--full-doctor")) if exit_code == 0
       exit_code
     end
   end
 
-  # Run the full doctor after a successful update and print a human-readable
-  # summary. Informational only: does not raise and does not affect the update's
-  # exit code. Accepts injected `doctor` and `out` for hermetic unit tests.
-  def run_post_update_doctor(doctor: nil, out: $stdout)
+  # Run doctor after a successful update and print a human-readable summary.
+  # Defaults to the fast core tier (agent registration + core files + manifest
+  # sync, binary pass|fail, no store walk) so a newcomer's first post-update
+  # run is not buried in convention warns they cannot act on. `full: true`
+  # (via `--full-doctor`) runs the complete store walk instead. Informational
+  # only: does not raise and does not affect the update's exit code. Accepts
+  # injected `doctor` and `out` for hermetic unit tests.
+  def run_post_update_doctor(doctor: nil, out: $stdout, full: false)
     doctor ||= Doctor.new
-    out.puts "\nRunning full doctor after update..."
-    result = doctor.run_checks("claude")
+    out.puts full ? "\nRunning full doctor after update..." : "\nRunning core doctor after update..."
+    result = full ? doctor.run_checks("claude") : doctor.run_core_checks("claude")
     s = result[:summary]
     out.puts "  Doctor status: #{result[:status]} " \
              "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
@@ -152,6 +156,11 @@ class Update < InstallerCore
       Agent options (default: --claude):
         --claude --codex --hermes --all
 
+      Post-update doctor:
+        By default, a successful update runs the fast core doctor sync (agent
+        registration, core files, manifest — binary pass|fail, no store walk).
+        --full-doctor   Run the full doctor (complete store walk) after updating.
+
       Behaviour:
         No flag advances to the next version on your current channel. Switching toward a
         more stable channel is frictionless; switching toward bleeding edge is confirmed.

package/skills/auto/SKILL.md

@@ -41,6 +41,27 @@ intents, then open the authoritative intent file for the hit you take over. The
 when QMD is absent, so fall back to the existing INDEX.md / file scan. (This is discovery; the
 reindex step under Completion is separate.)
 
+## Tiers (proportional auto sizing)
+
+Auto mode sizes every intent S/M/L at Why, deterministically, then matches agent topology
+and artifact depth to that size. Extended walkthrough: `references/tiers.md`.
+
+1. **Sizing rule.** S = single mechanism or file cluster (hours). M = one subsystem (a
+   day). L = cross-cutting or novel design.
+2. **Two levers.** Speed comes only from artifact content DEPTH and agent TOPOLOGY. The
+   same-structure invariant (same file set, stage order, gates, savepoint ledger) holds at
+   every tier and in both modes. A three-line spec.md is still a spec.md, in the same
+   place, under the same gate.
+3. **Per-tier topology.** S/M: one thinker agent, one boot, two stations, sonnet
+   executor, `actions/` skipped; S may also skip the QMD discovery deposit when chain and
+   sources are both empty. L: today's full team (`## Team Spin-Up` below).
+4. **Never-cut list**, any tier or mode: the independent reviewer (separate agent, fresh
+   context, never the maker), `outcome.md` as truth of delivery, the delivery lock,
+   worktree isolation, intent creation via skill, INDEX as status truth, the QMD reindex
+   at End. Lightness is about ceremony, never about these guarantees.
+5. **Tier record.** `Tier: S|M|L` at the top of spec.md. Convention-only: read by the
+   orchestrator, never validated by any gate or by doctor.
+
 ## Arm the Lifecycle Gate (do this FIRST)
 
 Immediately after selecting the intent — before any other work — arm auto mode. This
@@ -77,6 +98,8 @@ Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.
 
 ## Team Spin-Up
 
+This is the L-tier shape (see `## Tiers` above); S/M collapse it to one thinker agent.
+
 Auto mode spins up exactly ONE enforcer-led team per intent. The plastic-enforcer IS this orchestrator (you), not a separately dispatched agent, which avoids the who-gates-the-gater regress.
 
 Roster (one role per cycle stage):
@@ -161,9 +184,14 @@ Then proceed to How.
 
 ## How Phase
 
+This is the L-tier shape (see `## Tiers` above); S/M skip step 3 and fold the checklist
+rationale into plan.md inline. The `actions/` directory itself is scaffolded empty at
+intent birth and persists at every tier; only writing `ACTION_N.md` files into it is L
+only (S/M leave the directory empty).
+
 1. If `superpowers:writing-plans` is available as a skill, delegate plan creation to it. Tell it the plan saves to the active intent's directory (not `docs/superpowers/plans/`).
 2. Otherwise, write `plan.md` directly — implementation plan with numbered tasks
-3. Create `actions/` directory with `ACTION_N.md` files (one per task, self-contained)
+3. Write `ACTION_N.md` files into the existing `actions/` directory (one per task, self-contained) — L only
 4. Write `checklist.md` — execution registry with checkboxes covering all actions
 
 Then proceed to Exec.
@@ -293,3 +321,4 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 ## References
 
 - Read `references/agent-architecture.md` for the full team model (the 5-role enforcer-led team, per-stage handoffs, gate ownership, headless note, solo fallback) and the orchestrator hierarchy (Main Orchestrator, Project Orchestrators, coordination loop) when spinning up the team or understanding autonomous delivery scope
+- Read `references/tiers.md` for the extended per-tier walkthrough (S/M/L worked examples, the collapsed one-thinker flow, the QMD-skip case for S) and rationale

package/skills/auto/references/tiers.md

@@ -0,0 +1,77 @@
+# Tiers — Extended Walkthrough
+
+This is the detail behind `## Tiers` in SKILL.md. The five points there (sizing rule, two
+levers, per-tier topology, never-cut list, tier record) are the authoritative contract;
+this file only expands on them with examples and rationale.
+
+## Why sizing exists
+
+Auto mode used to run every intent through the same full-ceremony team: brainstorming,
+spec-specialist, planner, executor, and an independent reviewer, each a separate agent
+booting a fresh context. For a large or novel intent that ceremony earns its cost. For a
+small intent (one file, one mechanism, an hour of real work) the ceremony dominates:
+overhead runs about 3 to 4 times the actual work time, roughly flat regardless of size, so
+it hurts small intents the most. Sizing at Why and matching the topology to that size drops
+small-intent ceremony toward about 1.5x work time, without touching structure, gates, or
+the savepoint ledger.
+
+## Sizing rule, worked examples
+
+- S: fixing one script's argument parsing, adding one skill section, a single bug fix
+  confined to one file. Hours of work.
+- M: adding a new agent role file end to end, a subsystem with a handful of touched files
+  and one clear seam. About a day.
+- L: cross-cutting prose or code that spans the skill contract plus multiple agent role
+  files (like this intent, 130), or any genuinely novel design with no established pattern
+  to follow.
+
+## S/M collapsed topology, in detail
+
+One thinker agent boots ONCE and stays in a single context for two stations:
+
+1. Station 1 — writes `spec.md` (collapsed sections allowed, one line each is valid).
+2. Station 2 — writes `plan.md` + `checklist.md` in the SAME context (no reboot). plan.md
+   carries the checklist rationale inline instead of separate `actions/ACTION_N.md` files.
+   `actions/` is not created for S/M.
+
+Then a sonnet executor (a fresh dispatch, this is the one topology split that always
+happens) implements from plan.md + checklist.md, checks off items, appends `## Insights`,
+and drives the suite green, exactly as it does for L.
+
+The independent reviewer still runs at the final gate for S/M, in its own fresh context,
+never the maker. This is on the never-cut list; it does not collapse.
+
+S may skip the QMD discovery deposit (normally a `plastic-intent-discovery` pass before
+Why) when the intent's `chain` and `sources` are both empty in frontmatter. With no graph
+edges there is nothing to discover, so the deposit is pure overhead; a one-line context
+note ("no chain/sources, discovery skipped") takes its place.
+
+## L topology, unchanged
+
+L keeps today's full multi-agent team as described in `## Team Spin-Up`: brainstorming,
+spec-specialist, planner, executor, each a separate agent in its own fresh context, plus
+the independent reviewer at the final gate. Cross-cutting or novel work benefits from the
+separate perspectives and the handoff discipline; the ceremony is not waste at this size.
+
+## Same-structure invariant, why it is non-negotiable
+
+The file set, stage order, gates, and savepoint ledger never change by tier. Renaming or
+skipping files to save time would require new gate logic per tier and would break state
+derivability (the gates and the savepoint rebuild depend on a fixed file set at fixed
+paths). So the only two levers are content depth and agent topology; structure is the
+constant that keeps every tier auditable the same way.
+
+## Tier record, mechanics
+
+The tier is recorded as a `Tier: S|M|L` line at the very top of spec.md, above the `#
+Spec:` heading. It is convention-only: the orchestrator reads it to pick topology, and
+nothing else depends on it. No frontmatter schema change, no new file, no doctor rule, no
+gate check. If a later intent wants doctor or a gate to validate the line, that is a
+separate, explicit follow-up; this system deliberately adds no new operational surface.
+
+## Never-cut list, the safety floor
+
+At any tier or mode: the independent reviewer (separate agent, fresh context, never the
+maker), `outcome.md` as the truth of delivery, the delivery lock, worktree isolation,
+intent creation via skill, INDEX as status truth, the QMD reindex at End. These are
+predictability and safety guarantees, not ceremony, and lightness never touches them.

package/skills/roadmap/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plastic-roadmap
+description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of tickets in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
+---
+
+# Roadmap
+
+A roadmap is a named, ordered, delivery-side collection of intents: the delivery-side counterpart
+to a release (completion-side, `CHANGELOG.md`). It lives at `roadmaps/{slug}.md`, a sibling of
+`INDEX.md` wherever `INDEX.md` lives: the global tier's `~/.plastic/roadmaps/` (beside
+`~/.plastic/INDEX.md`), or a project's root, `~/.plastic/projects/{slug}/roadmaps/` (beside that
+project's `INDEX.md` and `project.yml`). It never sits inside `store/`, which holds intent
+directories, not project artifacts.
+
+A roadmap file has four parts: a title/meta header, `## Goal` (prose), `## Waves` (ordered; entries
+inside a wave are parallel-safe, waves run sequentially), and an append-only dated `## Log`. Each
+wave entry mirrors that intent's status in `INDEX.md` (`queued`/`delivering`/`delivered`/
+`abandoned`/`blocked`).
+
+**`INDEX.md` is the single writer of intent status; on any conflict INDEX wins and the roadmap
+entry is corrected to match.**
+
+The skill operates on the file directly via Read/Edit; no helper script.
+
+## Verbs
+
+| Verb | When | Mechanics |
+|------|------|-----------|
+| Create | user wants to start a new roadmap / plan a delivery batch | `references/operations.md#create` |
+| Add / reorder entries | user wants to add intents to a wave or resequence waves | `references/operations.md#add--reorder-entries` |
+| Sync status mirror | an entry's status may be stale against INDEX | `references/operations.md#sync-status-mirror` |
+| Append log line | a roadmap event just happened (created, wave done, closed) | `references/operations.md#append-a-log-line` |
+| Read / consume | a human or a coordinator needs the roadmap's current state | `references/operations.md#read--consume` |
+| Close / archive | the roadmap's `## Goal` is reached | `references/operations.md#close--archive` |
+
+See `references/file-format.md` for the exact entry-line shape, status vocabulary, checkbox/log
+format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
+verb above.
+
+## Notes
+
+- File location and the four-section shape are identical across tiers; do not invent a different
+  layout per project. The general rule: `roadmaps/` is a sibling of `INDEX.md`, wherever `INDEX.md`
+  lives.
+- `## Goal` is a checkable prose condition read by a human or agent, not an executable checker.
+- Wave entries render as checkboxes (`- [x] ... — delivered` / `- [ ] ... — <status>`); a human
+  reading cold should see shipped/running/next within a minute. `## Log` lines are one-sentence,
+  EM-to-CTO-voice, dated, and link each entry-intent's `outcome.md` (lossless-by-reference).
+- Additive: this skill introduces no gate, lock, or hook, and does not change `INDEX.md`'s section
+  list or the intent frontmatter schema.
+- Closing a roadmap moves it to `roadmaps/archived/{slug}.md` so `roadmaps/` lists only live ones.

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

@@ -0,0 +1,91 @@
+# Roadmap File Format
+
+## Location
+
+`roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives. For the global tier
+that is `~/.plastic/roadmaps/{slug}.md` (beside `~/.plastic/INDEX.md`); for any project it is
+that project's root, `~/.plastic/projects/{slug}/roadmaps/{slug}.md` (beside that project's
+`INDEX.md` and `project.yml`). `roadmaps/` never sits inside `store/`: `store/` holds intent
+directories, not project artifacts. Create the `roadmaps/` directory the first time a tier gets a
+roadmap.
+
+`roadmaps/` lists only live (open or in-flight) roadmaps. Once a roadmap's `## Goal` is reached,
+its file moves to `roadmaps/archived/{slug}.md` (see Close/archive in `operations.md`); the
+`archived/` subdirectory is scaffolded once, alongside `roadmaps/`, with a `.gitkeep`.
+
+## The four sections (in order)
+
+1. **Title/meta header** — `# Roadmap: <name>` plus a one-line meta sentence naming what the
+   roadmap delivers and which tier (project or global) it lives in.
+2. **`## Goal`** — a checkable prose condition: one or a few sentences a human or coordinator reads
+   to decide the roadmap is done. Not an executable checker, not a list of tasks.
+3. **`## Waves`** — ordered waves (`### Wave 1`, `### Wave 2`, ...). Entries inside a wave are
+   parallel-safe (can be dispatched together); waves run top to bottom, sequentially (wave 2 does
+   not start until wave 1's entries are no longer `queued`/`delivering`).
+4. **`## Log`** — append-only, dated, one line per event. Newest entry at the bottom. Never edit or
+   remove an existing log line.
+
+## Entry line shape
+
+One line per intent, inside its wave, as a Markdown checkbox:
+
+```
+- [x] <intent-id> <title> — delivered
+- [ ] <intent-id> <title> — <status>
+```
+
+`<intent-id>` and `<title>` match the intent's `INDEX.md` entry (terse, not a summary). The
+checkbox is checked (`[x]`) once `<status>` is `delivered`, unchecked (`[ ]`) for every other
+status. The checkbox is a rendering of the mirrored status token, not a second piece of state: a
+human scanning the file sees at a glance what shipped (checked) and what has not (unchecked),
+while the trailing token still carries the precise state (`queued`/`delivering`/`blocked`/
+`abandoned`) when unchecked.
+
+## Status vocabulary
+
+`queued` | `delivering` | `delivered` | `abandoned` | `blocked`
+
+Status is a **mirror** of `INDEX.md`. `INDEX.md` is the single writer of intent status; on any
+conflict INDEX wins and the roadmap entry (both its token and its checkbox) is corrected to match
+it. The roadmap never sets a status that INDEX does not already reflect.
+
+## Log line shape
+
+One line per event, starting `YYYY-MM-DD HH:MM UTC` (human-readable, sortable, zone-explicit so
+same-day parallel deliveries can still be ordered), in plain-language EM-to-CTO voice: what shipped
+and why it matters to a non-expert reader, no jargon or internal codenames, ending with a link to
+that entry-intent's `outcome.md`:
+
+```
+- <YYYY-MM-DD HH:MM UTC> <one plain-language sentence: what shipped, its impact> — see store/<id>--<slug>/outcome.md
+```
+
+The log line never restates `outcome.md` detail; it points at it (lossless-by-reference). This
+complements, and does not replace, `INDEX.md`'s `## Completed` section or `CHANGELOG.md`.
+
+## Worked example
+
+```
+# Roadmap: Stable 1.0
+
+Delivery-side collection of intents that close out the pre-1.0 hardening pass, plastic project store.
+
+## Goal
+All intents below are delivered, the suite is green, and a 1.0.0 release is cut.
+
+## Waves
+Entries in a wave are parallel-safe; waves run top to bottom. The checkbox tracks delivered/not;
+the token after the em-dash carries the precise mirrored status (queued | delivering | delivered |
+abandoned | blocked); INDEX wins on any conflict.
+
+### Wave 1
+- [x] 121 Fix bash gate redirect parsing — delivered
+- [ ] 130 Proportional cycle tiers — delivering
+
+### Wave 2
+- [x] 124 Roadmap feature — delivered
+
+## Log
+- 2026-07-06 14:32 UTC Shipped the bash-gate redirect fix so quoted arrows and heredoc trailers
+  stop blocking legitimate commits — see store/121--fix-bash-gate-redirect-parsing/outcome.md.
+```

package/skills/roadmap/references/operations.md

@@ -0,0 +1,78 @@
+# Roadmap Operations
+
+All six verbs operate on the Markdown file directly (Read/Edit). No helper script exists or is
+needed; the file is small and the edits are mechanical.
+
+**Human-comprehension goal.** Every operation below should leave the file such that a cold reader
+(no INDEX.md, no intent directories open) can answer "what's shipped, what's running, what's
+next" in under a minute, just from this one file.
+
+## Create
+
+1. Pick a `slug` (kebab-case, descriptive) and a `title`.
+2. Resolve the tier root: the directory that holds `INDEX.md` (a project's root, beside
+   `project.yml`, or `~/.plastic/` for the global tier). `roadmaps/` is always a sibling of
+   `INDEX.md`, never inside `store/`. Create `roadmaps/` there if it does not exist yet.
+3. Copy `templates/roadmap.md` to `roadmaps/{slug}.md`.
+4. Fill the header (`# Roadmap: <title>` + the one-line meta) and write a real `## Goal` prose
+   condition.
+5. Add at least one `## Waves` wave with real entries (see Add / reorder below), each entry's
+   status mirroring that intent's current `INDEX.md` status.
+6. Append the first `## Log` line, a short `YYYY-MM-DD HH:MM UTC`-prefixed plain-language note
+   that the roadmap was created.
+
+## Add / reorder entries
+
+- **Add**: append an entry line (`- <intent-id> <title> — <status>`) to the target wave. Pick the
+  intent's title and status straight from `INDEX.md`.
+- **New wave**: add a new `### Wave N` heading after the last wave; entries in it are gated behind
+  every earlier wave's entries leaving `queued`/`delivering`.
+- **Reorder**: move an entry line to a different wave, or move a `### Wave` heading (with its
+  entries) earlier or later. Reordering never changes an entry's status; it only changes when the
+  entry is eligible to run.
+- After any add/reorder, append a `## Log` line describing the change (e.g.
+  `- <YYYY-MM-DD HH:MM UTC> added 132 to wave 2`).
+
+## Sync status mirror
+
+1. Read the intent's real status from `INDEX.md` (`## Active`, `## Future`, `## Completed`, or
+   `## Abandoned`).
+2. Compare to the roadmap entry's `<status>` token.
+3. If they differ, **INDEX wins**: rewrite the roadmap entry's status token to match INDEX, and
+   flip its checkbox in the same edit (`[x]` when the new status is `delivered`, `[ ]` otherwise).
+   Never edit INDEX.md from the roadmap skill; the roadmap is a mirror, not a second writer.
+4. Append a `## Log` line recording the change. When the new status is `delivered`, write the
+   one-line EM-to-CTO entry described in `file-format.md` (date, what shipped and its impact in
+   plain language, then a link to that intent's `outcome.md`). For other transitions, write a
+   short dated plain-language line (no codenames, no jargon).
+
+## Append a log line
+
+- One line per event, starting `YYYY-MM-DD HH:MM UTC`, appended at the bottom of `## Log`. Never
+  edit or delete an existing line (append-only).
+- Every line is plain language a non-expert can read, never a codename or a raw `field -> value`.
+  A delivery event follows the EM-to-CTO one-line shape with an `outcome.md` link (see
+  `file-format.md`); bookkeeping events (created, an intent added to a wave, a wave completed, a
+  roadmap closed) are short dated plain-language lines.
+
+## Read / consume
+
+- A human reading the file gets the current picture directly: `## Goal` for the target, `## Waves`
+  for what is queued/delivering/delivered per wave (checkboxes give the shipped/not-shipped view at
+  a glance), `## Log` for a one-line, plain-language history with a link into each intent's
+  `outcome.md` for detail.
+- A future coordinator (for example, an auto-mode dispatcher) reads `## Waves` top to bottom:
+  a wave is eligible to dispatch once every entry in the previous wave is no longer
+  `queued`/`delivering`; within an eligible wave, entries still `queued` are parallel-dispatchable.
+  Always re-sync against `INDEX.md` before dispatch decisions, since INDEX is the source of truth.
+
+## Close / archive
+
+1. Confirm the roadmap's `## Goal` prose condition is met (every entry `delivered` or explicitly
+   `abandoned` with a recorded reason, plus whatever else the goal states).
+2. Create `roadmaps/archived/` beside `roadmaps/` (both siblings of `INDEX.md`) if it does not
+   exist yet.
+3. Move the file: `roadmaps/{slug}.md` -> `roadmaps/archived/{slug}.md`. `roadmaps/` itself then
+   lists only live (open or in-flight) roadmaps.
+4. Append the final `## Log` line before or as part of the move:
+   `- <YYYY-MM-DD HH:MM UTC> roadmap closed`.

package/templates/roadmap.md

@@ -0,0 +1,30 @@
+# Roadmap: <name>
+
+(one-line meta: what this roadmap delivers, and which tier it lives in. `roadmaps/` is a sibling
+of `INDEX.md` — a project's root or the global `~/.plastic/`, never inside `store/`. When this
+roadmap's goal is reached, move this file from `roadmaps/{slug}.md` to
+`roadmaps/archived/{slug}.md`; `roadmaps/` itself lists only live roadmaps.)
+
+## Goal
+(a checkable prose condition — one or a few sentences a human or coordinator reads to decide the
+roadmap is done. Not an executable checker.)
+
+## Waves
+Entries in a wave are parallel-safe; waves 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 mirrored
+status (queued | delivering | delivered | abandoned | blocked) from INDEX.md. INDEX always wins on
+any conflict between the checkbox/token here and INDEX's real status.
+
+### Wave 1
+- [ ] <intent-id> <title> — queued
+- [ ] <intent-id> <title> — queued
+
+### Wave 2
+- [x] <intent-id> <title> — delivered
+
+## Log
+(append-only, dated, one line per event. Each line is one plain-language, EM-to-CTO-voice sentence:
+what shipped and its impact for a non-expert reader, no jargon or internal codenames, ending with a
+link to that entry-intent's `outcome.md`. Never restate outcome detail here; link to it instead.
+Newest at the bottom.)
+- 2026-01-01 00:00 UTC Shipped the first wave of this roadmap; see store/<intent-id>--<slug>/outcome.md.