@zalom/plastic 1.0.0-beta.21 → 1.0.0-beta.22

package/hooks/hooks.json

@@ -37,6 +37,11 @@
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" code-gate",
             "statusMessage": "Checking lifecycle gate..."
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" lock-gate",
+            "statusMessage": "Checking lock gate..."
           }
         ]
       },

package/hooks/lock-gate

@@ -0,0 +1,12 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+SESSION_ID=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("session_id") || ""' 2>/dev/null)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-lock-gate" "$FILE_PATH" "$SESSION_ID"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.22",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-lock-gate

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+#
+# Usage: hook-lock-gate <file_path> [session_id]
+# Fail-CLOSED PreToolUse gate (intent 96). Blocks a mutating write to an active
+# intent's lifecycle dir when THIS session holds no live lock. Project code is NOT
+# gated here (D2). Emits the PreToolUse JSON deny contract at exit 0; reserves
+# non-zero exit for hook-internal errors only. Matcher Write|Edit|NotebookEdit, so
+# reads never reach here.
+require "json"
+require_relative "lib/bridge"
+
+begin
+  file_path = ARGV[0]
+  exit 0 unless file_path && !file_path.empty?
+  session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
+
+  bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)   # nil = no lock held
+  reason = Bridge.lock_gate_decision(bridge_data, file_path)
+  exit 0 unless reason
+
+  print JSON.generate(
+    "hookSpecificOutput" => {
+      "hookEventName" => "PreToolUse",
+      "permissionDecision" => "deny",
+      "permissionDecisionReason" => reason   # "run /plastic-intent-starting to lock and begin"
+    }
+  )
+  exit 0
+rescue => e
+  # Hook-internal failure only: do NOT impersonate a user-deny. Log and fail open
+  # here so a gate bug never bricks editing; the fail-CLOSED intent is about MISSING
+  # locks, not crashes.
+  $stderr.puts "plastic lock-gate error: #{e.message}"
+  exit 0
+end

package/scripts/lib/bridge.rb

@@ -585,15 +585,19 @@ module Bridge
 
   # --- Auto mode (intent 27) ---
 
-  # Arm auto mode for a session+intent. Works even when no bridge exists yet
-  # (mid-session intent creation). Re-derives intent state, then sets build.auto.
-  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
+  # Shared arming spine (intent 96): resolve the session key, derive intent state,
+  # set the caller-controlled auto flag, acquire the delivery lock, provision the
+  # per-intent worktrees, persist, and purge terminal bridges. arm_auto (auto: true)
+  # and arm_guided (auto: false) are thin delegators so the lock-stamp + provision
+  # behaviour stays identical across both modes. Works even when no bridge exists
+  # yet (mid-session intent creation).
+  def self.arm(session, intent_id:, intent_dir:, store:, name:, auto:)
     key = resolve_session(session, intent_id: intent_id, store: store)
     if blank?(session) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
-      $stderr.puts "plastic: no session id available; arming auto with derived bridge key #{key}"
+      $stderr.puts "plastic: no session id available; arming with derived bridge key #{key}"
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
-    data["build"]["auto"] = true
+    data["build"]["auto"] = auto
 
     # Acquire the delivery lock: this armed bridge is now the single owner of the
     # intent's delivery (intent 73c). Stamp owner + pid liveness fields.
@@ -617,6 +621,20 @@ module Bridge
     purge_done_bridges(session: key)
     data
   end
+  private_class_method :arm
+
+  # Arm auto mode for a session+intent. Works even when no bridge exists yet
+  # (mid-session intent creation). Re-derives intent state, then sets build.auto.
+  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: true)
+  end
+
+  # Acquire the delivery lock WITHOUT auto mode (intent 96 / Start guided branch).
+  # Mirrors arm_auto's lock-stamp + worktree provision but leaves build.auto = false.
+  # Same signature as arm_auto; disarm_auto (mode-agnostic) releases a guided lock.
+  def self.arm_guided(session, intent_id:, intent_dir:, store:, name:)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: false)
+  end
 
   # Disarm auto mode. No-op if no bridge exists for the session.
   def self.disarm_auto(session)
