@zalom/plastic 1.9.0 → 1.10.0

package/skills/conventions/references/locks-and-worktrees.md

@@ -43,7 +43,7 @@ shared one still is.
 The bridge resolves the current session in a fixed precedence: the stdin `session_id` first, then
 the `CLAUDE_CODE_SESSION_ID` environment variable, then a derived key when neither is present. A
 bridge is purge-eligible by terminal state, not by age: it is removed only once its intent is no
-longer active, never on a timer. See `docs/internals.md` for depth.
+longer active, never on a timer. See [`docs/internals.md`](https://github.com/zalom/plastic/blob/main/docs/internals.md) for depth.
 
 The delivery lock arbitrates at the whole-intent grain: it decides who may work
 an intent at all. Underneath it, a per-artifact claim token (intent 111)
@@ -58,7 +58,7 @@ work is unaffected; it engages, and denies, only when a second writer tries to
 take a fresh claim someone else already holds. A stale or corrupt claim fails
 open (the write proceeds, the claim yields) and the condition is surfaced in
 `plastic-lock status`, which lists any live claims alongside the delivery
-lock. See `plastic-lock claim`/`release-claim` and `docs/internals.md` for the
+lock. See `plastic-lock claim`/`release-claim` and [`docs/internals.md`](https://github.com/zalom/plastic/blob/main/docs/internals.md) for the
 full mechanism.
 
 There is exactly one lock in Plastic: `delivery.lock` (exclusive, one owner plus delegates),
@@ -108,6 +108,6 @@ each station.
 | What (create) | `<id>--<slug>.md`, born complete | no lock yet; no bridge | create-gate validates the proposed intent content (Write, Edit, and MCP edits) | savepoint `What` line; intent listed in INDEX `## Active` |
 | Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | gate-check requires the intent file with `## Intent` before spec.md; lock-gate admits only the owner or a delegate | savepoint `Why started`, `Why spec.md created` |
 | How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md, checklist.md, and a real action file all exist | gate-check requires spec.md before plan.md, and plan.md plus a real actions/ACTION_N.md before checklist.md | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
-| Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock; bash, interpreter, and MCP writes gated the same way | code-gate, worktree-gate, bash-gate, lock-gate | checklist boxes; savepoint milestones |
+| Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock; bash, interpreter, and MCP writes gated the same way | the five edit-path gates (savepoint-pre, lock-gate, code-gate with its stage and worktree rules, links-gate, create-gate) plus bash-gate for shell writes | checklist boxes; savepoint milestones |
 | End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the bridge is purge-eligible, and the QMD reindex runs LAST (after purge) | gate-check blocks outcome.md while checklist items are unchecked | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
 | Maintenance (Future, Terminal, or Active-with-a-stale-or-no-lock) | `revisions.md` move-and-record entries | detects (never acquires) `delivery.lock`; defers and reports while the target's lock is FRESH (`Lock.fresh?`); a stale or absent lock is not-active, maintenance proceeds | none enforced by any gate; the maintenance tool or skill itself checks `Lock.fresh?` (see WORK vs MAINTENANCE in `references/maintenance-and-revisions.md`) | append-only, rule-tagged `revisions.md` entry written in the same operation as the change, or the change is refused; lands via a fresh branch off store main merged back as one closed op, never `git add -A` |

package/skills/conventions/references/tiers-and-dispatch.md

@@ -38,10 +38,10 @@ user or the main session states a TIER (S, M, or L) and an EFFORT line in the br
 effort is `xhigh` for `plastic-advisor` and `max` for `plastic-faux-advisor`.
 
 Config is harness-scoped, keys matching `InstallerCore::DEFAULT_AGENTS` exactly (`claude`,
-`codex`, never `claude_code`): `advisor.enabled` (false skips installing both agents and the
-skill), `advisor.claude.default` (which agent the skill routes to), `advisor.claude.primary`
-and `.secondary` (the two slots, agent NAMES never model names, so a slot can point at a
-locally registered agent). Each agent's actual model is a plain `agents.models.claude.<name>`
+`codex`, `hermes`, never `claude_code`): `advisor.enabled` (false skips installing both agents and the
+skill), `advisor.claude.default` (which agent the skill routes to; an agent NAME never a model
+name, so it can point at a locally registered agent, and the only advisor routing key the
+installer writes). Each agent's actual model is a plain `agents.models.claude.<name>`
 override, the SAME harness-scoped mechanism every other agent uses, resolved through
 `InstallerCore#agent_model_overrides(harness:)`; there is no separate advisor-model key.
 `agents.models` is harness-scoped from this release (`agents.models.claude.*`,
@@ -92,7 +92,7 @@ belt-and-braces on top of the frontmatter pin.
 **Cross-harness portability.** The dispatch and model-tier contract above is harness-facing. The
 adapter layer that maps Plastic's hooks and model aliases onto each supported agent runtime
 (Claude, Codex, Hermes) is the cross-harness portability layer; see
-docs/reference/harness-adapters.md for the adapter contract.
+[`harness-adapters.md`](https://github.com/zalom/plastic/blob/main/docs/reference/harness-adapters.md) for the adapter contract.
 
 **Spawn preamble (intent 152).** `scripts/spawn-preamble` emits a live-state block purely from
 filesystem state: the active intent, stage, role/cycle-step, the honor instruction, and the
@@ -128,7 +128,8 @@ succession at a glance (last line = where we are).
 ### Auto-Mode Human Reporting (intent 92)
 
 In auto mode the orchestrator briefs the human at every lifecycle stage boundary in a fixed,
-impact-first shape (the EM-to-CTO report contract): State, then Risk, then Call. It leads with
+impact-first shape (the EM-to-CTO report contract): State, then Risk, then Call. This is the
+depth at M and L; at S the briefing fires once, at How. It leads with
 what changed and why it matters, names one risk, and leaves the decision to the human. Separately,
 the `plastic-humanizer` skill cleans authored prose (specs, outcomes, READMEs, release notes) of
 AI tells and slop; it is for documents, not for every reply.

package/skills/dashboard/SKILL.md

@@ -157,7 +157,7 @@ To explain or debug a ranking or disposition, read `references/classification.md
 
 The eval is the payload + golden snapshots: run the engine against the fixture store and
 assert the `--data` payload shape/sorting/classification and the byte-identical `--json` +
-text goldens in `test/fixtures/dashboard/`. See `test/dashboard_test.rb`. Drift without an
+text goldens in [`test/fixtures/dashboard/`](https://github.com/zalom/plastic/tree/main/test/fixtures/dashboard). See [`dashboard_test.rb`](https://github.com/zalom/plastic/blob/main/test/dashboard_test.rb). Drift without an
 intentional change means the skill is broken.
 
 ## Notes

package/skills/doctor/SKILL.md

@@ -36,8 +36,9 @@ Each manifest maps a file path to its SHA256.
 
 **On failure**, the report states this guided route, in order:
 
-1. Run `plastic doctor --fix` (the Fix all / Select individually / Skip router from
-   Step 4-5 below).
+1. Offer fixes in the `/plastic-doctor` conversation (the Fix all / Select individually /
+   Skip router from Steps 4-5 below); doctor itself only reports, and each chosen repair
+   is dispatched to the maintenance tool or skill that owns it.
 2. If that does not resolve it, roll back to the last known-good version via
    `plastic-rollback` (restores from the local, append-only `versions.json` ledger of
    versions actually run).
@@ -159,8 +160,8 @@ Use the `fix_hint` value to determine the correct action:
 | "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
 | "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
 | "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-store-provisioning` skill) to create the missing store |
-| "Re-run installer" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) |
-| "Run the Plastic installer to bootstrap the store" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) to restore the global store's plastic_home directory or INDEX.md |
+| "Re-run installer" | Run `npx -y @zalom/plastic@<channel> install --claude` (or `--codex`/`--hermes`/`--all` for that agent; channel: -alpha->@alpha, -beta->@beta, else @latest) |
+| "Run the Plastic installer to bootstrap the store" | Run `npx -y @zalom/plastic@<channel> install --claude` (or `--codex`/`--hermes`/`--all`; channel: -alpha->@alpha, -beta->@beta, else @latest) to restore the global store's plastic_home directory or INDEX.md |
 | "Dispatch plastic-store-curating ... revisions.md ..." | Invoke the `plastic-store-curating` (or the agent) to relocate the flagged section or ref into the intent's `revisions.md` via move-and-record (one dated, `[rule: <tag>]`-tagged entry per item), per plastic-conventions > references/maintenance-and-revisions.md. For a missing required section, restore or reproject it instead. |
 | "Run scripts/project-links ... PRESERVES ... --drop-unbacked-links" | Run `ruby ~/.plastic/scripts/maintenance-run --tool project-links --intent <id> --apply` for the one flagged id (never run bare `project-links` against a real store outside the rare owner-approved batch exception, D2) |
 
