@zalom/plastic 1.11.0 → 1.13.0

package/scripts/lib/installer_core.rb

@@ -206,7 +206,7 @@ class InstallerCore
   def statusline_choice(settings_path, argv: [], input: $stdin, reinstall: false)
     existing_command = read_json_safe(settings_path)&.dig("statusLine", "command").to_s
     return :plastic if existing_command.empty?
-    return :plastic if existing_command.include?("plastic-")
+    return :plastic if HookRegistry.claude_purge_command?(existing_command)
 
     idx = argv.index("--statusline")
     flag = idx && argv[idx + 1]
@@ -412,6 +412,8 @@ class InstallerCore
       "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
+      "scripts/lib/rule_catalog.rb" => "scripts/lib/rule_catalog.rb",
+      "scripts/lib/doctor_exclusions.rb" => "scripts/lib/doctor_exclusions.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
       "scripts/skill-lint" => "scripts/skill-lint",
       "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
@@ -941,14 +943,16 @@ class InstallerCore
 
   # ~/.codex/hooks.json merge (intent 102). Guide-settled shape [guide Part 3]:
   # top-level {"hooks": {<Event>: [...]}}, identical to Claude's settings.json
-  # hooks shape, so this mirrors merge_claude_hooks against a different file and
-  # a different purge predicate (the dispatcher command contains "codex-hook",
-  # not the "plastic-" substring merge_claude_hooks matches, since the path is
-  # "~/.plastic/scripts/codex-hook", not "~/.claude/hooks/plastic-<name>").
+  # hooks shape, so this mirrors merge_claude_hooks against a different file.
+  # Both harnesses now match ownership by registry (intent 275), not a
+  # substring: Codex by dispatcher filename equality, because its hooks are
+  # arguments to one shared dispatcher command rather than per-hook launcher
+  # files the way Claude's plastic-<name> launchers are.
   def merge_codex_hooks(hooks_json_path)
     data = read_json_safe(hooks_json_path) || {}
     hooks = data["hooks"] ||= {}
-    purge_stale_codex_hooks(hooks)
+    removed = purge_stale_codex_hooks(hooks)
+    report_removed_hook_entries(removed, "hooks.json")
     plastic = HookRegistry.codex_hooks_json(dispatcher_path: codex_dispatcher_path)
     plastic.each do |event, groups|
       hooks[event] ||= []
@@ -957,23 +961,34 @@ class InstallerCore
     write_json_atomic(hooks_json_path, data)
   end
 
+  # Returns [[event, command], ...] for every entry removed, mirroring
+  # purge_stale_plastic_hooks. Ownership comes from HookRegistry (intent 275).
   def purge_stale_codex_hooks(hooks)
-    codex_cmd = ->(cmd) { cmd.to_s.include?("codex-hook") }
+    removed = []
 
     hooks.each do |event, groups|
       next unless groups.is_a?(Array)
 
       hooks[event] = groups.map do |group|
         if group.is_a?(Hash) && group["hooks"].is_a?(Array)
-          group["hooks"].reject! { |h| codex_cmd.call(h["command"]) }
+          group["hooks"].reject! do |h|
+            HookRegistry.codex_purge_command?(h["command"]) && (removed << [event, h["command"]])
+          end
           group unless group["hooks"].empty?
         elsif group.is_a?(Hash) && group["command"]
-          codex_cmd.call(group["command"]) ? nil : group
+          if HookRegistry.codex_purge_command?(group["command"])
+            removed << [event, group["command"]]
+            nil
+          else
+            group
+          end
         else
           group
         end
       end.compact
     end
+
+    removed
   end
 
   def install_hermes(config, force)
@@ -1202,6 +1217,32 @@ class InstallerCore
     path.sub(Dir.home, "~")
   end
 
