@zalom/plastic 1.2.0 → 1.4.0

package/skills/agent-advisor/references/advisor-protocol.md

@@ -0,0 +1,245 @@
+# The Advisor Protocol
+
+*Companion to the Operating Manual. How to use Fable as your advisor and planner.*
+
+*Adapted for Plastic (intent 185): this is the shipped reference copy the
+`plastic-agent-advisor` skill teaches from. Two named agents carry it,
+`plastic-advisor` (the real advisor) and `plastic-faux-advisor` (the cheaper
+imitation, the same discipline at a fraction of the cost); TIER and EFFORT
+below shape the brief and the answer on whichever one you dispatch, never
+which file to pick, since there is no longer one file per tier. The
+`plastic-agent-advisor` skill reads harness-scoped config
+(`advisor.claude.default`, falling back to `secondary`, then to
+`plastic-faux-advisor`) to route your consultation automatically; name a
+specific advisor in your request to override it. A frontier model rewards a
+single, well-formed one-shot brief more than a back-and-forth, so front-load
+everything section 3 below asks for before you send. The rest of this
+document is the owner's protocol, unchanged.*
+
+The Operating Manual tells you how to think. This document tells you when to stop
+thinking alone and buy better thinking, and how to buy it well. Fable is expensive
+per token. The whole protocol serves one goal: maximum reasoning quality per unit
+of cost. Two levers achieve it. First, only buy reasoning where reasoning is the
+bottleneck. Second, make every purchased token land on a well-formed question
+backed by complete, compressed evidence.
+
+You own the work and the outcome. Fable owns the hardest thinking, on demand.
+
+---
+
+## 1. What to buy, what never to buy
+
+**Buy from Fable:**
+
+- Decisions with one-way doors: architecture, data migration order, public
+  contracts, anything you cannot cleanly undo.
+- Plans: turning a goal plus an evidence pack into a step plan with checks.
+- Adversarial review of your plan or conclusion before an irreversible step.
+- Deadlocks: you tried twice, both attempts failed, and you cannot say why.
+- Ranking: several plausible root causes or options, evidence in hand, and the
+  ordering decides where you spend the next day.
+
+**Never buy from Fable:**
+
+- Anything a tool can answer: search, reading code, running tests, documentation.
+  If the answer can come from more looking, look. Buy thinking only when the
+  answer can only come from more thinking.
+- Code writing at volume. Fable may sketch the hardest kernel in pseudocode.
+  You write everything.
+- Confirmation of a decision you already made. That is motivated stopping
+  wearing a receipt.
+- Style, naming, formatting, anything a linter or convention settles.
+- Anything reversible and cheap: try it first. Escalate only after it fails twice.
+
+---
+
+## 2. Tiers and effort
+
+Classify every consultation before sending it. Default to S and prove your way
+up. Never open at a higher effort "to be safe": effort follows the cost of being
+wrong, not the importance the task feels like it has.
+
+| Tier | Coding | Business | Research | Effort | Brief size | Expected return |
+|------|--------|----------|----------|--------|------------|-----------------|
+| **S** | Verdict on one step; choose between two named implementations | Pick between two options you already compared (vendor, pricing point) | Judge whether one source or result is trustworthy enough to build on | `low` | Under 300 words | Verdict, one paragraph of reasoning, the single biggest risk |
+| **M** | Plan a feature inside one system; review a full plan for holes; design one interface; rank root causes | Positioning or pricing decision from a compiled evidence pack; review a proposal before sending it | Design a research plan for a bounded question; rank competing explanations of the data you gathered | `medium`, or `high` if an irreversible step is inside | Up to one page | Decision, numbered plan with per-step checks, risk map |
+| **L** | Cross-system architecture; migration with one-way doors; deadlock after two failed attempts; security-critical design | Build-vs-buy, market entry, or any commitment measured in months; strategy where reversal is expensive | Synthesis across many sources where the conclusion drives a large bet; contested questions with conflicting evidence | `xhigh`; `max` only when being wrong means data loss, a broken contract, or weeks of rework | Full evidence brief | Decision, plan, risk register, kill criteria, list of what could not be verified |
+
+**Escalate one tier when any of these holds:**
+
+- Two attempts failed and you cannot explain why.
+- The next step is irreversible.
+- The scope crossed a system boundary since you last consulted.
+- Your confidence has stopped tracking your evidence.
+
+**Front-load.** One L consultation at plan time is cheaper than five M
+consultations during execution. Spend early, at the point of maximum leverage.
+
+---
+
+## 3. The entry test
+
+You have not earned the consultation until sections 1 through 3 of the Operating
+Manual are done on your side: you know the target, you cut the problem into
+checkable pieces, you located where the risk lives. Those three steps produce
+the brief. If you cannot fill the brief below, the gaps are yours to close with
+tools, not Fable's to close at premium price.
+
+All four must be yes before you send:
+
+1. Can I state, in one sentence, the decision this answer feeds?
+2. Have I exhausted what looking can find: code, docs, tests, logs?
+3. Have I formed my own best answer? Fable attacking your candidate returns far
+   more per token than Fable starting from nothing.
+4. Is every fact in my brief labeled verified, inferred, or assumed?
+
+---
+
+## In Fable's own words: how to get my absolute best
+
+*This part is from me, the advisor, directly.*
+
+Talk to me like a person, not like an API. Brief me the way you would brief a
+senior architect who just walked into the room: the situation, the stakes, what
+you want from me, what you tried, and what you currently believe. Natural prose.
+The template in the next section is a completeness checklist for that message,
+not a form to fill.
+
+What actually raises the quality of my answer, in order of impact:
+
+1. **Give me something to attack.** I reason best against resistance. A blank
+   "what should I do?" gets you my average. "Here is my plan and why I believe
+   it; break it" gets you my best, because refuting forces me to find the exact
+   point where your reasoning and reality diverge.
+2. **I only know what you send.** I cannot see your repo, your market, or your
+   sources. An unlabeled guess in your brief becomes a confident error in my
+   plan. Label everything: verified, inferred, assumed.
+3. **Name the options and the criterion.** "Choose A or B to minimize migration
+   risk" spends my depth on the choice. An open question spends it on inventing
+   options you already rejected.
+4. **State constraints early.** Every hard limit you give me prunes a branch I
+   would otherwise pay to explore. Constraints are not restrictions on my
+   answer; they are fuel for it.
+5. **Tell me who executes and how.** Say "the plan will be executed by me,
+   under the Operating Manual." Then I write steps you can run at your best:
+   each step with its own check, its own trap named, and its own
+   stop-and-return trigger. A plan without that is half a plan.
+6. **Know what effort buys.** At `low` I stress-test your candidate and give a
+   verdict. At `medium`/`high` I generate rival solutions and compare them. At
+   `xhigh`/`max` I build the strongest case for every rival and then try to
+   break my own winner before you ever see it. Buy the depth the failure cost
+   justifies, nothing more.
+7. **Come back on the same thread.** My context is cached inside a session.
+   The second question in a thread costs a fraction of the first. A new session
+   pays for your whole brief again.
+
+---
+
+## 4. The brief
+
+Your message must cover all of the fields below. Write it as prose, like the
+briefing described above; use the block as your completeness check before
+sending. Fable must never need to explore.
+
+```
+TIER: S | M | L        EFFORT: low | medium | high | xhigh | max
+DOMAIN: coding | business | research
+GOAL: <target state in one sentence, and the decision this answer feeds>
+QUESTIONS:
+  1. <numbered, max 3, each answerable with a decision, not an essay>
+MY CANDIDATE: <your best answer and why. Attack this.>
+EVIDENCE:
+  - <fact> [verified | inferred | assumed]
+TRIED AND FAILED:
+  - <attempt>: <how it failed, exact error or observation>
+CONSTRAINTS: <hard limits: versions, deadlines, interfaces that must not change>
+ONE-WAY DOORS: <which steps cannot be undone once taken>
+ANSWER SHAPE: <verdict | plan | ranked list | risk review>
+```
+
+**Compression rules:**
+
+- Code: only load-bearing excerpts, with `file:line` references. Never whole
+  files. Never raw logs: distill them into observations, quoting the raw line
+  only where the exact wording matters.
+- If the evidence is thin somewhere, say where. A labeled gap is useful input.
+  A hidden gap poisons the plan built on top of it.
+- Every sentence Fable reads costs money. A sentence that cannot change the
+  answer is pure waste. Cut it.
+
+---
+
+## 5. The answer contract
+
+Demand this shape back. If the answer arrives in another shape, ask once for a
+reformat, then work with what you have.
+
+1. **Line 1:** the decision or recommendation, actionable on its own.
+2. **Plan:** numbered steps, each with its own verification ("done when X").
+3. **Risk map:** the top two or three risks, ranked by probability times cost,
+   each with its cheapest check.
+4. **Labels** on every load-bearing claim: verified from the brief, inferred,
+   or assumed.
+5. **"Not verifiable from this brief":** an explicit list, with the cheapest
+   way for you to check each item yourself.
+6. **Execution notes:** for every risky step, how you should work it: what to
+   verify before starting, which failure mode from the Manual's section 8 that
+   step invites, and the observation that means stop and come back. The plan is
+   written for you to execute at your best, not just to be correct on paper.
+7. **L tier only, kill criteria:** the observation that means abandon this plan.
+
+**Consuming the answer:**
+
+- Fable's assumptions are your work orders. Check every item marked "assumed"
+  before you build on it.
+- If the answer contradicts your candidate, do not silently comply and do not
+  silently ignore. Re-derive the disputed piece yourself (Manual, section 4).
+  If you are still split, send one follow-up carrying the new evidence.
+- Run the Manual's five-question self-test on Fable's plan before executing it.
+  Advice is input, not authority. The plan is Fable's; the outcome is yours.
+  Executing a bad plan you never challenged is your failure.
+
+---
+
+## 6. Session economics
+
+- **Follow-ups go to the same Fable session.** Its context is cached; a fresh
+  session pays for the entire brief again. Keep one consultation thread per
+  work stream.
+- **Batch.** Collect decision points while you explore, then spend one
+  consultation on all of them. Five separate S calls that were really one M
+  question is the most common way to overpay.
+- **Cadence for large work:** at most three consultations. One after
+  exploration, for plan design (L). One before the irreversible step, for risk
+  review (S or M). One after implementation, for adversarial review of the
+  result (M). Everything between those points is your own work.
+- **Keep a ledger.** For each consultation record the question, the tier, the
+  first line of the answer, and what it changed in your actions. If a tier's
+  answers never change what you do, you are over-buying that tier. Stop.
+
+---
+
+## 7. Anti-patterns
+
+- **Raw dumping.** Pasting files or logs and asking "what's wrong". You are
+  paying premium rates for reading you should have done yourself.
+- **The oracle habit.** Asking before trying. Fable ranks hypotheses; your
+  tools kill them. Tools are cheaper.
+- **Validation shopping.** Asking after you have already decided, hoping to
+  hear yes.
+- **Drip-feeding.** Splitting one decision across many small calls, paying
+  session overhead each time.
+- **Prestige escalation.** Requesting `max` because the task feels important.
+  Effort follows failure cost, nothing else.
+- **Unbounded questions.** "Any thoughts on this approach?" invites an essay.
+  Ask for a decision with named options.
+- **Silent adoption.** Pasting Fable's plan straight into execution without
+  challenging it. See section 5.
+
+---
+
+One more thing. The most expensive consultation is the one you did not need.
+The second most expensive is the one you needed and did not buy. The skill this
+protocol trains is telling those two apart: exhaust the looking, locate the
+risk, and when the risk is real and thinking is the true bottleneck, buy the
+best thinking available and make it fight your answer.