@@ -673,6 +691,68 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Fail-closed lock gate (intent 96) -------------------------------------
+
+  # Returns a reason String to BLOCK, or nil to ALLOW. bridge_data is whatever
+  # discover_bridge(session:, cwd:) resolved for THIS session (own-session strict,
+  # or the lone headless/derived-key bridge), or nil = no lock held.
+  #
+  # BLOCK iff the target is an ACTIVE intent's lifecycle dir AND this session does
+  # NOT hold a LIVE lock FOR THAT SAME INTENT. ALLOW otherwise: a lock held for the
+  # target intent; a not-yet-active intent (creation, What); project code; anything
+  # that is not an active intent dir. The lock must match the TARGET intent: holding
+  # a live lock on intent A never green-lights a mutating write into intent B's dir.
+  # Project code is NOT gated here (D2) - it is isolated per-intent by worktree +
+  # branch, not by a write-time lock.
+  def self.lock_gate_decision(bridge_data, file_path)
+    return nil if blank?(file_path)
+
+    # Resolve the TARGET intent first so allow-by-lock is scoped to that intent.
+    target_dir = intent_dir_for(file_path)
+    return nil unless target_dir                  # not an intent dir (project code, scratch) -> ALLOW
+    id = intent_id_from_dir(target_dir)           # "<id>" from "<id>--<slug>"
+    store = File.dirname(target_dir)              # the store/ dir holding the intent
+    return nil unless id && intent_active?(id, store: store)  # not-yet-active (creation/What) -> ALLOW
+
+    # ALLOW only when this session holds a live lock for THIS SAME intent. A live
+    # lock on a different intent does not authorize writing into this intent's dir.
+    return nil if holds_live_lock?(bridge_data) &&
+                  bridge_data.is_a?(Hash) &&
+                  bridge_data.dig("intent", "id").to_s == id.to_s
+
+    "run /plastic-intent-starting to lock and begin"
+  end
+
+  # A discovered bridge counts as a held lock only if its lock is stamped AND the
+  # owner process is live on THIS host. Staleness/identity lives HERE (gate read
+  # path), never in arm_auto's write path. On host-mismatch we cannot probe the
+  # pid, so fall back to "held" (a remote live owner should still block).
+  def self.holds_live_lock?(bridge_data)
+    return false unless bridge_data.is_a?(Hash)
+    lock = bridge_data["lock"] || {}
+    return false if blank?(lock["owner_session"])
+    pid = lock["pid"]
+    host = lock["host"]
+    this_host = (Socket.gethostname rescue nil)
+    if host && this_host && host == this_host && pid.is_a?(Integer)
+      begin
+        Process.kill(0, pid)   # raises Errno::ESRCH if dead
+        return true
+      rescue Errno::ESRCH
+        return false           # dead owner -> not a held lock -> gate blocks (re-lock)
+      rescue Errno::EPERM
+        return true            # exists, not ours to signal -> live
+      end
+    end
+    true                       # different/unknown host: treat the stamped lock as held
+  end
+
+  # "<id>" from a ".../store/<id>--<slug>" dir, else nil.
+  def self.intent_id_from_dir(dir)
+    base = File.basename(dir.to_s)
+    base.include?("--") ? base.split("--", 2).first : nil
+  end
+
   # --- Worktree isolation gate (intent 73c2) ---
 
   # Returns a reason String to BLOCK, or nil to ALLOW. Two independent rules,

package/scripts/lib/installer_core.rb

@@ -208,6 +208,7 @@ class InstallerCore
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
+      "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
       "scripts/hook-retrieval-gate" => "scripts/hook-retrieval-gate",
       "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
@@ -562,6 +563,10 @@ class InstallerCore
           "matcher" => "Write|Edit|NotebookEdit",
           "hooks" => [
             { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
+            # Fail-closed lock gate (intent 96): a 2nd ordered command INSIDE the
+            # code-gate group (NOT a new same-matcher group, which the merge loop
+            # below would collapse). Blocks no-lock writes to an active intent's dir.
+            { "type" => "command", "command" => "#{hook_dir}/plastic-lock-gate", "statusMessage" => "Checking lock gate..." },
           ],
         },
         {

package/skills/intent-starting/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: plastic-intent-starting
+description: >-
+  Board a session onto an intent: take the lock FIRST, confirm savepoint state, ask auto or
+  guided ONCE, then resume at the latest delivered station and run the cycle to Done. Use on
+  `continuing --intent {id}`, when a new intent is registered and the user asks to work it,
+  or when the user picks an intent to work. Requires the intent in INDEX `## Active`.
+---
+
+# Intent Starting — board a session onto an intent
+
+Announce: "Boarding intent [ID] — [name]."
+
+`plastic-intent-starting` is the Start procedure. It boards a session onto one intent: take
+the lock FIRST, confirm the delivery state, ask **auto or guided ONCE**, board at the latest
+delivered station, then run the cycle to Done. The What → Why → How → Exec stations are the
+train track; Start boards the train, the ending procedure (~93) exits it.
+
+## Precondition + trigger
+
+Fires when the user picks an intent to work, when an agent is told to continue a SPECIFIC
+intent, or on `continuing --intent {id}` (the `continuing` → `starting` router is 106's job;
+this skill is invokable standalone now).
+
+If the intent is **terminal** (Done / Abandoned in INDEX): report only. Take NO lock, run NO
+resume, do NOT reopen it. Summarize the outcome and ask what is next. Stop here.
+
+## Lock FIRST (the spine)
+
+The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock-gate
+enforces it: without a held lock, mutating writes to this active intent's dir are denied with
+"run /plastic-intent-starting to lock and begin".
+
+1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
+   (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
+   brand-new What intent is activated here, then locked.
+2. **Arm the bridge.** Which arm is chosen by the mode answer (below), but the lock itself is
+   taken first. Reuse the arm one-liner shape from `plastic-auto`:
+   ```bash
+   # guided (lock only):
+   ruby -r ~/.plastic/scripts/lib/bridge -e \
+     'Bridge.arm_guided(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+   # auto (lock + auto), then hand to plastic-auto:
+   ruby -r ~/.plastic/scripts/lib/bridge -e \
+     'Bridge.arm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+   ```
+   Replace `<ID>`, `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
+   `<dir>` (the `ID--slug` directory), and `<name>`.
+
+**Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
+id the bridge is keyed by: pass the hook stdin `session_id` when you have it, otherwise
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. Both arms call `resolve_session`, which
+picks the first non-empty of: the explicit id you pass → `CLAUDE_CODE_SESSION_ID` → a
+deterministic derived key (a hash of the store and intent id). It never returns nil, so the
+lock is taken even when every session env var is empty; arming prints a one-line stderr
+notice when it falls through to the derived key.
+
+Idempotent re-arm: arming again with the same owner just refreshes the lock (re-derives and
+rewrites the bridge); it is not an error to re-board an intent this session already owns.
+
+## Confirm delivery state
+
+Read `savepoint.md` and classify from the **last line** alone, then verify ONLY that line's
+artifact is real (sentinel-aware via `Bridge.stage_file_present?`). On drift (the last line
+disagrees with files on disk), rebuild the ledger from disk and note the correction. Do not
+inline the rebuild; the `plastic-savepoint` skill owns it:
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
+```
+
+## Report + ask "auto or guided?" ONCE
+
+Report: the intent, the station it lands at (the matrix below), what is delivered, the next
+step. Then ask the user **"auto or guided?"** — exactly ONCE, whatever station it lands at.
+Never re-ask at a later station.
+
+- **guided** → `arm_guided` (lock only); continue step by step with the user through the
+  station's work below.
+- **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
+  only remaining job is the handoff; `plastic-auto` runs the cycle from here.
+
+## Board at the latest delivered station
+
+The station is derived from `savepoint.md` last line + real artifacts on disk. See
+`references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
+continue with) and the per-station notes. Summary of what "continue" means per station:
+
+- **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
+- **Why** → continue brainstorming → `spec.md`.
+- **How** → continue `plan.md` + `actions/` + `checklist.md`.
+- **Exec** → verify what has been delivered, then continue (or restart) the delivery /
+  research; tick the checklist.
+- **ready to complete** (`Exec outcome.md created`) → exit at Done.
+- **Done** → report only, ask what is next, never reopen.
+
+## Disarm / release on done
+
+When delivery finishes, disarm and release per the `plastic-auto` disarm/release prose (do
+not duplicate it here). The guided branch releases the lock via `disarm_auto`, which is
+mode-agnostic (it sets `auto = false` and calls `Worktree.release`), so it releases a guided
+lock too. When the work ships through a release, the release path merges the branch before the
+worktree is removed; the plain disarm remove is only for the no-release case.
+
+## References
+
+- `references/boarding-matrix.md` — the full boarding table and per-station behaviour.

package/skills/intent-starting/evals/evals.json

@@ -0,0 +1,117 @@
+{
+  "skill_name": "plastic-intent-starting",
+  "notes": "Intent 96. Scopes: description triggering (1-5) and behavior (6-10: lock-first spine, ask-mode-once, terminal report-only, mode->arm mapping, boarding matrix). The lock-first and gate behaviors are also proven by Ruby tests (test/bridge_guided_test.rb, test/lock_gate_test.rb, test/lock_gate_hook_test.rb).",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "start work on intent 96",
+      "expected_output": "Activates plastic-intent-starting (board a session onto the named intent).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "triggering",
+      "set": "train",
+      "prompt": "continuing --intent 96",
+      "expected_output": "Activates plastic-intent-starting (the --intent form boards a specific intent).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "work this intent",
+      "expected_output": "Activates plastic-intent-starting when an intent is in context to be worked.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 4,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "continue",
+      "expected_output": "Does NOT activate plastic-intent-starting; bare 'continue' is plastic-continuing (no specific intent named).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 5,
+      "scope": "triggering",
+      "set": "validation",
+      "prompt": "create a new intent for the uploader retry policy",
+      "expected_output": "Does NOT activate plastic-intent-starting; activates plastic-creating-intent.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 6,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Active intent X exists at the Why station. Start work on it (guided).",
+      "expected_output": "Takes the lock FIRST via Bridge.arm_guided (auto stays false) before any mutating work, confirms savepoint, then boards at Why and continues brainstorming toward spec.md.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "lock acquired before any mutating write; SKILL.md 'Lock FIRST' section precedes station work", "result": "expect-pass" },
+        { "type": "code", "check": "Bridge.arm_guided stamps the lock with auto=false (test/bridge_guided_test.rb green); lock-gate denies a no-lock write to the active intent dir (test/lock_gate_hook_test.rb green)", "result": "pass" }
+      ]
+    },
+    {
+      "id": 7,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Start work on an active intent without saying auto or guided.",
+      "expected_output": "Asks 'auto or guided?' exactly once after reporting the station; never re-asks at later stations.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "SKILL.md asks the mode exactly once and states 'never re-asked at a later station'", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 8,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Start work on an intent that is Done in INDEX.",
+      "expected_output": "Reports only: no lock, no resume, no reopen. Summarizes the outcome and asks what is next.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "terminal intent -> report only, no arm call", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 9,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Start work and choose auto.",
+      "expected_output": "guided -> Bridge.arm_guided; auto -> Bridge.arm_auto then hand off to plastic-auto (auto branch's only remaining job is the handoff).",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "SKILL.md maps guided->arm_guided and auto->arm_auto+handoff to plastic-auto", "result": "expect-pass" }
+      ]
+    },
+    {
+      "id": 10,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Start an intent whose savepoint last line is 'How  checklist.md created'.",
+      "expected_output": "Boards at Exec (verify plan + checklist real), per references/boarding-matrix.md, and continues delivery/ticks the checklist.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "boarding matrix lands 'How checklist.md created' / 'Exec started' at Exec", "result": "expect-pass" }
+      ]
+    }
+  ]
+}

package/skills/intent-starting/references/boarding-matrix.md

@@ -0,0 +1,35 @@
+# Boarding matrix — which station Start drops you at
+
+The station is derived from `savepoint.md`'s last line plus the real artifacts on disk.
+Classify from the last line alone, then verify ONLY that line's artifact is real
+(sentinel-aware). On drift, rebuild the ledger from disk and note it.
+
+| savepoint last line | latest delivered | boards at | continue with |
+|---|---|---|---|
+| `What  {id}--{slug}.md` (born) | What | **What / Why** | What work (106-expanded), then brainstorm → `spec.md` |
+| `Why  started` (spec still sentinel) | What | **Why** | continue brainstorming → `spec.md` |
+| `Why  spec.md created` | Why | **How** | `plan.md` + `actions/` + `checklist.md` |
+| `How  started` / `How  plan.md created` | (How in progress) | **How** | finish `plan.md` → `checklist.md` |
+| `How  checklist.md created` / `Exec  started` | How | **Exec** | implement, tick the checklist |
+| `Exec  outcome.md created` | Exec | **ready to complete** | exit at Done |
+| `Done  delivered` / `Done  abandoned` | terminal | **report only** | immutable; ask what is next |
+
+## Per-station behaviour (what "continue" means)
+
+- **What** → do what What requires (to be expanded in 106), then brainstorm → `spec.md`.
+- **Why** → continue brainstorming; deliver `spec.md`.
+- **How** → continue `plan.md` + `actions/` + `checklist.md`.
+- **Exec** → verify what has been delivered, then continue (or restart) the delivery /
+  research. The first unchecked `checklist.md` item is the next step; the newest `## Insights`
+  entry supplies human-readable context.
+- **ready to complete** → `outcome.md` is real; run the ending procedure (~93).
+- **Done** → terminal. Report the outcome, ask what is next. Never reopen; INDEX is
+  authoritative.
+
+## Notes
+
+- The mode (auto / guided) is asked exactly ONCE, whatever station Start lands at. It is never
+  re-asked at a later station. The lock is taken FIRST regardless of station (terminal intents
+  excepted: they get no lock and no resume).
+- An `## Insights` entry marked `(autonomous)` means the intent was being delivered
+  autonomously; in guided mode, surface that and offer to hand back to `plastic-auto`.