@zalom/plastic 1.0.0-beta.20 → 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.20",
+  "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/creating-skills/SKILL.md

@@ -48,6 +48,15 @@ routes each authoring task to the reference that holds the depth.
 | Deciding script versus prose, or writing a script | `references/scripts.md` |
 | Building evals for a skill | `references/evals.md` |
 
+## Shrink context, or let a skill self-improve
+
+- When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for
+  the global token levers: a PostToolUse hook that trims noisy tool output before it enters
+  context, and Programmatic Tool Calling that keeps looped tool results in code, not context.
+- When a skill should learn from its own real runs, open `references/hooks.md` (E8) for the
+  propose-only Stop or SubagentStop loop (transcript to proposed edits to human approval to
+  git, effort-gated). The dedicated skill is the future `improving-skills` skill.
+
 ## Scaffolder and evals
 
 - To start a new skill, agent, or hook from a born-slim file, run

package/skills/creating-skills/evals/evals.json

@@ -6,70 +6,103 @@
       "prompt": "I want to author a new Plastic skill, how should I structure it?",
       "expected_output": "The skill should activate. This is a direct authoring request that names the domain. Guide the user through progressive disclosure: metadata around 100 tokens, a slim body under 5000 tokens and 500 lines that routes, and references on demand. Point to references/skills.md for frontmatter, description, and voice, and route load-level questions through references/progressive-disclosure.md first.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill activates (direct authoring request that names the domain).",
+        "The response routes to references rather than dumping deep how-to inline.",
+        "The response states the load-level budgets (around 100 token metadata, body under 5000 tokens and 500 lines)."
+      ]
     },
     {
       "id": 2,
       "prompt": "The agent keeps ignoring my instructions and the file is huge, help me restructure it",
       "expected_output": "The skill should activate. This is an indirect trigger that never names skills or progressive disclosure, but the symptoms (bloated file, agent missing or skipping steps) are exactly the over-budget body case the skill covers. Guide toward splitting the body into references, keeping the body a thin router, and binding each reference to an observable trigger condition.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill activates on the indirect trigger (no skill or progressive-disclosure keyword in the prompt).",
+        "The response guides toward splitting the body into references and keeping a thin router."
+      ]
     },
     {
       "id": 3,
       "prompt": "Scaffold a new lifecycle hook for Plastic",
       "expected_output": "The skill should activate. Authoring a lifecycle hook is in scope. Route to references/hooks.md and offer scripts/scaffold.rb to start the hook from a born-slim file.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill activates (authoring a lifecycle hook is in scope).",
+        "The response routes to references/hooks.md and offers scripts/scaffold.rb."
+      ]
     },
     {
       "id": 4,
       "prompt": "Our prompts are bloated and we keep blowing the context budget",
       "expected_output": "The skill should activate. This is an indirect trigger: the user describes bloated prompts and a context budget problem without naming skills. The skill restructures instructions into a thin router over deep references with hard load-level budgets, which is the fix for this symptom.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill activates on the indirect context-budget trigger (no skill keyword in the prompt).",
+        "The response treats the fix as a thin router over deep references with hard load-level budgets."
+      ]
     },
     {
       "id": 5,
       "prompt": "Run the evals on my skill and check the pass rate",
       "expected_output": "The skill should NOT trigger. Running evals and reading pass rates is the job of plastic-evaluating-skills, not authoring. Near-miss negative: shares the words 'skill' and 'evals' but the operation is grading an existing skill, not creating or revising one.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill does not activate (running and grading evals is plastic-evaluating-skills, not authoring)."
+      ]
     },
     {
       "id": 6,
       "prompt": "Create a new intent for the dashboard work",
       "expected_output": "The skill should NOT trigger. Creating an intent is plastic-creating-intent. Near-miss negative: shares the verb 'create' but the object is an intent, not a skill, agent, or hook.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill does not activate (creating an intent is plastic-creating-intent)."
+      ]
     },
     {
       "id": 7,
       "prompt": "I keep losing every team fight because of a skill issue in this game, any tips?",
       "expected_output": "The skill should NOT trigger. This is a gaming question with no relation to authoring instructions. Near-miss negative: shares the word 'skill' in an unrelated sense.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill does not activate (gaming question, unrelated sense of 'skill')."
+      ]
     },
     {
       "id": 8,
       "prompt": "Write unit tests for my Ruby model that validates email addresses",
       "expected_output": "The skill should NOT trigger. Writing test code is a Ruby testing task. Near-miss negative: shares 'write' and 'test' but has nothing to do with authoring a skill, agent, or hook.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill does not activate (writing test code is a Ruby testing task, not authoring a skill)."
+      ]
     },
     {
       "id": 9,
       "prompt": "Author a slim SKILL.md for a PDF-extraction skill",
       "expected_output": "Activation is assumed for this output-quality case. Correct output is a SKILL.md whose frontmatter description is third person, front-loads concrete trigger keywords, states WHEN to use rather than the workflow, and includes at least one indirect trigger. The body stays under 5000 tokens and under 500 lines and routes to references rather than carrying deep how-to. Each reference link names an observable trigger condition with no bare pointer like 'see references/'. References stay one level deep, and no string contains an em-dash or en-dash.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The frontmatter description is written in the third person (no 'you' or 'I').",
+        "The description front-loads concrete trigger keywords in its opening clause.",
+        "The description includes at least one indirect trigger (a symptom phrasing that never names PDF extraction or skills).",
+        "The body is under 5000 tokens and under 500 lines.",
+        "Every reference link is bound to an observable trigger condition (no bare pointer such as 'see references/').",
+        "References stay one level deep (no reference points to a deeper reference).",
+        "No string in the SKILL.md or its references contains an em-dash or en-dash."
+      ]
     },
     {
       "id": 10,
       "prompt": "Make this subagent role file slim, the description is vague and the body is too long",
       "expected_output": "The skill should activate. Authoring or revising a subagent or Agent role file is in scope, and the symptoms (vague description, over-long body) are the progressive-disclosure case. Route to references/agents.md, tighten the description to state WHEN, and move depth into references. Output should keep the body under budget and use no em-dashes.",
       "files": [],
-      "assertions": []
+      "assertions": [
+        "The skill activates (revising a subagent or Agent role file is in scope).",
+        "The response routes to references/agents.md and tightens the description to state WHEN.",
+        "The proposed output keeps the body under budget and uses no em-dash or en-dash."
+      ]
     }
   ]
 }

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

@@ -17,6 +17,8 @@ handler grows past a few lines. This file covers only hook authoring.
 - No-op by default, opt-in (E4)
 - Exit codes and output channels (E5)
 - Verify the harness engaged (E6)
+- Token levers: global hooks that shrink context (E7)
+- Propose-only self-improving loop (E8)
 - Authoring checklist
 
 ## When to reach for a hook (E1)
@@ -177,6 +179,59 @@ Verify by observation, not assumption: [E6]
 - For a gate, attempt the action the gate should block and confirm it is refused. A gate that
   never refuses in testing is a gate that is not engaged.
 
+## Token levers: global hooks that shrink context (E7)
+
+Progressive disclosure trims what a skill loads. Two GLOBAL hooks trim what tool traffic
+costs at runtime, independent of any skill body. Both are token-reduction levers. Reach for
+them when prompts or tool output blow the context budget. [E7]
+
+- PostToolUse output preprocessing. Register a GLOBAL PostToolUse hook that trims noisy tool
+  output before it enters context: collapse repeated lines, cut a thousand-line log to its
+  head and tail, strip ANSI control codes, drop progress chatter. The model never sees the
+  noise, so it never pays tokens for it. Scope the hook with a matcher over the loud tools
+  (for example `Bash`), keep it lossless on signal (trim volume, never the line that carries
+  the answer), and make it no-op by default per E4. This is one GLOBAL hook, not a per-skill
+  or frontmatter hook. [E7]
+- Programmatic Tool Calling. When a tool runs in a loop and only the final result matters,
+  keep the intermediate results in code and return just the answer, instead of letting every
+  call land in context. Reach for it when a skill drives a tool in a loop and the per-call
+  output is throwaway. Pointer only: this is a Claude Code runtime feature, not a hook you
+  author here. [E7]
+
+The first lever trims output already produced; the second avoids producing the context at
+all. Pair either with sub-agent isolation (see `agents.md`) when a whole noisy sub-task can
+run off to the side and return only its conclusion. [E7]
+
+Both levers cut the CONTEXT axis (the input the model reads). The model's own OUTPUT tokens
+(what it writes) are a separate axis with no hook: cut them with terse instructions, tool
+responses that offer a concise mode, and sub-agent offloading that returns a short summary
+instead of the full trace. [E7]
+
+## Propose-only self-improving loop (E8)
+
+A skill can learn from its own real runs without ever editing itself unattended. Reach for
+this shape when a skill should improve from what actually happened in its runs. [E8]
+
+Wire a GLOBAL Stop or SubagentStop hook that, once an effort threshold is met, reads the
+just-finished transcript, drafts proposed edits to the skill, and stops. A human reviews the
+proposal, approves it, and the approved change lands in git. The hook never writes the skill
+directly. [E8]
+
+The guardrails that make this safe: [E8]
+
+- Propose only. The hook emits a diff or a suggestion, never an applied edit. Approval is a
+  human step, so a bad proposal costs a review, not a regression.
+- Effort-gated. Run the analysis only past a threshold (a long enough transcript, a real
+  failure observed), so cheap runs spend nothing.
+- Git-landed. The approved edit goes through the normal commit path, so every
+  self-improvement is reviewable and revertible.
+- Global, not scoped. This is one GLOBAL Stop or SubagentStop hook, not a per-skill
+  frontmatter hook.
+
+Pointer only. The real self-improving skill is the future `improving-skills` skill; this
+section records the safe shape so a skill author knows the loop exists and keeps it
+propose-only. [E8]
+
 ## Authoring checklist
 
 - [ ] Behavior must hold deterministically; a stronger skill description was tried first (E1).

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`.