@zalom/plastic 1.8.0 → 1.10.0

package/scripts/restore-intent-v1

@@ -6,9 +6,10 @@
 # while preserving its frontmatter GRAPH (sources/chain) as a target-resolved
 # union of the v1 snapshot and the current snapshot (intent 193). This is the
 # ONLY sanctioned way to restore a completed intent to v1; a hand-run whole-file
-# `git checkout`/revert is forbidden (see PLASTIC.md > Terminal immutability),
-# because it cannot tell prose from graph metadata and silently destroys
-# backlinks written after v1 (the 124/131 incident this tool exists to prevent).
+# `git checkout`/revert is forbidden (see plastic-conventions > references/maintenance-and-revisions.md,
+# WORK vs MAINTENANCE and its Restore-to-v1 paragraph), because it cannot tell prose from graph
+# metadata and silently destroys backlinks written after v1 (the 124/131 incident this tool
+# exists to prevent).
 #
 # Usage:
 #   restore-intent-v1 <intent-id> --at <git-ref> [--plastic-home PATH] [--apply] \
@@ -19,12 +20,14 @@
 # class of tool already destroyed live store data once. --apply is required to
 # write.
 #
-# Restore-to-v1 runs under the MAINTENANCE lock (PLASTIC.md > Terminal
-# immutability: the maintenance lock covers sanctioned structural move-and-record
-# edits after completion). This tool does NOT acquire, check, or manage that
-# lock itself (fail-open doctrine, intent 111: lock management is the
-# orchestrator's job, never built into a CLI as a trap); it only prints a
-# one-line reminder on --apply.
+# There is exactly one lock in Plastic, `delivery.lock`, and MAINTENANCE (this tool included)
+# never acquires or checks it: WORK vs MAINTENANCE (plastic-conventions >
+# references/maintenance-and-revisions.md) holds the corrected doctrine after intent 112's
+# proposed second "maintenance.lock" was abandoned before merge and never shipped. This tool does
+# NOT acquire, check, or manage `delivery.lock` itself (fail-open doctrine, intent 111: lock
+# management is the orchestrator's job, never built into a CLI as a trap); it only prints a
+# one-line reminder on --apply that the target intent must be terminal, which the caller is
+# responsible for confirming before running with --apply.
 #
 # LINKS BLAST RADIUS: an applied restore reprojects `## Links` via
 # scripts/project-links, which is a STORE-WIDE operation with no per-intent
@@ -142,8 +145,10 @@ class RestoreIntentV1CLI
     File.write(md_path, new_md) if md_changed
     other_files.each { |f, content| File.write(File.join(dir, f), content) }
 
