@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/scripts/lib/installer_core.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "json"
 require "yaml"
 require "fileutils"
@@ -12,6 +13,7 @@ require_relative "agent_models"
 require_relative "harness_text"
 require_relative "compact_instructions"
 require_relative "engine_permissions"
+require_relative "qmd_sync"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -45,23 +47,21 @@ class InstallerCore
   CLAUDE_SECTION_END = "<!-- END PLASTIC COMPACT -->"
   CLAUDE_SECTION_RE = /^<!-- BEGIN PLASTIC COMPACT.*?-->\n.*?\n<!-- END PLASTIC COMPACT -->\n?/m
 
-  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
-  # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
-  # a shared file Codex merges from multiple sources, so this block stays a small,
-  # hand-curated pointer rather than embedding the core wholesale, and it never drifts
-  # because it only ever points, never duplicates.
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the help topics
+  # `plastic help TOPIC` prints, injected into ~/.codex/AGENTS.md. Not a slice of
+  # PLASTIC.md itself: AGENTS.md is a shared file Codex merges from multiple sources,
+  # so this block stays a small, hand-curated pointer rather than embedding the core
+  # wholesale, and it never drifts because it only ever points, never duplicates.
   CODEX_AGENTS_MD_BODY = <<~MD.freeze
     Plastic is installed for this agent. Plastic is intent-driven state management: work runs
     in one of three modes, direct, thinking, or auto (a team drives the runner loop:
     `runner step`, `status`, `answer`). Do not jump straight to code.
 
     Standing rules:
-    - Core conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly. For
-      depth, read a chapter from ~/.agents/skills/plastic-conventions/references/ on demand.
-      Both are generated and overwritten on Plastic updates, so never edit them.
-    - Operational procedures are installed as skills under ~/.agents/skills/ (each
-      plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
-      $plastic-doctor), or let Codex pick one implicitly by matching its description.
+    - The command line is ~/.plastic/PLASTIC.md. Read it and follow it exactly. The
+      conventions are chapters `plastic help TOPIC` prints on demand. Both are
+      generated and overwritten on Plastic updates, so never edit them.
+    - Operational procedures are the `plastic` command line itself, run directly.
     - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
       the project tree.
 
@@ -352,12 +352,36 @@ class InstallerCore
     end
   end
 
+  # The command line (intent 363). Glob-derived for the reason screen_files is:
+  # a command is one row in scripts/lib/cli/table.rb plus one file, and a
+  # hand-written manifest would make it two files and a diff. The launcher
+  # bin/plastic requires scripts/lib/cli.rb by a relative path, so the whole
+  # subtree travels together or an installed copy LoadErrors on the first call.
+  def cli_files
+    Dir.glob(File.join(package_root, "scripts", "lib", "{cli,rlm}", "**", "*.rb")).each_with_object({}) do |path, acc|
+      rel = path.sub("#{package_root}/", "")
+      acc[rel] = rel
+    end
+  end
+
+  # `plastic help TOPIC` (intent 372, family 4) reads docs/help/TOPIC.md from
+  # package_root the same way it reads a command's file, so the chapter has to
+  # ship the same way a template does: glob-derived, one file added and it
+  # installs with no diff here.
+  def help_files
+    Dir.glob(File.join(package_root, "docs", "help", "*.md")).each_with_object({}) do |path, acc|
+      rel = File.join("docs", "help", 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). The templates and screen-kind halves are glob-derived
   # (template_files, screen_files above); the rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files)
+    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files).merge(cli_files)
+      .merge(help_files)
   end
 
   def hand_registered_files
@@ -391,6 +415,9 @@ class InstallerCore
       "scripts/plastic-lock" => "scripts/plastic-lock",
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
       "scripts/lib/compact_instructions.rb" => "scripts/lib/compact_instructions.rb",
