@zalom/plastic 1.3.0 → 1.4.0

package/PLASTIC-reference.md

@@ -67,16 +67,18 @@ root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the glob
 in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
 a sibling subdirectory scaffolded once with a `.gitkeep`.
 
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Batches`, and an
 append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
-waves run sequentially, top to bottom.
+an executable checker. `## Batches` holds ordered batches; entries inside a batch are
+parallel-safe, batches run sequentially, top to bottom. A roadmap written before owner ruling 145
+may instead use the legacy `## Waves` heading; the tooling accepts both, but never renames an
+existing roadmap file to migrate it.
 
-Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+Each batch entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
 that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
 on any conflict INDEX wins and the roadmap entry is corrected to match.
 
-**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
+**Human-comprehension surface.** A roadmap is also written to be read cold. Batch entries render as
 checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
 line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
 engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
@@ -86,7 +88,7 @@ opening the file with no other context can tell what shipped, what is running no
 next in under a minute.
 
 **Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
-loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
+loop is its runtime. Batches lay out the parallelism plan: what can run together, and in what order.
 Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
 running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
 after a stop. This section only states the relationship and points to intent 69 as the future

package/PLASTIC.md

@@ -456,9 +456,10 @@ Advisory. Hard gates guard writes, locks, and structure, never reads or searches
 Grep, Glob, and bash search are always allowed, including over the stores. When QMD is
 present and fresh, a content search over store markdown receives an advisory hint pointing
 at `qmd search` alongside its result; when QMD is present but stale, a background reindex
-fires so the next turn's hint runs against a fresh index (never synchronous). QMD and
-Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook appends
-one recommendation line per present tool. The legacy trailing `# qmd-ok` token is still
+fires so the next turn's hint runs against a fresh index (never synchronous). QMD, Enola,
+and Serena are recommendations, not obligations: the UserPromptSubmit power-tools hook
+appends one recommendation line per present tool, naming Enola only, not both, when Enola
+and Serena are both present (Enola-first, one code-navigation slot). The legacy trailing `# qmd-ok` token is still
 accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
 calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
@@ -603,6 +604,14 @@ purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Work
 -> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
 ever referencing a bridge or lock that disarm is about to remove.
 
+`scripts/end-intent` performs this order's disarm step (verify the code worktree is clean,
+then merge/remove worktrees, then clear the lock) as its own step 5, mechanically, since
+intent 188: a session no longer needs a separate one-liner for it, and the script's own
+exit code (0) is the single fact a caller needs that the intent is closed AND its delivery
+lock is gone. A pre-flight lock guard runs before anything is written (refuses a live
+foreign session, reclaims a stale one with an audit line), and a dirty code worktree
+refuses before removal rather than force-discarding uncommitted changes.
+
 The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
 the completing session keeps full read and write access to the terminal directory and no
 purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
@@ -621,6 +630,18 @@ always allowed and unbounded (curator reindex, dashboards, and future intents th
 its id or chain), so a done intent stays fully readable forever. Intent 93 states this rule;
 intent 112 builds the gate that enforces it.
 
+Restore-to-v1 (the owner rule that a completed intent is immutable: a late ruling goes to a
+new `--parent` branch intent, and the completed intent is restored to v1) is performed ONLY by
+`scripts/restore-intent-v1`, run under the maintenance lock. Its prose (the intent narrative,
+checklist.md, outcome.md, spec.md, plan.md) is immutable and reverts to v1; its frontmatter
+graph (`sources`/`chain`) is metadata about OTHER intents, not content of this one, and is
+APPEND-ONLY: it is preserved as the union of the v1 snapshot and the current snapshot, never
+subtracted. A hand-run whole-file `git checkout`/revert of a completed intent is FORBIDDEN,
+because it cannot distinguish prose from graph metadata and silently destroys backlinks written
+after v1 (proven on intent 124: a legitimately accrued chain edge was destroyed by a hand-run
+restore and went undetected for a week). This governs the restore mechanism only; it does not
+loosen terminal immutability itself.
+
 Fail-safe lock doctrine (the contract intent 111 implements): the lock system never traps a
 session or burns credits. When a gate cannot verify lock integrity it fails open, degrading
 to advisory (warn) rather than hard-blocking. Repair is orchestrator-driven: on a lock-issue

package/hooks/hooks.json

@@ -52,6 +52,11 @@
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" savepoint-pre",
             "statusMessage": "Recording stage start..."
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" links-gate",
+            "statusMessage": "Checking Links gate..."
           }
         ]
       },

package/hooks/links-gate

@@ -0,0 +1,3 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-links-gate"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/doctor.rb

@@ -18,6 +18,7 @@ require "digest"
 require_relative "lib/qmd_sync"
 require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
+require_relative "lib/store_discovery"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
 require_relative "lib/hook_registry"
@@ -26,6 +27,7 @@ require_relative "lib/bridge"
 require_relative "lib/agent_models"
 require_relative "lib/legacy_bookend_amnesty"
 require_relative "lib/skill_lint"
+require_relative "lib/config_asks"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -228,33 +230,38 @@ class Doctor
     end
   end
 
+  # Single source of truth for "what stores exist" (intent 189), shared with
+  # rebuild-graph, project-links, and new-intent via StoreDiscovery. Memoized: one Doctor
+  # instance runs many checks against the same plastic_home in a single pass.
+  def store_discovery
+    @store_discovery ||= StoreDiscovery.discover(plastic_home)
+  end
+
   def all_intent_dirs
     dirs = []
-
-    global_store = File.join(plastic_home, "store")
-    if File.directory?(global_store)
-      store_intent_dirs(global_store).each do |entry|
-        full = File.join(global_store, entry)
-        dirs << { path: full, name: entry, scope: "global" }
-      end
-    end
-
-    projects_root = File.join(plastic_home, "projects")
-    if File.directory?(projects_root)
-      Dir.children(projects_root).each do |project|
-        project_store = File.join(projects_root, project, "store")
-        next unless File.directory?(project_store)
-
-        store_intent_dirs(project_store).each do |entry|
-          full = File.join(project_store, entry)
-          dirs << { path: full, name: entry, scope: "project:#{project}" }
-        end
+    store_discovery[:stores].each do |s|
+      store_intent_dirs(s[:store]).each do |entry|
+        full = File.join(s[:store], entry)
+        dirs << { path: full, name: entry, scope: s[:key] }
       end
     end
-
     dirs
   end
 
+  # A store_index Hash seeded with EVERY store StoreDiscovery reports, mapping a
+  # store with zero intents to [] rather than leaving its key absent. Mirrors
+  # RebuildGraph#run and ProjectLinks#run, which both set `store_index[key] =
+  # nodes.keys` for every discovered store (empty array for an empty store). Without
+  # this seed, a store_index built only from intents that parse has no key for a
+  # freshly provisioned, still-empty store, so GraphRebuild.classify calls it
+  # :unknown_store instead of :dead, disagreeing with the repair tools about the
+  # same ref (intent 189 review, finding 1).
+  def seeded_store_index
+    idx = Hash.new { |h, k| h[k] = [] }
+    store_discovery[:stores].each { |s| idx[s[:key]] }
+    idx
+  end
+
   # --- Check category 1: Global store ---
 
   def check_global_store
@@ -432,12 +439,13 @@ class Doctor
     # well-formed arrays of id strings). Delegates to IntentValidator so the
     # born-complete contract is defined in exactly one place. Read-only: shape
     # repair is not a single-field inject, so this check is not fixable here.
+    known_stores = store_discovery[:stores].map { |s| s[:slug] }
     malformed = []
     intent_dirs.each do |d|
       md_path = File.join(d[:path], "#{d[:name]}.md")
       next unless File.exist?(md_path)
 
-      result = IntentValidator.validate_frontmatter(parse_frontmatter(md_path))
+      result = IntentValidator.validate_frontmatter(parse_frontmatter(md_path), known_stores: known_stores)
       shape_errors = result[:errors].select { |e| e.include?("must be an array") || e.include?("invalid id") }
       malformed << { dir: tilde(d[:path]), errors: shape_errors } unless shape_errors.empty?
     end
@@ -750,7 +758,7 @@ class Doctor
   def links_projection_check(scopes: nil)
     all_dirs = all_intent_dirs
 
-    store_index = Hash.new { |h, k| h[k] = [] }
+    store_index = seeded_store_index
     node_index = Hash.new { |h, k| h[k] = {} }
     intents = [] # { scope:, id:, sources:, chain:, path: }
 
@@ -803,7 +811,11 @@ class Doctor
     graph_finding_check(
       "graph_links_projection", findings,
       "Every intent's ## Links equals its frontmatter projection (membership and ordering)",
-      "Run scripts/project-links to regenerate the canonical ## Links sections"
+      "Run scripts/project-links to regenerate the canonical ## Links sections. By default " \
+      "it PRESERVES any line unbacked by frontmatter that still resolves to a real intent " \
+      "(reported as an orphan candidate, never silently deleted); add the missing " \
+      "sources/chain edge if the relationship is real, or pass --drop-unbacked-links to " \
+      "delete an orphan candidate deliberately."
     )
   end
 
@@ -829,7 +841,7 @@ class Doctor
 
     # Per-scope node maps + store_index over the WHOLE family.
     nodes_by_scope = Hash.new { |h, k| h[k] = {} }
-    store_index = Hash.new { |h, k| h[k] = [] }
+    store_index = seeded_store_index
     all_dirs.each do |d|
       md = File.join(d[:path], "#{d[:name]}.md")
       next unless File.exist?(md)
@@ -860,6 +872,9 @@ class Doctor
                                                 relocation_map: relocation_map,
                                                 store_index: store_index)
             case res[:status]
+            when :unknown_store
+              findings << "#{id}.#{field} cross-store ref #{ref} names a store this scan does " \
+                          "not recognize (#{res[:store]}); left untouched, verify store discovery"
             when :dead
               findings << "#{id}.#{field} cross-store ref #{ref} resolves to no intent (dead)"
             when :same_store
@@ -880,18 +895,12 @@ class Doctor
   end
 
   # { store_key => INDEX.md text } for every store (global + all projects), for the
-  # relocation-map builder. Reads INDEX.md one level above each store dir.
+  # relocation-map builder. Sourced from the same StoreDiscovery list all_intent_dirs
+  # uses, so the two can never enumerate a different set of stores.
   def cross_store_index_texts
     texts = {}
-    global_index = File.join(plastic_home, "INDEX.md")
-    texts["global"] = File.read(global_index) if File.exist?(global_index)
-
-    projects_root = File.join(plastic_home, "projects")
-    if File.directory?(projects_root)
-      Dir.children(projects_root).each do |project|
-        idx = File.join(projects_root, project, "INDEX.md")
-        texts["project:#{project}"] = File.read(idx) if File.exist?(idx)
-      end
+    store_discovery[:stores].each do |s|
+      texts[s[:key]] = File.read(s[:index]) if File.exist?(s[:index])
     end
     texts
   end
@@ -1489,25 +1498,51 @@ class Doctor
   end
 
   # agent_model_drift - advisory (never fail) config-vs-frontmatter comparison
-  # for every installed <agent_dir>/agents/plastic-*.md file (intent 170, D1).
-  # Resolution mirrors read-config's own precedence (project override -> global
-  # override -> shipped AgentModels::TIER_DEFAULTS), reusing AgentModels'
-  # `override_map` directly so this stays hermetically DI-testable (no
-  # shell-out to `read-config`, no ENV/global seam). There is no live project
-  # scope at doctor-run time for a globally-installed agent file, so the
-  # project layer is empty here; the resolver still supports one, matching the
-  # same `override_map(project_config:, global_config:)` shape the installer
-  # already calls.
+  # for every installed <agent_dir>/agents/plastic-*.md file (intent 170, D1;
+  # reclassified intent 191). Resolution mirrors read-config's own precedence
+  # (project override -> global override -> shipped AgentModels::TIER_DEFAULTS),
+  # reusing AgentModels' `override_map` directly so this stays hermetically
+  # DI-testable (no shell-out to `read-config`, no ENV/global seam). There is
+  # no live project scope at doctor-run time for a globally-installed agent
+  # file, so the project layer is empty here; the resolver still supports one,
+  # matching the same `override_map(project_config:, global_config:)` shape
+  # the installer already calls.
   #
-  # Classification per installed agent basename:
-  #   - no `agents.models.<basename>` override AND frontmatter == resolved
-  #     default -> pass (clean)
-  #   - no override AND frontmatter != resolved default -> warn (real drift)
-  #   - an override IS configured -> pass/informational, LISTED as a
-  #     sanctioned override, regardless of whether frontmatter matches (that
-  #     mismatch is the override working, e.g. `plastic-brainstorming: fable`)
+  # This check deliberately never diffs installed frontmatter against the
+  # shipped agents/*.md source tree directly (considered and rejected, intent
+  # 191): at real doctor run time doctor.rb lives at ~/.plastic/scripts/doctor.rb,
+  # and the installer copies only scripts/ into ~/.plastic, never the agents/
+  # tree, so a "compare against shipped frontmatter" check would find nothing
+  # in the field and pass silently on every real installation while only ever
+  # exercising itself inside the repo, the same dead-in-production shape
+  # already documented above check_skill_lint. The only registry of sanctioned
+  # defaults reachable at doctor run time is scripts/lib/agent_models.rb (it
+  # IS copied into ~/.plastic/scripts/lib), so this check classifies each
+  # installed basename using ONLY the two registries that module already
+  # ships, TIER_DEFAULTS and CONSULTATION_AGENTS. No new model values are
+  # added anywhere.
+  #
+  # Classification per installed agent basename, checked in this order:
+  #   1. an `agents.models.<basename>` override IS configured -> sanctioned,
+  #      pass/informational, LISTED regardless of whether frontmatter matches
+  #      (that mismatch is the override working, e.g. plastic-brainstorming: fable).
+  #   2. no override AND basename is a TIER_DEFAULTS key -> compare frontmatter
+  #      to that default; match is pass (clean), mismatch is real drift (warn).
+  #   3. no override AND basename is a CONSULTATION_AGENTS member -> not a
+  #      lifecycle stage role (intent 185); its model is user configuration by
+  #      contract (PLASTIC.md: "their models are user configuration"), so this
+  #      check does not compare and does not warn, it only lists the agent
+  #      informationally as a consultation role.
+  #   4. no override AND basename is in NEITHER registry -> unclassified. This
+  #      check has no ground truth for this agent, so it does not claim
+  #      "drift vs default nil" (that claim would be false); it reports,
+  #      advisory warn, that the agent is present in the installed agents dir
+  #      but absent from both registries in scripts/lib/agent_models.rb, and
+  #      names that file as the place to add it. Setting an
+  #      agents.models.<basename> override also silences this line, by
+  #      routing the agent through bucket 1.
   #   - zero installed agent files -> pass (nothing to check)
-  # This check never returns "fail".
+  # This check never returns "fail" (bucket 4 is an advisory warn, not a fail).
   def check_agent_model_drift(agent_key)
     agent_config = agents[agent_key]
     return [] unless agent_config
@@ -1527,21 +1562,29 @@ class Doctor
 
     drifted = []
     sanctioned = []
+    consultation = []
+    unclassified = []
 
     installed.each do |path|
       basename = File.basename(path, ".md")
       installed_model = (parse_frontmatter(path) || {})["model"]
-      resolved_default = AgentModels::TIER_DEFAULTS[basename]
       override = overrides[basename]
 
       if override
         sanctioned << "#{basename}: frontmatter=#{installed_model.inspect}, sanctioned override=#{override.inspect}"
-      elsif installed_model != resolved_default
-        drifted << "#{basename}: frontmatter=#{installed_model.inspect}, resolved default=#{resolved_default.inspect}"
+      elsif AgentModels::TIER_DEFAULTS.key?(basename)
+        resolved_default = AgentModels::TIER_DEFAULTS[basename]
+        if installed_model != resolved_default
+          drifted << "#{basename}: frontmatter=#{installed_model.inspect}, resolved default=#{resolved_default.inspect}"
+        end
+      elsif AgentModels::CONSULTATION_AGENTS.include?(basename)
+        consultation << "#{basename}: frontmatter=#{installed_model.inspect} (consultation role, not a lifecycle default, model is user configuration)"
+      else
+        unclassified << "#{basename}: frontmatter=#{installed_model.inspect}, no resolved default (basename is in neither AgentModels::TIER_DEFAULTS nor AgentModels::CONSULTATION_AGENTS in scripts/lib/agent_models.rb; add it there, or set agents.models.#{basename} to sanction a model explicitly)"
       end
     end
 
