@zalom/plastic 1.0.0-beta.8 → 1.0.0

package/scripts/hook-gate-check

@@ -9,11 +9,12 @@
 require "json"
 require_relative "lib/bridge"
 require_relative "lib/intent_validator"
+require_relative "lib/lock"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
 file_path_abs = File.expand_path(file_path)
 
@@ -24,6 +25,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
@@ -66,6 +73,15 @@ intent_dir = "#{store}/#{dir}"
 # Normalize both paths for comparison
 bridge_intent_dir_abs = File.expand_path(intent_dir)
 
+# Lease heartbeat (intent 108, D1): every write by the session that owns (or
+# delegates under) the lock refreshes the delivery.lock mtime. Best-effort:
+# a heartbeat failure must never break the gate hook.
+begin
+  Lock.heartbeat(bridge_intent_dir_abs, session: session)
+rescue StandardError
+  # ignore
+end
+
 # Not inside intent dir = not our business
 exit 0 unless file_path_abs.start_with?("#{bridge_intent_dir_abs}/")
 
@@ -112,32 +128,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-lock-gate

@@ -0,0 +1,83 @@
+#!/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"
+require_relative "lib/lock"
+
+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 bridge cache
+  reason = Bridge.lock_gate_decision(bridge_data, file_path, session: session)
+  unless reason
+    # Allow path: refresh the lease for the session that holds this target's
+    # lock (owner or delegate). Best-effort, never blocks.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      Lock.heartbeat(dir, session: session) if dir && !session.to_s.empty?
+    rescue StandardError
+      # ignore
+    end
+
+    # Second, independent gate (intent 111 D7): the artifact-grain claim.
+    # Composes UNDER the delivery lock above; only reached once the delivery
+    # lock already allows. Dormant (nil) unless a claim file exists for this
+    # artifact, so AC7 (existing single-owner flows) is unaffected.
+    begin
+      dir = Bridge.intent_dir_for(file_path)
+      artifact = File.basename(file_path) if dir
+      if dir && artifact
+        claim_reason = Claim.claim_gate_reason(dir, artifact, session: session)
+        if claim_reason
+          print JSON.generate(
+            "hookSpecificOutput" => {
+              "hookEventName" => "PreToolUse",
+              "permissionDecision" => "deny",
+              "permissionDecisionReason" => claim_reason,
+            }
+          )
+          exit 0
+        end
+
+        # Fail-open surface (AC3): allow, but make the yielded/stale claim visible.
+        if Claim.fail_open?(dir, artifact)
+          $stderr.puts "plastic claim gate: unresolvable claim on #{artifact} in " \
+                       "intent #{Bridge.intent_id_from_dir(dir)} yielded; write " \
+                       "proceeds (see /plastic-lock status)"
+        end
+
+        # Heartbeat the session's own claim on the allow path (best-effort).
+        Claim.heartbeat(dir, artifact, session: session) rescue nil
+      end
+    rescue StandardError
+      # ignore: a claim-gate bug must never block a write (fail open)
+    end
+
+    exit 0
+  end
+
+  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/hook-retrieval-gate

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a;
+# ADVISORY since intent 108, D8). Reads the tool call (JSON on stdin: tool_name +
+# tool_input), computes capabilities (QMD detect + freshness), and delegates the
+# decision to RetrievalGate. It NEVER blocks: reads and searches always run
+# (exit 0). A store content search that QMD could serve better gets a QMD hint
+# via PreToolUse additionalContext on stdout. Hard gates guard writes, locks,
+# and structure; never reads.
+# 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).
+#
+# Only CONTENT SEARCH over store markdown gets the hint; reads and structural
+# ops stay silent. Code navigation is a soft prompt recommendation
+# (UserPromptSubmit power-tools), not handled here.
+#
+# 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"
+
+module RetrievalGateHook
+  module_function
+
+  # Pure-ish core: capabilities and reindex are injected so this is unit-testable
+  # with no real qmd. Returns [exit_code, stderr_string, stdout_json].
+  #   stdin: raw PreToolUse JSON
+  #   capabilities: { qmd:, qmd_fresh: }
+  #   reindex: callable fired on the STALE path
+  def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
+    payload = parse(stdin)
+    return [0, nil, 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
+      # Advisory (intent 108, D8): reads and searches are never denied. The
+      # would-block reason becomes a hint the agent sees alongside the result.
+      hint = JSON.generate(
+        "hookSpecificOutput" => {
+          "hookEventName" => "PreToolUse",
+          "additionalContext" =>
+            "PLASTIC advisory: #{reason} (this search ran; the hint is not a block)"
+        }
+      )
+      [0, nil, hint]
+    else
+      # The `# qmd-ok` bypass token is still accepted (bypassed is set), but
+      # with nothing to bypass it no longer announces itself.
+      [0, nil, nil]
+    end
+  rescue StandardError
+    [0, nil, 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. Probes are injected so the
+  # three-tier QMD failure model is unit-testable:
+  #   - absent  : QMD not on PATH                 -> allow, no warn.
+  #   - broken  : QMD present but freshness probe  -> tier-b: WARN once, then treat
+  #               raises/times out                   as absent this turn (allow).
+  #   - fresh   : probe returns truthy            -> gate is live.
+  # A slow `qmd status` cannot stall a tool call: a 2s Timeout bounds the probe.
+  def detect_capabilities(cwd:,
+                          detect: -> { QmdSync.detect },
+                          fresh: -> { QmdSync.fresh? },
+                          warn: ->(m) { $stderr.puts(m) })
+    qmd = detect.call
+    qmd_fresh = false
+    if qmd
+      begin
+        qmd_fresh = Timeout.timeout(2) { fresh.call }
+      rescue StandardError
+        # Tier-b: QMD is present but its freshness probe broke/stalled. Distinct
+        # from QMD being absent — warn so a degraded QMD is visible, then fail open
+        # (allow this turn, no reindex).
+        warn.call("PLASTIC GATE — QMD is present but its freshness probe failed; " \
+                  "allowing this turn without routing search to QMD (check qmd).")
+        qmd = false
+        qmd_fresh = false
+      end
+    end
+    { qmd: qmd, qmd_fresh: qmd_fresh }
+  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, out = 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, nil] # fail-open at the outermost boundary too
+  end
+
+  $stderr.puts(err) if err && !err.empty?
+  print out if out && !out.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

package/scripts/hook-session-start

@@ -48,7 +48,7 @@ bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
   intent_dir = "#{store_root}/store/#{dir_name}"
-  session = ENV["CLAUDE_SESSION_ID"] || Process.pid.to_s
+  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
   bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)

