@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/rebuild-graph

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# rebuild-graph — repair the store-wide sources/chain frontmatter graph across the
+# global, plastic, and knowdb stores (intent 49). Deterministic, idempotent, and
+# one-directional (intent 68 I-invariants): dedupe, I3 (formative edge wins), I1
+# in-store backlinks, I2 preserved; cross-store refs resolved via a multi-hop
+# relocation map (relocation wins over coincidental id reuse). Emits a
+# before/after audit, then writes minimal style-preserving frontmatter.
+#
+# Usage:
+#   rebuild-graph [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#
+# Pure-Ruby (no bash). The pure logic lives in lib/graph_rebuild.rb and
+# lib/frontmatter_writer.rb; this shell does only discovery, IO, and reporting.
+# Never pushes ~/.plastic (no git ops here).
+
+require "yaml"
+require "date"
+require "time"
+require "fileutils"
+
+require_relative "lib/graph_rebuild"
+require_relative "lib/frontmatter_writer"
+require_relative "lib/intent_validator"
+
+class RebuildGraph
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  # The 49 intent dir audit destination (relative to plastic_home).
+  DEFAULT_AUDIT_REL =
+    "projects/plastic/store/49--store-wide-double-link-symmetry/resources/audit--graph-rebuild.md"
+
+  KIND_LABELS = {
+    dedupe: "Dedupes",
+    i3: "I3 resolutions (kept in sources, dropped from chain)",
+    repoint: "Cross-store repoints",
+    collapse: "Cross-store collapses (to bare same-store id)",
+    drop: "Dropped dead refs",
+    i1_backlink: "I1 backlinks added",
+  }.freeze
+
+  KIND_ORDER = %i[dedupe i3 repoint collapse drop i1_backlink].freeze
+
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
+    @plastic_home = plastic_home
+    @dry_run = dry_run
+
+    # A dry run must NOT stomp the canonical audit (the spec/checklist tell humans
+    # to run --dry-run to review the plan). When no explicit --audit-path is given,
+    # a dry run writes to a distinct `.dry-run.md` sibling, leaving the canonical
+    # real-run audit untouched. An explicit --audit-path is always honored verbatim
+    # (it is the caller's responsibility, and tests inject it).
+    canonical = File.join(plastic_home, DEFAULT_AUDIT_REL)
+    @audit_path =
+      if audit_path
+        audit_path
+      elsif dry_run
+        canonical.sub(/\.md\z/, ".dry-run.md")
+      else
+        canonical
+      end
+  end
+
+  attr_reader :plastic_home, :dry_run, :audit_path
+
+  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  # `root` is the dir holding INDEX.md; `store` is the intents dir.
+  def stores
+    list = []
+    global_store = File.join(plastic_home, "store")
+    list << { key: "global", root: plastic_home, store: global_store,
+              index: File.join(plastic_home, "INDEX.md") } if File.directory?(global_store)
+
+    %w[plastic knowdb].each do |slug|
+      root = File.join(plastic_home, "projects", slug)
+      store = File.join(root, "store")
+      next unless File.directory?(store)
+
+      list << { key: "project:#{slug}", root: root, store: store,
+                index: File.join(root, "INDEX.md") }
+    end
+    list
+  end
+
+  # { id => { sources:, chain:, path: } } for one store.
+  def load_nodes(store_dir)
+    nodes = {}
+    Dir.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
+
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes[fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        path: md,
+      }
+    end
+    nodes
+  end
+
+  def run
+    store_list = stores
+    nodes_by_store = {}
+    index_texts = {}
+    store_index = {}
+
+    store_list.each do |s|
+      nodes_by_store[s[:key]] = load_nodes(s[:store])
+      index_texts[s[:key]] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+      store_index[s[:key]] = nodes_by_store[s[:key]].keys
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(index_texts)
+
+    results = {}
+    store_list.each do |s|
+      key = s[:key]
+      input = nodes_by_store[key].transform_values { |v| { sources: v[:sources], chain: v[:chain] } }
+      results[key] = GraphRebuild.rebuild_store(
+        input,
+        referer_store: key,
+        relocation_map: relocation_map,
+        store_index: store_index
+      )
+    end
+
+    write_back(store_list, nodes_by_store, results) unless dry_run
+    emit_audit(store_list, nodes_by_store, results)
+
+    results
+  end
+
+  # Write changed frontmatter back via the minimal style-preserving writer.
+  def write_back(store_list, nodes_by_store, results)
+    store_list.each do |s|
+      key = s[:key]
+      new_nodes = results[key][:nodes]
+      nodes_by_store[key].each do |id, original|
+        rebuilt = new_nodes[id]
+        next if rebuilt.nil?
+        next if rebuilt[:sources] == original[:sources] && rebuilt[:chain] == original[:chain]
+
+        content = File.read(original[:path])
+        updated = FrontmatterWriter.rewrite_arrays(content,
+                                                   sources: rebuilt[:sources],
+                                                   chain: rebuilt[:chain])
+        File.write(original[:path], updated) if updated != content
+      end
+    end
+  end
+
+  # Render the audit and write it (always, even in dry-run, so the human reviews
+  # the dry-run plan). Returns the rendered string.
+  def emit_audit(store_list, _nodes_by_store, results)
+    text = render_audit(store_list, results)
+    FileUtils.mkdir_p(File.dirname(audit_path))
+    File.write(audit_path, text)
+    text
+  end
+
+  # PURE-ish formatter (string from results). Per-store, grouped by kind.
+  def render_audit(store_list, results)
+    total = store_list.sum { |s| results[s[:key]][:changes].size }
+    lines = []
+    lines << "# Audit: store-wide sources/chain graph rebuild (intent 49)"
+    lines << ""
+    lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
+    lines << ""
+    lines << "Total changes across all stores: #{total}"
+    lines << ""
+
+    store_list.each do |s|
+      key = s[:key]
+      changes = results[key][:changes]
+      lines << "## #{key}"
+      lines << ""
+      if changes.empty?
+        lines << "No changes."
+        lines << ""
+        next
+      end
+
+      KIND_ORDER.each do |kind|
+        group = changes.select { |c| c[:kind] == kind }
+        next if group.empty?
+
+        lines << "### #{KIND_LABELS[kind]} (#{group.size})"
+        group.each { |c| lines << "- #{format_change(c)}" }
+        lines << ""
+      end
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def format_change(c)
+    case c[:kind]
+    when :dedupe
+      "#{c[:intent]}: sources #{c[:before][:sources].inspect} → #{c[:after][:sources].inspect}, " \
+        "chain #{c[:before][:chain].inspect} → #{c[:after][:chain].inspect}"
+    when :i3
+      "#{c[:intent]}: #{c[:before]} kept in sources, dropped from chain"
+    when :repoint
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (relocated cross-store)"
+    when :collapse
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (collapsed to bare same-store id)"
+    when :drop
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} dropped (resolves nowhere)"
+    when :i1_backlink
+      "#{c[:intent]}.chain += #{c[:backlink]} (formative backlink)"
+    else
+      c.inspect
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  home = RebuildGraph::DEFAULT_HOME
+  dry = false
+  audit = nil
+  i = 0
+  while i < ARGV.length
+    case ARGV[i]
+    when "--plastic-home" then home = ARGV[i + 1]; i += 2
+    when "--dry-run" then dry = true; i += 1
+    when "--audit-path" then audit = ARGV[i + 1]; i += 2
+    else i += 1
+    end
+  end
+
+  tool = RebuildGraph.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  results = tool.run
+  total = results.values.sum { |r| r[:changes].size }
+  puts "rebuild-graph #{dry ? "DRY RUN" : "applied"}: #{total} change(s) across #{results.size} store(s)."
+  puts "Audit: #{tool.audit_path}"
+end