-    if drifted.empty?
+    if drifted.empty? && unclassified.empty?
       message = if sanctioned.empty?
                   "No agent-model drift (#{installed.size} installed agent(s) match the resolved default)"
                 else
@@ -1550,13 +1593,16 @@ class Doctor
       [check(
         category: "core_files", name: "agent_model_drift", status: "pass",
         message: message,
-        details: sanctioned
+        details: sanctioned + consultation
       )]
     else
+      parts = []
+      parts << "#{drifted.size} installed agent(s) have unsanctioned model drift vs the config-resolved default" if drifted.any?
+      parts << "#{unclassified.size} installed agent(s) have no resolved default in scripts/lib/agent_models.rb" if unclassified.any?
       [check(
         category: "core_files", name: "agent_model_drift", status: "warn",
-        message: "#{drifted.size} installed agent(s) have unsanctioned model drift vs the config-resolved default",
-        details: drifted + sanctioned,
+        message: parts.join("; "),
+        details: drifted + unclassified + sanctioned + consultation,
         fixable: false
       )]
     end
@@ -1920,6 +1966,65 @@ class Doctor
     a_pre <=> b_pre
   end
 
+  # --- Check category: config asks (release-introduced config questions) ---
+  #
+  # Reads config_asks.yml via ConfigAsks (intent 194): a shipped, declarative
+  # manifest so a release can announce a new config question and collect the
+  # answer without this file, update.rb, or any skill needing to change again.
+  # Rolled up into one check (mirrors check_deprecations shape). Full-tier
+  # (run_checks) ONLY, deliberately excluded from run_core_checks: the post-
+  # update path (update.rb#run_post_update_doctor) defaults to the fast/core
+  # tier, which rolls up with binary: true (any warn becomes overall "fail").
+  # A config-asks warn in that tier would flip every post-update doctor to
+  # "fail" on an otherwise healthy install until the question is answered,
+  # re-noising the post-update surface intent 126 deliberately quieted. The
+  # recoverable-later path for a pending question is a full `/plastic-doctor`
+  # run, the declared maintenance front door; the moment-it-happens path is
+  # update.rb#announce_pending_config_asks, which already runs on every hop.
+  #
+  # A manifest that exists but cannot be read or parsed is reported as its own
+  # WARN (config_asks_manifest), never as a silent pass: an unreadable
+  # manifest is not the same as "nothing declared", and reporting it as
+  # healthy would be the exact silent-failure this whole batch exists to
+  # close. agent_key filters entries by their optional agents scoping (an
+  # entry with no agents field applies to every agent).
+  def check_config_asks(agent_key = "claude")
+    manifest_problem = ConfigAsks.manifest_error(plastic_home)
+    if manifest_problem
+      return [check(
+        category: "config_asks", name: "config_asks_manifest", status: "warn",
+        message: "config_asks.yml problem: #{manifest_problem}",
+        fixable: false
+      )]
+    end
+
+    pending = ConfigAsks.pending(plastic_home, agent_key)
+
+    if pending.empty?
+      return [check(
+        category: "config_asks", name: "pending_asks", status: "pass",
+        message: "No pending config questions"
+      )]
+    end
+
+    details = pending.map do |entry|
+      lines = ["#{entry["question"]} (id: #{entry["id"]})"]
+      Array(entry["options"]).each do |opt|
+        lines << "  - #{opt["label"]}"
+        lines << "    #{ConfigAsks.write_config_command(plastic_home, entry["key"], opt["value"])}"
+      end
+      lines << "  - Not now (keep the default)"
+      lines << "    #{ConfigAsks.dismiss_command(plastic_home, entry["id"])}"
+      lines.join("\n")
+    end
+
+    [check(
+      category: "config_asks", name: "pending_asks", status: "warn",
+      message: "#{pending.size} pending config question(s)", details: details,
+      fixable: false
+    )]
+  end
+
   # --- Check category: QMD integration (read-only, optional) ---
   #
   # QMD is an optional integration. When `qmd` is not on PATH we emit a single
@@ -2014,6 +2119,7 @@ class Doctor
     all_checks += check_core_files(agent_key)
     all_checks += check_project_stores
     all_checks += check_deprecations
+    all_checks += check_config_asks(agent_key)
     all_checks += check_qmd
     all_checks += check_done_signals
     all_checks += check_skill_lint