@zalom/plastic 1.0.0-beta.11 → 1.0.0-beta.13

package/scripts/lib/worktree.rb

@@ -0,0 +1,409 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "socket"
+require "time"
+
+# Worktree -- Plastic-supplied git worktree isolation and the delivery lock
+# (intent 73c / 73c1).
+#
+# The harness `EnterWorktree` tool assumes cwd IS the repo root, which is false
+# for Plastic (cwd is often the parent of the repo subdir). When the mismatch
+# occurs the tool silently degrades to a plain feature branch on the shared
+# checkout, so parallel intent deliveries are NOT isolated. This module makes
+# isolation deterministic and cwd-independent: Plastic resolves the repo from
+# projects.yml and runs `git -C <repo> worktree add`, so the cwd-not-root bug
+# dies by construction (decision D6).
+#
+# Two worktrees per project intent, both named `{id}--{slug}` (decision D2):
+#   code  worktree  <repo>/.claude/worktrees/{id}--{slug}  branch plastic/{id}--{slug}
+#   store worktree  <plastic_home>/.worktrees/{id}--{slug} branch plastic-store/{id}--{slug}
+#
+# The bridge file doubles as the delivery lock (decision D3): single-owner,
+# stale-lock reclaim via pid liveness.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `ShellRunner`, so unit tests are hermetic (no real git; inject a fake runner).
+# No eval, no global/ENV config injection.
+module Worktree
+  module_function
+
+  # --- ShellRunner (DI seam) -------------------------------------------------
+
+  # The default runner shells out to real `git`. Tests inject a fake with the
+  # same `run(*args)` contract so no real git runs in unit tests.
+  class ShellRunner
+    Result = Struct.new(:status, :stdout, :stderr) do
+      def success?
+        status.zero?
+      end
+    end
+
+    def run(*args)
+      require "open3"
+      out, err, status = Open3.capture3("git", *args.map(&:to_s))
+      Result.new(status.exitstatus.to_i, out, err)
+    end
+  end
+
+  # --- pure helpers ----------------------------------------------------------
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  # The `{id}--{slug}` identity shared by both worktrees and both branches.
+  def dir_name(intent_id, intent_slug)
+    "#{intent_id}--#{intent_slug}"
+  end
+
+  # Pure, deterministic. Returns the four paths/branches. No git calls.
+  # `repo_path` is resolved from projects.yml when nil; when it cannot be
+  # resolved the code worktree path/branch are nil (a global-store-only intent).
+  def paths(slug:, intent_id:, intent_slug:, home: Dir.home, repo_path: nil)
+    name = dir_name(intent_id, intent_slug)
+    repo = repo_path || repo_for(slug, home: home)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    code_path = repo ? File.join(File.expand_path(repo), ".claude", "worktrees", name) : nil
+    store_path = File.join(plastic_home, ".worktrees", name)
+
+    {
+      "code" => code_path,
+      "code_branch" => code_path ? "plastic/#{name}" : nil,
+      "store" => store_path,
+      "store_branch" => "plastic-store/#{name}",
+    }
+  end
+
+  # Absolute repo path for a project slug from `~/.plastic/projects.yml`, or nil.
+  # Reuses the qmd_sync safe-loader pattern: any failure yields nil.
+  def repo_for(slug, home: Dir.home)
+    return nil if blank?(slug)
+    projects = load_projects(home)
+    info = projects[slug.to_s]
+    path = info.is_a?(Hash) ? info["path"] : nil
+    return nil if blank?(path)
+    File.expand_path(path)
+  end
+
+  # --- provisioning ----------------------------------------------------------
+
+  # Resolve the slug from the bridge's intent.store, create code + store
+  # worktrees (idempotent: reuse an existing worktree path, do not error), write
+  # the `worktree` block plus `provisioned: true` onto bridge_data, return it.
+  #
+  # Fails open with a stderr log when the repo is non-git or unresolvable:
+  # sets `provisioned: false` and leaves `code: null`. All git ops use
+  # `git -C <resolved path>` -- never cwd (decision D6).
+  def provision(bridge_data, home: Dir.home, runner: ShellRunner.new)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    intent = bridge_data["intent"] || {}
+    intent_id = intent["id"].to_s
+    store = intent["store"].to_s
+    intent_slug = slug_from_dir(intent["dir"]) || slug_from_dir(store)
+
+    slug = slug_for_store(store, home: home)
+    p = paths(slug: slug, intent_id: intent_id, intent_slug: intent_slug, home: home)
+
+    block = {
+      "code" => nil,
+      "code_branch" => nil,
+      "store" => p["store"],
+      "store_branch" => p["store_branch"],
+      "provisioned" => false,
+    }
+
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    # Gitignore safety (intent 73c3): the store worktrees live under the store git
+    # repo, so without ignoring `.worktrees/` a `git add -A` sweeps their gitlinks
+    # into the store commit. Ensure both ignore entries before any worktree add.
+    ensure_gitignored(plastic_home, ".worktrees/", runner: runner)
+
+    # Store worktree: created against the plastic home git repo. Fail-open if the
+    # store repo is not a git repo (a fresh global store may be ungit'd).
+    store_ok = add_worktree(runner, repo: plastic_home,
+                            worktree: p["store"], branch: p["store_branch"],
+                            label: "store")
+
+    # Code worktree: MANDATORY for project intents. Fail-open when the repo is
+    # unresolvable or non-git -- that is the global-store-only / non-git case.
+    repo = repo_for(slug, home: home)
+    code_ok = false
+    if repo && git_repo?(runner, repo)
+      ensure_gitignored(repo, ".claude/worktrees/", runner: runner)
+      code_ok = add_worktree(runner, repo: repo,
+                             worktree: p["code"], branch: p["code_branch"],
+                             label: "code")
+      if code_ok
+        block["code"] = p["code"]
+        block["code_branch"] = p["code_branch"]
+      end
+    else
+      warn "plastic: worktree provision fail-open -- repo for slug #{slug.inspect} " \
+           "is unresolvable or not a git repo; code worktree skipped"
+    end
+
+    block["store"] = store_ok ? p["store"] : nil
+    block["store_branch"] = store_ok ? p["store_branch"] : nil
+
+    # provisioned is true only when the MANDATORY code worktree exists. The gate
+    # fails open on provisioned: false (non-git / global-only).
+    block["provisioned"] = code_ok
+
+    bridge_data["worktree"] = block
+    bridge_data
+  end
+
+  # Remove both worktrees (then `git worktree prune`), clear the worktree block.
+  # No-op when nothing was provisioned. CLEANUP (73c3) layers the merge-vs-remove
+  # policy on top via `finish`; this is the plain remove. Pass `remove: false` to
+  # clear the block WITHOUT touching git (so `finish` can merge first, then call
+  # release to drop the worktrees once the code branch is integrated).
+  def release(bridge_data, home: Dir.home, runner: ShellRunner.new, remove: true)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if remove
+      plastic_home = File.expand_path(File.join(home, ".plastic"))
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+
+      remove_worktree(runner, repo: repo, worktree: block["code"]) if repo && block["code"]
+      remove_worktree(runner, repo: plastic_home, worktree: block["store"]) if block["store"]
+
+      prune(runner, repo: repo) if repo
+      prune(runner, repo: plastic_home)
+    end
+
+    bridge_data.delete("worktree")
+    bridge_data
+  end
+
+  # --- cleanup policy (merge-vs-remove) -------------------------------------
+
+  # Finish an intent's delivery by tearing down its worktrees, optionally merging
+  # the code branch back first (intent 73c3). The merge-vs-remove decision is the
+  # one piece of policy on top of the plain `release`:
+  #
+  #   merge: true  -> the releasing path. Merge the intent's code branch
+  #                   (`plastic/{id}--{slug}`) into the repo's default branch
+  #                   BEFORE removing the worktrees, so the work is integrated and
+  #                   not lost when the worktree disappears. Then `release`.
+  #   merge: false -> the disarm / abandon path. Just `release` (plain remove);
+  #                   the branch survives and can be reclaimed.
+  #
+  # Fail-open and idempotent throughout: a missing block, missing branch, or any
+  # git failure never raises and never blocks teardown. All git ops use
+  # `git -C <path>`, never cwd (decision D6). No-op when nothing was provisioned.
+  def finish(bridge_data, home: Dir.home, runner: ShellRunner.new, merge: false)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if merge
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+      branch = block["code_branch"]
+      merge_branch(runner, repo: repo, branch: branch) if repo && !blank?(branch)
+    end
+
+    release(bridge_data, home: home, runner: runner, remove: true)
+  end
+
+  # Merge `branch` into the repo's default branch from the main checkout. The
+  # worktree the branch is checked out in stays put; we merge in the repo dir
+  # itself (its own current branch is the integration target). Idempotent: a
+  # no-op merge ("Already up to date") still succeeds. Fail-open: a conflicting
+  # or otherwise failing merge is aborted and logged, never raised, so teardown
+  # still proceeds (CLEANUP must not strand a worktree).
+  def merge_branch(runner, repo:, branch:)
+    return false if blank?(repo) || blank?(branch)
+    target = current_branch(runner, repo: repo)
+    return false if blank?(target) || target == branch
+
+    res = runner.run("-C", repo, "merge", "--no-ff", "--no-edit", branch)
+    return true if res.success?
+
+    # Leave the integration branch clean: abort a half-applied/conflicted merge.
+    runner.run("-C", repo, "merge", "--abort")
+    warn "plastic: worktree finish could not merge #{branch.inspect} into " \
+         "#{target.inspect}: #{res.stderr.to_s.strip}; removing worktree without merge"
+    false
+  end
+
+  # The repo's current branch (the integration target), or nil when detached /
+  # unresolvable.
+  def current_branch(runner, repo:)
+    return nil if blank?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--abbrev-ref", "HEAD")
+    return nil unless res.success?
+    name = res.stdout.to_s.strip
+    (name.empty? || name == "HEAD") ? nil : name
+  end
+
+  # --- gitignore safety ------------------------------------------------------
+
+  # Ensure `entry` is present in `<repo>/.gitignore`, appending it once if absent
+  # (idempotent). Without this, the store worktrees that live UNDER the store git
+  # repo (~/.plastic/.worktrees/) get swept into the store commit by a `git add
+  # -A`, polluting the index with worktree gitlinks (observed during 73c1
+  # integration). Provisioning and cleanup both call this so the repos' indexes
+  # stay clean. Best-effort and non-raising: any failure is logged, never raised.
+  def ensure_gitignored(repo, entry, runner: ShellRunner.new)
+    return false if blank?(repo) || blank?(entry) || !Dir.exist?(repo)
+    gitignore = File.join(File.expand_path(repo), ".gitignore")
+    want = entry.to_s.strip
+
+    existing = File.exist?(gitignore) ? File.read(gitignore) : ""
+    present = existing.each_line.any? { |line| line.strip == want }
+    return true if present
+
+    File.open(gitignore, "a") do |io|
+      io.write("\n") unless existing.empty? || existing.end_with?("\n")
+      io.write("#{want}\n")
+    end
+    true
+  rescue StandardError => e
+    warn "plastic: ensure_gitignored(#{entry.inspect}) failed for #{repo.inspect}: #{e.message}"
+    false
+  end
+
+  # --- lock ------------------------------------------------------------------
+
+  # pid liveness: signal 0 probes without sending. Any error (no such process,
+  # not ours) means not live.
+  def session_live?(pid)
+    n = Integer(pid) rescue nil
+    return false if n.nil? || n <= 0
+    Process.kill(0, n)
+    true
+  rescue StandardError
+    false
+  end
+
+  # True iff ANOTHER bridge for this intent has a LIVE owner pid that is not
+  # current_session. Scans /tmp/plastic-*.json (or `tmp`). The current session's
+  # own bridge never counts as "other". A dead owner does not hold the lock
+  # (stale-lock reclaim).
+  def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home, tmp: nil)
+    tmp ||= default_tmp
+    id = intent_id.to_s
+    st = File.expand_path(store.to_s) unless blank?(store)
+
+    Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
+      next if f.end_with?(".tmp")
+      data = (JSON.parse(File.read(f)) rescue nil)
+      next unless data.is_a?(Hash)
+
+      intent = data["intent"] || {}
+      next unless intent["id"].to_s == id
+      unless st.nil?
+        bstore = intent["store"].to_s
+        next unless bstore.empty? || File.expand_path(bstore) == st
+      end
+
+      session = data["session"].to_s
+      next if !blank?(current_session) && session == current_session.to_s
+
+      lock = data["lock"] || {}
+      owner_pid = lock["pid"]
+      return true if session_live?(owner_pid)
+    end
+    false
+  rescue StandardError
+    false
+  end
+
+  # --- git operations (all use -C, never cwd) --------------------------------
+
+  # Idempotent worktree add. If `worktree` already exists on disk, treat as
+  # reuse (success, no git call). Otherwise `git -C <repo> worktree add <wt>
+  # -b <branch>`; if the branch already exists, retry without -b (reattach).
+  def add_worktree(runner, repo:, worktree:, branch:, label:)
+    return false if blank?(repo) || blank?(worktree)
+    return true if Dir.exist?(worktree) # idempotent reuse
+
+    res = runner.run("-C", repo, "worktree", "add", worktree, "-b", branch)
+    return true if res.success?
+
+    # Branch may already exist (a prior provision that was pruned but kept the
+    # branch). Retry attaching the existing branch.
+    res2 = runner.run("-C", repo, "worktree", "add", worktree, branch)
+    return true if res2.success?
+
+    warn "plastic: worktree add (#{label}) failed: #{res.stderr.to_s.strip}"
+    false
+  end
+
+  def remove_worktree(runner, repo:, worktree:)
+    return false if blank?(repo) || blank?(worktree)
+    res = runner.run("-C", repo, "worktree", "remove", worktree)
+    unless res.success?
+      # Force-remove tolerates dirty/locked worktrees; CLEANUP owns merge policy.
+      res = runner.run("-C", repo, "worktree", "remove", "--force", worktree)
+    end
+    res.success?
+  end
+
+  def prune(runner, repo:)
+    return false if blank?(repo)
+    runner.run("-C", repo, "worktree", "prune").success?
+  end
+
+  # True iff `repo` is a git work tree (idempotent, no mutation).
+  def git_repo?(runner, repo)
+    return false if blank?(repo) || !Dir.exist?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--is-inside-work-tree")
+    res.success? && res.stdout.to_s.strip == "true"
+  end
+
+  # --- internals (projects.yml resolution, mirrors qmd_sync) -----------------
+
+  def load_projects(home)
+    path = File.join(File.expand_path(home), ".plastic", "projects.yml")
+    return {} unless File.exist?(path)
+    data = begin
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+    projects = data.is_a?(Hash) ? data["projects"] : nil
+    projects.is_a?(Hash) ? projects : {}
+  end
+
+  # Resolve a project slug from a store directory. A project's tactical store
+  # lives at <plastic_home>/projects/<slug>/store; the global store yields nil
+  # (no project repo). Mirrors qmd_sync's slug_for_store fallback.
+  def slug_for_store(store_dir, home: Dir.home)
+    return nil if blank?(store_dir)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    store_dir = File.expand_path(store_dir)
+    return nil if store_dir == File.join(plastic_home, "store")
+
+    parts = store_dir.split(File::SEPARATOR)
+    idx = parts.rindex("projects")
+    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    nil
+  end
+
+  # Best-effort slug for the worktree dir-name from an intent dir/store path:
+  # the basename `{id}--{slug}` -> the `{slug}` portion (split on the first
+  # `--`). Used only for naming.
+  def slug_from_dir(dir)
+    return nil if blank?(dir)
+    base = File.basename(dir.to_s)
+    idx = base.index("--")
+    return nil unless idx
+    base[(idx + 2)..]
+  end
+
+  def default_tmp
+    t = ENV["PLASTIC_TMP"]
+    (t.nil? || t.strip.empty?) ? "/tmp" : t
+  end
+end

package/scripts/new-intent

@@ -311,7 +311,15 @@ def main(argv)
     File.write(File.join(intent_dir, name), "#{Bridge::PLACEHOLDER_SENTINEL}\n#{body}")
   end
 
-  # 6. Self-validate (frontmatter + sanctioned sections).
+  # 6. Stamp the born savepoint line (intent 81). The first ledger line is the
+  # `What` bookend, written deterministically at creation rather than relying on
+  # a PostToolUse gate firing on the intent-file write (which is missed in some
+  # sessions / harnesses). The intent file is never a sentinel placeholder, so
+  # append_savepoint records `What  {id}--{slug}.md`. Idempotent: a later gate
+  # fire adds nothing.
+  Bridge.append_savepoint(intent_dir, intent_file)
+
+  # 7. Self-validate (frontmatter + sanctioned sections).
   result = IntentValidator.validate(intent_dir)
   unless result[:ok]
     warn "new-intent: scaffolded intent is NOT born complete:"

package/scripts/spawn-preamble

@@ -43,8 +43,10 @@ REPORT_CONTRACT =
   "status (delivered or blocked), artifacts written, verification or tests run, " \
   "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
   "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
-  "(for example the planner explains the plan back to the orchestrator). See " \
-  "skills/auto/references/agent-report-contract.md for the per-role format."
+  "(for example the planner explains the plan back to the orchestrator). Keep the " \
+  "report prose-stripped: the envelope and payload only, no greeting, no preamble, " \
+  "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
+  "See skills/auto/references/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil

package/skills/auto/SKILL.md

@@ -90,7 +90,19 @@ Solo fallback: if the harness has no subagent dispatch, fall back to a single ag
 
 ## Stage-Aware Entry
 
-Read the active intent's directory. Determine current lifecycle stage from filesystem state:
+Read the active intent's `savepoint.md` FIRST (intent 81): the last line classifies the stage,
+and you then verify only that line's artifact before entering. Fall back to the filesystem probe
+below only when the ledger is missing (then rebuild it with `Bridge.rebuild_savepoint`).
+
+| Ledger last line | Enter |
+|---|---|
+| `What  {id}--{slug}.md` (born) or no spec | Start / complete Why (write spec.md) |
+| `Why  spec.md created` | Enter How |
+| `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Enter Exec (verify plan + checklist) |
+| `Exec  outcome.md created` | Exec done; complete the intent |
+| `Done  delivered|abandoned` | Terminal; do not resume |
+
+Filesystem fallback (ledger missing only):
 
 | Check (in order) | Stage |
 |---|---|
@@ -196,7 +208,13 @@ During initial project creation, all decisions are non-destructive by definition
 5. Review `## Insights` for observations that should spawn future intents. If any:
    - Create them (using `plastic-creating-intent` conventions)
    - Update `chain` in the current intent's frontmatter
-6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date). As the
+   closing act of the transfer, stamp the terminal ledger bookend (intent 81) so the savepoint's
+   last line records delivery:
+   ```bash
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'
+   ```
+   (Use `"abandoned"` instead when the intent is being moved to `## Abandoned`.) Idempotent.
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
 8. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent).
    It runs in the background so it never blocks the turn:
@@ -211,6 +229,20 @@ During initial project creation, all decisions are non-destructive by definition
    ```
    Disarming also purges stale bridge files from the temp directory automatically (it keeps the
    current bridge and any live run), 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 (step 4 above, 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.
 10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling

package/skills/auto/references/agent-report-contract.md

@@ -17,6 +17,14 @@ only. In-flight observations still go in `## Insights`; the report does not add
 completed its handoff: the agent that did the work is the cheapest, most accurate source of the
 account.
 
+## Prose-stripped (intent 84)
+
+The report is the envelope and the per-role payload, nothing else. Dispatched and background
+subagents report and do their job; they do not narrate. Strip conversational prose: no
+greeting, no preamble, no "Here is what I did" framing, no end-recap, no restating of the task.
+Reasoning belongs in the thinking channel, not the report body. This tightens the FORM (the
+fields stay exactly as below); it does not remove any required field.
+
 ## Common envelope
 
 Every role report, whatever the stage, carries these fields:

package/skills/continuing/SKILL.md

@@ -63,13 +63,28 @@ command is a no-op when QMD is absent, so fall back to the existing INDEX.md / f
 
 For that intent's directory:
 
-1. **Read `savepoint.md`.** It is a deterministic, append-only stage ledger (one line per
-   milestone, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. The **last line =
-   current stage**.
-2. **Verify the stage file.** Confirm the file the ledger names exists and is non-empty
-   (ledger `How  plan.md created` → `plan.md` must be present and non-empty).
+1. **Read `savepoint.md` FIRST (intent 81).** It is a deterministic, append-only ledger
+   (one line per event, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. Classify
+   the state from the **last line** alone, then verify ONLY that line's artifact. The bookends
+   are fixed: first line `What  created`, last line either a cycle position or
+   `Done  delivered|abandoned`.
+
+   | Last line | State | Verify only |
+   |---|---|---|
+   | `What  {id}--{slug}.md` | born / parked | intent file exists |
+   | `Why  started` | Why entered, no spec yet | spec.md not yet real; continue Why |
+   | `Why  spec.md created` | Why done | spec.md present; continue to How |
+   | `How  started` / `How  plan.md created` | How in progress | plan.md; continue How |
+   | `How  checklist.md created` / `Exec  started` | ready for / in Exec | plan.md + checklist.md present; continue Exec |
+   | `Exec  outcome.md created` | Exec done | outcome.md present; ready to complete |
+   | `Done  delivered` / `Done  abandoned` | terminal | do NOT cycle-resume; INDEX is authoritative |
+
+2. **Verify the stage file.** Confirm only the last line's artifact exists and is non-empty
+   (ledger `How  plan.md created` → `plan.md` must be present and non-empty). Do not re-probe
+   every lifecycle file.
 3. **Drift handling.** If the ledger's last line disagrees with files-on-disk, rebuild the
-   ledger from filesystem state and note the correction:
+   ledger from filesystem state and note the correction. A rebuilt ledger is the file-landing
+   skeleton (no `started`/`Done` lines), which still pins cycle position:
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
    ```

package/skills/intent-curator/SKILL.md

@@ -38,6 +38,9 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
-When an intent reaches a terminal state — moved to Completed OR Abandoned — refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+When an intent reaches a terminal state — moved to Completed OR Abandoned — do two things as the closing act of the transfer:
+
+1. 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.
+2. Refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
 
 After the agent completes, report what changed.

package/skills/managing-index/SKILL.md

@@ -41,6 +41,8 @@ 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, stamp the terminal savepoint bookend as the closing act of the transfer (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.
+
 ## Workflow
 
 QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or

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,15 @@ 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).** 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
+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.
+
 ### 4. Bump Version
 
 Determine which files to update from project.yml:
@@ -207,6 +217,28 @@ 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). 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.)
+
+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.read(ENV["CLAUDE_CODE_SESSION_ID"]); Worktree.finish(b, merge: true) if b'
+```
+
+`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. 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.
+
 ## Conventions
 
 - **Annotated tags only** - `git tag -a`, never lightweight tags