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

package/scripts/doctor.rb

@@ -17,6 +17,9 @@ require "digest"
 
 require_relative "lib/qmd_sync"
 require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/links_projection"
+require_relative "lib/links_section"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -473,9 +476,249 @@ class Doctor
       )
     end
 
+    # graph_invariants — cross-intent I1/I3/I4 checks (intent 68). I1/I3/I4 are
+    # defined within a single store's id space (bare ids resolve within the same
+    # store), so build the `nodes` map per scope and run validate_graph per scope.
+    # I2 asymmetry (a relational chain entry with no reciprocal sources) is NEVER
+    # flagged: validate_graph does not compute it.
+    checks.concat(graph_invariant_checks(intent_dirs))
+
+    # cross_store_resolution — RESOLVES (not just shape-checks) every cross-store
+    # `store:id` ref against the FULL store family via the relocation map
+    # (relocation consulted first), closing the shape-only gap i1/i3/i4 leave open.
+    # Resolution always spans all stores even under `--store` scoping; only the
+    # REPORTED findings are filtered to refs originating in the scoped store(s).
+    checks << cross_store_resolution_check(scopes: scopes)
+
+    # graph_links_projection — the `## Links` section of every intent must EQUAL its
+    # canonical I5 frontmatter projection (intent 72), in BOTH set membership AND
+    # ordering (sources first, then chain). Recomputes the projection from each
+    # intent's sources/chain + the on-disk basenames using the SAME resolver the
+    # scripts/project-links tool uses, so the two can never diverge. Resolution
+    # spans all stores; only the REPORTED findings are filtered to the scoped store.
+    checks << links_projection_check(scopes: scopes)
+
+    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
+  # ordering drift), or whose projection raises UnresolvedRef. `scopes` (nil = full
+  # run) filters only the REPORTED findings by origin scope.
+  def links_projection_check(scopes: nil)
+    all_dirs = all_intent_dirs
+
+    store_index = Hash.new { |h, k| h[k] = [] }
+    node_index = Hash.new { |h, k| h[k] = {} }
+    intents = [] # { scope:, id:, sources:, chain:, path: }
+
+    all_dirs.each do |d|
+      md = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md)
+
+      fm = parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      store_index[d[:scope]] << id
+      node_index[d[:scope]][id] = { basename: d[:name], label: fm["intent"].to_s.strip }
+      intents << {
+        scope: d[:scope], id: id, path: md,
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(cross_store_index_texts)
+
+    findings = []
+    intents.each do |node|
+      next if scopes && !scopes.include?(node[:scope])
+
+      resolve = ->(ref) do
+        LinksProjection.resolve_ref_projection(
+          ref, referer_store: node[:scope],
+               relocation_map: relocation_map, store_index: store_index, node_index: node_index
+        )
+      end
+
+      begin
+        expected = LinksProjection.section(sources: node[:sources], chain: node[:chain], resolve: resolve)
+        actual = actual_links_section(node[:path])
+      rescue LinksProjection::UnresolvedRef => e
+        findings << "#{node[:id]} ## Links projection failed: #{e.message}"
+        next
+      rescue LinksSection::AmbiguousLinks => e
+        findings << "#{node[:id]} ## Links ambiguous: #{e.message}"
+        next
+      end
+
+      next if actual == expected
+
+      findings << "#{node[:id]} ## Links does not match its frontmatter projection (membership/ordering drift)"
+    end
+
+    graph_finding_check(
+      "graph_links_projection", findings,
+      "Every intent's ## Links equals its frontmatter projection (membership and ordering)",
+      "Run scripts/project-links to regenerate the canonical ## Links sections"
+    )
+  end
+
+  # Extract a file's ACTUAL REAL `## Links` section text (FENCE-AWARE), normalized
+  # to the canonical block shape the projection emits. Delegates to the shared
+  # LinksSection.extract_section so the doctor check and the project-links tool
+  # agree on the section location and never match a `## Links` heading inside an
+  # example code fence. Returns "" when the section is absent (which differs from
+  # any real projection, so a missing section is a finding).
+  def actual_links_section(path)
+    LinksSection.extract_section(IntentValidator.body_of(File.read(path)))
+  end
+
+  # Build the relocation map + cross-store store_index from ALL stores, then for
+  # every intent's cross-store `sources`/`chain` ref resolve it and flag:
+  #   - DEAD: the target resolves nowhere
+  #   - RELOCATED-STALE: the ref points at an old location the relocation log has
+  #     moved (the resolved location differs from the literal ref), e.g. the
+  #     `global:24` id-reuse hazard that direct resolution would silently accept.
+  # `scopes` (nil = full run) filters only the REPORTED findings by origin scope.
+  def cross_store_resolution_check(scopes: nil)
+    all_dirs = all_intent_dirs
+
+    # Per-scope node maps + store_index over the WHOLE family.
+    nodes_by_scope = Hash.new { |h, k| h[k] = {} }
+    store_index = Hash.new { |h, k| h[k] = [] }
+    all_dirs.each do |d|
+      md = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md)
+
+      fm = parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      store_index[d[:scope]] << id
+      nodes_by_scope[d[:scope]][id] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(cross_store_index_texts)
+
+    findings = []
+    nodes_by_scope.each do |scope, nodes|
+      next if scopes && !scopes.include?(scope)
+
+      nodes.each do |id, edges|
+        %i[sources chain].each do |field|
+          edges[field].each do |ref|
+            next unless ref.include?(":") # only cross-store refs are resolved here
+
+            res = GraphRebuild.resolve_ref(ref, referer_store: scope,
+                                                relocation_map: relocation_map,
+                                                store_index: store_index)
+            case res[:status]
+            when :dead
+              findings << "#{id}.#{field} cross-store ref #{ref} resolves to no intent (dead)"
+            when :same_store
+              findings << "#{id}.#{field} cross-store ref #{ref} is relocated-stale (now same-store #{res[:id]})"
+            when :cross_store
+              findings << "#{id}.#{field} cross-store ref #{ref} is relocated-stale (now #{res[:ref]})" if res[:ref] != ref
+            end
+          end
+        end
+      end
+    end
+
+    graph_finding_check(
+      "graph_cross_store_resolution", findings,
+      "Every cross-store sources/chain ref resolves to a live, current intent",
+      "Run scripts/rebuild-graph to repoint/collapse/drop stale cross-store refs"
+    )
+  end
+
+  # { store_key => INDEX.md text } for every store (global + all projects), for the
+  # relocation-map builder. Reads INDEX.md one level above each store dir.
+  def cross_store_index_texts
+    texts = {}
+    global_index = File.join(plastic_home, "INDEX.md")
+    texts["global"] = File.read(global_index) if File.exist?(global_index)
+
+    projects_root = File.join(plastic_home, "projects")
+    if File.directory?(projects_root)
+      Dir.children(projects_root).each do |project|
+        idx = File.join(projects_root, project, "INDEX.md")
+        texts["project:#{project}"] = File.read(idx) if File.exist?(idx)
+      end
+    end
+    texts
+  end
+
+  # Build a per-scope `nodes` map and surface IntentValidator.validate_graph
+  # findings as warn-level checks. Scope-aware (the caller already filtered
+  # `intent_dirs` by scope), so a `global` id is not falsely flagged as a dangler
+  # when only a `project:` store is loaded, and vice versa.
+  def graph_invariant_checks(intent_dirs)
+    nodes_by_scope = Hash.new { |h, k| h[k] = {} }
+    intent_dirs.each do |d|
+      md_path = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md_path)
+
+      fm = parse_frontmatter(md_path)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes_by_scope[d[:scope]][fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    i1 = []
+    i3 = []
+    i4 = []
+    nodes_by_scope.each_value do |nodes|
+      findings = IntentValidator.validate_graph(nodes)
+      i1.concat(findings[:i1])
+      i3.concat(findings[:i3])
+      i4.concat(findings[:i4])
+    end
+
+    checks = []
+    checks << graph_finding_check(
+      "graph_i1_reciprocity", i1,
+      "Every sources edge has its reciprocal chain entry (I1)",
+      "Run new-intent / the rebuild so each source intent's chain backlinks the child"
+    )
+    checks << graph_finding_check(
+      "graph_i3_disjoint", i3,
+      "No intent lists the same id in both sources and chain (I3)",
+      "Remove the overlapping id from either sources or chain"
+    )
+    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"
+    )
     checks
   end
 
