@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/scripts/plastic-lock

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+#
+# plastic-lock: inspect and repair the durable delivery lock (intent 108, D5),
+# and take/free per-artifact claim tokens (intent 111 D1/D5).
+#
+# Usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim>
+#          [--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]
+#
+# Verbs:
+#   status        report the lock file, the bridge cache, their agreement,
+#                 and any live per-artifact claims
+#   fix           idempotent repair: rebuild lock + bridge from disk truth for
+#                 the current session; never touches a fresh foreign lock
+#   release       owner clears the lock (End tail / abandoning a boarding)
+#   reclaim       explicit takeover of a stale lock, audited in savepoint.md
+#   delegate      owner registers a subagent session under the lock (D4)
+#   claim         acquire the named --artifact's claim token (intent 111);
+#                 rejected (exit 1) while a fresh claim is held by anyone,
+#                 including this same session; takes over a stale claim
+#   release-claim free the named --artifact's claim token
+#
+# Without --intent-dir the intent is resolved from this session's bridge.
+# Exit 0 on success/report; exit 1 when the verb is blocked (held elsewhere).
+
+require "json"
+require_relative "lib/bridge"
+require_relative "lib/lock"
+
+def usage!
+  warn "usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim> " \
+       "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]"
+  exit 1
+end
+
+verb = ARGV.shift
+usage! unless %w[status fix release reclaim delegate claim release-claim].include?(verb)
+
+opts = {}
+until ARGV.empty?
+  case (flag = ARGV.shift)
+  when "--intent-dir" then opts[:dir] = ARGV.shift
+  when "--session" then opts[:session] = ARGV.shift
+  when "--delegate" then opts[:delegate] = ARGV.shift
+  when "--artifact" then opts[:artifact] = ARGV.shift
+  else
+    warn "unknown flag #{flag}"
+    usage!
+  end
+end
+
+session = opts[:session]
+session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.strip.empty?
+
+dir = opts[:dir]
+if dir.nil? || dir.strip.empty?
+  bridge = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
+  dir = Bridge.bridge_intent_dir(bridge)
+end
+if dir.nil?
+  warn "plastic-lock: no intent resolved; pass --intent-dir <intent dir>"
+  exit 1
+end
+dir = File.expand_path(dir)
+
+intent_id = Bridge.intent_id_from_dir(dir)
+store = File.dirname(dir)
+name = File.basename(dir)
+key = Bridge.resolve_session(session, intent_id: intent_id, store: store)
+
+case verb
+when "status"
+  lock = Lock.read(dir)
+  bridge = Bridge.read(key, intent_id: intent_id)
+  report = {
+    "intent_dir" => dir,
+    "session" => key,
+    "lock" => lock,
+    "lock_fresh" => Lock.fresh?(dir),
+    "lock_corrupt" => Lock.corrupt?(dir),
+    "bridge_present" => !bridge.nil?,
+    "agreement" => (lock && bridge) ?
+      (lock["owner_session"] == bridge.dig("lock", "owner_session")) : nil,
+    "claims" => Claim.claims_status(dir),
+  }
+  puts JSON.pretty_generate(report)
+when "fix"
+  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
+                              store: store, name: name)
+  puts JSON.pretty_generate(report)
+  unless report["status"] == "repaired"
+    warn "plastic-lock: #{report['status']} by #{report['owner']}" \
+         "#{report['hint'] ? " (#{report['hint']})" : ''}"
+    exit 1
+  end
+when "release"
+  result = Lock.release(dir, session: key)
+  if result == :not_owner
+    warn "plastic-lock: not the owner; run plastic-lock status"
+    exit 1
+  end
+  data = Bridge.read(key, intent_id: intent_id)
+  if data
+    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
+                     "host" => nil, "type" => nil, "delegates" => [] }
+    Bridge.write(key, data)
+  end
+  puts "released (#{result})"
+when "reclaim"
+  status, lock_data = Lock.takeover(dir, session: key)
+  if status == :fresh
+    warn "plastic-lock: lock is FRESH and held by #{lock_data['owner_session']}; " \
+         "back off (no silent reclaim)"
+    exit 1
+  end
+  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
+                              store: store, name: name)
+  puts JSON.pretty_generate(report)
+when "delegate"
+  usage! if opts[:delegate].nil?
+  ok = Lock.add_delegate(dir, delegate: opts[:delegate], session: key)
+  unless ok
+    warn "plastic-lock: only the lock owner may delegate; run plastic-lock status"
+    exit 1
+  end
+  puts "delegated #{opts[:delegate]} under #{key}"
+when "claim"
+  usage! if opts[:artifact].nil?
+  status, data = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                     delegate: opts[:delegate])
+  case status
+  when :acquired
+    puts "claimed #{opts[:artifact]} under #{key}"
+  when :held
+    warn "plastic-lock: #{opts[:artifact]} is claimed by " \
+         "#{data['owner_session']} since #{data['acquired_at']}; back off"
+    exit 1
+  when :stale
+    old = data && data["owner_session"]
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    status2, = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                   delegate: opts[:delegate])
+    if status2 == :acquired
+      warn "plastic-lock: took over stale claim on #{opts[:artifact]} from #{old}"
+      puts "claimed #{opts[:artifact]} under #{key}"
+    else
+      warn "plastic-lock: could not take over #{opts[:artifact]} (#{status2})"
+      exit 1
+    end
+  when :corrupt
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    Claim.acquire_claim(dir, opts[:artifact], session: key, delegate: opts[:delegate])
+    puts "claimed #{opts[:artifact]} under #{key} (repaired corrupt claim)"
+  end
+when "release-claim"
+  usage! if opts[:artifact].nil?
+  result = Claim.release_claim(dir, opts[:artifact], session: key)
+  if result == :not_owner
+    warn "plastic-lock: not the claim owner; run plastic-lock status"
+    exit 1
+  end
+  puts "released-claim #{opts[:artifact]} (#{result})"
+end

package/scripts/read-config

@@ -9,6 +9,7 @@
 
 require "yaml"
 require "json"
+require_relative "lib/agent_models"
 
 DEFAULTS = {
   "version" => 3,
@@ -23,6 +24,9 @@ DEFAULTS = {
     "type" => "claude-code",
     "parallel_mode" => "linear"
   },
+  "agents" => {
+    "models" => AgentModels::TIER_DEFAULTS
+  },
   "architect" => {
     "style" => nil
   }

package/scripts/spawn-preamble

@@ -41,10 +41,18 @@ REPORT_CONTRACT =
   "FINAL MESSAGE (your return value), not a side-channel file. Do not go idle or " \
   "finish silently. The report carries a common envelope: role, intent id, stage, " \
   "status (delivered or blocked), artifacts written, verification or tests run, " \
-  "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
+  "checklist deltas, deviations from spec, blockers or handoff notes, and an " \
+  "insights field carrying 0..N durable nuggets (what I discovered worth keeping, " \
+  "the most interesting residue of this turn; none if there were none); plus a " \
   "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
-  "(for example the planner explains the plan back to the orchestrator). See " \
-  "skills/auto/references/agent-report-contract.md for the per-role format."
+  "(for example the planner explains the plan back to the orchestrator). Populate " \
+  "the insights field even when you cannot write the intent file yourself: a " \
+  "background or dispatched agent carries each nugget home in the report and the " \
+  "orchestrator persists it via scripts/insight-append, so an insight never " \
+  "depends on the discovering session's file-write access. Keep the report " \
+  "prose-stripped: the envelope and payload only, no greeting, no preamble, " \
+  "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
+  "See skills/auto/references/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil

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

@@ -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):
@@ -75,17 +107,46 @@ Dispatch rule: sequential, one specialist per stage on one branch (the deliverab
 
 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`).
 
+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.