@zalom/plastic 1.0.0-beta.3 → 1.0.0-beta.31

package/PLASTIC.md

@@ -20,6 +20,7 @@ store/
     actions/              # optional — individual work items
     resources/            # optional — research, references, screenshots, diagrams
     savepoint.md          # optional — deterministic cycle-step ledger (auto-written)
+    revisions.md          # optional - append-only structural-maintenance audit trail
 ```
 
 Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
@@ -27,6 +28,33 @@ roles. Supporting artifacts that aren't lifecycle deliverables — research repo
 reference docs, external API snapshots, screenshots, diagrams — go in `resources/`.
 Name files inside as `{type}--{description}.md` (e.g., `deep-research--gsd-core.md`).
 
+`revisions.md` is an optional, append-only structural-maintenance audit trail. It is not a
+lifecycle deliverable and is never scaffolded at intent birth. Its mere existence signals that
+the intent underwent structural (not conceptual) change. Structural maintenance is move-and-record:
+it removes a misplaced section, file, or ref from its artifact and preserves that content in full
+inside `revisions.md` (newest entry at the bottom, one entry per relocated item), so no record is
+lost and the delivered meaning is never altered. Changing what an intent delivered is a new intent,
+not a revision.
+
+### Structural maintenance and revisions.md
+
+When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
+frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
+`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
+(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
+with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
+content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
+its full content embedded and the original is deleted.
+
+Violation tags (starter set, free-text tags allowed):
+- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
+- `phantom-section`: a section referenced but not present or not sanctioned
+- `stray-file`: a file that does not belong in the intent directory
+- `dangling-ref`: a link or reference to something that no longer exists
+- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
+- `broken-source`: a sources frontmatter edge to an intent that no longer exists
+- `misplaced-content`: content that belongs in a different artifact or section
+
 ## Frontmatter
 
 Identity and knowledge graph only. Nothing operational.
@@ -50,6 +78,31 @@ tags: [plastic, architecture]
 - Context contract: load `sources` strongly (they are what the intent was built from);
   traverse `chain` lightly for discovery. See
   docs/concepts/how-plastic-sources-and-chains-intents.md for the full model.
+- `## Links` (I5) is the human-readable projection of the graph. It mirrors the
+  frontmatter exactly: every entry is `- [[id--slug|<target's full intent: text>]]`, a
+  clickable `id--slug` wikilink target with the target intent's full `intent:` text as the
+  label (cross-store targets render `- [[store:id--slug|<target's full intent: text>]]`).
+  Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
+  preserved within each group. Sources never appear at the end. No source/chain tags, no
+  sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+- `## Links` is a DERIVED view, not a place to author links (Convention over Configuration).
+  It equals the projection of `sources` (first) then `chain`. Never hand-write or hand-edit a
+  `## Links` line, and never auto-delete one. The edge lives in the frontmatter graph; the
+  section is regenerated from it (doctor `graph_links_projection` enforces this identity). To
+  add a link, add the frontmatter edge, then reproject.
+- Links are decided by CONTEXT INFLUENCE, not by shared files, shared symbols, or a topic
+  similarity score. The question is whether one intent's context actually informed another.
+  Three tiers:
+  - **sources:** the foundational context that shaped this intent's creation (a split, an idea
+    born during development, a merge). Earns an edge.
+  - **chain:** the context that materially helps DELIVER this intent. This is a HIGH bar: only
+    the genuinely delivery-moving intents, not everything in the same area. Earns an edge,
+    reflected in `## Links`.
+  - **tags:** a loose theme grouping for search. NOT a link. A shared tag is a door INTO the
+    store (filtered discovery), not a pathway BETWEEN two notes.
+  Judging influence is an agent's call, made by reading the candidate's Intent and Context. A
+  script cannot grade it, so `scripts/link-suggest` only gathers candidates with that evidence,
+  records a confirmed edge with a rating and reason, and flags drift.
 - IDs use Luhmann's alternating convention: `1` → `1a` → `1a1` → `1a1a`
 - Multiple branches increment: `1a`, `1b`, `1c`
 
