@zalom/plastic 1.3.0 → 1.4.1

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
@@ -1259,12 +1268,35 @@ class Doctor
       end
     end
 
-    checks << codex_hooks_registered_check(config)
+    hooks_check = codex_hooks_registered_check(config)
+    checks << hooks_check
+    checks << codex_hooks_implemented_check(config)
+    checks << codex_hook_trust_advisory_check if hooks_check[:status] == "pass"
     codex_config_toml_advisory_check(config).tap { |c| checks << c if c }
 
     checks
   end
 
+  # Hooks being REGISTERED (hooks.json content matches HookRegistry) is not
+  # the same as hooks being TRUSTED: Codex gates every non-managed hook
+  # command behind a human /hooks review, keyed by the command's current
+  # hash, so a release that changes a hook command re-arms the review
+  # (intent 198, Decision D2). Whether Codex persists a queryable trust
+  # record anywhere under ~/.codex is undocumented and unverified, so this
+  # can never be a real pass or fail on trust state; it is an advisory that
+  # always names the /hooks step, and it fires only once hooks are actually
+  # registered (an unregistered hook is already reported by
+  # codex_hooks_registered_check, so reminding about trust on top of that
+  # would be noise, not signal).
+  def codex_hook_trust_advisory_check
+    check(
+      category: "agent_registration", name: "codex_hooks_trust", status: "warn",
+      message: "Open Codex, run /hooks, and trust the Plastic hook definitions. " \
+               "Codex re-arms this review whenever a hook's command changes.",
+      fixable: false
+    )
+  end
+
   # Codex-specific agent presence + structural sanity: ~/.codex/agents/plastic-*.toml
   # exist and each carries the mandatory fields. No TOML parser (doctor depends on none):
   # "structural" means the mandatory keys appear as lines and the multi-line
@@ -1306,6 +1338,15 @@ class Doctor
     has_name && has_desc && !di.nil? && !balanced.nil?
   end
 