+  # One graph check: pass when `findings` is empty, otherwise warn (never fail, so
+  # an existing store does not turn red on a graph finding). I1/I4 are auto-fixable.
+  def graph_finding_check(name, findings, pass_message, fix_hint)
+    if findings.empty?
+      check(category: "conventions", name: name, status: "pass", message: pass_message)
+    else
+      check(
+        category: "conventions", name: name, status: "warn",
+        message: "#{findings.size} #{name} violation(s)",
+        details: findings,
+        fixable: name != "graph_i3_disjoint",
+        fix_hint: fix_hint
+      )
+    end
+  end
+
   # --- Check category 3: Agent registration ---
 
   def check_agent_registration(agent_key)

package/scripts/lib/bridge.rb

@@ -18,13 +18,15 @@ module Bridge
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
-  # Stale-bridge purge window (intent 67). The bridge file is ephemeral
-  # live-session gate state, NOT a continuation source: an intent is resumed from
-  # its savepoint.md ledger, never from a /tmp bridge. So any bridge older than
-  # this window is dead weight and safe to purge, regardless of arm state. No
-  # real session stays live for two days, so a 48h cutoff never removes a bridge
-  # an active run depends on.
-  PURGE_AGE_SECONDS = 48 * 3600   # 48 hours
+  # Bridge cleanup is terminal-state, not age-based (intent 80). A bridge is dead
+  # weight ONLY once its intent is terminal (no longer in its store's INDEX.md
+  # `## Active` block); such bridges are purged. An Active intent's bridge is kept
+  # unconditionally, because while the intent is live the bridge is still load-
+  # bearing: it is the continuation signal (a parked or interrupted run resumes
+  # from it) and the anti-collision lock (it keys the per-session statusline so
+  # parallel sessions do not overwrite each other). An age window was the wrong
+  # axis: it left dead bridges resident for ~2 days AND could reap bridges of
+  # interrupted-but-still-active intents, which are exactly the ones to preserve.
 
   def self.intent_file(intent_dir)
     dir_name = File.basename(intent_dir)
