@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.10

package/scripts/lib/intent_validator.rb

@@ -0,0 +1,235 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "time"
+
+# IntentValidator — the single source of truth for "is an intent born complete?"
+# (intent 60).
+#
+# An intent is born complete when its frontmatter carries every required field
+# and its `sources` and `chain` are well-formed arrays of Folgezettel id references
+# (bare ids like `1a2`, or cross-store refs like `global:1a2`; integer ids are coerced).
+# This module is the only definition of that contract; the `validate-intent` CLI,
+# the doctor diagnostics, and the creating-intent skill all consult it so the
+# definition never drifts across copies.
+#
+# Pure and dependency-injected: `validate` accepts an injectable `plastic_home`
+# for house-style parity, parses with a rescue-to-safe-default reader, uses no
+# `eval`, and performs no file writes and no global-constant injection.
+module IntentValidator
+  module_function
+
+  # Must match Doctor::REQUIRED_FRONTMATTER_FIELDS (scripts/doctor.rb).
+  REQUIRED_FIELDS = %w[id intent sources chain created author tags].freeze
+
+  # Fields whose value must be a well-formed array of valid id strings.
+  ARRAY_ID_FIELDS = %w[sources chain].freeze
+
+  # Sanctioned top-level intent sections, in order (intent 60b). The only
+  # sanctioned `###` subsection is `### Decisions`, which is OPTIONAL (added after
+  # brainstorming) and therefore never flagged as missing. This is the single
+  # definition shared by the create gate, the validate-intent CLI, and doctor.
+  SANCTIONED_SECTIONS = ["## Intent", "## Context", "## Outcome", "## Insights", "## Links"].freeze
+
+  # Folgezettel id form: digits then an optional lowercase-letter/digit suffix
+  # (for example "14", "14a", "4a1"). Mirrors scripts/folgezettel-id.
+  ID_PATTERN = /\A([a-z0-9-]+:)?\d+[a-z0-9]*\z/
+
+  # True iff `value` is a String matching the Folgezettel id form.
+  def valid_id?(value)
+    value.to_s.match?(ID_PATTERN)
+  end
+
+  # Read a file's YAML frontmatter, returning the parsed Hash (or {} when the
+  # frontmatter block is empty), or nil when there is no parseable frontmatter.
+  # A copy of Doctor#parse_frontmatter so `created:` dates do not crash.
+  def parse_frontmatter(path)
+    return nil unless File.exist?(path)
+
+    parse_frontmatter_text(File.read(path))
+  rescue StandardError
+    nil
+  end
+
+  # PURE: parse YAML frontmatter from a content STRING (no file IO). Returns the
+  # parsed Hash, {} for an empty block, or nil when there is no parseable block.
+  def parse_frontmatter_text(content)
+    return nil unless content.is_a?(String) && content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return nil if parts.length < 3
+
+    YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+  rescue StandardError
+    nil
+  end
+
+  # PURE: strip the leading YAML frontmatter block from a content STRING,
+  # returning the body text (everything after the closing `---`). When there is
+  # no frontmatter block, the whole content is the body.
+  def body_of(content)
+    return "" unless content.is_a?(String)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    parts.length < 3 ? content : parts[2]
+  end
+
+  # PURE: given the intent file body text, return sanctioned-section findings.
+  # Flags any unknown top-level `## ` heading and any missing sanctioned section.
+  # Ignores `### ` subsections entirely (Decisions is optional and lives under
+  # Context). Returns { ok:, missing: [section names], unknown: [heading strings] }.
+  def validate_sections(body)
+    headings = body.to_s.lines.filter_map do |l|
+      s = l.strip
+      s if s.start_with?("## ") && !s.start_with?("### ")
+    end
+    present = headings & SANCTIONED_SECTIONS
+    missing = SANCTIONED_SECTIONS - present
+    unknown = headings - SANCTIONED_SECTIONS
+    { ok: missing.empty? && unknown.empty?, missing: missing, unknown: unknown }
+  end
+
+  # PURE: given a parsed frontmatter Hash (or nil), return
+  # { ok: Boolean, missing: [field names], errors: [human strings] }.
+  def validate_frontmatter(fm)
+    unless fm.is_a?(Hash)
+      return { ok: false, missing: REQUIRED_FIELDS.dup, errors: ["no frontmatter found"] }
+    end
+
+    missing = REQUIRED_FIELDS.reject { |f| fm.key?(f) }
+    errors = missing.map { |f| "missing required field: #{f}" }
+
+    ARRAY_ID_FIELDS.each do |key|
+      next unless fm.key?(key)
+
+      value = fm[key]
+      unless value.is_a?(Array)
+        errors << "#{key} must be an array"
+        next
+      end
+
+      value.each do |element|
+        errors << "#{key} has invalid id: #{element.inspect}" unless valid_id?(element)
+      end
+    end
+
+    { ok: missing.empty? && errors.empty?, missing: missing, errors: errors }
+  end
+
+  # PURE: combine the frontmatter result with section-structure findings for a
+  # content STRING. Returns the frontmatter result hash extended with
+  # :section_missing, :section_unknown, and folded section errors; :ok is the AND
+  # of frontmatter and sections. Lets the create gate validate proposed content
+  # (no file on disk) with the same definition as the CLI and doctor.
+  def validate_content(content)
+    fm_result = validate_frontmatter(parse_frontmatter_text(content))
+    sections = validate_sections(body_of(content))
+    merge_sections(fm_result, sections)
+  end
+
+  # Fold section findings into a frontmatter result hash (shared by validate and
+  # validate_content). Does not mutate the input.
+  def merge_sections(fm_result, sections)
+    errors = fm_result[:errors].dup
+    sections[:unknown].each { |h| errors << "unknown section: #{h}" }
+    sections[:missing].each { |s| errors << "missing required section: #{s}" }
+    {
+      ok: fm_result[:ok] && sections[:ok],
+      missing: fm_result[:missing],
+      errors: errors,
+      section_missing: sections[:missing],
+      section_unknown: sections[:unknown],
+    }
+  end
+
+  # Resolve an intent directory's primary md file and validate its frontmatter
+  # AND its sanctioned section structure. `plastic_home` is accepted for
+  # house-style parity (injectable) even though validation reads the dir directly.
+  def validate(intent_dir, plastic_home: File.join(Dir.home, ".plastic"))
+    md_path = File.join(intent_dir, "#{File.basename(intent_dir)}.md")
+    content = File.exist?(md_path) ? File.read(md_path) : nil
+    validate_content(content)
+  end
+
+  # PURE: cross-intent graph-shape invariants (intent 68). These need visibility
+  # over the whole intent set, so they live apart from the single-file born-complete
+  # helpers above (which must not drift). No file IO: the caller builds `nodes`.
+  #
+  # `nodes` is a Hash { id(String) => { sources: [ids], chain: [ids] } } for every
+  # intent in ONE store's id space. Returns { i1: [...], i3: [...], i4: [...] },
+  # each an array of human-readable finding strings.
+  #
+  # I2 (no false symmetry) is INTENTIONALLY not computed: a relational `chain` entry
+  # with no reciprocal `sources` is valid and must never be flagged.
+  def validate_graph(nodes)
+    nodes = normalize_nodes(nodes)
+    { i1: graph_i1(nodes), i3: graph_i3(nodes), i4: graph_i4(nodes) }
+  end
+
+  # Coerce node arrays to deduped String id lists; tolerate missing keys.
+  def normalize_nodes(nodes)
+    return {} unless nodes.is_a?(Hash)
+
+    nodes.each_with_object({}) do |(id, edges), acc|
+      edges = {} unless edges.is_a?(Hash)
+      acc[id.to_s] = {
+        sources: Array(edges[:sources] || edges["sources"]).map(&:to_s).uniq,
+        chain: Array(edges[:chain] || edges["chain"]).map(&:to_s).uniq,
+      }
+    end
+  end
+
+  # An id is a cross-store reference (out of this store's scope) when it carries a
+  # `<store>:` prefix, mirroring how `valid_id?` accepts the prefix. Such refs are
+  # resolved outside this node set, so they are never danglers here.
+  def cross_store_ref?(id)
+    id.to_s.include?(":")
+  end
+
+  # I1 (formative reciprocity): for every B and every `s` in B.sources that resolves
+  # in this store, B must appear in s.chain. A `s` that does not resolve is an I4
+  # dangler, not an I1 violation, so it is skipped here.
+  def graph_i1(nodes)
+    findings = []
+    nodes.each do |b_id, edges|
+      edges[:sources].each do |s|
+        next if cross_store_ref?(s)
+        next unless nodes.key?(s)
+
+        findings << "#{b_id}.sources lists #{s} but #{s}.chain is missing #{b_id}" unless nodes[s][:chain].include?(b_id)
+      end
+    end
+    findings
+  end
+
+  # I3 (per-node disjoint): X.sources and X.chain must not overlap.
+  def graph_i3(nodes)
+    findings = []
+    nodes.each do |x_id, edges|
+      (edges[:sources] & edges[:chain]).each do |overlap|
+        findings << "#{x_id} lists #{overlap} in BOTH sources and chain"
+      end
+    end
+    findings
+  end
+
+  # I4 (no danglers): every bare (same-store) id in any sources/chain must resolve
+  # to a node. Cross-store `<store>:<id>` refs resolve elsewhere and are not flagged.
+  def graph_i4(nodes)
+    findings = []
+    nodes.each do |id, edges|
+      %i[sources chain].each do |field|
+        edges[field].each do |ref|
+          next if cross_store_ref?(ref)
+          next if nodes.key?(ref)
+
+          findings << "#{id}.#{field} references #{ref} which resolves to no intent"
+        end
+      end
+    end
+    findings
+  end
+end

