@zalom/plastic 1.0.0-beta.9 → 1.0.1

package/skills/auto/SKILL.md

@@ -10,6 +10,12 @@ description: >-
 
 Announce: "Taking over intent [ID] — [name] for autonomous delivery."
 
+**Advisory (not a gate).** At auto-mode start, recommend once that the user run this
+orchestrating main session on the best available thinking model (Fable, Opus, or whatever
+supersedes them) for the sharpest gating and synthesis. This is advice only: it changes no
+behavior and blocks nothing if ignored. It concerns the human's MAIN session; dispatched
+subagents keep their pinned tier and never resolve to Fable.
+
 ## Precondition
 
 An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic-creating-intent."
@@ -35,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
@@ -43,13 +70,16 @@ edited before the plan exists (the gate applies to YOU, the orchestrator):
 
 ```bash
 ruby -r ~/.plastic/scripts/lib/bridge -e \
-  'Bridge.arm_auto(ENV["CLAUDE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+  'Bridge.arm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
 ```
 
 Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
-`<dir>` (the `ID--slug` directory), and `<name>`. If `CLAUDE_SESSION_ID` is unset, `arm_auto`
-falls back to a deterministic derived bridge key (a hash of the store and intent id), so the
-gate still engages; arming prints a one-line notice to stderr in that case.
+`<dir>` (the `ID--slug` directory), and `<name>`. The first argument is the session id you
+want the bridge keyed by: pass the hook stdin `session_id` when you have it, otherwise
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. Arming always succeeds and acquires the
+durable `delivery.lock` in the intent dir. For the `resolve_session` fallback chain
+(why arming never needs a non-empty session env var, and what the lock ownership model
+implies for later tool calls) read `references/end-tail.md`.
 
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
@@ -61,6 +91,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):
@@ -73,19 +105,48 @@ Roster (one role per cycle stage):
 
 Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
 
-Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
+Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage, and the provisioned code worktree path when one exists on disk) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
+
+Dispatch-time model contract (belt-and-braces): alongside the preamble, resolve each specialist's model through the config chain (`read-config agents.models.<basename> --project <repo>`: project override, then global, then the shipped tier default) and pass it explicitly at dispatch. Never rely on the dispatched role's frontmatter alone; a resolved subagent model is never Fable.
 
 Completion report (require-then-synthesize): every dispatched specialist MUST end with a structured completion report as its final message. The preamble's `REPORT_CONTRACT` injects this and the role prompts carry the per-role format (see `references/agent-report-contract.md`). Because child-agent honor is best-effort across harnesses, this is decision-shaping, not a hard block. When a specialist returns no usable report (it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), run `scripts/agent-report <intent_dir> --role <role>` to synthesize a deterministic filesystem-derived report so the handoff account always exists. Use the agent-authored report when present, the synthesized one otherwise.
 
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 
-Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).
+### Delegation (subagents writing under the owner's lock)
+
+The enforcer's session owns the delivery lock. Per-stage specialists run in
+their own sessions and would be denied by the lock gate, so register each one
+as a delegate before (or when) it needs to write into the intent dir:
+
+1. Instruct each spawned specialist to report its session id
+   (`CLAUDE_CODE_SESSION_ID`) in its first message.
+2. As the lock owner, run:
+   `ruby ~/.plastic/scripts/plastic-lock delegate --delegate <specialist-session-id>`
+3. If a specialist hits a lock-gate deny, the deny message names this exact
+   command; run it and have the specialist retry.
+
+Only the owner can delegate. Delegates cannot re-delegate or release.
+
+Headless manual gate: when running headless or in the background, still enforce gates manually rather than relying on hooks alone. The PostToolUse gate hook reads `session_id` from hook stdin, and the savepoint ledger write is decoupled from the bridge (derived from the file path, so it fires even with no session id) - these do NOT no-op. What can degrade is the bridge-keyed stage enforcement: if no session id reaches the bridge and no matching bridge is discovered, the stage-gate enforcement step exits without acting, so verify state yourself. The bridge still resolves arming via `CLAUDE_CODE_SESSION_ID` or the derived-key fallback (see the arm-gate note above).
 
 Solo fallback: if the harness has no subagent dispatch, fall back to a single agent walking the full What, Why, How, Exec cycle yourself. This preserves current behavior.
 
 ## Stage-Aware Entry
 
