@zalom/plastic 1.4.1 → 1.5.0

package/PLASTIC-reference.md

@@ -22,6 +22,8 @@ Violation tags (starter set, free-text tags allowed):
 - `broken-chain`: a chain frontmatter edge to an intent that no longer exists
 - `broken-source`: a sources frontmatter edge to an intent that no longer exists
 - `misplaced-content`: content that belongs in a different artifact or section
+- `links-projection`: a tool-authored `## Links` regeneration (project-links; intent 197)
+- `graph-rebuild`: a tool-authored sources/chain frontmatter rebuild (rebuild-graph; intent 197)
 
 ## Two Processes
 

package/PLASTIC.md

@@ -565,26 +565,38 @@ open (the write proceeds, the claim yields) and the condition is surfaced in
 lock. See `plastic-lock claim`/`release-claim` and `docs/internals.md` for the
 full mechanism.
 
-Two locks share this schema (the two-lock doctrine): `delivery.lock` (exclusive, one owner
-plus delegates) and the future `maintenance.lock` (short TTL, structural move-and-record
-only). They are mutually exclusive in either direction; maintenance is allowed at any
-lifecycle stage provided no delivery lock is held. Intent 108 ships the delivery lock and
-the mutual-exclusion seam; the maintenance lock implementation follows intent 93 in a
-chained intent.
+There is exactly one lock in Plastic: `delivery.lock` (exclusive, one owner plus delegates),
+shipped by intent 108. An earlier two-lock doctrine proposed a second `maintenance.lock`
+(short TTL, structural move-and-record only); intent 112 built it in full and was then
+abandoned before merge on a design pivot, so nothing from it ever shipped (`lock.rb`'s
+`TYPES` seam is the only trace left). Intent 197 rejects the second lock outright rather than
+reviving it: a lock held by a maintenance session could be mistaken by a resuming session
+for an active delivery. Maintenance instead DETECTS `delivery.lock`'s freshness
+(`Lock.fresh?`) and defers when fresh; it never acquires any lock of its own and leaves none
+behind. See "WORK vs MAINTENANCE" below for the full doctrine.
 
 Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
 for that intent happen only inside it. Plastic provisions the worktree deterministically: it
 resolves the project repo from `projects.yml` and runs `git -C <repo> worktree add`, so
-isolation never depends on the current working directory. There are two worktrees per project
-intent: a code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch `plastic/{id}--{slug}`)
-and a store worktree at `<plastic_home>/.worktrees/{id}--{slug}` (branch
-`plastic-store/{id}--{slug}`), so lifecycle-doc commits and code commits move as one unit.
+isolation never depends on the current working directory. There is one worktree per project
+intent, the code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch
+`plastic/{id}--{slug}`).
+
+Plastic does not provision a second worktree for lifecycle-doc writes. Two things cover that
+need instead. First, the harness's own native worktree: Claude Code manages its own code
+worktree at `<repo>/.claude/worktrees/{name}`, and Codex manages its own at
+`$CODEX_HOME/worktrees` (default `~/.codex/worktrees`); both exist on their own, independent of
+anything Plastic provisions. Second, intent 197's branch-from-main plus scoped commit, which
+gives store writes their own write safety without a dedicated worktree. Plastic tried a second,
+dedicated store worktree at `<plastic_home>/.worktrees/{id}--{slug}` first; agents never wrote
+into it, because every delivering agent writes lifecycle docs straight to the main store
+checkout, so intent 178 retired the store worktree in favor of the two mechanisms above.
 
 Provisioning fails open for intents that touch no project code (pure research or decision
 intents in the global store, or a non-git repo): those get the lock only, and the worktree
 block stays unprovisioned. The fail-open path is always logged, never silent.
 
-Cleanup is part of Done: the End tail merges the branch, then removes both worktrees. Never leave
+Cleanup is part of Done: the End tail merges the branch, then removes the worktree. Never leave
 an orphaned worktree behind, and clear a stale worktree reference with `git worktree prune`.
 
 ### Intent delivery, station by station
@@ -600,7 +612,7 @@ each station.
 | How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md, checklist.md, and a real action file all exist | gate-check requires spec.md before plan.md, and plan.md plus a real actions/ACTION_N.md before checklist.md | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
 | Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock; bash, interpreter, and MCP writes gated the same way | code-gate, worktree-gate, bash-gate, lock-gate | checklist boxes; savepoint milestones |
 | End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the bridge is purge-eligible, and the QMD reindex runs LAST (after purge) | gate-check blocks outcome.md while checklist items are unchecked | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
-| Maintenance (any stage) | `revisions.md` move-and-record entries | future `maintenance.lock` (short TTL), mutually exclusive with `delivery.lock` in either direction; 108 ships the schema seam only, the implementation follows intent 93 in a chained intent | acquisition refuses while the other lock type is fresh; a terminal intent with no lock held is read-only | dated, rule-tagged `revisions.md` entry; savepoint untouched |
+| Maintenance (Future, Terminal, or Active-with-a-stale-or-no-lock) | `revisions.md` move-and-record entries | detects (never acquires) `delivery.lock`; defers and reports while the target's lock is FRESH (`Lock.fresh?`); a stale or absent lock is not-active, maintenance proceeds | none enforced by any gate; the maintenance tool or skill itself checks `Lock.fresh?` (see WORK vs MAINTENANCE below) | append-only, rule-tagged `revisions.md` entry written in the same operation as the change, or the change is refused; lands via a fresh branch off store main merged back as one closed op, never `git add -A` |
 
 ### What "intent done" means (intent 93)
 
@@ -639,26 +651,113 @@ tail; `doctor` surfaces this as a "stalled completion" (terminal in INDEX but th
 still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
 a done intent is never moved back to `## Active`.
 
-Terminal immutability (the contract intent 112 enforces): a terminal directory is writable
-ONLY while a lock is held. The delivery lock covers the completing session's End tail up to
-`Lock.release`; the maintenance lock covers sanctioned structural move-and-record edits
-after. Terminal with no lock held is frozen. There are only two locks in the system,
-delivery and maintenance (108 D11). This governs WRITES only: reads of a terminal intent are
-always allowed and unbounded (curator reindex, dashboards, and future intents that reference
-its id or chain), so a done intent stays fully readable forever. Intent 93 states this rule;
-intent 112 builds the gate that enforces it.
+### WORK vs MAINTENANCE (intent 197)
+
+Plastic separates two different things an earlier doctrine blurred under one word,
+"immutable." WORK is the delivered CONTENT an intent produced: the code and project files a
+delivery changed, the research it recorded, the outcome it wrote. Once the intent is terminal
+(Completed or Abandoned), that content is immutable - the only way to change it is another
+intent that continues or reverts it. Editing a Done intent's own artifacts so it looks like it
+delivered something different, or that parts are missing, is forbidden (the book analogy:
+never rewrite the text on the pages of an old, valuable book).
+
+MAINTENANCE is everything else: structure, the sources/chain graph, a section that does not
+belong in the file, formatting, and any store-wide operational change (a new Plastic version
+adding or removing a frontmatter field across every intent). Maintenance is not immutable and
+needs no owner gate to run, on the one condition below (recording is universal). The
+decidable test is CONTENT vs METADATA, not "meaning vs structure": a graph edit is structure
+even when it is also, in a loose sense, about lineage, because it does not change what the
+intent delivered. Precedent: plastic intent 124's own `revisions.md` v1 dropped a dead chain
+edge to a non-existent `124b` (`[rule: broken-chain]`), and v2 added a missing required
+reciprocity edge to `131` (`[rule: misplaced-content]`), both ordinary maintenance, not
+owner-gated exceptions. Allowed maintenance: (a) a frontmatter chain/sources edge that points
+to a non-existent or wrong intent, or a missing required edge; (b) an extra non-convention
+section in the intent file, removed and moved into `revisions.md`; (c) a store-wide
+operational change from a new Plastic version, applied to every intent; (d) any other
+structural or operational tidy. Forbidden: anything that alters what the work delivered.
+
+The residual guard on every graph edit: it must move TOWARD ground truth (drop a dangling or
+false edge, add a reciprocity-forced or documented-real one) and must never invent a
+relationship - "might be related" is never a valid `[rule:]` reason. This is already implied
+by the mandatory `[rule: tag]` on every `revisions.md` entry; no additional per-edit owner
+gate is needed for an ordinary graph fix of this kind.
+
+Maintenance normally needs no intent and no roadmap at all; it runs through the maintenance
+tools and skills and records itself. The one exception: a batch touching more than about 5
+different intents at once must stay rare, and is always an owner decision - the agent asks
+first and shows the diff before proceeding. This exception governs rare cross-intent sweeps;
+it does not apply to an ordinary single-intent graph repair.
+
+Maintenance target-state eligibility, by the intent's own lifecycle state: a Future intent,
+yes; a Terminal (Completed or Abandoned) intent, yes; an Active intent mid-delivery, WAIT. The
+wait is keyed on whether the target currently holds a FRESH `delivery.lock` (`Lock.fresh?`),
+never on INDEX `## Active` membership - `end-intent` releases the lock only after the INDEX
+move and its commit tail finish, so keying on Active membership would miss that tail window
+and let maintenance race a live completion. A STALE lock is not maintenance's problem to
+resolve; it is treated as not-active, and maintenance proceeds rather than waiting
+indefinitely behind a dead session.
+
+There is exactly one lock in the system (see the two-lock correction above): `delivery.lock`,
+meaning an active agent is delivering that intent. Maintenance DETECTS this lock and NEVER
+ACQUIRES it, even transiently, because a maintenance-held lock could be mistaken by a resuming
+or continuation session for an active delivery. Maintenance leaves no lock behind: there is
+nothing to clean up afterward, and no ambiguity about who, if anyone, holds the one lock.
+`bridge.rb:1195`'s `lock_gate_decision` already allows any write once an intent is not in
+INDEX `## Active` - there is no enforced freeze gate in the codebase today, and there never
+was one that shipped (see the corrected history below).
+
+Stranding and clobbering are avoided by construction, not by a second lock: a maintenance
+action creates a fresh branch from the CURRENT state of store main, applies only its own
+scoped changes, and merges that branch back to main as part of the SAME closed operation.
+Nothing strands on an unmerged branch; two concurrent maintenance runs reconcile as ordinary
+merge conflicts on main, never silent loss. This is lighter than intent 178's full per-session
+delivery worktrees (178 stays about the agent write paths for delivery); maintenance only
+needs branch-from-main plus scoped merge-back (`scripts/lib/maintenance_git.rb`,
+`scripts/maintenance-run`).
+
+No commit anywhere, store or project repo, uses `git add -A`; every maintenance and delivery
+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
+`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
+`scripts/restore-intent-v1` each write this receipt in the SAME write as the structural
+change, or refuse to proceed without one (`scripts/lib/revisions_writer.rb`); the intent
+curator (`agents/plastic-intent-curator.md`) holds itself to the identical rule by hand.
+
+Doctor stays a detector: core and full checks, every installed agent, both global and project
+stores. It gains no write path of its own. The "Fix all" prompt
+(`skills/doctor/SKILL.md`) is a ROUTER: for each fixable finding it dispatches to the tool
+that already owns that class of repair (`project-links`, `rebuild-graph`,
+`restore-intent-v1`, or the curator, via `scripts/maintenance-run` where applicable), and
+those tools perform the mutation and write the `revisions.md` receipt - never doctor itself.
+
+Corrected history (D18): an earlier version of this section described a terminal-immutability
+gate "intent 112 enforces" and a two-lock model. Intent 112 built that gate in full and was
+then ABANDONED before merge on a design pivot; nothing from it ever shipped. `bridge.rb:1195`
+confirms no such gate runs today: a write to a terminal intent is allowed unconditionally once
+the intent leaves INDEX `## Active`. The deadlock that stopped intents 189, 192, and 195 from
+repairing three live `graph_links_projection` violations was self-imposed discipline (agents
+and the owner both treating undocumented doctrine as a real gate), not a technical one. This
+section is the corrected doctrine; intent 112's own history stays in INDEX as an abandoned,
+superseded design.
 
 Restore-to-v1 (the owner rule that a completed intent is immutable: a late ruling goes to a
 new `--parent` branch intent, and the completed intent is restored to v1) is performed ONLY by
-`scripts/restore-intent-v1`, run under the maintenance lock. Its prose (the intent narrative,
-checklist.md, outcome.md, spec.md, plan.md) is immutable and reverts to v1; its frontmatter
-graph (`sources`/`chain`) is metadata about OTHER intents, not content of this one, and is
-APPEND-ONLY: it is preserved as the union of the v1 snapshot and the current snapshot, never
-subtracted. A hand-run whole-file `git checkout`/revert of a completed intent is FORBIDDEN,
-because it cannot distinguish prose from graph metadata and silently destroys backlinks written
-after v1 (proven on intent 124: a legitimately accrued chain edge was destroyed by a hand-run
-restore and went undetected for a week). This governs the restore mechanism only; it does not
-loosen terminal immutability itself.
+`scripts/restore-intent-v1`. Its prose (the intent narrative, `checklist.md`, `outcome.md`,
+`spec.md`, `plan.md`) is immutable and reverts to v1; its frontmatter graph
+(`sources`/`chain`) is metadata about OTHER intents, not content of this one, and is
+APPEND-ONLY: preserved as the union of the v1 snapshot and the current snapshot, never
+subtracted. It writes its own `revisions.md` receipt in the same run. A hand-run whole-file
+`git checkout`/revert of a completed intent is FORBIDDEN, because it cannot distinguish prose
+from graph metadata and silently destroys backlinks written after v1 (proven on intent 124: a
+legitimately accrued chain edge was destroyed by a hand-run restore and went undetected for a
+week).
 
 Fail-safe lock doctrine (the contract intent 111 implements): the lock system never traps a
 session or burns credits. When a gate cannot verify lock integrity it fails open, degrading
@@ -674,5 +773,7 @@ plus `disposition` header at both terminals, the End tail with the reindex moved
 `done_signals` doctor check (three-signal agreement plus stalled-completion detection), and
 the lock-bounded post-done window with its keep-guard test. Intent 111 owns the lock
 liveness surface, the lock-issue message, orchestrator auto-repair, and the fail-open
-behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
-fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
+behavior itself. Intent 112 attempted a maintenance lock and an immutability gate; it was
+abandoned before merge and superseded by intent 197's WORK vs MAINTENANCE doctrine
+(detect-only lock, branch-and-merge, tool-enforced `revisions.md`). Intent 4a1b1 owns deep
+agent stuck-detection and is not superseded.

package/agents/plastic-intent-curator.md

@@ -27,8 +27,16 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 5. On a terminal-state transition (Completed OR Abandoned), do these things:
    a. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
    b. Call `plastic-intent-ending` for the terminal-transition close (INDEX move, savepoint `Done` bookend, store commit, disarm, and the QMD reindex last): `ruby ~/.plastic/scripts/end-intent --store <store> --id <id> --disposition delivered|abandoned`, then follow that skill's own disarm and reindex steps. Never restate the INDEX/savepoint/reindex one-liners here.
-6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
-7. Report what you changed
+6. Structural maintenance is move-and-record, and it is NEVER done without its receipt: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`) IN THE SAME PASS as the edit. If you cannot write `revisions.md` for any reason (permissions, a read-only path), you MUST NOT make the structural edit either - report the blocker instead of leaving an unrecorded change (this mirrors the tool-side rule: project-links, rebuild-graph, and restore-intent-v1 refuse rather than write a change with no receipt; you hold yourself to the same rule by hand). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md. A graph edit must move TOWARD ground truth (drop a dangling/false edge, add a reciprocity-forced or documented-real one) and must NEVER invent a relationship - "might be related" is never a valid `[rule:]` reason (PLASTIC.md > WORK vs MAINTENANCE).
+7. Before performing structural maintenance on ANY intent that is NOT the one your own session is currently delivering under its own held delivery lock, you must:
+   a. Check the target's lock freshness: `ruby ~/.plastic/scripts/plastic-lock status --intent-dir <target-intent-dir>` and read the `lock_fresh` field of its JSON output. If `true`, DEFER: make no edit to that intent, and report it as skipped (an active delivery is in progress). This is DETECT-ONLY - you never acquire, create, or hold any lock of your own for maintenance (PLASTIC.md > WORK vs MAINTENANCE; there is exactly one lock in Plastic, the delivery lock).
+   b. Require a clean store working tree before starting: `git -C ~/.plastic status --porcelain` (or the project store's own root, if not global) must be empty. If it is not, STOP and report the dirty paths rather than risk sweeping an unrelated concurrent change into your own commit; do not proceed until the tree is clean.
+   c. Create a fresh branch from the current tip of that repo's main: `git -C <repo-root> checkout -b maintenance/curator-<UTC-timestamp> main`.
+   d. Make the scoped edit plus its `revisions.md` receipt (step 6 above), touching nothing else.
+   e. Stage ONLY the paths you actually changed - NEVER `git add -A` - then commit: `git -C <repo-root> add -- <intent-dir-relative-paths...> && git -C <repo-root> commit -m "..."`.
+   f. Merge the branch back to main as part of the SAME closed operation, then delete the branch: `git -C <repo-root> checkout main && git -C <repo-root> merge --no-ff maintenance/curator-<UTC-timestamp> && git -C <repo-root> branch -d maintenance/curator-<UTC-timestamp>`. Never leave the change stranded on an unmerged branch.
+   This entire step 7 does not apply when you are running as part of your OWN session's normal end-of-delivery close (the existing steps 4-5 above, which already run inside that session's own held lock and are committed by `end-intent`'s own scoped `store_commit`, not by this step).
+8. Report what you changed
 
 ## Constraints
 

package/package.json

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

package/scripts/doctor.rb

@@ -52,18 +52,14 @@ class Doctor
   # never drift.
   LEGACY_BOOKEND_AMNESTY = LegacyBookendAmnesty::LIST
 
-  CLAUDE_HOOK_SCRIPTS = %w[
-    plastic-session-start
-    plastic-check-update
-    plastic-savepoint
-    plastic-gate-check
-    plastic-continue
-    plastic-future-intent-check
-    plastic-qmd-search
-  ].freeze
-
   CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit].freeze
 
+  # Launchers the installer places in the agent's hooks dir that are NOT hooks
+  # (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
+
   REQUIRED_SCRIPTS = %w[
     folgezettel-id
     read-config
@@ -815,7 +811,11 @@ class Doctor
       "it PRESERVES any line unbacked by frontmatter that still resolves to a real intent " \
       "(reported as an orphan candidate, never silently deleted); add the missing " \
       "sources/chain edge if the relationship is real, or pass --drop-unbacked-links to " \
-      "delete an orphan candidate deliberately."
+      "delete an orphan candidate deliberately. Prefer `ruby scripts/maintenance-run --tool " \
+      "project-links --intent <id> --apply` over running project-links directly: it detects " \
+      "(never acquires) the target's delivery lock, requires a clean store working tree, and " \
+      "commits the scoped change plus its revisions.md receipt as one merged operation " \
+      "(PLASTIC.md > WORK vs MAINTENANCE)."
     )
   end
 
@@ -1003,13 +1003,17 @@ class Doctor
     checks = []
     hooks_dir = File.join(agent_dir, "hooks")
 
+    # Derived from HookRegistry.events (intent 204), not a hand-kept list, so
+    # every registered hook (all 15, including the enforcement gates) is checked.
+    expected_launchers = HookRegistry.claude_launcher_names
+
     # hooks_exist
-    missing_hooks = CLAUDE_HOOK_SCRIPTS.reject { |h| File.exist?(File.join(hooks_dir, h)) }
+    missing_hooks = expected_launchers.reject { |h| File.exist?(File.join(hooks_dir, h)) }
 
     if missing_hooks.empty?
       checks << check(
         category: "agent_registration", name: "hooks_exist", status: "pass",
-        message: "All #{CLAUDE_HOOK_SCRIPTS.size} expected hook scripts exist"
+        message: "All #{expected_launchers.size} expected hook scripts exist"
       )
     else
       checks << check(
@@ -1021,7 +1025,7 @@ class Doctor
     end
 
     # hooks_executable
-    existing_hooks = CLAUDE_HOOK_SCRIPTS
+    existing_hooks = expected_launchers
       .map { |h| File.join(hooks_dir, h) }
       .select { |p| File.exist?(p) }
 
@@ -1041,6 +1045,29 @@ class Doctor
       )
     end
 
+    # hooks_no_orphans: the mirror of hooks_exist. A plastic-* launcher on disk
+    # that HookRegistry does not know about is dead code the next reader would
+    # trust as live (the same drift class as a missing launcher, just facing
+    # the other way). plastic-statusline is a legitimate non-hook installer
+    # artifact (see CLAUDE_NON_HOOK_LAUNCHERS) and is excluded here.
+    present_launchers = Dir.glob(File.join(hooks_dir, "plastic-*")).map { |p| File.basename(p) }
+    orphans = (present_launchers - expected_launchers - CLAUDE_NON_HOOK_LAUNCHERS).sort
+
+    if orphans.empty?
+      checks << check(
+        category: "agent_registration", name: "hooks_no_orphans", status: "pass",
+        message: "No orphaned hook launchers in #{tilde(hooks_dir)}"
+      )
+    else
+      checks << check(
+        category: "agent_registration", name: "hooks_no_orphans", status: "warn",
+        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)"
+      )
+    end
+
     # hooks_registered — settings.json has Plastic hooks for required events
     settings_path = File.join(agent_dir, "settings.json")
     settings = read_json_safe(settings_path)

package/scripts/end-intent

@@ -67,6 +67,7 @@
 require "fileutils"
 require "date"
 require "open3"
+require "pathname"
 require_relative "lib/bridge"
 require_relative "lib/lock"
 require_relative "lib/intent_validator"
@@ -324,14 +325,25 @@ def git_toplevel(dir)
 end
 
 # Best-effort store commit: never raises, never blocks the mechanical close.
-# Returns true when a commit was created, false otherwise (not a git repo,
-# nothing to commit, or the commit failed). Pins a local committer identity so
-# the commit succeeds even with no ambient git config (hermetic).
-def store_commit(store, id, disposition)
+# Returns true when a commit was created, false otherwise (not a git repo, nothing to
+# commit, or the commit failed). Pins a local committer identity so the commit succeeds
+# even with no ambient git config (hermetic).
+#
+# SCOPED, never `git add -A` (D17, intent 197): stages only the completing intent's own
+# directory plus the store's INDEX.md, by explicit relative path. An unrelated dirty file
+# elsewhere in the store (another session's uncommitted work, a maintenance session's
+# in-flight change) is left exactly as it was found, never swept into this commit. This is
+# the safety floor that makes a concurrent maintenance session's change-plus-receipt safe on
+# the shared store checkout before intent 178 (store worktrees) lands.
+def store_commit(store, id, disposition, intent_dir:, index_path:)
   root = git_toplevel(store)
   return false if root.nil?
 
-  Open3.capture3("git", "-C", root, "add", "-A")
+  paths = [intent_dir, index_path].select { |p| p && File.exist?(p) }
+                                   .map { |p| relative_to(root, p) }
+  return false if paths.empty?
+
+  Open3.capture3("git", "-C", root, "add", "--", *paths)
   _out, _err, status = Open3.capture3(
     "git", "-C", root,
     "-c", "user.name=Plastic", "-c", "user.email=plastic@localhost",
@@ -340,6 +352,18 @@ def store_commit(store, id, disposition)
   status.success?
 end
 
+# `path`, relative to `root` (both absolute). Assumes `path` is inside `root` (true for
+# both intent_dir and index_path here, since both are derived from `store`, itself always
+# inside the same git repo `git_toplevel` resolved `root` from). Uses File.realpath, not
+# File.expand_path: `root` came back from `git rev-parse --show-toplevel`, which resolves
+# symlinked ancestors (e.g. macOS's /var -> /private/var), so an unresolved `path` can start
+# with a different prefix than `root` and produce a bogus, escaping relative path. Both
+# `path` and `root` are known to exist by the time this is called (the caller filters on
+# File.exist? first), so realpath is safe here.
+def relative_to(root, path)
+  Pathname.new(File.realpath(path)).relative_path_from(Pathname.new(File.realpath(root))).to_s
+end
+
 # --- pre-flight lock guard (D3/D4, intent 188) ------------------------------
 
 # Session resolution order (D3): explicit --session, else CLAUDE_CODE_SESSION_ID,
@@ -617,8 +641,9 @@ def main(argv)
   # 3. Savepoint Done bookend (idempotent).
   Bridge.append_terminal_savepoint(intent_dir, disposition)
 
-  # 4. Store auto-commit, unless --no-commit.
-  store_commit(store, id, disposition) unless opts[:no_commit]
+  # 4. Store auto-commit, unless --no-commit. Scoped to this intent's own paths (D17):
+  # never git add -A.
+  store_commit(store, id, disposition, intent_dir: intent_dir, index_path: index_path) unless opts[:no_commit]
 
   # 5. Disarm (D2/D16): dirty-worktree guard, disarm seam, lock verification.
   result = run_disarm(intent_dir, id, session, discard_worktree_changes: opts[:discard_worktree_changes])

package/scripts/lib/bridge.rb

@@ -798,13 +798,12 @@ module Bridge
         "warning_at" => 80,
         "critical_at" => 90
       },
-      # Worktree isolation block (intent 73c). Born unprovisioned; arm_auto calls
-      # Worktree.provision to fill it. code/store are abs paths or null.
+      # Worktree isolation block (intent 73c; store-worktree half retired by
+      # intent 178). Born unprovisioned; arm_auto calls Worktree.provision to
+      # fill it. "code" is an abs path or null.
       "worktree" => {
         "code" => nil,
         "code_branch" => nil,
-        "store" => nil,
-        "store_branch" => nil,
         "provisioned" => false
       },
       # Delivery-lock CACHE block (intent 108, D2). The durable truth is the

package/scripts/lib/hook_registry.rb

@@ -138,6 +138,18 @@ module HookRegistry
     result
   end
 
+  # Flattened, deduplicated Claude launcher names for every hook `events`
+  # registers (intent 204): each hook name maps to a hooks/<name> launcher
+  # installed as ~/.claude/hooks/plastic-<name>. The single derivation doctor's
+  # hooks_exist/hooks_executable/hooks_no_orphans checks read from, so a
+  # hand-kept list of launchers can never drift out of step with `events`
+  # again (the gap that let 8 of 15 launchers, all the enforcement gates, go
+  # unchecked).
+  def claude_launcher_names
+    events.values.flatten.flat_map { |g| g["hooks"].map { |h| h["name"] } }
+          .uniq.sort.map { |name| "plastic-#{name}" }
+  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

@@ -330,6 +330,11 @@ class InstallerCore
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/lib/restore_intent_v1.rb" => "scripts/lib/restore_intent_v1.rb",
       "scripts/restore-intent-v1" => "scripts/restore-intent-v1",
+"scripts/lib/revisions_writer.rb" => "scripts/lib/revisions_writer.rb",
+"scripts/maintenance-run" => "scripts/maintenance-run",
+"scripts/lib/maintenance_git.rb" => "scripts/lib/maintenance_git.rb",
+"scripts/lib/worktree_sweep.rb" => "scripts/lib/worktree_sweep.rb",
+"scripts/sweep-store-worktrees" => "scripts/sweep-store-worktrees",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",

package/scripts/lib/maintenance_git.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "open3"
+
+# MaintenanceGit - git isolation for a maintenance action (intent 197, D12/D13): a fresh
+# branch off the CURRENT tip of `base`, the caller's block runs, only the paths the block
+# ACTUALLY changed are staged (never `git add -A`), committed, and the branch is merged back
+# to `base` as part of the SAME closed operation before this method returns. Nothing strands
+# on an unmerged branch; nothing outside the block's own change is ever touched.
+#
+# Requires a CLEAN working tree before starting (see module doc above for why); refuses
+# loudly rather than attempt to distinguish pre-existing dirt from the block's own changes.
+# On any error inside the block, the working tree is hard-reset and returned to `base` before
+# re-raising, which is SAFE only because the precondition already proved nothing else was
+# dirty when the branch was created.
+module MaintenanceGit
+  module_function
+
+  class NotAGitRepo < StandardError; end
+  class DirtyWorkingTree < StandardError; end
+
+  def git_toplevel(dir)
+    out, _err, status = Open3.capture3("git", "-C", dir, "rev-parse", "--show-toplevel")
+    return nil unless status.success?
+
+    top = out.strip
+    top.empty? ? nil : top
+  end
+
+  # Bare paths (status prefix stripped), relative to `root`. Empty array on a clean tree.
+  def porcelain_paths(root)
+    out, _err, status = Open3.capture3("git", "-C", root, "status", "--porcelain")
+    return [] unless status.success?
+
+    out.lines.map { |l| l[3..].to_s.strip }.reject(&:empty?)
+  end
+
+  # Runs `block` inside a fresh branch off `base`'s current tip. Returns
+  # { changed: [...], committed: bool, merged: bool, branch: name }.
+  def run_scoped(repo_dir:, branch_name:, commit_message:, base: "main")
+    root = git_toplevel(repo_dir)
+    raise NotAGitRepo, "#{repo_dir} is not inside a git repository" unless root
+
+    dirty = porcelain_paths(root)
+    unless dirty.empty?
+      raise DirtyWorkingTree,
+            "#{root} has #{dirty.size} uncommitted path(s) before maintenance started; " \
+            "commit or stash them first (never swept via git add -A): #{dirty.join(", ")}"
+    end
+
+    checkout!(root, base)
+    run_git!(root, "checkout", "--quiet", "-b", branch_name)
+
+    begin
+      yield
+    rescue StandardError
+      run_git!(root, "reset", "--hard", "--quiet")
+      run_git!(root, "clean", "-fd", "--quiet")
+      checkout!(root, base)
+      delete_branch(root, branch_name)
+      raise
+    end
+
+    changed = porcelain_paths(root)
+    if changed.empty?
+      checkout!(root, base)
+      delete_branch(root, branch_name)
+      return { changed: [], committed: false, merged: false, branch: branch_name }
+    end
+
+    run_git!(root, "add", "--", *changed)
+    run_git!(root, "-c", "user.name=Plastic", "-c", "user.email=plastic@localhost",
+             "commit", "--quiet", "-m", commit_message)
+    checkout!(root, base)
+    run_git!(root, "merge", "--quiet", "--no-ff", "-m", "Merge #{branch_name} into #{base}", branch_name)
+    delete_branch(root, branch_name)
+
+    { changed: changed, committed: true, merged: true, branch: branch_name }
+  end
+
+  def checkout!(root, ref)
+    run_git!(root, "checkout", "--quiet", ref)
+  end
+
+  def delete_branch(root, name)
+    Open3.capture3("git", "-C", root, "branch", "--quiet", "-D", name)
+  end
+
+  def run_git!(root, *args)
+    _out, err, status = Open3.capture3("git", "-C", root, *args)
+    raise "git #{args.join(" ")} failed in #{root}: #{err}" unless status.success?
+  end
+end

package/scripts/lib/revisions_writer.rb

@@ -0,0 +1,69 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# RevisionsWriter - the shared append-only revisions.md writer (intent 107's convention,
+# generalized from restore_intent_v1.rb's proven pattern, intent 197). Every tool that
+# performs structural maintenance on an intent (project-links, rebuild-graph,
+# restore-intent-v1) must record it here: PLASTIC.md's `revisions.md` contract is that a
+# structural change and its receipt are never separated. This module owns rendering ONE
+# entry's text and appending it correctly; it does no git operations (that is
+# lib/maintenance_git.rb's job) and never overwrites a prior entry.
+#
+# Pure where it can be (render_entry has no IO); the IO half (append!) is a thin,
+# dependency-free file read/write, matching every other tool in scripts/lib.
+module RevisionsWriter
+  module_function
+
+  # PURE. Renders one `## Revision vN - TIMESTAMP` entry in the documented shape
+  # (PLASTIC-reference.md > Structural maintenance and revisions.md; templates/revisions.md).
+  # `n` is the next revision number (caller resolves it via next_revision_number, or a caller
+  # that already knows it, e.g. a batch writer amortizing one file read across many entries).
+  # `why` is the one-sentence reason ending in "[rule: <tag>]" (tag is appended here if the
+  # caller passes a bare sentence plus `rule:`, so every caller cannot forget the tag).
+  # `prior_location` and `change` are free text (the "Change:" line for a metadata edit, or a
+  # multi-line indented "Content held:" block for a relocated section/file - callers building
+  # a Content-held entry should pass an already-indented `change` block).
+  def render_entry(n, why:, rule:, prior_location:, change:, timestamp: Time.now.utc)
+    ts = timestamp.strftime("%Y-%m-%d-%H:%M")
+    lines = []
+    lines << "## Revision v#{n} - #{ts}"
+    lines << "- Why: #{why.to_s.strip} [rule: #{rule}]"
+    lines << "- Prior location: #{prior_location}"
+    lines << "- Change: #{change}"
+    "#{lines.join("\n")}\n"
+  end
+
+  # PURE. Every existing "## Revision vN" number found in `existing_text` (empty array when
+  # none, i.e. the file does not exist yet or carries no entries). Mirrors
+  # scripts/restore-intent-v1's own `nums = existing.scan(/^## Revision v(\d+)/)` exactly, so
+  # the two writers can never disagree about numbering.
+  def revision_numbers(existing_text)
+    existing_text.to_s.scan(/^## Revision v(\d+)/).flatten.map(&:to_i)
+  end
+
+  def next_revision_number(existing_text)
+    (revision_numbers(existing_text).max || 0) + 1
+  end
+
+  # IO. Appends one entry to `<intent_dir>/revisions.md`, creating the file with its
+  # documented header (matching templates/revisions.md's "# revisions.md" title line) if it
+  # does not exist yet. NEVER overwrites or reorders a prior entry (append-only, intent 124's
+  # own v3-corrects-v2-by-appending precedent). Returns the revision number written.
+  #
+  # Raises RevisionsWriter::WriteFailed on any IO error (permission, disk full, read-only
+  # filesystem) so a caller can roll back a paired structural change rather than leave it
+  # unrecorded (D14's "or refuse"). Never swallows an error silently.
+  def append!(intent_dir, why:, rule:, prior_location:, change:, timestamp: Time.now.utc)
+    path = File.join(intent_dir, "revisions.md")
+    existing = File.exist?(path) ? File.read(path) : "# revisions.md\n\n"
+    n = next_revision_number(existing)
+    entry = render_entry(n, why: why, rule: rule, prior_location: prior_location,
+                         change: change, timestamp: timestamp)
+    File.write(path, "#{existing.chomp}\n\n#{entry}")
+    n
+  rescue StandardError => e
+    raise WriteFailed, "could not append revisions.md at #{path}: #{e.message}"
+  end
+
+  class WriteFailed < StandardError; end
+end