package/scripts/lib/links_projection.rb

@@ -0,0 +1,160 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# LinksProjection — pure logic that projects one intent's sources/chain graph into
+# the canonical I5 `## Links` section text (intent 72). Mirrors the pure-module
+# style of GraphRebuild: module-function helpers, no file IO, no eval, no
+# ENV/global state. The IO shell (scripts/project-links) and doctor build the
+# cross-store resolver and feed it here.
+#
+# Pinned canonical projection (the human's format call):
+#   1. ORDERING (load-bearing): ALL sources first, in frontmatter order, THEN all
+#      chain, in frontmatter order. Sources can NEVER appear at the end. No group
+#      headings, no per-entry source/chain tags: the ordering carries the meaning.
+#   2. ENTRY SHAPE: one list item `- [[<id>--<slug>|<target's full intent: text>]]`,
+#      where the wikilink TARGET is the target intent's resolvable `id--slug` file
+#      basename (so it clicks through in Obsidian) and the LABEL is the target's
+#      full `intent:` frontmatter text, whitespace-trimmed.
+#   3. CROSS-STORE: a cross-store target renders
+#      `- [[<store>:<id>--<slug>|<target's full intent: text>]]`.
+#   4. RESOLVER MISS: a ref that resolves to no intent raises UnresolvedRef. No
+#      bare-id, slug-less, or guessed link is ever emitted.
+#   5. EMPTY-STATE: empty sources AND chain yields the heading plus a single
+#      explanatory comment.
+module LinksProjection
+  module_function
+
+  HEADING = "## Links"
+  EMPTY_COMMENT = "<!-- No sources or chain; this intent has no graph edges to project. -->"
+
+  # Raised when a sources/chain ref resolves to no intent. Carries the offending
+  # ref so the IO shell can report it per-intent and skip the write.
+  class UnresolvedRef < StandardError
+    attr_reader :ref
+
+    def initialize(ref)
+      @ref = ref
+      super("unresolved sources/chain ref: #{ref.inspect}")
+    end
+  end
+
+  # PURE. Build the canonical `## Links` section text for one intent.
+  #
+  #   sources — array of id / `store:id` ref strings, in frontmatter order
+  #   chain   — array of id / `store:id` ref strings, in frontmatter order
+  #   resolve — a callable (`->(ref) { ... }`) mapping ONE ref to a Hash like
+  #             { target: "<id>--<slug>",            label: "<full intent: text>" } or
+  #             { target: "<store>:<id>--<slug>",    label: "<full intent: text>" }.
+  #             Returning nil (or a Hash lacking :target) signals no target and
+  #             raises UnresolvedRef. Keeping resolution injected keeps this module
+  #             pure and hermetically testable with in-memory maps.
+  #
+  # Returns the full section text: the `## Links` heading line, one entry line per
+  # ref (sources first, then chain), and a single trailing newline. The empty case
+  # returns the heading + the empty-state comment + a single trailing newline.
+  def section(sources:, chain:, resolve:)
+    src = Array(sources).map(&:to_s)
+    chn = Array(chain).map(&:to_s)
+
+    # Resolve EVERY ref to its { target:, label: } first, then dedup by the RESOLVED
+    # target (not the raw ref string). This is load-bearing: the same intent may be
+    # referenced as a bare id in one group and as `store:id` in another (or via a
+    # relocation), which dedups identically only AFTER resolution. Sources win
+    # (formative edge), and frontmatter order is preserved within each group.
+    seen = {}
+    rendered = []
+    src.each { |ref| add_entry(ref, resolve, seen, rendered) }
+    chn.each { |ref| add_entry(ref, resolve, seen, rendered) }
+
+    return empty_section if rendered.empty?
+
+    (["#{HEADING}\n"] + rendered.map { |line| "#{line}\n" }).join
+  end
+
+  # PURE. The canonical empty-state section: heading + the single comment line.
+  def empty_section
+    "#{HEADING}\n#{EMPTY_COMMENT}\n"
+  end
+
+  # Resolve `ref`, render its entry, and append it to `rendered` UNLESS its resolved
+  # target was already emitted (dedup by resolved target, first-seen wins so sources
+  # precede chain). Mutates `seen` and `rendered`. Raises UnresolvedRef on a miss.
+  def add_entry(ref, resolve, seen, rendered)
+    target, label = resolve_entry(ref, resolve)
+    return if seen.key?(target)
+
+    seen[target] = true
+    rendered << "- [[#{target}|#{label}]]"
+  end
+
+  # PURE. Resolve one ref to [target, label]. Raises UnresolvedRef when the
+  # resolver returns nothing usable.
+  def resolve_entry(ref, resolve)
+    resolved = resolve.call(ref)
+    target = resolved.is_a?(Hash) ? resolved[:target] || resolved["target"] : nil
+    raise UnresolvedRef, ref if target.nil? || target.to_s.strip.empty?
+
+    label = (resolved[:label] || resolved["label"]).to_s.strip
+    [target.to_s, label]
+  end
+
+  # PURE. Render one entry line `- [[<target>|<label>]]` from a single ref. Kept for
+  # callers/tests that render one entry; #section uses add_entry for dedup.
+  def entry(ref, resolve)
+    target, label = resolve_entry(ref, resolve)
+    "- [[#{target}|#{label}]]"
+  end
+
+  # PURE. Resolve ONE sources/chain ref to its `{ target:, label: }` projection,
+  # given the in-memory cross-store maps. This is the single resolver definition
+  # shared by the IO shell (scripts/project-links) and the doctor check, so the two
+  # can never diverge.
+  #
+  #   ref            — "40" (same-store bare id) or "knowdb:1" (cross-store)
+  #   referer_store  — store_key of the intent carrying the ref ("global" / "project:<slug>")
+  #   relocation_map — from GraphRebuild.build_relocation_map (spans all stores)
+  #   store_index    — { store_key => [bare ids present] } (spans all stores)
+  #   node_index     — { store_key => { id => { basename:, label: } } } (spans all stores)
+  #
+  # Returns { target:, label: } (target is `<id>--<slug>` for a same-store id, or
+  # `<slug>:<id>--<slug>` for a cross-store one), or nil when the ref resolves to no
+  # live intent (which makes #section / #entry raise UnresolvedRef).
+  #
+  # Uses GraphRebuild.resolve_ref so a relocation always wins over a coincidentally
+  # reused id (the `global:24` impostor hazard), exactly as the frontmatter rebuild
+  # and the cross-store doctor check do.
+  def resolve_ref_projection(ref, referer_store:, relocation_map:, store_index:, node_index:)
+    require_relative "graph_rebuild"
+
+    res = GraphRebuild.resolve_ref(ref, referer_store: referer_store,
+                                        relocation_map: relocation_map,
+                                        store_index: store_index)
+    case res[:status]
+    when :same_store
+      node = (node_index[referer_store] || {})[res[:id]]
+      return nil if node.nil?
+
+      { target: node[:basename], label: node[:label] }
+    when :cross_store
+      slug, bare = res[:ref].split(":", 2)
+      target_key = canonical_store_key(slug, store_index)
+      node = (node_index[target_key] || {})[bare]
+      return nil if node.nil?
+
+      { target: "#{slug}:#{node[:basename]}", label: node[:label] }
+    else # :dead
+      nil
+    end
+  end
+
+  # Map a ref store slug ("global", "knowdb", "plastic") to a node_index/store_index
+  # key ("global", "project:knowdb", "project:plastic"). Mirrors
+  # GraphRebuild.canonical_store_key's intent for the node_index keyspace.
+  def canonical_store_key(slug, store_index)
+    return "global" if slug == "global"
+    return slug if (store_index || {}).key?(slug)
+
+    projected = "project:#{slug}"
+    (store_index || {}).key?(projected) ? projected : slug
+  end
+end

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/power_tools.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "qmd_sync"
+
+# PowerTools — detect-then-degrade harness for Plastic's optional power-tools
+# (intent 66b). It owns deterministic detection of each tool and builds an
+# obligation ("mandate") string for whichever tools are present, so the agent is
+# obliged (not merely reminded) to use 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
+
+  # Obligation text for whichever tools are present, joined by newlines, or nil
+  # when none are. One MANDATORY line per present tool.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    lines = []
+
+    if qmd?(detector: qmd_detector)
+      lines << "MANDATORY: you MUST use QMD (`qmd search` / `qmd query` over the " \
+               "`plastic-*` collections) to check for an existing or related intent " \
+               "before treating this as new work; do not grep/Read the store first."
+    end
+
+    serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
+    if serena_present
+      lines << "MANDATORY: you MUST use Serena's symbolic tools (find_symbol / " \
+               "get_symbols_overview / find_referencing_symbols) for code navigation " \
+               "before grep/Read."
+    end
+
+    return nil if lines.empty?
+    lines.join("\n")
+  end
+end