@zalom/plastic 1.14.0 → 2.0.0-alpha.1

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

@@ -1,21 +1,26 @@
 # Locks and Worktrees
 
-This chapter holds the delivery lock, claims, worktrees, solo mode, fail-safe doctrine, and the station-by-station delivery table.
+This chapter holds the delivery lock, claims, worktrees, the fail-safe doctrine, and the station-by-station delivery table. Since 2.0 (intent 302) nothing here blocks a write: the lock and the worktree are how an auto team keeps one delivery in one place, recorded by the record hook, not enforced by a hook.
 
 ### Delivery Isolation and the Single-Owner Lock
 
-Exactly one session or agent develops an intent's delivery at a time. Ownership is
+Locks and worktrees exist only for auto teams. An interactive session working direct or
+thinking takes no lock: it records into the day ledger, or into the intent its per-session
+pointer names (`~/.plastic/store/.tmp/<session>/current`, where `<session>` is the first eight
+characters of the session id; the file holds today's day id or an intent id).
+
+For an auto team, exactly one team 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
+fields on legacy locks display as `Unknown`. Liveness is a lease: the record hook refreshes
+the lock file's mtime on every write the owning session makes, 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 pointer file is a cache of which intent a session
+records into; the lock file is the truth of who owns a delivery, and wins on any
+disagreement. Another team 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.
@@ -25,41 +30,27 @@ separate authorization-removal mechanism exists. Finished and failed delegate ac
 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.
+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 session pointer purge-eligible. Repair
+is one idempotent function with two entry points: the `plastic-lock` command (`who`, status,
+fix, release, reclaim, delegate) and the `plastic-doctor` skill's lock section, so repair
+self-heals. `who` is read-only and reports the controller, mtime heartbeat, delegates, and
+claims from durable files. This is mandatory for auto teams, not a convention.
 
-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`](https://github.com/zalom/plastic/blob/main/docs/internals.md) for depth.
+The record hook 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 session's `.tmp/` directory is purge-eligible by terminal state, not by age: it
+holds nothing durable, and losing it costs nothing. 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)
-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`](https://github.com/zalom/plastic/blob/main/docs/internals.md) for the
-full mechanism.
+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) is a coordination record at the
+file grain: it names who, among those already holding the delivery lock, is the one writer for
+one lifecycle file right now. 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. Since 2.0 nothing enforces a claim at write time; a team lead takes and
+releases claims through `plastic-lock claim` and `release-claim` to coordinate its executors,
+and `plastic-lock status` lists any live claims alongside the delivery lock. A stale or corrupt
+claim is reported there, never acted on. See [`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),
 shipped by intent 108. An earlier two-lock doctrine proposed a second `maintenance.lock`
@@ -72,8 +63,8 @@ for an active delivery. Maintenance instead DETECTS `delivery.lock`'s freshness
 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
+Every code-touching auto intent gets its own git worktree named `{id}--{slug}`, and all code
+edits for that intent happen 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
@@ -99,15 +90,16 @@ an orphaned worktree behind, and clear a stale worktree reference with `git work
 
 #### Intent delivery, station by station
 
-How one intent travels from boarding to Done, and what the lock, bridge, and gates do at
-each station.
+How one auto-team intent travels from boarding to Done, and what the lock, the pointer, and
+the record hook do at each station. Nothing in the third column blocks; the fourth column is
+what gets written down.
 
-| 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 | 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` |
+| Station | Delivered artifact | Lock and pointer steps | 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 session pointer | savepoint confirms the boarding station |
+| What (create) | `<id>--<slug>.md`, born complete | no lock yet; `new-intent` validates the file it writes (`scripts/validate-intent`) | savepoint `What` line; intent listed in INDEX `## Active` |
+| Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | savepoint `Why started`, `Why spec.md created` |
+| How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes | 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 | checklist boxes; savepoint milestones; the day-ledger line promotes when a project file lands |
+| 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 pointer is purge-eligible, and the QMD reindex runs LAST (after purge); `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | 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 | 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

@@ -55,9 +55,9 @@ meaning an active agent is delivering that intent. Maintenance DETECTS this lock
 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).
+No code freezes a terminal intent: since 2.0 (intent 302) nothing blocks a write anywhere,
+and before that the lock check already allowed any write once an intent left INDEX
+`## Active`. There never was a shipped freeze (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
@@ -82,8 +82,8 @@ already exists, a new run appends
 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.
+change, or refuse to proceed without one (`scripts/lib/revisions_writer.rb`); a hand-applied
+relocation holds itself to the identical rule.
 
 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
@@ -94,9 +94,9 @@ those tools perform the mutation and write the `revisions.md` receipt - never do
 
 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
+then ABANDONED before merge on a design pivot; nothing from it ever shipped. No such check
+runs today: a write to a terminal intent is allowed unconditionally, as is every other write
+since 2.0 (intent 302). 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,
@@ -115,8 +115,8 @@ legitimately accrued chain edge was destroyed by a hand-run restore and went und
 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
+session or burns credits. When a check cannot verify lock integrity it fails open, degrading
+to advisory (warn) rather than refusing. 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,
@@ -144,7 +144,7 @@ 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
+frontmatter edge to an intent that no longer exists), a relocation moves 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
@@ -212,7 +212,7 @@ dropped, and skips (never aborts on) any intent dir holding a fresh delivery loc
 
 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.