+      "scripts/lib/version_number.rb" => "scripts/lib/version_number.rb",
+      "scripts/lib/cli.rb" => "scripts/lib/cli.rb",
+      "bin/plastic" => "bin/plastic",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/insight-append" => "scripts/insight-append",
@@ -406,6 +433,14 @@ class InstallerCore
       "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/store_layout.rb" => "scripts/lib/store_layout.rb",
+      "scripts/lib/stores_move.rb" => "scripts/lib/stores_move.rb",
+      "scripts/lib/sqlite.rb" => "scripts/lib/sqlite.rb",
+      "scripts/lib/search_index.rb" => "scripts/lib/search_index.rb",
+      "scripts/lib/store_sync.rb" => "scripts/lib/store_sync.rb",
+      "scripts/lib/work_graph.rb" => "scripts/lib/work_graph.rb",
+      "scripts/lib/reference_archive.rb" => "scripts/lib/reference_archive.rb",
+      "scripts/lib/backup.rb" => "scripts/lib/backup.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",
@@ -624,7 +659,7 @@ class InstallerCore
   def bootstrap
     puts "  \u{1f331} First install \u{2014} bootstrapping store..."
 
-    FileUtils.mkdir_p(File.join(plastic_home, "store"))
+    FileUtils.mkdir_p(Plastic::StoreLayout.global_store(plastic_home))
     FileUtils.mkdir_p(File.join(plastic_home, "projects"))
 
     write_if_missing(File.join(plastic_home, "config.yml"), <<~YAML)
@@ -643,7 +678,7 @@ class InstallerCore
 
     write_if_missing(File.join(plastic_home, "projects.yml"), "---\nprojects: {}\n")
 
-    write_if_missing(File.join(plastic_home, "INDEX.md"), <<~MD)
+    write_if_missing(File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md"), <<~MD)
       # Index
 
       ## Active
@@ -661,7 +696,7 @@ class InstallerCore
       # Plastic: Agent Instructions
 
       Read `PLASTIC.md` in this directory for the core conventions; deeper doctrine lives
-      in the `plastic-conventions` skill's chapters. Follow it exactly. Never modify it:
+      in the chapters `plastic help TOPIC` prints. Follow it exactly. Never modify it:
       it is overwritten on plugin updates.
 
       This file (`AGENTS.md`) is where project-specific rules live.
@@ -672,6 +707,25 @@ class InstallerCore
     puts "  \u{2705} Store bootstrapped"
   end
 
+  # Intent 372 (former install skill, lines 119-127): `~/.plastic` becomes its own
+  # git repository the first time it exists, so `update` can later commit the core
+  # files it re-syncs. Leaves an existing repository alone.
+  def git_init_if_absent(runner: ->(cmd) { system(*cmd) })
+    FileUtils.mkdir_p(plastic_home)
+    return if File.directory?(File.join(plastic_home, ".git"))
+    runner.call(["git", "-C", plastic_home, "init", "-q"])
+  end
+
+  # Intent 372 (former install skill, lines 167-179): register every Plastic store as
+  # a QMD collection. QmdSync.register already no-ops per store when QMD is absent;
+  # the detector is injected too so a run stays hermetic on a machine that happens to
+  # have the real `qmd` binary on PATH.
+  def register_with_qmd(runner: QmdSync.default_runner, detector: QmdSync.method(:detect))
+    QmdSync.enumerate_stores(plastic_home: plastic_home).each do |store|
+      QmdSync.register(collection: store[:collection], dir: store[:dir], runner: runner, detector: detector)
+    end
+  end
+
   # --- Agent adapters ---
 
   # Uniform per-agent install record dir: <agent-dir>/plastic/ holds VERSION and
@@ -943,9 +997,9 @@ class InstallerCore
   # Every store root (the global store, plus each project store) whose real
   # path is reached with no symlink between it and plastic_home.
   def real_store_roots(plastic_home)
-    roots = [File.join(plastic_home, "store")] +
-            Dir.glob(File.join(plastic_home, "projects", "*", "store"))
-    roots.select { |root| real_store_root?(plastic_home, root) }
+    roots = [Plastic::StoreLayout.global_store(plastic_home)] +
+            Dir.glob(File.join(Plastic::StoreLayout.projects_root(plastic_home), "*", "store"))
+    roots.uniq.select { |root| real_store_root?(plastic_home, root) }
   end
 
   def real_store_root?(plastic_home, store_root)
@@ -1020,7 +1074,7 @@ class InstallerCore
   # fails milder than the bug it prevents, independent of what any caller's `root:` is or
   # what a hand-edited manifest claims.
   def store_roots
-    [File.join(plastic_home, "store"), File.join(plastic_home, "projects")].map { |p| File.expand_path(p) }
+    %w[store projects stores].map { |name| File.expand_path(File.join(plastic_home, name)) }
   end
 
   # `install_skills_flat` relocates any top-level underscore-prefixed markdown
@@ -1132,7 +1186,12 @@ class InstallerCore
     # 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"))
+    installed += generate_codex_agents(
+      File.join(config[:home_dir], "agents"),
+      models: agent_model_overrides(harness: "codex"),
+      efforts: agent_effort_overrides(harness: "codex"),
+      advisor_enabled: advisor_enabled?
+    )
 
     # Instruction injection (L1): Plastic standing conventions into ~/.codex/AGENTS.md.
     # Partial-ownership file, so it is NOT manifest-tracked (stripped surgically on uninstall).
@@ -1162,24 +1221,17 @@ class InstallerCore
   # a whole-file, Plastic-owned .toml per repo agents/*.md instead of copying markdown.
   # The returned paths append to `installed`, so they are manifest-tracked and pruned on
   # uninstall by the manifest whole-file-delete path, exactly like ~/.claude/agents/*.md.
-  def generate_codex_agents(agents_root, models: {})
+  def generate_codex_agents(agents_root, models: {}, efforts: {}, advisor_enabled: true)
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
     FileUtils.mkdir_p(agents_root)
     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)