@@ -206,4 +207,4 @@ This keeps the update flow clean when nothing is wrong.
 
 ## References
 
-- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and stuck detection thresholds when diagnosing gate failures or stuck agents
+- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and the recorded stuck-detection signals when diagnosing gate failures or stuck agents

package/skills/doctor/references/gates-stuck-detection.md

@@ -28,11 +28,16 @@ Hard blocking — hooks exit with code 2 when gates fail.
 
 ## Stuck Detection
 
-| Condition | Threshold | Action |
-|---|---|---|
-| Consecutive gate failures | 3+ | Warning |
-| Consecutive gate failures | 5+ | Force savepoint + escalate |
-| No activity | 5+ min | Warning |
-| No activity | 10+ min | Force savepoint + escalate |
-| Context pressure | 80% | Warning |
-| Context pressure | 90% | Force savepoint |
+No automatic stuck detector ships today: no threshold fires, and nothing forces a savepoint
+or escalates on its own. What exists is recorded data, and reading it is the diagnosing
+agent's judgment:
+
+- `build.gate_failures` in the bridge file: `scripts/hook-gate-check` increments it on every
+  blocked write and resets it to 0 on a passing one. Nothing reads the counter back; a high
+  value is a signal for you, not a trigger for the system.
+- `build.last_activity` in the bridge file: updated on passing writes. There are no
+  inactivity timers, and context pressure is not tracked anywhere.
+
+When diagnosing, treat repeated denies of the same gate with no station progress (compare
+the savepoint ledger) as stuck: stop, read the deny reason, and route through the resolving
+command it names.

package/skills/doctor/report.md

@@ -97,4 +97,4 @@ Checked at: {{timestamp}}
   FOOTER -- always include this line exactly as written.
   ===================================================================== -->
 
-Run `plastic doctor --fix` to auto-fix all fixable issues, or ask me to fix them now.
+Doctor only reports; it never fixes anything itself. Ask me to fix these issues and I will offer Fix all / Select individually / Skip, then route each chosen repair through the tool that owns it.

package/skills/install/SKILL.md

@@ -187,7 +187,7 @@ Version:  none -> <installed>
 Doctor:   <summary or "all clear">
 ```
 
-Then: "Read `docs/guides/your-first-intent-in-10-minutes.md` for your first intent, start to finish."
+Then: "Read [`your-first-intent-in-10-minutes.md`](https://github.com/zalom/plastic/blob/main/docs/guides/your-first-intent-in-10-minutes.md) for your first intent, start to finish."
 
 ### Local Install (testing/legacy)
 

package/skills/intent-brainstorming/SKILL.md

@@ -8,8 +8,6 @@ user-invocable: true
 
 Help turn ideas into fully formed designs through natural collaborative dialogue.
 
-Announce: "I'm using the brainstorming skill to explore the design for intent {id}: {name}."
-
 Start by understanding the current project context, then ask questions one at a time, in prose, to refine the idea. Once you understand what you're building, present the design and collect the owner's rulings on it. This skill's product is the enriched Why, not spec.md.
 
 <HARD-GATE>

package/skills/intent-creating/SKILL.md

@@ -42,7 +42,7 @@ When creating a tactical intent in a project store:
 - **Global:** `~/.plastic/store/`
 - **Project:** `~/.plastic/projects/{slug}/store/`
 
-### 1b. Check for a Duplicate or Predecessor (QMD-first)
+### 2. Check for a Duplicate or Predecessor (QMD-first)
 
 QMD-first (when available): before scanning the store with grep/Read, run
 `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
@@ -50,7 +50,7 @@ intents, then open the authoritative intent file for any hit you act on. The com
 when QMD is absent, so fall back to the existing INDEX.md / file scan. Do this before allocating
 the id so a near-duplicate can be reused and a true predecessor can be set in `--sources`.
 
-### 2. Decide Branch vs Root
+### 3. Decide Branch vs Root
 
 Decide this BEFORE scaffolding, because it sets whether you pass `--parent`.
 Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
@@ -85,7 +85,7 @@ Read `../plastic-conventions/references/knowledge-graph.md` for the full linking
 tiers of influence, sources versus chain, and how the `## Links` projection is derived. This path
 resolves relative to this skill's own installed directory.
 
-### 3. Determine Intent Properties
+### 4. Determine Intent Properties
 
 Ask or infer from context:
 - **intent**: one-line description
