@zalom/plastic 1.0.0-beta.24 → 1.0.0-beta.26

package/PLASTIC.md

@@ -283,32 +283,15 @@ hygiene after each intent. Advisory self-check, not hard-verifiable.
 
 ## Retrieval Gate
 
-A single capability-aware PreToolUse gate enforces retrieval-first routing on the agent's own
-Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). The gate is
-OPERATION-based: it separates searching from reading, and it never stands between you and
-reading something you have already located.
-
-- Only CONTENT SEARCH over a Plastic store is gated. The Grep tool and bash `grep`/`rg`/`ag`
-  whose target is at or under a store route to QMD when QMD is present and the index is fresh:
-  the raw scan is blocked and you use `qmd search`/`qmd query` (or `scripts/qmd-sync search`)
-  instead. When QMD is present but stale, the search is allowed this turn and a background
-  reindex is fired so the next turn enforces against a fresh index; reindex is never
-  synchronous. When QMD is absent, the search is allowed.
-- Reading a known target (the Read tool, bash `cat`/`head`/`tail`) and structural discovery
-  (the Glob tool, bash `find`/`ls`) are always allowed, including over the store. QMD cannot
-  list directories or hand back one specific file, so these are never gated.
-- Code is never hard-gated here. Symbolic code navigation via Serena is a soft prompt mandate
-  (the UserPromptSubmit power-tools hook), not a block: content grep over code is allowed,
-  because Serena navigates symbols and cannot grep arbitrary strings.
-- QMD failure model. Absent or stale degrades to allow (stale also fires the background
-  reindex). A broken QMD, where the freshness probe errors or times out, also fails open, and
-  the hook emits a one-line warning so a degraded QMD is visible rather than silent.
-- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command when you attempted
-  discovery and it did not serve you (no hits, or results that do not answer your need by your
-  reading of the snippets, not their score). A quoted or echoed occurrence does not bypass.
-  Bypasses are logged. The gate enforces that discovery was attempted, never that it succeeded.
-- Scope: only the agent's tool calls. Ruby `File.read` inside a script is invisible to the gate
-  and is out of scope by design.
+Advisory. Hard gates guard writes, locks, and structure, never reads or searches. Read,
+Grep, Glob, and bash search are always allowed, including over the stores. When QMD is
+present and fresh, a content search over store markdown receives an advisory hint pointing
+at `qmd search` alongside its result; when QMD is present but stale, a background reindex
+fires so the next turn's hint runs against a fresh index (never synchronous). QMD and
+Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook appends
+one recommendation line per present tool. The legacy trailing `# qmd-ok` token is still
+accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
+calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
 ## Context-economy measurement buckets (84a)
 
@@ -332,11 +315,28 @@ Hard blocking — hooks exit code 2 on gate failure.
 
 ## Delivery Isolation and the Single-Owner Lock
 
