@zalom/plastic 1.0.0-beta.11 → 1.0.0-beta.13

package/PLASTIC.md

@@ -183,6 +183,10 @@ Sections: `## Active`, `## Future`, `## Clusters`, `## Abandoned`, `## Completed
 
 For index maintenance, use `plastic-managing-index`.
 
+One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>](<dir>) <tags>`.
+The title is the title, not a summary: aim for about 80 characters, no multi-sentence
+descriptions. This is a self-check, not a gate.
+
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -194,6 +198,53 @@ ALL work flows through intents.
 5. Researches are intents. No separate folder.
 6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete.
 
+## House Style (self-check)
+
+The agent is the heaviest contributor to the transcript, so terseness pays every turn. These
+are pre-send self-checks the agent applies to its own output. They are not gated.
+
+- Answer or decision first. Lead with the result, then support it.
+- Bullets over paragraphs.
+- No preamble, no end-recap. Do not restate the question or summarize what you just said.
+- One question-cluster at a time when asking the human.
+- Reasoning goes in the thinking channel, not duplicated into the visible reply. This keeps
+  the human's visibility into your reasoning without paying for it twice in the transcript.
+
+Active-intent cache rule. For the intent under active development you already hold its
+delivered artifacts in your own context: prefer revisiting that in-context memory (hit the
+cache) over re-reading them from disk, which only widens context. QMD is for OTHER or indexed
+intents, not for re-reading what you just wrote. Pairs with `/clear` plus savepoint-resume
+hygiene after each intent. Advisory self-check, not hard-verifiable.
+
+## Retrieval Gate
+
+A single capability-aware PreToolUse gate enforces retrieval-first routing on the agent's own
+Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). Detection is binary:
+present means enforce, absent or down means off, with no warning and no advisory tier.
+
+- Store markdown (under a Plastic store) routes to QMD when QMD is present and the index is
+  fresh: the raw grep/find/Read is blocked and you use `qmd search`/`qmd query` (or
+  `scripts/qmd-sync search`) instead. When QMD is present but stale, the read is allowed this
+  turn and a background reindex is fired so the next turn enforces against a fresh index;
+  reindex is never synchronous. When QMD is absent or down, raw reads are allowed.
+- Serena-supported code and data files route to Serena symbolic tools when Serena is present;
+  absent means allowed.
+- Images, binaries, and everything else are allowed.
+- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command for the rare case where
+  QMD is healthy but you genuinely need the raw read. A quoted or echoed occurrence does not
+  bypass. Bypasses are logged.
+- Scope: only the agent's tool calls. Ruby `File.read` inside a script is invisible to the gate
+  and is out of scope by design.
+
+## Context-economy measurement buckets (84a)
+
+Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
+
+- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
+- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
+  in the transcript.
+- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
+
 ## Transition Gates
 
 | Transition | Trigger | Gate |
@@ -205,6 +256,26 @@ ALL work flows through intents.
 
 Hard blocking — hooks exit code 2 on gate failure.
 
+## Delivery Isolation and the Single-Owner Lock
+
+Exactly one session or agent develops an intent's delivery at a time. Ownership is the armed
+session bridge, which doubles as the delivery lock: arming records the owning session, the
+owner pid, an acquired-at timestamp, and the host. Another session that finds an armed bridge
+for the same intent with a live owner backs off; if the owner pid is dead the lock is
+reclaimable. This is mandatory, not a convention.
+
+Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
+for that intent happen only inside it. Plastic provisions the worktree deterministically: it
+resolves the project repo from `projects.yml` and runs `git -C <repo> worktree add`, so
+isolation never depends on the current working directory. There are two worktrees per project
+intent: a code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch `plastic/{id}--{slug}`)
+and a store worktree at `<plastic_home>/.worktrees/{id}--{slug}` (branch
+`plastic-store/{id}--{slug}`), so lifecycle-doc commits and code commits move as one unit.
+
+Provisioning fails open for intents that touch no project code (pure research or decision
+intents in the global store, or a non-git repo): those get the lock only, and the worktree
+block stays unprovisioned. The fail-open path is always logged, never silent.
+
 ## Deprecation Process
 
 Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is

package/hooks/hooks.json

@@ -40,6 +40,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" savepoint-pre",
+            "statusMessage": "Recording stage start..."
+          }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [
@@ -59,6 +69,16 @@
             "statusMessage": "Checking lifecycle gate..."
           }
         ]
+      },
+      {
+        "matcher": "Bash|Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" retrieval-gate",
+            "statusMessage": "Checking retrieval gate..."
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/hooks/retrieval-gate

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Retrieval-gate hook launcher (intent 84, Lever 2). No-op when there is no
+# global store. Passes the PreToolUse JSON through on stdin (exec inherits it)
+# and the plastic_home as ARGV[0], mirroring the qmd-search launcher.
+GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+if [ ! -f "$GLOBAL_INDEX" ]; then
+  exit 0
+fi
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-retrieval-gate" "$HOME/.plastic"

package/hooks/savepoint-pre

@@ -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-savepoint-pre" "$FILE_PATH"

package/package.json

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

package/scripts/hook-code-gate

@@ -3,11 +3,15 @@
 # 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.
+# PreToolUse gate. Composes two independent block rules; EITHER blocks the edit:
+#   - Stage rule (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.
+#   - Worktree isolation rule (intent 73c2): when the intent has a provisioned code
+#     worktree, block project-code edits outside it; and block edits to another
+#     intent's store dir whose delivery lock is held by a live non-owner session.
 #
 # 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.
+# No bridge = allow. Each rule fails open on its own conditions (see bridge.rb).
 
 require_relative "lib/bridge"
 
@@ -20,7 +24,8 @@ session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 exit 0 unless bridge_data
 
-reason = Bridge.code_gate_decision(bridge_data, file_path)
+reason = Bridge.code_gate_decision(bridge_data, file_path) ||
+         Bridge.worktree_gate_decision(bridge_data, file_path, current_session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/hook-gate-check

@@ -24,6 +24,12 @@ intent_dir_abs = Bridge.intent_dir_for(file_path_abs)
 if intent_dir_abs
   begin
     Bridge.append_savepoint(intent_dir_abs, file_path_abs)
+    # When checklist.md lands, How ends and Exec begins: emit the `Exec started`
+    # companion in the same event (intent 81). Guard on a real (non-placeholder)
+    # checklist so a scaffold sentinel does not trip it.
+    if File.basename(file_path_abs) == "checklist.md" && Bridge.stage_file_present?(file_path_abs)
+      Bridge.append_exec_started(intent_dir_abs)
+    end
   rescue StandardError
     # ignore — rebuildable from disk
   end
@@ -112,32 +118,17 @@ if is_stage_file || is_action_file
 
   Bridge.write(session, bridge_data)
 
-  # Build transition context
-  stage_labels = { "what" => "What", "why" => "Why", "how" => "How", "exec" => "Exec", "done" => "Done" }
-  next_hints = {
-    "why" => "write spec.md",
-    "how" => "Why complete. Invoke plastic-auto to deliver autonomously, or write plan.md manually.",
-    "exec" => "How complete. Invoke plastic-auto or plastic-executing-plan to execute, or work through the checklist manually.",
-    "done" => "Exec complete. Intent must be completed now — write outcome.md, update INDEX.md, auto-commit. Use plastic-auto or do it manually."
-  }
-
-  context_parts = ["PLASTIC"]
-  if old_stage != new_stage
-    context_parts[0] = "PLASTIC — Stage transition: #{stage_labels[old_stage] || old_stage} → #{stage_labels[new_stage] || new_stage}."
-  else
-    context_parts[0] = "PLASTIC — #{basename} written (stage: #{stage_labels[new_stage] || new_stage})."
-  end
-  context_parts << "#{basename} written."  if old_stage != new_stage
-  if new_missing.any?
-    context_parts << "Next: #{new_missing.join(", ")}"
-  elsif next_hints[new_stage]
-    context_parts << "Next: #{next_hints[new_stage]}"
-  end
+  # Build transition context — ONE concise sentence (intent 84, Lever 1),
+  # preserving the `Next: ...` hint. Formatting is pure in Bridge.gate_narration.
+  context = Bridge.gate_narration(
+    old_stage: old_stage, new_stage: new_stage,
+    basename: basename, new_missing: new_missing
+  )
 
   payload = {
     "hookSpecificOutput" => {
       "hookEventName" => "PostToolUse",
-      "additionalContext" => context_parts.join(" ")
+      "additionalContext" => context
     }
   }
   puts JSON.generate(payload)

package/scripts/hook-retrieval-gate

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse retrieval gate (intent 84, Lever 2). Reads the tool call (JSON on
+# stdin: tool_name + tool_input), computes capabilities (QMD detect+freshness,
+# Serena detect), delegates the decision to RetrievalGate, and enforces:
+#   ALLOW = exit 0 ; BLOCK = exit 2 with reason on stderr (shown to the agent).
+# Fail-open: any parse error, timeout, or unexpected exception exits 0. On the
+# STALE QMD path RetrievalGate fires QmdSync.reindex_async (NEVER synchronous).
+# Binds subagents (PreToolUse hooks apply to subagent tool calls too).
+#
+# Scope: only the agent's own Bash/Read/Grep/Glob calls. Ruby `File.read` inside
+# scripts is invisible to a PreToolUse hook and is out of scope (no exemptions).
+#
+# ARGV[0] is plastic_home (passed by the launcher), like hook-qmd-search.
+
+require "json"
+require "timeout"
+require_relative "lib/retrieval_gate"
+require_relative "lib/qmd_sync"
+require_relative "lib/power_tools"
+
+module RetrievalGateHook
+  module_function
+
+  # Pure-ish core: capabilities and reindex are injected so this is unit-testable
+  # with no real qmd/serena. Returns [exit_code, stderr_string].
+  #   stdin: raw PreToolUse JSON
+  #   capabilities: { qmd:, qmd_fresh:, serena: }
+  #   reindex: callable fired on the STALE path
+  def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
+    payload = parse(stdin)
+    return [0, nil] unless payload
+
+    tool_name = payload["tool_name"].to_s
+    tool_input = payload["tool_input"]
+    tool_input = {} unless tool_input.is_a?(Hash)
+
+    bypassed = false
+    reason = RetrievalGate.decision(
+      tool_name: tool_name, tool_input: tool_input,
+      plastic_home: plastic_home, cwd: cwd,
+      capabilities: capabilities, reindex: reindex
+    ) { |_sig| bypassed = true }
+
+    if reason
+      [2, "PLASTIC GATE — #{reason}"]
+    elsif bypassed
+      [0, "PLASTIC GATE — bypassed via # qmd-ok"]
+    else
+      [0, nil]
+    end
+  rescue StandardError
+    [0, nil] # fail-open
+  end
+
+  def parse(raw)
+    data = JSON.parse(raw.to_s)
+    data.is_a?(Hash) ? data : nil
+  rescue StandardError
+    nil
+  end
+
+  # Detect real capabilities for the live executable. A slow `qmd status` cannot
+  # stall a tool call: a Timeout around the freshness probe degrades to "absent
+  # for this turn" (allow, no reindex), staying fail-open and non-blocking.
+  def detect_capabilities(cwd:)
+    qmd = QmdSync.detect
+    qmd_fresh = false
+    if qmd
+      qmd_fresh = begin
+        Timeout.timeout(2) { QmdSync.fresh? }
+      rescue StandardError
+        # Probe stalled/failed: treat as absent this turn (allow, no reindex).
+        qmd = false
+        false
+      end
+    end
+    serena = PowerTools.serena?(cwd: cwd)
+    { qmd: qmd, qmd_fresh: qmd_fresh, serena: serena }
+  end
+
+  # Best-effort reindex callable for the STALE path. Resolves the collection from
+  # cwd (project + global) and fires the async reindexer for each; never raises.
+  def reindex_for(cwd:, plastic_home:)
+    lambda do
+      begin
+        cols = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
+        cols.each { |c| QmdSync.reindex_async(collection: c) }
+      rescue StandardError
+        # non-fatal; the read is already allowed this turn
+      end
+    end
+  end
+end
+
+# --- executable entrypoint ---
+if $PROGRAM_NAME == __FILE__
+  raw = begin
+    $stdin.read
+  rescue StandardError
+    ""
+  end
+
+  plastic_home = (ARGV[0] && !ARGV[0].empty?) ? ARGV[0] : File.expand_path("~/.plastic")
+  cwd = Dir.pwd
+
+  code, err = begin
+    caps = RetrievalGateHook.detect_capabilities(cwd: cwd)
+    RetrievalGateHook.run(
+      stdin: raw, plastic_home: plastic_home, cwd: cwd,
+      capabilities: caps,
+      reindex: RetrievalGateHook.reindex_for(cwd: cwd, plastic_home: plastic_home)
+    )
+  rescue StandardError
+    [0, nil] # fail-open at the outermost boundary too
+  end
+
+  $stderr.puts(err) if err && !err.empty?
+  exit code
+end

package/scripts/hook-savepoint-pre

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# Usage: hook-savepoint-pre <file_path>
+#
+# PreToolUse savepoint trigger (intent 81). When a stage-opening lifecycle file
+# (spec.md => Why, plan.md => How) is ABOUT to be written into an intent dir,
+# append the pre-stage `started` ledger line so the ledger records "this stage
+# was entered" before its artifact lands.
+#
+# Like the PostToolUse decoupled savepoint write (intent 52), it is derived from
+# the file path alone: no bridge, no session, fires headless. It NEVER blocks a
+# write: any non-match or failure exits 0. The append is idempotent and only
+# fires while the stage is genuinely starting (the artifact is not yet a real,
+# non-placeholder file), so re-edits add nothing.
+
+require_relative "lib/bridge"
+
+file_path = ARGV[0]
+exit 0 if file_path.nil? || file_path.empty?
+
+file_path_abs = File.expand_path(file_path)
+intent_dir = Bridge.intent_dir_for(file_path_abs)
+exit 0 unless intent_dir
+
+begin
+  Bridge.append_started_savepoint(intent_dir, file_path_abs)
+rescue StandardError
+  # best-effort; the ledger is rebuildable and the post line still lands
+end
+
+exit 0