@zalom/plastic 1.0.0-alpha.5 → 1.0.0-alpha.6

package/package.json

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

package/scripts/doctor.rb

@@ -0,0 +1,888 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Plastic doctor — diagnostic engine that checks a Plastic installation for health issues.
+# Usage: ruby ~/.plastic/scripts/doctor.rb [--agent claude|codex|hermes] [--help]
+#
+# Output: JSON to stdout. Warnings/errors to stderr.
+# Exit codes: 0 (all pass), 1 (warnings only), 2 (failures present)
+# Read-only — never modifies files.
+
+require "json"
+require "yaml"
+require "time"
+
+PLASTIC_HOME = File.join(Dir.home, ".plastic")
+
+AGENTS = {
+  "claude" => { name: "Claude Code", dir: File.join(Dir.home, ".claude") },
+  "codex"  => { name: "Codex CLI",   dir: File.join(Dir.home, ".agents") },
+  "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
+}.freeze
+
+REQUIRED_INDEX_SECTIONS = ["## Active", "## Future", "## Clusters", "## Abandoned", "## Completed"].freeze
+
+REQUIRED_FRONTMATTER_FIELDS = %w[id intent sources chain created author tags].freeze
+
+CLAUDE_HOOK_SCRIPTS = %w[
+  plastic-session-start
+  plastic-check-update
+  plastic-savepoint
+  plastic-gate-check
+  plastic-continue
+  plastic-future-intent-check
+].freeze
+
+CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit].freeze
+
+REQUIRED_SCRIPTS = %w[
+  folgezettel-id
+  read-config
+  hook-session-start
+  hook-continue
+  hook-future-intent-check
+  hook-gate-check
+  doctor.rb
+].freeze
+
+# --- Flag parsing ---
+
+def parse_args(argv)
+  agent = "claude"
+  help = false
+
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--agent"
+      if argv[i + 1] && AGENTS.key?(argv[i + 1])
+        agent = argv[i + 1]
+        i += 2
+      else
+        $stderr.puts "Error: --agent requires one of: #{AGENTS.keys.join(", ")}"
+        exit 2
+      end
+    when "--help", "-h"
+      help = true
+      i += 1
+    else
+      i += 1
+    end
+  end
+
+  { agent: agent, help: help }
+end
+
+def show_help
+  $stderr.puts <<~HELP
+
+    plastic doctor — diagnose Plastic installation health
+
+    Usage:
+      ruby ~/.plastic/scripts/doctor.rb [options]
+
+    Options:
+      --agent NAME    Agent to check: claude (default), codex, hermes
+      -h, --help      Show this help
+
+    Output:
+      JSON to stdout with check results.
+      Exit 0 = all pass, 1 = warnings only, 2 = failures present.
+
+  HELP
+end
+
+# --- Utility helpers ---
+
+def read_version
+  version_path = File.join(PLASTIC_HOME, "VERSION")
+  return nil unless File.exist?(version_path)
+
+  File.read(version_path).strip
+end
+
+def read_json_safe(path)
+  return nil unless File.exist?(path)
+
+  JSON.parse(File.read(path))
+rescue JSON::ParserError
+  content = File.read(path).gsub(%r{//[^\n]*}, "").gsub(/,(\s*[}\]])/, '\1')
+  JSON.parse(content)
+rescue
+  nil
+end
+
+def load_yaml_safe(path)
+  return nil unless File.exist?(path)
+
+  YAML.safe_load(File.read(path)) || {}
+rescue => e
+  $stderr.puts "Warning: failed to parse #{path}: #{e.message}"
+  nil
+end
+
+def tilde(path)
+  path.sub(Dir.home, "~")
+end
+
+def check(category:, name:, status:, message:, details: [], fixable: false, fix_hint: nil)
+  result = {
+    category: category,
+    name: name,
+    status: status,
+    message: message,
+    details: details,
+    fixable: fixable,
+  }
+  result[:fix_hint] = fix_hint if fix_hint
+  result
+end
+
+# --- Parse frontmatter from an intent markdown file ---
+
+def parse_frontmatter(path)
+  return nil unless File.exist?(path)
+
+  content = File.read(path)
+  return nil unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return nil if parts.length < 3
+
+  YAML.safe_load(parts[1]) || {}
+rescue
+  nil
+end
+
+# --- Collect all intent directories (global + project stores) ---
+
+def all_intent_dirs
+  dirs = []
+
+  global_store = File.join(PLASTIC_HOME, "store")
+  if File.directory?(global_store)
+    Dir.children(global_store).each do |entry|
+      full = File.join(global_store, entry)
+      dirs << { path: full, name: entry, scope: "global" } if File.directory?(full)
+    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)
+
+      Dir.children(project_store).each do |entry|
+        full = File.join(project_store, entry)
+        dirs << { path: full, name: entry, scope: "project:#{project}" } if File.directory?(full)
+      end
+    end
+  end
+
+  dirs
+end
+
+# --- Check category 1: Global store ---
+
+def check_global_store
+  checks = []
+
+  index_path = File.join(PLASTIC_HOME, "INDEX.md")
+
+  # index_exists
+  if File.exist?(index_path)
+    checks << check(
+      category: "global_store", name: "index_exists", status: "pass",
+      message: "INDEX.md exists"
+    )
+  else
+    checks << check(
+      category: "global_store", name: "index_exists", status: "fail",
+      message: "INDEX.md not found at #{tilde(index_path)}",
+      fixable: true, fix_hint: "Run the Plastic installer to bootstrap the store"
+    )
+    return checks # Can't check sections/references without INDEX.md
+  end
+
+  # index_sections
+  content = File.read(index_path)
+  missing_sections = REQUIRED_INDEX_SECTIONS.reject { |s| content.include?(s) }
+
+  if missing_sections.empty?
+    checks << check(
+      category: "global_store", name: "index_sections", status: "pass",
+      message: "INDEX.md has all 5 required sections"
+    )
+  else
+    checks << check(
+      category: "global_store", name: "index_sections", status: "fail",
+      message: "INDEX.md missing #{missing_sections.size} required section(s)",
+      details: missing_sections,
+      fixable: true, fix_hint: "Add missing sections to INDEX.md"
+    )
+  end
+
+  # orphaned_intents — directories in store/ not referenced in INDEX.md
+  store_dir = File.join(PLASTIC_HOME, "store")
+  if File.directory?(store_dir)
+    intent_dirs = Dir.children(store_dir).select { |e| File.directory?(File.join(store_dir, e)) }
+    orphans = intent_dirs.reject { |d| content.include?("store/#{d}") }
+
+    if orphans.empty?
+      checks << check(
+        category: "global_store", name: "orphaned_intents", status: "pass",
+        message: "No orphaned intent directories"
+      )
+    else
+      checks << check(
+        category: "global_store", name: "orphaned_intents", status: "warn",
+        message: "#{orphans.size} intent director#{orphans.size == 1 ? "y" : "ies"} not referenced in INDEX.md",
+        details: orphans.map { |d| "store/#{d}" },
+        fixable: true, fix_hint: "Add missing intents to INDEX.md or remove orphaned directories"
+      )
+    end
+  end
+
+  # ghost_references — paths in INDEX.md pointing to non-existent directories
+  store_refs = content.scan(%r{store/[\w][\w-]*(?:/[\w][\w.-]*)*/?\b}).uniq
+  # Normalize: extract just the store/ID--slug portion
+  store_paths = content.scan(%r{store/\S+}).map { |ref| ref.gsub(/[)\]>].*/, "").chomp("/") }.uniq
+
+  ghosts = store_paths.select do |ref|
+    full_path = File.join(PLASTIC_HOME, ref)
+    !File.exist?(full_path) && !File.directory?(full_path)
+  end
+
+  if ghosts.empty?
+    checks << check(
+      category: "global_store", name: "ghost_references", status: "pass",
+      message: "No ghost references in INDEX.md"
+    )
+  else
+    checks << check(
+      category: "global_store", name: "ghost_references", status: "warn",
+      message: "#{ghosts.size} path(s) in INDEX.md point to non-existent locations",
+      details: ghosts,
+      fixable: true, fix_hint: "Remove or fix broken references in INDEX.md"
+    )
+  end
+
+  checks
+end
+
+# --- Check category 2: Conventions ---
+
+def check_conventions
+  checks = []
+
+  intent_dirs = all_intent_dirs
+  dirname_pattern = /^\w+--[\w-]+$/
+
+  # intent_dirname
+  bad_dirnames = intent_dirs.reject { |d| d[:name].match?(dirname_pattern) }
+
+  if bad_dirnames.empty?
+    checks << check(
+      category: "conventions", name: "intent_dirname", status: "pass",
+      message: "All #{intent_dirs.size} intent directories follow {ID}--{slug} format"
+    )
+  else
+    checks << check(
+      category: "conventions", name: "intent_dirname", status: "warn",
+      message: "#{bad_dirnames.size} intent director#{bad_dirnames.size == 1 ? "y doesn't" : "ies don't"} follow {ID}--{slug} format",
+      details: bad_dirnames.map { |d| "#{tilde(d[:path])} (#{d[:scope]})" },
+      fixable: true, fix_hint: "Rename directories to {ID}--{slug} format"
+    )
+  end
+
+  # intent_filename — primary file inside directory matches {ID}--{slug}.md
+  bad_filenames = []
+  intent_dirs.each do |d|
+    expected_file = "#{d[:name]}.md"
+    expected_path = File.join(d[:path], expected_file)
+    unless File.exist?(expected_path)
+      bad_filenames << { dir: d, expected: expected_file }
+    end
+  end
+
+  if bad_filenames.empty?
+    checks << check(
+      category: "conventions", name: "intent_filename", status: "pass",
+      message: "All intent directories have matching {ID}--{slug}.md files"
+    )
+  else
+    checks << check(
+      category: "conventions", name: "intent_filename", status: "warn",
+      message: "#{bad_filenames.size} intent director#{bad_filenames.size == 1 ? "y" : "ies"} missing primary .md file",
+      details: bad_filenames.map { |b| "#{tilde(b[:dir][:path])} — expected #{b[:expected]}" },
+      fixable: true, fix_hint: "Create or rename the primary .md file to match the directory name"
+    )
+  end
+
+  # frontmatter_fields
+  bad_frontmatter = []
+  intent_dirs.each do |d|
+    md_path = File.join(d[:path], "#{d[:name]}.md")
+    next unless File.exist?(md_path)
+
+    fm = parse_frontmatter(md_path)
+    if fm.nil?
+      bad_frontmatter << { dir: tilde(d[:path]), missing: ["(no frontmatter found)"] }
+      next
+    end
+
+    missing = REQUIRED_FRONTMATTER_FIELDS.reject { |f| fm.key?(f) }
+    bad_frontmatter << { dir: tilde(d[:path]), missing: missing } unless missing.empty?
+  end
+
+  if bad_frontmatter.empty?
+    checks << check(
+      category: "conventions", name: "frontmatter_fields", status: "pass",
+      message: "All intent files have required frontmatter fields"
+    )
+  else
+    checks << check(
+      category: "conventions", name: "frontmatter_fields", status: "warn",
+      message: "#{bad_frontmatter.size} intent file(s) missing required frontmatter fields",
+      details: bad_frontmatter.map { |b| "#{b[:dir]}: missing #{b[:missing].join(", ")}" },
+      fixable: false
+    )
+  end
+
+  checks
+end
+
+# --- Check category 3: Agent registration ---
+
+def check_agent_registration(agent_key)
+  checks = []
+  config = AGENTS[agent_key]
+  agent_dir = config[:dir]
+
+  unless File.directory?(agent_dir)
+    checks << check(
+      category: "agent_registration", name: "agent_dir_exists", status: "fail",
+      message: "Agent directory #{tilde(agent_dir)} not found — #{config[:name]} may not be installed",
+      fixable: false
+    )
+    return checks
+  end
+
+  case agent_key
+  when "claude"
+    checks += check_claude_registration(agent_dir)
+  else
+    checks += check_generic_agent_registration(agent_key, agent_dir)
+  end
+
+  checks
+end
+
+def check_claude_registration(agent_dir)
+  checks = []
+  hooks_dir = File.join(agent_dir, "hooks")
+
+  # hooks_exist
+  missing_hooks = CLAUDE_HOOK_SCRIPTS.reject { |h| File.exist?(File.join(hooks_dir, h)) }
+
+  if missing_hooks.empty?
+    checks << check(
+      category: "agent_registration", name: "hooks_exist", status: "pass",
+      message: "All #{CLAUDE_HOOK_SCRIPTS.size} expected hook scripts exist"
+    )
+  else
+    checks << check(
+      category: "agent_registration", name: "hooks_exist", status: "fail",
+      message: "#{missing_hooks.size} hook script(s) missing",
+      details: missing_hooks.map { |h| "#{tilde(hooks_dir)}/#{h}" },
+      fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
+    )
+  end
+
+  # hooks_executable
+  existing_hooks = CLAUDE_HOOK_SCRIPTS
+    .map { |h| File.join(hooks_dir, h) }
+    .select { |p| File.exist?(p) }
+
+  non_executable = existing_hooks.reject { |p| File.executable?(p) }
+
+  if non_executable.empty?
+    checks << check(
+      category: "agent_registration", name: "hooks_executable", status: "pass",
+      message: "All existing hook scripts are executable"
+    )
+  else
+    checks << check(
+      category: "agent_registration", name: "hooks_executable", status: "fail",
+      message: "#{non_executable.size} hook script(s) not executable",
+      details: non_executable.map { |p| tilde(p) },
+      fixable: true, fix_hint: "chmod +x on the listed files"
+    )
+  end
+
+  # hooks_registered — settings.json has Plastic hooks for required events
+  settings_path = File.join(agent_dir, "settings.json")
+  settings = read_json_safe(settings_path)
+
+  if settings.nil?
+    checks << check(
+      category: "agent_registration", name: "hooks_registered", status: "fail",
+      message: "Cannot read #{tilde(settings_path)} — file missing or invalid",
+      fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
+    )
+  else
+    hooks = settings["hooks"] || {}
+    missing_events = CLAUDE_HOOK_EVENTS.reject do |event|
+      groups = hooks[event]
+      next false unless groups.is_a?(Array)
+
+      groups.any? do |group|
+        group.is_a?(Hash) && group["hooks"].is_a?(Array) &&
+          group["hooks"].any? { |h| h["command"].to_s.include?("plastic-") }
+      end
+    end
+
+    if missing_events.empty?
+      checks << check(
+        category: "agent_registration", name: "hooks_registered", status: "pass",
+        message: "All #{CLAUDE_HOOK_EVENTS.size} hook events registered in settings.json"
+      )
+    else
+      checks << check(
+        category: "agent_registration", name: "hooks_registered", status: "fail",
+        message: "#{missing_events.size} hook event(s) not registered in settings.json",
+        details: missing_events,
+        fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
+      )
+    end
+  end
+
+  # skills_exist
+  skills_dir = File.join(agent_dir, "skills", "plastic")
+  if File.directory?(skills_dir) && !Dir.empty?(skills_dir)
+    checks << check(
+      category: "agent_registration", name: "skills_exist", status: "pass",
+      message: "Skills directory exists at #{tilde(skills_dir)}"
+    )
+  else
+    checks << check(
+      category: "agent_registration", name: "skills_exist", status: "fail",
+      message: "Skills directory missing or empty at #{tilde(skills_dir)}",
+      fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
+    )
+  end
+
+  checks
+end
+
+def check_generic_agent_registration(agent_key, agent_dir)
+  checks = []
+  config = AGENTS[agent_key]
+
+  # For codex/hermes: just check skills exist (no settings.json hooks)
+  skills_dir = File.join(agent_dir, "skills", "plastic")
+  if File.directory?(skills_dir) && !Dir.empty?(skills_dir)
+    checks << check(
+      category: "agent_registration", name: "skills_exist", status: "pass",
+      message: "Skills directory exists at #{tilde(skills_dir)}"
+    )
+  else
+    checks << check(
+      category: "agent_registration", name: "skills_exist", status: "fail",
+      message: "Skills directory missing or empty at #{tilde(skills_dir)}",
+      fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --#{agent_key}"
+    )
+  end
+
+  checks
+end
+
+# --- Check category 4: Core files ---
+
+def check_core_files(agent_key)
+  checks = []
+
+  # plastic_md
+  plastic_md = File.join(PLASTIC_HOME, "PLASTIC.md")
+  if File.exist?(plastic_md)
+    checks << check(
+      category: "core_files", name: "plastic_md", status: "pass",
+      message: "PLASTIC.md exists"
+    )
+  else
+    checks << check(
+      category: "core_files", name: "plastic_md", status: "fail",
+      message: "PLASTIC.md not found at #{tilde(plastic_md)}",
+      fixable: true, fix_hint: "Re-run the Plastic installer to restore core files"
+    )
+  end
+
+  # version_file
+  version_path = File.join(PLASTIC_HOME, "VERSION")
+  if File.exist?(version_path)
+    checks << check(
+      category: "core_files", name: "version_file", status: "pass",
+      message: "VERSION file exists"
+    )
+  else
+    checks << check(
+      category: "core_files", name: "version_file", status: "fail",
+      message: "VERSION file not found at #{tilde(version_path)}",
+      fixable: true, fix_hint: "Re-run the Plastic installer to restore core files"
+    )
+  end
+
+  # scripts_present
+  scripts_dir = File.join(PLASTIC_HOME, "scripts")
+  missing_scripts = REQUIRED_SCRIPTS.reject { |s| File.exist?(File.join(scripts_dir, s)) }
+
+  if missing_scripts.empty?
+    checks << check(
+      category: "core_files", name: "scripts_present", status: "pass",
+      message: "All #{REQUIRED_SCRIPTS.size} required scripts present"
+    )
+  else
+    checks << check(
+      category: "core_files", name: "scripts_present", status: "fail",
+      message: "#{missing_scripts.size} required script(s) missing from #{tilde(scripts_dir)}",
+      details: missing_scripts,
+      fixable: true, fix_hint: "Re-run the Plastic installer to restore scripts"
+    )
+  end
+
+  # scripts_executable
+  if File.directory?(scripts_dir)
+    script_files = Dir.children(scripts_dir)
+      .map { |f| File.join(scripts_dir, f) }
+      .select { |f| File.file?(f) }
+
+    non_executable = script_files.reject { |f| File.executable?(f) }
+
+    if non_executable.empty?
+      checks << check(
+        category: "core_files", name: "scripts_executable", status: "pass",
+        message: "All scripts in #{tilde(scripts_dir)} are executable"
+      )
+    else
+      checks << check(
+        category: "core_files", name: "scripts_executable", status: "fail",
+        message: "#{non_executable.size} script(s) not executable",
+        details: non_executable.map { |f| tilde(f) },
+        fixable: true, fix_hint: "chmod +x on the listed files"
+      )
+    end
+  end
+
+  # version_match — compare global VERSION with agent-side VERSION
+  global_version = read_version
+  agent_config = AGENTS[agent_key]
+
+  if global_version && agent_config
+    agent_version_path = case agent_key
+                         when "claude" then File.join(agent_config[:dir], "plastic", "VERSION")
+                         else File.join(agent_config[:dir], "plastic", "VERSION")
+                         end
+
+    if File.exist?(agent_version_path)
+      agent_version = File.read(agent_version_path).strip
+
+      if global_version == agent_version
+        checks << check(
+          category: "core_files", name: "version_match", status: "pass",
+          message: "Global VERSION (#{global_version}) matches agent-side VERSION"
+        )
+      else
+        checks << check(
+          category: "core_files", name: "version_match", status: "warn",
+          message: "Version mismatch: global=#{global_version}, agent=#{agent_version}",
+          details: [
+            "#{tilde(File.join(PLASTIC_HOME, "VERSION"))}: #{global_version}",
+            "#{tilde(agent_version_path)}: #{agent_version}",
+          ],
+          fixable: false
+        )
+      end
+    else
+      checks << check(
+        category: "core_files", name: "version_match", status: "warn",
+        message: "Agent-side VERSION file not found at #{tilde(agent_version_path)}",
+        fixable: false
+      )
+    end
+  end
+
+  checks
+end
+
+# --- Check category 5: Project stores ---
+
+def check_project_stores
+  checks = []
+
+  projects_yml_path = File.join(PLASTIC_HOME, "projects.yml")
+  projects_data = load_yaml_safe(projects_yml_path)
+
+  if projects_data.nil?
+    checks << check(
+      category: "project_stores", name: "projects_yml", status: "warn",
+      message: "projects.yml not found or invalid at #{tilde(projects_yml_path)}",
+      fixable: true, fix_hint: "Re-run the Plastic installer to restore projects.yml"
+    )
+    return checks
+  end
+
+  projects = projects_data["projects"]
+  unless projects.is_a?(Hash) && !projects.empty?
+    # No projects registered — nothing to check
+    checks << check(
+      category: "project_stores", name: "projects_yml", status: "pass",
+      message: "projects.yml is valid (#{projects.is_a?(Hash) ? projects.size : 0} projects registered)"
+    )
+    return checks
+  end
+
+  # Load INDEX.md content for cross-reference checks
+  index_path = File.join(PLASTIC_HOME, "INDEX.md")
+  index_content = File.exist?(index_path) ? File.read(index_path) : ""
+
+  projects.each do |slug, project_info|
+    project_dir = File.join(PLASTIC_HOME, "projects", slug)
+
+    # project_dir_exists
+    if File.directory?(project_dir)
+      checks << check(
+        category: "project_stores", name: "project_dir_exists", status: "pass",
+        message: "Project directory exists for '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "project_dir_exists", status: "warn",
+        message: "Project directory missing for '#{slug}'",
+        details: [tilde(project_dir)],
+        fixable: true, fix_hint: "Create the project store directory: mkdir -p #{tilde(project_dir)}"
+      )
+    end
+
+    # project_index
+    project_index = File.join(project_dir, "INDEX.md")
+    if File.exist?(project_index)
+      checks << check(
+        category: "project_stores", name: "project_index", status: "pass",
+        message: "INDEX.md exists for project '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "project_index", status: "warn",
+        message: "INDEX.md missing for project '#{slug}'",
+        details: [tilde(project_index)],
+        fixable: true, fix_hint: "Create INDEX.md in the project store directory"
+      )
+    end
+
+    # cross_references — if project has `parent` field, check global store intent tags
+    parent_id = project_info.is_a?(Hash) ? project_info["parent"] : nil
+    next unless parent_id
+
+    # Find the intent directory for the parent ID
+    store_dir = File.join(PLASTIC_HOME, "store")
+    parent_dir = nil
+    if File.directory?(store_dir)
+      parent_dir = Dir.children(store_dir).find { |d| d.start_with?("#{parent_id}--") }
+    end
+
+    if parent_dir.nil?
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Parent intent '#{parent_id}' for project '#{slug}' not found in global store",
+        fixable: false
+      )
+      next
+    end
+
+    intent_md = File.join(store_dir, parent_dir, "#{parent_dir}.md")
+    fm = parse_frontmatter(intent_md)
+
+    if fm.nil?
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Cannot read frontmatter of parent intent '#{parent_id}' for project '#{slug}'",
+        fixable: false
+      )
+      next
+    end
+
+    tags = fm["tags"]
+    expected_tag = "project-#{slug}"
+
+    if tags.is_a?(Array) && tags.include?(expected_tag)
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "pass",
+        message: "Parent intent '#{parent_id}' has '#{expected_tag}' tag for project '#{slug}'"
+      )
+    else
+      checks << check(
+        category: "project_stores", name: "cross_references", status: "warn",
+        message: "Parent intent '#{parent_id}' missing '#{expected_tag}' tag",
+        details: ["Intent: store/#{parent_dir}", "Expected tag: #{expected_tag}", "Current tags: #{(tags || []).inspect}"],
+        fixable: false
+      )
+    end
+  end
+
+  checks
+end
+
+# --- Check category 6: Deprecations ---
+
+def check_deprecations
+  checks = []
+
+  deprecations_path = File.join(PLASTIC_HOME, "deprecations.yml")
+  data = load_yaml_safe(deprecations_path)
+
+  if data.nil?
+    checks << check(
+      category: "deprecations", name: "deprecations_file", status: "pass",
+      message: "No deprecations.yml found (nothing to report)"
+    )
+    return checks
+  end
+
+  entries = data["deprecations"]
+  unless entries.is_a?(Array) && !entries.empty?
+    checks << check(
+      category: "deprecations", name: "active_deprecations", status: "pass",
+      message: "No deprecation entries found"
+    )
+    return checks
+  end
+
+  current_version = read_version
+  unless current_version
+    checks << check(
+      category: "deprecations", name: "active_deprecations", status: "warn",
+      message: "Cannot compare deprecation versions — VERSION file missing",
+      fixable: false
+    )
+    return checks
+  end
+
+  # Find deprecations where removal version is greater than current version
+  # Use simple string comparison on semver (works for well-formed versions)
+  active = entries.select do |entry|
+    removal = entry["removal"].to_s
+    next false if removal.empty?
+
+    compare_versions(current_version, removal) < 0
+  end
+
+  if active.empty?
+    checks << check(
+      category: "deprecations", name: "active_deprecations", status: "pass",
+      message: "No active deprecations for current version (#{current_version})"
+    )
+  else
+    details = active.map do |entry|
+      lines = ["[#{entry["severity"]}] #{entry["summary"]} (removal: #{entry["removal"]})"]
+      if entry["migration_steps"].is_a?(Array)
+        entry["migration_steps"].each { |step| lines << "  - #{step}" }
+      end
+      lines.join("\n")
+    end
+
+    checks << check(
+      category: "deprecations", name: "active_deprecations", status: "warn",
+      message: "#{active.size} active deprecation(s) for version #{current_version}",
+      details: details,
+      fixable: false
+    )
+  end
+
+  checks
+end
+
+# Compare two semver strings. Returns -1, 0, or 1.
+# Handles pre-release tags: 1.0.0-alpha.5 < 1.0.0 < 2.0.0
+def compare_versions(a, b)
+  parse = ->(v) {
+    base, pre = v.split("-", 2)
+    segments = base.split(".").map(&:to_i)
+    [segments, pre]
+  }
+
+  a_segments, a_pre = parse.call(a)
+  b_segments, b_pre = parse.call(b)
+
+  # Pad to equal length
+  max_len = [a_segments.size, b_segments.size].max
+  a_segments += [0] * (max_len - a_segments.size)
+  b_segments += [0] * (max_len - b_segments.size)
+
+  cmp = (a_segments <=> b_segments)
+  return cmp unless cmp == 0
+
+  # Same base version: no pre-release > pre-release (1.0.0 > 1.0.0-alpha)
+  return 0 if a_pre.nil? && b_pre.nil?
+  return 1 if a_pre.nil? && b_pre
+  return -1 if a_pre && b_pre.nil?
+
+  # Both have pre-release: compare lexically
+  a_pre <=> b_pre
+end
+
+# --- Run all checks ---
+
+def run_checks(agent_key)
+  all_checks = []
+  all_checks += check_global_store
+  all_checks += check_conventions
+  all_checks += check_agent_registration(agent_key)
+  all_checks += check_core_files(agent_key)
+  all_checks += check_project_stores
+  all_checks += check_deprecations
+
+  summary = { pass: 0, warn: 0, fail: 0, total: all_checks.size }
+  all_checks.each { |c| summary[c[:status].to_sym] += 1 }
+
+  overall = if summary[:fail] > 0
+              "fail"
+            elsif summary[:warn] > 0
+              "warn"
+            else
+              "pass"
+            end
+
+  {
+    version: read_version || "unknown",
+    timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    status: overall,
+    agent: agent_key,
+    checks: all_checks,
+    summary: summary,
+  }
+end
+
+# --- Main ---
+
+def main
+  flags = parse_args(ARGV)
+
+  if flags[:help]
+    show_help
+    exit 0
+  end
+
+  result = run_checks(flags[:agent])
+
+  puts JSON.pretty_generate(result)
+
+  case result[:status]
+  when "fail" then exit 2
+  when "warn" then exit 1
+  else exit 0
+  end
+end
+
+main

package/scripts/install.rb

@@ -153,6 +153,7 @@ def distribute(mode)
     "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
     "scripts/hook-gate-check" => "scripts/hook-gate-check",
     "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+    "scripts/doctor.rb" => "scripts/doctor.rb",
   }
 
   core_files.each do |src, dest|

package/skills/doctor/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: doctor
+description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
+---
+
+# Doctor — Plastic Health Check
+
+## When to Use
+
+- User invokes `/plastic:doctor`
+- After `plastic:update` completes (automatically)
+- When hooks aren't firing, skills aren't loading, or something seems broken
+- When the user says "check plastic", "diagnose", "what's wrong with plastic"
+
+## Procedure
+
+### Step 1: Run the diagnostic script
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Replace `claude` with the current agent type if known (`codex`, `hermes`).
+
+Parse the JSON output from stdout. The script is read-only and never modifies
+files. Errors go to stderr.
+
+Exit codes indicate check results, not script failure:
+- `0` — all checks passed
+- `1` — warnings found
+- `2` — failures found
+
+All three exit codes mean the script ran successfully. Do not treat non-zero
+as an error.
+
+### Step 2: Determine overall status
+
+Read the `status` field from the JSON root:
+
+| Status | Meaning |
+|--------|---------|
+| `pass` | Everything is healthy |
+| `warn` | Warnings found but Plastic works normally |
+| `fail` | Blocking issues that prevent Plastic from operating |
+
+### Step 3: Fill the report template
+
+Read `report.md` from the same directory as this SKILL.md
+(`~/.plastic/skills/doctor/report.md` at runtime, or the plugin source
+`skills/doctor/report.md` during development).
+
+Group checks by category. For each category, list the checks with their
+status icon and message. If a check has `details`, list them as sub-items.
+
+Present the filled template to the user.
+
+### Step 4: Offer fixes (if applicable)
+
+If any checks have `fixable: true` AND status is not `pass`:
+
+1. Group fixable items by category
+2. Show what each fix would do (from `fix_hint`)
+3. Ask the user: **"Fix all / Select individually / Skip"**
+
+If no fixable issues exist, skip this step.
+
+### Step 5: Apply fixes
+
+Use the `fix_hint` value to determine the correct action:
+
+| Fix hint pattern | Agent action |
+|---|---|
+| "chmod +x on the listed files" | Run `chmod +x` on each file listed in `details` |
+| "Create missing directory" | Run `mkdir -p` on the path |
+| "Create INDEX.md with required sections" | Write INDEX.md with the 5 sections: Active, Future, Clusters, Abandoned, Completed |
+| "Add missing entries to INDEX.md" | Add orphaned intents to the appropriate INDEX.md section |
+| "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
+| "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+
+For fixes the agent cannot handle automatically, explain what the user needs
+to do manually.
+
+### Step 6: Verify
+
+After applying fixes, re-run the diagnostic script:
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Show the updated results.
+
+- If all checks pass: announce success.
+- If issues remain: explain what is still wrong and what the user can do.
+
+## Post-Update Mode
+
+When invoked from `plastic:update` (not directly by the user):
+
+1. Run the diagnostic script as in Step 1.
+2. If all checks pass: show a single line — **"Health check: all clear."**
+3. If issues are found: show the full report (Steps 3-6).
+
+This keeps the update flow clean when nothing is wrong.
+
+## Important Notes
+
+- The script is **read-only**. It inspects but never modifies files.
+  All fixes are performed by the agent using standard tools.
+- The script outputs JSON to stdout. Any diagnostic errors go to stderr.
+- Non-zero exit codes mean "issues found", not "script crashed".
+  Always parse stdout regardless of exit code.

package/skills/doctor/report.md

@@ -0,0 +1,96 @@
+# Plastic Doctor Report
+
+<!-- =======================================================================
+  AGENT INSTRUCTIONS -- How to fill this template
+  =========================================================================
+  1. Run the doctor script. It outputs JSON with check results.
+  2. Replace every {{placeholder}} below with the corresponding JSON value.
+  3. For the category sections: the template shows ONE example section.
+     Repeat that pattern for each unique category in the checks array.
+     The six known categories and their display names are:
+       global_store       -> "Global Store"
+       conventions        -> "Conventions"
+       agent_registration -> "Agent Registration"
+       core_files         -> "Core Files"
+       project_stores     -> "Project Stores"
+       deprecations       -> "Deprecations"
+  4. For each check within a category, emit one line with the status icon
+     and the check message. If the check has non-empty details, list them
+     as indented sub-items.
+  5. The "Fixable Issues" section should ONLY appear if at least one check
+     has fixable=true AND status is not "pass". Omit the entire section
+     otherwise.
+  6. Status icons (plain text, no emoji):
+       pass -> [PASS]
+       warn -> [WARN]
+       fail -> [FAIL]
+  7. The overall status icon in the header uses the same mapping.
+  8. After filling, remove all HTML comments -- they are instructions only.
+  ======================================================================= -->
+
+## {{overall_status_icon}} Overall: {{status}} -- Plastic v{{version}}
+
+Checked at: {{timestamp}}
+
+### Summary
+
+{{pass}} passed, {{warn}} warnings, {{fail}} failed -- {{total}} checks total
+
+---
+
+<!-- =====================================================================
+  CATEGORY SECTIONS
+  ======================================================================
+  Repeat the block below ONCE PER CATEGORY present in the checks array.
+  Group checks by their "category" field. Use the display name mapping
+  above for the heading. Within each category, list every check as a
+  single line: status icon + message. If a check has non-empty "details",
+  list each detail as an indented bullet beneath.
+
+  Example category section (for agent_registration with two checks):
+  ===================================================================== -->
+
+### Agent Registration
+
+- [PASS] Claude Code adapter registered
+- [FAIL] 2 hook scripts not executable
+  - ~/.claude/hooks/plastic-session-start
+  - ~/.claude/hooks/plastic-gate-check
+
+<!-- =====================================================================
+  Repeat the above pattern for each category found in the checks array.
+  Only include categories that have at least one check.
+  Order categories as they appear in the checks array.
+  ===================================================================== -->
+
+---
+
+<!-- =====================================================================
+  FIXABLE ISSUES SECTION
+  ======================================================================
+  Include this section ONLY if one or more checks have fixable=true AND
+  status is "warn" or "fail". If no fixable issues exist, omit everything
+  from the "Fixable Issues" heading through the end of the horizontal
+  rule that follows the table.
+
+  For each fixable check that is not "pass", emit one table row:
+    | status_icon | check_message | fix_hint |
+  ===================================================================== -->
+
+### Fixable Issues
+
+| Status | Issue | Fix |
+|--------|-------|-----|
+| [FAIL] | 2 hook scripts not executable | chmod +x on the listed files |
+
+<!-- =====================================================================
+  Repeat one row per fixable non-pass check.
+  ===================================================================== -->
+
+---
+
+<!-- =====================================================================
+  FOOTER -- always include this line exactly as written.
+  ===================================================================== -->
+
+Run `plastic doctor --fix` to auto-fix all fixable issues, or ask me to fix them now.

package/skills/update/SKILL.md

@@ -54,13 +54,21 @@ Key changes in this version:
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Commit
+### Step 4: Run health check
+
+Invoke `plastic:doctor` to verify the installation is healthy after the update.
+
+If all checks pass, show: **"Health check: all clear."**
+
+If issues are found, show the full doctor report and offer to fix any fixable items.
+
+### Step 5: Commit
 
 ```bash
 cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
 ```
 
-### Step 5: Clear update cache
+### Step 6: Clear update cache
 
 ```bash
 rm -f ~/.plastic/.cache/update-check.json