+      next if !advisor_enabled && AgentModels::CONSULTATION_AGENTS.include?(basename)
 
       dest = File.join(agents_root, "#{basename}.toml")
-      write_text_atomic(dest, render_codex_agent_toml(src, models[basename]))
+      write_text_atomic(dest, render_codex_agent_toml(src, models[basename], efforts[basename]))
       dest
     end
   end
@@ -1187,16 +1239,25 @@ class InstallerCore
   # Render one repo agents/*.md into a deterministic Codex agent TOML document. Fixed field
   # order (name, description, the model field(s) from codex_model_fields, developer_instructions)
   # so regenerate is byte-identical (idempotency).
-  def render_codex_agent_toml(source_path, override)
+  def render_codex_agent_toml(source_path, override, effort_override = nil)
     front, body = split_frontmatter(File.read(source_path))
     name = (front["name"] || File.basename(source_path, ".md")).to_s
     description = (front["description"] || "").to_s
-    effective = (override && !override.to_s.empty? ? override : front["model"]).to_s
+    effective = if override && !override.to_s.empty?
+                  override
+                else
+                  AgentModels.shipped_model_for(name, harness: "codex") || front["model"]
+                end
+    effort = if effort_override && !effort_override.to_s.empty?
+               effort_override
+             else
+               front["effort"] || AgentModels.shipped_effort_for(name)
+             end
 
     parts = []
     parts << %(name = "#{toml_inline_escape(name)}")
     parts << %(description = "#{toml_inline_escape(description)}")
-    parts << codex_model_fields(effective)
+    parts << codex_model_fields(effective, effort: effort)
     parts << "developer_instructions = \"\"\"\n#{toml_ml_escape(body.strip)}\n\"\"\""
     parts.reject(&:empty?).join("\n") + "\n"
   end
@@ -1216,20 +1277,20 @@ class InstallerCore
   # The model-selection line(s). A known tier alias (opus/sonnet/haiku) emits BOTH a `model` line
   # (from AgentModels.codex_model_for, the intent-186 per-role Codex identity) and a
   # model_reasoning_effort line, model first for deterministic byte-identical regenerate. Any other
