@zalom/plastic 1.8.0 → 1.10.0

package/scripts/lib/qmd_hook.rb

@@ -5,22 +5,28 @@ require_relative "qmd_sync"
 require_relative "power_tools"
 
 # QmdHook - decision logic for the power-tools UserPromptSubmit hook (intents 66,
-# 66b). Pure and dependency-injected: returns the additionalContext string to
-# emit, or nil to emit nothing. The executable hook wires real deps and prints;
-# this is unit-tested with a fake runner/detector (no real qmd, no network).
+# 66b, 187, 246). Pure and dependency-injected: returns the additionalContext
+# string to emit, or nil to emit nothing. The executable hook wires real deps and
+# prints; this is unit-tested with fake detectors (no real qmd, no network, no
+# subprocess at all).
 #
-# When qmd is present it still injects scored qmd hits (intent 66), then appends
-# the PowerTools mandate (a recommendation per present tool: qmd for finding
-# intents, Enola-first for code navigation, falling back to Serena; intent 187
-# added the enola_detector alongside the pre-existing serena_detector).
+# It emits exactly one thing: the PowerTools mandate, one recommendation line per
+# present tool (qmd for finding intents, Enola-first for code navigation, falling
+# back to Serena; intent 187 added the enola_detector alongside the pre-existing
+# serena_detector).
+#
+# Intent 246 removed the scored qmd hit injection this hook used to prepend.
+# Intent 225 measured that injection at 0.24 intent-level recall@3 against a plain
+# ripgrep control at 0.18, while agent-driven `qmd query` scored 0.71. The failure
+# was recall, not latency, so caching and async were both rejected. QmdSync.search
+# is untouched and still backs the `scripts/qmd-sync search` CLI verb. All three
+# detectors are PATH and marker-file walks with no subprocess, which is why what is
+# left costs about a tenth of a second.
 module QmdHook
   module_function
 
-  MIN_PROMPT_LENGTH = 10
-
-  def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
-          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5,
-          serena_detector: nil, enola_detector: nil)
+  def run(cwd:, detector: QmdSync.method(:detect), serena_detector: nil,
+          enola_detector: nil)
     serena_detector ||= -> { PowerTools.serena?(cwd: cwd) }
     enola_detector ||= -> { PowerTools.enola?(cwd: cwd) }
     qmd_present = !!detector.call
@@ -28,34 +34,8 @@ module QmdHook
     enola_present = !!enola_detector.call
     return nil unless qmd_present || serena_present || enola_present
 
-    p = prompt.to_s.strip
-    # The hit SEARCH is the only expensive step and the only one gated by prompt
-    # triviality: skip it for short or bare-"continue" prompts (and when qmd is
-    # absent). The mandate itself is always-on for whichever tools are present.
-    search_ok = qmd_present && p.length >= MIN_PROMPT_LENGTH && p.downcase != "continue"
-
-    parts = []
-    if search_ok
-      collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
-      hits = QmdSync.search(p, collections: collections, limit: limit,
-                            min_score: min_score, runner: runner, detector: detector)
-      if hits.any?
-        parts << "Related / prior Plastic intents (qmd BM25, includes completed) - " \
-                 "check before treating this as new work:"
-        hits.each do |h|
-          loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
-          pct = (h[:score] * 100).round
-          parts << "- [#{pct}%] #{loc} - #{h[:title]}"
-        end
-        parts << ""
-      end
-    end
-
-    mandate = PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
-                                 serena_detector: -> { serena_present },
-                                 enola_detector: -> { enola_present })
-    parts << mandate if mandate
-    return nil if parts.empty?
-    parts.join("\n")
+    PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
+                       serena_detector: -> { serena_present },
+                       enola_detector: -> { enola_present })
   end
 end

package/scripts/lib/qmd_sync.rb

@@ -134,21 +134,6 @@ module QmdSync
     pid
   end
 