-Read the active intent's directory. Determine current lifecycle stage from filesystem state:
+Read the active intent's `savepoint.md` FIRST (intent 81): the last line classifies the stage,
+and you then verify only that line's artifact before entering. Fall back to the filesystem probe
+below only when the ledger is missing (then rebuild it with `Bridge.rebuild_savepoint`).
+
+| Ledger last line | Enter |
+|---|---|
+| `What  {id}--{slug}.md` (born) or no spec | Start / complete Why (write spec.md) |
+| `Why  spec.md created` | Enter How |
+| `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Enter Exec (verify plan + checklist) |
+| `Exec  outcome.md created` | Exec done; complete the intent |
+| `Done  delivered|abandoned` | Terminal; do not resume |
+
+Filesystem fallback (ledger missing only):
 
 | Check (in order) | Stage |
 |---|---|
@@ -97,6 +158,10 @@ Read the active intent's directory. Determine current lifecycle stage from files
 
 Announce which stage you're entering and why.
 
+Notify user (What briefing): brief per `references/human-report-contract.md`
+(State: the work picked up and why it matters now; Risk: scope uncertainty; Call: confirm
+this is worth doing, or proceed).
+
 ## Why Completion (Autonomous)
 
 When entering at Why stage:
@@ -111,15 +176,26 @@ When entering at Why stage:
 5. Make decisions — pick best option, document in `## Context > ### Decisions` with rationale
 6. Log all autonomous decisions in `## Insights` with `(autonomous)` marker: "Decision: chose X because Y (autonomous)"
 7. Write `spec.md` — consolidated specification
+8. Notify user (Why briefing): brief per `references/human-report-contract.md`
+   (State: the approach chosen, one line; Risk: the main trade-off; Call: the one decision
+   needed, approve or pick an option).
 
 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
+5. Notify user (How briefing): brief per `references/human-report-contract.md`
+   (State: the plan shape, task count and what it builds; Risk: the riskiest task or
+   dependency; Call: approve the plan to build).
 
 Then proceed to Exec.
 
@@ -143,6 +219,9 @@ If the plan calls for creating a new project (the intent is an implementation in
 4. Check off items in `checklist.md` as completed
 5. Append observations to `## Insights` with `(autonomous)` marker
 6. Sub-agents can be spawned for parallel actions (one agent per action)
+7. Notify user (Exec briefing): brief per `references/human-report-contract.md`
+   (State: what got built and the test result; Risk: residual failures or deviations;
+   Call: go to review, or done).
 
 ## Permission Model — Safe-by-Default
 
@@ -172,7 +251,10 @@ During initial project creation, all decisions are non-destructive by definition
 ## Completion
 
 1. Verify all checklist items are checked
-2. Write `outcome.md` with detailed results
+2. Write `outcome.md` with detailed results, from `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md`.
+   Set the frontmatter `disposition: delivered` (this is the delivered terminal). `outcome.md`
+   is mandatory at every terminal and self-declares its disposition (see the canonical done-marker
+   and End tail in PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
 3. Write `## Outcome` summary in the intent file (1-2 sentences)
 4. **Release (if configured)**
    1. Detect project — match CWD against paths in `~/.plastic/projects.yml` to find the project slug. If no match, skip to step 5 (default commit-only behavior).
@@ -191,22 +273,41 @@ During initial project creation, all decisions are non-destructive by definition
 5. Review `## Insights` for observations that should spawn future intents. If any:
    - Create them (using `plastic-creating-intent` conventions)
    - Update `chain` in the current intent's frontmatter
-6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date). As the
+   closing act of the transfer, stamp the terminal ledger bookend (intent 81) so the savepoint's
+   last line records delivery:
+   ```bash
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'
+   ```
+   (Use `"abandoned"` instead when the intent is being moved to `## Abandoned`.) Idempotent.
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent).
-   It runs in the background so it never blocks the turn:
+8. Disarm the lifecycle gate (auto delivery is finished). Substitute the intent's own id for
+   `<ID>` (a session can be delivering more than one intent at once, intent 131, so disarm must
+   name which of the session's bridges to clear):
    ```bash
-   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>")'
    ```
-   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the
-   store that holds this intent (the global store or the project store).
-9. Disarm the lifecycle gate (auto delivery is finished):
+   Disarm runs the ordered End tail (release worktrees, then clear the `delivery.lock`,
+   then the bridge becomes purge-eligible) and performs the mandatory worktree cleanup
+   (intent 73c3): both per-intent worktrees are removed and both repos pruned. This is
+   the plain remove path (no merge); when the work ships through a release, the release
+   path merges the branch BEFORE the worktree is removed instead of relying on this step.
+   Never leave an orphaned worktree, and run `git worktree prune` if you hit a stale
+   reference. For the full ordering rationale and the release-vs-plain-disarm
+   distinction, read `references/end-tail.md`.
+9. QMD reindex LAST (canonical End tail), run only after disarm has released the
+   worktrees, cleared the `delivery.lock`, and purged the bridge. It runs in the
+   background so it never blocks the turn:
    ```bash
-   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Disarming also purges stale bridge files from the temp directory automatically (it keeps the
-   current bridge and any live run), so no manual `/tmp` cleanup is needed.
-10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+   `<store-root>` is the store that holds this intent (the global store or the project
+   store); the command is a no-op when QMD is absent. For why the reindex must be last
+   (so the index never references a bridge or lock about to disappear), read
+   `references/end-tail.md`.
+10. Notify user (Done briefing): brief per `references/human-report-contract.md`
+    (State: the delivered impact; Risk: residual risk; Call: the decision left to you, merge,
+    release, or accept). See `outcome.md` for details.
 
 ## Error Handling
 
@@ -219,3 +320,9 @@ 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
+- Read `references/human-report-contract.md` for the human-facing per-stage briefing (the
+  State/Risk/Call skeleton used at each "Notify user" step above, and how it differs from the
+  internal `agent-report-contract.md`)
+- Read `references/end-tail.md` for the `resolve_session` fallback chain and the disarm
+  ordering / worktree cleanup / QMD reindex rationale referenced above

package/skills/auto/references/agent-architecture.md

@@ -90,10 +90,13 @@ permanent sixth role, it exists only for the final review.
 
 ### Headless Manual Gate
 
-When running headless or in the background, the enforcer enforces gates manually and
-does not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in those runs (the
-gate-check and savepoint hooks no-op without it). The enforcer arms via the bridge's
-derived-key fallback and verifies state itself.
+When running headless or in the background, the enforcer enforces gates manually rather
+than relying on hooks alone. The savepoint ledger and PostToolUse gate hook still fire
+(the gate hook reads `session_id` from stdin; the savepoint write is path-derived and
+bridge-independent), so they do not blanket no-op. Only the bridge-keyed stage-enforcement
+step degrades when no session id reaches the bridge and no bridge is discovered. The
+enforcer arms via `CLAUDE_CODE_SESSION_ID` or the bridge's derived-key fallback and
+verifies state itself.
 
 ### Delegation
 

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

@@ -17,6 +17,14 @@ only. In-flight observations still go in `## Insights`; the report does not add
 completed its handoff: the agent that did the work is the cheapest, most accurate source of the
 account.
 
+## Prose-stripped (intent 84)
+
+The report is the envelope and the per-role payload, nothing else. Dispatched and background
+subagents report and do their job; they do not narrate. Strip conversational prose: no
+greeting, no preamble, no "Here is what I did" framing, no end-recap, no restating of the task.
+Reasoning belongs in the thinking channel, not the report body. This tightens the FORM (the
+fields stay exactly as below); it does not remove any required field.
+
 ## Common envelope
 
 Every role report, whatever the stage, carries these fields:
@@ -31,6 +39,11 @@ Every role report, whatever the stage, carries these fields:
 - **Checklist deltas**: which checklist items this turn checked off (executor), or `n/a`.
 - **Deviations from spec**: anything done differently from the spec or plan, and why, or `none`.
 - **Blockers / handoff notes**: what the next stage must watch for, or `none`.
+- **Insights**: 0..N durable nuggets discovered this turn (the most interesting residue),
+  each one a `## Insights`-worthy line; `none` if there were none. Background and dispatched
+  agents MUST populate this: they carry each nugget home in the report and the orchestrator
+  persists it (see Insights delivery below), so an insight never depends on the discovering
+  session having file-write access.
 
 ## Per-role payload
 
@@ -41,11 +54,13 @@ D2). The payload is what makes the report useful to the orchestrator beyond 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.
+- Insights: durable discoveries from the Why exploration, reported in the `insights:` field.
 
 ### spec-specialist (Why to How boundary)
 - Spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria).
 - How the recorded decisions resolved into the chosen approach.
 - Acceptance-criteria count, so the planner knows the surface to cover.
+- Insights: durable discoveries from consolidating the spec, reported in the `insights:` field.
 
 ### planner (How): worked exemplar
 The planner report EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR. It carries:
@@ -54,17 +69,20 @@ The planner report EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR. It carries:
 - Checklist coverage: item count and that every action plus suite-green is covered.
 This is the exemplar because the plan is an argument, and the orchestrator gates on whether that
 argument is sound before any code is written.
+- Insights: durable discoveries from planning, reported in the `insights:` field.
 
 ### executor (Exec)
 - Actions implemented this turn, mapped to checklist items checked off (checked / total).
 - A summary of the code changed (files and the shape of the change).
 - Test result: the full-suite command and its pass / fail counts.