-  # non-empty value is a literal Codex model id emitted verbatim as `model` only. Empty -> no line
-  # (the agent inherits the session default). If an alias somehow lacks a mapped model, the effort
-  # line still emits alone (backward-safe).
-  def codex_model_fields(effective)
+  # non-empty value is a literal Codex model id. Every non-empty model also emits the resolved effort,
+  # medium by default or the harness-scoped override. Empty emits no model fields.
+  def codex_model_fields(effective, effort: AgentModels::DEFAULT_EFFORT)
     return "" if effective.nil? || effective.to_s.empty?
-    effort = AgentModels.effort_for(effective)
-    if effort
+    if AgentModels.effort_for(effective)
       lines = []
       model = AgentModels.codex_model_for(effective)
       lines << %(model = "#{toml_inline_escape(model)}") if model && !model.to_s.empty?
-      lines << %(model_reasoning_effort = "#{effort}")
+      lines << %(model_reasoning_effort = "#{toml_inline_escape(effort)}") unless effort.to_s.empty?
       lines.join("\n")
     else
-      %(model = "#{toml_inline_escape(effective.to_s)}")
+      lines = [%(model = "#{toml_inline_escape(effective.to_s)}")]
+      lines << %(model_reasoning_effort = "#{toml_inline_escape(effort)}") unless effort.to_s.empty?
+      lines.join("\n")
     end
   end
 
@@ -1362,8 +1423,7 @@ class InstallerCore
   # 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.
   # 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
+  # AgentModels::CONSULTATION_AGENTS file entirely, so a user who declined the advisor never gets either
   # agent installed.
   def install_agents(agents_root, models: {}, efforts: {}, advisor_enabled: true)
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
@@ -1408,18 +1468,21 @@ class InstallerCore
   # ("claude" or "codex"). Defaults are NOT included, so unconfigured agents
   # keep their shipped frontmatter.
   #
-  # Both advisor agents (plastic-advisor, plastic-faux-advisor) resolve through
+  # Both advisor agents 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
+  # agents.models.claude.<agent> (or the legacy flat form, 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"))
+    global_path = File.join(plastic_home, "config.yml")
+    migrate_advisor_config_file(global_path)
+    global_config = load_config_yaml(global_path)
     project_config =
       if project_dir
-        load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml"))
+        project_path = File.join(project_dir, ".plastic_store", "config.yml")
+        migrate_advisor_config_file(project_path)
+        load_config_yaml(project_path)
       else
         {}
       end
@@ -1427,8 +1490,12 @@ class InstallerCore
   end
 
   def agent_effort_overrides(project_dir = nil, harness: "claude")
-    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")) : {}
+    global_path = File.join(plastic_home, "config.yml")
+    migrate_advisor_config_file(global_path)
+    global_config = load_config_yaml(global_path)
+    project_path = project_dir && File.join(project_dir, ".plastic_store", "config.yml")
+    migrate_advisor_config_file(project_path) if project_path
+    project_config = project_path ? load_config_yaml(project_path) : {}
     AgentModels.effort_override_map(project_config: project_config, global_config: global_config, harness: harness)
   end
 
@@ -1443,10 +1510,14 @@ class InstallerCore
     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
+  ADVISOR_NAME_MIGRATIONS = {
+    "plastic-advisor" => "plastic-primary-advisor",
+    "plastic-faux-advisor" => "plastic-secondary-advisor"
+  }.freeze
+  ADVISOR_SHORTHANDS = {
+    "primary" => "plastic-primary-advisor", "secondary" => "plastic-secondary-advisor",
+    "real" => "plastic-primary-advisor", "faux" => "plastic-secondary-advisor"
+  }.freeze
 
   # Write advisor.enabled / advisor.claude.default into the global config.yml
   # from install-time flags. Absent flags change nothing: advisor.enabled
@@ -1454,7 +1525,7 @@ class InstallerCore
   # (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")
