@zalom/plastic 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/doctor.rb

@@ -13,6 +13,7 @@ require "date"
 
 require_relative "lib/doctor_core"
 
+require_relative "lib/doctor_exclusions"
 require_relative "lib/qmd_sync"
 require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
@@ -531,17 +532,24 @@ class Doctor
 # check_done_signals's store-wide loop (211's territory, unchanged severities) and the new
 # per-intent check (check_intent_end) call, so the two surfaces can never independently
 # drift on what counts as a phantom line or a completeness gap. Returns
-# {conflict:, phantom:, gap:, stalled:} where conflict/phantom/stalled are nil or a finding
-# string, and gap is an ARRAY (0, 1, or 2 strings): the original inline code pushed the
-# "outcome missing" gap and the "audit echo missing" gap as two SEPARATE, independent `if`
-# blocks (never elsif), so a single terminal dir missing BOTH can legitimately contribute
-# two distinct gap strings in the same pass; collapsing that into one nilable field would
-# silently drop one of the two on a dir where both are true (verified against
-# test/doctor_done_signals_test.rb's fixtures before this extraction, per plan.md Step 3).
-def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, active:)
+# {conflict:, phantom:, gap:, operational_gap:, excluded:, stalled:} where conflict/phantom/
+# stalled are nil or a finding string, and gap/operational_gap/excluded are ARRAYs (0, 1, or 2
+# strings): the original inline code pushed the "outcome missing" gap and the "audit echo
+# missing" gap as two SEPARATE, independent `if` blocks (never elsif), so a single terminal
+# dir missing BOTH can legitimately contribute two distinct gap strings in the same pass;
+# collapsing that into one nilable field would silently drop one of the two on a dir where
+# both are true (verified against test/doctor_done_signals_test.rb's fixtures before this
+# extraction, per plan.md Step 3).
+#
+# `excluded_rules:` (intent 274) is the set of rule names the caller's doctor-exclusions file
+# names for this one intent id. A savepoint_operational finding routes to :excluded instead of
+# :operational_gap when "savepoint_operational" is in that set; the :gap bucket (signals_complete,
+# the outcome.md check) never consults it, which is what keeps the exclusion key (intent_id,
+# rule) rather than just intent_id (see test/doctor_done_signals_test.rb case 12).
+def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, active:, excluded_rules: [])
   outcome = File.join(dir, "outcome.md")
   outcome_real = Bridge.stage_file_present?(outcome)
-  findings = { conflict: nil, phantom: nil, gap: [], operational_gap: [], stalled: nil }
+  findings = { conflict: nil, phantom: nil, gap: [], operational_gap: [], excluded: [], stalled: nil }
 
   # HARD conflict: the deliverable exists but INDEX still says Active. This
   # is the one true INDEX-wins disagreement, so it stays a fail.
@@ -578,12 +586,13 @@ def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, activ
     # reconstructible via maintenance-run --tool rebuild-savepoint, so this is repairable and
     # reported as a fixable warn (savepoint_operational).
     savepoint = File.join(dir, "savepoint.md")
+    bucket = excluded_rules.include?("savepoint_operational") ? findings[:excluded] : findings[:operational_gap]
     if !File.exist?(savepoint)
-      findings[:operational_gap] << "#{label}: terminal in INDEX but savepoint.md is missing " \
-                                    "entirely (operational - reconstructible)"
+      bucket << "#{label}: terminal in INDEX but savepoint.md is missing " \
+                "entirely (operational - reconstructible)"
     elsif File.read(savepoint) !~ /\bDone\b.*\b(delivered|abandoned)\b/
-      findings[:operational_gap] << "#{label}: terminal in INDEX but savepoint.md has no " \
-                                    "`Done delivered|abandoned` line (operational - reconstructible)"
+      bucket << "#{label}: terminal in INDEX but savepoint.md has no " \
+                "`Done delivered|abandoned` line (operational - reconstructible)"
     end
 
     # Stalled completion: unchanged, never consulted amnesty.
@@ -601,10 +610,20 @@ def check_done_signals(scopes: nil)
   conflicts = []
   gaps = []              # delivery-claim (outcome.md) gaps only - legacy, informational
   operational_gaps = []  # savepoint gaps (missing file, or missing Done echo) - repairable
+  excluded = []           # savepoint gaps knowingly exempted via doctor-exclusions (intent 274)
+  exclusion_errors = []   # malformed doctor-exclusions lines, scope-tagged
+  exclusion_error_paths = []
+  exclusion_paths = []    # files that actually contributed a live exclusion
   stalled = []
   phantoms = []
 
   done_signal_stores(scopes).each do |store|
+    exclusions = DoctorExclusions.load(store[:index])
+    if exclusions[:errors].any?
+      exclusion_errors.concat(exclusions[:errors].map { |e| "#{store[:scope]}: #{e}" })
+      exclusion_error_paths << exclusions[:path]
+    end
+
     index_sections_by_dir(store[:index]).each do |dirname, in_sections|
       dir = File.join(store[:store_dir], dirname)
       next unless File.directory?(dir)
@@ -612,17 +631,26 @@ def check_done_signals(scopes: nil)
       terminal = (in_sections & ["Completed", "Abandoned"]).any?
       active = in_sections.include?("Active") && !terminal
       label = "#{store[:scope]} store/#{dirname}"
+      intent_id = dirname.split("--", 2).first
+      excluded_rules = DoctorExclusions.rules_for(exclusions, intent_id)
 
       findings = done_signal_findings_for_dir(
-        dir, label: label, scope: store[:scope], dirname: dirname, terminal: terminal, active: active
+        dir, label: label, scope: store[:scope], dirname: dirname, terminal: terminal, active: active,
+        excluded_rules: excluded_rules
       )
       conflicts << findings[:conflict] if findings[:conflict]
       phantoms << findings[:phantom] if findings[:phantom]
       gaps.concat(findings[:gap])
       operational_gaps.concat(findings[:operational_gap])
+      if findings[:excluded].any?
+        excluded.concat(findings[:excluded])
+        exclusion_paths << exclusions[:path]
+      end
       stalled << findings[:stalled] if findings[:stalled]
     end
   end
+  exclusion_paths.uniq!
+  exclusion_error_paths.uniq!
 
   checks = []
 
@@ -662,18 +690,39 @@ def check_done_signals(scopes: nil)
     )
   end
 
-  # savepoint_operational (intent 211, NEW): missing savepoint.md or missing Done echo -
-  # repairable via maintenance-run --tool rebuild-savepoint, so this stays warn+fixable.
-  if operational_gaps.empty?
+  # savepoint_operational (intent 211; intent 274 adds the per-store doctor-exclusions index):
+  # missing savepoint.md or missing Done echo - repairable via maintenance-run --tool
+  # rebuild-savepoint for most gaps, or knowingly excluded for the ones 219 D6 forbids ever
+  # repairing (no real outcome.md to echo a disposition from). Three branches (spec D4/D5):
+  # a malformed exclusion file can never report pass (loud), a clean remaining gap set reports
+  # pass with the exclusion count folded in, and a real remaining gap set stays warn, same as
+  # before intent 274, with the same count folded in when exclusions applied.
+  exclusion_suffix = excluded.empty? ? "" : " (#{excluded.size} excluded via #{exclusion_paths.join(", ")})"
+
+  if exclusion_errors.any?
+    checks << check(
+      category: "done_signals", name: "savepoint_operational", status: "warn",
+      message: "#{operational_gaps.size} terminal intent#{operational_gaps.size == 1 ? "" : "s"} " \
+               "missing an operational savepoint.md or its Done echo, and " \
+               "#{exclusion_errors.size} doctor-exclusions error#{exclusion_errors.size == 1 ? "" : "s"} " \
+               "(a malformed exclusion file never suppresses a finding)#{exclusion_suffix}",
+      details: operational_gaps + exclusion_errors, fixable: true,
+      fix_hint: "Fix the malformed doctor-exclusions file(s) (#{exclusion_error_paths.join(", ")}) - " \
+                "format `rule_name id id id`, blank lines and # comments ignored - then reconstruct " \
+                "any remaining real gap via `maintenance-run --tool rebuild-savepoint --intent <id> " \
+                "--apply` (197-conformant: receipt-before-write via RevisionsWriter, one intent per " \
+                "invocation, owner-approval-gated)."
+    )
+  elsif operational_gaps.empty?
     checks << check(
       category: "done_signals", name: "savepoint_operational", status: "pass",
-      message: "No terminal intent is missing an operational savepoint.md or its Done echo"
+      message: "No terminal intent is missing an operational savepoint.md or its Done echo#{exclusion_suffix}"
     )
   else
     checks << check(
       category: "done_signals", name: "savepoint_operational", status: "warn",
       message: "#{operational_gaps.size} terminal intent#{operational_gaps.size == 1 ? "" : "s"} " \
-               "missing an operational savepoint.md or its Done echo (reconstructible)",
+               "missing an operational savepoint.md or its Done echo (reconstructible)#{exclusion_suffix}",
       details: operational_gaps, fixable: true,
       fix_hint: "Reconstruct the minimal two-line started/Done echo via " \
                 "`maintenance-run --tool rebuild-savepoint --intent <id> --apply` (197-conformant: " \

package/scripts/lib/doctor_core.rb

@@ -32,7 +32,9 @@ class Doctor
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired
   # outside HookRegistry.events entirely, so it must be excluded from the
   # orphan-launcher scan below or a correct install would report a false orphan.
-  CLAUDE_NON_HOOK_LAUNCHERS = %w[plastic-statusline].freeze
+  # Defined in HookRegistry (intent 275) so the installer's purge can read it too;
+  # this is an alias, not a second source of truth.
+  CLAUDE_NON_HOOK_LAUNCHERS = HookRegistry::CLAUDE_NON_HOOK_LAUNCHERS
 
   REQUIRED_SCRIPTS = %w[
     folgezettel-id
@@ -243,7 +245,10 @@ class Doctor
         message: "#{orphans.size} hook launcher(s) on disk are not registered in HookRegistry",
         details: orphans.map { |h| "#{tilde(hooks_dir)}/#{h}" },
         fixable: true,
-        fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude (prunes stale launchers)"
+        fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude (prunes " \
+                  "stale launchers). The plastic- prefix is reserved for Plastic's own hooks: " \
+                  "if one of these is yours, rename it (for example to ~/.claude/hooks/" \
+                  "writing-style) and re-register it in settings.json before re-running."
       )
     end
 
@@ -271,7 +276,7 @@ class Doctor
 
         groups.any? do |group|
           group.is_a?(Hash) && group["hooks"].is_a?(Array) &&
-            group["hooks"].any? { |h| h["command"].to_s.include?("plastic-") }
+            group["hooks"].any? { |h| HookRegistry.claude_purge_command?(h["command"]) }
         end
       end
 
@@ -309,7 +314,7 @@ class Doctor
       live_plastic = (settings["hooks"] || {}).flat_map do |event, groups|
         Array(groups).flat_map do |g|
           next [] unless g.is_a?(Hash) && g["hooks"].is_a?(Array)
-          g["hooks"].map { |h| h["command"].to_s }.select { |c| c.include?("plastic-") }
+          g["hooks"].map { |h| h["command"].to_s }.select { |c| HookRegistry.claude_purge_command?(c) }
                     .map { |c| "#{event}: #{c}" }
         end
       end

package/scripts/lib/doctor_exclusions.rb

@@ -0,0 +1,93 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "rule_catalog"
+
+# DoctorExclusions - resolves, reads, and parses one store's per-store `doctor-exclusions`
+# table (intent 274): the record of knowingly-exempt (intent_id, rule) pairs that lets doctor
+# skip a finding it can never legitimately repair (219 D6 forbids inventing a disposition for
+# an unrepairable gap).
+#
+# Location (spec D6): sibling to that store's INDEX.md, resolved via `path_for` from the same
+# `store[:index]` Doctor#done_signal_stores already yields - zero new store-discovery logic.
+# Deliberately no `.md` extension: this is a config table, not a markdown document indexed by
+# QMD or walked by lifecycle machinery.
+#
+# Format (spec D6), `/etc/hosts`-shaped: `rule_name id id id`, one rule per line. Blank lines
+# and `#`-comment lines are ignored. Duplicate rule lines union their ids.
+#
+# Error contract (spec D5): fail open, loud in doctor. A missing file is the normal case -
+# zero exclusions, zero errors, identical to before this file existed. A malformed line never
+# excludes anything (fail milder than the bug: a typo must not silently suppress a real
+# regression) and contributes one error string naming its 1-based line number. An unreadable
+# file contributes one error and zero exclusions. This module NEVER raises.
+module DoctorExclusions
+  module_function
+
+  FILENAME = "doctor-exclusions"
+
+  # Same shape test/packaging_no_store_ids_test.rb already defines for a real Folgezettel id:
+  # digit-leading, then any mix of letters and digits.
+  FOLGEZETTEL_ID = /\A\d+[a-zA-Z0-9]*\z/
+
+  def path_for(index_path)
+    File.join(File.dirname(index_path), FILENAME)
+  end
+
+  # PURE. { rules: { rule_name => [ids] }, errors: [String] }. A line producing any error
+  # contributes nothing to rules; duplicate rule lines union their ids without an error.
+  #
+  # `scrub` (never raises) before any regex/String op: a hand-edited file can carry a byte
+  # sequence invalid in its declared encoding (e.g. a stray Latin-1 byte in a comment), and
+  # String#strip/split/=~ all raise Encoding::CompatibilityError on that input. Scrubbing
+  # replaces the invalid byte with U+FFFD and keeps this module's never-raises contract (D5)
+  # true for every input, not just well-formed UTF-8.
+  def parse(text)
+    rules = {}
+    errors = []
+
+    text.to_s.scrub.each_line.with_index(1) do |raw_line, n|
+      line = raw_line.strip
+      next if line.empty? || line.start_with?("#")
+
+      line = line.sub(/(?:\A|\s)#.*\z/, "").rstrip
+      tokens = line.split
+      rule = tokens.shift
+      line_errors = []
+
+      line_errors << "line #{n}: rule \"#{rule}\" lists no intent ids" if tokens.empty?
+      unless RuleCatalog.excludable_check?(rule)
+        line_errors << "line #{n}: unknown or non-excludable rule \"#{rule}\""
+      end
+      tokens.each do |tok|
+        line_errors << "line #{n}: \"#{tok}\" is not a Folgezettel intent id" unless tok =~ FOLGEZETTEL_ID
+      end
+
+      if line_errors.empty?
+        (rules[rule] ||= []).concat(tokens)
+        rules[rule].uniq!
+      else
+        errors.concat(line_errors)
+      end
+    end
+
+    { rules: rules, errors: errors }
+  end
+
+  # IO. `parse`'s shape plus `path:`. Never raises: a missing file is the normal case (zero
+  # exclusions, zero errors); an unreadable file (permission, is-a-directory, any
+  # SystemCallError) yields one error and zero exclusions.
+  def load(index_path)
+    path = path_for(index_path)
+    return { rules: {}, errors: [], path: path } unless File.exist?(path)
+
+    parse(File.read(path)).merge(path: path)
+  rescue SystemCallError => e
+    { rules: {}, errors: ["#{path}: unreadable (#{e.message})"], path: path }
+  end
+
+  # Rule names excluding `intent_id` in an already-`load`ed result. [] when none.
+  def rules_for(loaded, intent_id)
+    loaded[:rules].select { |_rule, ids| ids.include?(intent_id) }.keys
+  end
+end

package/scripts/lib/hook_registry.rb

@@ -186,6 +186,90 @@ module HookRegistry
           .uniq.sort.map { |name| "plastic-#{name}" }
   end
 
+  # Launchers the installer places in the agent's hooks dir that `events` does not
+  # register (intent 204): plastic-statusline is the settings["statusLine"] command.
+  # Defined here rather than in doctor_core so the installer's purge can recognise it
+  # without depending on the doctor; Doctor::CLAUDE_NON_HOOK_LAUNCHERS aliases it.
+  CLAUDE_NON_HOOK_LAUNCHERS = %w[plastic-statusline].freeze
+
+  # Hook names Plastic HAS registered and no longer does (intent 275). Purge-only:
+  # an old install still carries these entries in settings.json / hooks.json, and
+  # nothing else can tell us they were ever ours.
+  #
+  # MAINTENANCE DUTY: renaming or removing a hook from `events` means adding its old
+  # name here in the SAME change. Skip it and every existing install keeps a dead
+  # registration no update will ever clean up.
+  #
+  # Never fold these into claude_launcher_names: that method is what doctor's
+  # hooks_exist demands be present on disk, so a retired name there makes a correct
+  # install report missing launchers.
+  RETIRED_HOOK_NAMES = %w[
+    code-gate create-gate links-gate lock-gate savepoint-pre
+    qmd-search retrieval-gate model-instructions opus-manual
+  ].freeze
+
+  RETIRED_CLAUDE_LAUNCHERS = RETIRED_HOOK_NAMES.map { |n| "plastic-#{n}" }.freeze
+
+  # Filenames of Plastic's Codex dispatcher, current and retired. Codex hooks are
+  # not per-hook launcher files: every command is `"<dispatcher>" <name>`, so the
+  # dispatcher's own filename is what identifies an entry as ours.
+  CODEX_DISPATCHER_BASENAMES = %w[codex-hook].freeze
+
+  # Every launcher name the installer may purge from settings.json: what we register
+  # now, the non-hook launchers we place, and what we used to register.
+  def claude_purgeable_launcher_names
+    (claude_launcher_names + CLAUDE_NON_HOOK_LAUNCHERS + RETIRED_CLAUDE_LAUNCHERS).uniq.sort
+  end
+
+  # Current Codex hook names, from the same sources codex_hooks_json builds from.
+  def codex_hook_names
+    live = CODEX_LIVE_STATE_EVENTS.flat_map do |event|
+      events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+    (CODEX_PRE_HOOKS + CODEX_POST_HOOKS + CODEX_BASH_HOOKS + live).uniq.sort
+  end
+
+  def codex_purgeable_hook_names
+    (codex_hook_names + RETIRED_HOOK_NAMES).uniq.sort
+  end
+
+  # Is this settings.json hook command one of OURS? (intent 275)
+  #
+  # Ownership is registry membership, never a substring: the substring test this
+  # replaced deleted a user's own ~/.claude/hooks/plastic-writing-style hook on
+  # update. Tokenised rather than first-token-only because legacy entries take the
+  # form `ruby <path>/plastic-<name>.rb`, and those must still be purged.
+  def claude_purge_command?(cmd)
+    known = claude_purgeable_launcher_names
+    command_basenames(cmd).any? { |name| known.include?(name) }
+  end
+
+  # Is this ~/.codex/hooks.json command one of ours? Every Plastic Codex entry
+  # invokes our dispatcher by path (`"<plastic_home>/scripts/codex-hook" <name>`),
+  # so the dispatcher's filename identifies it. Basename EQUALITY, so a user's
+  # ~/bin/codex-hook-wrapper is not ours; the argument is not filtered on, because
+  # a command that already runs our dispatcher is ours whatever gate it names, and
+  # filtering would strand any name we forgot to retire.
+  #
+  # Tokenised the same way claude_purge_command? is (command_basenames), NOT a
+  # naive cmd.split.first: a first-token split breaks whenever plastic_home
+  # contains a space, since the shell-quoted dispatcher path then splits across
+  # multiple whitespace tokens and the true first token is only half the path.
+  # command_basenames strips quote characters per token, so whichever token
+  # carries the dispatcher's trailing `/codex-hook"` still resolves to the bare
+  # basename "codex-hook" after its trailing quote is stripped.
+  def codex_purge_command?(cmd)
+    command_basenames(cmd).any? { |name| CODEX_DISPATCHER_BASENAMES.include?(name) }
+  end
+
+  # Each whitespace-separated token reduced to a comparable launcher name:
+  # quotes stripped, directories dropped, a trailing .rb removed.
+  def command_basenames(cmd)
+    cmd.to_s.split(/\s+/).reject(&:empty?).map do |token|
+      File.basename(token.delete("\"'")).sub(/\.rb\z/, "")
+    end
+  end
+
   # The settings.json shape merge_claude_hooks expects: single-group events map
   # to a Hash, multi-group events to an Array (the merge loop handles both).
   def claude_settings_hooks(hook_dir:)

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/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