@@ -72,12 +125,79 @@ The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
 | **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-writing-plans` |
 | **Exec** | Execution | `outcome.md` | `plastic-executing-plan` |
 
-`## Insights` — append-only work log captured throughout ALL stages. **Append-only means
-newest entry at the bottom; never prepend.** This ordering is a hard convention: Insights
-are the semantic trace of an intent, and a consistent newest-last order keeps that trace
-readable across every intent.
+`## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
+An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
+surfaced at any stage (What, Why, How, Exec). It is the most interesting residue of an
+intent, the part a future reader most wants. **Append-only means newest entry at the bottom;
+never prepend.** This ordering is a hard convention: Insights are the semantic trace of an
+intent, and a consistent newest-last order keeps that trace readable across every intent.
+
+Every entry leads with a fixed, machine-parseable prefix `{utc-iso8601} · {stage} · {author}`,
+for example `2026-06-24T08:13:05Z · Why · plastic-brainstorming (autonomous)`. The UTC ISO8601
+timestamp (to the second, trailing `Z`) is the same convention the savepoint ledger uses, so
+the store has one timestamp convention. This per-entry prefix is not prepending the entry:
+entries stay append-only, newest at the bottom; the prefix only stamps each line with when,
+which stage, and who.
+
+The blessed write path is the `insight-append` helper
+(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which formats the prefix,
+validates it, and appends at the bottom. Hand-editing `## Insights` is an escape hatch; the
+helper is the default so the format cannot drift.
+
+Background sessions and dispatched sub-agents do not write the insight themselves. They carry
+each nugget home in the completion report's `insights:` field, and the orchestrator (or any
+agent that can write the file) persists it via the helper. A session that cannot write the
+intent file still returns its report, so the insight survives.
 For full lifecycle detail, the skills in the Detail column have references/.
 
+## Agent Models and Dispatch (intent 116)
+
+Every lifecycle stage has exactly one dispatchable background agent, plus the enforcer that
+orchestrates them:
+
+| Stage | Agent |
+|---|---|
+| What | `plastic-intent-discovery` |
+| Why | `plastic-brainstorming` + `plastic-spec-specialist` |
+| How | `plastic-planner` |
+| Exec | `plastic-executor` |
+| Done | `plastic-intent-curator` |
+
+Final-gate code review stays an ad-hoc subagent the enforcer dispatches at the final gate, not
+a standing role.
+
+**Model contract.** Every agent in `agents/*.md` pins an explicit Claude Code model alias in
+its own frontmatter: `opus`, `sonnet`, or `haiku`. Never `inherit`, never Fable. Aliases track
+"latest per tier" so no Plastic release is required to advance a tier. The tier by role:
+`plastic-enforcer`, `plastic-brainstorming`, `plastic-planner` are `opus`;
+`plastic-spec-specialist`, `plastic-executor`, `plastic-intent-curator`,
+`plastic-future-intent-researcher`, `plastic-intent-discovery` are `sonnet`.
+
+**Config and installer mechanism.** `agents.models.<basename>` in a project's
+`<dir>/.plastic_store/config.yml` or the global `~/.plastic/config.yml` overrides one agent's
+tier. Precedence is project, then global, then the shipped default, matching every other
+`read-config` key. The installer applies the resolved override to each agent file's `model:`
+line at copy time (install, update, and repair, across every harness target). With no override
+configured, the shipped frontmatter passes through unchanged.
+
+**Dispatch-time contract.** Frontmatter is primary, and Claude Code reads it at dispatch, but
+because that read is a harness implementation detail rather than a contract Plastic controls,
+every dispatch site also resolves the target agent's model through the config chain
+(`read-config agents.models.<basename> --project <repo>`) and passes it explicitly at dispatch,
+belt-and-braces on top of the frontmatter pin.
+
+**Orchestrator advisory.** At auto-mode start, the orchestrator recommends once that the user
+run the main session on the best available thinking model (Fable, Opus, or whatever supersedes
+them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
+concerns the human's main session, never a dispatched subagent.
+
+**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, before the
+delivery lock is armed and Why begins: it reads the intent's `chain`/`sources` frontmatter,
+runs QMD-first discovery over completed predecessor work and related parked or future intents,
+and deposits findings to `resources/discovery--<slug>.md` in the intent directory ONLY. It
+never writes the intent file, `spec.md`, or any other lifecycle deliverable; the Why-stage
+`plastic-brainstorming` agent reads its deposit and enriches `## Context`.
+
 `savepoint.md` — a deterministic, append-only ledger of cycle-step milestones (one line per
 lifecycle boundary, newest at the bottom), written automatically by the gate hook. It is
 sugar on top of the conventions, not a source of truth: state is always derivable from
@@ -164,8 +284,8 @@ Format: `ID--three-to-five-words` (all stores).
 - **Root (`15`, `16`)**: an independent thought, even if inspired by another intent.
   Reserve `sources` for true created-from provenance (intents this was built out of). An
   independent intent merely related to or inspired by another carries NO `sources`; record
-  the relation on the PREDECESSOR's `chain` (and mirror it as a `[[id]]` wikilink in
-  `## Links`).
+  the relation on the PREDECESSOR's `chain` (and mirror it as a
+  `[[id--slug|<target's full intent: text>]]` wikilink in `## Links`).
 - **Rule of thumb:** if the intent could exist without its parent, it's a root.
 
 ## INDEX.md