+  #                        shorthand "primary"/"secondary")
   def apply_config_flags(argv)
     no_advisor = argv.include?("--no-advisor")
     advisor_idx = argv.index("--advisor")
@@ -1462,7 +1533,13 @@ class InstallerCore
     return unless no_advisor || advisor_value
 
     config_path = File.join(plastic_home, "config.yml")
-    config = load_config_yaml(config_path)
+    config = if File.exist?(config_path)
+               parsed = YAML.safe_load(File.read(config_path))
+               return false unless parsed.nil? || parsed.is_a?(Hash)
+               migrate_advisor_config(parsed || {})
+             else
+               {}
+             end
 
     if no_advisor
       config["advisor"] ||= {}
@@ -1477,6 +1554,9 @@ class InstallerCore
 
     FileUtils.mkdir_p(plastic_home)
     File.write(config_path, YAML.dump(config))
+    true
+  rescue StandardError
+    false
   end
 
   def load_config_yaml(path)
@@ -1486,6 +1566,45 @@ class InstallerCore
     {}
   end
 
+  # Renames retired advisor keys without discarding a current key. It accepts
+  # malformed config sections and leaves unrelated values untouched.
+  def migrate_advisor_config(config)
+    return {} unless config.is_a?(Hash)
+    config = Marshal.load(Marshal.dump(config))
+    advisor = config["advisor"]
+    if advisor.is_a?(Hash) && advisor["claude"].is_a?(Hash)
+      default = advisor["claude"]["default"]
+      advisor["claude"]["default"] = ADVISOR_NAME_MIGRATIONS.fetch(default, default)
+    end
+    agents = config["agents"]
+    %w[models efforts].each do |section_name|
+      section = agents.is_a?(Hash) ? agents[section_name] : nil
+      next unless section.is_a?(Hash)
+      migrate_advisor_keys!(section)
+      %w[claude codex].each { |harness| migrate_advisor_keys!(section[harness]) if section[harness].is_a?(Hash) }
+    end
+    config
+  end
+
+  def migrate_advisor_config_file(path)
+    return false unless path && File.file?(path)
+    parsed = YAML.safe_load(File.read(path))
+    return false unless parsed.is_a?(Hash)
+    migrated = migrate_advisor_config(parsed)
+    return false if migrated == parsed
+    File.write(path, YAML.dump(migrated))
+    true
+  rescue StandardError
+    false
+  end
+
+  def migrate_advisor_keys!(section)
+    ADVISOR_NAME_MIGRATIONS.each do |legacy, current|
+      section[current] = section[legacy] if !section.key?(current) && section.key?(legacy)
+      section.delete(legacy)
+    end
+  end
+
   # --- Legacy plugin migration ---
 
   # Earlier versions registered Plastic as a local marketplace plugin

package/scripts/lib/intent_screen.rb

@@ -1,4 +1,5 @@
 # encoding: UTF-8
+require_relative "store_layout"
 # frozen_string_literal: true
 # IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
 # record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
@@ -101,9 +102,8 @@ module IntentScreen
   # --- store ---------------------------------------------------------------------
 
   def self.store_fields(store_root)
-    parent = File.basename(File.dirname(store_root))
-    if parent == "projects"
-      slug = File.basename(store_root)
+    slug = Plastic::StoreLayout.locate(File.join(store_root, "store")).last
+    if slug != Plastic::StoreLayout::GLOBAL
       { "store" => "project:#{slug}", "store.note" => "the #{slug} project store" }
     else
       { "store" => "global", "store.note" => "the global store" }

package/scripts/lib/lock.rb

@@ -368,8 +368,8 @@ module Lock
   # file is inert: nothing reads it, it stays zero bytes, and
   # scripts/end-intent:558 keys its exit contract on Lock.path alone. This is
   # a requirement, not a guarantee the code enforces: the curator stray-file