package/scripts/insight-append

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# insight-append - the blessed write path for an intent's `## Insights` section
+# (intent 82). A thin CLI wrapper over Insights.append_insight: it formats the
+# `{utc-iso8601} · {stage} · {author}` prefix, validates it, and appends one
+# entry at the bottom of the section (creating the section or file if absent).
+#
+# Sibling to scripts/spawn-preamble and scripts/agent-report. The library's
+# `now:` seam is the test seam; the CLI uses the default Time.now, which is fine
+# because determinism is covered at the library level (test/insights_test.rb).
+#
+# Usage:
+#   insight-append <intent_dir> <text> --stage S --author A
+#
+# Exit codes: 0 (entry appended), 2 (usage).
+
+require_relative "lib/insights"
+
+def parse_args(argv)
+  stage = nil
+  author = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--stage"
+      stage = argv[i + 1]
+      i += 2
+    when "--author"
+      author = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional[0], positional[1], stage, author]
+end
+
+intent_dir, text, stage, author = parse_args(ARGV)
+
+if [intent_dir, text, stage, author].any? { |v| v.nil? || v.to_s.empty? }
+  warn "usage: insight-append <intent_dir> <text> --stage S --author A"
+  exit 2
+end
+
+entry = Insights.append_insight(File.expand_path(intent_dir), text,
+                                stage: stage, author: author)
+puts "appended: #{entry}"

package/scripts/install.rb

@@ -14,6 +14,7 @@
 # so install.rb is the single file-syncer; the ledger action is contextual.
 
 require_relative "lib/installer_core"
+require_relative "lib/preflight"
 
 class Install < InstallerCore
   def cli(argv = ARGV)
@@ -22,6 +23,9 @@ class Install < InstallerCore
       return 0
     end
 
+    gate = preflight_gate
+    return gate unless gate.zero?
+
     force = argv.include?("--force")
     reinstall = argv.include?("--reinstall")
     ledger_action = flag_value(argv, "--ledger-action")
@@ -42,19 +46,19 @@ class Install < InstallerCore
       return 1
     end
 
