@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/scripts/lib/link_suggestions.rb

@@ -0,0 +1,319 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# LinkSuggestions - support links decided by CONTEXT INFLUENCE (intent 91, D7), not
+# by shared files, shared symbols, or a topic-similarity score. A script cannot judge
+# whether one intent's context influenced another (that is reasoning over meaning), so
+# this helper does NOT grade. It only:
+#
+#   - gather:      DISCOVERY. Find candidate intents (via an injected candidate-finder)
+#                  and surface each candidate's `## Intent` + `## Context` as the
+#                  EVIDENCE an agent reads to judge influence.
+#   - record_edge: record a CONFIRMED `sources`/`chain` frontmatter edge AND append a
+#                  dated line to the subject intent file's `## Insights` section
+#                  carrying (utc, target, edge, rating, reason).
+#                  Append-only, frontmatter block only, never a `## Links` line,
+#                  never a delete. A no-op without confirm: true.
+#   - drift:       flag any `## Links` wikilink with no matching frontmatter edge.
+#
+# Two systems frame this:
+#   - System for Brain: links are tiered by context influence (sources = foundational
+#     context that shaped creation; chain = the genuinely delivery-moving context, a
+#     HIGH bar; tags = loose theme grouping, not a link). The influence judgement is
+#     made by an agent, not here.
+#   - System for Work (Convention over Configuration): `## Links` is a derived view of
+#     `sources`/`chain`. This helper never authors a `## Links` line and never deletes.
+#
+# Design rules: all collaborators are injected via the constructor (the store dir, a
+# filesystem reader, AND a candidate-finder). No eval, no ENV / global config seam.
+# Reuses IntentValidator.parse_frontmatter; does NOT touch LinksProjection /
+# LinksSection / project-links / doctor.
+
+require "time"
+require_relative "intent_validator"
+require_relative "insights"
+
+class LinkSuggestions
+  # One discovery candidate plus the evidence an agent reads to judge influence.
+  Candidate = Struct.new(:id, :basename, :label, :intent, :context, keyword_init: true)
+
+  # A drift finding: a `## Links` ref with no matching `sources`/`chain` edge.
+  Drift = Struct.new(:ref, :detail, keyword_init: true)
+
+  RATINGS = %w[high medium low].freeze
+
+  # A minimal default filesystem reader. Injected so tests can substitute an
+  # in-memory map; the production path reads real files. No global state.
+  class DiskReader
+    def directory?(path)
+      File.directory?(path)
+    end
+
+    def children(path)
+      Dir.children(path)
+    end
+
+    def exist?(path)
+      File.exist?(path)
+    end
+
+    def read(path)
+      File.read(path)
+    end
+
+    def write(path, content)
+      File.write(path, content)
+    end
+  end
+
+  # Default candidate-finder: a cheap discovery net (NOT a grade) over the loaded
+  # nodes - candidates that share a non-project tag, share a `sources` parent/family,
+  # or sit at an adjacent id. The CLI may inject a QMD-backed finder instead. Either
+  # way this is DISCOVERY ONLY; influence is judged later by an agent.
+  class FamilyTagFinder
+    def call(subject_id, nodes)
+      subject = nodes[subject_id]
+      return [] unless subject
+
+      nodes.keys.select do |other_id|
+        next false if other_id == subject_id
+
+        other = nodes[other_id]
+        shares_tag?(subject, other) || shares_family?(subject, other) ||
+          adjacent_id?(subject_id, other_id)
+      end
+    end
+
+    private
+
+    def shares_tag?(subject, other)
+      !(link_tags(subject) & link_tags(other)).empty?
+    end
+
+    def link_tags(node)
+      node[:tags].reject { |t| t.start_with?("project-") }
+    end
+
+    def shares_family?(subject, other)
+      return true unless (subject[:sources] & other[:sources]).empty?
+
+      subject[:sources].include?(other[:id]) || other[:sources].include?(subject[:id])
+    end
+
+    # Adjacent ids (discovery hint only): equal non-numeric prefix with integers
+    # differing by 1 (9<->10, 99<->100, 90<->91), or a letter successor at the same
+    # depth (66a<->66b). This is NOT a grade; it only widens the candidate net.
+    def adjacent_id?(a, b)
+      return false if a == b || a.empty? || b.empty?
+
+      ma = a.match(/\A(.*?)(\d+)\z/)
+      mb = b.match(/\A(.*?)(\d+)\z/)
+      return (ma[2].to_i - mb[2].to_i).abs == 1 if ma && mb && ma[1] == mb[1]
+
+      return false unless a.length == b.length
+
+      a[0..-2] == b[0..-2] && a[-1].match?(/[a-z]/) && b[-1].match?(/[a-z]/) &&
+        (a[-1].succ == b[-1] || b[-1].succ == a[-1])
+    end
+  end
+
+  # store_dir - the directory holding `id--slug/` intent folders for ONE store.
+  # reader    - injected filesystem collaborator (DiskReader by default).
+  # finder    - injected candidate-finder responding to #call(subject_id, nodes).
+  def initialize(store_dir:, reader: DiskReader.new, finder: FamilyTagFinder.new)
+    @store_dir = store_dir
+    @reader = reader
+    @finder = finder
+  end
+
+  attr_reader :store_dir, :reader, :finder
+
+  # Load every intent in the store as a node Hash keyed by id:
+  #   { id => { id:, basename:, label:, path:, dir:, sources:[], chain:[], tags:[],
+  #             links_refs:[], intent:, context: } }
+  def load_nodes
+    nodes = {}
+    return nodes unless reader.directory?(store_dir)
+
+    reader.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless reader.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless reader.exist?(md)
+
+      content = reader.read(md)
+      fm = IntentValidator.parse_frontmatter_text(content)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      body = IntentValidator.body_of(content)
+      nodes[id] = {
+        id: id,
+        basename: entry,
+        label: fm["intent"].to_s.strip,
+        path: md,
+        dir: dir,
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        tags: Array(fm["tags"]).map(&:to_s),
+        links_refs: links_refs(body),
+        intent: section_text(body, "Intent"),
+        context: section_text(body, "Context"),
+      }
+    end
+    nodes
+  end
+
+  # DISCOVERY. The candidate intents for `subject_id`, each carrying its Intent +
+  # Context as the evidence an agent reads to judge influence. No grading. Sorted by
+  # natural id order for stable output.
+  def gather(subject_id, nodes: load_nodes)
+    return [] unless nodes.key?(subject_id)
+
+    ids = finder.call(subject_id, nodes)
+    ids.uniq.sort_by { |id| natural_key(id) }.filter_map do |id|
+      node = nodes[id]
+      next unless node
+
+      Candidate.new(id: id, basename: node[:basename], label: node[:label],
+                    intent: node[:intent], context: node[:context])
+    end
+  end
+
+  # Record a single CONFIRMED edge from `subject_id` to `target_id`:
+  #   1. append `target_id` to the subject's frontmatter `sources` or `chain`;
+  #   2. append a dated line to the subject's `## Insights` section capturing
+  #      {utc, target, edge, rating, reason}.
+  # Append-only, frontmatter block only. NEVER writes a `## Links` line, NEVER
+  # deletes. A no-op (returns false) without confirm: true, so a default run mutates
+  # nothing. Returns true when it wrote, false when it declined or the edge existed.
+  def record_edge(subject_id, target_id, edge:, rating: nil, reason: nil,
+                  confirm: false, now: Time.now, nodes: load_nodes)
+    return false unless confirm
+    return false unless %i[sources chain].include?(edge)
+
+    subject = nodes[subject_id]
+    return false unless subject
+    return false if subject[edge].include?(target_id)
+
+    content = reader.read(subject[:path])
+    updated = add_frontmatter_ref(content, edge.to_s, target_id)
+    return false if updated == content
+
+    final = append_link_insight(updated, target_id, edge, rating, reason, now)
+    reader.write(subject[:path], final)
+    true
+  end
+
+  # DRIFT. The `## Links` refs on `subject_id` with no matching `sources`/`chain`
+  # frontmatter edge behind them. Fence-skipping is honored so a `[[id]]` inside an
+  # example code block is not flagged.
+  def drift(subject_id, nodes: load_nodes)
+    subject = nodes[subject_id]
+    return [] unless subject
+
+    edges = (subject[:sources] + subject[:chain]).map { |r| bare_ref(r) }
+    subject[:links_refs].reject { |r| edges.include?(bare_ref(r)) }.map do |ref|
+      Drift.new(ref: ref,
+                detail: "`## Links` references #{ref} with no sources/chain edge behind it")
+    end
+  end
+
+  private
+
+  # Insert one dated link-decision line at the bottom of the subject intent file's
+  # `## Insights` section (96 D3: link rationale lives IN the intent file, never a side
+  # file). Reuses the blessed Insights writer (intent 82) for section insertion; carries
+  # the five fields (utc, target, edge, rating, reason) as a readable line under the 82
+  # exact-timestamp prefix. Returns the augmented content for the single caller write.
+  def append_link_insight(content, target_id, edge, rating, reason, now)
+    prefix = "#{now.utc.iso8601} · Link · link-suggest"
+    text = "#{edge} edge to #{target_id} (rating #{rating || "-"}): #{reason || "-"}"
+    Insights.with_entry(content, "#{prefix} — #{text}")
+  end
+
+  # Natural sort key for ids so 2 sorts before 10 and 14a groups with 14.
+  def natural_key(id)
+    id.scan(/\d+|[a-z]+/).map { |part| part.match?(/\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+  end
+
+  # Strip a `store:` prefix from a ref so a cross-store and same-store form compare.
+  def bare_ref(ref)
+    ref.to_s.include?(":") ? ref.to_s.split(":", 2).last : ref.to_s
+  end
+
+  # Extract bare-id wikilink refs from a body's `## Links` section. Matches
+  # `[[<id>--<slug>|...]]` and `[[<store>:<id>--<slug>|...]]`, yielding the bare id.
+  # Reads only the Links section so example fences elsewhere are not scanned.
+  def links_refs(body)
+    section = section_text(body, "Links")
+    return [] if section.empty?
+
+    section.scan(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/).filter_map do |match|
+      t = bare_ref(match.first.strip)
+      id = t.split("--", 2).first
+      id unless id.nil? || id.empty?
+    end.uniq
+  end
+
+  # The text under the first `## <heading>` heading, up to the next `## ` heading. A
+  # deliberately small reader since we only need the section content. Fence lines are
+  # skipped so a `## Links` (or any heading) inside an example block is ignored.
+  def section_text(body, heading)
+    lines = body.to_s.lines
+    out = []
+    capture = false
+    in_fence = false
+    lines.each do |line|
+      stripped = line.strip
+      if stripped.start_with?("```")
+        in_fence = !in_fence
+        next
+      end
+      next if in_fence
+
+      if stripped == "## #{heading}"
+        capture = true
+        next
+      end
+      break if capture && stripped.start_with?("## ")
+
+      out << line if capture
+    end
+    out.join.strip
+  end
+
+  # Append a ref to a frontmatter array (`sources` or `chain`), creating the key if
+  # absent. Touches ONLY the frontmatter block; the body (including `## Links`) is
+  # left byte-identical. Inline-flow arrays (`key: ["a", "b"]`) are extended in place;
+  # an absent key is inserted before the closing `---`. Never deletes.
+  def add_frontmatter_ref(content, key, ref)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return content if parts.length < 3
+
+    fm = parts[1]
+    line_re = /^#{Regexp.escape(key)}:\s*(.*)$/
+    if fm =~ line_re
+      current = Regexp.last_match(1).strip
+      new_line = extend_flow_array(key, current, ref)
+      fm = fm.sub(line_re, new_line)
+    else
+      fm = fm.rstrip + "\n#{key}: [\"#{ref}\"]\n"
+    end
+    "---#{fm}---#{parts[2]}"
+  end
+
+  def extend_flow_array(key, current, ref)
+    if current.empty? || current == "[]"
+      %(#{key}: ["#{ref}"])
+    elsif current.start_with?("[") && current.end_with?("]")
+      inner = current[1..-2].strip
+      inner.empty? ? %(#{key}: ["#{ref}"]) : %(#{key}: [#{inner}, "#{ref}"])
+    else
+      %(#{key}: ["#{ref}"])
+    end
+  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