@@ -176,6 +296,10 @@ Sections: `## Active`, `## Future`, `## Clusters`, `## Abandoned`, `## Completed
 
 For index maintenance, use `plastic-managing-index`.
 
+One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>](<dir>) <tags>`.
+The title is the title, not a summary: aim for about 80 characters, no multi-sentence
+descriptions. This is a self-check, not a gate.
+
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -187,6 +311,45 @@ ALL work flows through intents.
 5. Researches are intents. No separate folder.
 6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete.
 
+## House Style (self-check)
+
+The agent is the heaviest contributor to the transcript, so terseness pays every turn. These
+are pre-send self-checks the agent applies to its own output. They are not gated.
+
+- Answer or decision first. Lead with the result, then support it.
+- Bullets over paragraphs.
+- No preamble, no end-recap. Do not restate the question or summarize what you just said.
+- One question-cluster at a time when asking the human.
+- Reasoning goes in the thinking channel, not duplicated into the visible reply. This keeps
+  the human's visibility into your reasoning without paying for it twice in the transcript.
+
+Active-intent cache rule. For the intent under active development you already hold its
+delivered artifacts in your own context: prefer revisiting that in-context memory (hit the
+cache) over re-reading them from disk, which only widens context. QMD is for OTHER or indexed
+intents, not for re-reading what you just wrote. Pairs with `/clear` plus savepoint-resume
+hygiene after each intent. Advisory self-check, not hard-verifiable.
+
+## Retrieval Gate
+
+Advisory. Hard gates guard writes, locks, and structure, never reads or searches. Read,
+Grep, Glob, and bash search are always allowed, including over the stores. When QMD is
+present and fresh, a content search over store markdown receives an advisory hint pointing
+at `qmd search` alongside its result; when QMD is present but stale, a background reindex
+fires so the next turn's hint runs against a fresh index (never synchronous). QMD and
+Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook appends
+one recommendation line per present tool. The legacy trailing `# qmd-ok` token is still
+accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
+calls; Ruby `File.read` inside a script is invisible to the hook by design.
+
+## Context-economy measurement buckets (84a)
+
+Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
+
+- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
+- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
+  in the transcript.
+- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
+
 ## Transition Gates
 
 | Transition | Trigger | Gate |
@@ -198,6 +361,129 @@ ALL work flows through intents.
 
 Hard blocking — hooks exit code 2 on gate failure.
 