-    puts "Reminder: restore-to-v1 runs under the maintenance lock (PLASTIC.md > Terminal " \
-         "immutability). Confirm the maintenance lock is held before this --apply."
+    puts "Reminder: restore-to-v1 is MAINTENANCE, not WORK (plastic-conventions > " \
+         "references/maintenance-and-revisions.md, WORK vs MAINTENANCE). There is no " \
+         "maintenance lock to hold; confirm the target intent is terminal (Completed or " \
+         "Abandoned) with no fresh delivery.lock before this --apply."
 
     handle_links_reprojection(base)
     append_revision(dir, base, graph, files: prose_changes,
@@ -266,7 +271,7 @@ class RestoreIntentV1CLI
 
   def reproject_links
     project_links = File.expand_path("project-links", __dir__)
-    system(RbConfig.ruby, project_links, "--plastic-home", plastic_home)
+    system({"RUBYOPT" => nil}, RbConfig.ruby, project_links, "--plastic-home", plastic_home)
     return if $?.success?
 
     warn "restore-intent-v1: ## Links may now be stale (project-links reprojection failed). " \

package/scripts/scaffold-intent

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# scaffold-intent (intent 213) - one CLI, three subcommands, each writes one lifecycle
+# artifact by copying or mechanically deriving it from an already-committed source. Every
+# field it writes is a verbatim copy or a mechanical derivation (a `git diff --stat`, a
+# supplied file's contents) of an already-committed artifact; no subcommand interprets or
+# invents prose. A field it cannot derive mechanically is left as the template's own stub
+# text instead of being guessed at.
+#
+# Usage:
+#   scaffold-intent spec|checklist|outcome --store <path> --id <intent_id> [--force]
+#     [--test-summary <path>]   (outcome subcommand only)
+#
+# Subcommand is the first positional argument. --store and --id are required for every
+# subcommand. --test-summary is valid only on the outcome subcommand; on spec or
+# checklist, or naming a path that does not exist, it is a usage error (exit 1). No other
+# flags exist: --store, --id, --force, and --test-summary (outcome only) are the whole
+# shipped surface (D5, a one-way door).
+#
+# Exit codes:
+#   0  scaffolded
+#   1  usage or path-resolution failure
+#   2  refused to overwrite real content without --force
+#   3  a prerequisite committed artifact is missing or still sentinel
+#
+# The actions/ rule (intent 133a, D11): scaffold-intent does not scaffold actions/ in any
+# form. Actions require judgment and stay entirely with the planner. No subcommand
+# creates the directory, writes a .gitkeep, or writes a sentinel-only ACTION_*.md.
+#
+# outcome is an end-of-Exec step. Run it once the diff and the test summary exist, right
+# before plastic-intent-ending writes the narrative. Writing outcome.md makes the intent
+# read as Done to the statusline and to any stage-derived display (Bridge.derive_stage
+# keys on outcome.md's presence). This does NOT purge a bridge:
+# Bridge.purge_done_bridges keys on INDEX Active status plus lock presence, never on the
+# derived stage.
+
+require_relative "lib/scaffold_intent"
+
+SUBCOMMANDS = %w[spec checklist outcome].freeze
+
+def parse_args(argv)
+  opts = { subcommand: nil, store: nil, id: nil, force: false, test_summary: nil }
+  args = argv.dup
+  opts[:subcommand] = args.shift
+
+  i = 0
+  while i < args.length
+    arg = args[i]
+    case arg
+    when "--store"        then opts[:store] = args[i += 1]
+    when "--id"            then opts[:id] = args[i += 1]
+    when "--force"         then opts[:force] = true
+    when "--test-summary"  then opts[:test_summary] = args[i += 1]
+    else
+      usage_abort("unknown argument #{arg.inspect}")
+    end
+    i += 1
+  end
+  opts
+end
+
+def usage
+  "usage: scaffold-intent spec|checklist|outcome --store <store_path> --id <intent_id> " \
+    "[--force] [--test-summary <path>]"
+end
+
+def usage_abort(message)
+  warn "scaffold-intent: #{message}"
+  warn usage
+  exit 1
+end
+
+def main(argv)
+  opts = parse_args(argv)
+
+  usage_abort("subcommand must be one of #{SUBCOMMANDS.join('|')}") unless SUBCOMMANDS.include?(opts[:subcommand])
+  usage_abort("--store is required") if opts[:store].nil? || opts[:store].empty?
+  usage_abort("--id is required") if opts[:id].nil? || opts[:id].empty?
+  if opts[:test_summary] && opts[:subcommand] != "outcome"
+    usage_abort("--test-summary is valid only on the outcome subcommand")
+  end
+
+  store = ScaffoldIntent.expand(opts[:store])
+  usage_abort("store dir does not exist: #{store}") unless Dir.exist?(store)
+
+  intent_dir, err = ScaffoldIntent.resolve_intent_dir(store, opts[:id])
+  usage_abort(err) if intent_dir.nil?
+
+  test_summary_path = nil
+  if opts[:test_summary]
+    test_summary_path = ScaffoldIntent.expand(opts[:test_summary])
+    usage_abort("--test-summary path does not exist: #{test_summary_path}") unless File.exist?(test_summary_path)
+  end
+
+  result =
+    case opts[:subcommand]
+    when "spec"
+      ScaffoldIntent.scaffold_spec(intent_dir: intent_dir, force: opts[:force])
+    when "checklist"
+      ScaffoldIntent.scaffold_checklist(intent_dir: intent_dir, force: opts[:force])
+    when "outcome"
+      ScaffoldIntent.scaffold_outcome(intent_dir: intent_dir, force: opts[:force], store: store,
+                                      id: opts[:id], test_summary: test_summary_path)
+    end
+
+  if result[:message]
+    if result[:code] == 0
+      puts result[:message]
+    else
+      warn "scaffold-intent: #{result[:message]}"
+    end
+  end
+  puts result[:path] if result[:path]
+
+  exit result[:code]
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/start-intent

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# start-intent (intent 213, group 2) - board a session onto an intent: arm the delivery
+# lock, then print a read-only resume-station report.
+#
+# Usage:
+#   start-intent --store <path> --id <intent_id> --mode auto|guided [--session <session_id>]
+#
+# --store, --id, and --mode are required. --session is optional and defaults to
+# CLAUDE_CODE_SESSION_ID, matching end-intent's resolution order. No other flags exist.
+#
+# Steps performed:
+#   0. Resolve inputs: the intent dir, the intent name from frontmatter (falling back to
+#      the dir basename), the calling session (--session, else CLAUDE_CODE_SESSION_ID,
+#      else nil; deliberately no lock-owner fallback), and harness/thread from
+#      CODEX_THREAD_ID / CLAUDE_CODE_SESSION_ID (mirroring skills/auto/SKILL.md's arming
+#      snippet).
+#   1. Pre-flight lock read (read-only): refuse a fresh foreign lock, an unparseable
+#      lock, or a lock present with no resolvable session identity. A stale foreign lock
+#      falls through to arming, which arbitrates it itself.
+#   2. Arm: Bridge.arm_auto (--mode auto) or Bridge.arm_guided (--mode guided). Nothing
+#      else acquires anything.
+#   3. Print the resume-station report (read-only): which lifecycle files are real, and
+#      where the intent should resume (Why/How/Exec/Done).
+#
+# This script never releases and never takes over a lock: it never calls the Lock
+# module's release or takeover operations (parked intent 254's territory). A held or
+# corrupt lock is reported and refused, never repaired.
+#
+# Exit codes:
+#   0  armed and resume-station printed
+#   1  usage or path-resolution failure
+#   3  lock held by another live session (deny, mirrors end-intent's pre-flight refusal)
+#   4  unparseable lock, or no session identity with a lock present
+#
+# There is deliberately no exit 2 in this script's contract.
+
+require_relative "lib/start_intent"
+
+def parse_args(argv)
+  opts = { store: nil, id: nil, mode: nil, session: nil }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--store"   then opts[:store] = argv[i += 1]
+    when "--id"      then opts[:id] = argv[i += 1]
+    when "--mode"    then opts[:mode] = argv[i += 1]
+    when "--session" then opts[:session] = argv[i += 1]
+    else
+      usage_abort("unknown argument #{arg.inspect}")
+    end
+    i += 1
+  end
+  opts
+end
+
+def usage
+  "usage: start-intent --store <store_path> --id <intent_id> --mode auto|guided " \
+    "[--session <session_id>]"
+end
+
+def usage_abort(message)
+  warn "start-intent: #{message}"
+  warn usage
+  exit 1
+end
+
+def main(argv)
+  opts = parse_args(argv)
+
+  codex_thread_id = ENV["CODEX_THREAD_ID"]
+  claude_session_id = ENV["CLAUDE_CODE_SESSION_ID"]
+  detected = StartIntent.resolve_harness(codex_thread_id, claude_session_id)
+
+  result = StartIntent.run(
+    store: opts[:store], id: opts[:id], mode: opts[:mode], session: opts[:session],
+    env_session: claude_session_id, harness: detected[:harness], thread: detected[:thread]
+  )
+
+  Array(result[:stderr]).each { |line| warn line }
+  warn usage if result[:exit_code] == StartIntent::EXIT_USAGE
+  Array(result[:stdout]).each { |line| puts line }
+  exit result[:exit_code]
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/verify-intent

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# verify-intent (intent 213) - bundles the checks that need no project-specific knowledge
+# into one verdict: the per-intent doctor scan, an added-line em-dash diff guard, a
+# diffstat, and an optional caller-supplied suite command.
+#
+# Usage:
+#   verify-intent --store <path> --id <intent_id> [--base <ref>] [--suite <command>]
+#
+# --base overrides the auto-detected diff base (default: the merge base with the repo's
+# detected default branch) for repos where detection is ambiguous. --suite is an optional
+# caller-supplied command to run (in the repo directory) and fold into the verdict. No
+# other flags exist.
+#
+# Checks, all run every invocation (the fourth only when --suite is given):
+#   1. doctor    - Doctor#run_intent_check(id, store: scope), fail-open on a crash
+#   2. em-dash   - added lines only of `git diff <base>...HEAD`, never the whole tree
+#   3. diffstat  - `git diff --stat <base>...HEAD`, never a failure on its own
+#   4. suite     - the supplied --suite command, run with RUBYOPT cleared
+#
+# Every check runs, then the run exits on the LOWEST-numbered failure that occurred, so one
+# invocation gives the full picture on stdout even when several checks fail.
+#
+# Exit codes:
+#   0  every check passed
+#   1  usage or path-resolution failure
+#   2  doctor reported an issue
+#   3  the em-dash guard found a violation on an added line
+#   4  the supplied --suite command exited non-zero
+
+require_relative "lib/verify_intent"
+
+def parse_args(argv)
+  opts = { store: nil, id: nil, base: nil, suite: nil }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--store" then opts[:store] = argv[i += 1]
+    when "--id"    then opts[:id] = argv[i += 1]
+    when "--base"  then opts[:base] = argv[i += 1]
+    when "--suite" then opts[:suite] = argv[i += 1]
+    else
+      usage_abort("unknown argument #{arg.inspect}")
+    end
+    i += 1
+  end
+  opts
+end
+
+def usage
+  "usage: verify-intent --store <path> --id <intent_id> [--base <ref>] [--suite <command>]"
+end
+
+def usage_abort(message)
+  warn "verify-intent: #{message}"
+  warn usage
+  exit 1
+end
+
+def main(argv)
+  opts = parse_args(argv)
+  usage_abort("--store is required") if opts[:store].nil? || opts[:store].empty?
+  usage_abort("--id is required") if opts[:id].nil? || opts[:id].empty?
+
+  verdict = VerifyIntent.run(store: opts[:store], id: opts[:id], base: opts[:base], suite: opts[:suite])
+  verdict[:lines].each { |line| puts line }
+  exit verdict[:exit_code]
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/skills/agent-advisor/SKILL.md

@@ -39,12 +39,12 @@ a session.
 
 ## Routing: which advisor answers
 
-1. Read the harness-scoped config: `advisor.claude.default`. If unset, fall back to
-   `advisor.claude.secondary`, then to `plastic-faux-advisor`.
+1. Read the harness-scoped config: `advisor.claude.default`, the only advisor routing key
+   the installer writes. If unset, use `plastic-advisor`, the shipped default.
 2. If the user names which advisor they want ("ask the real one", "use Fable", "ask the
-   cheap one"), honor that directly and dispatch `advisor.claude.primary` (default
-   `plastic-advisor`) or `advisor.claude.secondary` (default `plastic-faux-advisor`)
-   accordingly, overriding step 1 for this consultation only.
+   cheap one"), honor that directly and dispatch `plastic-advisor` (the real advisor) or
+   `plastic-faux-advisor` (the cheaper imitation) accordingly, overriding step 1 for this
+   consultation only.
 3. If `advisor.enabled` reads `false`, neither advisor agent nor this skill is
    installed; this step should not be reachable, but if it is, tell the user the
    advisor is disabled and point at "Setting the default" below.

package/skills/auto/SKILL.md

@@ -27,7 +27,7 @@ Claude Code).
 
 An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic-intent-creating."
 
-If multiple active intents exist, ask the user which one to deliver (this is the only question auto asks).
+If multiple active intents exist, ask the user which one to deliver (the one question auto asks at boarding, before delivery starts).
 
 **Picking work when no intent is specified.** If the user says "auto" without naming an
 intent and none is active, consult the roadmap first (the primary planning surface), then
@@ -75,15 +75,26 @@ and artifact depth to that size. Extended walkthrough: `references/tiers.md`.
    place, under the same gate.
 3. **Per-tier topology.** S/M: one thinker agent, one boot, two stations, sonnet
    executor; the thinker writes at least one real action file (one consolidated
-   `actions/ACTION_1.md`), never an empty `actions/`. S may also skip the QMD discovery
-   deposit when chain and sources are both empty. L: today's full team (`## Team Spin-Up`
-   below), one `actions/ACTION_N.md` per task.
+   `actions/ACTION_1.md`), never an empty `actions/`. That executor runs as ONE dispatch
+   for the whole consolidated action, with no per-task two-stage review loop
+   (`plastic-intent-executing` holds that gate). S cuts two more things: it skips the QMD
+   discovery deposit when chain and sources are both empty AND a size of S is already on
+   record (a stamped `Tier: S` line in spec.md), which a first activation does not have,
+   and it sends ONE mid-flight owner briefing, at How. M and L send all four. L: today's
+   full team (`## Team Spin-Up` below), one `actions/ACTION_N.md` per task, and a per-task
+   implementer plus two-stage review.
 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.
+   orchestrator, never validated by any gate or by doctor. A separate
+   `Settled: yes (<reason>)` line may sit directly beneath the `Tier:` line; an absent
+   line means not settled, and settledness is independent of scope.
+
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing, agent-model
+config, advisor routing, and the auto-mode human report contract behind the sizing above. This
+path resolves relative to this skill's own installed directory.
 
 ## Arm the Lifecycle Gate (do this FIRST)
 
@@ -110,6 +121,9 @@ implies for later tool calls) read `references/end-tail.md`.
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
 Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.md) → Exec.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger behind the arming above.
+
 ## Flags
 
 - `--skip-permissions` - bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
@@ -130,7 +144,7 @@ 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-intent-executing`) 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, 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`).
+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 [`harness-adapters.md`](https://github.com/zalom/plastic/blob/main/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,
 unless an explicit `agents.models.<name>` config override names Fable for that role, in which
@@ -210,9 +224,9 @@ Filesystem fallback (ledger missing only):
 
 Announce which stage you're entering and why.
 
-Notify user (What briefing): brief per `references/human-report-contract.md`
+Notify user (What briefing, M and L only): 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).
+this is worth doing, or proceed). At S this briefing does not fire; the How briefing carries it.
 
 ## Why Completion (Autonomous)
 
