@zalom/plastic 1.0.0-alpha.13 → 1.0.0-alpha.15

package/PLASTIC.md

@@ -18,9 +18,15 @@ store/
     checklist.md          # optional — execution registry (How deliverable)
     outcome.md            # optional — detailed result (Exec deliverable)
     actions/              # optional — individual work items
+    resources/            # optional — research, references, screenshots, diagrams
     savepoint.md          # optional — session state for resume
 ```
 
+Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
+roles. Supporting artifacts that aren't lifecycle deliverables — research reports,
+reference docs, external API snapshots, screenshots, diagrams — go in `resources/`.
+Name files inside as `{type}--{description}.md` (e.g., `deep-research--gsd-core.md`).
+
 ## Frontmatter
 
 Identity and knowledge graph only. Nothing operational.
@@ -115,6 +121,15 @@ Format: `ID--three-to-five-words` (all stores).
 - Intent file matches directory: `1a1--slug/1a1--slug.md`
 - Next ID: `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
 
+**Branch vs root — the semantic decision.** The numbering is mechanics; choosing
+*whether* to branch is meaning:
+
+- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation of the
+  parent. It cannot stand on its own; it only makes sense as part of the parent's work.
+- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
+  Record provenance with `sources: ["14"]`, not by branching.
+- **Rule of thumb:** if the intent could exist without its parent, it's a root.
+
 ## INDEX.md
 
 A Zettelkasten structure note, not a table of contents. Clusters by meaning.

package/hooks/auto-arm

@@ -0,0 +1,5 @@
+#!/bin/bash
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["user_prompt"].to_s' 2>/dev/null || echo "")
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-auto-arm" "$MESSAGE"

package/hooks/code-gate

@@ -0,0 +1,10 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-code-gate" "$FILE_PATH"

package/hooks/hooks.json

@@ -29,6 +29,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" code-gate",
+            "statusMessage": "Checking lifecycle gate..."
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
@@ -61,6 +73,16 @@
             "statusMessage": "Checking future intents..."
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/auto-arm\"",
+            "statusMessage": "Checking auto mode..."
+          }
+        ]
       }
     ]
   }

package/package.json

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

package/scripts/hook-auto-arm

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Usage: hook-auto-arm <message>
+# UserPromptSubmit arming (intent 27). Two jobs, both additive context — never blocks:
+#   1. Detect auto-trigger phrases -> steer the agent to invoke plastic:auto.
+#   2. If auto mode is armed and the active intent hasn't reached How -> remind the agent
+#      that project-code edits are gate-blocked until plan.md + checklist.md exist.
+# Outputs UserPromptSubmit hookSpecificOutput JSON, or exits silently.
+
+require "json"
+require_relative "lib/bridge"
+
+message = (ARGV[0] || "").downcase
+parts = []
+
+# --- 1. Auto-trigger steering ---
+AUTO_TRIGGERS = ["take it from here", "deliver this", "/plastic:auto", "auto mode"].freeze
+# bare "auto" only as a standalone word to avoid matching "automatic", "automation", etc.
+triggered = AUTO_TRIGGERS.any? { |p| message.include?(p) } || message.match?(/\bauto\b/)
+if triggered
+  parts << "Auto-mode request detected. Invoke the plastic:auto skill to deliver the " \
+           "active intent autonomously — it arms the lifecycle gate so project code " \
+           "cannot be edited before plan.md + checklist.md exist."
+end
+
+# --- 2. Standing gate reminder when armed and pre-How ---
+session = ENV["CLAUDE_SESSION_ID"]
+bridge_data = (session && !session.empty? && File.exist?(Bridge.path(session))) ? Bridge.read(session) : nil
+if bridge_data && bridge_data.dig("build", "auto") == true
+  intent = bridge_data["intent"] || {}
+  store = intent["store"]; dir = intent["dir"]
+  if store && dir
+    intent_dir = File.expand_path("#{store}/#{dir}")
+    reached_how = File.exist?("#{intent_dir}/plan.md") && File.exist?("#{intent_dir}/checklist.md")
+    unless reached_how
+      parts << "Auto mode armed on intent #{intent["id"]} — produce spec -> plan -> " \
+               "checklist before editing project code. Code edits are gate-blocked until then."
+    end
+  end
+end
+
+exit 0 if parts.empty?
+
+payload = {
+  "hookSpecificOutput" => {
+    "hookEventName" => "UserPromptSubmit",
+    "additionalContext" => parts.join("\n")
+  }
+}
+puts JSON.generate(payload)

package/scripts/hook-code-gate

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Usage: hook-code-gate <file_path>
+# PreToolUse gate (intent 27): when auto mode is armed and the active intent has not
+# reached How (plan.md + checklist.md), block edits to project code outside the store.
+#
+# Exit 0 = allow. Exit 2 = block (reason on stderr, shown to the agent).
+# No bridge / auto not armed / How reached / path under ~/.plastic or the intent dir = allow.
+
+require_relative "lib/bridge"
+
+file_path = ARGV[0]
+exit 0 unless file_path && !file_path.empty?
+
+# --- Load bridge (mirror hook-gate-check resolution) ---
+session = ENV["CLAUDE_SESSION_ID"]
+bridge_data = nil
+
+if session && !session.empty?
+  bridge_data = Bridge.read(session) if File.exist?(Bridge.path(session))
+end
+
+unless bridge_data
+  candidates = Dir.glob("/tmp/plastic-*.json").reject { |f| f.end_with?(".tmp") }
+  if candidates.any?
+    newest = candidates.max_by { |f| File.mtime(f) }
+    bridge_data = JSON.parse(File.read(newest)) rescue nil
+  end
+end
+
+exit 0 unless bridge_data
+
+reason = Bridge.code_gate_decision(bridge_data, file_path)
+exit 0 unless reason
+
+$stderr.puts "PLASTIC GATE — #{reason}"
+exit 2

package/scripts/install.rb

@@ -164,6 +164,8 @@ def distribute(mode)
     "scripts/hook-continue" => "scripts/hook-continue",
     "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
     "scripts/hook-gate-check" => "scripts/hook-gate-check",
+    "scripts/hook-code-gate" => "scripts/hook-code-gate",
+    "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
     "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
     "scripts/doctor.rb" => "scripts/doctor.rb",
   }
@@ -441,6 +443,12 @@ def merge_claude_hooks(settings_path)
         { "type" => "command", "command" => "#{hook_dir}/plastic-savepoint", "statusMessage" => "Saving Plastic intent state..." },
       ],
     },
+    "PreToolUse" => {
+      "matcher" => "Write|Edit|NotebookEdit",
+      "hooks" => [
+        { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
+      ],
+    },
     "PostToolUse" => {
       "matcher" => "Write|Edit",
       "hooks" => [
@@ -452,6 +460,7 @@ def merge_claude_hooks(settings_path)
       "hooks" => [
         { "type" => "command", "command" => "#{hook_dir}/plastic-continue", "statusMessage" => "Checking for continue..." },
         { "type" => "command", "command" => "#{hook_dir}/plastic-future-intent-check", "statusMessage" => "Checking future intents..." },
+        { "type" => "command", "command" => "#{hook_dir}/plastic-auto-arm", "statusMessage" => "Checking auto mode..." },
       ],
     },
   }

package/scripts/lib/bridge.rb

@@ -88,6 +88,7 @@ module Bridge
         "has" => has,
         "missing" => missing,
         "gate_failures" => 0,
+        "auto" => false,
         "last_activity" => Time.now.utc.iso8601
       },
       "observe" => {
@@ -159,6 +160,61 @@ module Bridge
     PROJECT_CONFIG_DEFAULTS.dup
   end
 
+  # --- 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:)
+    data = derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
+    data["build"]["auto"] = true
+    write(session, data)
+    data
+  end
+
+  # Disarm auto mode. No-op if no bridge exists for the session.
+  def self.disarm_auto(session)
+    data = read(session)
+    return nil unless data
+    data["build"] ||= {}
+    data["build"]["auto"] = false
+    write(session, data)
+    data
+  end
+
+  # Decide whether a code edit should be blocked while auto mode is armed.
+  # Returns a reason string to BLOCK, or nil to ALLOW.
+  #
+  # Blocks iff: auto armed AND intent hasn't reached How (stage what/why) AND the
+  # target is project code — i.e. NOT under ~/.plastic and NOT inside the intent dir.
+  def self.code_gate_decision(bridge_data, file_path, home: Dir.home)
+    return nil unless bridge_data.is_a?(Hash)
+    build = bridge_data["build"] || {}
+    return nil unless build["auto"] == true
+
+    intent_info = bridge_data["intent"] || {}
+    store = intent_info["store"]
+    dir = intent_info["dir"]
+    return nil unless store && dir
+    intent_dir_abs = File.expand_path("#{store}/#{dir}")
+
+    # "How reached" = the plan triplet exists. Gate by artifact presence, not the
+    # stage label (derive_stage returns "how" as soon as spec.md exists, before any
+    # plan). Code edits stay blocked until plan.md + checklist.md are both present.
+    reached_how = File.exist?("#{intent_dir_abs}/plan.md") &&
+                  File.exist?("#{intent_dir_abs}/checklist.md")
+    return nil if reached_how
+
+    file_abs = File.expand_path(file_path.to_s)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    return nil if file_abs == plastic_home || file_abs.start_with?("#{plastic_home}/")
+    return nil if file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/")
+
+    id = intent_info["id"]
+    "intent #{id} has not reached How — write plan.md + checklist.md before " \
+      "editing project code. Run plastic:auto or plastic:writing-plans first. " \
+      "(blocked edit: #{file_abs})"
+  end
+
   def self.deep_merge(base, overlay)
     result = base.dup
     overlay.each do |key, value|

package/skills/auto/SKILL.md

@@ -16,6 +16,25 @@ An active intent MUST exist in INDEX.md. If none exists, refuse: "No active inte
 
 If multiple active intents exist, ask the user which one to deliver (this is the only question auto asks).
 
+## Arm the Lifecycle Gate (do this FIRST)
+
+Immediately after selecting the intent — before any other work — arm auto mode. This
+writes the session bridge that makes the code-edit gate live, so project code cannot be
+edited before the plan exists (the gate applies to YOU, the orchestrator):
+
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.arm_auto(ENV["CLAUDE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+```
+
+Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
+`<dir>` (the `ID--slug` directory), and `<name>`. If `CLAUDE_SESSION_ID` is unset, arming
+is best-effort — proceed regardless; the gate simply won't engage.
+
+**Hard rule for the rest of this run:** do NOT edit project code (anything outside the
+intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
+Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.md) → Exec.
+
 ## Flags
 
 - `--skip-permissions` — bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
@@ -130,7 +149,11 @@ During initial project creation, all decisions are non-destructive by definition
    - Update `chain` in the current intent's frontmatter
 6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+8. Disarm the lifecycle gate (auto delivery is finished):
+   ```bash
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
+   ```
+9. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling
 

package/skills/auto/evals/evals.json

@@ -0,0 +1,92 @@
+{
+  "skill_name": "plastic:auto",
+  "notes": "Intent 27. Scopes: description triggering (1-8) and behavior/output quality (9). Assertions written after observing Step-3 runs (one clean subagent router per case).",
+  "results": {
+    "triggering": { "cases": 8, "passed": 8, "pass_at_1": 1.0, "run": "2026-06-10, one subagent per case" },
+    "behavior": { "cases": 1, "passed": 1, "evidence": "dogfood: intent 27 itself delivered via auto produced spec->plan->checklist before any code edit; code-gate unit test proves pre-How project-code edits are blocked" }
+  },
+  "evals": [
+    {
+      "id": 1, "scope": "triggering", "set": "train",
+      "prompt": "auto",
+      "expected_output": "Activates plastic:auto (the bare 'auto' keyword is the documented trigger).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic:auto", "observed": "plastic:auto", "result": "pass" }
+      ]
+    },
+    {
+      "id": 2, "scope": "triggering", "set": "train",
+      "prompt": "take it from here and deliver intent 27 end to end",
+      "expected_output": "Activates plastic:auto (autonomous delivery of an active intent).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic:auto", "observed": "plastic:auto", "result": "pass" }
+      ]
+    },
+    {
+      "id": 3, "scope": "triggering", "set": "validation",
+      "prompt": "go fully autonomous on the active intent, don't ask me questions",
+      "expected_output": "Activates plastic:auto.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic:auto", "observed": "plastic:auto", "result": "pass" }
+      ]
+    },
+    {
+      "id": 4, "scope": "triggering", "set": "train",
+      "prompt": "deliver this intent for me",
+      "expected_output": "Activates plastic:auto.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE == plastic:auto", "observed": "plastic:auto", "result": "pass" }
+      ]
+    },
+    {
+      "id": 5, "scope": "triggering", "set": "train",
+      "prompt": "set up a hook to automatically format the file on every save",
+      "expected_output": "Does NOT activate plastic:auto. Near-miss: shares 'auto*' but is a settings/hooks task (update-config).",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic:auto", "observed": "update-config", "result": "pass" }
+      ]
+    },
+    {
+      "id": 6, "scope": "triggering", "set": "validation",
+      "prompt": "deliver the built package to the dist directory",
+      "expected_output": "Does NOT activate plastic:auto. Near-miss: shares 'deliver' but is a build/file task.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic:auto", "observed": "none", "result": "pass" }
+      ]
+    },
+    {
+      "id": 7, "scope": "triggering", "set": "train",
+      "prompt": "create a new intent for the dashboard idea",
+      "expected_output": "Does NOT activate plastic:auto; activates plastic:creating-intent.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic:auto", "observed": "plastic:creating-intent", "result": "pass" }
+      ]
+    },
+    {
+      "id": 8, "scope": "triggering", "set": "validation",
+      "prompt": "what's the status of my active intents?",
+      "expected_output": "Does NOT activate plastic:auto; this is a read/continuing/managing-index query.",
+      "files": [],
+      "assertions": [
+        { "type": "code", "check": "router CHOICE != plastic:auto", "observed": "plastic:managing-index", "result": "pass" }
+      ]
+    },
+    {
+      "id": 9, "scope": "behavior", "set": "train",
+      "prompt": "Active intent X exists with only a '## Intent' section. Deliver it in auto mode.",
+      "expected_output": "Arms the lifecycle gate first, then produces spec.md (Why), then plan.md + actions/ + checklist.md (How), and edits NO project code before plan.md + checklist.md exist. Disarms on completion.",
+      "files": [],
+      "assertions": [
+        { "type": "human", "check": "spec.md written before plan.md before any project-code edit", "observed": "dogfood run of intent 27 followed this order", "result": "pass" },
+        { "type": "code", "check": "code-gate blocks project-code Edit/Write while pre-How (test/code_gate_test.rb)", "observed": "test green", "result": "pass" }
+      ]
+    }
+  ]
+}

package/skills/creating-intent/SKILL.md

@@ -60,6 +60,16 @@ IDs are scoped to the store they live in. Use the correct store path:
 "${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "<STORE>" "<parent_id>"
 ```
 
+**Branch vs root — decide before assigning the ID.** Having a "parent" in mind does
+NOT automatically mean branch. Choose by meaning:
+
+- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation. It only
+  makes sense as part of the parent's work.
+- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
+  Capture the inspiration in `sources` (e.g., `sources: ["14"]`), not in the ID.
+- **Rule of thumb:** if the intent could exist without its parent, make it a root and
+  set `sources`. Only branch when it genuinely cannot stand alone.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context: