@zalom/plastic 1.0.0-beta.9 → 1.0.1

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).
@@ -472,7 +475,10 @@ class Doctor
         category: "conventions", name: "section_structure", status: "warn",
         message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
         details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
-        fixable: false
+        fixable: true,
+        fix_hint: "Dispatch plastic-intent-curator to relocate each unsanctioned section into the " \
+                  "intent's revisions.md via move-and-record (a missing required section is restored " \
+                  "or reprojected instead); see PLASTIC.md > Structural maintenance and revisions.md"
       )
     end
 
@@ -501,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
@@ -698,7 +882,9 @@ class Doctor
     checks << graph_finding_check(
       "graph_i4_danglers", i4,
       "Every sources/chain id resolves to a real intent (I4)",
-      "Fix or remove the dangling id reference"
+      "Dispatch plastic-intent-curator to record the dangling sources/chain edge as a " \
+      "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
+      "PLASTIC.md > Structural maintenance and revisions.md), or restore the missing intent"
     )
     checks
   end
@@ -822,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|
+          matches = live.select { |h| h.is_a?(Hash) && h["matcher"] == g["matcher"] }
+          wanted = g["hooks"].map { |h| h["command"] }
+          got = matches.flat_map { |m| Array(m["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>/)
@@ -1412,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
@@ -1438,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
@@ -1463,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-auto-arm

@@ -26,7 +26,7 @@ if triggered
 end
 
 # --- 2. Standing gate reminder when armed and pre-How ---
-bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_SESSION_ID"], cwd: Dir.pwd)
+bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd)
 if bridge_data && bridge_data.dig("build", "auto") == true
   intent = bridge_data["intent"] || {}
   store = intent["store"]; dir = intent["dir"]

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 -> env -> /tmp scan) ---
 session = payload["session_id"]
-session = ENV["CLAUDE_SESSION_ID"] if session.nil? || session.to_s.empty?
+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-code-gate

@@ -3,24 +3,47 @@
 # frozen_string_literal: true
 
 # Usage: hook-code-gate <file_path>
-# PreToolUse gate (intent 27): when auto mode is armed and the active intent has not
-# reached How (plan.md + checklist.md), block edits to project code outside the store.
+# PreToolUse gate. Composes two independent block rules; EITHER blocks the edit:
+#   - Stage rule (intent 27): when auto mode is armed and the active intent has not
+#     reached How (plan.md + checklist.md), block edits to project code outside the store.
+#   - Worktree isolation rule (intent 73c2): when the intent has a provisioned code
+#     worktree, block project-code edits outside it; and block edits to another
+#     intent's store dir whose delivery lock is held by a live non-owner session.
 #
 # Exit 0 = allow. Exit 2 = block (reason on stderr, shown to the agent).
-# No bridge / auto not armed / How reached / path under ~/.plastic or the intent dir = allow.
+# No bridge = allow. Each rule fails open on its own conditions (see bridge.rb).
 
 require_relative "lib/bridge"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
-# --- Load bridge (shared resolution; stdin session_id -> env -> /tmp scan) ---
-bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
+# Auditable escape (intent 150, mirrors the Bash gate's intent 108 D7): a trailing
+# `# plastic-ok` in the new Write/Edit content allows the edit and logs it, so a
+# deliberately sanctioned code edit no longer needs the Bash-funneling workaround.
+new_content = ARGV[2]
+if new_content && Bridge::PLASTIC_OK_RE.match?(new_content.chomp)
+  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#{file_path}")
+    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) ---
+bridge_data = Bridge.discover_bridge(session: session, cwd: file_path)
 exit 0 unless bridge_data
 
-reason = Bridge.code_gate_decision(bridge_data, file_path)
+reason = Bridge.code_gate_decision(bridge_data, file_path) ||
+         Bridge.worktree_gate_decision(bridge_data, file_path, current_session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/hook-continue

@@ -7,6 +7,7 @@
 
 require "json"
 require "open3"
+require_relative "lib/dashboard_banner"
 
 index_path, _store_root, _mode = ARGV
 exit 0 unless index_path && File.exist?(index_path)
@@ -28,4 +29,20 @@ payload = {
     "additionalContext" => context
   }
 }
+
+# Hook-owned systemMessage floor (intent 125, Task 6): a hard fallback summary
+# independent of the agent's reply, mirroring hook-session-start's BootBanner
+# pattern. Best-effort only — any failure here (subprocess, JSON, renderer)
+# degrades silently, omitting systemMessage; this hook must never crash
+# UserPromptSubmit over a summary line.
+begin
+  data_json, _data_err, data_status = Open3.capture3("ruby", dashboard, "continue", "--data")
+  if data_status.success?
+    banner = DashboardBanner.render(JSON.parse(data_json))
+    payload["systemMessage"] = banner if banner
+  end
+rescue StandardError
+  nil
+end
+
 puts JSON.generate(payload)

package/scripts/hook-create-gate

@@ -9,8 +9,8 @@
 # the on-disk file (which does not exist yet at PreToolUse), using IntentValidator
 # for born-complete frontmatter plus the sanctioned section structure.
 #
-# It depends ONLY on the stdin path + content, never on the auto-bridge or
-# CLAUDE_SESSION_ID, so it runs unconditionally (headless / background sessions).
+# It depends ONLY on the stdin path + content, never on the auto-bridge or any
+# session id, so it runs unconditionally (headless / background sessions).
 # It validates ONLY the intent file, never sentinel placeholder lifecycle files
 # (spec.md/plan.md/etc.); the path matcher excludes them.
 #
@@ -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,11 +9,12 @@
 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?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
 file_path_abs = File.expand_path(file_path)
 
@@ -24,6 +25,12 @@ intent_dir_abs = Bridge.intent_dir_for(file_path_abs)
 if intent_dir_abs
   begin
     Bridge.append_savepoint(intent_dir_abs, file_path_abs)
+    # When checklist.md lands, How ends and Exec begins: emit the `Exec started`
+    # companion in the same event (intent 81). Guard on a real (non-placeholder)
+    # checklist so a scaffold sentinel does not trip it.
+    if File.basename(file_path_abs) == "checklist.md" && Bridge.stage_file_present?(file_path_abs)
+      Bridge.append_exec_started(intent_dir_abs)
+    end
   rescue StandardError
     # ignore — rebuildable from disk
   end
@@ -66,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}/")
 
@@ -112,32 +128,17 @@ if is_stage_file || is_action_file
 
   Bridge.write(session, bridge_data)
 
-  # Build transition context
-  stage_labels = { "what" => "What", "why" => "Why", "how" => "How", "exec" => "Exec", "done" => "Done" }
-  next_hints = {
-    "why" => "write spec.md",
-    "how" => "Why complete. Invoke plastic-auto to deliver autonomously, or write plan.md manually.",
-    "exec" => "How complete. Invoke plastic-auto or plastic-executing-plan to execute, or work through the checklist manually.",
-    "done" => "Exec complete. Intent must be completed now — write outcome.md, update INDEX.md, auto-commit. Use plastic-auto or do it manually."
-  }
-
-  context_parts = ["PLASTIC"]
-  if old_stage != new_stage
-    context_parts[0] = "PLASTIC — Stage transition: #{stage_labels[old_stage] || old_stage} → #{stage_labels[new_stage] || new_stage}."
-  else
-    context_parts[0] = "PLASTIC — #{basename} written (stage: #{stage_labels[new_stage] || new_stage})."
-  end
-  context_parts << "#{basename} written."  if old_stage != new_stage
-  if new_missing.any?
-    context_parts << "Next: #{new_missing.join(", ")}"
-  elsif next_hints[new_stage]
-    context_parts << "Next: #{next_hints[new_stage]}"
-  end
+  # Build transition context — ONE concise sentence (intent 84, Lever 1),
+  # preserving the `Next: ...` hint. Formatting is pure in Bridge.gate_narration.
+  context = Bridge.gate_narration(
+    old_stage: old_stage, new_stage: new_stage,
+    basename: basename, new_missing: new_missing
+  )
 
   payload = {
     "hookSpecificOutput" => {
       "hookEventName" => "PostToolUse",
-      "additionalContext" => context_parts.join(" ")
+      "additionalContext" => context
     }
   }
   puts JSON.generate(payload)

package/scripts/hook-lock-gate

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+#
+# Usage: hook-lock-gate <file_path> [session_id]
+# Fail-CLOSED PreToolUse gate (intent 96). Blocks a mutating write to an active
+# intent's lifecycle dir when THIS session holds no live lock. Project code is NOT
+# gated here (D2). Emits the PreToolUse JSON deny contract at exit 0; reserves
+# non-zero exit for hook-internal errors only. Matcher Write|Edit|NotebookEdit, so
+# reads never reach here.
+require "json"
+require_relative "lib/bridge"
+require_relative "lib/lock"
+
+begin
+  file_path = ARGV[0]
+  exit 0 unless file_path && !file_path.empty?
+  session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
+
+  bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)   # nil = no bridge cache
+  reason = Bridge.lock_gate_decision(bridge_data, file_path, session: session)
+  unless reason
+    # Allow path: refresh the lease for the session that holds this target's
+    # lock (owner or delegate). Best-effort, never blocks.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      Lock.heartbeat(dir, session: session) if dir && !session.to_s.empty?
+    rescue StandardError
+      # ignore
+    end
+
+    # Second, independent gate (intent 111 D7): the artifact-grain claim.
+    # Composes UNDER the delivery lock above; only reached once the delivery
+    # lock already allows. Dormant (nil) unless a claim file exists for this
+    # artifact, so AC7 (existing single-owner flows) is unaffected.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      artifact = File.basename(file_path) if dir
+      if dir && artifact
+        claim_reason = Claim.claim_gate_reason(dir, artifact, session: session)
+        if claim_reason
+          print JSON.generate(
+            "hookSpecificOutput" => {
+              "hookEventName" => "PreToolUse",
+              "permissionDecision" => "deny",
+              "permissionDecisionReason" => claim_reason,
+            }
+          )
+          exit 0
+        end
+
+        # Fail-open surface (AC3): allow, but make the yielded/stale claim visible.
+        if Claim.fail_open?(dir, artifact)
+          $stderr.puts "plastic claim gate: unresolvable claim on #{artifact} in " \
+                       "intent #{Bridge.intent_id_from_dir(dir)} yielded; write " \
+                       "proceeds (see /plastic-lock status)"
+        end
+
+        # Heartbeat the session's own claim on the allow path (best-effort).
+        Claim.heartbeat(dir, artifact, session: session) rescue nil
+      end
+    rescue StandardError
+      # ignore: a claim-gate bug must never block a write (fail open)
+    end
+
+    exit 0
+  end
+
+  print JSON.generate(
+    "hookSpecificOutput" => {
+      "hookEventName" => "PreToolUse",
+      "permissionDecision" => "deny",
+      "permissionDecisionReason" => reason   # "run /plastic-intent-starting to lock and begin"
+    }
+  )
+  exit 0
+rescue => e
+  # Hook-internal failure only: do NOT impersonate a user-deny. Log and fail open
+  # here so a gate bug never bricks editing; the fail-CLOSED intent is about MISSING
+  # locks, not crashes.
+  $stderr.puts "plastic lock-gate error: #{e.message}"
+  exit 0
+end