@zalom/plastic 1.2.0 → 1.4.0

package/scripts/lib/agent_models.rb

@@ -21,6 +21,18 @@ module AgentModels
     "plastic-intent-discovery" => "sonnet"
   }.freeze
 
+  # The two advisor agents (intent 185 final design): plastic-advisor (the real
+  # advisor, ships `model: fable`) and plastic-faux-advisor (the imitation
+  # advisor, an ordinary model carrying the same reasoning discipline inline,
+  # ships `model: opus`). Both are shipped DEFAULTS in frontmatter, never a
+  # hard-wired identity: agents.models.claude.<name> (or the legacy flat form)
+  # overrides either one through the same install-time frontmatter rewrite
+  # every agent override uses. Neither is a lifecycle-stage role: never
+  # dispatched by the auto pipeline, not part of TIER_DEFAULTS. Claude-only for
+  # this release (generate_codex_agents skips both by name; the Codex advisor
+  # case is intent 186, not a permanent exclusion).
+  CONSULTATION_AGENTS = %w[plastic-advisor plastic-faux-advisor].freeze
+
   # Codex reasoning-effort per tier alias (intent 102a). model_reasoning_effort is a
   # depth-of-thinking dial independent of model selection (181 line 317-318), so mapping
   # the tier here never encodes a rotting Codex model id (116 D1). opus is the deepest
@@ -35,22 +47,37 @@ module AgentModels
 
   module_function
 
-  # Pull the `agents.models` sub-hash out of a loaded config hash, tolerating a
-  # missing or malformed shape. Returns a plain { basename => model } hash.
-  def models_section(config)
+  # Pull { basename => model } out of a loaded config hash's `agents.models`
+  # section, scoped to `harness` ("claude" or "codex"), tolerating a missing or
+  # malformed shape. `agents.models` can mix two shapes: legacy FLAT scalar
+  # entries (agents.models.plastic-executor: sonnet), honored as the claude
+  # harness only, and harness-scoped sub-hashes (agents.models.claude.*,
+  # agents.models.codex.*). Nested wins over flat for the same agent on the
+  # claude harness; a non-claude harness reads ONLY its own nested sub-hash,
+  # never the flat entries, so a literal model id written under the flat form
+  # (or agents.models.claude.*) can never leak into another harness's config.
+  def models_section(config, harness: "claude")
     return {} unless config.is_a?(Hash)
     agents = config["agents"]
     return {} unless agents.is_a?(Hash)
     section = agents["models"]
-    section.is_a?(Hash) ? section : {}
+    return {} unless section.is_a?(Hash)
+
+    nested = section[harness]
+    nested = nested.is_a?(Hash) ? nested : {}
+    return nested unless harness == "claude"
+
+    flat = section.reject { |_key, value| value.is_a?(Hash) }
+    flat.merge(nested)
   end
 
   # Override map for the installer: global overrides overlaid by project
-  # overrides (project wins). Defaults are intentionally excluded. Unknown agent
-  # keys are carried through as-is; install_agents simply never matches them to a
-  # copied file, so they are ignored without raising.
-  def override_map(project_config: {}, global_config: {})
-    models_section(global_config).merge(models_section(project_config))
+  # overrides (project wins), scoped to `harness`. Defaults are intentionally
+  # excluded. Unknown agent keys are carried through as-is; install_agents
+  # simply never matches them to a copied file, so they are ignored without
+  # raising.
+  def override_map(project_config: {}, global_config: {}, harness: "claude")
+    models_section(global_config, harness: harness).merge(models_section(project_config, harness: harness))
   end
 
   # The model_reasoning_effort for a Plastic tier alias, or nil for any value that is not

package/scripts/lib/bridge.rb

@@ -259,6 +259,34 @@ module Bridge
     auto_pool.max_by { |c| c[:mtime] }&.fetch(:data)
   end
 