@@ -100,11 +100,11 @@ Ask or infer from context:
 
 `chain` carries what this intent spawns AND related-but-not-spawned successors it leads to;
 it starts empty and is populated later. See
-`docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
+[`how-plastic-sources-and-chains-intents.md`](https://github.com/zalom/plastic/blob/main/docs/concepts/how-plastic-sources-and-chains-intents.md) for the full model.
 Place the intent in `## Active` or `## Future` in INDEX.md (status is
 convention-derived, not a frontmatter field).
 
-### 4. Scaffold via new-intent (single call)
+### 5. Scaffold via new-intent (single call)
 
 Delegate id allocation, directory and file creation, the born-complete intent
 file, the sentinel placeholder lifecycle files, the reciprocal file links, and
@@ -112,7 +112,7 @@ self-validation to one `new-intent` invocation. Do NOT hand-author any of these
 files.
 
 ```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/new-intent" \
+ruby ~/.plastic/scripts/new-intent \
   --store "<STORE>" --intent "<one-line>" --slug "<slug>" \
   [--parent "<parent_id>"] [--author "<author>"] \
   [--sources "id,id"] [--tags "project-<slug>,tag"]

package/skills/intent-creating/references/lifecycle.md

@@ -73,7 +73,7 @@ State is derived from what exists, not from what's declared.
 
 1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
 2. Decide branch vs root (this sets whether you pass `--parent`)
-3. Scaffold with one call: `"${CLAUDE_PLUGIN_ROOT}/scripts/new-intent" --store <store> --intent "<one-line>" --slug <slug> [--parent <id>] [--sources id,id] [--tags ...]`. This allocates the id, creates the directory plus `actions/` and `resources/`, renders the born-complete intent file (frontmatter plus `## Intent`, `## Context`, `## Outcome`, `## Insights`, `## Links`), writes the sentinel placeholder lifecycle files, wires the reciprocal links, and self-validates.
+3. Scaffold with one call: `ruby ~/.plastic/scripts/new-intent --store <store> --intent "<one-line>" --slug <slug> [--parent <id>] [--sources id,id] [--tags ...]`. This allocates the id, creates the directory plus `actions/` and `resources/`, renders the born-complete intent file (frontmatter plus `## Intent`, `## Context`, `## Outcome`, `## Insights`, `## Links`), writes the sentinel placeholder lifecycle files, wires the reciprocal links, and self-validates.
 4. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
 
 The intent file is born complete with all five sanctioned `##` sections; the lifecycle files (`spec.md`/`plan.md`/`checklist.md`/`outcome.md`) are sentinel placeholders that read as "stage not reached" until an agent fills them and deletes the `<!-- plastic:placeholder -->` first line.

package/skills/intent-discovering/SKILL.md

@@ -11,8 +11,6 @@ user-invocable: false
 
 # Intent Discovery — What-stage context deposit
 
-Announce: "Discovering context for intent [ID] — [name]."
-
 Runs once, at intent activation, after the lock is armed and before Why. It gathers what is
 already known so Why does not start cold, and deposits it as a resource the
 Why-stage brainstorming agent reads.
@@ -21,9 +19,18 @@ Why-stage brainstorming agent reads.
 Inside `plastic-intent-starting`, right after the bridge is armed, under the
 lock. Dispatched as the `plastic-intent-discovery` background agent.
 
+**Precondition for skipping: a size of S already on record, and no graph edges.** Read the
+activating intent's `chain` and `sources` frontmatter fields first. When a `Tier: S` line is
+already stamped at the top of `spec.md` AND both fields are empty, the pass does not run:
+write the single line `no chain/sources, discovery skipped` to
+`resources/discovery--<slug>.md` and stop there. Sizing happens at Why, which is after this
+stage, so a first activation usually has no size yet and the full pass runs. Never guess a
+size to unlock the skip. At M or L, or when either field is filled, run the full pass below.
+
 ## What it does
 1. **Read the intent's links.** Load the activating intent file's `chain` and
-   `sources` frontmatter fields.
+   `sources` frontmatter fields. If both are empty and a size of S is already on record, apply
+   the skip above and stop.
 2. **QMD-first discovery.** Search the Plastic stores with
    `scripts/qmd-sync search "<terms>"` (or the `qmd` skill), scoped to the
    relevant `plastic-*` collections, across completed predecessor work named in

package/skills/intent-ending/SKILL.md

