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

package/PLASTIC.md

@@ -20,6 +20,7 @@ store/
     actions/              # optional — individual work items
     resources/            # optional — research, references, screenshots, diagrams
     savepoint.md          # optional — deterministic cycle-step ledger (auto-written)
+    revisions.md          # optional - append-only structural-maintenance audit trail
 ```
 
 Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
@@ -27,6 +28,33 @@ roles. Supporting artifacts that aren't lifecycle deliverables — research repo
 reference docs, external API snapshots, screenshots, diagrams — go in `resources/`.
 Name files inside as `{type}--{description}.md` (e.g., `deep-research--gsd-core.md`).
 
+`revisions.md` is an optional, append-only structural-maintenance audit trail. It is not a
+lifecycle deliverable and is never scaffolded at intent birth. Its mere existence signals that
+the intent underwent structural (not conceptual) change. Structural maintenance is move-and-record:
+it removes a misplaced section, file, or ref from its artifact and preserves that content in full
+inside `revisions.md` (newest entry at the bottom, one entry per relocated item), so no record is
+lost and the delivered meaning is never altered. Changing what an intent delivered is a new intent,
+not a revision.
+
+### Structural maintenance and revisions.md
+
+When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
+frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
+`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
+(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
+with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
+content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
+its full content embedded and the original is deleted.
+
+Violation tags (starter set, free-text tags allowed):
+- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
+- `phantom-section`: a section referenced but not present or not sanctioned
+- `stray-file`: a file that does not belong in the intent directory
+- `dangling-ref`: a link or reference to something that no longer exists
+- `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
+
 ## Frontmatter
 
 Identity and knowledge graph only. Nothing operational.

package/agents/plastic-intent-curator.md

@@ -23,6 +23,7 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 3. **Link discovery** — suggest connections between intents that share topics but aren't linked
 4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
 5. **Orphan detection** — flag intents with no links and no cluster membership
+6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
 
 ## How You Work
 
@@ -32,11 +33,13 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
 5. On a terminal-state transition: whenever you move an intent to Completed OR Abandoned, refresh the QMD index for that store so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
-6. Report what you changed
+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
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
 - You never create new intents — that's the creating-intent skill's job
-- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
+- For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
 - For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

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.23",
   "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",
@@ -235,6 +236,7 @@ class InstallerCore
       "templates/plan.md" => "templates/plan.md",
       "templates/checklist.md" => "templates/checklist.md",
       "templates/outcome.md" => "templates/outcome.md",
+      "templates/revisions.md" => "templates/revisions.md",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
@@ -562,6 +564,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`.

package/templates/revisions.md

@@ -0,0 +1,58 @@
+# revisions.md
+
+<!--
+FORM reference. A live revisions.md exists in an intent directory ONLY when structural
+maintenance actually happened. It is never scaffolded at intent birth, it carries no
+placeholder sentinel, and its mere presence signals that this intent underwent structural
+(not conceptual) change.
+
+Rules:
+- Append-only. Newest entry at the BOTTOM. Never edit or reorder past entries.
+- One entry per relocated item (one section, one file, or one ref per entry).
+- Move-and-record: remove the misplaced thing from its artifact and preserve it IN FULL
+  here. Never rewrite, summarize, or reinterpret delivered meaning. A change to delivered
+  meaning is a new intent, not a revision.
+- Header form: "## Revision vN - YYYY-MM-DD-HH:MM" (N increments by one per entry).
+
+Fields:
+- Why:            one sentence naming the broken rule, ending with "[rule: <tag>]".
+- Prior location: the artifact plus the section or path the content came from.
+- Content held:   the verbatim removed content, as an indented block (block form), OR
+- Change:         a one-line "removed X (before: ... -> after: ...)" for a frontmatter
+                  edit, used instead of a Content held block.
+
+Stray file: embed the file's full content as the Content held block and delete the
+original; Prior location names the filename. revisions.md is the single container.
+
+Violation-tag catalog (starter set; free-text tags are allowed):
+- unsanctioned-section : a top-level section the sanctioned-section rule now rejects
+- phantom-section      : a section referenced but not present or not sanctioned
+- stray-file           : a file that does not belong in the intent directory
+- dangling-ref         : a link or reference to something that no longer exists
+- 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
+
+The examples below show the three variants. Delete them when you write the first real
+entry; keep the "# revisions.md" title line above.
+-->
+
+## Revision v1 - 2026-06-30-14:35
+- Why: unsanctioned top-level section left over from an early draft [rule: unsanctioned-section]
+- Prior location: intent.md - ## Scope
+- Content held:
+
+  ## Scope
+  <the full content that was removed, verbatim>
+
+## Revision v2 - 2026-06-30-15:02
+- Why: chain edge to an intent that no longer exists [rule: broken-chain]
+- Prior location: intent.md frontmatter - chain
+- Change: removed "99x"  (before: ["4a1a", "99x"]  ->  after: ["4a1a"])
+
+## Revision v3 - 2026-06-30-15:20
+- Why: a stray notes file that does not belong in the intent directory [rule: stray-file]
+- Prior location: notes-old.md
+- Content held:
+
+  <the full content of notes-old.md, verbatim; the original file is then deleted>