+- (a) hook prose tokens: the narration the lifecycle hooks emit into context.
 - (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/dashboard/SKILL.md

@@ -19,7 +19,7 @@ state → byte-identical payload, regardless of model. Do NOT hand-summarize int
 
 - User invokes `/plastic-dashboard`
 - User asks "where are we", "what's next", "what should I work on", "show me the intents"
-- `plastic-project-continuing` lands on the board on resume
+- `plastic-intent-continuing` lands on the board on a bare resume
 - `plastic-auto` reads `--json` to choose the next dispatchable intent
 
 ## Procedure (the Markdown board — default human surface)

package/skills/direct/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: plastic-direct
+description: Use when a prompt asks for a change, a fix, an edit, a file, or an answer, and no thinking conversation is open on an intent. Judges whether the work is small enough to run right now, asks one clarifying question when one answer would settle it, or offers a thinking intent when it would not. Do not use for a prompt that says "auto" or "continue", a prompt asking to start a new intent, or a prompt inside an open thinking conversation, which belong to plastic-auto, plastic-intent-continuing, plastic-intent-creating, and plastic-intent-speccing.
+user-invocable: false
+---
+
+# Direct mode
+
+Route the prompt in one read, then act. Direct work runs inline in this session, never through a
+dispatched agent, unless the user asks for agents.
+
+## 1. Estimate before you start
+
+Judge the prompt alone, before doing any of the work:
+
+1. Count the targets the prompt names, or that one grep finds.
+2. Require each change to be a named operation on a known target (rename this, add a check there,
+   delete that line), not an outcome ("clean it up", "make it faster").
+3. Budget about one minute per target and sum.
+4. At or under five minutes, run it now. Five minutes is an owner ruling, not a measured
+   threshold.
+5. A bounded sum above five minutes, offer a dedicated intent.
+6. An unknown target, or a change described only by its outcome, cannot be bounded. Ask one
+   question when one answer would supply the missing operation or target. Otherwise offer a
+   thinking intent. A target that only investigation can find is never settled by one
+   question.
+
+Tests or a build the prompt implies do not count against the budget. Verification is part of
+direct work, not a reason to leave direct mode.
+
+## 2. One question, then run
+
+A clarifying question is allowed in direct mode and does not by itself turn the request into a
+thinking intent. Ask one, then run. If the answer is still vague, offer a thinking intent rather
+than asking a second question or guessing.
+
+## 3. The routes
+
+| What the prompt looks like | Where it goes |
+|---|---|
+| Clear, and bounded at or under five minutes | Run it now, inline |
+| Clear, but the bounded estimate is above five minutes | Offer a dedicated intent, `plastic-intent-creating` |
+| Vague, and one answer would resolve it | Ask one clarifying question, then run |
+| Still vague after that one answer | Offer a thinking intent, `plastic-intent-speccing` |
+| Phrased as needing help rather than as an instruction | Offer grill plus a thinking conversation, `plastic-intent-speccing` |
+| Says "auto" explicitly | Hand off to `plastic-auto` |
+
+Read `references/request-signals.md` when a prompt sits on the boundary between two routes, for
+the 15 observable signals and the response each one selects.
+
+## 4. Record and verify
+
+- Verification in direct mode is the UI, the tests, or the user. There is no reviewer agent per
+  item.
+- Only a prompt that changes something on disk or produces an artifact becomes a checklist item.
+  A pure question is answered inline and recorded nowhere.
+- Direct work records into the day ledger that the per-session pointer names. Assume the pointer
+  exists. Never write it.
+
+## 5. What direct does not take
+
+The capture hook detects `auto` and `continue` before you read the prompt, so defer rather than
+keyword-match them yourself. `auto` goes to `plastic-auto`, and `continue` goes to
+`plastic-intent-continuing`. On `auto` with no registered intent, route through
+`plastic-intent-creating` first, because auto requires a registered intent. A prompt that arrives
+inside an open thinking conversation belongs to that conversation, not here.

package/skills/direct/references/request-signals.md

@@ -0,0 +1,59 @@
+# Request signals
+
+The table below is reproduced from
+`296--make-plastic-faster-small-work/resources/research--request-analysis.md`, the
+request-analysis research deposit of intent 296, with its source column renumbered against the
+eight-source list below. Read it when a prompt sits on the boundary between two routes. That
+deposit also carries seven worked examples, one per boundary, for a reader who wants them.
+
+## The signal table
+
+| Signal | What it looks like in a real prompt | Response it selects | Source or ruling |
+|---|---|---|---|
+| A concrete file and a concrete operation are named | "Rename `foo` to `bar` in `app/models/user.rb` and update its three callers." | execute now | D13, D14 |
+| The target is a single, already-known location | "Fix the typo in README.md line 12." | execute now | D14 |
+| The change is described only by its outcome, with no operation named | "Clean up the user model, it's gotten messy." | ask one clarifying question | Kamsties, "Understanding Ambiguity in Requirements Engineering" (source 5); D13 |
+| The prompt uses weak, hedging modal language ("might", "could", "maybe", "somewhere") | "This might need better error handling somewhere in the payment flow." | ask one clarifying question | "Automatic Detection of Ambiguous Terminology for Software Requirements" (weakness ambiguity, source 6); D13 |
+| The prompt admits several equally plausible readings with no cue that favors one | "Make the form better." (styling, validation, and accessibility are all live readings) | ask one clarifying question | "Knowing but Not Showing" (source 3); "Ask or Assume?" (source 1) |
+| One answer to the clarifying question fully resolves scope | User answers: "Just the null check on line 42, nothing else." | execute now | D10 |
+| The answer to the clarifying question is itself vague or open-ended | User answers: "I don't know, whatever seems right." | offer a thinking intent | D13; "Ask or Assume?" (source 1) |
+| The prompt is phrased as a request for help rather than an instruction | "I need help figuring out how to structure the billing refactor, not sure where to start." | offer a thinking intent | D13 |
+| The number of named or discoverable targets is small (roughly one to three) and each change is additive | "Update the copyright year in these three footer partials." | execute now | D14 |
+| The number of targets is large, or the work is described as spanning many files | "Migrate all 40 view partials to the new component library." | offer a thinking intent | D14 |
+| The target is not yet known and must be found by investigation before any edit is possible | "Something is causing the checkout page to be slow, find it and fix it." | offer a thinking intent | D14; sources 7 and 8 |
+| The action is destructive or hard to reverse and its scope is ambiguous | "Delete the old migrations directory." | ask one clarifying question | "Structured Uncertainty guided Clarification for LLM Agents" (source 4) |
+| The action is destructive but small, self-contained, and obviously scoped | "Delete the unused `tmp_debug.rb` file I just created." | execute now | D14 |
+| The request implies running tests or a build step the agent can run itself as part of verification | "Fix the failing test in user_test.rb." | execute now | D15 |
+| The prompt changes nothing on disk and produces no artifact | "What does the PaymentProcessor class do?" | execute now (answered inline; never admitted as a checklist item) | D17 |
+
+Row 8 uses the deposit's wording. Ruling D13 makes the help-needed route grill plus a
+thinking conversation, as `SKILL.md` section 3 states.
+
+## Rulings, not findings
+
+Four things in the table above are owner rulings with no literature behind them. Apply
+them, and know they are policy knobs the owner can turn, not measured results.
+
+- The five-minute total and the one-minute-per-target budget. Task-complexity research (sources 7
+  and 8) correlates target count and search depth with lower agent success, which supports
+  counting targets, but no source sets these numbers.
+- The one-question cap. The clarification research (sources 1, 2, and 4) treats question count as
+  a calibrated, cost-weighted choice that can be zero, one, or more. A hard cap of one is the
+  owner's choice.
+- "Auto" meaning auto mode. It is an interface convention, a keyword that names the mode instead
+  of asking for a judgement.
+- "Help needed" phrasing meaning grill plus a thinking conversation. It is a register cue
+  specific to how this owner phrases requests, not a general finding.
+
+## Sources
+
+1. "Ask or Assume? Uncertainty-Aware Clarification-Seeking in Coding Agents." https://arxiv.org/abs/2603.26233
+2. "Learning to Ask: When LLM Agents Meet Unclear Instruction." EMNLP 2025. https://aclanthology.org/2025.emnlp-main.1104.pdf
+3. "Knowing but Not Showing: LLMs Recognize Ambiguity but Rarely Ask Clarifying Questions." https://arxiv.org/pdf/2605.25284
+4. "Structured Uncertainty guided Clarification for LLM Agents." https://openreview.net/forum?id=dc8ebScygC
+5. Kamsties, Erik. "Understanding Ambiguity in Requirements Engineering." https://link.springer.com/chapter/10.1007/3-540-28244-0_11
+6. "Automatic Detection of Ambiguous Terminology for Software Requirements." https://www.eecis.udel.edu/~yuewang/paper/nldb2013.pdf
+7. "An Approach for Systematic Decomposition of Complex LLM Tasks." https://arxiv.org/html/2510.07772v1
+8. "On the Importance of Task Complexity in Evaluating LLM-Based Multi-Agent Systems." https://arxiv.org/html/2510.04311
+
+All eight were accessed 2026-08-29. The D-numbers in the table are decisions in `296/spec.md`.

package/skills/doctor/SKILL.md

@@ -13,7 +13,7 @@ Doctor has three scopes. Pick the right one for the situation:
 | Scope | Flag | When it runs | States |
 |-------|------|--------------|--------|
 | Core check | `--core` | SessionStart hook (automatic), also available on demand | Binary: pass or error |
-| Store check | `--store [global\|<slug>]` | Dashboard load, `plastic-project-continuing` | Three-state: pass / warn / fail |
+| Store check | `--store [global\|<slug>]` | Dashboard load, the project route of `plastic-intent-continuing` | Three-state: pass / warn / fail |
 | Full check | (no flag) | After every update (automatic), or `/plastic-doctor` | Three-state: pass / warn / fail |
 
 ### `--core` (binary, operational-readiness only)
@@ -51,8 +51,12 @@ Each manifest maps a file path to its SHA256.
 
 Checks the operations Plastic itself depends on in one store: QMD search reachability (scoped
 to that store's own collection; global uses `plastic-global`, a project slug uses
-`plastic-<slug>`), sources/chain resolution, cross-store resolution, INDEX parsing, and links
-projection. A project slug also checks tool readiness (Serena, Enola): each is a pass whether
+`plastic-<slug>`), sources/chain resolution, cross-store resolution, INDEX parsing, links
+projection, done signals (including `backfilled_complete`: a terminal intent still missing a
+real spec.md, plan.md, or action file), and, for the global store only, the session ledger
+(`orphaned_session_tmp`: a `.tmp/<session>/` directory whose heartbeat is older than 24
+hours; `day_ledger_shape`: a `.sessions/` entry that is not a `YYYYMMDD` day directory with
+its `<day>.md`). A project slug also checks tool readiness (Serena, Enola): each is a pass whether
 present or absent, present naming it available, absent noting it as an optional integration
 never installed by doctor. Scope options:
 