@@ -62,8 +62,8 @@ for orchestrator-owned or completion-tracking items.
    `## Links` projection). On a refusal, fix via the OWNING tool, never a
    hand edit of the check's own output:
    - checklist/outcome content - finish it yourself, the same as before.
-   - links projection - `scripts/project-links --intent <id> --apply` via
-     `maintenance-run`.
+   - links projection - run
+     `ruby ~/.plastic/scripts/maintenance-run --tool project-links --intent <id> --apply`.
    - a savepoint issue - advisory only (WARN, never blocks): run
      `plastic-intent-savepoint` to rebuild via `Bridge.rebuild_savepoint` if
      you want it clean, but it never refuses the close on its own.
@@ -171,8 +171,9 @@ historical record of what was planned.
 
 ## Routing
 
-`plastic-releasing`, `plastic-auto`, the curator agent, `store-curating`, and
-`store-indexing` all delegate their mechanical close to this skill (or call
-`scripts/end-intent` directly for steps 1-5). None of them restate the
-outcome/INDEX/savepoint/disarm prose inline any more; if you find one that
-does, that surface has drifted and should route here instead.
+`plastic-releasing`, `plastic-auto`, `plastic-intent-executing`, the curator
+agent, `store-curating`, and `store-indexing` all delegate their mechanical
+close to this skill (or call `scripts/end-intent` directly for steps 1-5).
+None of them restate the outcome/INDEX/savepoint/disarm prose inline any
+more; if you find one that does, that surface has drifted and should route
+here instead.

package/skills/intent-executing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plastic-intent-executing
-description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
+description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (at L a fresh subagent per task with two-stage review, at S and M one executor dispatch for the whole consolidated action). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
 user-invocable: true
 ---
 
@@ -8,9 +8,7 @@ user-invocable: true
 
 ## Overview
 
-Load plan from the active intent's `plan.md`, execute all tasks, review between tasks, report when complete.
-
-**Announce at start:** "I'm using the executing-plan skill to implement this plan."
+Load plan from the active intent's `plan.md`, execute all tasks, review per the tier gate below, report when complete.
 
 ## Step 0: Sync Worktree First
 
@@ -42,7 +40,12 @@ If `superpowers:subagent-driven-development` is available as a skill, delegate t
 - Superpowers skills respect "user preferences for plan/spec location"; Plastic IS that preference
 
 ### Subagent-Driven (Default)
-Dispatches a fresh subagent per task. Controller never implements, only dispatches, reviews, and tracks progress. Two-stage review after each task: spec compliance first, then code quality.
+Dispatches subagents to do the work. The controller never implements. It dispatches, reviews, and tracks progress. How many dispatches it makes depends on the tier stamped at the top of `spec.md` (the `Tier:` line, the single authoritative record). `plan.md` carries a bold `**Tier:**` field copied from it, a convenience only:
+
+- **S or M:** one executor dispatch implements the whole consolidated action from `plan.md` plus `checklist.md` in one pass. There is no per-task implementer-then-two-reviewers loop.
+- **L:** a fresh subagent per task, and a two-stage review after each task: spec compliance first, then code quality.
+
+The final independent review in Step 3 runs at every tier. It is a separate agent with fresh context, and it is never the maker.
 
 ### Inline (Fallback)
 Executes tasks sequentially in the current session. Use when subagents aren't available or user explicitly requests inline mode.
@@ -59,6 +62,19 @@ Run Step 0 (Sync Worktree First) before this step.
 
 ### Step 2: Execute Each Task
 
+Read the `Tier:` line stamped at the top of `spec.md` first (the authority), then follow the matching branch. `plan.md`'s bold `**Tier:**` field is a convenience copy of the same value, useful when `spec.md` is not already open.
+
+#### At S or M: one executor dispatch
+
+Dispatch ONE executor subagent and give it the whole delivery: every task's full text from `plan.md` (pasted in, never a file reference), the checklist items it must tick, the project context from CLAUDE.md, and the active intent context from `{ID}--{slug}.md`. In auto mode this is the `plastic-executor` agent; elsewhere use the `implementer-prompt.md` template. The executor implements the consolidated action in order, ticks each item as it lands (see `## Tick-as-you-land`), and drives the test suite green.
+
+Read its response by code:
+- DONE or DONE_WITH_CONCERNS → proceed to Step 3. Run no per-task spec review and no per-task quality review at these tiers; Step 3's final review covers the work.
+- NEEDS_CONTEXT → provide the missing context, re-dispatch the executor.
+- BLOCKED → stop, report to the user, wait for resolution.
+
+#### At L: one subagent per task
+
 For each task sequentially (never parallel: conflict risk):
 
 **a. Dispatch implementer subagent**
