@zalom/plastic 1.4.0 → 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

@@ -99,6 +99,11 @@ tags: [plastic, architecture]
 | **How** | Planning | `plan.md` + `actions/ACTION_N.md` (at least one) + `checklist.md` | `plastic-intent-planning` |
 | **Exec** | Execution | `outcome.md` | `plastic-intent-executing` |
 
+Invoke a skill for your harness: Claude Code uses the slash form (`/plastic-intent-creating`);
+Codex CLI uses a dollar prefix instead (`$plastic-intent-creating`), and may also select a skill
+implicitly by matching its description. Skill names elsewhere in this document are given bare
+(`plastic-intent-creating`); add the prefix for your harness.
+
 `## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
 An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
 surfaced at any stage (What, Why, How, Exec). It is the most interesting residue of an
@@ -288,8 +293,8 @@ Beyond the lifecycle agents, Plastic ships thin skills for day-to-day operation:
 - **`plastic-feedback`** (intent 174) turns a described Plastic quirk, bug, or feature idea
   into a redacted local report file and a prefilled GitHub issue URL; only the user can submit
   it. `disable-model-invocation` hides its description from your own context, so if the user
-  hits a Plastic quirk, bug, or missing feature, offer to run `/plastic-feedback` yourself
-  instead of waiting to be asked; the user still sends it, you never do.
+  hits a Plastic quirk, bug, or missing feature, offer to invoke the plastic-feedback skill
+  yourself instead of waiting to be asked; the user still sends it, you never do.
 
 ## Releases and Versioning
 
@@ -505,18 +510,31 @@ Each gate guards one thing. All are hard except the retrieval gate:
 
 Exactly one session or agent develops an intent's delivery at a time. Ownership is
 session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
-(atomically, O_EXCL), recording the owner session, the host, the acquired-at time, a
-delegates list, and the lock type. Liveness is a lease: the owner's hooks refresh the lock
-file's mtime on tool activity, and the lock counts as stale only when that heartbeat is
-older than the TTL. No process id is consulted anywhere. The /tmp session bridge is a cache
+(atomically, O_EXCL). The session id is the authorization identity. Descriptive provenance
+records the controller's explicit `harness`, `agent`, `model`, `thread`, and `mode` values,
+but never grants access and is never inferred from transcripts or filesystem paths. Missing
+fields on legacy locks display as `Unknown`. Liveness is a lease: the owner's hooks refresh
+the lock file's mtime on tool activity, and that mtime is the sole heartbeat truth. The lock
+counts as stale only when the mtime is older than the TTL. No process id is consulted anywhere.
+The /tmp session bridge is a cache
 of this state; on any disagreement, or when the bridge is missing, the lock file wins.
 Another session that finds a fresh lock backs off; a stale lock is reclaimed only by
 explicit takeover, which replaces the lock and appends an audit line to the intent's
-savepoint.md. Subagents spawned by the owner write under the owner's lock once registered
-as delegates. Disarm clears the lock; the End tail is ordered: verify, merge and remove
+savepoint.md. Rearming the same session preserves its acquired identity and refreshes known
+provenance; an explicit takeover replaces the controller and starts new provenance.
+Subagents spawned by the owner write under the owner's lock once registered as delegates.
+Delegate activity status (`active`, `finished`, or `failed`) is descriptive and does not revoke
+the session's string-array authorization. A registered delegate remains authorized until a
+separate authorization-removal mechanism exists. Finished and failed delegate activity is
+retained as descriptive history, bounded to the 20 most recent terminal entries. A controller,
+a delegate, and an artifact claim are distinct evidence: controller ownership authorizes the
+delivery, delegate registration authorizes a child session, and a claim selects one current
+writer for one artifact. Disarm clears the lock; the End tail is ordered: verify, merge and remove
 worktrees, clear the lock, and only then is the bridge purge-eligible. Repair is one
-idempotent function with two entry points: the `plastic-lock` command (status, fix,
-release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. This is
+idempotent function with two entry points: the `plastic-lock` command (`who`, status, fix,
+release, reclaim, delegate) and `/plastic-intent-starting`, so boarding self-heals. `who` is
+read-only and reports the controller, mtime heartbeat, delegates, and claims from durable files.
+This is
 mandatory, not a convention.
 
 Solo-mode gate defaults (intent 128): on a confirmed positive solo determination
@@ -547,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
@@ -582,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)
 
@@ -621,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
@@ -656,6 +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.0",
+  "version": "1.5.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/codex-hook

@@ -2,18 +2,57 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# Usage: codex-hook <gate>   (gate: code-gate | lock-gate | savepoint-pre | gate-check | create-gate)
+# Usage: codex-hook <gate>
+#   file-mutation gates: code-gate | lock-gate | savepoint-pre | gate-check | create-gate | links-gate
+#   live-state hooks (intent 199): session-start | check-update | continue |
+#     future-intent-check | auto-arm | qmd-search | savepoint
+#   shell-tool gates (intent 203): bash-gate | retrieval-gate
 #
-# The Codex input adapter (intent 102). Reads a Codex hook stdin payload
-# (session_id at top level, the apply_patch command in tool_input.command,
-# [guide Part 4]), parses the diff envelope via ApplyPatchEnvelope, and drives
-# Plastic's payload-agnostic Ruby gate/savepoint cores once per file operation.
-# The cores' output contracts are already Codex-compatible, so their stdout/
-# stderr/exit are relayed unchanged (see ACTION_1's ARGV-contract table).
+# The Codex input adapter (intent 102, extended by 199 and 203). Reads a Codex
+# hook stdin payload once. Three shapes exist and the gate name alone selects
+# which path runs (Codex's own hooks.json registration guarantees they never
+# cross): the file-mutation gates read session_id at top level and the
+# apply_patch command in tool_input.command [guide Part 4], parse the diff
+# envelope via ApplyPatchEnvelope, and drive Plastic's payload-agnostic Ruby
+# gate/savepoint cores once per file operation, relaying stdout/stderr/exit
+# unchanged. The live-state hooks carry no tool_input at all (they are not tool
+# calls); the dispatcher execs the SAME launcher file Claude already runs for
+# that hook (hooks/<name>), which is already harness-agnostic (resolves
+# ~/.plastic off $HOME, reads only the common stdin fields the guide confirms
+# Codex shares with Claude for these three events), so the body is reused, not
+# rewritten (D3). The shell-tool gates (bash-gate, retrieval-gate) report
+# tool_name: "Bash" with the command in tool_input.command, but MUST NOT be
+# routed through ApplyPatchEnvelope.parse below: a plain shell command has no
+# *** Begin Patch/*** End Patch envelope, so it would parse to an empty op list
+# and hit this file's own `exit 0 if ops.empty?` line, silently allowing every
+# Bash call and reopening the exact hole intent 203 closes. So these two exec
+# the SAME scripts/hook-bash-gate / scripts/hook-retrieval-gate files Claude
+# already runs, unmodified, the identical "drive the body, relay its output"
+# pattern used for the live-state hooks. The one adaptation shared by both the
+# live-state and shell-tool paths is threading the payload's session_id into
+# CLAUDE_CODE_SESSION_ID, since Codex's own process env never carries it, plus
+# a bounded timeout: hooks/check-update backgrounds a real npm network call
+# without redirecting its output away from the inherited stdout/stderr pipes,
+# and Codex invokes hooks synchronously, so without a bound a slow network call
+# could hold this dispatcher's pipe open past the launcher's own (fast) exit.
 require "json"
+require "open3"
 require "rbconfig"
+require "timeout"
 require_relative "lib/apply_patch_envelope"
 require_relative "lib/intent_validator"
+require_relative "lib/links_gate"
+
+# Sync stdout so a relayed launcher's stdout and stderr land on the merged
+# pipe in call order. Ruby buffers STDOUT (but not STDERR) when it is not a
+# TTY; without this, `warn err` below can reach the OS pipe before a
+# preceding `print out` is flushed, corrupting the relayed JSON for any
+# caller that merges the dispatcher's own stdout and stderr.
+$stdout.sync = true
+
+STATE_HOOKS = %w[session-start check-update continue future-intent-check auto-arm qmd-search savepoint].freeze
+STATE_TIMEOUT = 5
+SHELL_HOOKS = %w[bash-gate retrieval-gate].freeze
 
 gate = ARGV[0].to_s
 raw = ($stdin.read rescue nil)
@@ -22,7 +61,49 @@ payload = (JSON.parse(raw) rescue nil)
 exit 0 unless payload.is_a?(Hash)
 
 session = payload["session_id"].to_s
+
+if STATE_HOOKS.include?(gate)
+  launcher = File.expand_path(File.join(__dir__, "..", "hooks", gate))
+  cwd = payload["cwd"].to_s
+  cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
+  env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
+  out, err, status = begin
+    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env, launcher, stdin_data: raw, chdir: cwd) }
+  rescue StandardError
+    ["", "", nil] # fail open: launcher missing, unexecutable, crashed, or too slow
+  end
+  print out unless out.to_s.empty?
+  warn err unless err.to_s.empty?
+  exit(status ? status.exitstatus : 0)
+end
+
+if SHELL_HOOKS.include?(gate)
+  # bash-gate / retrieval-gate (intent 203): a shell command has no apply_patch
+  # diff envelope, so this branch execs the SAME scripts/hook-bash-gate /
+  # scripts/hook-retrieval-gate files Claude already runs, unmodified, and
+  # relays their exit code and stderr. It must never fall through to
+  # ApplyPatchEnvelope.parse below (see header comment).
+  cwd = payload["cwd"].to_s
+  cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
+  env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
+  script = File.join(__dir__, "hook-#{gate}")
+  argv = [script]
+  # hook-retrieval-gate reads plastic_home off ARGV[0] (mirrors hooks/retrieval-gate's
+  # own launcher, which passes "$HOME/.plastic"); hook-bash-gate takes no args, it
+  # resolves Dir.home directly.
+  argv << ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") } if gate == "retrieval-gate"
+  out, err, status = begin
+    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env, RbConfig.ruby, *argv, stdin_data: raw, chdir: cwd) }
+  rescue StandardError
+    ["", "", nil] # fail open: script missing, unexecutable, crashed, or too slow
+  end
+  print out unless out.to_s.empty?
+  warn err unless err.to_s.empty?
+  exit(status ? status.exitstatus : 0)
+end
+
 command = payload.dig("tool_input", "command") || payload.dig("tool_params", "command")
+exit 0 if command.nil? # fail-open: no tool_input at all (unrecognized gate name or non-tool-call payload)
 ops = ApplyPatchEnvelope.parse(command)
 exit 0 if ops.empty? # fail-open: nothing parseable to gate
 
@@ -55,8 +136,11 @@ when "create-gate"
 
 when "lock-gate"
   # Deny is signalled by JSON on stdout at exit 0. Relay the first deny.
+  # "codex" is threaded as the harness (intent 201 D2): hook-lock-gate renders
+  # any deny reason with the $plastic-<name> form instead of Claude's default
+  # slash.
   ops.each do |o|
-    out, _ = run_core("hook-lock-gate", o.path, session)
+    out, _ = run_core("hook-lock-gate", o.path, session, "codex")
     if out.include?('"permissionDecision":"deny"') || out.include?('"permissionDecision": "deny"')
       print out
       exit 0
@@ -91,6 +175,36 @@ when "savepoint-pre"
   ops.each { |o| run_core("hook-savepoint-pre", o.path) }
   exit 0
 
+when "links-gate"
+  # Write-time belt for the PLASTIC.md ## Links contract (intent 192), reusing
+  # the SAME LinksGate.decision Claude's hook-links-gate already drives, so
+  # both harnesses share one decision function. before_content is the real
+  # on-disk file (File.read, or "" when it does not yet exist); after_content
+  # is the proposed result, o.added_content.
+  #
+  # DISCLOSED, NARROWER judgment than Claude's version (intent 198, Decision
+  # D3): ApplyPatchEnvelope.parse only ever captures a diff's ADDED lines,
+  # never its removed or context lines, so for an Update whose diff is a
+  # partial hunk rather than a full-file rewrite, after_content may not be the
+  # complete proposed file. This is the same class of disclosed limitation
+  # create-gate already carries for Update/Delete/Move (best effort, never a
+  # hard crash). links-gate has no PostToolUse backstop to defer to on Claude
+  # either, so running this best-effort compare on Update ops too is strictly
+  # more coverage than the prior total fail-open.
+  ops.each do |o|
+    next unless intent_file?(o.path)
+
+    before_content = File.exist?(o.path) ? File.read(o.path) : ""
+    plastic_home = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
+    reason = LinksGate.decision(file_path: o.path, before_content: before_content,
+                                 after_content: o.added_content.to_s, plastic_home: plastic_home)
+    next unless reason
+
+    $stderr.puts reason
+    exit 2
+  end
+  exit 0
+
 else
   exit 0
 end