@zalom/plastic 1.8.0 → 1.9.0

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

@@ -0,0 +1,113 @@
+# Locks and Worktrees
+
+This chapter holds the delivery lock, claims, worktrees, solo mode, fail-safe doctrine, and the station-by-station delivery table.
+
+### 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). The session id is the authorization identity. Descriptive provenance
+records the controller's explicit `harness`, `agent`, `model`, `thread`, and `mode` values,
+but never grants access and is never inferred from transcripts or filesystem paths. Missing
+fields on legacy locks display as `Unknown`. Liveness is a lease: the owner's hooks refresh
+the lock file's mtime on tool activity, and that mtime is the sole heartbeat truth. The lock
+counts as stale only when the mtime 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. Rearming the same session preserves its acquired identity and refreshes known
+provenance; an explicit takeover replaces the controller and starts new provenance.
+Subagents spawned by the owner write under the owner's lock once registered as delegates.
+Delegate activity status (`active`, `finished`, or `failed`) is descriptive and does not revoke
+the session's string-array authorization. A registered delegate remains authorized until a
+separate authorization-removal mechanism exists. Finished and failed delegate activity is
+retained as descriptive history, bounded to the 20 most recent terminal entries. A controller,
+a delegate, and an artifact claim are distinct evidence: controller ownership authorizes the
+delivery, delegate registration authorizes a child session, and a claim selects one current
+writer for one artifact. 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 (`who`, status, fix,
+release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. `who` is
+read-only and reports the controller, mtime heartbeat, delegates, and claims from durable files.
+This is
+mandatory, not a convention.
+
+Solo-mode gate defaults (intent 128): on a confirmed positive solo determination
+(`Bridge.solo_delivery?`, a single owner working alone with no sign of parallel or team
+delivery), the lock and worktree arbitration gates relax from enforced to advisory. The moment
+any parallel or team activity appears they return to strictly enforced. This is a real behavior
+difference, not just a message change: a solo session is not hard-blocked by these gates, a
+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.
+
+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.
+
+There is exactly one lock in Plastic: `delivery.lock` (exclusive, one owner plus delegates),
+shipped by intent 108. An earlier two-lock doctrine proposed a second `maintenance.lock`
+(short TTL, structural move-and-record only); intent 112 built it in full and was then
+abandoned before merge on a design pivot, so nothing from it ever shipped (`lock.rb`'s
+`TYPES` seam is the only trace left). Intent 197 rejects the second lock outright rather than
+reviving it: a lock held by a maintenance session could be mistaken by a resuming session
+for an active delivery. Maintenance instead DETECTS `delivery.lock`'s freshness
+(`Lock.fresh?`) and defers when fresh; it never acquires any lock of its own and leaves none
+behind. See "WORK vs MAINTENANCE" in `references/maintenance-and-revisions.md` for the full
+doctrine.
+
+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 is one worktree per project
+intent, the code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch
+`plastic/{id}--{slug}`).
+
+Plastic does not provision a second worktree for lifecycle-doc writes. Two things cover that
+need instead. First, the harness's own native worktree: Claude Code manages its own code
+worktree at `<repo>/.claude/worktrees/{name}`, and Codex manages its own at
+`$CODEX_HOME/worktrees` (default `~/.codex/worktrees`); both exist on their own, independent of
+anything Plastic provisions. Second, intent 197's branch-from-main plus scoped commit, which
+gives store writes their own write safety without a dedicated worktree. Plastic tried a second,
+dedicated store worktree at `<plastic_home>/.worktrees/{id}--{slug}` first; agents never wrote
+into it, because every delivering agent writes lifecycle docs straight to the main store
+checkout, so intent 178 retired the store worktree in favor of the two mechanisms above.
+
+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.
+
+Cleanup is part of Done: the End tail merges the branch, then removes the worktree. Never leave
+an orphaned worktree behind, and clear a stale worktree reference with `git worktree prune`.
+
+
+#### 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/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 |
+| 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/maintenance-and-revisions.md

@@ -0,0 +1,170 @@
+# Maintenance and Revisions
+
+This chapter holds WORK vs MAINTENANCE, the revisions.md move-and-record contract, the violation-tag catalog, and the context-economy measurement buckets.
+
+#### WORK vs MAINTENANCE (intent 197)
+
+Plastic separates two different things an earlier doctrine blurred under one word,
+"immutable." WORK is the delivered CONTENT an intent produced: the code and project files a
+delivery changed, the research it recorded, the outcome it wrote. Once the intent is terminal
+(Completed or Abandoned), that content is immutable - the only way to change it is another
+intent that continues or reverts it. Editing a Done intent's own artifacts so it looks like it
+delivered something different, or that parts are missing, is forbidden (the book analogy:
+never rewrite the text on the pages of an old, valuable book).
+
+MAINTENANCE is everything else: structure, the sources/chain graph, a section that does not
+belong in the file, formatting, and any store-wide operational change (a new Plastic version
+adding or removing a frontmatter field across every intent). Maintenance is not immutable and
+needs no owner gate to run, on the one condition below (recording is universal). The
+decidable test is CONTENT vs METADATA, not "meaning vs structure": a graph edit is structure
+even when it is also, in a loose sense, about lineage, because it does not change what the
+intent delivered. Precedent: plastic intent 124's own `revisions.md` v1 dropped a dead chain
+edge to a non-existent `124b` (`[rule: broken-chain]`), and v2 added a missing required
+reciprocity edge to `131` (`[rule: misplaced-content]`), both ordinary maintenance, not
+owner-gated exceptions. Allowed maintenance: (a) a frontmatter chain/sources edge that points
+to a non-existent or wrong intent, or a missing required edge; (b) an extra non-convention
+section in the intent file, removed and moved into `revisions.md`; (c) a store-wide
+operational change from a new Plastic version, applied to every intent; (d) any other
+structural or operational tidy. Forbidden: anything that alters what the work delivered.
+
+The residual guard on every graph edit: it must move TOWARD ground truth (drop a dangling or
+false edge, add a reciprocity-forced or documented-real one) and must never invent a
+relationship - "might be related" is never a valid `[rule:]` reason. This is already implied
+by the mandatory `[rule: tag]` on every `revisions.md` entry; no additional per-edit owner
+gate is needed for an ordinary graph fix of this kind.
+
+Maintenance normally needs no intent and no roadmap at all; it runs through the maintenance
+tools and skills and records itself. The one exception: a batch touching more than about 5
+different intents at once must stay rare, and is always an owner decision - the agent asks
+first and shows the diff before proceeding. This exception governs rare cross-intent sweeps;
+it does not apply to an ordinary single-intent graph repair.
+
+Maintenance target-state eligibility, by the intent's own lifecycle state: a Future intent,
+yes; a Terminal (Completed or Abandoned) intent, yes; an Active intent mid-delivery, WAIT. The
+wait is keyed on whether the target currently holds a FRESH `delivery.lock` (`Lock.fresh?`),
+never on INDEX `## Active` membership - `end-intent` releases the lock only after the INDEX
+move and its commit tail finish, so keying on Active membership would miss that tail window
+and let maintenance race a live completion. A STALE lock is not maintenance's problem to
+resolve; it is treated as not-active, and maintenance proceeds rather than waiting
+indefinitely behind a dead session.
+
+There is exactly one lock in the system (see the two-lock correction in
+`references/locks-and-worktrees.md`, and the corrected history below in this chapter):
+`delivery.lock`,
+meaning an active agent is delivering that intent. Maintenance DETECTS this lock and NEVER
+ACQUIRES it, even transiently, because a maintenance-held lock could be mistaken by a resuming
+or continuation session for an active delivery. Maintenance leaves no lock behind: there is
+nothing to clean up afterward, and no ambiguity about who, if anyone, holds the one lock.
+`bridge.rb:1195`'s `lock_gate_decision` already allows any write once an intent is not in
+INDEX `## Active` - there is no enforced freeze gate in the codebase today, and there never
+was one that shipped (see the corrected history below).
+
+Stranding and clobbering are avoided by construction, not by a second lock: a maintenance
+action creates a fresh branch from the CURRENT state of store main, applies only its own
+scoped changes, and merges that branch back to main as part of the SAME closed operation.
+Nothing strands on an unmerged branch; two concurrent maintenance runs reconcile as ordinary
+merge conflicts on main, never silent loss. This is lighter than intent 178's full per-session
+delivery worktrees (178 stays about the agent write paths for delivery); maintenance only
+needs branch-from-main plus scoped merge-back (`scripts/lib/maintenance_git.rb`,
+`scripts/maintenance-run`).
+
+No commit anywhere, store or project repo, uses `git add -A`; every maintenance and delivery
+commit stages only the paths it actually changed (`scripts/end-intent`'s `store_commit`,
+`scripts/maintenance-run`).
+
+The one condition on every maintenance action, with no exception, is that it is recorded.
+Every maintenance action, whether run by a tool or made by hand, must leave an append-only
+`revisions.md` entry on its target intent (`## Revision vN`, a `Why ... [rule: tag]` line, a
+`Prior location`, and the change itself). If the file already exists, a new run appends
+`vN+1`; it never overwrites an earlier entry (precedent: intent 124's `revisions.md` v3
+corrects v2 by appending a correction entry and explicitly leaving v2 in place). This is
+tool-enforced, not prose alone: `scripts/project-links`, `scripts/rebuild-graph`, and
+`scripts/restore-intent-v1` each write this receipt in the SAME write as the structural
+change, or refuse to proceed without one (`scripts/lib/revisions_writer.rb`); the intent
+curator (`agents/plastic-intent-curator.md`) holds itself to the identical rule by hand.
+
+Doctor stays a detector: core and full checks, every installed agent, both global and project
+stores. It gains no write path of its own. The "Fix all" prompt
+(`skills/doctor/SKILL.md`) is a ROUTER: for each fixable finding it dispatches to the tool
+that already owns that class of repair (`project-links`, `rebuild-graph`,
+`restore-intent-v1`, or the curator, via `scripts/maintenance-run` where applicable), and
+those tools perform the mutation and write the `revisions.md` receipt - never doctor itself.
+
+Corrected history (D18): an earlier version of this section described a terminal-immutability
+gate "intent 112 enforces" and a two-lock model. Intent 112 built that gate in full and was
+then ABANDONED before merge on a design pivot; nothing from it ever shipped. `bridge.rb:1195`
+confirms no such gate runs today: a write to a terminal intent is allowed unconditionally once
+the intent leaves INDEX `## Active`. The deadlock that stopped intents 189, 192, and 195 from
+repairing three live `graph_links_projection` violations was self-imposed discipline (agents
+and the owner both treating undocumented doctrine as a real gate), not a technical one. This
+section is the corrected doctrine; intent 112's own history stays in INDEX as an abandoned,
+superseded design.
+
+Restore-to-v1 (the owner rule that a completed intent is immutable: a late ruling goes to a
+new `--parent` branch intent, and the completed intent is restored to v1) is performed ONLY by
+`scripts/restore-intent-v1`. Its prose (the intent narrative, `checklist.md`, `outcome.md`,
+`spec.md`, `plan.md`) is immutable and reverts to v1; its frontmatter graph
+(`sources`/`chain`) is metadata about OTHER intents, not content of this one, and is
+APPEND-ONLY: preserved as the union of the v1 snapshot and the current snapshot, never
+subtracted. It writes its own `revisions.md` receipt in the same run. A hand-run whole-file
+`git checkout`/revert of a completed intent is FORBIDDEN, because it cannot distinguish prose
+from graph metadata and silently destroys backlinks written after v1 (proven on intent 124: a
+legitimately accrued chain edge was destroyed by a hand-run restore and went undetected for a
+week).
+
+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 attempted a maintenance lock and an immutability gate; it was
+abandoned before merge and superseded by intent 197's WORK vs MAINTENANCE doctrine
+(detect-only lock, branch-and-merge, tool-enforced `revisions.md`). Intent 4a1b1 owns deep
+agent stuck-detection and is not superseded.
+
+`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
+- `links-projection`: a tool-authored `## Links` regeneration (project-links; intent 197)
+- `graph-rebuild`: a tool-authored sources/chain frontmatter rebuild (rebuild-graph; intent 197)
+
+### 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).

package/skills/conventions/references/roadmaps.md

@@ -0,0 +1,44 @@
+# Roadmaps
+
+This chapter holds the full roadmap file format and its relationship to INDEX.md status and to loop engineering.
+
+### Roadmaps
+
+Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
+is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
+release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
+close, and consume one.
+
+File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
+inside `store/` (store holds intent directories, not project artifacts). For a project that is its
+root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
+`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
+in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
+a sibling subdirectory scaffolded once with a `.gitkeep`.
+
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Batches`, and an
+append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
+an executable checker. `## Batches` holds ordered batches; entries inside a batch are
+parallel-safe, batches run sequentially, top to bottom. A roadmap written before owner ruling 145
+may instead use the legacy `## Waves` heading; the tooling accepts both, but never renames an
+existing roadmap file to migrate it.
+
+Each batch entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
+on any conflict INDEX wins and the roadmap entry is corrected to match.
+
+**Human-comprehension surface.** A roadmap is also written to be read cold. Batch entries render as
+checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
+line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
+engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
+or codenames, ending with a link
+to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
+opening the file with no other context can tell what shipped, what is running now, and what is
+next in under a minute.
+
+**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
+loop is its runtime. Batches lay out the parallelism plan: what can run together, and in what order.
+Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
+running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
+after a stop. This section only states the relationship and points to intent 69 as the future
+consumer; it does not change intent 69's own design.

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

@@ -0,0 +1,134 @@
+# Tiers and Dispatch
+
+This chapter holds tier depth beyond the S/M/L definition, the agent-model and dispatch mechanics, and the auto-mode human reporting contract.
+
+Speed comes from two levers only: artifact content depth and agent topology. The
+same-structure invariant holds: same file set, stage order, gates, and savepoint ledger at
+every tier and in both modes.
+
+S/M collapse the topology (one thinker agent writes spec.md then plan.md plus
+checklist.md plus at least one real action file in one context, consolidated into a single
+actions/ACTION_1.md at S/M and one file per task at L; a sonnet executor implements). L
+keeps the full team.
+
+Never cut at any tier: the independent reviewer, outcome.md as truth of delivery, the
+delivery lock, worktree isolation, intent creation via skill, INDEX as status truth, the
+QMD reindex at End.
+
+Guided mode is unchanged: full-depth artifacts, the human at every gate.
+
+Every lifecycle stage has exactly one dispatchable background agent, plus the enforcer that
+orchestrates them: see PLASTIC.md's Agent Models and Dispatch table for the stage-to-agent
+mapping (What, Why, How, Exec, Done).
+
+Final-gate code review stays an ad-hoc subagent the enforcer dispatches at the final gate, not
+a standing role.
+
+**The advisor: two consultation agents, never injected (intent 185).** Neither is a stage
+role: never in PLASTIC.md's Agent Models and Dispatch table, never dispatched by the auto
+pipeline, and neither ever touches a user's own session. `plastic-advisor` is the real advisor, ships `model: fable`,
+expensive, billed through usage credits. `plastic-faux-advisor` is the imitation advisor, ships
+`model: opus`, an ordinary model carrying the Operating Manual's reasoning discipline inlined
+in its own body (not injected into anything), so it reasons the same disciplined way at a
+fraction of the cost. The `plastic-agent-advisor` skill is the one front door: it teaches when
+consulting is worth the money (from the Advisor Protocol: buy one-way doors, plans, adversarial
+review, deadlocks, ranking; never buy what a tool can answer, code volume, or confirmation of a
+decision already made), routes to the configured agent, and can set the config on request. The
+user or the main session states a TIER (S, M, or L) and an EFFORT line in the brief; shipped
+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>`
+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.*`,
+`agents.models.codex.*`), with the pre-existing flat form (`agents.models.<name>: value`)
+still honored as the claude harness and nested winning over flat. This closes a real latent
+bug: previously the same override map fed both the Claude frontmatter rewrite and the Codex
+TOML generator, so a literal Claude model id could leak into a Codex config; a model named
+under `claude` is now never emitted to `codex`. Install asks which advisor is the default
+(Claude Code only), with a plain description of each: Faux Fable (recommended, cheaper,
+available on any plan) or Fable 5 (the frontier model, billed through credits). Update asks
+the same question once when the key is unset, then never again. Claude-only for this release:
+the owner has not evaluated the Codex reasoning-model ecosystem long enough to judge it, so
+`generate_codex_agents` skips both agents by name, tracked at intent 186, not a permanent
+exclusion.
+
+**Auto-mode entry.** `plastic-auto` is the entry skill for autonomous delivery: it takes over How
+and Exec, spins up the stage-agent team named in PLASTIC.md's Agent Models and Dispatch table,
+and works the dashboard's dispatchable queue. The dashboard's
+`--data` output splits intents into a `dispatchable_queue` (work an agent can pick up) and
+`human_only` (intents that need a person); auto mode consumes the former.
+
+**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 by default,
+unless an explicit `agents.models.<name>` config override names Fable for that role, in which
+case the override is honored as written. The two advisors, `plastic-advisor` and
+`plastic-faux-advisor`, are not lifecycle stage roles: the never-Fable rule governs stage
+agents only. Neither is ever dispatched by the auto pipeline; they are consultation roles
+summoned deliberately by the user or the main session, and their models are user configuration
+(fable and opus by default on Claude Code). 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.
+
+**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.
+
+**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
+report contract. When the intent's code worktree is resolvable and exists on disk, it also
+appends the worktree's absolute path plus a verbatim instruction to `cd` there directly, for
+harnesses whose `EnterWorktree` cannot discover a nested repo from a non-repo launch directory.
+Output is byte-identical when no worktree resolves.
+
+**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. The two advisors,
+`plastic-advisor` and `plastic-faux-advisor`, are not lifecycle stage roles: the never-Fable
+rule governs stage agents only. Neither is ever dispatched by the auto pipeline; they are
+consultation roles summoned deliberately by the user or the main session, and their models are
+user configuration (fable and opus by default on Claude Code).
+
+**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, after the
+delivery lock is armed and before Why begins, running under that lock as the owner session (it
+does not acquire the lock itself and is not blocked by it): 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
+files-on-disk, and the ledger is rebuildable. It exists so a resuming agent reads the cycle's
+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
+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/doctor/SKILL.md

@@ -85,6 +85,10 @@ per-project finding**; that is `--store <slug>`'s job (see above). This is what
 - When hooks aren't firing, skills aren't loading, or something seems broken
 - When the user says "check plastic", "diagnose", "what's wrong with plastic"
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging before diagnosing a stuck or misbehaving gate.
+This path resolves relative to this skill's own installed directory.
+
 ## Procedure
 
 ### Step 1: Run the diagnostic script
@@ -157,7 +161,7 @@ Use the `fix_hint` value to determine the correct action:
 | "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 |
-| "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.md > Structural maintenance and revisions.md. For a missing required section, restore or reproject it instead. |
+| "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) |
 
 For fixes the agent cannot handle automatically, explain what the user needs
@@ -165,6 +169,10 @@ to do manually. The `revisions.md` remedy is curator-applied (a move-and-record
 relocation, not a mechanical edit) and stays human-gated by the Step 4
 Fix / Select / Skip prompt.
 
+Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
+MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog behind
+the `revisions.md` remedy above.
+
 ### Step 6: Verify
 
 After applying fixes, re-run the diagnostic script:

package/skills/intent-brainstorming/SKILL.md

@@ -106,6 +106,10 @@ Do not author spec.md here.
 - **Produces:** the enriched Why (`## Context`, `### Decisions`, one `## Insights` entry per ruling).
 - **Next:** /plastic-intent-speccing consolidates the enriched Why into spec.md.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on. This path resolves relative to this skill's own
+installed directory.
+
 ## Key Principles
 
 - **One question at a time** - Don't overwhelm with multiple questions

package/skills/intent-continuing/SKILL.md

@@ -47,6 +47,10 @@ scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "
 surface the candidate intent, then open the authoritative intent file for the hit you resume. The
 command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract behind the resume below. This path resolves relative to this skill's own
+installed directory.
+
 For that intent's directory:
 
 1. **Read `savepoint.md` FIRST (intent 81).** It is a deterministic, append-only ledger

package/skills/intent-creating/SKILL.md

@@ -71,8 +71,9 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
 
 When a branch intent exists because a late ruling arrived AFTER its parent was already
 completed (the owner's late-ruling rule), the parent is restored to v1 via
-`scripts/restore-intent-v1`, never by a hand-run `git checkout`/revert. See `PLASTIC.md` >
-Terminal immutability for the rule and the tool.
+`scripts/restore-intent-v1`, never by a hand-run `git checkout`/revert. See
+`plastic-conventions > references/maintenance-and-revisions.md`, WORK vs MAINTENANCE, for the
+rule and the tool.
 
 `## Links` is a DERIVED view of `sources`/`chain`. Never hand-write a `## Links` line; add the
 frontmatter edge and reproject. Links are decided by context influence (a `chain` edge has a high
@@ -80,6 +81,10 @@ bar: the candidate's context must materially help deliver this intent), not by s
 similarity score. To gather candidates with their context and record an edge, use the
 `plastic-intent-linking` skill and `scripts/link-suggest`.
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the full linking doctrine: the
+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
 
 Ask or infer from context:

package/skills/intent-ending/SKILL.md

@@ -15,6 +15,10 @@ curator path, and releasing all call this skill (or its backing script,
 prose three times. `abandoned` is the SAME procedure as `delivered`, not a
 failure branch: only outcome.md content and the INDEX section differ.
 
+Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means and
+the End-stage tail behind the steps below. This path resolves relative to this skill's own
+installed directory.
+
 ## The 8 steps (0-7)
 
 | # | Step | Who does it |

package/skills/intent-executing/SKILL.md

@@ -25,6 +25,10 @@ After syncing, verify the plan's target files exist at the paths plan.md names.
 If a named file or directory is missing (renamed or removed upstream), stop and
 report it rather than editing a stale path.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger, before touching the
+worktree above. This path resolves relative to this skill's own installed directory.
+
 ## Mode Selection
 
 ### Check for superpowers first
@@ -138,6 +142,9 @@ the changed file, the installed output) rather than restating the intended
 change. Never present an unverified claim to the owner. If verification
 fails, fix it before the gate, not after.
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging behind every owner gate named here.
+
 ## Methods report (audits and sweeps)
 
 When the work is an audit or a sweep (checking many files or many instances of
@@ -166,6 +173,9 @@ persisting each ruling with `--stage Exec`.
 - **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.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on.
+
 ## Model Selection for Subagents
 
 Match model to task complexity:

package/skills/intent-linking/SKILL.md

@@ -26,6 +26,10 @@ Two distinct steps, do not conflate them:
 
 ## The three tiers (by context influence)
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the full linking doctrine behind
+these tiers, the sources-versus-chain distinction, and the `## Links` projection. This path
+resolves relative to this skill's own installed directory.
+
 - **sources:** the foundational context that shaped this intent's CREATION (a split, an idea born
   during development, a merge). Earns an edge. Decided by origin, never inferred.
 - **chain:** the context that materially helps DELIVER this intent. HIGH bar: only the genuinely

package/skills/intent-locking/SKILL.md

@@ -12,6 +12,10 @@ session-keyed, liveness is a lease (the owner's hooks refresh the file mtime;
 stale means the heartbeat is older than the TTL). The /tmp bridge is only a
 cache; the lock file wins every disagreement.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation in full:
+the single-owner lock, claims, worktrees, solo mode, and the station ledger behind every verb
+below. This path resolves relative to this skill's own installed directory.
+
 ## Verbs
 
 Run from the project (the intent resolves from this session's bridge), or pass

package/skills/intent-planning/SKILL.md

@@ -31,6 +31,10 @@ If the spec covers multiple independent subsystems, it should have been broken i
 
 ## Tier shapes
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind this section. This path resolves relative to this skill's own
+installed directory.
+
 Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the action shape it calls for. Every tier produces at least one REAL action file in `actions/`; the tier only changes how many:
 
 - **S or M (default):** write ONE consolidated `actions/ACTION_1.md` that carries the whole ordered delivery (the steps plus the exact changes). `plan.md` still holds the overall map and `checklist.md` still mirrors the task list. You may split into a few action files when that reads cleaner, but one real action file is the floor.
@@ -121,6 +125,9 @@ When collecting owner rulings for `[ORCHESTRATOR]` hard-gate items, read
 - **Produces:** `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md` (every tier; one consolidated file at S/M, one per task at L).
 - **Next:** /plastic-intent-executing.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on.
+
 ## Git Commit
 
 After writing all artifacts (plan.md, checklist.md, and the actions/ACTION_N.md files), commit to the store: