@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/scripts/lib/dashboard_banner.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Renders a one-line dashboard summary for the hook-owned systemMessage floor
+# (intent 125, Task 6). Pure and dependency-injected, mirroring BootBanner: it
+# takes the already-parsed `dashboard.rb continue --data` JSON payload and
+# returns a single line, with no file I/O and no subprocess calls in here, so
+# it is unit-testable in isolation while the hook feeds it real data.
+module DashboardBanner
+  module_function
+
+  # payload: the Hash from JSON.parse(`dashboard.rb continue --data`), or nil
+  #          when the subprocess call failed or produced unusable JSON.
+  #
+  # Returns a single summary line, or nil when the payload has nothing usable
+  # (the caller degrades silently in that case, omitting systemMessage).
+  def render(payload)
+    return nil unless payload.is_a?(Hash)
+    counts = payload["counts"]
+    return nil unless counts.is_a?(Hash)
+    active = counts["active"].to_i
+    future = counts["future"].to_i
+    line = "Plastic: #{active} active · #{future} next · run /plastic-dashboard to see the board"
+    nbt = next_big_thing_id(payload)
+    line += " · next big thing: #{nbt}" if nbt
+    line
+  end
+
+  # The id of the top-ranked next_big candidate, when the payload's matrix carries
+  # exactly the shape dashboard.rb emits (a "next_big" list of {id, ...} hashes,
+  # already rank-sorted). Returns nil for any other shape rather than raising.
+  def next_big_thing_id(payload)
+    matrix = payload["matrix"]
+    return nil unless matrix.is_a?(Hash)
+    list = matrix["next_big"]
+    return nil unless list.is_a?(Array) && !list.empty?
+    top = list.first
+    return nil unless top.is_a?(Hash)
+    id = top["id"].to_s
+    id.empty? ? nil : id
+  end
+end

package/scripts/lib/hook_registry.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# HookRegistry: THE single source of truth for Plastic's hook registration
+# (intent 108, D7). Three consumers, none of which may hand-roll matchers:
+#   - InstallerCore#merge_claude_hooks builds settings.json entries from it
+#   - hooks/hooks.json (legacy plugin surface) is pinned to it by test
+#   - doctor's hooks_match_registry check compares live settings against it
+# Change registrations HERE and only here.
+module HookRegistry
+  module_function
+
+  # MCP tools that MUTATE files. Every write/lock/create gate must match them,
+  # or symbolic edits bypass the whole gate layer (the universal MCP-edit
+  # bypass found in 108's gate inventory).
+  SERENA_EDIT_TOOLS = %w[
+    mcp__serena__replace_content
+    mcp__serena__replace_symbol_body
+    mcp__serena__insert_after_symbol
+    mcp__serena__insert_before_symbol
+    mcp__serena__safe_delete_symbol
+    mcp__serena__rename_symbol
+  ].freeze
+
+  WRITE_MATCHER = (%w[Write Edit NotebookEdit] + SERENA_EDIT_TOOLS).join("|")
+  CREATE_MATCHER = (%w[Write Edit] + SERENA_EDIT_TOOLS).join("|")
+
+  # event => ordered list of { "matcher" =>, "hooks" => [{ "name" =>, "status" => }] }
+  # The name is the hooks/<name> launcher; the flat install ships it as
+  # ~/.claude/hooks/plastic-<name>.
+  def events
+    {
+      "SessionStart" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "session-start", "status" => "Loading Plastic context..." },
+          { "name" => "check-update", "status" => "" },
+        ] },
+      ],
+      "PreCompact" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "savepoint", "status" => "Saving Plastic intent state..." },
+        ] },
+      ],
+      "PreToolUse" => [
+        { "matcher" => WRITE_MATCHER, "hooks" => [
+          { "name" => "code-gate", "status" => "Checking lifecycle gate..." },
+          { "name" => "lock-gate", "status" => "Checking lock gate..." },
+        ] },
+        { "matcher" => "Write|Edit", "hooks" => [
+          { "name" => "savepoint-pre", "status" => "Recording stage start..." },
+        ] },
+        { "matcher" => CREATE_MATCHER, "hooks" => [
+          { "name" => "create-gate", "status" => "Checking create gate..." },
+        ] },
+        { "matcher" => "Bash", "hooks" => [
+          { "name" => "bash-gate", "status" => "Checking lifecycle gate..." },
+        ] },
+        { "matcher" => "Bash|Read|Grep|Glob", "hooks" => [
+          { "name" => "retrieval-gate", "status" => "Checking retrieval gate..." },
+        ] },
+      ],
+      "PostToolUse" => [
+        { "matcher" => "Write|Edit", "hooks" => [
+          { "name" => "gate-check", "status" => "Checking lifecycle gates..." },
+        ] },
+      ],
+      "UserPromptSubmit" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "continue", "status" => "Checking for continue..." },
+          { "name" => "future-intent-check", "status" => "Checking future intents..." },
+          { "name" => "auto-arm", "status" => "Checking auto mode..." },
+          { "name" => "qmd-search", "status" => "Searching QMD..." },
+        ] },
+      ],
+    }
+  end
+
+  # The settings.json shape merge_claude_hooks expects: single-group events map
+  # to a Hash, multi-group events to an Array (the merge loop handles both).
+  def claude_settings_hooks(hook_dir:)
+    events.each_with_object({}) do |(event, groups), out|
+      mapped = groups.map do |g|
+        {
+          "matcher" => g["matcher"],
+          "hooks" => g["hooks"].map do |h|
+            { "type" => "command",
+              "command" => File.join(hook_dir, "plastic-#{h['name']}"),
+              "statusMessage" => h["status"] }
+          end,
+        }
+      end
+      out[event] = mapped.length == 1 ? mapped.first : mapped
+    end
+  end
+end

package/scripts/lib/insights.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+# insights.rb - the blessed write path for an intent's `## Insights` section
+# (intent 82). A sibling library to bridge.rb so the insight write path stays
+# independent of the savepoint ledger (the spec forbids touching the ledger).
+#
+# Every entry leads with a fixed, machine-parseable prefix
+# `{utc-iso8601} · {stage} · {author}` where the timestamp is `now.utc.iso8601`,
+# the SAME convention `Bridge.append_savepoint_line` uses, so the store has one
+# timestamp convention across both ledgers. Entries are append-only, newest at
+# the BOTTOM (the [[34]] ordering law): the per-entry prefix is not prepending
+# the entry, and existing entries are never reordered.
+
+require "time"
+require_relative "bridge"
+
+module Insights
+  HEADING = "## Insights"
+  # The middle dot (U+00B7) with a single space on each side separates the
+  # timestamp, stage, and author fields.
+  SEPARATOR = " · "
+  # A well-formed prefix: UTC ISO8601 timestamp to the second with a trailing
+  # `Z`, then a non-empty stage, then a non-empty author, each ` · `-separated.
+  PREFIX_RE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z · [^·]+ · [^·]+/.freeze
+
+  # Append one insight entry at the BOTTOM of the `## Insights` section of the
+  # intent file, creating the section (or the file) if absent. `now:` is the DI
+  # seam: defaults to Time.now, tests inject Time.utc(...). Raises ArgumentError
+  # if the assembled prefix is not well-formed (guard on write).
+  def self.append_insight(intent_dir, text, stage:, author:, now: Time.now)
+    prefix = "#{now.utc.iso8601}#{SEPARATOR}#{stage}#{SEPARATOR}#{author}"
+    unless valid_insight_prefix?(prefix)
+      raise ArgumentError, "malformed insight prefix: #{prefix.inspect}"
+    end
+
+    entry = "#{prefix} — #{text}"
+    path = Bridge.intent_file(intent_dir)
+    File.write(path, with_entry(File.exist?(path) ? File.read(path) : "", entry))
+    entry
+  end
+
+  # Pure validator: true when `line` begins with a well-formed prefix. No IO,
+  # no clock. Rejects a date-only prefix, a missing separator, a missing `Z`,
+  # and sub-second precision.
+  def self.valid_insight_prefix?(line)
+    line.is_a?(String) && line.match?(PREFIX_RE)
+  end
+
+  # Insert `entry` at the bottom of the `## Insights` section of `content`,
+  # preserving every existing line and their order. Pure string transform.
+  def self.with_entry(content, entry)
+    lines = content.empty? ? [] : content.split("\n", -1)
+    heading_idx = lines.index { |l| l.strip == HEADING }
+    return append_new_section(lines, entry) if heading_idx.nil?
+
+    insert_at = section_end(lines, heading_idx)
+    lines.insert(insert_at, entry)
+    lines.join("\n")
+  end
+
+  # The insertion index for a new entry: just after the last non-empty content
+  # line that belongs to the `## Insights` section (before the next `## `
+  # heading or EOF).
+  def self.section_end(lines, heading_idx)
+    last_content = heading_idx
+    idx = heading_idx + 1
+    while idx < lines.length
+      break if lines[idx].start_with?("## ")
+
+      last_content = idx unless lines[idx].strip.empty?
+      idx += 1
+    end
+    last_content + 1
+  end
+
+  # Append a fresh `## Insights` section (blank line, heading, entry) to the end
+  # of the existing content.
+  def self.append_new_section(lines, entry)
+    body = lines.join("\n")
+    body = body.sub(/\n+\z/, "") unless body.empty?
+    pieces = body.empty? ? [] : [body, ""]
+    pieces << HEADING << entry
+    "#{pieces.join("\n")}\n"
+  end
+end