+  def report_removed_hook_entries(removed, file_label)
+    return if removed.nil? || removed.empty?
+
+    puts "  \u{1f9f9} Removed #{removed.size} stale Plastic hook entr#{removed.size == 1 ? "y" : "ies"} from #{file_label}:"
+    removed.each { |event, command| puts "     - #{event}: #{tilde(command.to_s)}" }
+  end
+
+  # The other half of intent 275: a hook the purge KEPT because the registry does not
+  # know it, but whose name carries Plastic's prefix. Silence here is what let the
+  # 1.11.0 update delete the owner's plastic-writing-style hook unnoticed; now the
+  # update says the prefix is reserved and the hook stays.
+  def report_reserved_prefix_hooks(hooks)
+    kept = hooks.flat_map do |_event, groups|
+      next [] unless groups.is_a?(Array)
+
+      groups.flat_map { |g| g.is_a?(Hash) ? Array(g["hooks"]).map { |h| h["command"] } + [g["command"]] : [] }
+    end.compact.select { |cmd| cmd.to_s.include?("plastic-") }.uniq
+
+    return if kept.empty?
+
+    puts "  \u{2139}\u{fe0f}  Kept #{kept.size} hook(s) Plastic does not own, named with the reserved plastic- prefix:"
+    kept.each { |cmd| puts "     - #{tilde(cmd.to_s)}" }
+    puts "     The plastic- prefix is reserved for Plastic's own hooks. Rename yours (for"
+    puts "     example ~/.claude/hooks/writing-style) so a future update never mistakes it."
+  end
+
   # --- settings.json merge (read-modify-write, never clobber) ---
 
   def merge_claude_hooks(settings_path, choice: :plastic)
@@ -1211,7 +1252,9 @@ class InstallerCore
     hooks = settings["hooks"] ||= {}
     hook_dir = File.join(Dir.home, ".claude", "hooks")
 
-    purge_stale_plastic_hooks(hooks)
+    removed = purge_stale_plastic_hooks(hooks)
+    report_removed_hook_entries(removed, "settings.json")
+    report_reserved_prefix_hooks(hooks)
 
     # Single source of truth (intent 108, D7): registrations live in
     # HookRegistry; this merge only translates them into settings.json.
@@ -1228,7 +1271,7 @@ class InstallerCore
       groups.each do |g|
         existing = hooks[event].find do |h|
           h.is_a?(Hash) && h["matcher"] == g["matcher"] &&
-            h["hooks"].is_a?(Array) && h["hooks"].any? { |x| x["command"].to_s.include?("plastic-") }
+            h["hooks"].is_a?(Array) && h["hooks"].any? { |x| HookRegistry.claude_purge_command?(x["command"]) }
         end
 
         if existing
@@ -1240,7 +1283,7 @@ class InstallerCore
     end
 
     existing_status = settings["statusLine"]
-    if existing_status && !existing_status.dig("command").to_s.include?("plastic-")
+    if existing_status && !HookRegistry.claude_purge_command?(existing_status["command"])
       cache_dir = File.join(plastic_home, ".cache")
       FileUtils.mkdir_p(cache_dir)
       File.write(File.join(cache_dir, "original-statusline.json"), JSON.pretty_generate(existing_status))
@@ -1254,9 +1297,10 @@ class InstallerCore
     write_json_atomic(settings_path, settings)
   end
 
+  # Returns [[event, command], ...] for every entry removed, so merge_claude_hooks
+  # can report it. Ownership comes from HookRegistry (intent 275), never a substring.
   def purge_stale_plastic_hooks(hooks)
-    plastic_cmd = ->(cmd) { cmd.to_s.include?("plastic-") }
-
+    removed = []
     hooks.delete("statusLine")
 
     hooks.each do |event, groups|
@@ -1264,15 +1308,24 @@ class InstallerCore
 
       hooks[event] = groups.map do |group|
         if group.is_a?(Hash) && group["hooks"].is_a?(Array)
-          group["hooks"].reject! { |h| plastic_cmd.call(h["command"]) }
+          group["hooks"].reject! do |h|
+            HookRegistry.claude_purge_command?(h["command"]) && (removed << [event, h["command"]])
+          end
           group unless group["hooks"].empty?
         elsif group.is_a?(Hash) && group["command"]
-          plastic_cmd.call(group["command"]) ? nil : group
+          if HookRegistry.claude_purge_command?(group["command"])
+            removed << [event, group["command"]]
+            nil
+          else
+            group
+          end
         else
           group
         end
       end.compact
     end
+
+    removed
   end
 
   # --- Codex AGENTS.md marked-section injection (22a/Beads pattern) ---
@@ -1445,10 +1498,10 @@ class InstallerCore
 
       settings["hooks"][event] = groups.map do |group|
         if group.is_a?(Hash) && group["hooks"].is_a?(Array)
-          group["hooks"].reject! { |h| h["command"].to_s.include?("plastic-") }
+          group["hooks"].reject! { |h| HookRegistry.claude_purge_command?(h["command"]) }
           group unless group["hooks"].empty?
         elsif group.is_a?(Hash) && group["command"]
-          group["command"].to_s.include?("plastic-") ? nil : group
+          HookRegistry.claude_purge_command?(group["command"]) ? nil : group
         else
           group
         end
@@ -1457,7 +1510,7 @@ class InstallerCore
 
     settings["hooks"].delete_if { |_, v| v.is_a?(Array) && v.empty? }
     settings.delete("hooks") if settings["hooks"]&.empty?
-    if settings.dig("statusLine", "command").to_s.include?("plastic-")
+    if HookRegistry.claude_purge_command?(settings.dig("statusLine", "command"))
       settings.delete("statusLine")
       original_path = File.join(plastic_home, ".cache", "original-statusline.json")
       if File.exist?(original_path)
@@ -1491,7 +1544,7 @@ class InstallerCore
       data["hooks"][event] = groups.map do |g|
         next g unless g.is_a?(Hash) && Array(g["hooks"]).is_a?(Array)
 
-        g["hooks"] = Array(g["hooks"]).reject { |h| h["command"].to_s.include?("codex-hook") }
+        g["hooks"] = Array(g["hooks"]).reject { |h| HookRegistry.codex_purge_command?(h["command"]) }
         g["hooks"].empty? ? nil : g
       end.compact
     end

package/scripts/lib/rule_catalog.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# RuleCatalog - the one rule vocabulary in Plastic (intent 274), two curated named sets on two
+# different axes so there is exactly one place to look up or register a rule name:
+#
+#   EXCLUDABLE_CHECKS - a doctor check `name` a per-store doctor-exclusions file may name. A
+#   check name says WHICH DIAGNOSTIC FIRED. v1 carries exactly one key, savepoint_operational
+#   (see spec D3): most doctor checks have no exclusion mechanism at all, and this is the only
+#   one the owner asked to make skippable.
+#
+#   REVISION_RULES - the `[rule: <tag>]` vocabulary every revisions.md entry must carry
+#   (scripts/lib/revisions_writer.rb). A tag says WHY an intent's files were structurally
+#   edited. Most check names have no repair verb and most repair verbs are not checks, so this
+#   is a genuinely separate axis, not an alias of EXCLUDABLE_CHECKS.
+#
+# REVISION_RULES is enforced by test only (test/rule_catalog_test.rb), never at
+# RevisionsWriter runtime (spec D2): a receipt writer that refuses to write on an unrecognized
+# tag is a guard that fails harder than the bug it would be catching, so append! keeps
+# accepting any tag and the test catches an unregistered one before it ships.
+#
+# Zero requires (boot-safe): nothing here pulls in json/yaml/io, so this file can load from
+# anywhere, including the SessionStart boot path, without cost.
+#
+# Packaging note (test/packaging_no_store_ids_test.rb): every token below is letter-leading,
+# never digit-leading, so nothing here trips the Folgezettel-id-literal scan. Never put an
+# intent id in this file.
+module RuleCatalog
+  module_function
+
+  EXCLUDABLE_CHECKS = {
+    "savepoint_operational" => "savepoint.md missing entirely, or missing its Done " \
+                               "delivered|abandoned echo, on a terminal intent. Usually " \
+                               "repairable via maintenance-run --tool rebuild-savepoint; " \
+                               "excludable for the gaps 219 D6 forbids ever repairing.",
+  }.freeze
+
+  # Measured from live store data across all eight stores, 2026-08-24 (spec D1).
+  REVISION_RULES = [
+    "links-projection",
+    "broken-chain",
+    "stray-file",
+    "savepoint-operational-reconstruction",
+    "unsanctioned-section",
+    "missing-reciprocity",
+    "misplaced-content",
+    "missing-required-frontmatter",
+    "savepoint-truthfulness",
+    "restored-to-v1",
+    "relocation",
+    "graph-rebuild",
+    "dangling-ref",
+  ].freeze
+
+  def excludable_check?(name)
+    EXCLUDABLE_CHECKS.key?(name)
+  end
+
+  def revision_rule?(tag)
+    REVISION_RULES.include?(tag)
+  end
+end

package/scripts/maintenance-run

@@ -15,6 +15,7 @@
 #   maintenance-run --tool rebuild-graph [--plastic-home PATH] [--apply]
 #   maintenance-run --tool restore-intent-v1 <id> --at <ref> [--plastic-home PATH] [--apply] [--skip-links]
 #   maintenance-run --tool rebuild-savepoint --intent <id> [--store <key>] [--plastic-home PATH] [--apply]
+#   maintenance-run --tool register-exclusions [--rule <name>] [--store <key>] [--plastic-home PATH] [--apply]
 #
 # project-links here is ALWAYS single-intent: --intent is required. A store-wide
 # project-links sweep is the rare, owner-approved batch exception (D2) and is run directly
@@ -38,6 +39,7 @@ require_relative "lib/lock"
 require_relative "lib/maintenance_git"
 require_relative "lib/bridge"
 require_relative "lib/revisions_writer"
+require_relative "doctor" # safe: doctor.rb's CLI is behind $PROGRAM_NAME == __FILE__
 
 DEFAULT_HOME = File.join(Dir.home, ".plastic")
 
@@ -75,7 +77,7 @@ end
 
 def parse_argv(argv)
   opts = { tool: nil, intent: nil, store: nil, plastic_home: DEFAULT_HOME, apply: false,
-           at: nil, skip_links: false, id: nil }
+           at: nil, skip_links: false, id: nil, rule: nil }
   i = 0
   while i < argv.length
     case argv[i]
@@ -86,6 +88,7 @@ def parse_argv(argv)
     when "--apply" then opts[:apply] = true
     when "--at" then opts[:at] = argv[i += 1]
     when "--skip-links" then opts[:skip_links] = true
+    when "--rule" then opts[:rule] = argv[i += 1]
     else
       opts[:id] ||= argv[i] # positional id, restore-intent-v1 only
     end
@@ -269,9 +272,138 @@ def run_rebuild_savepoint(home, intent, store, apply)
   report_result(result)
 end
 
+# Renders one store's canonical doctor-exclusions content (spec D6/D7): a leading comment
+# block documenting the format, then one `rule_name id id id` line per rule, ids sorted. Pure.
+# `existing_text:` (review F2) is the file's raw content BEFORE this run, or nil when the
+# file does not exist yet. A hand-edited exclusion file's comments are the only home for an
+# exemption's justification (D8: no revisions.md receipt exists for this tool), so an update
+# preserves every comment and blank line from `existing_text` verbatim, in original order,
+# ahead of the freshly rendered rule lines - it never re-renders over them. The boilerplate
+# header is written only when there is no existing file to preserve anything from.
+def render_exclusions_file(rules, existing_text: nil)
+  if existing_text
+    lines = existing_text.each_line.select { |l| l.strip.empty? || l.strip.start_with?("#") }.map(&:chomp)
+  else
+    lines = [
+      "# doctor-exclusions - knowingly-exempt (intent_id, rule) pairs (intent 274).",
+      "# Format: rule_name id id id  (one line per rule, ids space-separated).",
+      "# Blank lines and lines starting with # are ignored. Ids only, never any other",
+      "# content - doctor reports how many findings this file suppressed and where",
+      "# this file lives, so the count always stays honest.",
+      "",
+    ]
+  end
+  rules.keys.sort.each do |rule_name|
+    lines << "#{rule_name} #{rules[rule_name].sort.join(" ")}"
+  end
+  "#{lines.join("\n")}\n"
+end
+
+# register-exclusions (intent 274, spec D7/D8): the one-time population tool. Computes
+# violations through Doctor's OWN done_signal_findings_for_dir rather than a reimplementation
+# of that predicate (the drift 222 extracted that function to prevent), unions with any
+# existing hand-edited file, skips (never aborts on) any intent dir holding a fresh delivery
+# lock, and writes ALL stores in one scoped commit (they already live in the single ~/.plastic
+# git repo, so a cross-store write is still one repo and one scoped commit - D7).
+#
+# Writes NO revisions.md entries (D8): this tool modifies no intent directory, only one
+# store-level table per store, so 197's receipt-before-write rule (which covers tools that
+# structurally edit an intent's OWN files) does not apply, and writing one would mean editing
+# every touched Completed intent directory - forbidden, completed intents are immutable. The
+# scoped commit plus the diffable exclusion file itself are the receipt.
+def run_register_exclusions(home, rule, store, apply)
+  rule ||= "savepoint_operational"
+  unless RuleCatalog.excludable_check?(rule)
+    abort_loud("--rule #{rule.inspect} is not excludable (expected one of: " \
+               "#{RuleCatalog::EXCLUDABLE_CHECKS.keys.join(", ")})")
+  end
+
+  doctor = Doctor.new(plastic_home: home)
+  stores = doctor.done_signal_stores(store ? [store] : nil)
+  abort_loud("no store matches --store #{store.inspect}") if store && stores.empty?
+
+  plan = {}
+  skip_lines = []
+
+  stores.each do |s|
+    existing = DoctorExclusions.load(s[:index])
+    if existing[:errors].any?
+      abort_loud("#{s[:scope]}: existing doctor-exclusions is malformed, refusing to rewrite " \
+                 "it (#{existing[:errors].join("; ")})", 1)
+    end
+    # scrub: DoctorExclusions.load already scrubs internally (never raises, D5), but this
+    # raw read feeds render_exclusions_file's own line scan below, which was NOT going
+    # through that scrub - an invalid byte in a hand-written comment raised
+    # Encoding::CompatibilityError here on every register-exclusions run, dry-run included,
+    # even though `existing` itself (loaded via DoctorExclusions.load) reported the file
+    # clean. Scrub this read the same way so both paths agree.
+    existing_text = File.exist?(existing[:path]) ? File.read(existing[:path]).scrub : nil
+
+    found_ids = []
+    doctor.index_sections_by_dir(s[:index]).each do |dirname, in_sections|
+      dir = File.join(s[:store_dir], dirname)
+      next unless File.directory?(dir)
+
+      terminal = (in_sections & ["Completed", "Abandoned"]).any?
+      next unless terminal
+
+      if Lock.fresh?(dir)
+        skip_lines << "#{s[:scope]}: #{dirname} skipped (fresh delivery lock)"
+        next
+      end
+
+      active = in_sections.include?("Active") && !terminal
+      findings = doctor.done_signal_findings_for_dir(
+        dir, label: "#{s[:scope]} store/#{dirname}", scope: s[:scope], dirname: dirname,
+        terminal: terminal, active: active, excluded_rules: []
+      )
+      found_ids << dirname.split("--", 2).first if findings[:operational_gap].any?
+    end
+
+    already = existing[:rules][rule] || []
+    added = found_ids - already
+    next if added.empty?
+
+    merged_rules = existing[:rules].merge(rule => (already | found_ids).sort)
+    plan[s] = { content: render_exclusions_file(merged_rules, existing_text: existing_text), added: added.sort }
+  end
+
+  puts skip_lines.join("\n") unless skip_lines.empty?
+
+  if plan.empty?
+    puts "maintenance-run: no new #{rule} violations to register."
+    exit 0
+  end
+
+  unless apply
+    plan.each do |s, info|
+      puts "maintenance-run: DRY RUN, #{s[:scope]} would register #{info[:added].size} " \
+           "id(s) under #{rule}: #{info[:added].join(", ")}"
+    end
+    exit 0
+  end
+
+  begin
+    result = MaintenanceGit.run_scoped(
+      repo_dir: home, branch_name: "maintenance/register-exclusions-#{stamp}",
+      commit_message: "chore: maintenance - register doctor exclusions (#{rule})"
+    ) do
+      plan.each { |s, info| File.write(DoctorExclusions.path_for(s[:index]), info[:content]) }
+    end
+  rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
+    abort_loud(e.message, 4)
+  rescue RuntimeError => e
+    abort_loud(e.message, 3)
+  end
+  report_result(result)
+end
+
 def main(argv)
   opts = parse_argv(argv)
-  abort_loud("--tool is required (project-links|rebuild-graph|restore-intent-v1|rebuild-savepoint)") unless opts[:tool]
+  unless opts[:tool]
+    abort_loud("--tool is required " \
+               "(project-links|rebuild-graph|restore-intent-v1|rebuild-savepoint|register-exclusions)")
+  end
 
   case opts[:tool]
   when "project-links"
@@ -281,9 +413,11 @@ def main(argv)
     run_restore_intent_v1(opts[:plastic_home], opts[:id], opts[:at], opts[:store], opts[:apply], opts[:skip_links])
   when "rebuild-savepoint"
     run_rebuild_savepoint(opts[:plastic_home], opts[:intent], opts[:store], opts[:apply])
+  when "register-exclusions"
+    run_register_exclusions(opts[:plastic_home], opts[:rule], opts[:store], opts[:apply])
   else
-    abort_loud("unknown --tool #{opts[:tool].inspect} " \
-               "(expected project-links|rebuild-graph|restore-intent-v1|rebuild-savepoint)")
+    abort_loud("unknown --tool #{opts[:tool].inspect} (expected project-links|rebuild-graph|" \
+               "restore-intent-v1|rebuild-savepoint|register-exclusions)")
   end
 end
 

package/scripts/scaffold-intent

@@ -31,8 +31,8 @@
 #
 # outcome is an end-of-Exec step. Run it once the diff and the test summary exist, right
 # before plastic-intent-ending writes the narrative. Writing outcome.md makes the intent
-# read as Done to the statusline and to any stage-derived display (Bridge.derive_stage
-# keys on outcome.md's presence). This does NOT purge a bridge:
+# read as Done to any stage-derived display (Bridge.derive_stage keys on outcome.md's
+# presence). This does NOT purge a bridge:
 # Bridge.purge_done_bridges keys on INDEX Active status plus lock presence, never on the
 # derived stage.
 

package/skills/conventions/SKILL.md