@@ -86,10 +90,6 @@ 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
@@ -159,10 +159,13 @@ Use the `fix_hint` value to determine the correct action:
 | "Add missing entries to INDEX.md" | Add orphaned intents to the appropriate INDEX.md section |
 | "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 |
+| "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (see Provisioning a project store below) to create the missing store |
 | "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. |
+| "Relocate ... revisions.md ..." | 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. |
+| "Write the missing documents from the record via `scaffold-intent backfill ...`" | Run `ruby ~/.plastic/scripts/scaffold-intent backfill --store <store> --id <id> --disposition <delivered\|abandoned>` for each listed intent; it fills only missing or placeholder files and never touches real content |
+| "Remove each listed .tmp/<session>/ directory after confirming that session is gone" | For each listed directory, confirm no live session uses it (a live session rewrites its heartbeat on every prompt and edit), then remove that directory by hand; never remove an unlisted one |
+| "For a day directory missing its <day>.md, run `file-session-intent --day <day> ...`" | Run `ruby ~/.plastic/scripts/file-session-intent --day <day> --carry-to <today> --store <store>` for the named day; rename or remove an entry that is not a `YYYYMMDD` day directory |
 | "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
@@ -247,6 +250,50 @@ removes exactly the dead rows through the same writer and commit, but holds back
 intent dir carries a fresh lock or has not gone terminal yet (nothing to suppress there yet),
 naming both as kept.
 
-## References
+## Locks (auto teams only)
+
+Locks exist for auto teams: a `delivery.lock` file in the intent directory names the owning
+session, and the `record` hook refreshes its mtime on every edit (the lease heartbeat; stale
+means older than the TTL). Direct work takes no lock. When a lock reads held by a session
+that is gone, when work resumes after a crash, reboot, or `/tmp` wipe, or when the user says
+"fix the lock", "who holds the lock", or "reclaim the lock", use the CLI (intent 304 folded
+the former locking skill here):
+
+| Verb | What it does | When |
+|---|---|---|
+| `who` | Owner, heartbeat, claims, delegates, from durable files only | Safe inspection; needs `--intent-dir` |
+| `status` | Lock file, freshness, the derived worktree, whether this session's pointer names the intent, claims | Always safe; run first |
+| `fix` | Idempotent repair from disk truth for this session; never touches a fresh foreign lock | Interrupted work, corrupt state, `/tmp` wiped |
+| `release` | The owner clears the lock | Ending or abandoning an auto delivery |
+| `reclaim` | Explicit takeover of a stale lock; appends an audit line to `savepoint.md` | The owner is gone and the lease expired |
+| `delegate` | The owner registers a subagent session, or marks it `finished` or `failed` | Auto-team orchestration |
+
+```
+ruby ~/.plastic/scripts/plastic-lock status --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock who --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock reclaim --intent-dir <store>/<id>--<slug>
+```
+
+`fix` exits non-zero when another session holds a fresh lock: back off, `status` shows the
+owner. `reclaim` refuses a fresh lock; every takeover is audited. The lock file's mtime is the
+sole freshness truth. Never delete a lock file by hand. Read
+`../plastic-conventions/references/locks-and-worktrees.md` when a lock question goes beyond
+these verbs (claims, worktrees, the station ledger).
+
+## Provisioning a project store
+
+When a project is registered in `~/.plastic/projects.yml` but has no store on disk (doctor
+reports `project_store_dir`), provision it (intent 304 folded the former provisioning skill
+here). The slug is the project's key under `projects`; an unregistered slug exits non-zero and
+creates nothing, and this procedure never edits `projects.yml`.
+
+```bash
+ruby ~/.plastic/scripts/provision-project-store <slug>
+ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
+```
 
-- 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
+The provisioner is pure filesystem and idempotent: it creates
+`~/.plastic/projects/<slug>/store/` with `.gitkeep`, writes `INDEX.md` and `project.yml` only
+when missing, and never clobbers. The QMD registration is a separate, optional step that
+no-ops when QMD is absent. New projects are provisioned by `plastic-project-creating`, not here.

package/skills/doctor/report.md

@@ -18,6 +18,8 @@
        core_files         -> "Core Files"
        project_stores     -> "Project Stores"
        deprecations       -> "Deprecations"
+       done_signals       -> "Done Signals"
+       session_ledger     -> "Session Ledger" (global store only)
   4. For each check within a category, emit one line with the status icon
      and the check message. If the check has non-empty details, list them
      as indented sub-items.
@@ -59,7 +61,7 @@ Checked at: {{timestamp}}
 - [PASS] Claude Code adapter registered
 - [FAIL] 2 hook scripts not executable
   - ~/.claude/hooks/plastic-session-start
-  - ~/.claude/hooks/plastic-gate-check
+  - ~/.claude/hooks/plastic-record
 
 <!-- =====================================================================
   Repeat the above pattern for each category found in the checks array.

package/skills/install/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plastic-install
-description: 'Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. First install defaults to --latest (stable); reinstalls match the already-installed channel. Global install is recommended: it creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.'
+description: 'Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. The package pin selects the channel (@latest, @beta, @alpha; the channel flags were removed in 2.0). First install defaults to @latest (stable); reinstalls match the already-installed channel. Global install is recommended: it creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.'
 user-invocable: true
 ---
 
