@zalom/plastic 1.12.0 → 1.14.0

package/scripts/maintenance-run

@@ -15,7 +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]
+#   maintenance-run --tool register-exclusions [--prune] [--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
@@ -77,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, rule: nil }
+           at: nil, skip_links: false, id: nil, rule: nil, prune: false }
   i = 0
   while i < argv.length
     case argv[i]
@@ -89,6 +89,7 @@ def parse_argv(argv)
     when "--at" then opts[:at] = argv[i += 1]
     when "--skip-links" then opts[:skip_links] = true
     when "--rule" then opts[:rule] = argv[i += 1]
+    when "--prune" then opts[:prune] = true
     else
       opts[:id] ||= argv[i] # positional id, restore-intent-v1 only
     end
@@ -311,12 +312,53 @@ end
 # 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)
+#
+# `prune:` (intent 280) reverses the direction: instead of adding newly-violating ids, it
+# removes rows that `DoctorExclusions.dead_rows` reports as suppressing nothing, through the
+# SAME walk, the SAME comment-preserving writer, and the SAME dry-run/--apply gate. `known_ids`
+# (post-review fix) is resolved against a direct scan of the store's own directory listing, never
+# against which ids the INDEX walk happened to visit - an id can have a real directory without
+# being listed in INDEX at all (a de-indexed "ghost"), and walk membership alone misclassified
+# that as :no_intent (deleted) even though the directory plainly still exists. `evaluated_ids` is
+# the narrower set the walk DOES visit; an id with a real directory the walk never evaluated
+# carries no evidence either way, so `dead_rows` leaves it out of its result entirely - never
+# called dead by the reporter, so `prune` never sees it as a pruning candidate in the first
+# place.
+#
+# The walk here only ever evaluates `savepoint_operational`'s own finding bucket
+# (`findings[:operational_gap]`), regardless of `--rule`: `run_register_exclusions` refuses
+# `--prune --rule <other>` outright (a second review fix) rather than silently computing
+# `found_ids` from an unrelated check and misreporting every row under `<other>` dead.
+#
+# Three classes of row are additionally held harmless before anything is written
+# (`protected_ids`), belt-and-suspenders on top of the `evaluated_ids` gate: an id whose dir was
+# skipped for a fresh delivery lock (D6 - the lock skip runs AFTER the id already lands in
+# `evaluated_ids`, but BEFORE it can ever reach `found_ids`, since findings are never computed
+# for it), an id whose intent has not reached a terminal state yet (D6a - savepoint_operational
+# only fires on a terminal intent, so the row has nothing to suppress YET), and an id with a real
+# directory that is not in `evaluated_ids` at all (on disk, unindexed - this last class never
+# actually reaches `held` in practice, since `dead_rows`'s own gate already excludes it; the
+# protection stays explicit anyway rather than relying solely on that gate). A rule left with
+# zero ids after pruning is dropped from the hash entirely (D7): `render_exclusions_file` would
+# otherwise write a bare `rule_name` line that `DoctorExclusions.parse` rejects as "lists no
+# intent ids".
+def run_register_exclusions(home, rule, store, apply, prune = false)
   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
+  # Review fix: the walk below only ever evaluates savepoint_operational's own finding bucket
+  # (`findings[:operational_gap]`), regardless of --rule. Passing --prune --rule <other> would
+  # compute `found_ids` from an entirely unrelated check and subtract it against <other>'s
+  # registered ids, misreporting every one of them dead. Unreachable in v1 (EXCLUDABLE_CHECKS
+  # carries exactly one key) but one catalog entry away, so refuse it explicitly rather than
+  # silently mis-pruning the day a second excludable check exists.
+  if prune && rule != "savepoint_operational"
+    abort_loud("--prune evaluates only savepoint_operational; #{rule.inspect} rows are left " \
+               "untouched (the walk this tool runs only ever checks that one rule's finding " \
+               "bucket, regardless of --rule)")
+  end
 
   doctor = Doctor.new(plastic_home: home)
   stores = doctor.done_signal_stores(store ? [store] : nil)
@@ -340,15 +382,45 @@ def run_register_exclusions(home, rule, store, apply)
     existing_text = File.exist?(existing[:path]) ? File.read(existing[:path]).scrub : nil
 
     found_ids = []
+    protected_ids = []
+
+    # `known_ids` (post-review fix): every id with a REAL DIRECTORY in this store, scanned
+    # directly from disk - not from the INDEX walk below. Mirrors doctor.rb's own fix: an id can
+    # have a directory on disk without being listed in INDEX (a de-indexed "ghost"), and the walk
+    # alone would never visit it, misclassifying that ghost as :no_intent (deleted) even though
+    # it plainly still exists.
+    # Shares doctor.store_intent_dirs (doctor.rb:159, intent 189's store-discovery helper)
+    # rather than reimplementing the same directory scan (review fix): one predicate for "what
+    # is an intent directory in this store", never two that could drift apart.
+    known_ids = if File.directory?(s[:store_dir])
+                  doctor.store_intent_dirs(s[:store_dir]).map { |e| e.split("--", 2).first }
+                else
+                  []
+                end
+    # `evaluated_ids`: the narrower set the walk below actually judges (INDEX-listed and on disk).
+    evaluated_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)
 