-- Insights appended, with the `(autonomous)` marker.
+- Insights reported in the `insights:` field (each with the `(autonomous)` marker); the
+  executor or the orchestrator persists them to `## Insights` via the `insight-append` helper.
 
 ### final reviewer (final gate)
 - Verdict: `pass` or `blockers found`.
 - Each acceptance criterion checked, with the evidence that confirms or refutes it.
 - Gaps or risks found, ranked, with a recommended disposition.
+- Insights: durable discoveries from the review, reported in the `insights:` field.
 
 ## Fallback: always a report
 
@@ -84,3 +102,20 @@ ledger, the lifecycle artifacts present, the checklist checked / total, and the
 line, and emits a filesystem-derived report labelled `synthesized`. So a handoff account always
 exists: authored by the agent when possible, reconstructed deterministically when not. This
 formalizes the by-hand reconstruction the orchestrator did while delivering intent 68.
+
+## Insights delivery
+
+Insights ride home in the completion report. Every agent reports its durable nuggets in the
+`insights:` field; the orchestrator (or any agent that can write the intent file) then persists
+each one via the helper:
+
+```
+scripts/insight-append <intent_dir> <text> --stage S --author A
+```
+
+The helper formats the `{utc-iso8601} · {stage} · {author}` prefix (the same timestamp
+convention as the savepoint ledger), validates it, and appends the entry at the bottom of the
+`## Insights` section, newest last. This is the fix for dropped background and sub-agent
+insights: a session that cannot write the intent file still returns its report, so the insight
+survives and the orchestrator writes it on receipt. Hand-editing `## Insights` is an escape
+hatch; the helper is the default so the prefix format cannot drift.

package/skills/auto/references/end-tail.md

@@ -0,0 +1,56 @@
+# End-Tail Mechanics: resolve_session and Disarm Ordering
+
+Deep WHY/mechanics detail behind two spots in `SKILL.md`: how `arm_auto` resolves a
+session id when arming the gate, and why the End-tail steps in Completion (release
+worktrees, clear the lock, purge the bridge, reindex) run in that exact order.
+
+## Table of Contents
+
+- [resolve_session fallback internals](#resolve_session-fallback-internals)
+- [Disarm ordering and worktree cleanup rationale](#disarm-ordering-and-worktree-cleanup-rationale)
+- [QMD reindex ordering rationale](#qmd-reindex-ordering-rationale)
+
+## resolve_session fallback internals
+
+`arm_auto` calls `resolve_session`, which picks the first non-empty of: the explicit
+id you pass -> `CLAUDE_CODE_SESSION_ID` -> a deterministic derived key (a hash of the
+store and intent id). It never returns nil, so the gate engages even when every
+session env var is empty; the call never needs a non-empty session env var to
+function. Arming prints a one-line notice to stderr when it falls through to the
+derived key.
+
+Arming acquires the durable `delivery.lock` in the intent dir, keyed by that resolved
+session. Ownership is session-keyed, not process-keyed, so the arm one-liner exiting
+immediately is fine by construction: the lock stays yours for every later tool call in
+this session. A failed arm raises with a message naming the resolving `plastic-lock`
+verb.
+
+## Disarm ordering and worktree cleanup rationale
+
+Disarm runs the ordered End tail: it releases the worktrees first, then clears the
+intent's `delivery.lock` (and the bridge's lock cache), and only then is the bridge
+purge-eligible. Disarming also purges stale bridge files from the temp directory
+automatically (it keeps the current bridge, any live run, and any bridge whose intent
+still holds a delivery lock), so no manual `/tmp` cleanup is needed.
+
+**Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
+`disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
+worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
+`<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
+from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
+only when no release merges the branch (the branch survives and can be reclaimed).
+
+When the work is being shipped through a release, do NOT rely on this plain remove. The
+release path (Completion step 4, via `plastic-releasing`) is responsible for merging the
+intent's code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the
+worktree is removed, so the integrated work is not lost. It does this with
+`Worktree.finish(bridge_data, merge: true)` (merge-then-remove). Never leave an orphaned
+worktree, and run `git worktree prune` if you hit a stale reference.
+
+## QMD reindex ordering rationale
+
+Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is
+the store that holds this intent (the global store or the project store). The reindex is
+the LAST End-tail step, run after purge, so the index never references a bridge or lock
+that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner
+Lock`).

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

@@ -0,0 +1,55 @@
+# Human Report Contract (per-stage EM-to-CTO briefing)
+
+This doc defines how the orchestrator briefs the human at each of the five stage boundaries
+(What, Why, How, Exec, Done) in auto mode. It is the outward, human-facing counterpart to the
+internal report contract in `references/agent-report-contract.md`. Voice: an engineering
+manager briefing a CTO. Lead with impact, name the risk, leave the decision.
+
+## The skeleton
+
+One fixed 3-line shape, reused at every stage:
+
+1. **State**: what happened and what it means, impact first, one line.
+2. **Risk**: the one thing that could bite, or "nothing flagged."
+3. **Call**: the decision left to you, or the go-ahead I am taking.
+
+This is a shape, not a rigid template. Keep the order (State, then Risk, then Call) and keep it
+short. The words can flex to fit the stage.
+
+## Per-stage content
+
+- **What**: State = the work I picked up and why it matters now. Risk = scope uncertainty.
+  Call = confirm this is worth doing, or I proceed.
+- **Why**: State = the approach I chose, one line. Risk = the main trade-off. Call = the one
+  decision I need (approve, or pick an option).
+- **How**: State = the plan shape (task count and what it builds). Risk = the riskiest task or
+  dependency. Call = approve the plan to build.
+- **Exec**: State = what got built and the test result. Risk = residual failures or deviations.
+  Call = go to review, or done.
+- **Done**: State = the delivered impact. Risk = residual risk. Call = the decision left to you
+  (merge, release, accept).
+
+## Boundary vs intent 74
+
+Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
+machine-checked handoff from a dispatched specialist back to the orchestrator: a structured
+envelope plus a per-role payload. This contract is the OUTWARD human briefing, orchestrator to
+user, in prose. Different direction, different audience, different form. The orchestrator
+CONSUMES the intent 74 report to WRITE the human briefing defined here. The two never merge.
+
+## Brevity: point, don't repeat
+
+Surface rules (no em-dashes, plain words, no filler openers, and so on) are owned by the
+shipped `plastic-humanizer` skill and the always-on plain-language layer. This contract does not
+re-list that catalog. It restates only the hard bans as one line: no em-dashes, no "not X but Y",
+no rule of three, no hype words, no sycophancy, no over-bolding. Apply `plastic-humanizer` and the
+always-on layer for everything else.
+
+## Emission: guided vs auto
+
+In guided mode, the briefing lands at each stage boundary and the human acts on the Call line
+before the next stage starts.
+
+In auto mode, the orchestrator still emits the briefing at each boundary, as a running EM-to-CTO
+account. The Call line becomes the go-ahead the orchestrator takes itself and moves on, except at
+the existing hard stops (destructive action without a safe alternative, project-path confirm).

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/brainstorming/SKILL.md

@@ -44,30 +44,8 @@ You MUST create a task for each of these items and complete them in order:
 
 ## Process Flow
 
-```dot
-digraph brainstorming {
-    "Explore project context" [shape=box];
-    "Ask clarifying questions" [shape=box];
-    "Propose 2-3 approaches" [shape=box];
-    "Present design sections" [shape=box];
-    "User approves design?" [shape=diamond];
-    "Write spec" [shape=box];
-    "Spec self-review\n(fix inline)" [shape=box];
-    "User reviews spec?" [shape=diamond];
-    "Invoke plastic-writing-plans" [shape=doublecircle];
-
-    "Explore project context" -> "Ask clarifying questions";
-    "Ask clarifying questions" -> "Propose 2-3 approaches";
-    "Propose 2-3 approaches" -> "Present design sections";
-    "Present design sections" -> "User approves design?";
-    "User approves design?" -> "Present design sections" [label="no, revise"];
-    "User approves design?" -> "Write spec" [label="yes"];
-    "Write spec" -> "Spec self-review\n(fix inline)";
-    "Spec self-review\n(fix inline)" -> "User reviews spec?";
-    "User reviews spec?" -> "Write spec" [label="changes requested"];
-    "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
-}
-```
+The Checklist above states the ordered flow (steps 1-8). For the same flow as a
+diagram, read `references/design-principles.md`.
 
 **The terminal state is invoking `plastic-writing-plans`.** Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is `plastic-writing-plans`.
 
@@ -95,16 +73,11 @@ digraph brainstorming {
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify if something doesn't make sense
 
-**Design for isolation and clarity:**
-- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
-- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
-- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
-- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
-
-**Working in existing codebases:**
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+**Design for isolation and clarity, and working in existing codebases:** before
+proposing a design, read `references/design-principles.md` for unit-boundary
+guidance (what makes a good interface, when a file has grown too large) and
+existing-codebase guidance (follow established patterns, fold in targeted
+improvements without unrelated refactoring).
 
 ## After the Design
 **Documentation:**