@@ -58,11 +60,20 @@ module Bridge
   end
 
   # Resolve a bridge session: first non-empty of explicit, CLAUDE_SESSION_ID,
-  # then a derived key. Never returns nil/empty. Whitespace-only counts as empty.
+  # CLAUDE_CODE_SESSION_ID, then a derived key. Never returns nil/empty.
+  # Whitespace-only counts as empty.
+  #
+  # The CLAUDE_CODE_SESSION_ID fallback (intent 79) is additive: it only changes
+  # behavior when CLAUDE_SESSION_ID is blank but CLAUDE_CODE_SESSION_ID is set —
+  # the bg/headless case where the real session id lives in CLAUDE_CODE_SESSION_ID.
+  # Keying by the real id (instead of a derived hash) lets the statusline, which
+  # receives that same id on stdin, find the bridge by direct filename lookup.
   def self.resolve_session(explicit, intent_id:, store:)
     return explicit.to_s.strip unless blank?(explicit)
     env = ENV["CLAUDE_SESSION_ID"]
     return env.to_s.strip unless blank?(env)
+    code_env = ENV["CLAUDE_CODE_SESSION_ID"]
+    return code_env.to_s.strip unless blank?(code_env)
     derive_key(store, intent_id)
   end
 
@@ -122,25 +133,62 @@ module Bridge
     pool.max_by { |c| c[:mtime] }&.fetch(:data)
   end
 