-  # True when the QMD index has no pending (unembedded) documents. Binary
-  # freshness signal for the retrieval gate (intent 84, Lever 2). `qmd status` is
-  # plain text (no --json); it prints a line like "Pending: N need embedding".
-  # No pending line found -> treat as fresh (conservative: a parse miss must not
-  # block reads). Runner failure -> false (cannot confirm freshness). The caller
-  # gates on `detect` first, so absence is handled upstream; this only answers
-  # "is the present index fresh?". Pure via the injected runner.
-  def self.fresh?(runner: default_runner)
-    out, ok = runner.call(["status"])
-    return false unless ok && out
-    m = out[/^\s*Pending:\s*(\d+)\b/i, 1]
-    pending = m ? m.to_i : 0
-    pending.zero?
-  end
-
   # Read-only status used by doctor and the session-start report line.
   # Returns a structured hash; never mutates the index.
   def status(plastic_home:, runner: default_runner, detector: method(:detect))

package/scripts/lib/revisions_writer.rb

@@ -15,7 +15,7 @@ module RevisionsWriter
   module_function
 
   # PURE. Renders one `## Revision vN - TIMESTAMP` entry in the documented shape
-  # (PLASTIC-reference.md > Structural maintenance and revisions.md; templates/revisions.md).
+  # (plastic-conventions > references/maintenance-and-revisions.md; templates/revisions.md).
   # `n` is the next revision number (caller resolves it via next_revision_number, or a caller
   # that already knows it, e.g. a batch writer amortizing one file read across many entries).
   # `why` is the one-sentence reason ending in "[rule: <tag>]" (tag is appended here if the

package/scripts/lib/ruby_probe.rb

@@ -0,0 +1,60 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Which ruby would a spawned Plastic hook actually get, and what version is it?
+# Intent 235, D6. Pure and dependency injected: the capture seam is a lambda, so
+# tests never spawn a process and never touch ENV.
+#
+# A hook is launched by the agent application, not by a login shell, so a version
+# manager that activates on shell prompt render (mise, rbenv, asdf) may never reach
+# it and bare `ruby` can still resolve to the system interpreter. Doctor reports
+# that. It never repairs it.
+#
+# Mechanism, and why it is honest:
+#   - The command word is the bare name "ruby", so the operating system resolves it
+#     on the inherited PATH exactly the way it does for a spawned bash launcher. We
+#     do not read PATH ourselves and we do not reimplement the search.
+#   - The resolved interpreter answers for itself: RUBY_VERSION is its own version,
+#     RbConfig.ruby is its own absolute path. One spawn, no guessing.
+#   - RUBYOPT is cleared, matching what every Plastic launcher now does. That makes
+#     this the honest simulation of the post-fix world, and it stops the probe from
+#     crashing on the exact machine that most needs the report (an old ruby plus a
+#     shell that exports RUBYOPT=--yjit).
+module RubyProbe
+  module_function
+
+  # A hash passed as the first argument MERGES onto the inherited environment. It
+  # clears nothing unless the key is present with a nil or empty value, so the nil
+  # here is load bearing.
+  CLEARED_ENV = { "RUBYOPT" => nil }.freeze
+
+  PROBE_ARGS = ["-rrbconfig", "-e", "puts RUBY_VERSION; puts RbConfig.ruby"].freeze
+
+  def default_capture
+    lambda do |env, command, *args|
+      require "open3"
+      out, _err, status = Open3.capture3(env, command, *args)
+      [out, status.success?]
+    rescue Errno::ENOENT
+      ["", false] # no ruby on PATH: undetectable, fail open
+    end
+  end
+
+  # => { found: true, version: "3.3.5", path: "/opt/ruby/bin/ruby" }
+  # => { found: false, version: nil, path: nil } on any trouble at all.
+  def resolve(capture: default_capture)
+    out, ok = capture.call(CLEARED_ENV, "ruby", *PROBE_ARGS)
+    return not_found unless ok
+
+    version, path = out.to_s.lines.map(&:strip).reject(&:empty?)
+    return not_found if version.nil? || version.empty?
+
+    { found: true, version: version, path: path }
+  rescue StandardError
+    not_found
+  end
+
+  def not_found
+    { found: false, version: nil, path: nil }
+  end
+end