-Exactly one session or agent develops an intent's delivery at a time. Ownership is the armed
-session bridge, which doubles as the delivery lock: arming records the owning session, the
-owner pid, an acquired-at timestamp, and the host. Another session that finds an armed bridge
-for the same intent with a live owner backs off; if the owner pid is dead the lock is
-reclaimable. This is mandatory, not a convention.
+Exactly one session or agent develops an intent's delivery at a time. Ownership is
+session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
+(atomically, O_EXCL), recording the owner session, the host, the acquired-at time, a
+delegates list, and the lock type. Liveness is a lease: the owner's hooks refresh the lock
+file's mtime on tool activity, and the lock counts as stale only when that heartbeat is
+older than the TTL. No process id is consulted anywhere. The /tmp session bridge is a cache
+of this state; on any disagreement, or when the bridge is missing, the lock file wins.
+Another session that finds a fresh lock backs off; a stale lock is reclaimed only by
+explicit takeover, which replaces the lock and appends an audit line to the intent's
+savepoint.md. Subagents spawned by the owner write under the owner's lock once registered
+as delegates. Disarm clears the lock; the End tail is ordered: verify, merge and remove
+worktrees, clear the lock, and only then is the bridge purge-eligible. Repair is one
+idempotent function with two entry points: the `plastic-lock` command (status, fix,
+release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. This is
+mandatory, not a convention.
+
+Two locks share this schema (the two-lock doctrine): `delivery.lock` (exclusive, one owner
+plus delegates) and the future `maintenance.lock` (short TTL, structural move-and-record
+only). They are mutually exclusive in either direction; maintenance is allowed at any
+lifecycle stage provided no delivery lock is held. Intent 108 ships the delivery lock and
+the mutual-exclusion seam; the maintenance lock implementation follows intent 93 in a
+chained intent.
 
 Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
 for that intent happen only inside it. Plastic provisions the worktree deterministically: it
@@ -350,6 +350,76 @@ Provisioning fails open for intents that touch no project code (pure research or
 intents in the global store, or a non-git repo): those get the lock only, and the worktree
 block stays unprovisioned. The fail-open path is always logged, never silent.
 
+### Intent delivery, station by station
+
+How one intent travels from boarding to Done, and what the lock, bridge, and gates do at
+each station.
+
+| Station | Delivered artifact | Lock and bridge steps | Pre-stage gate | Post-stage record |
+|---|---|---|---|---|
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree, writes the bridge cache | lock-gate denies any write into an active intent dir without this intent's lock; every deny names the resolving command | savepoint confirms the boarding station |
+| What (create) | `<id>--<slug>.md`, born complete | no lock yet; no bridge | create-gate validates the proposed intent content (Write, Edit, and MCP edits) | savepoint `What` line; intent listed in INDEX `## Active` |
+| Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | gate-check requires the intent file with `## Intent` before spec.md; lock-gate admits only the owner or a delegate | savepoint `Why started`, `Why spec.md created` |
+| How | `plan.md`, `actions/`, `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md plus checklist.md exist | gate-check requires spec.md before plan.md, and plan.md plus actions/ before checklist.md | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
+| Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock; bash, interpreter, and MCP writes gated the same way | code-gate, worktree-gate, bash-gate, lock-gate | checklist boxes; savepoint milestones |
+| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the bridge is purge-eligible, and the QMD reindex runs LAST (after purge) | gate-check blocks outcome.md while checklist items are unchecked | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
+| Maintenance (any stage) | `revisions.md` move-and-record entries | future `maintenance.lock` (short TTL), mutually exclusive with `delivery.lock` in either direction; 108 ships the schema seam only, the implementation follows intent 93 in a chained intent | acquisition refuses while the other lock type is fresh; a terminal intent with no lock held is read-only | dated, rule-tagged `revisions.md` entry; savepoint untouched |
+
+### What "intent done" means (intent 93)
+
+Done is one law with three signals, and they must agree. INDEX `## Completed` /
+`## Abandoned` is the single canonical terminal marker: it is the store-wide ledger a fresh
+session reads first, so it wins on any conflict. `outcome.md` is the "deliverable exists"
+signal, and the savepoint `Done delivered|abandoned` line is the audit echo. All three must
+agree; when they disagree, INDEX is authoritative and `doctor` flags the mismatch (the
+`done_signals` check: `outcome.md` real but still under `## Active`, or terminal without a
+real `outcome.md`, or a terminal intent whose savepoint carries no `Done` line).
+
+`outcome.md` is mandatory at every terminal transition, delivered and abandoned alike. It
+self-declares its disposition through a `disposition: delivered|abandoned` frontmatter
+header. The delivered path authors it with the result; the abandoned path authors it with
+the abandonment reason and no longer leaves the scaffolded placeholder sentinel in place.
+
+The canonical End tail runs in this order, and the QMD reindex is always LAST, after the
+purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Worktree.release
+-> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
+ever referencing a bridge or lock that disarm is about to remove.
+
+The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
+the completing session keeps full read and write access to the terminal directory and no
+purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
+Once the lock is released the window closes: the bridge becomes purge-eligible and the
+directory is frozen. A crash mid-tail is recovered by stale-lock reclaim plus finishing the
+tail; `doctor` surfaces this as a "stalled completion" (terminal in INDEX but the lock is
+still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
+a done intent is never moved back to `## Active`.
+
+Terminal immutability (the contract intent 112 enforces): a terminal directory is writable
+ONLY while a lock is held. The delivery lock covers the completing session's End tail up to
+`Lock.release`; the maintenance lock covers sanctioned structural move-and-record edits
+after. Terminal with no lock held is frozen. There are only two locks in the system,
+delivery and maintenance (108 D11). This governs WRITES only: reads of a terminal intent are
+always allowed and unbounded (curator reindex, dashboards, and future intents that reference
+its id or chain), so a done intent stays fully readable forever. Intent 93 states this rule;
+intent 112 builds the gate that enforces it.
+
+Fail-safe lock doctrine (the contract intent 111 implements): the lock system never traps a
+session or burns credits. When a gate cannot verify lock integrity it fails open, degrading
+to advisory (warn) rather than hard-blocking. Repair is orchestrator-driven: on a lock-issue
+signal the orchestrator inspects and repairs the lock automatically, and the human
+`plastic-lock` command is a fallback path, not the trigger. Intent 93 states this doctrine;
+intent 111 builds the fail-open behavior, the lock-liveness surface, the lock-issue message,
+and the auto-repair.
+
+Scope split. Intent 93 ships doctrine plus the low-risk reconciliation that needs no new
+lock: the canonical done-marker and three-signal reconciliation, the mandatory `outcome.md`
+plus `disposition` header at both terminals, the End tail with the reindex moved last, the
+`done_signals` doctor check (three-signal agreement plus stalled-completion detection), and
+the lock-bounded post-done window with its keep-guard test. Intent 111 owns the lock
+liveness surface, the lock-issue message, orchestrator auto-repair, and the fail-open
+behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
+fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
+
 ## Deprecation Process
 
 Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is

package/agents/plastic-intent-curator.md

@@ -32,7 +32,10 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
 3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
-5. On a terminal-state transition: whenever you move an intent to Completed OR Abandoned, refresh the QMD index for that store so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
+5. On a terminal-state transition (Completed OR Abandoned), run the closing acts in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+   a. 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).
+   b. Stamp the terminal savepoint bookend (intent 81) recording the disposition. Idempotent.
+   c. Refresh the QMD index for that store LAST, after the terminal move, outcome.md, and savepoint, so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
 6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
 7. Report what you changed
 

package/hooks/code-gate

@@ -1,6 +1,15 @@
 #!/bin/bash
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
+  if !path.empty? && !path.start_with?("/")
+    root = ti["project_root"] || data["cwd"] || ""
+    path = File.join(root, path) unless root.empty?
+  end
+  puts path
+' 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
   exit 0

package/hooks/hooks.json

@@ -19,7 +19,7 @@
     ],
     "PreCompact": [
       {
-        "matcher": "manual|auto",
+        "matcher": "",
         "hooks": [
           {
             "type": "command",
@@ -31,7 +31,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|NotebookEdit",
+        "matcher": "Write|Edit|NotebookEdit|mcp__serena__replace_content|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__safe_delete_symbol|mcp__serena__rename_symbol",
         "hooks": [
           {
             "type": "command",
@@ -56,7 +56,7 @@
         ]
       },
       {
-        "matcher": "Write",
+        "matcher": "Write|Edit|mcp__serena__replace_content|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__safe_delete_symbol|mcp__serena__rename_symbol",
         "hooks": [
           {
             "type": "command",

package/hooks/lock-gate

@@ -1,6 +1,15 @@
 #!/bin/bash
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
+  if !path.empty? && !path.start_with?("/")
+    root = ti["project_root"] || data["cwd"] || ""
+    path = File.join(root, path) unless root.empty?
+  end
+  puts path
+' 2>/dev/null)
 
 if [ -z "$FILE_PATH" ]; then
   exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.24",
+  "version": "1.0.0-beta.26",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/doctor.rb

@@ -20,6 +20,9 @@ require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
+require_relative "lib/hook_registry"
+require_relative "lib/lock"
+require_relative "lib/bridge"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -504,6 +507,184 @@ class Doctor
     checks
   end
 
+  # --- Check: the three done-signals agree + stalled completion (intent 93) ---
+  #
+  # "Done" is one law with three signals that MUST agree: INDEX
+  # `## Completed`/`## Abandoned` is the single canonical terminal marker;
+  # `outcome.md` is the "deliverable exists" signal (real, non-placeholder, with a
+  # `disposition:` header); the savepoint `Done` line is the audit echo. INDEX
+  # wins on conflict. This check flags any disagreement, and separately surfaces a
+  # "stalled completion": an intent that is terminal in INDEX but whose End tail
+  # never released its `delivery.lock` (the post-done window never closed). Read
+  # only, dependency-light: it uses INDEX parsing, file presence, the placeholder
+  # sentinel, and `Lock.fresh?` — no new lock, no 111 lock-liveness surface.
+
+  # For one store's INDEX.md, map each referenced intent directory name to the
+  # `## ...` section(s) it appears under: { "<id>--<slug>" => ["Active", ...] }.
+  def index_sections_by_dir(index_path)
+    sections = Hash.new { |h, k| h[k] = [] }
+    return sections unless File.exist?(index_path)
+
+    current = nil
+    File.foreach(index_path) do |line|
+      if (m = line.match(/^##\s+(.+?)\s*$/))
+        current = m[1]
+        next
+      end
+      next unless current
+
+      line.scan(%r{store/([\w][\w.-]*?)(?:/|\))}) do |(dirname)|
+        sections[dirname] << current unless sections[dirname].include?(current)
+      end
+    end
+    sections
+  end
+
+  # Stores to reconcile: the global store plus each project store, filtered by
+  # `scopes` (nil = all) exactly like check_conventions.
+  def done_signal_stores(scopes)
+    stores = []
+
+    if scopes.nil? || scopes.include?("global")
+      stores << {
+        scope: "global",
+        index: File.join(plastic_home, "INDEX.md"),
+        store_dir: File.join(plastic_home, "store"),
+      }
+    end
+
+    projects_root = File.join(plastic_home, "projects")
+    if File.directory?(projects_root)
+      Dir.children(projects_root).sort.each do |project|
+        scope = "project:#{project}"
+        next unless scopes.nil? || scopes.include?(scope)
+
+        store_dir = File.join(projects_root, project, "store")
+        next unless File.directory?(store_dir)
+
+        stores << {
+          scope: scope,
+          index: File.join(projects_root, project, "INDEX.md"),
+          store_dir: store_dir,
+        }
+      end
+    end
+
+    stores
+  end
+
+  def check_done_signals(scopes: nil)
+    conflicts = [] # canonical INDEX-wins disagreement (fail)
+    gaps = []      # terminal completeness gaps on immutable/legacy history (warn)
+    stalled = []   # terminal but End tail unfinished (warn)
+
+    done_signal_stores(scopes).each do |store|
+      index_sections_by_dir(store[:index]).each do |dirname, in_sections|
+        dir = File.join(store[:store_dir], dirname)
+        next unless File.directory?(dir)
+
+        terminal = (in_sections & ["Completed", "Abandoned"]).any?
+        active = in_sections.include?("Active") && !terminal
+        outcome = File.join(dir, "outcome.md")
+        outcome_real = Bridge.stage_file_present?(outcome)
+        label = "#{store[:scope]} store/#{dirname}"
+
+        # HARD conflict: the deliverable exists but INDEX still says Active. This
+        # is the one true INDEX-wins disagreement, so it stays a fail.
+        if active && outcome_real
+          conflicts << "#{label}: outcome.md is real but the intent is still under ## Active " \
+                       "(INDEX is canonical — move it to its terminal section or revert outcome.md)"
+        end
+
+        # Completeness gap (warn, not fail): a terminal intent whose outcome.md is
+        # missing/placeholder. Legacy terminal intents predate this convention and
+        # are immutable, so this is advisory, never breakage.
+        if terminal && !outcome_real
+          state = File.exist?(outcome) ? "still a placeholder" : "missing"
+          gaps << "#{label}: terminal in INDEX but outcome.md is #{state} " \
+                  "(author outcome.md with the disposition header)"
+        end
+
+        next unless terminal
+
+        # Audit echo (weakest signal, D1): the savepoint should carry a
+        # `Done delivered|abandoned` line. Missing on legacy history -> advisory gap.
+        savepoint = File.join(dir, "savepoint.md")
+        if File.exist?(savepoint) && File.read(savepoint) !~ /\bDone\b.*\b(delivered|abandoned)\b/
+          gaps << "#{label}: terminal in INDEX but savepoint.md has no " \
+                  "`Done delivered|abandoned` line (audit echo missing)"
+        end
+
+        # Stalled completion: the End tail never released the delivery lock, so the
+        # post-done window `[INDEX terminal -> Lock.release]` never closed.
+        if File.exist?(Lock.path(dir))
+          note = Lock.fresh?(dir) ? "delivery.lock still present (post-done window not closed)"
+                                  : "delivery.lock is present and STALE"
+          stalled << "#{label}: #{note} — the End tail did not finish"
+        end
+      end
+    end
+
+    checks = []
+
+    # signals_agree: only the canonical INDEX-wins conflict is a hard fail, so
+    # `doctor` never goes red on immutable legacy terminal intents.
+    if conflicts.empty?
+      checks << check(
+        category: "done_signals", name: "signals_agree", status: "pass",
+        message: "No done-signal conflicts (no intent has a real outcome.md while still Active)"
+      )
+    else
+      checks << check(
+        category: "done_signals", name: "signals_agree", status: "fail",
+        message: "#{conflicts.size} done-signal conflict#{conflicts.size == 1 ? "" : "s"} " \
+                 "(INDEX ## Completed/## Abandoned is canonical; a real outcome.md must not stay Active)",
+        details: conflicts, fixable: true,
+        fix_hint: "Reconcile to INDEX (canonical): move the intent to its terminal section, or revert " \
+                  "outcome.md to a placeholder. Deliverable-exists but still-Active is the one done-signal " \
+                  "state that must never persist."
+      )
+    end
+
+    # signals_complete: terminal completeness gaps are advisory (warn), because
+    # completed intents are immutable and legacy history predates this convention.
+    if gaps.empty?
+      checks << check(
+        category: "done_signals", name: "signals_complete", status: "pass",
+        message: "Every terminal intent carries a real outcome.md and a Done savepoint echo"
+      )
+    else
+      checks << check(
+        category: "done_signals", name: "signals_complete", status: "warn",
+        message: "#{gaps.size} terminal completeness gap#{gaps.size == 1 ? "" : "s"} " \
+                 "(outcome.md or the savepoint Done echo is missing; advisory on immutable history)",
+        details: gaps, fixable: true,
+        fix_hint: "For live terminals, author a real outcome.md with the `disposition:` header via the " \
+                  "completion/abandon path (plastic-auto or plastic-intent-curator) and stamp the terminal " \
+                  "savepoint. Legacy terminal intents are immutable, so pre-convention gaps stay advisory."
+      )
+    end
+
+    if stalled.empty?
+      checks << check(
+        category: "done_signals", name: "stalled_completion", status: "pass",
+        message: "No stalled completions (every terminal intent released its delivery lock)"
+      )
+    else
+      checks << check(
+        category: "done_signals", name: "stalled_completion", status: "warn",
+        message: "#{stalled.size} stalled completion#{stalled.size == 1 ? "" : "s"} " \
+                 "(terminal in INDEX but the End tail did not finish)",
+        details: stalled, fixable: true,
+        fix_hint: "Finish the End tail via stale-lock reclaim: `plastic-lock reclaim`, then complete the " \
+                  "tail (Worktree.release -> Lock.release -> purge -> QMD reindex last). This FINISHES a " \
+                  "completion; it is NOT a reactivation of a done intent."
+      )
+    end
+
+    checks
+  end
+
   # Build the cross-store node maps (basename + label per store) + relocation map
   # from ALL stores, then for every intent compute its canonical `## Links`
   # projection and flag any whose ACTUAL `## Links` section differs (membership or
@@ -827,6 +1008,45 @@ class Doctor
           fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
         )
       end
+
+      # hooks_match_registry (intent 108, D7): the live settings must carry
+      # EXACTLY the registrations HookRegistry defines; any drift (a missing
+      # gate, a stray plastic hook, a stale matcher) is how bash-gate shipped
+      # dead once already.
+      expected = HookRegistry.claude_settings_hooks(hook_dir: hooks_dir)
+      diffs = []
+      expected.each do |event, group|
+        groups = group.is_a?(Array) ? group : [group]
+        live = settings.dig("hooks", event) || []
+        groups.each do |g|
+          match = live.find { |h| h.is_a?(Hash) && h["matcher"] == g["matcher"] }
+          wanted = g["hooks"].map { |h| h["command"] }
+          got = match ? Array(match["hooks"]).map { |h| h["command"] } : []
+          missing = wanted - got
+          diffs << "#{event}[#{g['matcher']}] missing: #{missing.join(', ')}" unless missing.empty?
+        end
+      end
+      live_plastic = (settings["hooks"] || {}).flat_map do |event, groups|
+        Array(groups).flat_map do |g|
+          next [] unless g.is_a?(Hash) && g["hooks"].is_a?(Array)
+          g["hooks"].map { |h| h["command"].to_s }.select { |c| c.include?("plastic-") }
+                    .map { |c| "#{event}: #{c}" }
+        end
+      end
+      expected_cmds = expected.values.flat_map { |g| g.is_a?(Array) ? g : [g] }
+                              .flat_map { |g| g["hooks"].map { |h| h["command"] } }
+      strays = live_plastic.reject { |lp| expected_cmds.any? { |c| lp.end_with?(c) } }
+      diffs.concat(strays.map { |s| "stray: #{s}" })
+
+      checks << if diffs.empty?
+        check(category: "agent_registration", name: "hooks_match_registry",
+              status: "pass", message: "settings.json hooks match HookRegistry")
+      else
+        check(category: "agent_registration", name: "hooks_match_registry",
+              status: "fail", message: "#{diffs.size} hook registration(s) diverge from HookRegistry",
+              details: diffs, fixable: true,
+              fix_hint: "Re-run the installer merge: npx @zalom/plastic update (or ruby ~/.plastic/scripts/install.rb)")
+      end
     end
 
     # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
@@ -1417,6 +1637,7 @@ class Doctor
     all_checks += check_project_stores
     all_checks += check_deprecations
     all_checks += check_qmd
+    all_checks += check_done_signals
 
     summarize(all_checks, agent_key)
   end
@@ -1443,9 +1664,9 @@ class Doctor
     all_checks =
       case store
       when :all
-        check_global_store + check_project_stores + check_conventions
+        check_global_store + check_project_stores + check_conventions + check_done_signals
       when :global
-        check_global_store + check_conventions(scopes: ["global"])
+        check_global_store + check_conventions(scopes: ["global"]) + check_done_signals(scopes: ["global"])
       else
         all_checks_for_project_slug(store)
       end
@@ -1468,7 +1689,8 @@ class Doctor
     end
 
     check_project_store(slug, projects[slug]) +
-      check_conventions(scopes: ["project:#{slug}"])
+      check_conventions(scopes: ["project:#{slug}"]) +
+      check_done_signals(scopes: ["project:#{slug}"])
   end
 
   # Roll a list of checks up into the standard result envelope.

package/scripts/hook-bash-gate

@@ -28,13 +28,31 @@ exit 0 if command.nil? || command.to_s.strip.empty?
 cwd = payload["cwd"]
 cwd = Dir.pwd if cwd.nil? || cwd.to_s.empty?
 
-# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 session = payload["session_id"]
 session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.to_s.empty?
+
+# Auditable escape (intent 108, D7): a trailing `# plastic-ok` allows the
+# command and logs it, so sanctioned writes are visible, not silent.
+if Bridge.bash_escape?(command)
+  begin
+    require "fileutils"
+    log = File.join(Dir.home, ".plastic", ".cache", "gate-escapes.log")
+    FileUtils.mkdir_p(File.dirname(log))
+    File.open(log, "a") do |io|
+      io.puts("#{Time.now.utc.iso8601}\t#{session}\t#{command.gsub(/\s+/, ' ').strip}")
+    end
+  rescue StandardError
+    # the escape still applies; logging is best-effort
+  end
+  exit 0
+end
+
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
+# A nil bridge does NOT short-circuit (intent 108): the lock gate decides from
+# the durable delivery.lock file, so it must run even without a bridge cache.
 bridge_data = Bridge.discover_bridge(session: session, cwd: cwd)
-exit 0 unless bridge_data
 
-reason = Bridge.bash_gate_decision(bridge_data, command, cwd: cwd)
+reason = Bridge.bash_gate_decision(bridge_data, command, cwd: cwd, session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/hook-create-gate

@@ -19,8 +19,13 @@
 # Reads the Claude Code PreToolUse payload as JSON on STDIN:
 #   { "tool_input": { "file_path": "...", "content": "..." } }
 # Empty / unparseable / non-matching path => exit 0 (cannot judge, allow).
-# Matching path but missing content => exit 2 (fail-safe: refuse to allow an
-# unvalidated intent write).
+# Three payload shapes on a matching path (intent 108, D7):
+#   Write (content):        validate the proposed content.
+#   Edit (old_string):      simulate the replacement on the on-disk file and
+#                           validate the RESULT; a missing file blocks.
+#   Pathless MCP mutation:  validate the CURRENT on-disk file (the PostToolUse
+#                           gate-check backstop validates the result); a
+#                           missing file blocks (fail-safe).
 
 require "json"
 require_relative "lib/intent_validator"
@@ -43,14 +48,45 @@ is_intent_file = dir.match?(%r{/store/[^/]+--[^/]+\z}) &&
                  File.basename(abs) == "#{File.basename(dir)}.md"
 exit 0 unless is_intent_file
 
-content = payload.dig("tool_input", "content") || payload.dig("tool_params", "content")
-if content.nil?
-  $stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)}: cannot read proposed content; " \
-               "refusing to allow an unvalidated intent write."
+input = payload["tool_input"] || payload["tool_params"] || {}
+content = input["content"]
+old_string = input["old_string"]
+
+def block!(lines)
+  Array(lines).each { |l| $stderr.puts l }
   exit 2
 end
 
-result = IntentValidator.validate_content(content)
+result =
+  if !content.nil?
+    # Write: validate the proposed content (intent 60b, unchanged).
+    IntentValidator.validate_content(content)
+  elsif !old_string.nil?
+    # Edit (intent 108, D7): simulate the replacement on the on-disk file and
+    # validate the RESULT, so an Edit can no longer sneak an intent file past
+    # the validator.
+    unless File.exist?(abs)
+      block!("PLASTIC CREATE GATE — #{File.basename(abs)} does not exist; " \
+             "create intents via new-intent / plastic-creating-intent.")
+    end
+    current = File.read(abs)
+    unless current.include?(old_string)
+      exit 0 # the Edit tool itself will fail; nothing lands, nothing to judge
+    end
+    simulated = input["replace_all"] ? current.gsub(old_string, input["new_string"].to_s)
+                                     : current.sub(old_string, input["new_string"].to_s)
+    IntentValidator.validate_content(simulated)
+  else
+    # Pathless mutation (MCP symbolic edits): the proposal is not visible at
+    # PreToolUse. Judge the CURRENT file: valid -> allow (the PostToolUse
+    # gate-check backstop validates the result), invalid/missing -> block.
+    unless File.exist?(abs)
+      block!("PLASTIC CREATE GATE — #{File.basename(abs)}: cannot read proposed " \
+             "content and no file exists; refusing to allow an unvalidated intent write.")
+    end
+    IntentValidator.validate_content(File.read(abs))
+  end
+
 exit 0 if result[:ok]
 
 $stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)} is not a valid intent:"

package/scripts/hook-gate-check

@@ -9,6 +9,7 @@
 require "json"
 require_relative "lib/bridge"
 require_relative "lib/intent_validator"
+require_relative "lib/lock"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
@@ -72,6 +73,15 @@ intent_dir = "#{store}/#{dir}"
 # Normalize both paths for comparison
 bridge_intent_dir_abs = File.expand_path(intent_dir)
 
+# Lease heartbeat (intent 108, D1): every write by the session that owns (or
+# delegates under) the lock refreshes the delivery.lock mtime. Best-effort:
+# a heartbeat failure must never break the gate hook.
+begin
+  Lock.heartbeat(bridge_intent_dir_abs, session: session)
+rescue StandardError
+  # ignore
+end
+
 # Not inside intent dir = not our business
 exit 0 unless file_path_abs.start_with?("#{bridge_intent_dir_abs}/")