@@ -228,9 +242,10 @@ 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`
+8. Notify user (Why briefing, M and L only): 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).
+   needed, approve or pick an option). At S this briefing does not fire; the How briefing
+   carries it.
 
 Then proceed to How.
 
@@ -246,9 +261,12 @@ one consolidated `actions/ACTION_1.md`, L writes one `actions/ACTION_N.md` per t
 2. Otherwise, write `plan.md` directly - implementation plan with numbered tasks
 3. Write at least one real `ACTION_N.md` into the existing `actions/` directory, self-contained (S/M: one consolidated `ACTION_1.md`; L: one per task)
 4. Write `checklist.md` - execution registry with checkboxes covering all actions
-5. Notify user (How briefing): brief per `references/human-report-contract.md`
+5. Notify user (How briefing, every tier): 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).
+   dependency; Call: approve the plan to build). At S this is the ONE mid-flight briefing:
+   fold into the same three lines what the What and Why briefings would have said (the work
+   picked up, the approach chosen), and send it here, with the plan ready and before any
+   code is written.
 
 Then proceed to Exec.
 
@@ -257,7 +275,7 @@ Then proceed to Exec.
 If the plan calls for creating a new project (the intent is an implementation intent that needs a new codebase):
 
 1. Determine project path from `~/.plastic/config.yml` `project_roots` or from intent context
-2. **Confirm path with user** - this is the ONE human interaction during auto delivery:
+2. **Confirm path with user** - the one human interaction added mid-delivery, and only when this gate fires:
    > "Creating project `<slug>` at `<path>`. Confirm path, or provide alternative."
 3. Invoke `plastic-project-creating` skill
 4. The global intent is now Completed (creating-project handles this)
@@ -272,9 +290,10 @@ 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`
+7. Notify user (Exec briefing, M and L only): 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).
+   Call: go to review, or done). At S this briefing does not fire; the final owner report at
+   End carries what it would have said.
 
 ## Permission Model - Safe-by-Default
 
