@zalom/plastic 1.3.0 → 1.4.1

package/PLASTIC-reference.md

@@ -67,16 +67,18 @@ root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the glob
 in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
 a sibling subdirectory scaffolded once with a `.gitkeep`.
 
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Batches`, and an
 append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
-waves run sequentially, top to bottom.
+an executable checker. `## Batches` holds ordered batches; entries inside a batch are
+parallel-safe, batches run sequentially, top to bottom. A roadmap written before owner ruling 145
+may instead use the legacy `## Waves` heading; the tooling accepts both, but never renames an
+existing roadmap file to migrate it.
 
-Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+Each batch entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
 that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
 on any conflict INDEX wins and the roadmap entry is corrected to match.
 
-**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
+**Human-comprehension surface.** A roadmap is also written to be read cold. Batch entries render as
 checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
 line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
 engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
@@ -86,7 +88,7 @@ opening the file with no other context can tell what shipped, what is running no
 next in under a minute.
 
 **Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
-loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
+loop is its runtime. Batches lay out the parallelism plan: what can run together, and in what order.
 Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
 running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
 after a stop. This section only states the relationship and points to intent 69 as the future

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
 
@@ -456,9 +461,10 @@ Advisory. Hard gates guard writes, locks, and structure, never reads or searches
 Grep, Glob, and bash search are always allowed, including over the stores. When QMD is
 present and fresh, a content search over store markdown receives an advisory hint pointing
 at `qmd search` alongside its result; when QMD is present but stale, a background reindex
-fires so the next turn's hint runs against a fresh index (never synchronous). QMD and
-Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook appends
-one recommendation line per present tool. The legacy trailing `# qmd-ok` token is still
+fires so the next turn's hint runs against a fresh index (never synchronous). QMD, Enola,
+and Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook
+appends one recommendation line per present tool, naming Enola only, not both, when Enola
+and Serena are both present (Enola-first, one code-navigation slot). The legacy trailing `# qmd-ok` token is still
 accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
 calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
@@ -504,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
@@ -603,6 +622,14 @@ purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Work
 -> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
 ever referencing a bridge or lock that disarm is about to remove.
 
+`scripts/end-intent` performs this order's disarm step (verify the code worktree is clean,
+then merge/remove worktrees, then clear the lock) as its own step 5, mechanically, since
+intent 188: a session no longer needs a separate one-liner for it, and the script's own
+exit code (0) is the single fact a caller needs that the intent is closed AND its delivery
+lock is gone. A pre-flight lock guard runs before anything is written (refuses a live
+foreign session, reclaims a stale one with an audit line), and a dirty code worktree
+refuses before removal rather than force-discarding uncommitted changes.
+
 The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
 the completing session keeps full read and write access to the terminal directory and no
 purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
@@ -621,6 +648,18 @@ always allowed and unbounded (curator reindex, dashboards, and future intents th
 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.
 
+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.
+
 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
 to advisory (warn) rather than hard-blocking. Repair is orchestrator-driven: on a lock-issue
@@ -637,4 +676,3 @@ the lock-bounded post-done window with its keep-guard test. Intent 111 owns the
 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.
-

package/hooks/hooks.json

@@ -52,6 +52,11 @@
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" savepoint-pre",
             "statusMessage": "Recording stage start..."
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" links-gate",
+            "statusMessage": "Checking Links gate..."
           }
         ]
       },

package/hooks/links-gate

@@ -0,0 +1,3 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-links-gate"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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