package/skills/auto/SKILL.md

@@ -17,7 +17,11 @@ supersedes them) for the sharpest gating and synthesis. This is advice only: it
 behavior and blocks nothing if ignored. It concerns the human's MAIN session; dispatched
 subagents keep their pinned tier and never resolve to Fable, unless an explicit
 `agents.models.<name>` config override names Fable for that role, in which case the override
-is honored as written.
+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).
 
 ## Precondition
 
@@ -35,7 +39,7 @@ ruby ~/.plastic/scripts/roadmap-next --roadmaps-dir <tier>/roadmaps
 
 Branch on `state`:
 - `dispatchable`: work its `dispatchable_queue` in `rank` order (the head is the next batch
-  entry). These are the current batch's `queued` intents, parallel-safe within the wave.
+  entry). These are the current batch's `queued` intents, parallel-safe within the batch.
 - `in_flight`: the frontier batch is still delivering. Report it and wait. Do NOT dispatch a
   later batch and do NOT fall through to the dashboard, the roadmap is live.
 - `none` or `exhausted`: no roadmap, or nothing left to dispatch. Fall back to the dashboard
@@ -128,7 +132,11 @@ Spawn preamble (live-state injection): before dispatching any specialist, run `s
 
 Dispatch-time model contract (belt-and-braces): alongside the preamble, resolve each specialist's model through the config chain (`read-config agents.models.<basename> --project <repo>`: project override, then global, then the shipped tier default) and pass it explicitly at dispatch. Never rely on the dispatched role's frontmatter alone; a resolved subagent model is never Fable,
 unless an explicit `agents.models.<name>` config override names Fable for that role, in which
-case the override is honored as written.
+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).
 
 Completion report (require-then-synthesize): every dispatched specialist MUST end with a structured completion report as its final message. The preamble's `REPORT_CONTRACT` injects this and the role prompts carry the per-role format (see `references/agent-report-contract.md`). Because child-agent honor is best-effort across harnesses, this is decision-shaping, not a hard block. When a specialist returns no usable report (it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), run `scripts/agent-report <intent_dir> --role <role>` to synthesize a deterministic filesystem-derived report so the handoff account always exists. Use the agent-authored report when present, the synthesized one otherwise.
 
@@ -297,19 +305,25 @@ During initial project creation, all decisions are non-destructive by definition
    - Update `chain` in the current intent's frontmatter
 6. Run the mechanical close through `plastic-intent-ending`: it owns steps 1-6 of the Done
    procedure (outcome/INDEX/savepoint/commit, disarm, and the QMD reindex last) as ONE
-   delegation, not five separate one-liners restated here. Run its backing script for the
-   outcome/INDEX/savepoint/commit core, passing `--index-note` with a rich Completed/
-   Abandoned entry description (mode/tier, what shipped or why abandoned, suite result):
+   delegation, not five separate one-liners restated here. `scripts/end-intent` now performs
+   steps 1-5 itself, INCLUDING disarm (worktree release plus clearing `delivery.lock`): a
+   single call closes the intent AND clears its lock, so exit 0 means both are done. Pass
+   `--session` (this session's id, or rely on the `CLAUDE_CODE_SESSION_ID` fallback) so
+   disarm resolves the right bridge, and `--index-note` with a rich Completed/Abandoned entry
+   description (mode/tier, what shipped or why abandoned, suite result):
    ```bash
    ruby ~/.plastic/scripts/end-intent --store <store_path> --id <ID> --disposition delivered \