package/scripts/lib/scaffold_intent.rb

@@ -0,0 +1,392 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "worktree"
+require_relative "bridge"
+require_relative "spec_header"
+require_relative "intent_validator"
+
+# ScaffoldIntent - all logic for `scripts/scaffold-intent` (intent 213). Three
+# subcommands (spec|checklist|outcome), each writes one lifecycle artifact by copying or
+# mechanically deriving it from an already-committed source: the intent file's
+# `### Decisions` list, spec.md's `## Acceptance Criteria` list, or a `git diff --stat`
+# plus an optional supplied test-summary file. No subcommand interprets or invents prose;
+# a field this module cannot derive mechanically is left as the template's own stub text
+# instead of being guessed at.
+#
+# `scaffold-intent` does not scaffold `actions/` in any form (intent 133a, D11): actions
+# require judgment and stay entirely with the planner. No method here creates the
+# directory, writes a `.gitkeep`, or writes a sentinel-only `ACTION_*.md`.
+#
+# Pure and dependency-injected: never calls `exit` or `abort`, never reads `ARGV` or
+# `ENV` directly (only via the ambient `Dir.home` default, matching Bridge/Worktree
+# convention). A git seam is injected as `runner:`, defaulting to
+# `Worktree::ShellRunner.new`, so tests drive this in process with a fake runner and
+# never touch real git. Every method returns a value; `scripts/scaffold-intent` maps the
+# returned result to an exit code.
+module ScaffoldIntent
+  module_function
+
+  SPEC_SECTIONS = [
+    "## Problem", "## Goals", "## Non-Goals", "## Approach",
+    "## Alternatives Considered", "## Decisions",
+    "## Acceptance Criteria", "## Open Questions",
+  ].freeze
+
+  SETTLED_PLACEHOLDER_COMMENT =
+    "<!-- Settled: yes (<reason>)  optional, add this line only when the design is settled -->\n"
+
+  # --- path resolution (pure) --------------------------------------------------
+
+  def expand(path)
+    File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+  end
+
+  # Resolve the single "<store>/<id>--*" directory. Returns [dir, nil] on success, or
+  # [nil, message] on a usage failure (no match, or more than one match).
+  def resolve_intent_dir(store, id)
+    matches = Dir.glob(File.join(store, "#{id}--*")).select { |d| File.directory?(d) }
+    return [nil, "no intent directory matches #{id}--* under #{store}"] if matches.empty?
+    if matches.length > 1
+      return [nil, "ambiguous id #{id.inspect}: #{matches.length} matching directories under #{store}"]
+    end
+
+    [matches.first, nil]
+  end
+
+  # The templates dir, resolved the same way from this file's own directory
+  # (scripts/lib) as `scripts/scaffold-intent` resolves it from its own directory
+  # (scripts/): two levels up. A repo checkout has templates/ at the repo root; an
+  # installed copy has it at <plastic_home>/templates, which is also two levels up
+  # from <plastic_home>/scripts/lib. The explicit `<plastic_home>/templates` fallback
+  # covers the case where that computed path does not exist. Returns nil when neither
+  # exists.
+  def resolve_templates_dir(home: Dir.home)
+    primary = File.expand_path("../../templates", __dir__)
+    return primary if Dir.exist?(primary)
+
+    fallback = File.expand_path(File.join(home, ".plastic", "templates"))
+    return fallback if Dir.exist?(fallback)
+
+    nil
+  end
+
+  def templates_missing_message(home: Dir.home)
+    primary = File.expand_path("../../templates", __dir__)
+    fallback = File.expand_path(File.join(home, ".plastic", "templates"))
+    "no templates directory found; tried #{primary} and #{fallback}"
+  end
+
+  # --- result builders (pure) ---------------------------------------------------
+
+  def ok_result(path)
+    { status: :ok, code: 0, message: nil, path: path }
+  end
+
+  def refuse_result(path)
+    { status: :refused, code: 2, path: path,
+      message: "#{path} already has real content; pass --force to overwrite it deliberately" }
+  end
+
+  def error_result(message)
+    { status: :error, code: 3, message: message, path: nil }
+  end
+
+  # True iff `target` exists, carries real (non-sentinel) content, and `force` was not
+  # passed: the caller must refuse to write and leave the file untouched.
+  def refuse_without_force?(target, force)
+    File.exist?(target) && Bridge.stage_file_present?(target) && !force
+  end
+
+  # --- generic section helpers (pure) --------------------------------------------
+
+  # Split `text` into { "## Heading" => body_text } by top-level `## ` headings (never
+  # `### `). Each body runs from the line after its heading to the line before the next
+  # `## ` heading (or EOF), copied verbatim including any trailing blank line.
+  def sections_from(text)
+    sections = {}
+    current = nil
+    buf = []
+    text.each_line do |line|
+      if line.start_with?("## ")
+        sections[current] = buf.join if current
+        current = line.rstrip
+        buf = []
+      elsif current
+        buf << line
+      end
+    end
+    sections[current] = buf.join if current
+    sections
+  end
+
+  # Replace the body of `heading` in `text` with `new_body_lines` (an Array of String
+  # fragments), leaving every other line untouched. A no-op (returns `text` unchanged)
+  # when `heading` is not found.
+  def replace_section_body(text, heading, new_body_lines)
+    lines = text.lines
+    idx = lines.index { |l| l.rstrip == heading }
+    return text if idx.nil?
+
+    stop = idx + 1
+    stop += 1 while stop < lines.length && !lines[stop].start_with?("## ")
+    (lines[0..idx] + new_body_lines + lines[stop..]).join
+  end
+
+  # --- `### Decisions` extraction from the intent file (pure) --------------------
+
+  # Byte-for-byte body of the first `### Decisions` heading in `intent_file_content`.
+  # Returns [body, nil] on success, or [nil, message] when the heading is absent or its
+  # body has no non-blank line.
+  def extract_decisions(intent_file_content)
+    lines = intent_file_content.lines
+    idx = lines.index { |l| l.rstrip == "### Decisions" }
+    return [nil, "the intent file has no ### Decisions list to copy; the Why stage is not finished"] if idx.nil?
+
+    stop = idx + 1
+    stop += 1 while stop < lines.length && !(lines[stop].start_with?("## ") || lines[stop].start_with?("### "))
+    body_lines = lines[(idx + 1)...stop]
+    body_lines = strip_blank_edges(body_lines)
+
+    if body_lines.empty?
+      return [nil, "the intent file's ### Decisions list has no content to copy; the Why stage is not finished"]
+    end
+
+    [body_lines.join, nil]
+  end
+
+  # --- `## Acceptance Criteria` extraction from spec.md (pure) --------------------
+
+  # Byte-for-byte body of `## Acceptance Criteria` in `spec_content`. Returns
+  # [body, nil] on success, or [nil, message] when the heading is absent or its body
+  # holds no `- [ ]` line.
+  def extract_acceptance_criteria(spec_content)
+    lines = spec_content.lines
+    idx = lines.index { |l| l.rstrip == "## Acceptance Criteria" }
+    return [nil, "spec.md has no ## Acceptance Criteria section to copy"] if idx.nil?
+
+    stop = idx + 1
+    stop += 1 while stop < lines.length && !lines[stop].start_with?("## ")
+    body_lines = strip_blank_edges(lines[(idx + 1)...stop])
+
+    unless body_lines.any? { |l| l =~ /^\s*- \[ \]/ }
+      return [nil, "spec.md's ## Acceptance Criteria has no checklist items (no line matching '- [ ]')"]
+    end
+
+    [body_lines.join, nil]
+  end
+
+  def strip_blank_edges(lines)
+    lines = lines.drop_while { |l| l.strip.empty? }
+    lines.reverse.drop_while { |l| l.strip.empty? }.reverse
+  end
+
+  # --- spec subcommand ------------------------------------------------------------
+
+  def scaffold_spec(intent_dir:, force:, templates_dir: nil, home: Dir.home)
+    target = File.join(intent_dir, "spec.md")
+    return refuse_result(target) if refuse_without_force?(target, force)
+
+    intent_file = Bridge.intent_file(intent_dir)
+    return error_result("the intent file is missing at #{intent_file}") unless File.exist?(intent_file)
+
+    intent_content = File.read(intent_file)
+    fm = IntentValidator.parse_frontmatter_text(intent_content)
+    intent_name = fm.is_a?(Hash) ? fm["intent"] : nil
+    if Bridge.blank?(intent_name)
+      return error_result("the intent file at #{intent_file} has no frontmatter intent name")
+    end
+
+    decisions_body, decisions_err = extract_decisions(intent_content)
+    return error_result(decisions_err) if decisions_body.nil?
+
+    tdir = templates_dir || resolve_templates_dir(home: home)
+    return error_result(templates_missing_message(home: home)) if tdir.nil?
+
+    spec_template_path = File.join(tdir, "spec.md")
+    return error_result("spec.md template not found at #{spec_template_path}") unless File.exist?(spec_template_path)
+
+    written = build_spec_content(intent_name: intent_name, decisions_body: decisions_body,
+                                  template_text: File.read(spec_template_path))
+
+    FileUtils.mkdir_p(intent_dir)
+    File.write(target, written)
+    ok_result(target)
+  end
+
+  def build_spec_content(intent_name:, decisions_body:, template_text:)
+    template_sections = sections_from(template_text)
+
+    out = []
+    out << SpecHeader.render(tier: nil, settled_reason: nil)
+    out << SETTLED_PLACEHOLDER_COMMENT
+    out << "\n"
+    out << "# Spec: #{intent_name}\n"
+    out << "\n"
+
+    SPEC_SECTIONS.each do |heading|
+      out << "#{heading}\n"
+      if heading == "## Decisions"
+        out << decisions_body
+        out << "\n"
+      else
+        out << (template_sections[heading] || "")
+      end
+    end
+
+    out.join
+  end
+
+  # --- checklist subcommand --------------------------------------------------------
+
+  def scaffold_checklist(intent_dir:, force:, templates_dir: nil, home: Dir.home)
+    target = File.join(intent_dir, "checklist.md")
+    return refuse_result(target) if refuse_without_force?(target, force)
+
+    spec_path = File.join(intent_dir, "spec.md")
+    unless File.exist?(spec_path) && Bridge.stage_file_present?(spec_path)
+      return error_result("spec.md is missing or still the scaffold placeholder at #{spec_path}")
+    end
+
+    ac_body, ac_err = extract_acceptance_criteria(File.read(spec_path))
+    return error_result(ac_err) if ac_body.nil?
+
+    intent_file = Bridge.intent_file(intent_dir)
+    fm = IntentValidator.parse_frontmatter(intent_file)
+    intent_name = fm.is_a?(Hash) ? fm["intent"] : nil
+    if Bridge.blank?(intent_name)
+      return error_result("the intent file at #{intent_file} has no frontmatter intent name")
+    end
+
+    tdir = templates_dir || resolve_templates_dir(home: home)
+    return error_result(templates_missing_message(home: home)) if tdir.nil?
+
+    checklist_template_path = File.join(tdir, "checklist.md")
+    unless File.exist?(checklist_template_path)
+      return error_result("checklist.md template not found at #{checklist_template_path}")
+    end
+
+    template_text = File.read(checklist_template_path).sub("{{INTENT_NAME}}", intent_name)
+    written = replace_section_body(template_text, "## In Progress", [ac_body, "\n"])
+
+    FileUtils.mkdir_p(intent_dir)
+    File.write(target, written)
+    ok_result(target)
+  end
+
+  # --- repo / base-branch resolution (shared with ACTION_3) -----------------------
+
+  # The provisioned code worktree for this intent when it exists on disk, else the git
+  # toplevel of the current working directory. Returns nil when neither resolves.
+  def resolve_repo_dir(store:, id:, intent_dir:, home: Dir.home, runner: Worktree::ShellRunner.new)
+    wt_home = Worktree.home_from_store(store) || home
+    slug = Worktree.slug_for_store(store, home: wt_home)
+    intent_slug = File.basename(intent_dir).split("--", 2).last
+    paths = Worktree.paths(slug: slug, intent_id: id, intent_slug: intent_slug, home: wt_home)
+    code = paths["code"]
+    return code if code && Dir.exist?(code)
+
+    res = runner.run("-C", Dir.pwd, "rev-parse", "--show-toplevel")
+    return nil unless res.success?
+
+    top = res.stdout.to_s.strip
+    top.empty? ? nil : top
+  end
+
+  # Standard git base-branch detection, first success wins: origin/HEAD, then `main`,
+  # then `master`. Returns nil when none resolve.
+  def detect_base_branch(repo, runner: Worktree::ShellRunner.new)
+    res = runner.run("-C", repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+    if res.success?
+      ref = res.stdout.to_s.strip
+      return ref.sub(%r{\Aorigin/}, "") unless ref.empty?
+    end
+
+    return "main" if runner.run("-C", repo, "rev-parse", "--verify", "--quiet", "main").success?
+    return "master" if runner.run("-C", repo, "rev-parse", "--verify", "--quiet", "master").success?
+
+    nil
+  end
+
+  # [stdout, nil] on success, [nil, stderr] on failure. Three-dot range so the diff is
+  # against the merge base, not the tip of the base branch.
+  def diffstat(repo, base, runner: Worktree::ShellRunner.new)
+    res = runner.run("-C", repo, "diff", "--stat", "#{base}...HEAD")
+    return [nil, res.stderr.to_s.strip] unless res.success?
+
+    [res.stdout.to_s, nil]
+  end
+
+  # --- outcome subcommand -----------------------------------------------------------
+
+  def scaffold_outcome(intent_dir:, force:, store:, id:, test_summary: nil,
+                       home: Dir.home, runner: Worktree::ShellRunner.new, templates_dir: nil)
+    target = File.join(intent_dir, "outcome.md")
+    return refuse_result(target) if refuse_without_force?(target, force)
+
+    intent_file = Bridge.intent_file(intent_dir)
+    return error_result("the intent file is missing at #{intent_file}") unless File.exist?(intent_file)
+
+    fm = IntentValidator.parse_frontmatter(intent_file)
+    intent_name = fm.is_a?(Hash) ? fm["intent"] : nil
+    if Bridge.blank?(intent_name)
+      return error_result("the intent file at #{intent_file} has no frontmatter intent name")
+    end
+
+    tdir = templates_dir || resolve_templates_dir(home: home)
+    return error_result(templates_missing_message(home: home)) if tdir.nil?
+
+    outcome_template_path = File.join(tdir, "outcome.md")
+    unless File.exist?(outcome_template_path)
+      return error_result("outcome.md template not found at #{outcome_template_path}")
+    end
+
+    verification_body = build_verification_body(store: store, id: id, intent_dir: intent_dir,
+                                                 home: home, runner: runner, test_summary: test_summary)
+
+    content = File.read(outcome_template_path).sub("# Outcome: <intent name>", "# Outcome: #{intent_name}")
+    written = replace_section_body(content, "## Verification", [verification_body, "\n"])
+
+    FileUtils.mkdir_p(intent_dir)
+    File.write(target, written)
+    ok_result(target)
+  end
+
+  def build_verification_body(store:, id:, intent_dir:, home:, runner:, test_summary:)
+    repo = resolve_repo_dir(store: store, id: id, intent_dir: intent_dir, home: home, runner: runner)
+
+    out = []
+    if repo.nil?
+      out << "Diffstat unavailable: no repo could be resolved for this intent\n"
+    else
+      base = detect_base_branch(repo, runner: runner)
+      if base.nil?
+        out << "Diffstat unavailable: no base branch could be detected (no origin/HEAD, main, or master)\n"
+      else
+        stat, err = diffstat(repo, base, runner: runner)
+        if stat.nil?
+          out << "Diffstat unavailable: #{err}\n"
+        else
+          out << "Diffstat against #{base}:\n"
+          out << "```\n"
+          out << stat
+          out << "\n" unless stat.end_with?("\n")
+          out << "```\n"
+        end
+      end
+    end
+
+    unless Bridge.blank?(test_summary)
+      out << "\n"
+      out << "Test summary from #{test_summary}:\n"
+      out << "```\n"
+      content = File.read(test_summary)
+      out << content
+      out << "\n" unless content.end_with?("\n")
+      out << "```\n"
+    end
+
+    out.join
+  end
+end

package/scripts/lib/spec_header.rb

@@ -0,0 +1,83 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# SpecHeader - the single implementation that parses the `Tier:` and `Settled:` lines out
+# of a spec.md's header block (intent 213). No script, skill, or hook re-implements this
+# grammar anywhere else; Bridge.savepoint_tier delegates here instead of carrying its own
+# copy of the Tier regex.
+#
+# Grammar (both lines live above the `# ` level-1 heading):
+#
+#   Tier: L
+#   Settled: yes (design fixed by the 2026-07-18 Fable advisor verdict)
+#
+# `Tier:` is exactly one of S, M, L; anything else is unparseable and yields nil. An ABSENT
+# `Settled:` line means not settled, there is no `Settled: no` variant. The parenthesised
+# reason is REQUIRED for a line to count as settled: a bare `Settled: yes` with no reason
+# does NOT parse as settled. D2 calls Settled a ONE-WAY DOOR (leniency accepted now can
+# never be tightened later), so this stays strict from the start rather than being loosened
+# once and then needing a breaking change to fix.
+module SpecHeader
+  module_function
+
+  # Mirrors Bridge::PLACEHOLDER_SENTINEL (scripts/lib/bridge.rb:22). Not required in from
+  # bridge.rb to avoid a require cycle: bridge.rb requires spec_header.rb, so spec_header.rb
+  # must have zero require_relative dependencies of its own.
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+
+  HEADER_BLOCK_MAX_LINES = 10
+
+  TIER_RE = /\ATier:\s*(S|M|L)\z/
+  SETTLED_RE = /\ASettled:\s*yes\s*\((.*)\)\z/
+
+  # PURE. Parse a spec.md's raw text. Returns a Hash with symbol keys, always the same
+  # three keys: tier ("S"|"M"|"L"|nil), settled (true|false), settled_reason (String|nil).
+  def parse(text)
+    result = { tier: nil, settled: false, settled_reason: nil }
+    return result if text.nil?
+
+    lines = text.each_line.first(HEADER_BLOCK_MAX_LINES)
+    lines.each do |raw|
+      line = raw.chomp.strip
+      next if line.empty?
+      next if line == PLACEHOLDER_SENTINEL
+      break if line.start_with?("# ")
+
+      if (m = line.match(TIER_RE))
+        result[:tier] = m[1]
+      elsif (m = line.match(SETTLED_RE))
+        result[:settled] = true
+        result[:settled_reason] = m[1]
+      end
+    end
+
+    result
+  end
+
+  # Read at most the header block off disk and parse it. Returns the same Hash shape as
+  # `parse`, with every value nil/false when the path does not exist or cannot be read.
+  def parse_file(path)
+    lines = []
+    File.open(path) do |f|
+      HEADER_BLOCK_MAX_LINES.times do
+        line = f.gets
+        break if line.nil?
+        lines << line
+      end
+    end
+    parse(lines.join)
+  rescue StandardError
+    { tier: nil, settled: false, settled_reason: nil }
+  end
+
+  # Render the two header lines for a spec.md. `tier` is "S"|"M"|"L" or nil, `settled_reason`
+  # is a String or nil. Returns a String ending in one newline. A nil tier renders the
+  # placeholder `Tier: S|M|L`; a nil reason renders no Settled line at all (absent means not
+  # settled).
+  def render(tier: nil, settled_reason: nil)
+    lines = []
+    lines << "Tier: #{tier || 'S|M|L'}"
+    lines << "Settled: yes (#{settled_reason})" if settled_reason
+    "#{lines.join("\n")}\n"
+  end
+end