-  # rule (skills/conventions/references/maintenance-and-revisions.md:155)
-  # has no *.lock carve-out today, so a wrongful delete there degrades one
+  # rule (docs/help/maintenance-and-revisions.md:155) has no *.lock
+  # carve-out today, so a wrongful delete there degrades one
   # write window to the pre-fix (unguarded) behavior, not a hard failure.
   def with_write_guard(intent_dir, type: "delivery",
                        guard_timeout: WRITE_GUARD_TIMEOUT_SECONDS,

package/scripts/lib/node_file.rb

@@ -5,7 +5,8 @@ require "yaml"
 require "date"
 
 # NodeFile (intent 334, n3): one node file's YAML envelope (`node`, `kind`,
-# `files`, `budget`) over a Markdown body, plus the deterministic id minter
+# `files`, `budget`, and the optional research `report`) over a Markdown body,
+# plus the deterministic id minter
 # (327 D1r, D5r, D9r-D12r, D16r). The kind-prefix rule lives here, not in
 # GraphEdges, which stays loose about id grammar so a numeric roadmap id
 # parses the same way (D12r).
@@ -83,6 +84,8 @@ module NodeFile
 
     budget, budget_errors = normalize_budget(fm["budget"])
     errors.concat(budget_errors)
+    report, report_errors = normalize_report(fm["report"], kind)
+    errors.concat(report_errors)
 
     {
       ok: errors.empty?,
@@ -90,15 +93,32 @@ module NodeFile
       kind: kind.empty? ? nil : kind,
       files: files.is_a?(Array) ? files : nil,
       budget: budget,
+      report: report,
       body: body,
       errors: errors,
     }
   end
 
   def failure(errors)
-    { ok: false, node: nil, kind: nil, files: nil, budget: nil, body: nil, errors: errors }
+    { ok: false, node: nil, kind: nil, files: nil, budget: nil, report: nil, body: nil, errors: errors }
   end
 
+  def normalize_report(raw, kind)
+    return [nil, []] if raw.nil?
+    return [nil, ["report: is allowed only on research nodes"]] unless kind == "research"
+    return [nil, ["report: must be a non-empty relative Markdown path under resources/"]] unless raw.is_a?(String)
+
+    path = raw
+    parts = path.split("/", -1)
+    valid = path == path.strip && parts.length >= 2 && parts.first == "resources" &&
+            parts.none? { |part| part.empty? || %w[. ..].include?(part) } &&
+            !path.include?("\\") && path.end_with?(".md")
+    return [nil, ["report: must be a relative .md path under resources/ with no traversal"]] unless valid
+
+    [path, []]
+  end
+  private_class_method :normalize_report
+
   # <id>.md or <id>--<slug>.md, exactly - a longer id's file (n11--x.md) must
   # never satisfy a shorter id (n1), so the id is matched as the whole prefix
   # up to end-of-string or the literal "--" separator, never as a substring

package/scripts/lib/node_input.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 require "date"
 require "digest"
@@ -70,7 +71,7 @@ module NodeInput
     status.success? ? truncate_landed_commits(out) : nil
   end
 
-  PROJECT_LAYOUT_RE = %r{\A(.*)/projects/([^/]+)/store/[^/]+\z}.freeze
+  PROJECT_LAYOUT_RE = %r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}.freeze
 
   # --- paths ---------------------------------------------------------------
 
@@ -118,22 +119,26 @@ module NodeInput
     end
 
     text = render_node_block(node: node, kind: parsed[:kind], files: parsed[:files], budget: parsed[:budget],
-                              body: parsed[:body])
+                              report: parsed[:report], body: parsed[:body])
     { ok: true, error_kind: nil, text: text, errors: [], kind: parsed[:kind], files: parsed[:files] || [],
-      budget: parsed[:budget] }
+      budget: parsed[:budget], report: parsed[:report] }
   end
 
   def failure_block(kind, errors)
-    { ok: false, error_kind: kind, text: nil, errors: errors, kind: nil, files: nil, budget: nil }
+    { ok: false, error_kind: kind, text: nil, errors: errors, kind: nil, files: nil, budget: nil, report: nil }
   end
   private_class_method :failure_block
 
-  def render_node_block(node:, kind:, files:, budget:, body:)
+  def render_node_block(node:, kind:, files:, budget:, body:, report: nil)
     lines = []
     lines << "# Node #{node}"
     lines << "kind: #{kind}"
     lines << "files: #{Array(files).join(', ')}"
     lines << "budget: #{budget}"
+    if report
+      lines << "report: #{report}"
+      lines << "report delivery: return the complete Markdown body in the YAML report field; the runner writes it"
+    end
     lines << ""
     lines << body.to_s.strip
     "#{lines.join("\n")}\n"
@@ -395,7 +400,7 @@ module NodeInput
     return nil unless m
 
     home, slug = m[1], m[2]
-    path = File.join(home, "projects", slug, "project.yml")
+    path = File.join(Plastic::StoreLayout.project_root(home, slug), "project.yml")
     return nil unless File.exist?(path)
 
     # `permitted_classes` (post-execution review finding B3): the same bug

package/scripts/lib/node_return.rb

@@ -33,7 +33,7 @@ module NodeReturn
   STATUSES = %w[done failed_verification needs_decision blocked].freeze
 
   ALLOWED_KEYS = %w[
-    node status commit summary findings proposed_nodes proposed_edges question reason
+    node status commit summary findings report proposed_nodes proposed_edges question reason
   ].freeze
 
   REQUIRED_FIELDS = {
@@ -51,7 +51,7 @@ module NodeReturn
 
   Result = Struct.new(
     :ok, :node, :status, :commit, :summary, :findings, :proposed_nodes, :proposed_edges,
-    :question, :reason, :errors,
+    :report, :question, :reason, :errors,
     keyword_init: true
   )
 
@@ -86,6 +86,10 @@ module NodeReturn
     proposed_edges, edge_errors = normalize_proposed_edges(doc["proposed_edges"])
     return failure(edge_errors) if edge_errors.any?
 
+    if !doc["report"].nil? && !doc["report"].is_a?(String)
+      return failure(["report: must be a Markdown string"])
+    end
+
     Result.new(
       ok: true,
       node: doc["node"].to_s,
@@ -95,6 +99,7 @@ module NodeReturn
       findings: normalize_findings(doc["findings"]),
       proposed_nodes: proposed_nodes,
       proposed_edges: proposed_edges,
+      report: doc["report"],
       question: doc["question"],
       reason: doc["reason"],
       errors: [],
@@ -111,7 +116,7 @@ module NodeReturn
   def failure(errors)
     Result.new(
       ok: false, node: nil, status: nil, commit: nil, summary: nil, findings: [],
-      proposed_nodes: [], proposed_edges: [], question: nil, reason: nil,
+      proposed_nodes: [], proposed_edges: [], report: nil, question: nil, reason: nil,
       errors: Array(errors)
     )
   end

package/scripts/lib/preflight.rb

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-require "rubygems"
+require_relative "version_number"
 
 # Pure, dependency-injected pre-flight checks for Plastic's runtime dependencies
 # (intent 38). Takes injected probes (ruby version, node version, git presence,
@@ -63,9 +63,7 @@ module Preflight
   end
 
   def safe_version(str)
-    Gem::Version.new(str.to_s)
-  rescue ArgumentError
-    nil
+    VersionNumber.parse(str)
   end
 
   def strip_leading_v(str)

package/scripts/lib/project_config.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 
 # ProjectConfig - reads a project's project.yml merged over the shipped defaults
@@ -18,7 +19,7 @@ module ProjectConfig
   }.freeze
 
   def read(slug)
-    path = File.join(Dir.home, ".plastic", "projects", slug, "project.yml")
+    path = File.join(Plastic::StoreLayout.project_root(File.join(Dir.home, ".plastic"), slug), "project.yml")
     config = if File.exist?(path)
                YAML.safe_load(File.read(path)) || {}
              else