@zalom/plastic 1.0.0-beta.8 → 1.0.0

package/skills/intent-starting/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: plastic-intent-starting
+description: >-
+  Board a session onto an intent: take the lock FIRST, confirm savepoint state, ask auto or
+  guided ONCE, then resume at the latest delivered station and run the cycle to Done. Use on
+  `continuing --intent {id}`, when a new intent is registered and the user asks to work it,
+  or when the user picks an intent to work. Requires the intent in INDEX `## Active`.
+---
+
+# Intent Starting — board a session onto an intent
+
+Announce: "Boarding intent [ID] — [name]."
+
+`plastic-intent-starting` is the Start procedure. It boards a session onto one intent: take
+the lock FIRST, confirm the delivery state, ask **auto or guided ONCE**, board at the latest
+delivered station, then run the cycle to Done. The What → Why → How → Exec stations are the
+train track; Start boards the train, the ending procedure (~93) exits it.
+
+## Precondition + trigger
+
+Fires when the user picks an intent to work, when an agent is told to continue a SPECIFIC
+intent, or on `continuing --intent {id}` (the `continuing` → `starting` router is 106's job;
+this skill is invokable standalone now).
+
+If the intent is **terminal** (Done / Abandoned in INDEX): report only. Take NO lock, run NO
+resume, do NOT reopen it. Summarize the outcome and ask what is next. Stop here.
+
+## Lock FIRST (the spine)
+
+The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock-gate
+enforces it: without a held lock, mutating writes to this active intent's dir are denied with
+"run /plastic-intent-starting to lock and begin".
+
+1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
+   (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
+   brand-new What intent is activated here, then locked.
+2. **Self-heal the lock state first.** Run:
+   `ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <STORE>/<dir>`
+   This is the one repair function (same one /plastic-lock exposes): it removes
+   corrupt or legacy lock state and rebuilds the lock and bridge from disk for
+   this session. If it reports `held`, another session owns the intent: STOP
+   and tell the user who holds it. If it reports `stale`, ask the user before
+   running `plastic-lock reclaim` (takeover is audited).
+3. **Arm the bridge.** Which arm is chosen by the mode answer (below), but the lock itself is
+   taken first. Reuse the arm one-liner shape from `plastic-auto`:
+   ```bash
+   # guided (lock only):
+   ruby -r ~/.plastic/scripts/lib/bridge -e \
+     'Bridge.arm_guided(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+   # auto (lock + auto), then hand to plastic-auto:
+   ruby -r ~/.plastic/scripts/lib/bridge -e \
+     'Bridge.arm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+   ```
+   Replace `<ID>`, `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
+   `<dir>` (the `ID--slug` directory), and `<name>`.
+4. **Dispatch What-stage discovery (under the lock).** Right after arming, when the intent
+   was just activated in step 1 (on a resume that already has
+   `resources/discovery--<slug>.md`, skip: discovery runs once per intent, at activation
+   only), dispatch the `plastic-intent-discovery` agent (see the `plastic-intent-discovery`
+   skill), now that this session owns the lock, deposit authorized as the owner session. Resolve its
+   model explicitly and pass it at dispatch time (belt-and-braces): `read-config
+   agents.models.plastic-intent-discovery --project <repo>`. The agent runs QMD discovery
+   over the intent's `chain`/`sources` and deposits findings to
+   `resources/discovery--<slug>.md` only; it never writes the intent file, so the
+   lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
+   discovery yields nothing, proceed to Why normally.
+
+**Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
+id the bridge is keyed by: pass the hook stdin `session_id` when you have it, otherwise
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. Both arms call `resolve_session`, which
+picks the first non-empty of: the explicit id you pass → `CLAUDE_CODE_SESSION_ID` → a
+deterministic derived key (a hash of the store and intent id). It never returns nil, so the
+lock is taken even when every session env var is empty; arming prints a one-line stderr
+notice when it falls through to the derived key.
+
+**What the lock IS.** Ownership is session-keyed and lease-based: arming writes a durable
+`delivery.lock` file in the intent dir naming this session as owner, and the owner's hooks
+refresh the file mtime on tool activity (the lease heartbeat). The /tmp bridge is only a
+cache of that file; on any disagreement the lock file wins, so a wiped /tmp never strands
+the owner. Idempotent re-arm: arming again with the same owner just refreshes the lock; it
+is not an error to re-board an intent this session already owns. A failed arm raises with
+a message naming the resolving `plastic-lock` verb (`status`, `reclaim`, or `fix`): follow
+that message, never delete a lock file by hand.
+
+## Confirm delivery state
+
+Read `savepoint.md` and classify from the **last line** alone, then verify ONLY that line's
+artifact is real (sentinel-aware via `Bridge.stage_file_present?`). On drift (the last line
+disagrees with files on disk), rebuild the ledger from disk and note the correction. Do not
+inline the rebuild; the `plastic-savepoint` skill owns it:
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
+```
+
+## Report + ask "auto or guided?" ONCE
+
+Report: the intent, the station it lands at (the matrix below), what is delivered, the next
+step. Then ask the user **"auto or guided?"** — exactly ONCE, whatever station it lands at.
+Never re-ask at a later station.
+
+- **guided** → `arm_guided` (lock only); continue step by step with the user through the
+  station's work below.
+- **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
+  only remaining job is the handoff; `plastic-auto` runs the cycle from here.
+
+## Board at the latest delivered station
+
+The station is derived from `savepoint.md` last line + real artifacts on disk. See
+`references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
+continue with) and the per-station notes. Summary of what "continue" means per station:
+
+- **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
+- **Why** → continue brainstorming → `spec.md`.
+- **How** → continue `plan.md` + `actions/` + `checklist.md`.
+- **Exec** → verify what has been delivered, then continue (or restart) the delivery /
+  research; tick the checklist.
+- **ready to complete** (`Exec outcome.md created`) → exit at Done.
+- **Done** → report only, ask what is next, never reopen.
+
+## Disarm / release on done
+
+When delivery finishes, disarm and release per the `plastic-auto` disarm/release prose (do
+not duplicate it here). The guided branch releases the lock via `disarm_auto`, which is
+mode-agnostic (it sets `auto = false` and calls `Worktree.release`), so it releases a guided
+lock too. When the work ships through a release, the release path merges the branch before the
+worktree is removed; the plain disarm remove is only for the no-release case.
+
+## References
+
+- `references/boarding-matrix.md` — the full boarding table and per-station behaviour.

package/skills/intent-starting/evals/evals.json

@@ -0,0 +1,117 @@
+{
+  "skill_name": "plastic-intent-starting",
+  "notes": "Intent 96. Scopes: description triggering (1-5) and behavior (6-10: lock-first spine, ask-mode-once, terminal report-only, mode->arm mapping, boarding matrix). The lock-first and gate behaviors are also proven by Ruby tests (test/bridge_guided_test.rb, test/lock_gate_test.rb, test/lock_gate_hook_test.rb).",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "start work on intent 96",
+      "expected_output": "Activates plastic-intent-starting (board a session onto the named intent).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "continuing --intent 96",
+      "expected_output": "Activates plastic-intent-starting (the --intent form boards a specific intent).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "work this intent",
+      "expected_output": "Activates plastic-intent-starting when an intent is in context to be worked.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 4,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "continue",
+      "expected_output": "Does NOT activate plastic-intent-starting; bare 'continue' is plastic-continuing (no specific intent named).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 5,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "create a new intent for the uploader retry policy",
+      "expected_output": "Does NOT activate plastic-intent-starting; activates plastic-creating-intent.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 6,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Active intent X exists at the Why station. Start work on it (guided).",
+      "expected_output": "Takes the lock FIRST via Bridge.arm_guided (auto stays false) before any mutating work, confirms savepoint, then boards at Why and continues brainstorming toward spec.md.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "lock acquired before any mutating write; SKILL.md 'Lock FIRST' section precedes station work", "result": "expect-pass" },
+        { "type": "code", "check": "Bridge.arm_guided stamps the lock with auto=false (test/bridge_guided_test.rb green); lock-gate denies a no-lock write to the active intent dir (test/lock_gate_hook_test.rb green)", "result": "pass" }
+      ]
+    },
+    {
+      "id": 7,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Start work on an active intent without saying auto or guided.",
+      "expected_output": "Asks 'auto or guided?' exactly once after reporting the station; never re-asks at later stations.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "SKILL.md asks the mode exactly once and states 'never re-asked at a later station'", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 8,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Start work on an intent that is Done in INDEX.",
+      "expected_output": "Reports only: no lock, no resume, no reopen. Summarizes the outcome and asks what is next.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "terminal intent -> report only, no arm call", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 9,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Start work and choose auto.",
+      "expected_output": "guided -> Bridge.arm_guided; auto -> Bridge.arm_auto then hand off to plastic-auto (auto branch's only remaining job is the handoff).",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "SKILL.md maps guided->arm_guided and auto->arm_auto+handoff to plastic-auto", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 10,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Start an intent whose savepoint last line is 'How  checklist.md created'.",
+      "expected_output": "Boards at Exec (verify plan + checklist real), per references/boarding-matrix.md, and continues delivery/ticks the checklist.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "boarding matrix lands 'How checklist.md created' / 'Exec started' at Exec", "result": "expect-pass" }
+      ]
+    }
+  ]
+}

package/skills/intent-starting/references/boarding-matrix.md

@@ -0,0 +1,35 @@
+# Boarding matrix — which station Start drops you at
+
+The station is derived from `savepoint.md`'s last line plus the real artifacts on disk.
+Classify from the last line alone, then verify ONLY that line's artifact is real
+(sentinel-aware). On drift, rebuild the ledger from disk and note it.
+
+| savepoint last line | latest delivered | boards at | continue with |
+|---|---|---|---|
+| `What  {id}--{slug}.md` (born) | What | **What / Why** | What work (106-expanded), then brainstorm → `spec.md` |
+| `Why  started` (spec still sentinel) | What | **Why** | continue brainstorming → `spec.md` |
+| `Why  spec.md created` | Why | **How** | `plan.md` + `actions/` + `checklist.md` |
+| `How  started` / `How  plan.md created` | (How in progress) | **How** | finish `plan.md` → `checklist.md` |
+| `How  checklist.md created` / `Exec  started` | How | **Exec** | implement, tick the checklist |
+| `Exec  outcome.md created` | Exec | **ready to complete** | exit at Done |
+| `Done  delivered` / `Done  abandoned` | terminal | **report only** | immutable; ask what is next |
+
+## Per-station behaviour (what "continue" means)
+
+- **What** → do what What requires (to be expanded in 106), then brainstorm → `spec.md`.
+- **Why** → continue brainstorming; deliver `spec.md`.
+- **How** → continue `plan.md` + `actions/` + `checklist.md`.
+- **Exec** → verify what has been delivered, then continue (or restart) the delivery /
+  research. The first unchecked `checklist.md` item is the next step; the newest `## Insights`
+  entry supplies human-readable context.
+- **ready to complete** → `outcome.md` is real; run the ending procedure (~93).
+- **Done** → terminal. Report the outcome, ask what is next. Never reopen; INDEX is
+  authoritative.
+
+## Notes
+
+- The mode (auto / guided) is asked exactly ONCE, whatever station Start lands at. It is never
+  re-asked at a later station. The lock is taken FIRST regardless of station (terminal intents
+  excepted: they get no lock and no resume).
+- An `## Insights` entry marked `(autonomous)` means the intent was being delivered
+  autonomously; in guided mode, surface that and offer to hand back to `plastic-auto`.

package/skills/linking-intents/SKILL.md

@@ -6,34 +6,70 @@ description: Use when creating connections between intents, the user says "link"
 # Linking Intents
 
 ## When to Use
-- During intent creation (automatic — ask about related intents)
+- During intent creation (automatic: ask about related intents)
 - User says "link", "connect", "relates to"
 - Agent discovers a relationship between intents during work
 
-## Connection Types (Ranked by Strength)
+## Discovery and ranking are separate
 
-### 1. Direct Links (Strongest)
-Explicit wikilinks in the `## Links` section. Bidirectional — add to both intents.
+Two distinct steps, do not conflate them:
 
-```markdown
-## Links
-- [[1a]] — research this plan is based on
-```
+1. **Discovery** (finding candidate related intents) may use any tool: grep, find, ripgrep,
+   or QMD/Serena when present (QMD-first per the project rule). Discovery casts a wide net.
+2. **Ranking** the candidates is a CONTEXT-INFLUENCE judgement: read each candidate's `## Intent`
+   and `## Context` and ask whether that context actually informed this intent. Ranking is NOT a
+   structural metric (no shared-file or shared-symbol grading: on intent 90, matching whole files
+   flagged 35 intents because ~20 touch `bridge.rb`). It is NOT a similarity score either (QMD
+   relevance measures topic proximity, not influence). A script cannot make this call; an agent
+   does.
+
+## The three tiers (by context influence)
+
+- **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
+  delivery-moving intents, not everything in the same area. Earns an edge, reflected in `## Links`.
+  Worked example (intent 90): 79 created it so 79 is a source; 80 deferred the exact fix 90 makes,
+  so its context directly helps delivery and 80 is chain; 49/66/73 are same-area background, so
+  they get a shared tag and no link.
+- **tags:** loose theme grouping for search. NOT a link.
+
+**Timing.** The influence judgement happens at What/Why (and during upkeep), guided by this rule.
+It does not wait for code to exist; it is reasoning over the candidate's context, not over a diff.
+
+**Record the call.** For every edge an agent adds, store a rating (high / medium / low) plus a
+one-line reason as a dated line under the intent file's `## Insights` section (per 96 D3, link
+rationale lives in the intent file, not a side file). It stays out of frontmatter (graph only) and
+out of the projected `## Links` label, so the audit trail never breaks the projection identity.
+
+## `## Links` is derived (never author it by hand)
+
+`## Links` is a DERIVED view of `sources` then `chain`, not a place to write links. Never
+hand-write a `## Links` line, and never auto-delete one. To add a link, add the frontmatter
+edge (below), then let the projection regenerate the section (`scripts/project-links`).
+
+Run `scripts/link-suggest <id>` to gather candidate intents WITH each one's Intent and Context (the
+evidence you judge influence on) and to flag drift (a `## Links` line with no frontmatter edge
+behind it). To record a confirmed edge plus its rating and reason, run it with
+`--record <id> --edge <sources|chain> --rating <high|medium|low> --reason "..." --confirm`. It never
+grades influence itself, never writes an edge without `--confirm`, and never deletes.
+
+## Connection Types (the frontmatter edges)
 
-### 2. Sources (Backward)
+### 1. Sources (Backward)
 The `sources` array in frontmatter. The direct ascendant(s) this intent was created from / emerged from the lifecycle of (formation, not topic similarity), backward links to the work it was built out of:
 ```yaml
 sources: ["1a", "1a2"]
 ```
 
-### 3. Chain (Forward)
+### 2. Chain (Forward)
 The `chain` array in frontmatter. What this intent spawned AND related-but-not-spawned successors it leads to, forward links to children, follow-on, and related work:
 ```yaml
 chain: ["1b1", "1b2"]
 ```
 
-### 4. Tags (Weakest)
-Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership.
+### 3. Tags (for discovery, not links)
+Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership. A shared tag is a loose theme grouping: it earns NO edge.
 ```yaml
 tags: [plastic, project-reddit-kb]
 ```

package/skills/linking-intents/references/zettelkasten.md

@@ -10,6 +10,13 @@ Plastic implements three Zettelkasten structures:
 
 INDEX.md is a structure note (hub), not a table of contents.
 
+`## Links` mirrors the frontmatter graph exactly. Each entry is
+`- [[id--slug|<target's full intent: text>]]` (cross-store: `- [[store:id--slug|...]]`),
+a clickable `id--slug` target with the target's full `intent:` text as the label.
+Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
+preserved within each group. Sources never appear at the end. No source/chain tags, no
+sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+
 ## Folgezettel IDs
 
 IDs encode lineage using Luhmann's alternating convention:

package/skills/lock/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: lock
+description: Inspect, repair, release, or reclaim an intent's delivery lock. Use when a lock-gate deny names /plastic-lock, when resuming interrupted work after a crash, reboot, or /tmp wipe, when a lock reads held or stale, or when the user says "fix the lock", "who holds the lock", or "reclaim the lock".
+---
+
+# Plastic Lock
+
+Command-only wrapper around `~/.plastic/scripts/plastic-lock`. The durable
+delivery lock is a `delivery.lock` file in the intent directory: ownership is
+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.
+
+## Verbs
+
+Run from the project (the intent resolves from this session's bridge), or pass
+`--intent-dir` explicitly:
+
+| Verb | What it does | When |
+|---|---|---|
+| `status` | Report the lock file, bridge cache, freshness, agreement | Always safe; run first |
+| `fix` | Idempotent repair: rebuild lock + bridge from disk truth for THIS session. Never touches a fresh foreign lock | Interrupted work, corrupted state, /tmp wiped, legacy pid locks |
+| `release` | Owner clears the lock | Ending or abandoning a boarding |
+| `reclaim` | Explicit takeover of a STALE lock; appends an audit line to savepoint.md | The owner is gone and the lease expired |
+| `delegate` | Owner registers a subagent session under the lock (`--delegate <session-id>`) | Auto-mode orchestration |
+
+```
+ruby ~/.plastic/scripts/plastic-lock status
+ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock reclaim --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock delegate --delegate <subagent-session-id>
+```
+
+## Rules
+
+- `fix` exits non-zero when another session holds a FRESH lock: back off, do
+  not retry in a loop. `status` shows the owner.
+- `reclaim` refuses a fresh lock. There is no silent reclaim anywhere; every
+  takeover is audited in the intent's savepoint.md.
+- Acquiring a lock for new work is NOT this skill's job: board through
+  `/plastic-intent-starting`, which calls the same repair internally.

package/skills/managing-index/SKILL.md

@@ -41,6 +41,12 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ### Completed
 All completed intents with dates. Links preserved, never deleted.
 
+When you move an intent INTO Completed or Abandoned, run the closing acts of the transfer in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+
+1. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
+2. Stamp the terminal savepoint bookend (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+3. Refresh the QMD index for that store LAST, after the terminal move and savepoint (no-op when QMD is absent), in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+
 ## Workflow
 
 QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or

package/skills/managing-index/references/zettelkasten-linking.md

@@ -8,7 +8,12 @@
 
 ## Three Connection Types (Ranked)
 
-1. **Direct links** (strongest) — wikilinks in `## Links` section
+1. **Direct links** (strongest): wikilinks in the `## Links` section, the projection of the
+   frontmatter graph. Each entry is `- [[id--slug|<target's full intent: text>]]` (cross-store:
+   `- [[store:id--slug|...]]`), a clickable `id--slug` target labeled with the target's full
+   `intent:` text. Ordering is mandatory: all `sources` first (top), then all `chain`,
+   frontmatter order preserved within each group. Sources never appear at the end. No
+   source/chain tags, no sub-grouping.
 2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See `docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
 3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
 

package/skills/releasing/SKILL.md

@@ -20,6 +20,7 @@ Project configuration drives the workflow - no hardcoded assumptions.
 - [ ] Run post-push actions (GitHub release, npm publish, etc.)
 - [ ] Verify release sync (npm dist-tag, GitHub "Latest", git tag all show the new version)
 - [ ] Complete active intent
+- [ ] Clean up the intent's worktrees (merge-then-remove)
 
 ## Workflow
 
@@ -84,6 +85,12 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
+**Worktree-isolated intents (intent 73c3).** A worktree-delivered intent's code lives on
+`plastic/{id}--{slug}`, merged together with cleanup in step 9, not on a hand-made feature
+branch. Do not delete the worktree before its branch is merged, or the work is lost. For
+the full rationale and the already-merged-by-hand no-op case, read
+`references/promotion-and-tagging.md`.
+
 ### 4. Bump Version
 
 Determine which files to update from project.yml:
@@ -94,8 +101,20 @@ Determine which files to update from project.yml:
 
 Update the version string in each file, then commit:
 
+**Cut the CHANGELOG entry.** Before committing, edit `CHANGELOG.md` at the repo root so
+the changelog change rides this same version-bump commit and reaches the tag. Write one
+line in the existing shape:
+
+`` `<version>` - shipped <date>; collected <intent-id> (<one-line summary>) ``
+
+Prepend it as the first bullet under `## Released` (newest-first). If this version was
+sitting under `## Unreleased`, move it out of that section and into `## Released`. Keep
+the line intent-centric narrative (which intents the cut collected and why), NOT commit
+detail: step 5's tag-message changelog and step 7's `gh release create --generate-notes`
+already own the commit-level detail, so do not duplicate it here.
+
 ```bash
-git add <version-files>
+git add <version-files> CHANGELOG.md
 git commit -m "chore: bump version to X.Y.Z - [one-line summary]"
 ```
 
@@ -207,6 +226,27 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 **If no active intent exists for this release**, that itself is a problem - work happened outside the intent system. Log it and move on, but flag it.
 
+### 9. Clean Up the Intent's Worktrees (merge-then-remove)
+
+A release is the merge-then-remove path for the intent's worktrees (intent 73c3): the
+intent's code branch is merged back into the default branch BEFORE the worktree is removed.
+Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
+removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
+from the bridge:
+
+```bash
+ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
+  'b = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd); Worktree.finish(b, merge: true) if b'
+```
+
+(Uses `discover_bridge`, not a bare session-keyed `Bridge.read`, because a session can own more
+than one live bridge now — intent 131 — and `discover_bridge` resolves the right one for this cwd.)
+
+Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
+prune` in the affected repo if you hit a stale reference. For why this is the one place the
+merge-vs-remove policy lands on merge, and the fail-open/idempotent guarantees of `finish`,
+read `references/promotion-and-tagging.md`.
+
 ## Conventions
 
 - **Annotated tags only** - `git tag -a`, never lightweight tags
@@ -219,34 +259,9 @@ A release IS a delivery. The active intent that drove this work must be complete
 - **Verify sync** - after pushing, confirm npm dist-tag, GitHub "Latest", and the git tag all show the new version
 - **Branch cleanup** - delete merged feature branches: `git branch -d <branch>`
 
-## Promotion
-
-To promote a release across channels, use `--promote`:
-
-```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
-```
-
-**Promotion rules:**
-- Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
-- Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
-
-## Retroactive Tagging
-
-For repos without prior tags, tag historical releases:
-
-```bash
-git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
-```
-
-Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).
-
 ## References
 
+- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+  tagging a historical release retroactively, read `references/promotion-and-tagging.md`
+  for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

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

@@ -0,0 +1,60 @@
+# Promotion, Retroactive Tagging, and Worktree Merge Rationale
+
+Occasional variant paths off the main release workflow: promoting a pre-release
+across channels, tagging historical releases retroactively, and the deep rationale
+for why the intent's worktree is merged before removal.
+
+## Table of Contents
+
+- [Worktree merge-then-remove rationale](#worktree-merge-then-remove-rationale)
+- [Promotion](#promotion)
+- [Retroactive Tagging](#retroactive-tagging)
+
+## Worktree merge-then-remove rationale
+
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+Workflow step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
+A release is the merge-then-remove path for the intent's worktrees. This is the one place
+the merge-vs-remove policy lands on "merge": the intent's code branch (`plastic/{id}--{slug}`)
+is merged back into the repo's default branch BEFORE the worktree is removed, so the
+integrated work is never lost. (The disarm path in `plastic-auto`, by contrast, is a plain
+remove because no release is merging the branch.)
+
+`Worktree.finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the
+worktree is still removed rather than stranded), and a second call with the block already
+cleared is a no-op.
+
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic-releasing --promote beta    # promotes current alpha → beta
+plastic-releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
+## Retroactive Tagging
+
+For repos without prior tags, tag historical releases:
+
+```bash
+git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
+```
+
+Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).