@zalom/plastic 1.9.0 → 1.10.0

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,22 @@ 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
@@ -137,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
@@ -217,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)
 
@@ -235,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.
 
@@ -253,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.
 
@@ -264,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)
@@ -279,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
 
@@ -314,16 +326,15 @@ Read `../plastic-conventions/references/completion-and-done.md` for what "intent
 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`):
@@ -333,14 +344,15 @@ the End-stage tail the steps below walk through.
         - `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):
@@ -354,13 +366,11 @@ the End-stage tail the steps below walk through.
    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/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).

package/skills/auto/references/tiers.md

@@ -37,15 +37,31 @@ One thinker agent boots ONCE and stays in a single context for two stations:
 
 Then a sonnet executor (a fresh dispatch, this is the one topology split that always
 happens) implements from plan.md + checklist.md, checks off items, appends `## Insights`,
-and drives the suite green, exactly as it does for L.
+and drives the suite green. At S/M that is ONE executor dispatch for the whole consolidated
+action: no per-task implementer, and no per-task spec review or quality review. L keeps the
+per-task loop. The gate lives in `plastic-intent-executing`'s Subagent-Driven workflow,
+which reads the `Tier:` line stamped at the top of spec.md, the authoritative record. The
+arithmetic: an S plan with N tasks costs 3N plus 1 agent boots under the L shape, and 2
+boots under this one.
 
 The independent reviewer still runs at the final gate for S/M, in its own fresh context,
 never the maker. This is on the never-cut list; it does not collapse.
 
+S sends ONE mid-flight owner briefing instead of four. Only the How briefing fires, at the
+point the plan is ready and before any code is written, and it folds in what the What and
+Why briefings would have said; the Exec briefing folds into the final owner report at End.
+M and L send all four. The briefing calls live in `plastic-auto`'s stage sections, and the
+depth note lives in `references/human-report-contract.md`.
+
 S may skip the QMD discovery deposit (normally a `plastic-intent-discovery` pass before
 Why) when the intent's `chain` and `sources` are both empty in frontmatter. With no graph
 edges there is nothing to discover, so the deposit is pure overhead; a one-line context
-note ("no chain/sources, discovery skipped") takes its place.
+note ("no chain/sources, discovery skipped") takes its place, written to
+`resources/discovery--<slug>.md`. Three places implement the skip: the dispatch site in
+`plastic-intent-starting` step 4, the precondition in `plastic-intent-discovering`, and the
+same precondition in the `plastic-intent-discovery` agent file. The skip needs a size already
+on record (a stamped `Tier: S` line in spec.md), and sizing happens at Why, so a first
+activation usually runs the full pass.
 
 ## L topology, unchanged
 
@@ -70,6 +86,12 @@ nothing else depends on it. No frontmatter schema change, no new file, no doctor
 gate check. If a later intent wants doctor or a gate to validate the line, that is a
 separate, explicit follow-up; this system deliberately adds no new operational surface.
 
+Settledness is a separate line, `Settled: yes (<reason>)`, directly beneath the `Tier:` line
+and above the `# Spec:` heading. It records that a design has already done its thinking. An
+absent line means not settled; there is no `Settled: no` form. Settledness and scope are
+independent, so a large intent can be settled without becoming a smaller tier.
+`scripts/lib/spec_header.rb` is the only parser of both lines.
+
 ## Never-cut list, the safety floor
 
 At any tier or mode: the independent reviewer (separate agent, fresh context, never the

package/skills/conventions/references/completion-and-done.md

@@ -38,3 +38,6 @@ directory is frozen. A crash mid-tail is recovered by stale-lock reclaim plus fi
 tail; `doctor` surfaces this as a "stalled completion" (terminal in INDEX but the lock is
 still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
 a done intent is never moved back to `## Active`.
+
+One report per audience: a delivery produces `outcome.md` plus one EM-to-CTO owner report, and
+no other step restates either (see `skills/auto/references/human-report-contract.md`).

package/skills/conventions/references/gates-and-enforcement.md

@@ -4,20 +4,36 @@ This chapter holds the escape-and-logging depth for each transition gate.
 
 #### The gates by name
 
-Each gate guards one thing. All are hard:
+Each gate guards one thing. `scripts/lib/hook_registry.rb` is the single source of truth for
+registration. On the edit path (Write, Edit, NotebookEdit, and MCP structural edits) five
+gates run inside one dispatcher process per write, in this fixed order with the first deny
+winning:
 
-- **create-gate** validates the proposed intent file at What write-time (Write, Edit, and MCP
-  edits), so a malformed or incomplete intent never lands.
-- **gate-check** enforces lifecycle stage order (spec.md before plan.md, the plan triplet before
-  the checklist, all checklist items before outcome.md).
+- **savepoint-pre** appends the `started` savepoint ledger line before a write into an intent
+  directory; it records and never denies.
 - **lock-gate** arbitrates ownership and claims: it admits only the intent's lock owner or a
   registered delegate to write into an active intent directory, and every deny names the
   resolving `plastic-lock` command.
-- **bash-gate** intercepts a write attempted through a bash or interpreter one-liner (a heredoc, a
-  `>` redirect, a `ruby -e` or `python -c` write), so the same rules apply whether an edit goes
-  through the Write tool or a shell. A trailing `# plastic-ok` comment is an auditable escape that
-  lets a deliberate command through, and every use is logged to
-  `~/.plastic/.cache/gate-escapes.log`. The code gate (Write and Edit) carries the identical
-  audited `# plastic-ok` escape, logged to the same file. The escape does not extend to
-  `NotebookEdit` or MCP structural edits: they are still gated, just without an escape hatch.
+- **code-gate** denies a code edit before How is delivered and a code edit outside the
+  provisioned worktree (stage rule or worktree rule, first match wins). It carries the audited
+  `# plastic-ok` escape described under bash-gate.
+- **links-gate** is the write-time belt for the `## Links` contract: hand-written links lines
+  that do not project from the `sources`/`chain` frontmatter are denied.
+- **create-gate** validates the proposed intent file at What write-time (Write, Edit, and MCP
+  edits), so a malformed or incomplete intent never lands.
+
+Alongside the edit-path dispatcher the registry defines:
+
+- **bash-gate** (on the Bash matcher) intercepts a write attempted through a bash or interpreter
+  one-liner (a heredoc, a `>` redirect, a `ruby -e` or `python -c` write), so the same rules
+  apply whether an edit goes through the Write tool or a shell. A trailing `# plastic-ok`
+  comment is an auditable escape that lets a deliberate command through, and every use is
+  logged to `~/.plastic/.cache/gate-escapes.log`. The code gate (Write and Edit) carries the
+  identical audited `# plastic-ok` escape, logged to the same file. The escape does not extend
+  to `NotebookEdit` or MCP structural edits: they are still gated, just without an escape hatch.
+- **gate-check** (PostToolUse on Write and Edit) enforces lifecycle stage order (spec.md before
+  plan.md, the plan triplet before the checklist, all checklist items before outcome.md).
+- **future-intent-check** (UserPromptSubmit) surfaces parked future intents whose keywords match
+  the user's message; like the other prompt-time hooks (continue, auto-arm, power-tools) it
+  informs and never denies.