@@ -85,17 +101,13 @@ Only after spec compliance passes. Reviews clean code, testing, architecture. Pa
 Follow `## Tick-as-you-land` below: move the task's checklist item to `## Completed` and add a `## Session Log` row in the same edit.
 
 ### Step 3: Final Review
-After all tasks complete, dispatch a final reviewer for the entire implementation.
+After all tasks complete, dispatch a final reviewer for the entire implementation. This runs at every tier, S, M, and L. The reviewer is a separate agent with fresh context and is never the maker. At S and M this is the only review the work gets, so if it returns changes, re-dispatch the executor to fix them, then re-review.
 
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form. Set the frontmatter `disposition: delivered` (the delivered terminal). `outcome.md` is mandatory at every terminal and self-declares its disposition (canonical done-marker in PLASTIC.md).
-2. Write `## Outcome` summary in the intent file (1-2 sentences)
-3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
-4. Update cluster entries to show `_(completed)_`
-5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID>: <name>"`
-6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
+1. Update the intent's cluster entries in `INDEX.md` to show `_(completed)_`. Do this first, so the store auto-commit in the next step picks it up. `plastic-intent-ending` does not cover cluster maintenance (`store-indexing` and `store-curating` own it), so doing it here keeps the step from being lost.
+2. Hand the mechanical close to `plastic-intent-ending`. It owns `outcome.md`, the intent file's `## Outcome` stamp, the INDEX terminal move, the savepoint `Done` line, the store auto-commit, disarm, the QMD reindex, and the EM-to-CTO owner report, as ONE delegation. Author the outcome.md content when that skill asks for it; do not restate the mechanical steps here.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately, do not leave it for later.
 
@@ -117,12 +129,8 @@ For each task:
 ### Step 3: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form. Set the frontmatter `disposition: delivered` (the delivered terminal). `outcome.md` is mandatory at every terminal and self-declares its disposition (canonical done-marker in PLASTIC.md).
-2. Write `## Outcome` summary in the intent file (1-2 sentences)
-3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
-4. Update cluster entries to show `_(completed)_`
-5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID>: <name>"`
-6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
+1. Update the intent's cluster entries in `INDEX.md` to show `_(completed)_`. Do this first, so the store auto-commit in the next step picks it up. `plastic-intent-ending` does not cover cluster maintenance (`store-indexing` and `store-curating` own it), so doing it here keeps the step from being lost.
+2. Hand the mechanical close to `plastic-intent-ending`. It owns `outcome.md`, the intent file's `## Outcome` stamp, the INDEX terminal move, the savepoint `Done` line, the store auto-commit, disarm, the QMD reindex, and the EM-to-CTO owner report, as ONE delegation. Author the outcome.md content when that skill asks for it; do not restate the mechanical steps here.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 
@@ -171,7 +179,7 @@ persisting each ruling with `--stage Exec`.
 
 - **Before:** `plan.md` and `checklist.md` exist; the worktree is armed.
 - **Produces:** code changes, a ticked checklist, and (for audits or sweeps) a methods report in `resources/`.
-- **Next:** intent-ending owns `outcome.md` (see intent 161). This skill's own Update-Intent-and-Complete step above is unchanged by this note.
+- **Next:** `plastic-intent-ending` owns `outcome.md` and the rest of the mechanical close (see intent 161). The Update-Intent-and-Complete step above hands off to it.
 
 Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
 report-home contract this handoff relies on.

package/skills/intent-grilling/SKILL.md

@@ -53,20 +53,22 @@ This process is thorough. It typically takes 20-45 minutes for a complex design.
 
 > "We've covered [areas]. Still to explore: [areas]. Continue, or pause and capture what we have?"
 
-If the user wants to pause, capture all decisions made so far into the active intent's spec.md.
+If the user wants to pause, capture all decisions made so far into the active intent's `## Context` / `### Decisions`, ready for /plastic-intent-speccing to consolidate later.
 
 ### 5. Close Out
 
 When all branches are resolved:
 
-1. Write the complete spec to the active intent directory (`spec.md`)
+1. Record every ruling in the active intent's `## Context` / `### Decisions`, then hand off
+   to /plastic-intent-speccing to consolidate them into `spec.md` (that skill owns
+   `spec.md` exclusively)
 2. List all decisions made
 3. List any deferred items (things the user explicitly chose to decide later)
 4. Proceed to Autonomous Handoff Offer (step 6)
 
 ### 6. Autonomous Handoff Offer
 
-After closing out (spec written, decisions listed), assess whether the agent has enough context to deliver the intent autonomously.
+After closing out (decisions listed, spec consolidated by /plastic-intent-speccing), assess whether the agent has enough context to deliver the intent autonomously.
 
 **Self-assessment checklist:**
 - All key decisions resolved (no open "it depends" or "TBD")

package/skills/intent-planning/SKILL.md

@@ -12,8 +12,6 @@ Write comprehensive implementation plans assuming the engineer has zero context
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
-**Announce at start:** "I'm using the writing-plans skill to plan intent {id}: {name}."
-
 ## Active Intent Gate
 
 Before proceeding, resolve the active intent:
@@ -55,13 +53,19 @@ This structure informs the task decomposition. Each task should produce self-con
 
 ## Bite-Sized Task Granularity
 
-**Each step is one action (2-5 minutes):**
+Granularity follows the `Tier:` line the spec stamped.
+
+**At M or L, each step is one action (2-5 minutes):**
 - "Write the failing test" - step
 - "Run it to make sure it fails" - step
 - "Implement the minimal code to make the test pass" - step
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
+**At S, size each step to the work.** Do not slice a small delivery into fixed 2-5 minute steps. Keep steps coarse enough to read in one pass, and let the one consolidated `actions/ACTION_1.md` carry the whole delivery. Each step still names its exact file paths, its exact changes, and how it is verified. Only the slicing relaxes.
+
+This changes granularity, nothing else. Every tier still produces at least one real `actions/ACTION_N.md`, and an empty or `.gitkeep`-only `actions/` still fails the How gate (see `## Tier shapes` above).
+
 ## Plan Format
 
 For the exact plan/task/checklist/action format (the Plan Document Header

package/skills/intent-researching/SKILL.md

@@ -8,8 +8,6 @@ user-invocable: true
 
 Investigate a topic related to the active intent. Choose the right depth, produce a cited report.
 
-**Announce at start:** "I'm researching [topic] for intent {id} — {name}."
-
 ## Active Intent Gate
 
 Before proceeding, resolve the active intent:

package/skills/intent-starting/SKILL.md

@@ -10,8 +10,6 @@ user-invocable: true
 
 # Intent Starting — board a session onto an intent
 
-Announce: "Boarding intent [ID] — [name]."
-
 `plastic-intent-starting` is the Start procedure. It boards a session onto one intent: take
 the lock FIRST, confirm the delivery state, ask **auto or guided ONCE**, board at the latest
 delivered station, then run the cycle to Done. The What → Why → How → Exec stations are the
@@ -70,6 +68,16 @@ This path resolves relative to this skill's own installed directory.
    lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
    discovery yields nothing, proceed to Why normally.
 
+   **Skip the dispatch only at Tier S, when there is nothing to discover.** The skip fires
+   only when BOTH hold: a size of S is already on record for this intent, and the activating
+   intent's `chain` and `sources` frontmatter fields are both empty. On record means a
+   stamped `Tier: S` line at the top of `spec.md`. Sizing happens at Why, which is after this
+   step, so a first activation usually has no size yet: run the pass. The skip mainly earns
+   its keep on a re-activated intent that is already sized S. Never guess a size here to
+   unlock the skip. When both conditions hold, write the single line
+   `no chain/sources, discovery skipped` to `resources/discovery--<slug>.md` in its place,
+   then go to Why.
+
 **Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
 id the bridge is keyed by: pass the hook stdin `session_id` when you have it; in the executable
 snippets, a nonblank `CODEX_THREAD_ID` identifies Codex, otherwise a nonblank

package/skills/project-creating/SKILL.md

@@ -10,8 +10,6 @@ user-invocable: true
 
 # Creating a Project
 
-Announce: "Creating project `<slug>` from intent [ID] — [name]."
-
 ## Precondition
 
 An active intent must exist with enough context to define a project — at minimum: name/slug, path, and key decisions from `## Context > ### Decisions`.

package/skills/project-creating/references/project-scaffolding.md

@@ -74,7 +74,7 @@ Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
 # Index
 
 ## Active
-- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
+- [1 — <intent name>](store/1--<slug>/1--<slug>.md) — implementation, from: global:<ID>
 ```
 
 **For multi-intent spawning (Hub):**

package/skills/releasing/SKILL.md

@@ -332,7 +332,7 @@ the intent-41 re-land playbook.
 
 - Read `references/release-lines.md` for the two release lanes, the stable-line guarantees,
   the version-line map, and the intent-41 re-land playbook before starting any release
-- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+- When promoting a pre-release across channels (alpha to beta, beta to stable) or
   tagging a historical release retroactively, read `references/promotion-and-tagging.md`
   for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/promotion-and-tagging.md

@@ -33,21 +33,27 @@ cleared is a no-op.
 
 ## Promotion
 
-To promote a release across channels, use `--promote`:
+Promotion is not a CLI flag; there is no `--promote` command. It is a set of steps the
+agent performs during the releasing workflow, reusing the normal release mechanics
+(version bump, tag, `npm publish` with the channel's dist-tag, GitHub release):
 
 ```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
+# Promote alpha → beta: set version files from -alpha.N to -beta.1, commit, tag, then
+npm publish --access public --tag beta
+
+# Promote beta → stable: strip the pre-release suffix (e.g., 1.0.0-beta.3 → 1.0.0),
+# commit, tag, then
+npm publish --access public          # no --tag flag publishes to latest
 ```
 
 **Promotion rules:**
 - Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
 - Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
+- An annotated tag is created for the promoted version, and the GitHub release is cut
+  as in the normal workflow (`gh release create ... --latest` for stable).
+- To point a channel at an already-published version without republishing, move the
+  dist-tag directly: `npm dist-tag add @zalom/plastic@<version> <channel>`. To move the
+  GitHub "Latest" badge: `gh release edit <tag> --latest`.
 
 ## Retroactive Tagging
 

package/skills/releasing/references/release-lines.md

@@ -20,7 +20,7 @@ green Minitest run can fully vouch for.
 
 **Beta-verified lane.** Branch, merge to the `beta` branch, publish to the npm `beta` dist-tag,
 verify in real use, then merge `beta` into `main` and cut stable. It sits on top of the existing
-promotion mechanics (`--promote beta` / `--promote stable`, linear only, see
+promotion mechanics (agent-performed channel promotion, linear only, see
 `promotion-and-tagging.md`); it names when to use them, not new machinery.
 
 ## Routing rule

package/skills/skill-creating/SKILL.md

@@ -35,8 +35,11 @@ routes each authoring task to the reference that holds the depth.
 - Build at least three evals before writing extensive docs.
 - Match determinism to fragility: a deterministic script for fragile or
   repeated mechanical steps, prose for judgment calls.
-- Imperative voice, no second person. No em-dashes or en-dashes in any shipped
-  skill or doc (use commas, periods, parentheses, colons).
+- Imperative voice, no second person. User-facing docs (README, docs/, AGENTS.md,
+  CLAUDE.md) never use em-dashes or en-dashes, and newly authored skill text avoids
+  them (use commas, periods, parentheses, colons). Existing internal files and the
+  sanctioned template emissions (templates/index.md's INDEX line shape) are not
+  violations.
 
 ## Route the authoring task to its reference
 

package/skills/store-indexing/SKILL.md

@@ -14,20 +14,20 @@ user-invocable: false
 
 ## INDEX.md Structure
 
-INDEX.md is a Zettelkasten main structure note - the brain's entry point. It has four sections:
+INDEX.md is a Zettelkasten main structure note - the brain's entry point. It has five sections:
 
 ### Active
 Intents currently being worked on. Max 1-2 for focus.
 ```markdown
 ## Active
-- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2.md) — decision, human
+- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2--design-plastic-state-system.md) — decision, human
 ```
 
 ### Future
 Intents parked for later. May be picked up by agents.
 ```markdown
 ## Future
-- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1.md) — implementation, human
+- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1--build-reddit-knowledge-base.md) — implementation, human
 ```
 
 ### Clusters
@@ -35,10 +35,13 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ```markdown
 ## Clusters
 ### Reddit Knowledge Base
-- [1a — Research](store/1a--research-reddit-saved-posts/1a.md)
-- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1.md)
+- [1a — Research](store/1a--research-reddit-saved-posts/1a--research-reddit-saved-posts.md)
+- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1--plan-reddit-knowledge-base.md)
 ```
 
+### Abandoned
+Intents ended without delivery. Links preserved, never deleted.
+
 ### Completed
 All completed intents with dates. Links preserved, never deleted.