+## Delivery Isolation and the Single-Owner Lock
+
+Exactly one session or agent develops an intent's delivery at a time. Ownership is
+session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
+(atomically, O_EXCL), recording the owner session, the host, the acquired-at time, a
+delegates list, and the lock type. Liveness is a lease: the owner's hooks refresh the lock
+file's mtime on tool activity, and the lock counts as stale only when that heartbeat is
+older than the TTL. No process id is consulted anywhere. The /tmp session bridge is a cache
+of this state; on any disagreement, or when the bridge is missing, the lock file wins.
+Another session that finds a fresh lock backs off; a stale lock is reclaimed only by
+explicit takeover, which replaces the lock and appends an audit line to the intent's
+savepoint.md. Subagents spawned by the owner write under the owner's lock once registered
+as delegates. Disarm clears the lock; the End tail is ordered: verify, merge and remove
+worktrees, clear the lock, and only then is the bridge purge-eligible. Repair is one
+idempotent function with two entry points: the `plastic-lock` command (status, fix,
+release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. This is
+mandatory, not a convention.
+
+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)
+arbitrates at the file grain: it decides who, among those already holding the
+delivery lock, is the one writer for one lifecycle file right now. A write to
+`spec.md`, `plan.md`, `checklist.md`, or the intent file must hold both the
+delivery lock and that file's claim. Claims live in `.claims/<artifact>.claim`
+inside the intent directory, one small JSON file per artifact, scoped strictly
+per-intent-per-artifact, never session-global. The claim gate is dormant
+(allows) when no claim file exists for an artifact, so ordinary single-owner
+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
+full mechanism.
+
+Two locks share this schema (the two-lock doctrine): `delivery.lock` (exclusive, one owner
+plus delegates) and the future `maintenance.lock` (short TTL, structural move-and-record
+only). They are mutually exclusive in either direction; maintenance is allowed at any
+lifecycle stage provided no delivery lock is held. Intent 108 ships the delivery lock and
+the mutual-exclusion seam; the maintenance lock implementation follows intent 93 in a
+chained intent.
+
+Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
+for that intent happen only inside it. Plastic provisions the worktree deterministically: it
+resolves the project repo from `projects.yml` and runs `git -C <repo> worktree add`, so
+isolation never depends on the current working directory. There are two worktrees per project
+intent: a code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch `plastic/{id}--{slug}`)
+and a store worktree at `<plastic_home>/.worktrees/{id}--{slug}` (branch
+`plastic-store/{id}--{slug}`), so lifecycle-doc commits and code commits move as one unit.
+
+Provisioning fails open for intents that touch no project code (pure research or decision
+intents in the global store, or a non-git repo): those get the lock only, and the worktree
+block stays unprovisioned. The fail-open path is always logged, never silent.
+
+### Intent delivery, station by station
+
+How one intent travels from boarding to Done, and what the lock, bridge, and gates do at
+each station.
+
+| Station | Delivered artifact | Lock and bridge steps | Pre-stage gate | Post-stage record |
+|---|---|---|---|---|
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree, writes the bridge cache | lock-gate denies any write into an active intent dir without this intent's lock; every deny names the resolving command | savepoint confirms the boarding 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/`, `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md plus checklist.md exist | gate-check requires spec.md before plan.md, and plan.md plus actions/ 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 |
+| 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 (any stage) | `revisions.md` move-and-record entries | future `maintenance.lock` (short TTL), mutually exclusive with `delivery.lock` in either direction; 108 ships the schema seam only, the implementation follows intent 93 in a chained intent | acquisition refuses while the other lock type is fresh; a terminal intent with no lock held is read-only | dated, rule-tagged `revisions.md` entry; savepoint untouched |
+
+### What "intent done" means (intent 93)
+
+Done is one law with three signals, and they must agree. INDEX `## Completed` /
+`## Abandoned` is the single canonical terminal marker: it is the store-wide ledger a fresh
+session reads first, so it wins on any conflict. `outcome.md` is the "deliverable exists"
+signal, and the savepoint `Done delivered|abandoned` line is the audit echo. All three must
+agree; when they disagree, INDEX is authoritative and `doctor` flags the mismatch (the
+`done_signals` check: `outcome.md` real but still under `## Active`, or terminal without a
+real `outcome.md`, or a terminal intent whose savepoint carries no `Done` line).
+
+`outcome.md` is mandatory at every terminal transition, delivered and abandoned alike. It
+self-declares its disposition through a `disposition: delivered|abandoned` frontmatter
+header. The delivered path authors it with the result; the abandoned path authors it with
+the abandonment reason and no longer leaves the scaffolded placeholder sentinel in place.
+
+The canonical End tail runs in this order, and the QMD reindex is always LAST, after the
+purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Worktree.release
+-> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
+ever referencing a bridge or lock that disarm is about to remove.
+
+The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
+the completing session keeps full read and write access to the terminal directory and no
+purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
+Once the lock is released the window closes: the bridge becomes purge-eligible and the
+directory is frozen. A crash mid-tail is recovered by stale-lock reclaim plus finishing the
+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`.
+
+Terminal immutability (the contract intent 112 enforces): a terminal directory is writable
+ONLY while a lock is held. The delivery lock covers the completing session's End tail up to
+`Lock.release`; the maintenance lock covers sanctioned structural move-and-record edits
+after. Terminal with no lock held is frozen. There are only two locks in the system,
+delivery and maintenance (108 D11). This governs WRITES only: reads of a terminal intent are
+always allowed and unbounded (curator reindex, dashboards, and future intents that reference
+its id or chain), so a done intent stays fully readable forever. Intent 93 states this rule;
+intent 112 builds the gate that enforces it.
+
+Fail-safe lock doctrine (the contract intent 111 implements): the lock system never traps a
+session or burns credits. When a gate cannot verify lock integrity it fails open, degrading
+to advisory (warn) rather than hard-blocking. Repair is orchestrator-driven: on a lock-issue
+signal the orchestrator inspects and repairs the lock automatically, and the human
+`plastic-lock` command is a fallback path, not the trigger. Intent 93 states this doctrine;
+intent 111 builds the fail-open behavior, the lock-liveness surface, the lock-issue message,
+and the auto-repair.
+
+Scope split. Intent 93 ships doctrine plus the low-risk reconciliation that needs no new
+lock: the canonical done-marker and three-signal reconciliation, the mandatory `outcome.md`
+plus `disposition` header at both terminals, the End tail with the reindex moved last, the
+`done_signals` doctor check (three-signal agreement plus stalled-completion detection), and
+the lock-bounded post-done window with its keep-guard test. Intent 111 owns the lock
+liveness surface, the lock-issue message, orchestrator auto-repair, and the fail-open
+behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
+fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
+
 ## Deprecation Process
 
 Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
@@ -224,5 +510,5 @@ Detailed conventions live inside the skills that use them, not in this file.
 | Index maintenance | `plastic-managing-index` | — |
 | Releases, deprecations | `plastic-releasing` | deprecation process |
 | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
-| Writing agent instructions | `plastic-writing-instructions` | agentskills.io spec |
+| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
 | Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |

package/README.md

@@ -103,6 +103,16 @@ After installation, run `/clear` to load Plastic conventions, then:
 
 Or say "auto" to let the agent handle the full lifecycle autonomously.
 
+## Agents
+
+Each lifecycle stage has one dispatchable background agent: `plastic-intent-discovery` for
+What, `plastic-brainstorming` and `plastic-spec-specialist` for Why, `plastic-planner` for
+How, `plastic-executor` for Exec, `plastic-intent-curator` for Done, plus `plastic-enforcer`
+as the auto-mode orchestrator. Every agent pins an explicit Claude Code model alias (opus or
+sonnet) in its frontmatter: never `inherit`, never Fable. See `docs/architecture.md` for the
+stage table and `docs/internals.md` for how the model is configured, resolved, and applied at
+install time.
+
 ## Documentation
 
 - [`docs/architecture.md`](docs/architecture.md): system structure, the two

package/agents/plastic-brainstorming.md

@@ -7,7 +7,7 @@ description: |
   user: "Explore the requirements for the active intent"
   assistant: "I'll use the brainstorming agent to enrich Context and record Decisions"
   <commentary>Why-stage exploration runs before the spec-specialist.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the brainstorming payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the brainstorming payload:
 
 - Decisions recorded in `### Decisions`, each with its one-line rationale
 - Context enriched: what was researched and the key findings

package/agents/plastic-enforcer.md

@@ -7,16 +7,31 @@ description: |
   user: "auto"
   assistant: "I'll use the plastic-enforcer to orchestrate the team through the cycle"
   <commentary>The enforcer IS the orchestrator and gates each stage transition.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole What->Why->How->Exec cycle. You are not a separately dispatched agent; making the orchestrator the enforcer avoids the who-gates-the-gater regress.
 
+**Advisory (not a gate).** At auto-mode start, recommend once that the user run this
+orchestrating main session on the best available thinking model (Fable, Opus, or whatever
+supersedes them) for the sharpest gating and synthesis. This is advice only: it changes no
+behavior and blocks nothing if ignored. It concerns the human's MAIN session; dispatched
+subagents keep their pinned tier and never resolve to Fable.
+
 ## Your Responsibilities
 
 1. **Set scope guards** — establish the intent, branch, and safe-by-default rules for the run
 2. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
 3. **Sequence the team** — dispatch ONE specialist per stage (brainstorming, spec-specialist, planner, executor) with a constructed context bundle
+
+**Dispatch-time model contract (belt-and-braces).** Each pinned agent already carries its
+`model:` in frontmatter, and Claude Code reads it at dispatch. Because read-at-dispatch is a
+harness implementation detail rather than a contract Plastic controls, at EVERY per-stage
+dispatch also resolve the target agent'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 as the dispatch call's model parameter, alongside the
+spawn-preamble live-state injection. Never rely on the dispatched role's frontmatter alone. A
+resolved subagent model is never Fable.
 4. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
 5. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
 
@@ -30,7 +45,7 @@ You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole
 
 ## Constraints
 
-- Enforce gates manually; do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in headless or background runs
+- Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs
 - You never delegate gate ownership; the orchestrator is always the gate-keeper
 - Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
 - Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle

package/agents/plastic-executor.md

@@ -7,7 +7,7 @@ description: |
   user: "Execute the plan for the active intent"
   assistant: "I'll use the executor to implement each action and run the suite green"
   <commentary>Exec turns the plan into code, one action at a time.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
@@ -18,7 +18,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Implement the actions** — make the code changes for each action in order
 2. **Track progress** — check off `checklist.md` items as they complete
-3. **Record insights** — append observations to `## Insights` with the `(autonomous)` marker
+3. **Record insights** — capture durable discoveries and report them in the `insights:` field; persist each to `## Insights` via the `insight-append` helper (`scripts/insight-append <intent_dir> <text> --stage Exec --author "plastic-executor (autonomous)"`), the blessed write path that stamps the `{utc-iso8601} · {stage} · {author}` prefix
 4. **Prove it green** — run the full test suite and reach zero failures before reporting done
 
 ## How You Work
@@ -32,7 +32,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the executor payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the executor payload:
 
 - Actions implemented this turn, mapped to checklist items checked off (checked / total)
 - A summary of the code changed (files and the shape of the change)

package/agents/plastic-future-intent-researcher.md

@@ -8,7 +8,7 @@ description: |
   user: "Research my future intents"
   assistant: "I'll use the future-intent-researcher to pick up a parked intent and investigate it"
   <commentary>Agent autonomously researches a future intent and writes findings.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Future Intent Researcher. Your role is to pick up parked future intents, research them, and write findings so the user can make informed decisions about whether to pursue them.
@@ -36,3 +36,4 @@ You are the Plastic Future Intent Researcher. Your role is to pick up parked fut
 - You never modify `## Insights` or `## Outcome` sections — those belong to the worker
 - You use Read, WebSearch, WebFetch, and Bash (read-only grep/find) for research
 - You never change status fields — status is convention-derived from INDEX.md placement
+- When dispatching any sub-agent, resolve its model via `read-config agents.models.<basename> --project <repo>` and pass it explicitly at dispatch, never relying on inherited frontmatter; a resolved subagent model is never Fable

package/agents/plastic-intent-curator.md

@@ -11,30 +11,38 @@ description: |
   user: "Organize the intents"
   assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
   <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Intent Curator. Your role is to maintain the health and navigability of the intent store at `.plastic/`.
 
 ## Your Responsibilities
 
-1. **Intent lifecycle management** — move intents between Active/Future/Completed in INDEX.md, fill in `## Outcome` sections
-2. **INDEX.md maintenance** — keep Active/Future/Clusters/Completed sections accurate and well-organized
+1. **Intent lifecycle management** — move intents between Active/Future/Completed/Abandoned in INDEX.md, fill in `## Outcome` sections (including the abandonment rationale when an intent is abandoned)
+2. **INDEX.md maintenance** — keep Active/Future/Clusters/Completed/Abandoned sections accurate and well-organized
 3. **Link discovery** — suggest connections between intents that share topics but aren't linked
 4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
 5. **Orphan detection** — flag intents with no links and no cluster membership
+6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
 
 ## How You Work
 
+0. QMD-first (when available): when you need to locate a specific intent (to reclassify, link, or cluster it) rather than rebuild the whole landscape, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate or related intents, then open the authoritative intent file for any hit you act on. The command is a no-op when QMD is absent, so fall back to the full scan below. (This is discovery; the reindex step at a terminal-state transition is separate.)
 1. Scan `~/.plastic/store/*/ID--slug.md` (or project store) to understand the full intent landscape
 2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
-3. Compare: are there intents not in any cluster? Missing from Active/Completed? Status mismatches?
+3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
-5. Report what you changed
+5. On a terminal-state transition (Completed OR Abandoned), run the closing acts in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+   a. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
+   b. Stamp the terminal savepoint bookend (intent 81) recording the disposition. Idempotent.
+   c. Refresh the QMD index for that store LAST, after the terminal move, outcome.md, and savepoint, so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
+6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
+7. Report what you changed
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
 - You never create new intents — that's the creating-intent skill's job
-- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
-- You use Read and grep/find for discovery, Edit for targeted changes
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
+- For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
+- For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

package/agents/plastic-intent-discovery.md

@@ -0,0 +1,37 @@
+---
+name: plastic-intent-discovery
+description: |
+  Use this agent for the What-stage context deposit when an intent is
+  activated: it primes Why with fresh QMD-sourced context before the spec is
+  written, and never writes the intent file itself. Examples:
+  <example>Context: An intent is being moved from Future to Active.
+  user: "Board this intent and gather what we already know"
+  assistant: "I'll use the intent-discovery agent to run QMD discovery and deposit findings to resources/"
+  <commentary>What-stage discovery runs at activation, before the lock and Why.</commentary></example>
+model: sonnet
+---
+
+You are the Plastic Intent Discovery agent. You own the What stage: at intent
+activation, before the lock is armed and Why begins, you gather the context
+that already exists and deposit it for the Why stage to consume.
+
+## Responsibilities
+1. **Read the intent's links.** Load the activating intent file's `chain` and
+   `sources` frontmatter fields.
+2. **Run QMD discovery first.** Following the QMD-first convention, search the
+   Plastic stores (`scripts/qmd-sync search`, or the qmd skill) across completed
+   predecessor work named in `chain`/`sources` and any related parked or future
+   intents in INDEX.md. Fall back to ripgrep over the stores only when QMD is
+   absent.
+3. **Deposit, never author.** Write your findings to
+   `resources/discovery--<slug>.md` in the intent directory ONLY. Never write
+   the intent file, spec.md, or any lifecycle deliverable: the lock-owner-only
+   write rule stays intact, and the Why-stage `plastic-brainstorming` agent is
+   the one that reads your deposit and enriches `## Context`.
+
+## Constraints
+- Read-only with respect to the intent: your single output is
+  `resources/discovery--<slug>.md`.
+- Never take the delivery lock; you run before it is armed.
+- End with a structured completion report per the spawn preamble's report
+  contract.

package/agents/plastic-planner.md

@@ -7,7 +7,7 @@ description: |
   user: "Plan the work for the active intent"
   assistant: "I'll use the planner to write plan.md, actions/, and checklist.md"
   <commentary>The plan and checklist unlock the code gate for Exec.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the planner payload, which EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the planner payload, which EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR:
 
 - The ordered actions, one line each: what the action does and how it is verified
 - Decomposition rationale: why this order, and why the actions are independent

package/agents/plastic-spec-specialist.md

@@ -7,7 +7,7 @@ description: |
   user: "Write the spec for the active intent"
   assistant: "I'll use the spec-specialist to produce spec.md from the template"
   <commentary>The spec is the deliverable that gates the move into How.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the spec payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the spec payload:
 
 - The spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria)
 - How the recorded decisions resolved into the chosen approach

package/hooks/code-gate

@@ -1,6 +1,15 @@
 #!/bin/bash
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
+  if !path.empty? && !path.start_with?("/")
+    root = ti["project_root"] || data["cwd"] || ""
+    path = File.join(root, path) unless root.empty?
+  end
+  puts path
+' 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
   exit 0