@@ -19,7 +19,7 @@ when the trigger in the second column applies to the work in front of you.
 | `references/knowledge-graph.md` | when creating, linking, curating, or indexing intents and you need the sources-vs-chain doctrine, the tiers of influence, the `## Links` projection, or branch-vs-root directory semantics |
 | `references/lifecycle-and-savepoints.md` | when running a lifecycle stage or a savepoint and you need the subagent report-home contract for how an insight reaches the intent |
 | `references/tiers-and-dispatch.md` | when sizing an intent, choosing agent models, routing to the advisor, or writing an auto-mode human report |
-| `references/gates-and-enforcement.md` | when a transition gate blocks you, or before using an audited escape, for the gate mechanics and the logging contract |
+| `references/gates-and-enforcement.md` | when a transition gate blocks you, or before using an audited escape, for the gate mechanics and the logging contract, or when naming, registering, or retiring a hook |
 | `references/locks-and-worktrees.md` | before taking or releasing a delivery lock, and when working with claims, worktrees, solo mode, or the station ledger |
 | `references/completion-and-done.md` | when ending an intent, for what "intent done" means and the End-stage tail |
 | `references/maintenance-and-revisions.md` | before any structural maintenance edit, for WORK vs MAINTENANCE, the `revisions.md` move-and-record contract, the violation-tag catalog, and the context-economy measurement buckets |

package/skills/conventions/references/gates-and-enforcement.md

@@ -2,6 +2,15 @@
 
 This chapter holds the escape-and-logging depth for each transition gate.
 
+#### Hook naming and ownership
+
+The `plastic-` prefix on an installed hook launcher is reserved for hooks `HookRegistry`
+registers. A user-owned hook must never take it: the installer purges Plastic's registrations
+from the agent's hook config on every update, matching by registry launcher name (current plus
+`RETIRED_HOOK_NAMES`), and doctor's `hooks_no_orphans` reports any unregistered `plastic-*`
+launcher on disk. Renaming or removing a hook from `events` means adding its old name to
+`RETIRED_HOOK_NAMES` in the same change, or every existing install keeps a dead registration.
+
 #### The gates by name
 
 Each gate guards one thing. `scripts/lib/hook_registry.rb` is the single source of truth for

package/skills/conventions/references/maintenance-and-revisions.md

@@ -72,10 +72,12 @@ No commit anywhere, store or project repo, uses `git add -A`; every maintenance
 commit stages only the paths it actually changed (`scripts/end-intent`'s `store_commit`,
 `scripts/maintenance-run`).
 
-The one condition on every maintenance action, with no exception, is that it is recorded.
-Every maintenance action, whether run by a tool or made by hand, must leave an append-only
-`revisions.md` entry on its target intent (`## Revision vN`, a `Why ... [rule: tag]` line, a
-`Prior location`, and the change itself). If the file already exists, a new run appends
+The one condition on every maintenance action that STRUCTURALLY EDITS AN INTENT'S OWN FILES is
+that it is recorded. (One narrow carve-out exists for a tool that edits no intent directory at
+all - see `register-exclusions` below.) Every such maintenance action, whether run by a tool or
+made by hand, must leave an append-only `revisions.md` entry on its target intent (`## Revision
+vN`, a `Why ... [rule: tag]` line, a `Prior location`, and the change itself). If the file
+already exists, a new run appends
 `vN+1`; it never overwrites an earlier entry (precedent: intent 124's `revisions.md` v3
 corrects v2 by appending a correction entry and explicitly leaving v2 in place). This is
 tool-enforced, not prose alone: `scripts/project-links`, `scripts/rebuild-graph`, and
@@ -160,6 +162,38 @@ Violation tags (starter set, free-text tags allowed):
 - `links-projection`: a tool-authored `## Links` regeneration (project-links; intent 197)
 - `graph-rebuild`: a tool-authored sources/chain frontmatter rebuild (rebuild-graph; intent 197)
 
+This is a starter set; free-text tags are allowed. `RuleCatalog::REVISION_RULES`
+(`scripts/lib/rule_catalog.rb`, intent 274) is the canonical, currently-in-use vocabulary,
+measured from live store data rather than hand-curated, and `test/rule_catalog_test.rb` pins
+every `[rule:]` literal hardcoded under `scripts/` as a registered member - so an unregistered
+tag is caught before it ships, without `RevisionsWriter.append!` itself ever refusing to write
+one (a receipt writer that refuses on an unrecognized tag would fail harder than the bug it is
+meant to catch).
+
+#### register-exclusions: a maintenance tool that writes no revisions.md entry
+
+`scripts/maintenance-run --tool register-exclusions [--rule <name>] [--store <key>] [--apply]`
+(intent 274) is the one narrow exception to the "every maintenance action is recorded in
+`revisions.md`" rule above. It populates each store's `doctor-exclusions` file (the per-store
+record of knowingly-exempt `(intent_id, rule)` pairs `doctor`'s `savepoint_operational` check
+honors - see `skills/doctor/SKILL.md`) by computing violations through
+`Doctor#done_signal_findings_for_dir` directly, the same function `check_done_signals` itself
+calls, so the registry can never disagree with the checker about what counts as a violation.
+
+The carve-out: this tool modifies no intent directory at all. It writes exactly one
+store-level table per store (`doctor-exclusions`, sibling to `INDEX.md`), never an intent's
+own files, so the receipt rule above - which covers tools that structurally edit an intent's
+own files - does not apply to it. Writing a `revisions.md` receipt anyway would mean editing
+every touched Completed intent directory, which the standing rule that completed intents are
+immutable forbids outright. The receipt is instead the scoped git commit
+(`MaintenanceGit.run_scoped`) plus the exclusion file itself, where every line is its own
+durable, diffable record - not a missing safeguard, a deliberate substitution for a receipt
+shape that would otherwise require an illegal write.
+
+Like every other tool behind `maintenance-run`, it dry-runs by default (the owner-approval
+gate), unions with any existing hand-edited file content so a manually added id is never
+dropped, and skips (never aborts on) any intent dir holding a fresh delivery lock.
+
 ### Context-economy measurement buckets (84a)
 
 Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.

package/skills/doctor/SKILL.md

@@ -205,6 +205,34 @@ This keeps the update flow clean when nothing is wrong.
 - Non-zero exit codes mean "issues found", not "script crashed".
   Always parse stdout regardless of exit code.
 
+## Doctor-Exclusions: Known-Exempt Findings
+
+Some `savepoint_operational` findings can never legitimately close (a terminal intent with no
+real `outcome.md` has no disposition to echo, and doctor never invents one), so each store
+carries a `doctor-exclusions` file, sibling to that store's `INDEX.md`, recording
+knowingly-exempt `(intent_id, rule)` pairs. Format: one `rule_name id id id` line per rule,
+blank lines and `#` comments ignored. v1 honors exactly one rule, `savepoint_operational`.
+
+**Reading the count.** When any exclusion applies, the `savepoint_operational` check's message
+folds in the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/doctor-exclusions)"`.
+A malformed line in the file forces the check to `warn` with the parse error in `details`, even
+when zero real gaps remain, so a broken file is never silently permissive.
+
+**Hand-editing.** The file is plain text; add a line (or append ids to an existing rule line) and
+save. No installer step, no reindex, and no `revisions.md` entry is required or written.
+
+**Populating it in bulk.** Run the maintenance tool, dry-run first:
+
+```bash
+ruby ~/.plastic/scripts/maintenance-run --tool register-exclusions
+```
+
+This computes every current `savepoint_operational` violation across all stores (or one store
+via `--store <key>`), through doctor's own finding function, and prints what it would register
+without writing anything. Review the output, then re-run with `--apply` to write the file(s) and
+land one scoped git commit. It unions with any existing hand-added ids (never drops one) and
+skips, rather than aborts on, any intent dir holding a fresh delivery lock.
+
 ## References
 
 - Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and the recorded stuck-detection signals when diagnosing gate failures or stuck agents