-  # --- Stale-bridge purge (intent 67) ---------------------------------------
-  #
-  # Remove stale tmp/plastic-*.json bridge files so discover_bridge's per-fire
-  # scan stays bounded. Best-effort and non-raising: returns the array of removed
-  # paths. Continuation does not depend on these files (an intent resumes from its
-  # savepoint.md ledger), so the only safety rule is age: a bridge older than
-  # max_age_seconds is purged regardless of arm state, while anything newer is kept
-  # (it may be a live run). The current session's own bridge is never purged
+  # --- Terminal-state bridge purge (intent 80) -------------------------------
+
+  # True iff the intent is Active in its store's INDEX.md. An INDEX.md lives at
+  # the PARENT of the store/ dir the bridge records, so we resolve it from the
+  # bridge's intent.store. Non-raising: any failure (missing/unreadable INDEX,
+  # bad arg) returns false, which means "not active" so the caller treats the
+  # bridge as purgeable. `index_active_ids` is a pure-data test seam: when an
+  # Array of id strings is supplied, membership is checked against it directly
+  # with no file read.
+  def self.intent_active?(intent_id, store:, index_active_ids: nil)
+    target = intent_id.to_s
+    return index_active_ids.include?(target) if index_active_ids.is_a?(Array)
+
+    index = File.join(File.dirname(store.to_s), "INDEX.md")
+    return false unless File.exist?(index)
+
+    in_active = false
+    File.foreach(index) do |line|
+      stripped = line.chomp
+      if stripped == "## Active"
+        in_active = true
+        next
+      end
+      next unless in_active
+      break if stripped.start_with?("## ") # next section ends the Active block
+      m = stripped.match(/^- \[(\S+) +—/)
+      return true if m && m[1] == target
+    end
+    false
+  rescue StandardError
+    false
+  end
+
+  # Remove tmp/plastic-*.json bridge files whose intent is terminal, so
+  # discover_bridge's per-fire scan stays bounded. Best-effort and non-raising:
+  # returns the array of removed paths. A bridge is purged when it cannot be
+  # parsed, has no intent.id, has no intent.store, or its intent is not Active in
+  # its store's INDEX.md. An Active intent's bridge is kept (continuation signal +
+  # anti-collision lock), and the current session's own bridge is never purged
   # (preserves the disarm_auto contract that it stays readable). Wired into
   # arm_auto and disarm_auto so both manual and auto delivery keep the temp dir
-  # clean.
-  def self.purge_stale_bridges(session:, now: Time.now, max_age_seconds: PURGE_AGE_SECONDS,
-                               tmp: tmp_dir)
+  # clean at deterministic work boundaries.
+  def self.purge_done_bridges(session:, tmp: tmp_dir)
     current = path(session, tmp: tmp)
     removed = []
     Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
       next if f == current
       begin
-        next if (now - File.mtime(f)) < max_age_seconds
+        data = JSON.parse(File.read(f)) rescue nil
+        keep = false
+        if data
+          id = data.dig("intent", "id")
+          store = data.dig("intent", "store")
+          keep = !blank?(id) && !blank?(store) && intent_active?(id, store: store)
+        end
+        next if keep
         File.delete(f)
         removed << f
       rescue Errno::ENOENT
@@ -152,7 +200,7 @@ module Bridge
     end
     removed
   rescue => e
-    $stderr.puts "plastic: purge_stale_bridges failed: #{e.message}"
+    $stderr.puts "plastic: purge_done_bridges failed: #{e.message}"
     removed || []
   end
 
@@ -386,13 +434,13 @@ module Bridge
   # (mid-session intent creation). Re-derives intent state, then sets build.auto.
   def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
     key = resolve_session(session, intent_id: intent_id, store: store)
-    if blank?(session) && blank?(ENV["CLAUDE_SESSION_ID"])
+    if blank?(session) && blank?(ENV["CLAUDE_SESSION_ID"]) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
       $stderr.puts "plastic: no session id available; arming auto with derived bridge key #{key}"
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
     data["build"]["auto"] = true
     write(key, data)
-    purge_stale_bridges(session: key)
+    purge_done_bridges(session: key)
     data
   end
 
@@ -403,7 +451,7 @@ module Bridge
     data["build"] ||= {}
     data["build"]["auto"] = false
     write(session, data)
-    purge_stale_bridges(session: session)
+    purge_done_bridges(session: session)
     data
   end
 

package/scripts/lib/frontmatter_writer.rb

@@ -0,0 +1,130 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# FrontmatterWriter — pure, minimal, style-preserving rewrite of the `sources:`
+# and `chain:` arrays in an intent file's content string (intent 49).
+#
+# It rewrites ONLY those two arrays and leaves every other frontmatter line and
+# the entire body byte-identical. It preserves each array's existing serialization
+# style independently:
+#   - flow style: `sources: ["40", "1a"]`  (or `[]`)
+#   - block style: a `sources:` line followed by `  - '1a'` item lines
+# When the desired array equals the file's current value (same ids, same order),
+# the content is returned UNCHANGED so a re-run produces no diff (idempotency).
+#
+# Pure: no file IO, no eval, no global/ENV state. The IO shell reads/writes files.
+module FrontmatterWriter
+  module_function
+
+  # Rewrite `sources:`/`chain:` in `content`. `sources`/`chain` are the desired
+  # final arrays of id strings. Returns the new content (or the original when
+  # nothing changed). Only operates within the leading `---`...`---` frontmatter
+  # block; never touches the body.
+  def rewrite_arrays(content, sources:, chain:)
+    return content unless content.is_a?(String) && content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return content if parts.length < 3
+
+    fm = parts[1]
+    body = parts[2]
+
+    fm = rewrite_one(fm, "sources", sources)
+    fm = rewrite_one(fm, "chain", chain)
+
+    "---#{fm}---#{body}"
+  end
+
+  # Rewrite a single `key:` array within the frontmatter text `fm`, preserving the
+  # key's existing flow-vs-block style. No-op when the key is absent or unchanged.
+  def rewrite_one(fm, key, desired)
+    lines = fm.lines
+    idx = lines.index { |l| l.match?(/\A#{Regexp.escape(key)}:\s/) || l.match?(/\A#{Regexp.escape(key)}:\s*\z/) }
+    return fm if idx.nil?
+
+    header = lines[idx]
+    if block_style?(lines, idx)
+      rewrite_block(lines, idx, key, desired)
+    else
+      rewrite_flow(lines, idx, header, key, desired)
+    end
+  end
+
+  # The key is block style when its own line carries no inline value and the next
+  # non-blank line is a `-` list item.
+  def block_style?(lines, idx)
+    header = lines[idx]
+    inline = header.sub(/\A[^:]+:/, "").strip
+    return false unless inline.empty?
+
+    nxt = lines[idx + 1]
+    !nxt.nil? && nxt.match?(/\A\s*-\s/)
+  end
+
+  # Flow style: replace the inline array on the header line, preserving indentation
+  # and any trailing newline. No-op when the current ids already match `desired`.
+  def rewrite_flow(lines, idx, header, key, desired)
+    current = parse_flow(header)
+    return lines.join if current == desired
+
+    newline = header.end_with?("\n") ? "\n" : ""
+    lines[idx] = "#{key}: #{render_flow(desired)}#{newline}"
+    lines.join
+  end
+
+  # Parse the inline flow array from a `key: [ ... ]` header line.
+  def parse_flow(header)
+    inline = header.sub(/\A[^:]+:/, "").strip
+    return [] if inline.empty? || inline == "[]"
+
+    inline = inline.sub(/\A\[/, "").sub(/\]\z/, "")
+    inline.split(",").map { |t| t.strip.gsub(/\A['"]|['"]\z/, "") }.reject(&:empty?)
+  end
+
+  def render_flow(ids)
+    return "[]" if ids.empty?
+
+    "[#{ids.map { |i| "\"#{i}\"" }.join(", ")}]"
+  end
+
+  # Block style: replace the contiguous `-` item lines following the header. No-op
+  # when the current ids already match `desired`. Preserves the item indentation
+  # and quoting style sampled from the existing first item.
+  def rewrite_block(lines, idx, key, desired)
+    last = idx
+    item_lines = []
+    (idx + 1).upto(lines.length - 1) do |i|
+      break unless lines[i].match?(/\A\s*-\s/)
+
+      item_lines << lines[i]
+      last = i
+    end
+
+    current = item_lines.map { |l| l.sub(/\A\s*-\s*/, "").strip.gsub(/\A['"]|['"]\z/, "") }
+    return lines.join if current == desired
+
+    indent, quote = block_item_shape(item_lines.first)
+    rendered = desired.map { |id| "#{indent}- #{quote}#{id}#{quote}\n" }
+
+    # When desired is empty, collapse the block to an inline `key: []` to keep YAML
+    # valid (a bare `key:` with no items parses as nil, not an empty array).
+    rendered = ["#{key}: []\n"] if desired.empty? && rendered.empty?
+
+    if desired.empty?
+      new_lines = lines[0...idx] + rendered + lines[(last + 1)..]
+    else
+      new_lines = lines[0...idx] + [lines[idx]] + rendered + lines[(last + 1)..]
+    end
+    new_lines.join
+  end
+
+  # Sample indentation and quote char from an existing block item line.
+  def block_item_shape(sample)
+    return ["", "'"] if sample.nil?
+
+    indent = sample[/\A\s*/].to_s
+    value = sample.sub(/\A\s*-\s*/, "").strip
+    quote = value.start_with?('"') ? '"' : "'"
+    [indent, quote]
+  end
+end