package/scripts/spawn-preamble

@@ -29,7 +29,30 @@ require_relative "lib/bridge"
 HONOR_INSTRUCTION =
   "You are operating inside Plastic. Use it as your operating scaffold. " \
   "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
-  "Your output is a deliverable, not a message."
+  "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
+
+# Verbatim completion-report contract (intent 74). Kept as one constant so the
+# contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
+# and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
+# report wording: the work output is lifecycle artifacts, the final message is a
+# structured report about them. Both are required and they do not contradict.
+REPORT_CONTRACT =
+  "Before you finish, END your turn with a structured completion report as your " \
+  "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, 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). 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
@@ -116,6 +139,8 @@ lines << "Current stage: #{stage}"
 lines << "Cycle step / role: #{cycle}"
 lines << ""
 lines << HONOR_INSTRUCTION
+lines << ""
+lines << REPORT_CONTRACT
 lines << "=== end preamble ==="
 
 puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -28,6 +28,13 @@ Work `dispatchable_queue` in `rank` order (these are `defer`/`research` disposit
 safe to deliver autonomously). Leave `human_only` and `next_big_thing` for the user — those
 are `drive`/`triage` items the human should lead. See the `plastic-dashboard` skill.
 
+QMD-first (when available): when the user describes the work to deliver rather than naming an
+intent, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
+intents, then open the authoritative intent file for the hit you take over. The command is a no-op
+when QMD is absent, so fall back to the existing INDEX.md / file scan. (This is discovery; the
+reindex step under Completion is separate.)
+
 ## Arm the Lifecycle Gate (do this FIRST)
 
 Immediately after selecting the intent — before any other work — arm auto mode. This
@@ -36,13 +43,18 @@ 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`. `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.
 
 **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.
@@ -68,15 +80,29 @@ 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`).
 
+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).
+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 |
 |---|---|
@@ -182,20 +208,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. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+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:
    ```bash
-   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Delivery is the lifecycle event that keeps the search index fresh. `<store-root>` is the
+   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):
    ```bash
-   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"])'
    ```
    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.
+
+   **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 (step 4 above, 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.
 10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling

package/skills/auto/evals/evals.json

@@ -202,6 +202,54 @@
           "result": "pass"
         }
       ]
+    },
+    {
+      "id": 12,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "A power-tool is present (qmd on PATH, or a .serena marker / serena on PATH). A substantive prompt arrives in auto mode.",
+      "expected_output": "The UserPromptSubmit power-tools hook appends a MANDATORY obligation per present tool: a MUST-use-QMD line when qmd is present (to check for an existing or related intent before treating work as new), and a MUST-use-Serena line when serena is present (symbolic tools before grep/Read). QMD hits are still injected when above threshold.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns MUST/MANDATORY lines for each present tool; QmdHook.run appends the mandate",
+          "observed": "power_tools_test.rb + qmd_hook_test.rb assert MUST wording; serena line gated on the serena detector",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Neither qmd nor serena is present (no qmd on PATH, no .serena marker, no serena on PATH). A substantive prompt arrives.",
+      "expected_output": "Detect-then-degrade: the hook emits nothing (silent no-op, exit 0). No mandate text appears. Nothing is required to install.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns nil and QmdHook.run returns nil when neither tool is present",
+          "observed": "power_tools_test.rb test_mandate_neither_is_nil + qmd_hook_test.rb test_nil_when_neither_tool_present",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. In auto mode the user says: deliver the work on the uploader retry policy (no intent id given).",
+      "expected_output": "Before scanning the store with grep/Read to find the matching intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"uploader retry policy\"` to surface the candidate intent, then opens the authoritative intent file for the hit it takes over. This discovery step is distinct from the completion-time reindex step. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read during discovery; authoritative file opened for the hit; reindex step stays separate",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
     }
   ]
 }

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

@@ -61,6 +61,26 @@ and not hallucinate intents or stages. This is the standard L2 live-state mechan
 for harnesses whose spawned sub-agents do not inherit the top-level session event. See
 `docs/reference/harness-adapters.md` for how it slots into the per-harness contract.
 
+### Completion Reports
+
+Every dispatched specialist ends its turn with a structured completion report as its final
+message (its return value), so the agent that did the work is the one that accounts for it. The
+report carries a common envelope plus a role-specific payload that fulfils the agent's place in
+the cycle; the planner explains the plan back to the orchestrator, the executor reports what was
+built and the test result, and so on. The format lives in `references/agent-report-contract.md`,
+and the verbatim instruction is injected once via the spawn preamble's `REPORT_CONTRACT`
+constant, which the role prompts reproduce.
+
+Enforcement is require-report then synthesize-fallback. The preamble and prompts make the report
+mandatory (decision-shaping), but child-agent honor is best-effort across harnesses (Tier B/C),
+so it is never a hard block. When a specialist returns no usable report, the enforcer runs
+`scripts/agent-report <intent_dir> --role <role>`, a pure function of the intent dir (no network,
+clock, or randomness, mirroring `spawn-preamble`) that emits a filesystem-derived report from the
+savepoint, the artifacts present, the checklist checked/total, and the outcome line. A handoff
+account therefore always exists: agent-authored when present, deterministically reconstructed
+otherwise. This structures the finish notification only; in-flight observations stay in
+`## Insights`, no progress chatter is added.
+
 ### Gate Ownership
 
 The enforcer arms and verifies the lifecycle gate, then gates every stage transition.
@@ -70,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

@@ -0,0 +1,121 @@
+# Agent Completion Report Contract
+
+Every agent dispatched by the auto-mode enforcer MUST end its turn with a structured
+completion report. This doc defines that report: one common envelope plus a per-role payload.
+It is the format the `REPORT_CONTRACT` constant in `scripts/spawn-preamble` points at, the
+role prompts (`agents/plastic-*.md`) reproduce, and the deterministic fallback
+(`scripts/agent-report`) approximates. Keep all four in agreement; the constant in
+`scripts/spawn-preamble` is the single source of truth for the injected wording.
+
+## Purpose
+
+The report is the agent's FINAL MESSAGE (its return value), not a side-channel file. Every
+harness hands a spawned agent's final text back to the dispatcher, so the final message is the
+one carrier that works everywhere (decision D1). The report structures the FINISH notification
+only. In-flight observations still go in `## Insights`; the report does not add progress chatter
+(decision D5). An agent that finishes correct artifacts but goes idle without a report has not
+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:
+
+- **Role**: which specialist produced this (brainstorming, spec, planner, executor, reviewer).
+- **Intent id and stage**: the active intent id and the cycle stage just completed.
+- **Status**: `delivered` or `blocked`.
+- **Artifacts written**: the files produced or changed (store paths, and project paths for the
+  executor).
+- **Verification / tests run**: the command run and its result, or `n/a` for stages that write
+  no code.
+- **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
+
+Each role appends a payload that fulfils its place in the What, Why, How, Exec cycle (decision
+D2). The payload is what makes the report useful to the orchestrator beyond the envelope.
+
+### brainstorming (Why exploration)
+- 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:
+- 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: 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 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
+
+Decision-shaping (the preamble plus these prompts) makes the report mandatory, but child-agent
+honor is best-effort across harnesses (Tier B/C in `docs/reference/harness-adapters.md`), so the
+contract is never a hard block (decision D3). When a dispatched agent returns no usable report
+(it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), the
+enforcer synthesizes one:
+
+```
+scripts/agent-report <intent_dir> --role <role>
+```
+
+`scripts/agent-report` is a pure function of the intent directory (no network, clock, or
+randomness, mirroring `scripts/spawn-preamble`): it reads the current stage from the savepoint
+ledger, the lifecycle artifacts present, the checklist checked / total, and the `## Outcome`
+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/brainstorming/SKILL.md

@@ -74,6 +74,7 @@ digraph brainstorming {
 ## The Process
 
 **Understanding the idea:**
+- QMD-first (when available): before scanning the store with grep/Read for prior decisions, specs, or outcomes, run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents, then open the authoritative intent file for any hit you act on. The command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
 - Check out the current project state first (files, docs, recent commits)
 - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
 - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.

package/skills/brainstorming/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-brainstorming",
+  "notes": "Intent 66a. Spec for the QMD-first step in the Why/explore-context phase (surface prior decisions/specs/outcomes before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. Brainstorming the active intent during the Why phase, the agent needs prior decisions and specs on caching.",
+      "expected_output": "In the explore-project-context (Why) step, before scanning the store with grep/Read, runs `ruby ~/.plastic/scripts/qmd-sync search \"caching decisions\"` to surface prior decisions, specs, or outcomes, then opens the authoritative intent file for any hit it acts on. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run during Why before grep/Read; authoritative file opened for any hit",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}