@zalom/plastic 1.10.0 → 1.12.0

package/README.md

@@ -139,7 +139,7 @@ Walk this once in
 | Intent | `plastic-continuing`, `plastic-intent-creating`, `plastic-intent-starting`, `plastic-intent-brainstorming`, `plastic-intent-grilling`, `plastic-intent-speccing`, `plastic-intent-planning`, `plastic-intent-executing`, `plastic-intent-ending`, `plastic-intent-continuing`, `plastic-intent-researching` |
 | Project and delivery | `plastic-project-creating`, `plastic-project-continuing`, `plastic-roadmap`, `plastic-roadmap-continuing`, `plastic-releasing` |
 | Skill | `plastic-skill-creating`, `plastic-skill-evaluating` |
-| Product | `plastic-install`, `plastic-update`, `plastic-uninstall`, `plastic-rollback`, `plastic-doctor`, `plastic-humanizer` |
+| Product | `plastic-install`, `plastic-update`, `plastic-uninstall`, `plastic-rollback`, `plastic-doctor` |
 
 See [`docs/guides/index.md`](docs/guides/index.md) for task-oriented walkthroughs.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.10.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/auto/references/human-report-contract.md

@@ -57,11 +57,9 @@ CONSUMES the intent 74 report to WRITE the human briefing defined here. The two
 
 ## Brevity: point, don't repeat
 
-Surface rules (no em-dashes, plain words, no filler openers, and so on) are owned by the
-shipped `plastic-humanizer` skill and the always-on plain-language layer. This contract does not
-re-list that catalog. It restates only the hard bans as one line: no em-dashes, no "not X but Y",
-no rule of three, no hype words, no sycophancy, no over-bolding. Apply `plastic-humanizer` and the
-always-on layer for everything else.
+Surface rules are owned by the `writing-style` skill. This contract does not restate them, in full
+or in summary. It defines the report's shape only: what to say, in what order, and when to stop.
+Apply the `writing-style` skill for the wording.
 
 ## Emission: guided vs auto
 

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/conventions/references/tiers-and-dispatch.md

@@ -130,6 +130,6 @@ succession at a glance (last line = where we are).
 In auto mode the orchestrator briefs the human at every lifecycle stage boundary in a fixed,
 impact-first shape (the EM-to-CTO report contract): State, then Risk, then Call. This is the
 depth at M and L; at S the briefing fires once, at How. It leads with
-what changed and why it matters, names one risk, and leaves the decision to the human. Separately,
-the `plastic-humanizer` skill cleans authored prose (specs, outcomes, READMEs, release notes) of
-AI tells and slop; it is for documents, not for every reply.
+what changed and why it matters, names one risk, and leaves the decision to the human. Wording
+rules for the briefing, and for authored prose such as specs, outcomes, READMEs, and release
+notes, are owned by the `writing-style` skill, not by this contract.

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

package/skills/humanizer/SKILL.md

@@ -1,40 +0,0 @@
----
-name: plastic-humanizer
-description: Use to clean authored prose so it reads human and clutter-free. Removes AI tells and slop from a document, spec, outcome, README, report, or release note. Use when the user says "humanize", "de-slop", "remove the AI tells", or "clean up the wording". For documents, not for every chat reply, and not for code.
-user-invocable: true
----
-
-# Humanizer
-
-Make writing read like a person wrote it: plain, direct, low-clutter. Run this as a pass over authored prose (specs, outcomes, README, reports). Do not run it on code or on every chat turn.
-
-## Lead (house style)
-Reframe your answers and any questions you have for me like you are speaking to a well-educated non-English native person. Reduce slang, and rarely used words and terms in the general communication. And cut all the fancy words from explanations. Technical terms and concepts are fine and need no gloss.
-
-## Voice
-Answer like a busy bartender or a senior support engineer who has seen almost every ticket. Help fast, give the fix first, earn the tip.
-
-## Job 1 - remove these surface tells
-1. Em-dashes and en-dashes - use a comma or a full stop.
-2. "Not X but Y" (and "it's not just X, it's Y").
-3. Rule of three - three items only for rhythm.
-4. Hype / AI words - delve, robust, comprehensive, seamless, leverage, crucial, unlock, landscape.
-5. Filler openers / signposting - "It's worth noting", "It's important to", "Let's dive in".
-6. Hedging pile-up - might, could, perhaps, generally, when not needed.
-7. Sycophancy - "Great question", "You're absolutely right".
-8. Over-bolding - bold only what carries weight.
-
-## Job 2 - fix the structure
-- Lead with the one main point.
-- Cut sentences that only restate.
-- Pick concrete words over abstract ones.
-- Match the user's voice when samples of their writing exist.
-
-## Process
-Write, check once against the rules above, then send. On documents, run this pass last.
-
-## Length
-Keep it short. If a sentence does not help the reader, cut it.
-
-## More
-For before/after examples, read `references/examples.md`. To make the house style always-on in chat, see `references/always-on-snippet.md`. The full 33-pattern catalog and the research behind this skill live in intent 92's `resources/`. They are background and are not loaded here.

package/skills/humanizer/evals/evals.json

@@ -1,70 +0,0 @@
-{
-  "skill_name": "plastic-humanizer",
-  "notes": "Intent 92. Cleans authored prose: removes 8 surface tells and applies structural levers (one point, cut restatement, concrete words, match voice). Triggers on document-cleanup asks, not on code. Runner is intent 76; assertions are human for now.",
-  "evals": [
-    {
-      "id": 1,
-      "scope": "trigger",
-      "set": "validation",
-      "prompt": "Humanize this README - it reads like AI wrote it.",
-      "expected_output": "Selects plastic-humanizer and runs the cleanup pass over the document.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "plastic-humanizer is selected for a document-cleanup request",
-          "observed": "description triggers on 'humanize' / 'reads like AI' for a document",
-          "result": "pass"
-        }
-      ]
-    },
-    {
-      "id": 2,
-      "scope": "trigger",
-      "set": "validation",
-      "prompt": "Clean up the wording in this spec.",
-      "expected_output": "Selects plastic-humanizer and cleans the spec prose.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "plastic-humanizer is selected for 'clean up the wording'",
-          "observed": "description triggers on 'clean up the wording'",
-          "result": "pass"
-        }
-      ]
-    },
-    {
-      "id": 3,
-      "scope": "non-trigger",
-      "set": "validation",
-      "prompt": "Fix the failing test in foo.rb.",
-      "expected_output": "Does NOT select plastic-humanizer; this is a code task, not prose cleanup.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "plastic-humanizer is not selected for a code task",
-          "observed": "description scopes the skill to documents, not code",
-          "result": "pass"
-        }
-      ]
-    },
-    {
-      "id": 4,
-      "scope": "output",
-      "set": "validation",
-      "prompt": "Given a slop sample: 'It's worth noting that this is not just a fix, but a comprehensive, robust, and seamless improvement that will unlock real value.' Humanize it.",
-      "expected_output": "Cleaned text has no em-dashes and none of the 8 tells, leads with one point, and drops restatement. For example: 'This fix makes X faster.'",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "output drops the 8 tells, leads with one point, cuts restatement",
-          "observed": "no em-dashes; no 'not X but Y'; no rule-of-three; no hype words; no filler opener; one load-bearing point",
-          "result": "pass"
-        }
-      ]
-    }
-  ]
-}

package/skills/humanizer/references/always-on-snippet.md

@@ -1,9 +0,0 @@
-# Always-on chat style (copy-paste)
-
-Paste this into your global `CLAUDE.md` (applies to all projects) or a project `AGENTS.md` (one project). It keeps the chat style on at near-zero cost. The full cleanup for documents is the `plastic-humanizer` skill.
-
-```
-Reframe your answers and any questions like you are speaking to a well-educated person who is not a native English speaker. Reduce slang and rarely used words. Cut fancy words from explanations. Technical terms and concepts are fine.
-
-Answer like a busy bartender or a senior support engineer who has seen almost every ticket: help fast, give the fix first, earn the tip.
-```

package/skills/humanizer/references/examples.md

@@ -1,48 +0,0 @@
-# Examples - before and after
-
-Each pair shows a tell or a slop pattern, then the fix.
-
-## 1. Em-dash
-Before: The release is ready - we just need sign-off.
-After: The release is ready. We just need sign-off.
-Why: Use a full stop or comma, not an em-dash.
-
-## 2. "Not X but Y"
-Before: This is not just a config change, it's a rethink of the flow.
-After: This change reworks the flow.
-Why: State the point directly.
-
-## 3. Rule of three
-Before: The tool is fast, robust, and powerful.
-After: The tool is fast.
-Why: Drop the list-for-rhythm; keep the claim you can back.
-
-## 4. Hype / AI word
-Before: We leverage a comprehensive caching layer to unlock performance.
-After: We cache results to make it faster.
-Why: Plain verbs and nouns.
-
-## 5. Filler opener / signposting
-Before: It's worth noting that the cache expires after five minutes.
-After: The cache expires after five minutes.
-Why: Say the thing; skip the runway.
-
-## 6. Hedging pile-up
-Before: This might possibly help reduce cost in some cases, generally.
-After: This reduces cost.
-Why: One clear claim. Add a caveat only if it is real.
-
-## 7. Sycophancy
-Before: Great question! That's a really insightful point. Here's the answer.
-After: Here's the answer.
-Why: Drop the praise; answer.
-
-## 8. Structural fix (the mush)
-Before: There are several important considerations to keep in mind when thinking about how best to approach the broad and multifaceted topic of caching, each of which carries its own trade-offs.
-After: Cache reads, not writes. Reads repeat; writes do not.
-Why: One load-bearing point. Cut the restatement and the abstract throat-clearing.
-
-## 9. Over-bolding
-Before: **Note:** the cache **expires** after **five minutes**, so **always** check it.
-After: The cache expires after five minutes, so check it first.
-Why: Bold nothing here; the sentence carries itself.