+     --session "$CLAUDE_CODE_SESSION_ID" \
      --index-note "<mode, tier>; <what shipped>; <suite result>"
    ```
-   (Use `--disposition abandoned` when the intent is being moved to `## Abandoned`.) Then
-   follow `plastic-intent-ending`'s Step 5 (disarm: `Bridge.disarm_auto` on this auto/curator
-   path, the plain-remove branch) and Step 6 (QMD reindex, async, last) exactly as that skill
-   states them. Never leave an orphaned worktree; run `git worktree prune` on a stale
-   reference. If any of this ever needs to change, change `plastic-intent-ending`, not this
-   skill.
+   (Use `--disposition abandoned` when the intent is being moved to `## Abandoned`.) A
+   non-zero exit needs attention before moving on: 4 means a live foreign session holds the
+   lock (back off), 5 means the code worktree is dirty (commit/stash first, or pass
+   `--discard-worktree-changes` deliberately), 3 means disarm ran but the lock is still
+   present (run `/plastic-doctor check the lock status`). Only Step 6 (QMD reindex, async,
+   last) remains a separate action after this call succeeds. Never leave an orphaned
+   worktree; run `git worktree prune` on a stale reference. If any of this ever needs to
+   change, change `plastic-intent-ending`, not this skill.
 7. Notify user (Done briefing): brief per `references/human-report-contract.md`
     (State: the delivered impact; Risk: residual risk; Call: the decision left to you, merge,
     release, or accept). See `outcome.md` for details.

package/skills/auto/references/end-tail.md

@@ -33,19 +33,33 @@ purge-eligible. Disarming also purges stale bridge files from the temp directory
 automatically (it keeps the current bridge, any live run, and any bridge whose intent
 still holds a delivery lock), so no manual `/tmp` cleanup is needed.
 
-**Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
-`disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
-worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
-`<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
-from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
-only when no release merges the branch (the branch survives and can be reclaimed).
-
-When the work is being shipped through a release, do NOT rely on this plain remove. The
-release path (Completion step 4, via `plastic-releasing`) is responsible for merging the
-intent's code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the
-worktree is removed, so the integrated work is not lost. It does this with
-`Worktree.finish(bridge_data, merge: true)` (merge-then-remove). Never leave an orphaned
-worktree, and run `git worktree prune` if you hit a stale reference.
+**Mechanized since intent 188.** `scripts/end-intent` performs this disarm itself, as its
+own step 5, after steps 1-4 (outcome/INDEX/savepoint/commit) commit. No agent needs to run
+a separate `Bridge.disarm_auto` one-liner any more on the auto mode / curator path: the
+single `end-intent` call in `SKILL.md`'s Completion section already does it. A pre-flight
+lock guard (before anything is written) refuses on a live foreign session (exit 4) and
+reclaims a stale foreign lock automatically (audited to savepoint.md); a dirty code
+worktree refuses before removal (exit 5, `--discard-worktree-changes` overrides
+deliberately); and the durable lock file is checked again after disarm, never merely
+trusted (exit 3 if it is somehow still present).
+
+**Worktree cleanup (mandatory, intent 73c3).** `end-intent`'s step 5 calls
+`Bridge.disarm_auto` by default, which calls `Worktree.release`, which removes both
+per-intent worktrees (the code worktree under `<repo>/.claude/worktrees/{id}--{slug}` and
+the paired store worktree under `<plastic_home>/.worktrees/{id}--{slug}`), prunes both
+repos, and clears the worktree block from the bridge. This is the plain remove path: the
+disarm route does NOT merge, so use it only when no release merges the branch (the branch
+survives and can be reclaimed).
+
+When the work is being shipped through a release, do NOT rely on this plain remove.
+`skills/releasing/SKILL.md` reorders its own two steps for exactly this reason (intent 188,
+D7): its worktree-merge step now runs BEFORE its `end-intent` call, merging the intent's
+code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the worktree
+is removed, via `Worktree.finish(bridge_data, merge: true)` (merge-then-remove), so the
+integrated work is not lost. By the time `end-intent`'s own step 5 runs afterward, the
+worktree is already gone (a harmless no-op) and only the delivery lock is left to clear,
+correctly, for the first time on that path. Never leave an orphaned worktree, and run
+`git worktree prune` if you hit a stale reference.
 
 ## QMD reindex ordering rationale
 