@@ -303,17 +322,19 @@ During initial project creation, all decisions are non-destructive by definition
 
 ## Completion
 
+Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means and
+the End-stage tail the steps below walk through.
+
 1. Verify all checklist items are checked
-2. Write `outcome.md` with detailed results, from `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md`.
+2. Write `outcome.md` with detailed results, from `~/.plastic/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).
-   2. Read `~/.plastic/projects/{slug}/project.yml`. If the file doesn't exist or has no `release` key, skip to step 5.
+3. **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 4 (default commit-only behavior).
+   2. Read `~/.plastic/projects/{slug}/project.yml`. If the file doesn't exist or has no `release` key, skip to step 4.
    3. Based on `release.on_complete`:
-      - `commit` - git add + commit (same as default, proceed to step 5)
+      - `commit` - git add + commit (same as default, proceed to step 4)
       - `commit_and_push` - git add + commit + push
       - `manual` - skip auto-commit, notify user: "Release configured as manual - commit when ready."
    4. If `release.verify` is set, run the verify command (e.g. `bundle exec rake test`):
@@ -323,14 +344,15 @@ During initial project creation, all decisions are non-destructive by definition
         - `stop` - write `savepoint.md` with current state, notify user: "Verify failed - savepoint written.", **STOP**
         - `manual` - notify user: "Verify failed: [summary]. Resolve manually."
    5. If `release.on_green` has items, invoke `plastic-releasing` to handle them (tag, changelog, publish, etc.). Do NOT duplicate release logic - delegate entirely.
-5. Review `## Insights` for observations that should spawn future intents. If any:
+4. Review `## Insights` for observations that should spawn future intents. If any:
    - Create them (using `plastic-intent-creating` conventions)
    - Update `chain` in the current intent's frontmatter