+  # --- Shared INDEX entry matcher (intent 188, D12/D13) -----------------------
+  #
+  # ONE definition site for the "- [ID <sep> Title](link)" shape both
+  # `intent_active?` (below) and `scripts/end-intent`'s own INDEX-move parser
+  # depend on, so the two regexes can never drift apart again (the em-dash-only
+  # bug was flagged and deferred at intents 96 and 169, then independently
+  # rediscovered as a SEPARATE end-intent defect at intent 188). Accepts a real
+  # em dash (U+2014) OR a plain hyphen as the id/title separator on READ.
+  # Hardening this widens intent_active?'s fail-open case: a hyphen-formatted
+  # `## Active` line used to read as not-active (lock gate failed open); it now
+  # reads as active (gate correctly blocks). Accepted as a bug fix (D13): no
+  # passing test relied on the old fail-open behavior. Every WRITE still emits
+  # the real em dash (D10); only what this matcher can PARSE has widened.
+  #
+  # The separator is built from the codepoint, not a literal byte in this
+  # source file, so this new code stays em-dash free (the shipped-file
+  # convention; store files like INDEX.md are the exempt surface this matcher
+  # READS, not where this constant lives). Matches the existing convention in
+  # scripts/end-intent.
+  EM_DASH = "\u2014".freeze
+  INDEX_ENTRY_RE = /\A- \[(\S+)\s+(?:#{Regexp.escape(EM_DASH)}|-)\s+(.*?)\]\(([^)]+)\)/.freeze
+
+  # Match `line` (already chomped) against the shared INDEX entry shape.
+  # Returns a MatchData (captures: 1 = id, 2 = title, 3 = link) or nil.
+  def self.index_entry_match(line)
+    line.to_s.match(INDEX_ENTRY_RE)
+  end
+
   # --- Terminal-state bridge purge (intent 80) -------------------------------
 
   # True iff the intent is Active in its store's INDEX.md. An INDEX.md lives at
@@ -284,7 +312,7 @@ module Bridge
       end
       next unless in_active
       break if stripped.start_with?("## ") # next section ends the Active block
-      m = stripped.match(/^- \[(\S+) +—/)
+      m = index_entry_match(stripped)
       return true if m && m[1] == target
     end
     false

package/scripts/lib/config_asks.rb

@@ -0,0 +1,110 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# Shared resolution for config_asks.yml: a shipped, declarative manifest that
+# lets a release announce a brand new config question without editing
+# update.rb, doctor.rb, or any skill. Sibling of deprecations.yml (announce
+# only); this one also tracks whether the user has answered or dismissed each
+# entry, via config_asks_dismissed (mirrors deprecations_dismissed).
+#
+# Footgun for whoever adds the next entry: pending reads config.yml directly
+# and never merges in read-config's DEFAULTS, so keying a new entry on
+# something that already has a non-nil value in read-config's DEFAULTS would
+# make that entry look unset, and therefore pending, forever, even though the
+# rest of Plastic already treats it as answered by that default. See the
+# matching note in config_asks.yml's schema header.
+module ConfigAsks
+  FILENAME = "config_asks.yml"
+
+  # nil if the manifest is absent (a legitimate no-op: no release has declared
+  # a config question yet) or valid. A short description of the problem if the
+  # file exists but could not be read or parsed, or does not declare a
+  # config_asks array. Callers use this to tell "nothing declared" apart from
+  # "declared but broken" -- the manifest being unreadable must never look
+  # like a clean pass.
+  def self.manifest_error(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return nil unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path))
+    return "#{FILENAME} does not declare a config_asks list" unless data.is_a?(Hash) && data["config_asks"].is_a?(Array)
+
+    nil
+  rescue StandardError => e
+    "#{FILENAME} could not be read: #{e.message}"
+  end
+
+  # All declared entries, or [] if the manifest is missing or malformed. Use
+  # manifest_error alongside this when the difference between "no entries"
+  # and "could not read the manifest" matters (it always does for a health
+  # check or an announcement -- see manifest_error above).
+  def self.load_entries(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return [] unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path)) || {}
+    entries = data["config_asks"]
+    entries.is_a?(Array) ? entries : []
+  rescue StandardError
+    []
+  end
+
+  # Entries whose key is unset in config.yml AND whose id is not dismissed AND
+  # whose agents (if any) include agent_key. Deliberately ignores "introduced"
+  # -- see the schema comment in config_asks.yml for why (retro-fire).
+  #
+  # agent_key: nil means "do not filter by agent" (every entry applies); pass
+  # the caller's actual agent ("claude", "codex", "hermes") to respect an
+  # entry's agents scoping.
+  def self.pending(plastic_home, agent_key = nil)
+    config = load_config(plastic_home)
+    dismissed = Array(config["config_asks_dismissed"])
+
+    load_entries(plastic_home).select do |entry|
+      next false if dismissed.include?(entry["id"])
+      next false unless applies_to_agent?(entry, agent_key)
+
+      value = dig(config, entry["key"].to_s)
+      value.nil? || value == ""
+    end
+  end
+
+  # The exact command that answers one option of one entry.
+  def self.write_config_command(plastic_home, key, value)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} #{key} #{value}"
+  end
+
+  # The exact command that dismisses one entry ("not now" / keep default).
+  def self.dismiss_command(plastic_home, id)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} config_asks_dismissed --push #{id}"
+  end
+
+  # An entry with no agents field (or an empty one) applies to every agent.
+  # Otherwise it applies only when agent_key is nil (no filtering requested)
+  # or is present in the entry's agents list.
+  def self.applies_to_agent?(entry, agent_key)
+    scoped = Array(entry["agents"])
+    return true if scoped.empty?
+    return true if agent_key.nil?
+
+    scoped.include?(agent_key)
+  end
+  private_class_method :applies_to_agent?
+
+  def self.load_config(plastic_home)
+    path = File.join(plastic_home, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+  private_class_method :load_config
+
+  def self.dig(hash, dotted_key)
+    dotted_key.split(".").reduce(hash) { |acc, k| acc.is_a?(Hash) ? acc[k] : nil }
+  end
+  private_class_method :dig
+end

package/scripts/lib/graph_rebuild.rb

@@ -197,11 +197,17 @@ module GraphRebuild
 
   # Classify a resolved (store, id) relative to the referer, using the live store
   # index to detect dead targets:
-  #   - target id present in the referer's OWN store -> :same_store (collapse to bare)
-  #   - target id present in a DIFFERENT store       -> :cross_store (keep slug:id)
-  #   - target id present NOWHERE                     -> :dead (drop)
+  #   - the store token resolves to no known store          -> :unknown_store (NEVER
+  #     dropped; this is what makes a future discovery miss non-destructive, intent 189 D2)
+  #   - target id present in the referer's OWN known store   -> :same_store (collapse)
+  #   - target id present in a DIFFERENT known store          -> :cross_store (keep slug:id)
+  #   - target id present NOWHERE in a known store            -> :dead (drop)
   def classify(store_tok, bare, referer_store, store_index, original_ref)
     canonical = canonical_store_key(store_tok, store_index)
+    unless known_store?(canonical, store_index)
+      return { status: :unknown_store, ref: original_ref.to_s, store: store_tok }
+    end
+
     if ids_in(store_index, canonical).include?(bare)
       if canonical == referer_store
         { status: :same_store, id: bare }
@@ -213,6 +219,15 @@ module GraphRebuild
     end
   end
 
+  # True iff `canonical` names a store this run actually knows about (it is "global", or a
+  # literal key in `store_index`). A ref whose store token canonicalizes to anything else
+  # has never been discovered by this run, and must be classified :unknown_store, never
+  # :dead: those are different facts (store unknown vs. id absent from a known store) and
+  # only the second one means the ref is genuinely gone.
+  def known_store?(canonical, store_index)
+    canonical == "global" || (store_index || {}).key?(canonical)
+  end
+
   def ids_in(store_index, store_key)
     Array((store_index || {})[store_key])
   end
@@ -225,8 +240,11 @@ module GraphRebuild
   #   relocation_map — from build_relocation_map (spans all stores)
   #   store_index    — { store_key => bare ids present } (spans all stores)
   #
-  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ] }.
-  # kinds: :dedupe, :i3, :repoint, :collapse, :drop, :i1_backlink.
+  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ],
+  #           preserved: [ {intent:, field:, ref:, store:} ] }.
+  # kinds (changes, real mutations only): :dedupe, :i3, :repoint, :collapse, :drop,
+  # :i1_backlink. `preserved` is DIFFERENT: an unknown-store ref left byte-for-byte
+  # unchanged, reported for visibility, never counted as a "change" (nothing mutated).
   #
   # Order is load-bearing (spec Phase 2):
   #   1. dedupe each array order-preserving
@@ -247,6 +265,7 @@ module GraphRebuild
     end
 
     changes = []
+    preserved = []
 
     out.each do |id, edges|
       # 1. dedupe order-preserving
@@ -289,6 +308,11 @@ module GraphRebuild
               changes << { intent: id, kind: :repoint, field: field, before: ref, after: res[:ref] }
             end
             rebuilt << res[:ref]
+          when :unknown_store
+            # NEVER drop: the store is unrecognized, not the id absent from a known store.
+            # Preserve byte-for-byte and report separately from `changes` (nothing mutated).
+            preserved << { intent: id, field: field, ref: ref, store: res[:store] }
+            rebuilt << ref
           when :dead
             changes << { intent: id, kind: :drop, field: field, before: ref, after: nil }
             # dropped: not appended
@@ -323,6 +347,6 @@ module GraphRebuild
       end
     end
 
-    { nodes: out, changes: changes }
+    { nodes: out, changes: changes, preserved: preserved }
   end
 end

package/scripts/lib/hook_registry.rb

@@ -48,6 +48,7 @@ module HookRegistry
         ] },
         { "matcher" => "Write|Edit", "hooks" => [
           { "name" => "savepoint-pre", "status" => "Recording stage start..." },
+          { "name" => "links-gate", "status" => "Checking Links gate..." },
         ] },
         { "matcher" => CREATE_MATCHER, "hooks" => [
           { "name" => "create-gate", "status" => "Checking create gate..." },
@@ -84,7 +85,7 @@ module HookRegistry
   # [{"matcher","hooks":[{"type":"command","command","statusMessage"}]}]}},
   # identical to Claude's shape, string command. Single source of truth (108 D7):
   # any drift from `events` is a bug, pinned by test.
-  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre create-gate].freeze
+  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre links-gate create-gate].freeze
   CODEX_POST_HOOKS = %w[gate-check].freeze
 
   def codex_hooks_json(dispatcher_path:)

package/scripts/lib/installer_core.rb

@@ -251,16 +251,37 @@ class InstallerCore
     puts "  \u{2705} Core files synced (v#{version})"
   end
 
+  # Templates ship in full: every file under templates/ in the repo must reach
+  # ~/.plastic/templates/ on install/update. Derived from Dir.glob so a new
+  # template file added later is registered automatically, closing the
+  # whack-a-mole pattern that hid templates/index.md and templates/project.yml
+  # from every install for five weeks (intent 190).
+  def template_files
+    Dir.glob(File.join(package_root, "templates", "*")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("templates", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
-  # by install_sync_test).
+  # by install_sync_test). The templates half is glob-derived (template_files above); the
+  # rest stays a hand-written literal.
   def core_files
+    hand_registered_files.merge(template_files)
+  end
+
+  def hand_registered_files
     {
       "PLASTIC.md" => "PLASTIC.md",
       "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
+      "config_asks.yml" => "config_asks.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",
+      "scripts/write-config" => "scripts/write-config",
       "scripts/select-update-target" => "scripts/select-update-target",
       "scripts/hook-session-start" => "scripts/hook-session-start",
       "scripts/hook-continue" => "scripts/hook-continue",
@@ -271,6 +292,7 @@ class InstallerCore
       "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/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
@@ -296,6 +318,7 @@ class InstallerCore
       "scripts/roadmap-next" => "scripts/roadmap-next",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/lib/graph_rebuild.rb" => "scripts/lib/graph_rebuild.rb",
+      "scripts/lib/store_discovery.rb" => "scripts/lib/store_discovery.rb",
       "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",
@@ -303,21 +326,21 @@ class InstallerCore
       "scripts/project-links" => "scripts/project-links",
       "scripts/link-suggest" => "scripts/link-suggest",
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
+      "scripts/lib/restore_intent_v1.rb" => "scripts/lib/restore_intent_v1.rb",
+      "scripts/restore-intent-v1" => "scripts/restore-intent-v1",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
+      "scripts/hook-links-gate" => "scripts/hook-links-gate",
+      "scripts/lib/links_gate.rb" => "scripts/lib/links_gate.rb",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
-      "templates/intent.md" => "templates/intent.md",
-      "templates/spec.md" => "templates/spec.md",
-      "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/project_validator.rb" => "scripts/lib/project_validator.rb",
+      "scripts/validate-project" => "scripts/validate-project",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
       "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",
@@ -465,12 +488,16 @@ class InstallerCore
       installed << dest
     end
 
-    # Copy skills as flat, hyphen-namespaced personal skills (plastic-<name>/)
+    # Copy skills as flat, hyphen-namespaced personal skills (plastic-<name>/).
+    # advisor.enabled: false skips the agent-advisor skill along with both
+    # advisor agents below, so a user who declined the advisor never sees a
+    # dead-end skill pointing at nothing installed.
     skills_source = File.join(package_root, "skills")
-    installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, skills_root, exclude: skill_exclude) 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"), models: agent_model_overrides)
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides, advisor_enabled: advisor_enabled?)
 
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
@@ -495,8 +522,12 @@ class InstallerCore
   def install_codex(config, force)
     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 += generate_codex_agents(File.join(config[:home_dir], "agents"), models: agent_model_overrides)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    # Codex-scoped overrides only (agents.models.codex.*): a literal Claude
+    # model id set under agents.models.claude.* (or the legacy flat form,
+    # which resolves as claude) must never reach a Codex TOML.
+    installed += generate_codex_agents(File.join(config[:home_dir], "agents"), models: agent_model_overrides(harness: "codex"))
 
     # Instruction injection (L1): Plastic standing conventions into ~/.codex/AGENTS.md.
     # Partial-ownership file, so it is NOT manifest-tracked (stripped surgically on uninstall).
@@ -525,8 +556,17 @@ class InstallerCore
     return [] if sources.empty?
 
     FileUtils.mkdir_p(agents_root)
-    sources.map do |src|
+    sources.filter_map do |src|
       basename = File.basename(src, ".md")
+      # Codex advisor support is out of scope for this release (intent 185): the
+      # owner has not evaluated the Codex reasoning-model ecosystem long enough to
+      # judge it. Skip every AgentModels::CONSULTATION_AGENTS file (both
+      # plastic-advisor and plastic-faux-advisor) by name, a deliberate and
+      # mechanical scope cut tracked at intent 186 (Codex advisor evaluation), not
+      # a permanent exclusion and not conditioned on any frontmatter or override
+      # value.
+      next if AgentModels::CONSULTATION_AGENTS.include?(basename)
+
       dest = File.join(agents_root, "#{basename}.toml")
       write_text_atomic(dest, render_codex_agent_toml(src, models[basename]))
       dest
@@ -639,8 +679,9 @@ class InstallerCore
   def install_hermes(config, force)
     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"), models: agent_model_overrides)
+    skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides, advisor_enabled: advisor_enabled?)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -650,12 +691,14 @@ class InstallerCore
   # directory name -- the only personal-skill namespacing Claude Code supports).
   # Any top-level underscore-prefixed markdown fragment (e.g. `_active-intent-gate.md`,
   # `_decision-tables.md`) is a shared non-skill fragment and relocates to ~/.plastic/
-  # instead, so every skill can read it from one shared location.
-  def install_skills_flat(skills_source, skills_root)
+  # instead, so every skill can read it from one shared location. `exclude` skips
+  # named top-level skill directories entirely (intent 185: the agent-advisor skill
+  # when advisor.enabled is false).
+  def install_skills_flat(skills_source, skills_root, exclude: [])
     installed = []
     FileUtils.mkdir_p(skills_root)
 
-    Dir.children(skills_source).reject { |e| e.start_with?(".") }.each do |entry|
+    Dir.children(skills_source).reject { |e| e.start_with?(".") || exclude.include?(e) }.each do |entry|
       src = File.join(skills_source, entry)
       if File.directory?(src)
         installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"))
@@ -675,10 +718,18 @@ 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, models: {})
+  # advisor_enabled: false (advisor.enabled config key) skips every
+  # AgentModels::CONSULTATION_AGENTS file entirely (both plastic-advisor and
+  # plastic-faux-advisor), so a user who declined the advisor never gets either
+  # agent installed.
+  def install_agents(agents_root, models: {}, advisor_enabled: true)
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
+    unless advisor_enabled
+      sources = sources.reject { |src| AgentModels::CONSULTATION_AGENTS.include?(File.basename(src, ".md")) }
+    end
+
     FileUtils.mkdir_p(agents_root)
     sources.map do |src|
       dest = File.join(agents_root, File.basename(src))
@@ -700,9 +751,18 @@ class InstallerCore
   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)
+  # project dir is known) overlaid on global config, scoped to `harness`
+  # ("claude" or "codex"). Defaults are NOT included, so unconfigured agents
+  # keep their shipped frontmatter.
+  #
+  # Both advisor agents (plastic-advisor, plastic-faux-advisor) resolve through
+  # this SAME generic map, like any other agent: a config author sets
+  # agents.models.claude.plastic-advisor (or the legacy flat
+  # agents.models.plastic-advisor, read as claude) to point either agent at a
+  # different literal model. There is no separate advisor-specific model key;
+  # which agent the advisor SKILL routes to by default is a routing decision
+  # (advisor.claude.default), never a model-selection one.
+  def agent_model_overrides(project_dir = nil, harness: "claude")
     global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
     project_config =
       if project_dir
@@ -710,7 +770,54 @@ class InstallerCore
       else
         {}
       end
-    AgentModels.override_map(project_config: project_config, global_config: global_config)
+    AgentModels.override_map(project_config: project_config, global_config: global_config, harness: harness)
+  end
+
+  # advisor.enabled: project overlays global, missing or malformed counts as
+  # enabled (fail-open). Harness-blind: false skips both advisor agents and the
+  # agent-advisor skill on every installed harness.
+  def advisor_enabled?(project_dir = nil)
+    global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
+    project_config = project_dir ? load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml")) : {}
+    value = project_config.dig("advisor", "enabled")
+    value = global_config.dig("advisor", "enabled") if value.nil?
+    value != false
+  end
+
+  # Agent-name shorthands for the --advisor flag: the two shipped choices,
+  # named for the role (real advisor vs. the cheaper imitation), never a model
+  # name.
+  ADVISOR_SHORTHANDS = { "real" => "plastic-advisor", "faux" => "plastic-faux-advisor" }.freeze
+
+  # Write advisor.enabled / advisor.claude.default into the global config.yml
+  # from install-time flags. Absent flags change nothing: advisor.enabled
+  # defaults to enabled when missing, and advisor.claude.default is left unset
+  # (the skill's own fallback chain applies) when missing.
+  #   --no-advisor      -> advisor.enabled: false
+  #   --advisor VALUE   -> advisor.claude.default: VALUE (an agent name, or the
+  #                        shorthand "real"/"faux")
+  def apply_config_flags(argv)
+    no_advisor = argv.include?("--no-advisor")
+    advisor_idx = argv.index("--advisor")
+    advisor_value = advisor_idx && argv[advisor_idx + 1]
+    return unless no_advisor || advisor_value
+
+    config_path = File.join(plastic_home, "config.yml")
+    config = load_config_yaml(config_path)
+
+    if no_advisor
+      config["advisor"] ||= {}
+      config["advisor"]["enabled"] = false
+    end
+    if advisor_value
+      agent_name = ADVISOR_SHORTHANDS[advisor_value] || advisor_value
+      config["advisor"] ||= {}
+      config["advisor"]["claude"] ||= {}
+      config["advisor"]["claude"]["default"] = agent_name
+    end
+
+    FileUtils.mkdir_p(plastic_home)
+    File.write(config_path, YAML.dump(config))
   end
 
   def load_config_yaml(path)