+      walked_id = dirname.split("--", 2).first
+      evaluated_ids << walked_id
+      # D6a: savepoint_operational only fires on a terminal intent, so a row naming a live
+      # non-terminal intent has nothing to suppress YET. Doctor reports it; prune leaves it.
+      protected_ids << walked_id unless (in_sections & ["Completed", "Abandoned"]).any?
+
       terminal = (in_sections & ["Completed", "Abandoned"]).any?
       next unless terminal
 
       if Lock.fresh?(dir)
         skip_lines << "#{s[:scope]}: #{dirname} skipped (fresh delivery lock)"
+        # Prune direction (intent 280 D6, post-review fix): the lock skip runs AFTER
+        # evaluated_ids already recorded this id (just above) but BEFORE findings are computed,
+        # so it never reaches `consumed` - dead_rows would read it as :no_finding (evaluated,
+        # nothing consumed) purely because we never checked. Hold it harmless via protected_ids
+        # regardless of what dead_rows would report.
+        protected_ids << walked_id
         next
       end
 
@@ -357,36 +429,74 @@ def run_register_exclusions(home, rule, store, apply)
         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?
+      found_ids << walked_id if findings[:operational_gap].any?
     end
 
+    # Post-review fix: an id with a real directory that INDEX never lists at all is walked by
+    # neither branch above, so its terminal state is unknowable here. PURE DEFENSE-IN-DEPTH:
+    # `dead_rows`'s own `evaluated_ids` gate already excludes such an id from `dead` entirely (it
+    # is neither :no_finding nor :no_intent - no evidence either way), so `held` below never
+    # actually contains one and this concat's protection never needs to fire. Unlike D6 (fresh
+    # lock) and D6a (not yet terminal), which DO reach `held` and print "kept (protected, still
+    # live)", an unindexed id is never named in that skip output - it was never a live pruning
+    # candidate to begin with.
+    protected_ids.concat(known_ids - evaluated_ids)
+
     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 }
+    if prune
+      # This tool calls done_signal_findings_for_dir with excluded_rules: [], so a registered id
+      # that still has a gap shows up in found_ids rather than in the :excluded bucket. found_ids
+      # IS the consumed set for this rule.
+      dead = DoctorExclusions.dead_rows(existing, consumed: { rule => found_ids }, known_ids: known_ids,
+                                          evaluated_ids: evaluated_ids)
+                             .select { |row| row[:rule] == rule }
+                             .map { |row| row[:id] }
+      held = dead & protected_ids # D6 (fresh lock) + D6a (not terminal) + on-disk-but-unindexed
+      held.each { |id| skip_lines << "#{s[:scope]}: #{id} kept (protected, still live)" }
+      dead -= held
+      next if dead.empty?
+
+      remaining = already - dead
+      merged_rules = existing[:rules].merge(rule => remaining.sort)
+      merged_rules.delete(rule) if remaining.empty? # D7: a bare rule line fails to reload
+      plan[s] = { content: render_exclusions_file(merged_rules, existing_text: existing_text),
+                  removed: dead.sort }
+    else
+      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
   end
 
   puts skip_lines.join("\n") unless skip_lines.empty?
 
   if plan.empty?
-    puts "maintenance-run: no new #{rule} violations to register."
+    puts(prune ? "maintenance-run: no dead #{rule} exclusion rows to prune."
+               : "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(", ")}"
+      puts(if prune
+             "maintenance-run: DRY RUN, #{s[:scope]} would prune #{info[:removed].size} " \
+             "dead row(s) under #{rule}: #{info[:removed].join(", ")}"
+           else
+             "maintenance-run: DRY RUN, #{s[:scope]} would register #{info[:added].size} " \
+             "id(s) under #{rule}: #{info[:added].join(", ")}"
+           end)
     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})"
+      repo_dir: home, branch_name: "maintenance/#{prune ? "prune" : "register"}-exclusions-#{stamp}",
+      commit_message: "chore: maintenance - #{prune ? "prune dead" : "register"} doctor exclusions (#{rule})"
     ) do
       plan.each { |s, info| File.write(DoctorExclusions.path_for(s[:index]), info[:content]) }
     end
@@ -414,7 +524,7 @@ def main(argv)
   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])
+    run_register_exclusions(opts[:plastic_home], opts[:rule], opts[:store], opts[:apply], opts[:prune])
   else
     abort_loud("unknown --tool #{opts[:tool].inspect} (expected project-links|rebuild-graph|" \
                "restore-intent-v1|rebuild-savepoint|register-exclusions)")

package/scripts/scaffold-intent

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

package/skills/conventions/SKILL.md

@@ -19,7 +19,7 @@ when the trigger in the second column applies to the work in front of you.
 | `references/knowledge-graph.md` | when creating, linking, curating, or indexing intents and you need the sources-vs-chain doctrine, the tiers of influence, the `## Links` projection, or branch-vs-root directory semantics |
 | `references/lifecycle-and-savepoints.md` | when running a lifecycle stage or a savepoint and you need the subagent report-home contract for how an insight reaches the intent |
 | `references/tiers-and-dispatch.md` | when sizing an intent, choosing agent models, routing to the advisor, or writing an auto-mode human report |
-| `references/gates-and-enforcement.md` | when a transition gate blocks you, or before using an audited escape, for the gate mechanics and the logging contract, or when naming, registering, or retiring a hook |
+| `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 or skill |
 | `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,14 +2,19 @@
 
 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.
+#### Hook and skill naming and ownership
+
+The `plastic-` prefix is reserved for both surfaces: hooks `HookRegistry` registers and skills
+Plastic ships. A user-owned hook or skill 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 reports every violation it can find. On disk,
+`hooks_no_orphans` reports an unregistered `plastic-*` launcher file the registry does not know.
+In the live config, `hooks_entries_owned` (Claude) and `codex_hooks_entries_owned` (Codex)
+report a config entry that is neither a current registration nor recognizably ours, and,
+separately, a current registration whose launcher file is missing from disk. For skills,
+`stray_skills` reports a `plastic-*` skill directory the manifest does not track. 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
 

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

@@ -190,6 +190,20 @@ immutable forbids outright. The receipt is instead the scoped git commit
 durable, diffable record - not a missing safeguard, a deliberate substitution for a receipt
 shape that would otherwise require an illegal write.
 
+`--prune` (intent 280) reverses the same tool's direction under the identical carve-out: instead
+of adding newly-violating ids, it removes rows that suppress nothing this run (the intent's gap
+got repaired, the id was mistyped, or the intent directory is gone), computed via the same
+`DoctorExclusions.dead_rows` predicate doctor itself reports from, so the reporter and the
+remover can never disagree about what a dead row is. Same dry-run-by-default, same `--apply`
+gate, same comment-preserving writer, same one scoped commit, same no-`revisions.md`-entry rule -
+this direction still modifies no intent directory, only the store-level table. It holds back two
+kinds of row before writing even when they read as dead: an id whose intent dir carries a fresh
+delivery lock (the lock skip would otherwise leave it out of the walk entirely and misclassify
+it), and an id whose intent has not reached a terminal state yet (`savepoint_operational` only
+fires on a terminal intent, so the row has nothing to suppress *yet*). Both are named in the
+output as kept, never silently dropped, and a rule left with zero ids after pruning is removed
+from the file rather than written as a bare `rule_name` line the loader would reject.
+
 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.

package/skills/doctor/SKILL.md

@@ -218,6 +218,12 @@ folds in the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/do
 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.
 
+**Both surfaces, one line.** A registration is honored by the store-wide `savepoint_operational`
+check and by the per-intent `doctor.rb --intent <id>` run, which reports the same missing
+`savepoint.md` under the check name `intent_savepoint_truthful`. Register the id once. The
+per-intent run honors it only for an intent that is terminal in `INDEX.md`, and never suppresses
+a phantom-savepoint-line finding.
+
 **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.
 
@@ -233,6 +239,14 @@ without writing anything. Review the output, then re-run with `--apply` to write
 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.
 
+**Dead-row notice.** A registered row can go dead (gap repaired, id mistyped, or the intent
+directory gone). When any row is dead, the message adds a second suffix next to the exclusion
+count naming the count, the file, and the prune command - purely informational, status and exit
+code unchanged. Prune it the same way, dry-run first: register-exclusions --prune [--apply]. It
+removes exactly the dead rows through the same writer and commit, but holds back an id whose
+intent dir carries a fresh lock or has not gone terminal yet (nothing to suppress there yet),
+naming both as kept.
+
 ## 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/skill-creating/SKILL.md

@@ -40,6 +40,9 @@ routes each authoring task to the reference that holds the depth.
   them (use commas, periods, parentheses, colons). Existing internal files and the
   sanctioned template emissions (templates/index.md's INDEX line shape) are not
   violations.
+- The `plastic-` prefix is reserved for skills and hooks Plastic itself ships. A skill
+  authored outside Plastic's own tree takes a different name; doctor's ownership checks
+  and the installer's purge both key off the prefix.
 
 ## Route the authoring task to its reference
 

package/skills/skill-creating/references/skills.md

@@ -58,6 +58,9 @@ Rules [A5]:
 5. Must not contain `anthropic` or `claude`.
 6. Prefer the gerund form, which reads as a capability (`processing-pdfs`, `creating-skills`,
    not `pdf-tool`).
+7. Never start with `plastic-`. That prefix is reserved for skills and hooks Plastic itself
+   ships; doctor's ownership checks (`stray_skills`) and the installer's purge both key off it,
+   so a user-authored skill carrying it reads as squatting on Plastic's own namespace.
 
 ## The `description` field (triggering)