-6. Run the mechanical close through `plastic-intent-ending`: it owns steps 1-6 of the Done
-   procedure (outcome/INDEX/savepoint/commit, disarm, and the QMD reindex last) as ONE
-   delegation, not five separate one-liners restated here. `scripts/end-intent` now performs
-   steps 1-5 itself, INCLUDING disarm (worktree release plus clearing `delivery.lock`): a
-   single call closes the intent AND clears its lock, so exit 0 means both are done. Pass
+5. Run the mechanical close through `plastic-intent-ending`: it owns steps 1-7 of the Done
+   procedure (outcome/INDEX/savepoint/commit, disarm, the QMD reindex last, and the single
+   EM-to-CTO owner report) as ONE delegation, not a series of separate one-liners restated
+   here. `scripts/end-intent` now performs steps 1-5 itself, INCLUDING disarm (worktree
+   release plus clearing `delivery.lock`): a single call closes the intent AND clears its
+   lock, so exit 0 means both are done. Pass
    `--session` (this session's id, or rely on the `CLAUDE_CODE_SESSION_ID` fallback) so
    disarm resolves the right bridge, and `--index-note` with a rich Completed/Abandoned entry
    description (mode/tier, what shipped or why abandoned, suite result):
@@ -344,13 +366,11 @@ During initial project creation, all decisions are non-destructive by definition
    lock (back off), 5 means the code worktree is dirty (commit/stash first, or pass
    `--discard-worktree-changes` deliberately), 3 means disarm ran but the lock is still
    present (run `/plastic-doctor check the lock status`), 6 means the structure gate refused
-   (see the named reason on stderr; fix via the owning tool named above, then re-run). Only
-   Step 6 (QMD reindex, async, last) remains a separate action after this call succeeds.
+   (see the named reason on stderr; fix via the owning tool named above, then re-run). Two
+   steps remain as separate actions after this call succeeds: Step 6 (QMD reindex, async,
+   last) and Step 7 (the EM-to-CTO owner report, the single report the owner reads).
    Never leave an orphaned worktree; run `git worktree prune` on a stale reference. If any of
    this ever needs to change, change `plastic-intent-ending`, not this skill.
-7. 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
 

package/skills/auto/evals/evals.json

@@ -208,13 +208,13 @@
       "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.",
+      "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). No search hits are injected: intent 246 removed the per-prompt qmd hit search, so the hook emits the mandate and nothing else.",
       "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",
+          "observed": "power_tools_test.rb + qmd_hook_test.rb assert MUST wording; serena line gated on the serena detector; qmd_hook_test.rb test_no_retrieval_hits_are_ever_injected asserts no hit header for any tool combination",
           "result": "pass"
         }
       ]

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

@@ -59,7 +59,7 @@ savepoint line, else stage derived from which lifecycle files exist), the cycle
 role, and the honoring instruction that the agent must emit valid lifecycle artifacts
 and not hallucinate intents or stages. This is the standard L2 live-state mechanism
 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.
+[`harness-adapters.md`](https://github.com/zalom/plastic/blob/main/docs/reference/harness-adapters.md) for how it slots into the per-harness contract.
 
 ### Completion Reports
 

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

@@ -90,7 +90,7 @@ argument is sound before any code is written.
 ## 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
+honor is best-effort across harnesses (Tier B/C in [`harness-adapters.md`](https://github.com/zalom/plastic/blob/main/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:

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

@@ -1,7 +1,8 @@
 # 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
+(What, Why, How, Exec, Done) in auto mode, at M and L; at S only the How boundary fires (see
+`## Depth at Tier S`). 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.
 
@@ -29,6 +30,23 @@ short. The words can flex to fit the stage.
 - **Done**: State = the delivered impact. Risk = residual risk. Call = the decision left to you
   (merge, release, accept).
 
+## Depth at Tier S
+
+At Tier S in auto mode the mid-flight briefings collapse to one. Only the How briefing fires, and
+it folds in what the What and Why briefings would have said: the work picked up and the approach
+chosen go into its State line. The Exec briefing folds into the final owner report at End. M and L
+send all four. The shape does not change: still State, then Risk, then Call, and the per-stage
+content above still says what each line covers. This is a depth cut, not a new report. A delivery
+still ends with `outcome.md` plus one owner report.
+
+## One report per audience
+
+A delivery produces exactly two artifacts: `outcome.md` (authored by `plastic-intent-ending`)
+and one EM-to-CTO owner report at the End stage. No stage or skill restates a delivery
+already written to `outcome.md`; point at it instead. Skills do not open with a banner that
+names the skill or restates the intent id and name the owner just typed. Announce only what
+the reader cannot already know: an error, a result, a choice with its reason, or a handoff.
+
 ## Boundary vs intent 74
 
 Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
@@ -50,6 +68,7 @@ always-on layer for everything else.
 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
+In auto mode, at M and L the orchestrator still emits the briefing at each boundary, as a running
+EM-to-CTO account. At S only the How briefing fires; see `## Depth at Tier S` above for what it
+folds in. 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).