-    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action)
+    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
     0
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil)
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
 
-    results = selected.map { |key| install_for_agent(key, force) }
+    results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -72,8 +76,37 @@ class Install < InstallerCore
     File.exist?(path) ? File.read(path).strip : nil
   end
 
+  # Injectable pre-flight gate: real probes as default args, printing to an
+  # injectable `out:` IO so this is hermetically testable via StringIO. Returns
+  # 1 (stop the install) when Ruby is missing/too-old, else 0.
+  def preflight_gate(ruby_version: RUBY_VERSION, node_version: node_probe, git_present: git_probe,
+                      mise_present: mise_probe, out: $stderr)
+    result = Preflight.check(ruby_version: ruby_version, node_version: node_version,
+                              git_present: git_present, mise_present: mise_present)
+    result[:messages].each { |message| out.puts(message) }
+    result[:fatal] ? 1 : 0
+  end
+
   private
 
+  def node_probe
+    `node --version`.strip
+  rescue StandardError
+    ""
+  end
+
+  def git_probe
+    !`command -v git`.strip.empty?
+  rescue StandardError
+    false
+  end
+
+  def mise_probe
+    !`command -v mise`.strip.empty?
+  rescue StandardError
+    false
+  end
+
   def flag_value(argv, name)
     i = argv.index(name)
     return nil unless i && argv[i + 1]
@@ -96,7 +129,8 @@ class Install < InstallerCore
     verb = mode == :reinstall ? "re-synced" : "installed"
     puts "\n\u{2705} Plastic v#{version} #{verb}."
     puts "   Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
-    puts "   Run /clear (or restart your agent) to pick up new conventions.\n\n"
+    puts "   Run /clear (or restart your agent) to pick up new conventions."
+    puts "   Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
   end
 
   def show_help
@@ -119,9 +153,12 @@ class Install < InstallerCore
         --alpha       Alpha channel
 
       Other options:
-        --reinstall   Re-sync core files for the installed version (repair). Store untouched.
-        --force       Overwrite existing files without prompting
-        -h, --help    Show this help
+        --reinstall          Re-sync core files for the installed version (repair). Store untouched.
+        --force              Overwrite existing files without prompting
+        --statusline VALUE   keep or plastic. If an existing statusline is found, this
+                             skips the interactive prompt. Interactive sessions ask by
+                             default; non-interactive sessions default to keep.
+        -h, --help           Show this help
 
       Notes:
         Install is one-shot. If Plastic is already installed, use `update` to upgrade or

package/scripts/lib/agent_models.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Shared model-tier resolution for Plastic subagents (intent 116).
+#
+# TIER_DEFAULTS mirrors the shipped `agents/*.md` frontmatter so `read-config`
+# can answer `agents.models.<basename>` with the built-in default. The installer
+# does NOT use TIER_DEFAULTS: it applies only genuine config overrides via
+# `override_map`, so shipped frontmatter with no override passes through
+# unchanged.
+module AgentModels
+  # Claude Code aliases only (never pinned ids, never Fable). Keys are the agent
+  # file basenames without the `.md` extension.
+  TIER_DEFAULTS = {
+    "plastic-enforcer" => "opus",
+    "plastic-brainstorming" => "opus",
+    "plastic-planner" => "opus",
+    "plastic-spec-specialist" => "sonnet",
+    "plastic-executor" => "sonnet",
+    "plastic-intent-curator" => "sonnet",
+    "plastic-future-intent-researcher" => "sonnet",
+    "plastic-intent-discovery" => "sonnet"
+  }.freeze
+
+  module_function
+
+  # Pull the `agents.models` sub-hash out of a loaded config hash, tolerating a
+  # missing or malformed shape. Returns a plain { basename => model } hash.
+  def models_section(config)
+    return {} unless config.is_a?(Hash)
+    agents = config["agents"]
+    return {} unless agents.is_a?(Hash)
+    section = agents["models"]
+    section.is_a?(Hash) ? section : {}
+  end
+
+  # Override map for the installer: global overrides overlaid by project
+  # overrides (project wins). Defaults are intentionally excluded. Unknown agent
+  # keys are carried through as-is; install_agents simply never matches them to a
+  # copied file, so they are ignored without raising.
+  def override_map(project_config: {}, global_config: {})
+    models_section(global_config).merge(models_section(project_config))
+  end
+end