package/scripts/lib/installer_core.rb

@@ -6,6 +6,8 @@ require "yaml"
 require "fileutils"
 require "digest"
 require "time"
+require_relative "hook_registry"
+require_relative "agent_models"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/versions) and their tests can run
@@ -159,6 +161,37 @@ class InstallerCore
     nums.select { |n| n >= 1 && n <= agents.size }.map { |n| agents[n - 1][:key] }
   end
 
+  # Resolve whether install should keep the user's existing statusline or switch it
+  # to Plastic's. Pure function of (settings file, argv, input, reinstall): no writes,
+  # so it stays fully unit-testable apart from merge_claude_hooks.
+  def statusline_choice(settings_path, argv: [], input: $stdin, reinstall: false)
+    existing_command = read_json_safe(settings_path)&.dig("statusLine", "command").to_s
+    return :plastic if existing_command.empty?
+    return :plastic if existing_command.include?("plastic-")
+
+    idx = argv.index("--statusline")
+    flag = idx && argv[idx + 1]
+    return flag.to_sym if %w[keep plastic].include?(flag)
+
+    return :keep if reinstall
+    return prompt_statusline(input: input) if input.tty?
+
+    :keep
+  end
+
+  def prompt_statusline(input: $stdin)
+    return :keep unless input.tty?
+
+    puts "An existing statusline was found in your settings.\n\n"
+    puts "  1. Keep my statusline (Plastic will not change it)"
+    puts "  2. Switch to Plastic's statusline"
+    puts
+    print "Select (1 or 2, Enter to keep): "
+    answer = input.gets&.strip
+
+    answer == "2" ? :plastic : :keep
+  end
+
   # --- Distribution phase ---
 
   def distribute(mode)
@@ -195,6 +228,7 @@ class InstallerCore
   def core_files
     {
       "PLASTIC.md" => "PLASTIC.md",
+      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",
@@ -203,14 +237,26 @@ class InstallerCore
       "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-savepoint-pre" => "scripts/hook-savepoint-pre",
       "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
+      "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.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",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
+      "scripts/plastic-lock" => "scripts/plastic-lock",
+      "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/agent-report" => "scripts/agent-report",
+      "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
+      "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
+      "scripts/lib/dashboard_banner.rb" => "scripts/lib/dashboard_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
@@ -218,6 +264,10 @@ class InstallerCore
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
       "scripts/lib/links_projection.rb" => "scripts/lib/links_projection.rb",
       "scripts/lib/links_section.rb" => "scripts/lib/links_section.rb",
+      "scripts/lib/link_suggestions.rb" => "scripts/lib/link_suggestions.rb",
+      "scripts/project-links" => "scripts/project-links",
+      "scripts/link-suggest" => "scripts/link-suggest",
+      "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
@@ -226,10 +276,12 @@ 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",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
+      "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
@@ -302,7 +354,7 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
-  def install_for_agent(key, force)
+  def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
 
@@ -315,7 +367,7 @@ class InstallerCore
     old_files = manifest_files(manifest_path_for(key, config))
 
     result = case key
-             when "claude" then install_claude(config, force)
+             when "claude" then install_claude(config, force, argv: argv, input: input, reinstall: reinstall)
              when "codex" then install_codex(config, force)
              when "hermes" then install_hermes(config, force)
              end
@@ -344,7 +396,7 @@ class InstallerCore
     removed
   end
 
-  def install_claude(config, force)
+  def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")
     plastic_dir = File.join(config[:dir], "plastic")
@@ -375,7 +427,7 @@ class InstallerCore
     installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
 
     # Copy agent role files into <dir>/agents (manifest-tracked, pruned on update)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
@@ -387,7 +439,8 @@ class InstallerCore
 
     # Merge hooks + statusline into settings.json (no plugin registration)
     settings_path = File.join(config[:dir], "settings.json")
-    merge_claude_hooks(settings_path)
+    choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
+    merge_claude_hooks(settings_path, choice: choice)
 
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
@@ -400,7 +453,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -410,7 +463,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -443,18 +496,51 @@ class InstallerCore
   # equivalents). Returns the installed destination paths so callers can append
   # them to `installed` before write_manifest (manifest + prune are then automatic).
   # No-op safe: returns [] when the package has no agents dir or it is empty.
-  def install_agents(agents_root)
+  def install_agents(agents_root, models: {})
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
     FileUtils.mkdir_p(agents_root)
     sources.map do |src|
       dest = File.join(agents_root, File.basename(src))
-      FileUtils.cp(src, dest)
+      basename = File.basename(src, ".md")
+      override = models[basename]
+      if override
+        File.write(dest, rewrite_model_line(File.read(src), override))
+      else
+        FileUtils.cp(src, dest)
+      end
       dest
     end
   end
 
+  # Rewrite the single top-level `model:` line in a YAML frontmatter block.
+  # Only the frontmatter (between the first two `---` fences) is touched.
+  def rewrite_model_line(content, model)
+    content.sub(/^model:[^\n]*$/, "model: #{model}")
+  end
+
+  # Resolve per-agent model overrides for this install: project config (when a
+  # project dir is known) overlaid on global config. Defaults are NOT included,
+  # so unconfigured agents keep their shipped frontmatter.
+  def agent_model_overrides(project_dir = nil)
+    global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
+    project_config =
+      if project_dir
+        load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml"))
+      else
+        {}
+      end
+    AgentModels.override_map(project_config: project_config, global_config: global_config)
+  end
+
+  def load_config_yaml(path)
+    return {} unless File.exist?(path)
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
   # --- Legacy plugin migration ---
 
   # Earlier versions registered Plastic as a local marketplace plugin
@@ -520,7 +606,7 @@ class InstallerCore
 
   # --- settings.json merge (read-modify-write, never clobber) ---
 
-  def merge_claude_hooks(settings_path)
+  def merge_claude_hooks(settings_path, choice: :plastic)
     settings = read_json_safe(settings_path) || {}
     return if settings.nil?
 
@@ -529,55 +615,9 @@ class InstallerCore
 
     purge_stale_plastic_hooks(hooks)
 
-    plastic_hooks = {
-      "SessionStart" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-session-start", "statusMessage" => "Loading Plastic context..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-check-update", "statusMessage" => "" },
-        ],
-      },
-      "PreCompact" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-savepoint", "statusMessage" => "Saving Plastic intent state..." },
-        ],
-      },
-      # PreToolUse carries TWO plastic groups with distinct matchers: the
-      # code-gate (Write|Edit|NotebookEdit) and the create-gate (Write only, intent
-      # 60b). A single group cannot carry two matchers, so this event maps to a
-      # LIST of groups; the merge loop appends each (idempotent because the purge
-      # pass removes all prior plastic groups first).
-      "PreToolUse" => [
-        {
-          "matcher" => "Write|Edit|NotebookEdit",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
-          ],
-        },
-        {
-          "matcher" => "Write",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-create-gate", "statusMessage" => "Checking create gate..." },
-          ],
-        },
-      ],
-      "PostToolUse" => {
-        "matcher" => "Write|Edit",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-gate-check", "statusMessage" => "Checking lifecycle gates..." },
-        ],
-      },
-      "UserPromptSubmit" => {
-        "matcher" => "",
-        "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..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-qmd-search", "statusMessage" => "Searching QMD..." },
-        ],
-      },
-    }
+    # Single source of truth (intent 108, D7): registrations live in
+    # HookRegistry; this merge only translates them into settings.json.
+    plastic_hooks = HookRegistry.claude_settings_hooks(hook_dir: hook_dir)
 
     plastic_hooks.each do |event, group|
       hooks[event] ||= []
@@ -608,7 +648,7 @@ class InstallerCore
       File.write(File.join(cache_dir, "original-statusline.json"), JSON.pretty_generate(existing_status))
     end
 
-    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" }
+    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" } if choice == :plastic
 
     # No plugin/marketplace registration: skills are flat personal skills
     # (plastic-<name>/) discovered directly from ~/.claude/skills.