@zalom/plastic 1.0.0-beta.3 → 1.0.0-beta.31

package/scripts/lib/links_section.rb

@@ -0,0 +1,207 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_validator"
+
+# LinksSection — pure, minimal, style-preserving rewrite of ONLY the `## Links`
+# section of an intent file's content string (intent 72). Mirrors the discipline of
+# FrontmatterWriter: pure (no file IO, no eval, no global/ENV state), and returns
+# the original content UNCHANGED when nothing changed (idempotency).
+#
+# `## Links` is canonically the LAST sanctioned section
+# (IntentValidator::SANCTIONED_SECTIONS = Intent, Context, Outcome, Insights,
+# Links), and real intents put it last. So a file with an existing `## Links` has
+# its section replaced in place (from the heading to the next top-level `## `
+# heading or EOF), and a file WITHOUT a `## Links` gets one appended at end-of-body,
+# separated by exactly one blank line, preserving the body's trailing-newline shape.
+#
+# FENCE AWARENESS (intent 72 corruption fix): a `## Links` heading INSIDE a fenced
+# code block (``` or ~~~, possibly with an info string like ```markdown) is part of
+# an EXAMPLE, not a real section. All section scanning here IGNORES headings inside
+# fences and only ever targets the REAL `## Links` section (outside any fence). The
+# section end is the next `## ` heading that is ALSO outside a fence, so a replace
+# never consumes or unbalances a code fence. If more than one REAL `## Links`
+# heading exists, #rewrite raises AmbiguousLinks rather than guess.
+#
+# Frontmatter is NEVER touched: the leading `---`...`---` block is preserved
+# byte-for-byte and only the body is rebuilt.
+module LinksSection
+  module_function
+
+  HEADING = "## Links"
+
+  # A fence delimiter: ``` or ~~~ (any length >= 3), optional leading whitespace,
+  # optional info string (e.g. ```markdown). Mirrors CommonMark fenced-code rules
+  # closely enough for intent bodies.
+  FENCE_RE = /\A\s*(`{3,}|~{3,})/
+
+  # Raised when a body has more than one REAL `## Links` heading outside any fence;
+  # the tool must fail loud rather than guess which one to rewrite.
+  class AmbiguousLinks < StandardError
+    def initialize(count)
+      super("found #{count} real `## Links` headings outside code fences; refusing to guess")
+    end
+  end
+
+  # PURE. Replace (or insert) the REAL `## Links` section in `content` with
+  # `section_text` (the canonical block from LinksProjection.section, which begins
+  # with the `## Links` heading line and ends with a single trailing newline).
+  # Returns the new content, or the original when nothing changed. Raises
+  # AmbiguousLinks when more than one real `## Links` heading exists.
+  def rewrite(content, section_text)
+    return content unless content.is_a?(String)
+
+    fm, body = split_frontmatter(content)
+    new_body = rewrite_body(body, section_text)
+    updated = "#{fm}#{new_body}"
+    updated == content ? content : updated
+  end
+
+  # Split content into [frontmatter_with_delimiters, body]. When there is no
+  # frontmatter block, the frontmatter part is "" and the whole content is the
+  # body. The frontmatter part is preserved byte-for-byte by the caller.
+  def split_frontmatter(content)
+    return ["", content] unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return ["", content] if parts.length < 3
+
+    ["---#{parts[1]}---", parts[2]]
+  end
+
+  # Rewrite ONLY the REAL `## Links` section within the body text.
+  def rewrite_body(body, section_text)
+    bounds = links_bounds(body)
+    if bounds
+      replace_section(body, section_text, bounds)
+    else
+      insert_section(body, section_text)
+    end
+  end
+
+  # PURE. Locate the REAL `## Links` section (fence-aware). Returns
+  # [start_index, end_index] line indices into body.lines, where start_index is the
+  # `## Links` heading line and end_index is the index of the next out-of-fence
+  # `## ` heading (or lines.length at EOF). Returns nil when there is no real
+  # `## Links` heading. Raises AmbiguousLinks when more than one exists.
+  def links_bounds(body)
+    lines = body.to_s.lines
+    starts = real_links_heading_indices(lines)
+    return nil if starts.empty?
+    raise AmbiguousLinks, starts.length if starts.length > 1
+
+    start = starts.first
+    stop = next_out_of_fence_heading(lines, start + 1)
+    [start, stop]
+  end
+
+  # PURE. Indices of every `## Links` heading line that is OUTSIDE any code fence.
+  # Accepts a body String or an Array of lines.
+  def real_links_heading_indices(body_or_lines)
+    lines = body_or_lines.is_a?(Array) ? body_or_lines : body_or_lines.to_s.lines
+    indices = []
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      indices << i if !in_fence && line.rstrip == HEADING
+    end
+    indices
+  end
+
+  # PURE. Index of the first `## ` heading at or after `from` that is OUTSIDE any
+  # code fence. Returns lines.length when none (EOF). Fence state is recomputed
+  # from the top so nested example fences after the real heading are respected.
+  def next_out_of_fence_heading(lines, from)
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      return i if i >= from && !in_fence && line.start_with?("## ")
+    end
+    lines.length
+  end
+
+  # PURE. Given the current fence state, decide whether `line` is a fence delimiter
+  # and return the new state, or nil when the line is not a fence delimiter.
+  # An opening fence records its marker family (` or ~); a closing fence must use a
+  # marker of the SAME family and carry no info string.
+  def fence_open_close(line, in_fence, fence_marker)
+    m = line.match(FENCE_RE)
+    return nil unless m
+
+    marker = m[1]
+    family = marker[0] # "`" or "~"
+    if in_fence
+      # A closing fence uses the same family, length >= the opener, no info string.
+      rest = line.sub(FENCE_RE, "").strip
+      if family == fence_marker && rest.empty?
+        { in_fence: false, marker: nil }
+      else
+        # A delimiter of the OTHER family (or an info-string line) inside a fence is
+        # literal content, not a fence event.
+        nil
+      end
+    else
+      { in_fence: true, marker: family }
+    end
+  end
+
+  # True iff the body has a REAL (out-of-fence) `## Links` heading. Used by callers
+  # to classify regenerate-vs-add without re-deriving fence state.
+  def links_heading?(body)
+    !real_links_heading_indices(body.to_s.lines).empty?
+  end
+
+  # Replace the REAL `## Links` section (the [start, stop] line bounds) with
+  # `section_text`, preserving everything before the heading and after the section
+  # byte-for-byte (including any fenced example that lives BEFORE the real section).
+  def replace_section(body, section_text, bounds)
+    lines = body.lines
+    start, stop = bounds
+    before = lines[0...start].join
+    tail = (lines[stop..] || [])
+
+    # `section_text` already ends with exactly one newline. When there is trailing
+    # content (another section follows), separate the block from it with one blank
+    # line; otherwise the section ends the body.
+    block = tail.empty? ? section_text : "#{section_text}\n"
+    "#{before}#{block}#{tail.join}"
+  end
+
+  # Append a `## Links` section at end-of-body, after the last existing section,
+  # separated by exactly one blank line, preserving the body's trailing newline.
+  def insert_section(body, section_text)
+    trimmed = body.to_s.sub(/\s+\z/, "")
+    if trimmed.empty?
+      # An empty body (no sections) just becomes the section.
+      section_text
+    else
+      "#{trimmed}\n\n#{section_text}"
+    end
+  end
+
+  # PURE. Extract the REAL `## Links` section text (fence-aware), normalized to the
+  # canonical block shape the projection emits: heading line + entry lines + a
+  # single trailing newline. Returns "" when there is no real section. Shared by
+  # the IO shell's audit and the doctor drift check so all three agree on the
+  # location. Raises AmbiguousLinks when more than one real heading exists.
+  def extract_section(body)
+    bounds = links_bounds(body)
+    return "" if bounds.nil?
+
+    start, stop = bounds
+    lines = body.to_s.lines
+    section = lines[(start + 1)...stop].join.sub(/\n+\z/, "\n")
+    section = "" if section.strip.empty?
+    "#{HEADING}\n#{section}"
+  end
+end

package/scripts/lib/lock.rb

@@ -0,0 +1,375 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "socket"
+require "time"
+
+# Lock: the durable single-owner delivery lock (intent 108).
+#
+# One JSON lock file per intent, delivery.lock, living IN the intent dir beside
+# savepoint.md (git-ignored, transient state). Ownership is session-keyed (D1):
+# the file records the owner session, never a pid. Liveness is a lease: the
+# owner's hooks touch the file mtime on tool calls (heartbeat); the lock is
+# stale only when that heartbeat is older than the TTL. The /tmp bridge is a
+# per-session CACHE of this state; on any disagreement the lock file wins (D2).
+#
+# Mutual-exclusion seam (D3): the schema carries a type ("delivery" now,
+# "maintenance" in a chained intent after 93) and acquire refuses while the
+# OTHER type is fresh. Only the seam ships in 108.
+#
+# Pure and dependency-injected: every function takes explicit paths plus ttl:
+# and now:; nothing here reads ENV or globals, and nothing shells out.
+module Lock
+  module_function
+
+  TYPES = %w[delivery maintenance].freeze
+
+  # Lease TTL. Heartbeats fire from the write-path hooks (PostToolUse
+  # gate-check and the lock-gate allow path), so a delivering session
+  # refreshes constantly; 30 minutes tolerates long read-only stretches
+  # without opening a takeover window mid-delivery. Reclaim is explicit
+  # either way (takeover), so the TTL only bounds WHEN takeover is allowed.
+  TTL_SECONDS = 1800
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  def path(intent_dir, type: "delivery")
+    File.join(intent_dir, "#{type}.lock")
+  end
+
+  # Parsed lock Hash, or nil when absent or corrupt (corrupt? distinguishes).
+  def read(intent_dir, type: "delivery")
+    p = path(intent_dir, type: type)
+    return nil unless File.exist?(p)
+    data = JSON.parse(File.read(p)) rescue nil
+    data.is_a?(Hash) ? data : nil
+  end
+
+  def corrupt?(intent_dir, type: "delivery")
+    File.exist?(path(intent_dir, type: type)) && read(intent_dir, type: type).nil?
+  end
+
+  # Lease freshness: the file mtime IS the heartbeat.
+  def fresh?(intent_dir, type: "delivery", ttl: TTL_SECONDS, now: Time.now)
+    p = path(intent_dir, type: type)
+    return false unless File.exist?(p)
+    (now - File.mtime(p)) <= ttl
+  end
+
+  # session is the owner or a registered delegate (D4).
+  def authorized?(data, session)
+    return false unless data.is_a?(Hash)
+    return false if blank?(session)
+    return true if data["owner_session"].to_s == session.to_s
+    Array(data["delegates"]).map(&:to_s).include?(session.to_s)
+  end
+
+  # The one question gates ask: does session hold this intent's lock?
+  # Owner/delegate on an EXISTING lock counts even when stale (a stale lock is
+  # still theirs until an explicit takeover replaces it); freshness only
+  # guards AGAINST other sessions.
+  def holds?(intent_dir, session:, type: "delivery")
+    authorized?(read(intent_dir, type: type), session)
+  end
+
+  # Atomic acquisition (O_EXCL). Returns a [status, data] pair:
+  #   [:acquired, lock]  created fresh
+  #   [:owned, lock]     re-acquire by the current owner (idempotent re-arm)
+  #   [:held, lock]      fresh foreign lock: back off
+  #   [:stale, lock]     expired foreign lock: explicit takeover required
+  #   [:excluded, other] the OTHER lock type is fresh (D3)
+  #   [:corrupt, nil]    unparseable lock file: run repair
+  def acquire(intent_dir, session:, type: "delivery", host: Socket.gethostname,
+              ttl: TTL_SECONDS, now: Time.now)
+    raise ArgumentError, "unknown lock type #{type.inspect}" unless TYPES.include?(type)
+    raise ArgumentError, "lock session must be present" if blank?(session)
+
+    other = (TYPES - [type]).first
+    if fresh?(intent_dir, type: other, ttl: ttl, now: now)
+      return [:excluded, read(intent_dir, type: other)]
+    end
+
+    return [:corrupt, nil] if corrupt?(intent_dir, type: type)
+
+    existing = read(intent_dir, type: type)
+    if existing
+      if existing["owner_session"].to_s == session.to_s
+        data = payload(session: session, type: type, host: host, now: now,
+                       delegates: Array(existing["delegates"]))
+        write(intent_dir, data, type: type)
+        return [:owned, data]
+      end
+      return [:held, existing] if fresh?(intent_dir, type: type, ttl: ttl, now: now)
+      return [:stale, existing]
+    end
+
+    data = payload(session: session, type: type, host: host, now: now)
+    File.open(path(intent_dir, type: type),
+              File::WRONLY | File::CREAT | File::EXCL) do |io|
+      io.write(JSON.pretty_generate(data))
+    end
+    [:acquired, data]
+  rescue Errno::EEXIST
+    [:held, read(intent_dir, type: type)] # lost the O_EXCL race
+  end
+
+  def payload(session:, type:, host:, now:, delegates: [])
+    {
+      "type" => type,
+      "owner_session" => session.to_s,
+      "host" => host,
+      "acquired_at" => now.utc.iso8601,
+      "delegates" => delegates,
+    }
+  end
+
+  # Owner/delegate heartbeat: touch the mtime, never rewrite content.
+  def heartbeat(intent_dir, session:, type: "delivery", now: Time.now)
+    return false unless holds?(intent_dir, session: session, type: type)
+    FileUtils.touch(path(intent_dir, type: type), mtime: now)
+    true
+  end
+
+  # Owner registers a delegate (D4): a session allowed to write under this
+  # lock. Only the OWNER may delegate; delegates cannot re-delegate.
+  def add_delegate(intent_dir, delegate:, session:, type: "delivery")
+    data = read(intent_dir, type: type)
+    return false if blank?(delegate)
+    return false unless data && data["owner_session"].to_s == session.to_s
+    data["delegates"] = (Array(data["delegates"]) + [delegate.to_s]).uniq
+    write(intent_dir, data, type: type)
+    true
+  end
+
+  # Owner releases the lock (disarm / End tail, D6). force: true is the repair
+  # path's escape hatch for corrupt or own-session rebuilds.
+  # Returns :released, :not_owner, or :none.
+  def release(intent_dir, session:, type: "delivery", force: false)
+    p = path(intent_dir, type: type)
+    return :none unless File.exist?(p)
+    data = read(intent_dir, type: type)
+    unless force || (data && data["owner_session"].to_s == session.to_s)
+      return :not_owner
+    end
+    File.delete(p)
+    :released
+  end
+
+  # Explicit takeover of a stale (or corrupt) lock (D2): replace the lock and
+  # append an audit line to savepoint.md. NEVER takes over a fresh foreign
+  # lock; there is no silent reclaim path anywhere else.
+  # Returns [:taken, data], [:fresh, existing], or acquire's error statuses.
+  def takeover(intent_dir, session:, type: "delivery", host: Socket.gethostname,
+               ttl: TTL_SECONDS, now: Time.now)
+    existing = read(intent_dir, type: type)
+    if existing && !authorized?(existing, session) &&
+       fresh?(intent_dir, type: type, ttl: ttl, now: now)
+      return [:fresh, existing]
+    end
+
+    old_owner = existing ? existing["owner_session"] : "corrupt-or-missing"
+    p = path(intent_dir, type: type)
+    File.delete(p) if File.exist?(p)
+    status, data = acquire(intent_dir, session: session, type: type, host: host,
+                           ttl: ttl, now: now)
+    return [status, data] unless status == :acquired
+
+    audit = "#{now.utc.iso8601}  Lock  takeover: #{session} reclaimed #{type} " \
+            "lock from #{old_owner}\n"
+    File.open(File.join(intent_dir, "savepoint.md"), "a") { |io| io.write(audit) }
+    [:taken, data]
+  end
+
+  # Rewrite the lock file in place (owner-side mutations). A content write also
+  # refreshes the mtime, which is correct: every sanctioned mutation is owner
+  # activity.
+  def write(intent_dir, data, type: "delivery")
+    File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
+  end
+end
+
+# Claim: the per-artifact claim-token layer (intent 111, D1/D7). Sits BENEATH
+# the session-keyed delivery lock: a lifecycle-file write must hold BOTH the
+# intent's delivery lock (Lock, unchanged) AND that specific artifact's claim.
+# Neither layer replaces the other.
+#
+# Storage: one small JSON file per artifact, sibling to delivery.lock, under
+# `.claims/<artifact>.claim` INSIDE the intent dir. Scope is strictly
+# per-intent-per-artifact (D4, hard constraint): a claim's on-disk path is
+# always `<intent_dir>/.claims/<artifact>.claim`, so a claim can never affect
+# any artifact but its own, nor any intent but its own. This is what stops a
+# stuck/stale claim from recreating the collision-90 failure mode.
+#
+# Exclusivity is O_EXCL at acquire, not session-equality (see plan.md): a
+# fresh claim is NEVER idempotently re-granted, even to the session that
+# holds it. This is what makes "exactly one writer" mechanical rather than a
+# convention: the second acquire against a live claim is rejected at the
+# filesystem, even when both callers share one CLAUDE_CODE_SESSION_ID.
+#
+# Fail open, always (D3): a stale or corrupt claim never blocks; it yields to
+# the current writer and the condition is surfaced (see Claim.fail_open?,
+# added in a later action, the named contract 112 gates on).
+#
+# Pure and dependency-injected: every function takes explicit paths plus ttl:
+# and now:; nothing here reads ENV or globals, and nothing shells out. Does
+# not touch any Lock function.
+module Claim
+  module_function
+
+  CLAIMS_DIR = ".claims"
+
+  def dir_path(intent_dir)
+    File.join(intent_dir, CLAIMS_DIR)
+  end
+
+  def path(intent_dir, artifact)
+    File.join(dir_path(intent_dir), "#{artifact}.claim")
+  end
+
+  # Parsed claim Hash, or nil when absent or corrupt (corrupt? distinguishes).
+  def read(intent_dir, artifact)
+    p = path(intent_dir, artifact)
+    return nil unless File.exist?(p)
+    data = JSON.parse(File.read(p)) rescue nil
+    data.is_a?(Hash) ? data : nil
+  end
+
+  def corrupt?(intent_dir, artifact)
+    File.exist?(path(intent_dir, artifact)) && read(intent_dir, artifact).nil?
+  end
+
+  # Lease freshness: the file mtime IS the heartbeat (mirrors Lock.fresh?).
+  def fresh?(intent_dir, artifact, ttl: Lock::TTL_SECONDS, now: Time.now)
+    p = path(intent_dir, artifact)
+    return false unless File.exist?(p)
+    (now - File.mtime(p)) <= ttl
+  end
+
+  def payload(session:, artifact:, now:, delegate: nil)
+    {
+      "artifact" => artifact,
+      "owner_session" => session.to_s,
+      "acquired_at" => now.utc.iso8601,
+      "delegate" => delegate,
+    }
+  end
+
+  # Atomic acquisition (O_EXCL). Returns a [status, data] pair:
+  #   [:acquired, claim]  created fresh
+  #   [:held, claim]      fresh claim (own or foreign): never idempotently
+  #                       re-granted; the caller backs off or waits
+  #   [:stale, claim]     expired claim: caller may take over (see plastic-lock)
+  #   [:corrupt, nil]     unparseable claim file: caller may repair
+  def acquire_claim(intent_dir, artifact, session:, delegate: nil,
+                     ttl: Lock::TTL_SECONDS, now: Time.now)
+    raise ArgumentError, "claim session must be present" if Lock.blank?(session)
+    raise ArgumentError, "claim artifact must be present" if Lock.blank?(artifact)
+
+    FileUtils.mkdir_p(dir_path(intent_dir))
+    return [:corrupt, nil] if corrupt?(intent_dir, artifact)
+
+    existing = read(intent_dir, artifact)
+    if existing
+      return [:held, existing] if fresh?(intent_dir, artifact, ttl: ttl, now: now)
+      return [:stale, existing]
+    end
+
+    data = payload(session: session, artifact: artifact, now: now, delegate: delegate)
+    File.open(path(intent_dir, artifact),
+              File::WRONLY | File::CREAT | File::EXCL) do |io|
+      io.write(JSON.pretty_generate(data))
+    end
+    [:acquired, data]
+  rescue Errno::EEXIST
+    [:held, read(intent_dir, artifact)] # lost the O_EXCL race
+  end
+
+  # session is the owner or the registered delegate on this claim. Stale-own
+  # still counts as holding (mirrors Lock.holds?): the claim is theirs until
+  # an explicit takeover replaces it; freshness only guards AGAINST others.
+  def holds_claim?(intent_dir, artifact, session:)
+    data = read(intent_dir, artifact)
+    return false unless data.is_a?(Hash)
+    return false if Lock.blank?(session)
+    data["owner_session"].to_s == session.to_s || data["delegate"].to_s == session.to_s
+  end
+
+  # Owner (or force:) releases the claim. Returns :none, :not_owner, or
+  # :released.
+  def release_claim(intent_dir, artifact, session:, force: false)
+    p = path(intent_dir, artifact)
+    return :none unless File.exist?(p)
+    unless force || holds_claim?(intent_dir, artifact, session: session)
+      return :not_owner
+    end
+    File.delete(p)
+    :released
+  end
+
+  # Owner/delegate heartbeat: touch the mtime, never rewrite content. False
+  # (no-op) when the session does not hold the claim.
+  def heartbeat(intent_dir, artifact, session:, now: Time.now)
+    return false unless holds_claim?(intent_dir, artifact, session: session)
+    FileUtils.touch(path(intent_dir, artifact), mtime: now)
+    true
+  end
+
+  # The named fail-open contract (intent 111 D6; intent 112 gates its Exec on
+  # this test and re-runs it as a regression check on every lock.rb edit it
+  # makes). True iff a claim FILE exists but is unresolvable (stale or
+  # corrupt): the write must PROCEED (yield the claim to the current writer)
+  # and surface the condition; it MUST NEVER block. Absence of a claim is not
+  # fail-open, that is plain dormancy (the gate is not engaged at all).
+  def fail_open?(intent_dir, artifact, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return true if corrupt?(intent_dir, artifact)
+    !!(read(intent_dir, artifact) && !fresh?(intent_dir, artifact, ttl: ttl, now: now))
+  end
+
+  # The data behind `plastic-lock status` (AC5): every live claim under this
+  # intent, with enough to show who holds what since when, and whether it is
+  # still fresh. Returns [] when no artifact has ever been claimed.
+  def claims_status(intent_dir, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return [] unless Dir.exist?(dir_path(intent_dir))
+    Dir.glob(File.join(dir_path(intent_dir), "*.claim")).sort.map do |file|
+      artifact = File.basename(file, ".claim")
+      data = begin
+        parsed = JSON.parse(File.read(file))
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+      {
+        "artifact" => (data && data["artifact"]) || artifact,
+        "owner_session" => data && data["owner_session"],
+        "delegate" => data && data["delegate"],
+        "acquired_at" => data && data["acquired_at"],
+        "fresh" => fresh?(intent_dir, artifact, ttl: ttl, now: now),
+        "corrupt" => data.nil?,
+      }
+    end
+  end
+
+  # Second, independent write gate at the artifact grain (intent 111 D7). Returns a
+  # deny reason String to BLOCK, or nil to ALLOW. Composes UNDER the delivery-lock
+  # gate: only reached after the session already holds the intent's delivery lock.
+  # ENGAGES only when a claim file exists (dormant otherwise, so single-owner flows
+  # and the existing suite stay green, AC7). Fails open on stale/corrupt via
+  # fail_open?, the named contract.
+  def claim_gate_reason(intent_dir, artifact, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return nil if Lock.blank?(artifact)
+    return nil unless File.exist?(path(intent_dir, artifact))   # dormant: no claim
+    return nil if holds_claim?(intent_dir, artifact, session: session)  # you hold it
+    return nil if fail_open?(intent_dir, artifact, ttl: ttl, now: now)  # stale/corrupt: yield
+    data = read(intent_dir, artifact)
+    holder = data && data["owner_session"]
+    since = data && data["acquired_at"]
+    "artifact #{artifact} is claimed by #{holder} since #{since}; another writer holds " \
+      "it. Back off or run /plastic-lock status. If you are a distinct delegate, the " \
+      "owner must register you: plastic-lock delegate --intent-dir #{intent_dir} " \
+      "--session <your-session-id>"
+  end
+end

package/scripts/lib/power_tools.rb

@@ -0,0 +1,75 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "qmd_sync"
+
+# PowerTools — detect-then-degrade harness for Plastic's optional power-tools
+# (intent 66b; demoted to recommendations in intent 108, D8). It owns
+# deterministic detection of each tool and builds a RECOMMENDATION string for
+# whichever tools are present, so the agent is reminded (not obliged) to prefer
+# them: QMD for finding intents, Serena for code navigation.
+#
+# Strictly detect-then-degrade: a tool that is absent contributes nothing, and
+# `mandate` returns nil when no tool is present. Nothing here installs anything.
+#
+# Pure and dependency-injected: every detection runs through an injected callable
+# or keyword probe (PATH scan / `.serena` marker walk), so the whole module is
+# unit-testable with no real binaries, no network, and no global/ENV state.
+module PowerTools
+  module_function
+
+  # True when QMD is present. Reuses QmdSync.detect (PATH probe), injectable.
+  def qmd?(detector: QmdSync.method(:detect))
+    !!detector.call
+  end
+
+  # True when Serena is present: a `.serena` directory exists in cwd or any
+  # ancestor, OR `serena` is resolvable on PATH. Both probes are injectable so
+  # tests do not depend on the host having Serena installed.
+  def serena?(cwd:, path_probe: method(:which_serena), marker_finder: method(:serena_marker?))
+    return true if marker_finder.call(cwd)
+    !!path_probe.call
+  end
+
+  # True when `serena` is an executable on PATH. Mirrors QmdSync.which_qmd.
+  def which_serena
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "serena")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
+  # Walk up from cwd to the filesystem root, returning true if any level holds a
+  # `.serena` directory.
+  def serena_marker?(cwd)
+    dir = File.expand_path(cwd)
+    loop do
+      return true if Dir.exist?(File.join(dir, ".serena"))
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    false
+  end
+
+  # Recommendation text for whichever tools are present, joined by newlines, or
+  # nil when none are. One recommendation line per present tool.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    lines = []
+
+    if qmd?(detector: qmd_detector)
+      lines << "QMD is available: prefer `qmd search` / `qmd query` over the " \
+               "`plastic-*` collections to check for existing or related intents " \
+               "before treating work as new."
+    end
+
+    serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
+    if serena_present
+      lines << "Serena is available: prefer its symbolic tools (find_symbol / " \
+               "get_symbols_overview / find_referencing_symbols) for code navigation."
+    end
+
+    return nil if lines.empty?
+    lines.join("\n")
+  end
+end