+  # Plain string extraction of the single model-selection line a generated
+  # Codex agent TOML carries (model_reasoning_effort for a tier alias, model
+  # for a literal override id; codex_model_fields never emits both). No TOML
+  # parser dependency, mirroring codex_agent_toml_well_formed? above.
+  def codex_agent_toml_model_value(content)
+    m = content.match(/^model_reasoning_effort\s*=\s*"([^"]*)"/) || content.match(/^model\s*=\s*"([^"]*)"/)
+    m && m[1]
+  end
+
   # codex_hooks_registered (intent 102, the owner-facing first-run validation
   # path, Decision 14): ~/.codex/hooks.json must carry EXACTLY the commands
   # HookRegistry.codex_hooks_json defines, mirroring the Claude
@@ -1347,6 +1388,124 @@ class Doctor
     end
   end
 
+  # codex_hooks_implemented (intent 200): codex_hooks_registered_check above proves
+  # hooks.json content matches what HookRegistry would emit; both sides of THAT
+  # comparison come from the registry, so a pass only proves the registry agrees
+  # with itself. It never looks at the actual dispatcher, so it cannot see a
+  # registered gate with no real branch there (links-gate shipped exactly this way,
+  # dead, in v1.4.0/intent 192, invisible to doctor and the suite until 198 found it
+  # by hand), or a dispatcher branch nobody registers (bash-gate's shape, intent
+  # 203, in the opposite direction). This check closes both directions at once.
+
+  # The Codex gate names HookRegistry actually registers: the six apply_patch-gated
+  # names (CODEX_PRE_HOOKS + CODEX_POST_HOOKS), the two Bash-matcher shell gates
+  # (CODEX_BASH_HOOKS), and the live-state hook names Codex inherits whole from
+  # `events` (CODEX_LIVE_STATE_EVENTS). No parsing needed: these are HookRegistry's
+  # own Ruby constants.
+  def codex_registry_gate_names
+    live_state = HookRegistry::CODEX_LIVE_STATE_EVENTS.flat_map do |event|
+      HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+    (HookRegistry::CODEX_PRE_HOOKS + HookRegistry::CODEX_POST_HOOKS +
+     HookRegistry::CODEX_BASH_HOOKS + live_state).uniq
+  end
+
+  # Source-text extraction of scripts/codex-hook's supported gate names (D3): the
+  # dispatcher is an executable script with real top-level side effects (it reads
+  # $stdin and may exit), so it can never be required or executed to introspect it,
+  # only read as plain text, mirroring codex_agent_toml_well_formed? above. Pulls
+  # gate names from the STATE_HOOKS and SHELL_HOOKS %w[] literals, plus the `when
+  # "<name>"` labels of the top-level `case gate` statement (stopping at its
+  # trailing `else`). Line-shape dependent, not AST-safe, disclosed as such in
+  # docs; the healthy-install pass test against the REAL dispatcher is what proves
+  # this shape still holds.
+  #
+  # SELF-CHECKING: returns nil, never [], when nothing recognizable is found. A
+  # reshaped dispatcher (combined `when "a", "b"` arms, a multi-line array, a
+  # Hash-dispatch rewrite) would otherwise silently read as zero gate names, and a
+  # zero-gate dispatcher would make the diff below either flag every registered
+  # hook as "missing" or, worse, quietly under-report a real gap. A check that
+  # finds nothing and calls that healthy IS the exact disease this whole check
+  # exists to catch, one level up, so nil forces the caller (below) to fail loudly
+  # instead of reporting health it never actually verified.
+  def codex_dispatcher_gate_names(source)
+    names = []
+    %w[STATE_HOOKS SHELL_HOOKS].each do |const|
+      m = source.match(/^#{const}\s*=\s*%w\[([^\]]*)\]/)
+      names.concat(m[1].split(/\s+/)) if m
+    end
+
+    case_start = source.index(/^case gate\b/)
+    if case_start
+      case_body = source[case_start..-1]
+      else_idx = case_body.index(/^else\b/)
+      scanned = else_idx ? case_body[0...else_idx] : case_body
+      names.concat(scanned.scan(/^when\s+"([^"]+)"/).flatten)
+    end
+
+    names.uniq!
+    names.empty? ? nil : names
+  end
+
+  # The both-direction diff. Each mismatch becomes one detail line naming the
+  # hook, the direction, the harness ("Codex"), and the concrete runtime effect,
+  # never a generic "Codex hooks drift" message (D4).
+  def codex_hooks_implemented_check(config)
+    dispatcher_path = File.join(plastic_home, "scripts", "codex-hook")
+
+    unless File.exist?(dispatcher_path)
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+        message: "scripts/codex-hook not found at #{tilde(dispatcher_path)}; cannot verify " \
+                 "the Codex hook registry and dispatcher agree",
+        fixable: true, fix_hint: "Re-run the Plastic installer with --codex"
+      )
+    end
+
+    dispatcher_names = codex_dispatcher_gate_names(File.read(dispatcher_path))
+
+    if dispatcher_names.nil?
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+        message: "Could not read any gate names out of #{tilde(dispatcher_path)}: the " \
+                 "STATE_HOOKS/SHELL_HOOKS constants and the `case gate` statement no longer " \
+                 "match the shape this check expects, so the registry could not be checked " \
+                 "against the real dispatcher. This is exactly the silent-pass failure this " \
+                 "check exists to prevent; update codex_dispatcher_gate_names in doctor.rb " \
+                 "to the file's new shape.",
+        fixable: false
+      )
+    end
+
+    registry_names = codex_registry_gate_names
+    missing_dispatcher_branch = registry_names - dispatcher_names
+    dead_branch = dispatcher_names - registry_names
+
+    if missing_dispatcher_branch.empty? && dead_branch.empty?
+      return check(
+        category: "agent_registration", name: "codex_hooks_implemented", status: "pass",
+        message: "Every Codex-registered gate has a scripts/codex-hook branch, and every " \
+                 "dispatcher branch is registered"
+      )
+    end
+
+    details = missing_dispatcher_branch.map do |name|
+      "#{name} is registered in ~/.codex/hooks.json but scripts/codex-hook has no branch " \
+        "for it, so it always falls through to the fail-open else and always allows the write"
+    end
+    details += dead_branch.map do |name|
+      "#{name} has a branch in scripts/codex-hook but is not registered in HookRegistry for " \
+        "Codex, so it is dead code Codex never reaches"
+    end
+
+    check(
+      category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
+      message: "Codex's hook registry and scripts/codex-hook disagree on #{details.size} gate(s)",
+      details: details,
+      fixable: false
+    )
+  end
+
   # config.toml advisory (intent 102, Decision 2, R2): READ ONLY. Warns on the two
   # documented footguns (hooks disabled, sandbox read-only); never writes, and
   # returns nil (no check emitted) when config.toml is absent or carries neither.
@@ -1489,29 +1648,57 @@ 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
 
+    return check_agent_model_drift_codex(agent_config) if agent_key == "codex"
+
     agents_dir = File.join(agent_config[:dir], "agents")
     installed = Dir.glob(File.join(agents_dir, "plastic-*.md")).sort
 
@@ -1527,36 +1714,124 @@ 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
                   "No unsanctioned agent-model drift; #{sanctioned.size} sanctioned override(s) in effect"
                 end
+      [check(
+        category: "core_files", name: "agent_model_drift", status: "pass",
+        message: message,
+        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: parts.join("; "),
+        details: drifted + unclassified + sanctioned + consultation,
+        fixable: false
+      )]
+    end
+  end
+
+  # Codex leg of agent_model_drift (intent 198, Decision D4): the shared .md
+  # path above is structurally blind on Codex (codex agents are TOML under
+  # ~/.codex/agents/, never ~/.agents/agents/*.md), so it always passed on an
+  # empty glob without opening a single Codex file. This mirrors the same
+  # four buckets (sanctioned override, matches default, drifted,
+  # unclassified) against ~/.codex/agents/plastic-*.toml instead, reading
+  # model / model_reasoning_effort with the same plain string matching
+  # codex_agent_toml_well_formed? already uses (no TOML parser dependency).
+  # The expected value resolves through AgentModels::TIER_DEFAULTS mapped
+  # through AgentModels.effort_for, honoring the Codex-scoped
+  # agents.models.codex.<name> override precedence install_codex's own
+  # agent_model_overrides(harness: "codex") already applies.
+  # AgentModels::CONSULTATION_AGENTS need no special-case bucket here:
+  # generate_codex_agents already skips writing them for Codex entirely, so
+  # the glob below never finds them and there is nothing to classify.
+  def check_agent_model_drift_codex(agent_config)
+    agents_dir = File.join(agent_config[:home_dir], "agents")
+    installed = Dir.glob(File.join(agents_dir, "plastic-*.toml")).sort
+
+    if installed.empty?
+      return [check(
+        category: "core_files", name: "agent_model_drift", status: "pass",
+        message: "No installed plastic-* agent TOML files to check for model drift"
+      )]
+    end
+
+    global_config = load_yaml_safe(File.join(plastic_home, "config.yml")) || {}
+    overrides = AgentModels.override_map(project_config: {}, global_config: global_config, harness: "codex")
+
+    drifted = []
+    sanctioned = []
+    unclassified = []
+
+    installed.each do |path|
+      basename = File.basename(path, ".toml")
+      installed_value = codex_agent_toml_model_value(File.read(path))
+      override = overrides[basename]
+
+      if override
+        sanctioned << "#{basename}: toml=#{installed_value.inspect}, sanctioned override=#{override.inspect}"
+      elsif AgentModels::TIER_DEFAULTS.key?(basename)
+        expected_effort = AgentModels.effort_for(AgentModels::TIER_DEFAULTS[basename])
+        if installed_value != expected_effort
+          drifted << "#{basename}: toml=#{installed_value.inspect}, resolved default effort=#{expected_effort.inspect}"
+        end
+      else
+        unclassified << "#{basename}: toml=#{installed_value.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.codex.#{basename} " \
+                         "to sanction a model explicitly)"
+      end
+    end
+
+    if drifted.empty? && unclassified.empty?
+      message = if sanctioned.empty?
+                  "No agent-model drift (#{installed.size} installed Codex agent TOML(s) match the resolved default)"
+                else
+                  "No unsanctioned Codex agent-model drift; #{sanctioned.size} sanctioned override(s) in effect"
+                end
       [check(
         category: "core_files", name: "agent_model_drift", status: "pass",
         message: message,
         details: sanctioned
       )]
     else
+      parts = []
+      parts << "#{drifted.size} installed Codex agent TOML(s) have unsanctioned model drift vs the config-resolved default" if drifted.any?
+      parts << "#{unclassified.size} installed Codex agent TOML(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,
         fixable: false
       )]
     end
@@ -1920,6 +2195,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 +2348,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