@zalom/plastic 1.2.0 → 1.4.0

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