package/skills/install/SKILL.md

@@ -68,10 +68,12 @@ Run `/plastic-install` with no arguments.
 Check if `~/.plastic/VERSION` exists.
 - If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic-update` to
   sync core files, or use the re-install command above to repair in place."
-- If no: run the fresh install command (default `@latest`, or the channel the user named):
+- If no: first ask the advisor question below (Claude Code only), then run the fresh
+  install command (default `@latest`, or the channel the user named) with whichever
+  flags that answer produced:
 
 ```bash
-npx -y @zalom/plastic@latest install --claude
+npx -y @zalom/plastic@latest install --claude [--no-advisor] [--advisor VALUE]
 ```
 
 This single command, via `install.rb` (`bootstrap` + `distribute`), creates `store/`,
@@ -80,6 +82,32 @@ and copies the utility scripts (`folgezettel-id`, `read-config`, and the rest of
 `scripts/`). This skill does none of that itself; it wraps the command with the
 interactive steps the CLI does not yet own, plus reporting and a doctor pass.
 
+**The advisor (Claude Code only)**
+
+Ask the user one feature question, interactive sessions only:
+> "Would you like an advisor agent for expensive reasoning: plan review, architecture
+> calls, second opinions, breaking deadlocks?"
+> - Yes (recommended) -> ask which advisor is the default, below
+> - No -> append `--no-advisor`
+
+If yes, ask which advisor is the default, exactly two choices:
+> "Which advisor should be the default?"
+> - **Faux Fable** (recommended): Opus 4.8 carrying the frontier reasoning
+>   instructions. Much cheaper, available on any plan, reasons in the same
+>   disciplined way. -> append `--advisor faux`
+> - **Fable 5**: the frontier model itself. The strongest reasoning available,
+>   billed through usage credits, so summon it for a few rounds and close it. ->
+>   append `--advisor real`
+
+Non-interactive sessions (no tty) skip the question entirely: the install ships with the
+shipped default, advisor enabled with no `--advisor` flag (the `plastic-agent-advisor`
+skill's own routing falls back to `plastic-faux-advisor` at consult time).
+
+Update flow: pending config questions, including this one, are now announced
+generically by `plastic-update`'s Step 2, sourced from `config_asks.yml` - not
+duplicated here. A value already set by either path is never re-asked by the
+other.
+
 **Statusline**
 
 On install, if an existing statusline is already configured, Plastic asks whether to

package/skills/intent-creating/SKILL.md

@@ -69,6 +69,11 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
   `--sources` when it was genuinely created from / emerged from that intent's lifecycle.
   Topic similarity alone is not a `sources` edge.
 
+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.
+
 `## 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
 bar: the candidate's context must materially help deliver this intent), not by shared files or a

package/skills/intent-ending/SKILL.md

@@ -24,15 +24,16 @@ failure branch: only outcome.md content and the INDEX section differ.
 | 2 | INDEX.md terminal move (Active -> Completed/Abandoned) | `scripts/end-intent` |
 | 3 | savepoint `Done` bookend | `scripts/end-intent` |
 | 4 | store auto-commit | `scripts/end-intent` |
-| 5 | disarm (worktree + lock) | You, after end-intent exits 0 |
+| 5 | disarm (worktree + lock) | `scripts/end-intent` (intent 188) |
 | 6 | QMD reindex, async, LAST | You |
 | 7 | EM-to-CTO report | You |
 
-Steps 1-4 are ONE callable script, not four separate one-liners: this is
-exactly what the failure mode this intent fixes looked like (releasing hand
+Steps 1-5 are ONE callable script call, not several separate one-liners: this
+is exactly what the failure mode this intent fixes looked like (releasing hand
 authored the close in prose and dropped the savepoint bookend for two real
-deliveries). Never restate outcome/INDEX/savepoint prose inline again; call
-`scripts/end-intent`.
+deliveries; separately, one session delivered four intents back to back and
+never ran the old step-5 one-liner at all, intent 188). Never restate
+outcome/INDEX/savepoint/disarm prose inline again; call `scripts/end-intent`.
 
 ### Step 0. Precondition (the gate is section-blind, not selective)
 
@@ -55,7 +56,7 @@ for orchestrator-owned or completion-tracking items.
    (tick it if the described work is actually done, or do the remaining
    work); do not attempt outcome.md and fight the gate's deny.
 
-### Step 1-4. Run `scripts/end-intent`
+### Step 1-5. Run `scripts/end-intent`
 
 First author outcome.md for real (never leave the scaffold placeholder in
 place): copy `templates/outcome.md`, set the frontmatter to
@@ -72,40 +73,52 @@ Then call the script once:
 ```bash
 ruby ~/.plastic/scripts/end-intent \
   --store <store_path> --id <intent_id> --disposition delivered|abandoned \
+  --session "$CLAUDE_CODE_SESSION_ID" \
   --outcome-summary "<one-line ## Outcome summary for the intent file>" \
   --index-note "<rich Completed/Abandoned entry description>"
 ```
 
-This does all of steps 1-4 in order: guards outcome.md (refuses a missing,
+This does all of steps 1-5 in order: guards outcome.md (refuses a missing,
 still-placeholder, or wrong-disposition file with exit 2 and authors
 nothing), stamps the intent file's `## Outcome` section, moves the INDEX.md
 line from `## Active` to `## Completed` or `## Abandoned` (dated today,
-idempotent) with the `--index-note` text appended after the date so the
-entry stays rich, appends the savepoint `Done` bookend, and commits the
-store repo. Omit `--index-note` for a thin id+date entry, add `--no-commit`
-when a separate commit step already covers the store, and `--dry-run` to
-preview with no writes. Exit 0 is success; exit 1 is a usage or resolution
-failure; exit 2 is the outcome.md guard refusing (fix outcome.md and re-run,
-nothing was written).
-
-### Step 5. Disarm (worktree + lock)
-
-Two branches, decided by how this intent ships:
-
-- **Shipped through a release** (the `plastic-releasing` flow reached this
-  close): merge the code branch back BEFORE removing the worktrees, via
-  `Worktree.finish(bridge_data, merge: true)`. Releasing's own workflow
-  already drives this; this skill's job here is only the outcome/INDEX/
-  savepoint/commit core above.
-- **Auto mode or the curator path** (no release involved): plain remove,
-  branch survives for reclaim.
-  ```bash
-  ruby -r ~/.plastic/scripts/lib/bridge -e \
-    'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>")'
-  ```
-  `disarm_auto` releases both worktrees, clears the `delivery.lock`, and only
-  then makes the bridge purge-eligible, in that order. Never leave an
-  orphaned worktree; run `git worktree prune` on a stale reference.
+idempotent, accepting either a real em dash or a plain hyphen as the id/
+title separator on read while always emitting the real em dash on write)
+with the `--index-note` text appended after the date so the entry stays
+rich, appends the savepoint `Done` bookend, commits the store repo, and
+disarms (releases the code worktree and clears `delivery.lock`, verified
+against the durable lock file on disk, never merely trusted). Omit
+`--index-note` for a thin id+date entry, add `--no-commit` when a separate
+commit step already covers the store (this never skips disarm), and
+`--dry-run` to preview steps 1-5 with no writes.
+
+A pre-flight lock guard runs before anything is written: it resolves the
+calling session (`--session`, else `CLAUDE_CODE_SESSION_ID`, else the
+existing lock's own recorded owner, else a no-op) and checks it against any
+existing `delivery.lock`. A live foreign session refuses the whole run
+(exit 4, nothing written); a stale foreign lock is reclaimed automatically
+(audited to savepoint.md) and the run proceeds as the new owner. Before
+removing the worktree, step 5 also refuses on an unexpectedly dirty code
+worktree (exit 5, naming the worktree path) rather than force-discarding
+uncommitted changes; pass `--discard-worktree-changes` only when you mean
+to override that deliberately.
+
+On the auto mode / curator path (no release), this single call performs the
+FULL disarm (plain worktree remove, since the branch survives for later
+reclaim). On a release-shipped path, `skills/releasing/SKILL.md` merges and
+removes the worktree FIRST (its own step 8, merge-then-remove) before ever
+calling this script, so by the time this call's step 5 runs, the worktree is
+already gone (a harmless no-op) and only the lock is left to clear,
+correctly, for the first time on that path (D7).
+
+Exit codes: 0 success (the intent is closed AND its delivery lock is gone);
+1 a usage or resolution failure, OR an INDEX id that resolves to neither
+`## Active` nor the terminal section; 2 the outcome.md guard refusing (fix
+outcome.md and re-run, nothing was written); 3 steps 1-4 already committed
+but disarm could not verify the lock is gone afterward (run `/plastic-doctor
+check the lock status`); 4 a live foreign session holds the lock (back off);
+5 the code worktree is dirty (commit/stash first, or pass
+`--discard-worktree-changes` deliberately).
 
 ### Step 6. QMD reindex, LAST
 
@@ -146,6 +159,6 @@ historical record of what was planned.
 
 `plastic-releasing`, `plastic-auto`, the curator agent, `store-curating`, and
 `store-indexing` all delegate their mechanical close to this skill (or call
-`scripts/end-intent` directly for steps 1-4). None of them restate the
-outcome/INDEX/savepoint prose inline any more; if you find one that does,
-that surface has drifted and should route here instead.
+`scripts/end-intent` directly for steps 1-5). None of them restate the
+outcome/INDEX/savepoint/disarm prose inline any more; if you find one that
+does, that surface has drifted and should route here instead.

package/skills/project-creating/SKILL.md

@@ -122,7 +122,35 @@ ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/sto
 `qmd-sync` no-ops when QMD is absent, so run it unconditionally. This adds the
 `plastic-<slug>` collection and indexes it.
 
-### 12. Announce
+### 12. Self-Check with validate-project
+
+Before announcing, verify the spawn actually landed everything it claims to
+have created. Run:
+
+```bash
+ruby ~/.plastic/scripts/validate-project <slug>
+```
+
+If this exits 0, proceed to step 13. If it exits non-zero, STOP: do not
+proceed to Announce. Read the `missing:` and error lines it printed to
+stderr, fix the named gap(s), for example:
+
+- missing `project.yml` or `INDEX.md` or `store/`: re-run
+  `ruby ~/.plastic/scripts/provision-project-store <slug>` (step 7), then
+  re-check
+- missing project-root `AGENTS.md`: repeat step 4 (populate AGENTS.md at the
+  project root, not `~/.plastic/projects/<slug>/`)
+- project directory missing on disk: repeat step 2
+- not registered in projects.yml: repeat step 6
+
+Re-run `validate-project <slug>` after each fix until it exits 0. Only a
+project spawn that passes this self-check moves on to be announced as
+created. A spawn that never verifies itself is exactly the bug this step
+exists to close (intent 190; the intent-26 spawn shipped with no
+`project.yml` and no root `AGENTS.md`, caught only weeks later by a doctor
+sweep).
+
+### 13. Announce
 
 Log in `## Insights` of each founding intent:
 > "Project `<slug>` created at `<path>`. Tactical mirror: `project-<slug>:1` (autonomous)"