@@ -16,8 +16,10 @@ user-invocable: true
 
 If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
 `-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
-(first install), default to `@latest`. The user can always override with
-`--alpha` / `--beta` / `--latest`.
+(first install), default to `@latest`. To change channel, pin the package instead of
+passing a flag: `npx -y @zalom/plastic@alpha install --claude` (or a version such as
+`@2.0.0-alpha.1`); the `--alpha`, `--beta`, and `--latest` flags were removed in 2.0
+(intent 310) because they never selected a package.
 
 ## Re-install / repair
 
@@ -31,13 +33,13 @@ npx -y @zalom/plastic@<channel> install --reinstall --claude
 
 Then **run `/plastic-doctor`** and report what it found.
 
-## Channel Flags
+## Channels
 
-| Flag | Behavior |
-|------|----------|
-| `--latest` | Install from the stable channel (default on a first install) |
-| `--beta` | Install from the beta channel |
-| `--alpha` | Install from the alpha channel |
+| Package | Channel |
+|---------|---------|
+| `@zalom/plastic@latest` | stable (default on a first install) |
+| `@zalom/plastic@beta` | beta |
+| `@zalom/plastic@alpha` | alpha; `npx -y @zalom/plastic@alpha install --claude` is the 2.0 alpha path |
 
 When invoked from within Claude Code (re-install or channel switch), the skill
 runs the appropriate npx command: