@oevery/rsp 2.0.3 → 3.1.0-beta.0

package/dist/cli.mjs

@@ -1,609 +1,97 @@
 #!/usr/bin/env node
+import {
+  ARCHIVES_DIR,
+  ArchiveHistoryError,
+  CHANGES_DIR,
+  CONFIG_PATH,
+  DEFAULT_DECISION_RECORDS_PATH,
+  FOCUS_DIR,
+  GROUP_BRIEF_FILENAME,
+  HISTORY_DEFAULT_LIMIT,
+  HISTORY_MAX_LIMIT,
+  LOCK_PATH,
+  ManagedPathError,
+  OBSOLETE_RSP_RULES_PATH,
+  PKG_ROOT,
+  RSP_DIR,
+  RSP_RULES_PATH,
+  VALID_KINDS,
+  WorkRefError,
+  buildDurableReviewGuidance,
+  cleanupEmptyParentDirs,
+  clearConfigCache,
+  collectArchiveChecklist,
+  collectArchiveReadiness,
+  countCheckboxes,
+  detectDeltaSections,
+  detectProjectName,
+  emitJson,
+  ensureDecisionRecordsDirectory,
+  ensureManagedFile,
+  extractSection,
+  generateChangeContent,
+  generateDesignContent,
+  generateGroupBriefContent,
+  generateSpecContent,
+  getDurableReviewCandidateTargets,
+  getVersion,
+  guardRspInitialized,
+  hasArchivedGroupBrief,
+  hasMeaningfulBlockers,
+  hasRspAgentsBlock,
+  historyInspectionComplete,
+  inspectArchiveHistory,
+  inspectArchiveTree,
+  inspectChangeDependencies,
+  inspectChangeGroups,
+  inspectFocusTree,
+  inspectManagedDirectory,
+  inspectManagedFile,
+  inspectManagedFileTree,
+  inspectProjectStatus,
+  inspectRspConfig,
+  inspectUnsupportedRules,
+  inspectWorkTree,
+  isValidSpecName,
+  loadRspConfig,
+  normalizeLogicalPath,
+  parseFrontmatter,
+  parseScenarios,
+  pc,
+  projectDependencyForest,
+  queryArchiveHistory,
+  readArchiveHistoryDetail,
+  recordRuntimeDiagnostic,
+  requireManagedDirectory,
+  resolveArchiveDirectory,
+  resolveDecisionRecordsPath,
+  resolveExecutableChange,
+  resolveFocusMarkerPath,
+  resolveKinds,
+  resolveManagedDirectoryChain,
+  resolveRequiredSections,
+  resolveWorkRef,
+  selectArchiveHistoryRecord,
+  toErrorMessage,
+  upsertRspAgentsBlock,
+  validateDecisionRecordsFilesystemPath,
+  walkMarkdownFiles,
+  writeManagedFile
+} from "./chunk-QLXIDVKK.mjs";
 
 // src/cli.ts
 import { resolve } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { defineCommand, runMain } from "citty";
-
-// src/commands/add-rules.ts
-import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3, join as join3 } from "path";
-
-// src/core/config.ts
-import { existsSync as existsSync2 } from "fs";
-import { readFile as readFile2 } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
 import { fileURLToPath } from "url";
-import pc from "picocolors";
-
-// src/core/helpers.ts
-import { existsSync } from "fs";
-import { readdir, readFile, rmdir } from "fs/promises";
-import { basename, dirname, join, relative, sep } from "path";
-import { parse } from "yaml";
-
-// src/core/output.ts
-function toErrorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-function emitJson(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
-function emitStatusJsonError(error, options) {
-  const payload = {
-    command: "status",
-    ok: false,
-    filters: {
-      focused: options.focused,
-      blocked: options.blocked,
-      stale: null
-    },
-    focused: [],
-    records: [],
-    summary: {
-      total: 0,
-      focused: 0,
-      blocked: 0
-    },
-    archiveTrend: [],
-    runtime: [],
-    error
-  };
-  emitJson(payload);
-}
-function recordRuntimeDiagnostic(runtime, diagnostic, verbose = false) {
-  runtime.push(diagnostic);
-  if (verbose) {
-    console.error(`  ${pc.dim(`[verbose] ${diagnostic.operation} ${diagnostic.path}: ${diagnostic.message}`)}`);
-  }
-}
-
-// src/core/helpers.ts
-var RSP_AGENTS_BEGIN = "<!-- rsp:begin -->";
-var RSP_AGENTS_END = "<!-- rsp:end -->";
-function parseYamlText(text) {
-  const parsed = parse(text);
-  if (parsed === null || parsed === void 0)
-    return {};
-  if (typeof parsed !== "object" || Array.isArray(parsed))
-    throw new Error("YAML document must be a mapping/object");
-  return parsed;
-}
-function parseFrontmatter(content) {
-  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\r?\n/);
-  if (!m)
-    return null;
-  return parseYamlText(m[1]);
-}
-function countCheckboxes(content) {
-  const todo = (content.match(/\[ \]/g) || []).length;
-  const progress = (content.match(/\[\/\]/g) || []).length;
-  const done = (content.match(/\[x\]/g) || []).length;
-  const dropped = (content.match(/\[-\]/g) || []).length;
-  return { todo, progress, done, dropped, total: todo + progress + done + dropped };
-}
-async function walkMarkdownFiles(dir, options = {}) {
-  const all = await walkFiles(dir, options);
-  return all.filter((f) => f.endsWith(".md"));
-}
-async function walkFiles(dir, options = {}) {
-  const files = [];
-  try {
-    const items = await readdir(dir, { withFileTypes: true });
-    for (const item of items) {
-      if (item.name.startsWith("."))
-        continue;
-      const filePath = join(dir, item.name);
-      if (item.isDirectory())
-        files.push(...await walkFiles(filePath, options));
-      else
-        files.push(filePath);
-    }
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      options.onError?.({
-        code: "walk_failed",
-        operation: "readdir",
-        path: dir,
-        message: toErrorMessage(error)
-      });
-    }
-  }
-  return files;
-}
-function changeNameFromPath(changesDir, filePath) {
-  const rel = normalizeLogicalPath(relative(changesDir, filePath));
-  return rel.replace(/\.md$/, "");
-}
-function normalizeLogicalPath(pathValue) {
-  return pathValue.split(sep).join("/").replace(/\\/g, "/");
-}
-function generateChangeContent(name, summary = "", kind) {
-  const proposalSummary = summary || (name === "project-setup" ? "Capture the project model, boundaries, and stable local constraints" : "<one-line summary>");
-  if (name === "project-setup") {
-    return `---
-kind: ops
----
-
-# Change: project-setup
-
-## Proposal
-- Summary: ${proposalSummary}
-- Why:
-  - Establish a durable project model before normal implementation work starts
-- Scope:
-  - Review the repository structure, entrypoints, and primary outputs
-  - Fill .rsp/specs/design.md with durable architecture facts
-  - Add .rsp/rules/project-rules.md when stable local rules or validation steps exist
-- Non-goals:
-  - Do not duplicate durable project facts across this change, specs, and rules
-
-## Spec
-### ADDED
-- Requirement: project bootstrap capture
-  - The repository's purpose, scope, and structure are reflected in .rsp/specs/design.md
-
-### MODIFIED
-- Requirement: stable local operating constraints
-  - Stable validation or workflow constraints are reflected in .rsp/rules/project-rules.md when needed
-
-### Acceptance
-#### Scenario: project model captured
-- GIVEN an initialized RSP project
-- WHEN project setup is completed
-- THEN .rsp/specs/design.md reflects durable project facts
-- AND .rsp/rules/project-rules.md exists only when stable local rules are present
-
-## Design
-- Approach:
-  - Keep bootstrap knowledge in this single change while moving durable facts into specs and rules
-- Affected areas:
-  - .rsp/specs/design.md
-  - .rsp/rules/project-rules.md
-- Constraints:
-  - Keep the setup lightweight and avoid duplicating durable project facts
-
-## Tasks
-- [ ] Review the repository structure, entrypoints, and primary outputs
-- [ ] Review AGENTS.md and confirm the RSP entry points to the right project files
-- [ ] Fill .rsp/specs/design.md with durable architecture facts
-- [ ] Add .rsp/rules/project-rules.md if stable local rules or validation steps exist
-
-## Verify
-- Automated:
-  - [ ] Run rsp doctor
-- Manual:
-  - [ ] Review .rsp/specs/design.md and confirm it matches the repository
-- Durable updates:
-  - [ ] Decide whether this change produced durable knowledge that belongs in \`.rsp/specs/\` or \`.rsp/rules/\`
-  - [ ] If yes, write only stable facts to the smallest correct target file before archive; do not promote task history, debugging notes, or one-off implementation context
-
-## Blockers
-- none
-`;
-  }
-  const frontmatterKind = kind ?? "<choose: feature | fix | refactor | docs | ops | research>";
-  const template = getChangeTemplateByKind(kind);
-  return `---
-kind: "${frontmatterKind}"
----
-
-# Change: ${name}
-
-## Proposal
-- Summary: ${proposalSummary}
-- Why:
-  - ${template.why}
-- Scope:
-  - ${template.scope}
-- Non-goals:
-  - ${template.nonGoals}
-
-## Spec
-${template.specSection}
-
-### Acceptance
-${template.acceptanceSection}
-
-## Design
-- Approach:
-  - ${template.approach}
-- Affected areas:
-  - ${template.affectedArea1}
-  - ${template.affectedArea2}
-- Constraints:
-  - ${template.constraints}
-
-## Tasks
-- [ ] Finalize the proposal, spec, and design details for this change
-- [ ] ${template.task}
-- [ ] Verify the result and update any required durable docs or rules
-
-## Verify
-- Automated:
-  - [ ] ${template.automatedVerify}
-- Manual:
-  - [ ] ${template.manualVerify}
-- Durable updates:
-  - [ ] Decide whether this change produced durable knowledge that belongs in \`.rsp/specs/\` or \`.rsp/rules/\`
-  - [ ] If yes, write only stable facts to the smallest correct target file before archive; do not promote task history, debugging notes, or one-off implementation context
-
-## Blockers
-- none
-`;
-}
-function getChangeTemplateByKind(kind) {
-  switch (kind) {
-    case "feature":
-      return {
-        why: "<what user need or capability gap this addresses>",
-        scope: "<what new behavior or capability will be delivered>",
-        nonGoals: "<what related capabilities are explicitly out of scope>",
-        specSection: "### ADDED\n- Requirement: <new user-facing behavior>\n  - <verifiable requirement for the new capability>",
-        acceptanceSection: "#### Scenario: user exercises the new capability\n- GIVEN <context>\n- WHEN <user action>\n- THEN <expected new behavior>",
-        approach: "<how the new capability will be implemented>",
-        affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
-        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
-        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
-        task: "<implement the new behavior and its acceptance scenario in the affected areas>",
-        automatedVerify: "<exact test, lint, build, or check command for the new behavior>",
-        manualVerify: "<exact end-to-end user scenario to validate the new capability>"
-      };
-    case "fix":
-      return {
-        why: "<what current behavior is wrong or broken>",
-        scope: "<what specific defect is being corrected>",
-        nonGoals: "<what related but separate issues are out of scope>",
-        specSection: "### MODIFIED\n- Requirement: correct behavior\n  - <expected correct behavior after the fix>",
-        acceptanceSection: "#### Scenario: defect is resolved\n- GIVEN <conditions that trigger the defect>\n- WHEN <action that previously failed>\n- THEN <expected correct outcome>\n- AND the original broken outcome no longer occurs",
-        approach: "<root cause analysis and fix strategy>",
-        affectedArea1: "<concrete file path, directory, module, or subsystem containing the defect>",
-        affectedArea2: "<secondary path, dependency, or test file if needed>",
-        constraints: "<regression, backward-compatibility, safety, or scope constraint that must hold>",
-        task: "<identify the root cause and apply the minimal fix>",
-        automatedVerify: "<exact regression test, lint, build, or check command that proves the fix>",
-        manualVerify: "<exact steps to reproduce the original issue and confirm it no longer occurs>"
-      };
-    case "refactor":
-      return {
-        why: "<what maintainability, readability, or structural issue motivates this>",
-        scope: "<what code areas are being restructured>",
-        nonGoals: "<no behavior change is expected or intended>",
-        specSection: "### MODIFIED\n- Requirement: internal structure improvement\n  - <desired structural outcome without observable behavior change>",
-        acceptanceSection: "#### Scenario: behavior is preserved after restructuring\n- GIVEN the existing codebase before the refactor\n- WHEN the refactored code runs against existing tests\n- THEN all existing tests pass unchanged",
-        approach: "<how the code will be restructured (rename, extract, move, etc.)>",
-        affectedArea1: "<concrete file path, directory, module, or subsystem being refactored>",
-        affectedArea2: "<secondary path, dependency, or test file if needed>",
-        constraints: "<observable behavior must remain unchanged; compatibility, performance, and safety constraints must still hold>",
-        task: "<restructure the code while keeping behavior identical>",
-        automatedVerify: "<exact existing test, lint, build, or check command that must continue to pass>",
-        manualVerify: "<exact scenario to spot-check that behavior is unchanged after the refactor>"
-      };
-    case "docs":
-      return {
-        why: "<why the documentation change matters>",
-        scope: "<which docs, readers, or workflows will be updated>",
-        nonGoals: "<what documentation behavior or audience is out of scope>",
-        specSection: "### MODIFIED\n- Requirement: documentation accuracy\n  - <what durable reader-facing behavior or explanation changes>",
-        acceptanceSection: "#### Scenario: reader follows the updated guidance\n- GIVEN the updated documentation\n- WHEN a reader follows the documented workflow\n- THEN the steps are accurate and sufficient",
-        approach: "<how the documentation will be updated and organized>",
-        affectedArea1: "<concrete doc path, directory, module doc, or documentation surface 1>",
-        affectedArea2: "<secondary doc path or reference file if needed>",
-        constraints: "<durable wording, consistency, scope, or audience constraint that must hold>",
-        task: "<update the target documentation and supporting references>",
-        automatedVerify: "<exact markdown, docs, link, lint, build, or check command if applicable>",
-        manualVerify: "<exact reader or operator scenario to confirm the updated guidance is accurate>"
-      };
-    case "research":
-      return {
-        why: "<what question or uncertainty this research resolves>",
-        scope: "<what system area, option set, or hypothesis is being examined>",
-        nonGoals: "<what implementation work is explicitly out of scope>",
-        specSection: "### ADDED\n- Requirement: research outcome recording\n  - <what finding, option, or decision must be captured clearly>",
-        acceptanceSection: "#### Scenario: research question is resolved\n- GIVEN the current uncertainty or open question\n- WHEN the investigation is completed\n- THEN the result is recorded clearly enough to guide follow-up work",
-        approach: "<how the investigation will be performed and what evidence will be gathered>",
-        affectedArea1: "<concrete file path, directory, module, subsystem, or source under investigation>",
-        affectedArea2: "<secondary path, dependency, environment, or evidence source if needed>",
-        constraints: "<time, evidence, safety, or scope constraint for the investigation>",
-        task: "<gather evidence, record the recommendation or finding, and note any follow-up implementation work if needed>",
-        automatedVerify: "<exact command, script, query, or check used to confirm the observed behavior>",
-        manualVerify: "<exact review of the findings to confirm they answer the original question and identify follow-up work if needed>"
-      };
-    case "ops":
-      return {
-        why: "<why this operational or environment change matters>",
-        scope: "<what environment, workflow, or operational path changes>",
-        nonGoals: "<what product or feature behavior will not change>",
-        specSection: "### MODIFIED\n- Requirement: operational behavior\n  - <what reliable operational outcome should change or stay true>",
-        acceptanceSection: "#### Scenario: operational path succeeds\n- GIVEN the target environment or workflow\n- WHEN the operational change is applied\n- THEN the expected operational outcome is reliable",
-        approach: "<how the operational change will be applied safely>",
-        affectedArea1: "<concrete script, config path, workflow, environment path, or operational surface 1>",
-        affectedArea2: "<secondary script, config path, dependency, or environment surface if needed>",
-        constraints: "<rollback, safety, reliability, environment, or scope constraint that must hold>",
-        task: "<apply and verify the operational change>",
-        automatedVerify: "<exact operational validation, lint, build, deploy, or check command>",
-        manualVerify: "<exact operator workflow or environment scenario to confirm the operational result>"
-      };
-    default:
-      return {
-        why: "<why this change matters>",
-        scope: "<what this change will do>",
-        nonGoals: "<what this change will not do>",
-        specSection: "### ADDED\n- Requirement: <new or updated behavior>\n  - <verifiable requirement>",
-        acceptanceSection: "#### Scenario: <name>\n- GIVEN <context>\n- WHEN <action>\n- THEN <expected outcome>",
-        approach: "<how the change will be implemented>",
-        affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
-        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
-        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
-        task: "<implement the core change in the affected areas>",
-        automatedVerify: "<exact test, lint, build, or check command>",
-        manualVerify: "<exact end-to-end scenario to validate>"
-      };
-  }
-}
-function renderRspAgentsBlock() {
-  return `${RSP_AGENTS_BEGIN}
-## RSP Entry
-
-RSP keeps durable rules, specs, and current work under \`.rsp/\`.
-Treat AGENTS.md as navigation only; keep durable rules and design in \`.rsp/\`.
-
-Read in order:
-1. .rsp/rules/rsp-rules.md
-2. .rsp/focus.d/
-3. matching .rsp/changes/*.md for the focused entries
-4. .rsp/specs/design.md
-5. .rsp/specs/INDEX.md
-6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
-
-If \`.rsp/focus.d/\` is empty, ask what to work on or suggest \`npx -y @oevery/rsp create <name>\`.
-If your agent supports Agent Skills, load \`rsp\` for setup, repair, and durable-decision tasks.
-${RSP_AGENTS_END}`;
-}
-function upsertRspAgentsBlock(content) {
-  const block = renderRspAgentsBlock();
-  const managedRe = /<!-- rsp:begin -->[\s\S]*?<!-- rsp:end -->/;
-  if (managedRe.test(content)) {
-    const next2 = content.replace(managedRe, block);
-    return { content: next2, changed: next2 !== content };
-  }
-  const trimmed = content.trimStart();
-  const next = trimmed ? `${block}
-
-${trimmed}` : `${block}
-`;
-  return { content: next, changed: true };
-}
-function hasRspAgentsBlock(content) {
-  return content.includes(RSP_AGENTS_BEGIN) && content.includes(RSP_AGENTS_END);
-}
-var CHANGE_NAME_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
-function isValidChangeName(name) {
-  return CHANGE_NAME_RE.test(name);
-}
-function guardRspInitialized() {
-  const rspRulesPath = join(RSP_DIR, "rules", "rsp-rules.md");
-  const designPath = join(RSP_DIR, "specs", "design.md");
-  if (!existsSync(rspRulesPath) || !existsSync(designPath)) {
-    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
-    console.error(`  ${pc.dim("Run: rsp init")}`);
-    process.exit(1);
-  }
-}
-async function getFocusedChangeNames(options = {}) {
-  const names = /* @__PURE__ */ new Set();
-  const focusDir = join(RSP_DIR, "focus.d");
-  if (!existsSync(focusDir))
-    return names;
-  const entries = await walkFiles(focusDir, options);
-  for (const entryPath of entries)
-    names.add(normalizeLogicalPath(relative(focusDir, entryPath)));
-  return names;
-}
-function getOpenCheckboxes(sectionText) {
-  return sectionText.split("\n").map((line) => line.trim()).filter((line) => /^- \[[ /]\]/.test(line));
-}
-async function cleanupEmptyParentDirs(path, stopDir) {
-  let parent = dirname(path);
-  while (parent !== stopDir) {
-    try {
-      const remaining = await readdir(parent);
-      if (remaining.length === 0)
-        await rmdir(parent);
-      else
-        break;
-    } catch {
-      break;
-    }
-    parent = dirname(parent);
-  }
-}
-async function detectProjectName() {
-  try {
-    if (existsSync("package.json")) {
-      const raw = await readFile("package.json", "utf-8");
-      const pkg = JSON.parse(raw);
-      if (pkg.name && pkg.name !== "")
-        return pkg.name;
-    }
-  } catch {
-  }
-  return basename(process.cwd());
-}
-function generateDesignContent(projectName) {
-  return `# Project Design: ${projectName}
-
-## Purpose
-- <what this project is responsible for>
-- <who or what it serves>
-
-## Stable Facts
-- <durable fact that future agents or developers must know>
-- <key architectural invariant>
-
-## Boundaries
-- In scope:
-  - <major capability or boundary>
-- Out of scope:
-  - <intentional non-goal>
-
-## Structure
-- <important directory or subsystem> \u2014 <responsibility>
-
-## Constraints
-- <cross-cutting technical or operational constraint, when it affects architecture>
-`;
-}
-function generateProjectRulesContent(projectName) {
-  return `---
-name: project-rules
-description: Project-specific rules for ${projectName}
----
-
-# Project Rules
-
-## Scope
-- <stable local rules, workflow constraints, or validation expectations>
-- Do not put temporary debugging steps here.
-
-## Validation
-- <preferred stable validation commands, not temporary troubleshooting steps>
-
-## Conventions
-- <project-specific conventions>
-`;
-}
-function generateRulesContent(name) {
-  const title = toTitleCase(name);
-  return `---
-name: ${name}
-description: Durable rules for ${title}
----
-
-# ${title}
-
-## Scope
-- <what this rules file governs>
-
-## Rules
-- <stable local rule>
-
-## Validation
-- <relevant validation command or check>
-`;
-}
-function generateSpecContent(name) {
-  const title = toTitleCase(name);
-  return `# ${title}
-
-## Purpose
-- <why this project-level spec exists>
-
-## Stable Facts
-- <durable fact that future work must know>
-
-## Boundaries
-- In scope:
-  - <what this spec covers>
-- Out of scope:
-  - <what this spec does not cover>
-
-## Constraints
-- <stable constraint, if any>
-`;
-}
-function toTitleCase(value) {
-  return value.split(/[-/]/g).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
-}
-function extractSection(content, heading) {
-  const lines = content.split("\n");
-  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
-  if (start === -1)
-    return "";
-  const body = [];
-  for (let index = start + 1; index < lines.length; index++) {
-    const line = lines[index];
-    if (line.startsWith("## "))
-      break;
-    body.push(line);
-  }
-  return body.join("\n").trim();
-}
-function hasMeaningfulBlockers(content) {
-  const blockers = extractSection(content, "Blockers");
-  if (!blockers)
-    return false;
-  const lines = blockers.split("\n").map((line) => line.trim()).filter(Boolean);
-  if (lines.length === 0)
-    return false;
-  return lines.some((line) => !/^[-*]\s*(?:none)?$/i.test(line) && !/^none$/i.test(line));
-}
-function detectDeltaSections(content) {
-  const body = extractSection(content, "Spec");
-  return {
-    added: /^###\s*ADDED/im.test(body),
-    modified: /^###\s*MODIFIED/im.test(body),
-    removed: /^###\s*REMOVED/im.test(body)
-  };
-}
-function parseScenarios(content) {
-  const scenarios = [];
-  const regex = /^#{3,4}\s*Scenario:\s*(.+)$/gim;
-  let match;
-  while ((match = regex.exec(content)) !== null) {
-    const heading = match[1].trim();
-    const startPos = match.index + match[0].length;
-    const restContent = content.slice(startPos);
-    const nextSection = restContent.match(/^#{3,4}\s/m);
-    const block = nextSection ? restContent.slice(0, nextSection.index) : restContent;
-    const steps = block.split("\n").map((s) => s.trim()).filter((s) => s.startsWith("-") && /GIVEN|WHEN|THEN|AND|BUT/i.test(s)).map((s) => s.replace(/^[-*]\s*/, ""));
-    if (steps.length > 0)
-      scenarios.push({ heading, steps });
-  }
-  return scenarios;
-}
+import { defineCommand, runMain } from "citty";
 
-// src/core/config.ts
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var PKG_ROOT = join2(__dirname, "..");
-var RSP_DIR = ".rsp";
-var CHANGES_DIR = join2(RSP_DIR, "changes");
-var FOCUS_DIR = join2(RSP_DIR, "focus.d");
-var ARCHIVES_DIR = join2(RSP_DIR, "archives");
-var LOCK_PATH = join2(RSP_DIR, ".lock");
-var CONFIG_PATH = join2(RSP_DIR, "config.yaml");
-var VALID_KINDS = ["feature", "fix", "refactor", "docs", "ops", "research"];
-var DEFAULT_REQUIRED_SECTIONS = ["Proposal", "Spec", "Design", "Tasks", "Verify", "Blockers"];
-var _configCache = null;
-async function loadRspConfig() {
-  if (_configCache)
-    return _configCache;
-  if (!existsSync2(CONFIG_PATH)) {
-    _configCache = {};
-    return _configCache;
-  }
-  const raw = await readFile2(CONFIG_PATH, "utf-8");
-  const parsed = parseYamlText(raw);
-  _configCache = {
-    kinds: Array.isArray(parsed.kinds) ? parsed.kinds.map(String) : void 0
-  };
-  return _configCache;
-}
-function resolveKinds(config) {
-  return config.kinds && config.kinds.length > 0 ? config.kinds : [...VALID_KINDS];
-}
-function resolveRequiredSections(_config) {
-  return [...DEFAULT_REQUIRED_SECTIONS];
-}
-async function getVersion() {
-  const { version } = JSON.parse(await readFile2(join2(PKG_ROOT, "package.json"), "utf-8"));
-  return version;
-}
+// src/commands/add-spec.ts
+import { mkdir as mkdir2, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
 
 // src/core/lock.ts
-import { mkdir, readFile as readFile3, unlink, writeFile } from "fs/promises";
+import { mkdir, readFile, unlink, writeFile } from "fs/promises";
 async function withRspLock(operation, fn) {
+  requireManagedDirectory(RSP_DIR, "RSP root", { allowMissing: true });
   await mkdir(RSP_DIR, { recursive: true });
   try {
     await writeFile(LOCK_PATH, `${process.pid}
@@ -626,7 +114,7 @@ ${(/* @__PURE__ */ new Date()).toISOString()}`, { flag: "wx" });
 }
 async function handleStaleLock(operation) {
   try {
-    const content = await readFile3(LOCK_PATH, "utf-8");
+    const content = await readFile(LOCK_PATH, "utf-8");
     const lines = content.trim().split("\n");
     const pid = Number(lines[0]);
     if (pid && Number.isFinite(pid)) {
@@ -661,51 +149,41 @@ ${(/* @__PURE__ */ new Date()).toISOString()}`, { flag: "wx" });
   }
 }
 
-// src/commands/add-rules.ts
-async function addRules(name, projectName = "project") {
-  if (!name || !isValidChangeName(name)) {
-    console.error(`  ${pc.red("Error:")} rule name must be kebab-case with optional subdirectory`);
-    process.exit(1);
-  }
-  guardRspInitialized();
-  const path = join3(RSP_DIR, "rules", `${name}.md`);
-  if (existsSync3(path)) {
-    console.error(`  ${pc.red("Error:")} rule file already exists: .rsp/rules/${name}.md`);
-    process.exit(1);
-  }
-  return withRspLock("add-rules", async () => {
-    await mkdir2(dirname3(path), { recursive: true });
-    const resolvedProjectName = projectName === "project" ? await detectProjectName() : projectName;
-    const content = name === "project-rules" ? generateProjectRulesContent(resolvedProjectName) : generateRulesContent(name);
-    await writeFile2(path, content);
-    console.log(`  ${pc.green("Created:")} .rsp/rules/${name}.md
-`);
-  });
-}
-
-// src/commands/add-spec.ts
-import { existsSync as existsSync5 } from "fs";
-import { mkdir as mkdir3, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname4, join as join5 } from "path";
-
 // src/commands/specs-index.ts
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import { basename as basename2, join as join4, relative as relative2 } from "path";
-async function buildSpecsIndex({ acquireLock = true } = {}) {
+import { existsSync } from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { basename, isAbsolute, join, relative, sep } from "path";
+async function buildSpecsIndex({ acquireLock = true, quiet = false } = {}) {
   if (acquireLock)
-    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false }));
-  const specsDir = join4(RSP_DIR, "specs");
-  if (!existsSync4(specsDir)) {
-    console.log(`  ${pc.dim("No specs directory.")}
+    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false, quiet }));
+  const specsDir = join(RSP_DIR, "specs");
+  const configInspection = await inspectRspConfig();
+  if (configInspection.issues.length > 0)
+    throw new Error(configInspection.issues.join("; "));
+  const decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+  const inspection = await inspectManagedFileTree(specsDir, "Specs", { allowMissing: true });
+  if (inspection.issues.length > 0)
+    throw inspection.issues[0];
+  if (!inspection.rootExists) {
+    if (!quiet)
+      console.log(`  ${pc.dim("No specs directory.")}
 `);
-    return;
+    return false;
   }
-  const specFiles = (await walkMarkdownFiles(specsDir)).filter((fp) => {
-    const name = basename2(fp);
-    return name !== "INDEX.md" && name !== "design.md";
+  const specFiles = inspection.files.filter((fp) => fp.endsWith(".md")).filter((fp) => {
+    const name = basename(fp);
+    return name !== "INDEX.md" && name !== "design.md" && !isInside(DEFAULT_DECISION_RECORDS_PATH, fp) && !isInside(decisionRecordsPath, fp);
   }).sort();
   const lines = [];
+  lines.push("---");
+  lines.push("title: Specs Index");
+  lines.push("summary: Additional project-level specs beyond design.md.");
+  lines.push("kind: generated-index");
+  lines.push("index_type: specs");
+  lines.push("source_dir: .rsp/specs");
+  lines.push(`entry_count: ${specFiles.length}`);
+  lines.push("---");
+  lines.push("");
   lines.push("# Specs Index");
   lines.push("");
   lines.push("_Additional project-level specs beyond `design.md`._");
@@ -716,8 +194,8 @@ async function buildSpecsIndex({ acquireLock = true } = {}) {
     lines.push("| File | Title | Summary |");
     lines.push("|------|-------|---------|");
     for (const fp of specFiles) {
-      const rel = normalizeLogicalPath(relative2(specsDir, fp));
-      const content = await readFile4(fp, "utf-8");
+      const rel = normalizeLogicalPath(relative(specsDir, fp));
+      const content = await readFile2(fp, "utf-8");
       const fm = parseFrontmatter(content);
       const fmTitle = fm && typeof fm.title === "string" ? fm.title : "";
       const title = fmTitle || extractTitle(content) || rel.replace(/\.md$/, "");
@@ -725,11 +203,20 @@ async function buildSpecsIndex({ acquireLock = true } = {}) {
       lines.push(`| ${escapeCell(rel)} | ${escapeCell(title)} | ${escapeCell(summary || "\u2014")} |`);
     }
   }
-  lines.push("");
-  lines.push("_Auto-generated by `rsp update`._");
-  await writeFile3(join4(specsDir, "INDEX.md"), lines.join("\n"));
-  console.log(`  ${pc.green("INDEX.md updated:")} ${specFiles.length} spec file(s).
+  const indexPath = join(specsDir, "INDEX.md");
+  const nextContent = lines.join("\n");
+  const existingContent = existsSync(indexPath) ? await readFile2(indexPath, "utf-8") : null;
+  const changed = existingContent !== nextContent;
+  if (changed)
+    await writeManagedFile(indexPath, nextContent, "Specs index");
+  if (!quiet)
+    console.log(`  ${pc.green("INDEX.md updated:")} ${specFiles.length} spec file(s).
 `);
+  return changed;
+}
+function isInside(directory, filePath) {
+  const rel = relative(directory, filePath);
+  return rel === "" || !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
 }
 function extractTitle(content) {
   for (const rawLine of content.split("\n")) {
@@ -766,249 +253,384 @@ function escapeCell(value) {
 
 // src/commands/add-spec.ts
 async function addSpec(name, projectName = "project") {
-  if (!name || !isValidChangeName(name)) {
+  if (!name || !isValidSpecName(name)) {
     console.error(`  ${pc.red("Error:")} spec name must be kebab-case with optional subdirectory`);
     process.exit(1);
   }
+  if (name.startsWith("decisions/")) {
+    console.error(`  ${pc.red("Error:")} .rsp/specs/decisions/ is reserved for Decision Records`);
+    process.exit(1);
+  }
   guardRspInitialized();
-  const path = join5(RSP_DIR, "specs", `${name}.md`);
-  if (existsSync5(path)) {
-    console.error(`  ${pc.red("Error:")} spec file already exists: .rsp/specs/${name}.md`);
+  try {
+    const configInspection = await inspectRspConfig();
+    if (configInspection.issues.length > 0) {
+      console.error(`  ${pc.red("Error:")} ${configInspection.issues.join("; ")}`);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`  ${pc.red("Error:")} .rsp/config.yaml could not be parsed: ${toErrorMessage(error)}`);
     process.exit(1);
   }
   return withRspLock("add-spec", async () => {
-    await mkdir3(dirname4(path), { recursive: true });
+    const specsDir = join2(RSP_DIR, "specs");
+    const segments = name.split("/");
+    const parent = resolveManagedDirectoryChain(specsDir, segments.slice(0, -1), "spec path");
+    const path = join2(parent, `${segments.at(-1)}.md`);
+    const inspection = await inspectManagedFileTree(specsDir, "Specs");
+    if (inspection.issues.length > 0)
+      throw inspection.issues[0];
+    await mkdir2(parent, { recursive: true });
     const resolvedProjectName = projectName === "project" ? await detectProjectName() : projectName;
     const content = name === "design" ? generateDesignContent(resolvedProjectName) : generateSpecContent(name);
-    await writeFile4(path, content);
-    await buildSpecsIndex({ acquireLock: false });
+    let created = false;
+    try {
+      await writeFile2(path, content, { flag: "wx" });
+      created = true;
+      await buildSpecsIndex({ acquireLock: false });
+    } catch (error) {
+      if (created) {
+        try {
+          await unlink2(path);
+          await cleanupEmptyParentDirs(path, specsDir);
+        } catch {
+        }
+      }
+      if (error.code === "EEXIST")
+        throw new Error(`spec file already exists: .rsp/specs/${name}.md`);
+      throw error;
+    }
     console.log(`  ${pc.green("Created:")} .rsp/specs/${name}.md
 `);
   });
 }
 
 // src/commands/archive.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir4, readFile as readFile6, rename, unlink as unlink2 } from "fs/promises";
-import { basename as basename4, dirname as dirname6, join as join7 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir3, readFile as readFile4, rename, unlink as unlink3 } from "fs/promises";
+import { basename as basename3, join as join4 } from "path";
 
 // src/commands/archive-index.ts
-import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
-import { basename as basename3, dirname as dirname5, join as join6, relative as relative3 } from "path";
-async function buildArchiveIndex({ acquireLock = true } = {}) {
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile3 } from "fs/promises";
+import { basename as basename2, dirname, join as join3, relative as relative2 } from "path";
+async function buildArchiveIndex({ acquireLock = true, quiet = false } = {}) {
   if (acquireLock)
-    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false }));
-  if (!existsSync6(ARCHIVES_DIR)) {
-    console.log(`  ${pc.dim("No archives directory.")}
+    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false, quiet }));
+  const inspection = await inspectArchiveTree();
+  if (inspection.diagnostics.length > 0) {
+    const diagnostic = inspection.diagnostics[0];
+    throw new WorkRefError(diagnostic.code, diagnostic.message, diagnostic.input);
+  }
+  if (!inspection.rootExists) {
+    if (!quiet)
+      console.log(`  ${pc.dim("No archives directory.")}
 `);
-    return;
+    return false;
   }
-  const archiveFiles = (await walkMarkdownFiles(ARCHIVES_DIR)).filter((fp) => basename3(fp) !== "INDEX.md").sort();
+  const archiveFiles = inspection.files;
   const lines = [];
-  lines.push("# Archive Index");
+  lines.push("---");
+  lines.push("title: Archive Index");
+  lines.push("summary: Completed RSP changes.");
+  lines.push("kind: generated-index");
+  lines.push("index_type: archives");
+  lines.push("source_dir: .rsp/archives");
+  lines.push(`entry_count: ${archiveFiles.length}`);
+  lines.push("---");
   lines.push("");
-  lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
+  lines.push("# Archive Index");
   lines.push("");
   if (archiveFiles.length === 0) {
     lines.push("_No archived changes yet._");
   } else {
-    lines.push("| Date | Change | Summary |");
-    lines.push("|------|--------|---------|");
+    lines.push("| Date | Change | Kind | Summary |");
+    lines.push("|------|--------|------|---------|");
   }
   for (const fp of archiveFiles) {
-    const base = basename3(fp);
-    const archiveRel = normalizeLogicalPath(relative3(ARCHIVES_DIR, fp));
-    const archiveDirPart = dirname5(archiveRel);
+    const base = basename2(fp);
+    const archiveRel = normalizeLogicalPath(relative2(ARCHIVES_DIR, fp));
+    const archiveDirPart = dirname(archiveRel);
     const dateMatch = base.match(/^(\d{4}-\d{2}-\d{2})_(.+)\.md$/);
     const date = dateMatch ? dateMatch[1] : "\u2014";
     const baseName = dateMatch ? dateMatch[2] : base.replace(/\.md$/, "");
     const changeName = archiveDirPart !== "." ? `${archiveDirPart}/${baseName}` : baseName;
     let summary = "";
+    let kind = "";
     try {
-      const content = await readFile5(fp, "utf-8");
+      const content = await readFile3(fp, "utf-8");
+      const fm = parseFrontmatter(content);
+      if (typeof fm?.kind === "string")
+        kind = fm.kind;
+      if (typeof fm?.summary === "string")
+        summary = fm.summary.trim();
       const proposal = extractSection(content, "Proposal");
-      const summaryLine = proposal.split("\n").map((line) => line.trim()).find((line) => line.startsWith("- Summary:"));
-      if (summaryLine)
-        summary = summaryLine.slice("- Summary:".length).trim();
+      const outcomeLine = proposal.split("\n").map((line) => line.trim()).find((line) => line.startsWith("- Outcome:"));
+      const legacySummaryLine = proposal.split("\n").map((line) => line.trim()).find((line) => line.startsWith("- Summary:"));
+      if (!summary && outcomeLine)
+        summary = outcomeLine.slice("- Outcome:".length).trim();
+      if (!summary && legacySummaryLine)
+        summary = legacySummaryLine.slice("- Summary:".length).trim();
     } catch {
     }
-    const summaryCell = summary ? summary.replace(/\|/g, "\\|") : "\u2014";
-    lines.push(`| ${date} | ${changeName} | ${summaryCell} |`);
-  }
-  lines.push("");
-  lines.push("_Auto-generated by `rsp update`._");
-  const indexPath = join6(ARCHIVES_DIR, "INDEX.md");
-  await writeFile5(indexPath, lines.join("\n"));
-  console.log(`  ${pc.green("INDEX.md updated:")} ${archiveFiles.length} archived change(s).
+    lines.push(`| ${date} | ${escapeCell2(changeName)} | ${escapeCell2(kind || "\u2014")} | ${escapeCell2(summary || "\u2014")} |`);
+  }
+  const indexPath = join3(ARCHIVES_DIR, "INDEX.md");
+  const nextContent = lines.join("\n");
+  const existingContent = existsSync2(indexPath) ? await readFile3(indexPath, "utf-8") : null;
+  const changed = existingContent !== nextContent;
+  if (changed)
+    await writeManagedFile(indexPath, nextContent, "archive index");
+  if (!quiet)
+    console.log(`  ${pc.green("INDEX.md updated:")} ${archiveFiles.length} archived change(s).
 `);
+  return changed;
+}
+function escapeCell2(value) {
+  return value.replace(/\|/g, "\\|");
 }
 
 // src/commands/archive.ts
-async function archiveChange(name) {
+async function archiveChange(name, options = {}) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp archive <name>`);
     process.exit(1);
   }
-  if (!isValidChangeName(name)) {
-    console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
-    process.exit(1);
-  }
   guardRspInitialized();
-  const srcPath = join7(CHANGES_DIR, `${name}.md`);
-  if (!existsSync7(srcPath)) {
-    console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
-    process.exit(1);
+  if (options.dryRun) {
+    const workRef = await resolveArchiveWorkRefOrExit(name);
+    const content = await readFile4(workRef.path, "utf-8");
+    const dependencyInspection = await inspectChangeDependencies();
+    const checklist = collectArchiveChecklist(content, {
+      activeBlockers: dependencyInspection.activeBlockers.get(name)
+    });
+    console.log();
+    console.log(`  ${pc.bold("Archive dry-run for")} ${pc.cyan(name)}`);
+    console.log();
+    if (checklist.length === 0) {
+      console.log(`  ${pc.green("\u2713")} Ready to archive. No deterministic warnings found.
+`);
+    } else {
+      for (const line of checklist)
+        console.log(`  ${pc.yellow("\u26A0")} ${line}`);
+      console.log();
+      console.log(`  ${pc.dim("Review the warnings above before treating this work as fully closed.")}
+`);
+    }
+    return;
   }
-  return withRspLock("archive-change", async () => {
-    const content = await readFile6(srcPath, "utf-8");
-    const checklist = collectArchiveChecklist(content);
-    for (const line of checklist)
-      console.log(`  ${pc.yellow("\u26A0")} ${line}`);
-    if (checklist.length > 0)
-      console.log(`  ${pc.dim("Archive will continue. Review the warnings above before treating this work as fully closed.")}
+  try {
+    return await withRspLock("archive-change", async () => {
+      const workRef = await resolveExecutableChange(name, { mustExist: true });
+      const srcPath = workRef.path;
+      const archiveSubdir = resolveArchiveDirectory(workRef);
+      const focusEntry = resolveFocusMarkerPath(workRef);
+      const content = await readFile4(srcPath, "utf-8");
+      const dependencyInspection = await inspectChangeDependencies();
+      const checklist = collectArchiveChecklist(content, {
+        activeBlockers: dependencyInspection.activeBlockers.get(name)
+      });
+      for (const line of checklist)
+        console.log(`  ${pc.yellow("\u26A0")} ${line}`);
+      if (checklist.length > 0)
+        console.log(`  ${pc.dim("Archive will continue. Review the warnings above before treating this work as fully closed.")}
 `);
-    const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    const dir = dirname6(name);
-    const base = basename4(name);
-    const archiveSubdir = dir !== "." ? join7(ARCHIVES_DIR, dir) : ARCHIVES_DIR;
-    await mkdir4(archiveSubdir, { recursive: true });
-    const archiveName = resolveArchiveName(archiveSubdir, date, base);
-    await rename(srcPath, join7(archiveSubdir, archiveName));
-    const postArchiveWarnings = [];
-    let focusCleared = false;
-    const focusEntry = join7(FOCUS_DIR, name);
-    if (existsSync7(focusEntry)) {
+      const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const base = basename3(workRef.name);
+      await mkdir3(archiveSubdir, { recursive: true });
+      const archiveName = resolveArchiveName(archiveSubdir, date, base);
+      await rename(srcPath, join4(archiveSubdir, archiveName));
+      const postArchiveWarnings = [];
+      let focusCleared = false;
+      if (existsSync3(focusEntry)) {
+        try {
+          await unlink3(focusEntry);
+          await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
+          focusCleared = true;
+        } catch (error) {
+          postArchiveWarnings.push(`focus marker cleanup failed: ${toErrorMessage(error)}`);
+        }
+      }
       try {
-        await unlink2(focusEntry);
-        await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
-        focusCleared = true;
+        await cleanupEmptyParentDirs(srcPath, CHANGES_DIR);
       } catch (error) {
-        postArchiveWarnings.push(`focus marker cleanup failed: ${toErrorMessage(error)}`);
+        postArchiveWarnings.push(`changes directory cleanup failed: ${toErrorMessage(error)}`);
       }
-    }
-    try {
-      await cleanupEmptyParentDirs(srcPath, CHANGES_DIR);
-    } catch (error) {
-      postArchiveWarnings.push(`changes directory cleanup failed: ${toErrorMessage(error)}`);
-    }
-    const clearedMsg = focusCleared ? `  ${pc.dim("focus marker cleared")}
+      const clearedMsg = focusCleared ? `  ${pc.dim("focus marker cleared")}
 ` : "";
-    console.log(`  ${pc.green("Archived:")} ${archiveName}
+      console.log(`  ${pc.green("Archived:")} ${archiveName}
 ${clearedMsg}`);
-    try {
-      await buildArchiveIndex({ acquireLock: false });
-    } catch (error) {
-      postArchiveWarnings.push(`archive index rebuild failed: ${toErrorMessage(error)}`);
-    }
-    for (const warning of postArchiveWarnings)
-      console.log(`  ${pc.yellow("\u26A0")} ${warning}`);
-    if (postArchiveWarnings.length > 0)
-      console.log(`  ${pc.dim("Archive completed, but follow-up cleanup was only partially successful.")}
+      try {
+        await buildArchiveIndex({ acquireLock: false });
+      } catch (error) {
+        postArchiveWarnings.push(`archive index rebuild failed: ${toErrorMessage(error)}`);
+      }
+      for (const warning of postArchiveWarnings)
+        console.log(`  ${pc.yellow("\u26A0")} ${warning}`);
+      if (postArchiveWarnings.length > 0)
+        console.log(`  ${pc.dim("Archive completed, but follow-up cleanup was only partially successful.")}
 `);
-    if (existsSync7(".git")) {
-      const archiveRelPath = dir !== "." ? join7(dir, archiveName) : archiveName;
-      console.log(`  ${pc.cyan("Git workflow:")}
+      if (existsSync3(".git")) {
+        console.log(`  ${pc.cyan("Git delivery:")}
 `);
-      console.log(`    git add .rsp/archives/${archiveRelPath}`);
-      console.log(`    git commit -m "feat: archive ${name}"`);
-      console.log();
+        console.log(`    git status --short`);
+        console.log(`    Inspect the complete archive transition; stage and commit only with separate Git authority.`);
+        console.log();
+      }
+    });
+  } catch (error) {
+    if (error instanceof WorkRefError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      process.exit(1);
     }
-  });
+    throw error;
+  }
+}
+async function resolveArchiveWorkRefOrExit(name) {
+  try {
+    const workRef = await resolveExecutableChange(name, { mustExist: true });
+    resolveArchiveDirectory(workRef);
+    resolveFocusMarkerPath(workRef);
+    return workRef;
+  } catch (error) {
+    if (error instanceof WorkRefError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
 }
 function resolveArchiveName(archiveSubdir, date, base) {
   const initialName = `${date}_${base}.md`;
-  if (!existsSync7(join7(archiveSubdir, initialName)))
+  if (!existsSync3(join4(archiveSubdir, initialName)))
     return initialName;
   const MAX_SUFFIX = 9999;
   for (let index = 2; index <= MAX_SUFFIX; index++) {
     const candidate = `${date}_${base}-${index}.md`;
-    if (!existsSync7(join7(archiveSubdir, candidate)))
+    if (!existsSync3(join4(archiveSubdir, candidate)))
       return candidate;
   }
-  console.error(`  ${pc.red("Error:")} archive name collision exceeded ${MAX_SUFFIX} attempts for ${base}`);
-  process.exit(1);
-}
-function collectArchiveChecklist(content) {
-  const warnings = [];
-  const tasksSection = extractSection(content, "Tasks");
-  const verifySection = extractSection(content, "Verify");
-  const taskTodos = getOpenCheckboxes(tasksSection);
-  if (taskTodos.length > 0)
-    warnings.push(`${taskTodos.length} task item(s) still incomplete`);
-  const verifyTodos = getOpenCheckboxes(verifySection);
-  if (verifyTodos.length > 0)
-    warnings.push(`${verifyTodos.length} Verify checklist item(s) are still incomplete`);
-  if (hasMeaningfulBlockers(content))
-    warnings.push("active blockers are present in the change file");
-  const scenarios = parseScenarios(content);
-  if (scenarios.length === 0)
-    warnings.push("no Scenario blocks found (some changes do not need them)");
-  return warnings;
+  throw new WorkRefError(
+    "archive_name_exhausted",
+    `archive name collision exceeded ${MAX_SUFFIX} attempts for ${base}`,
+    base
+  );
 }
 
 // src/commands/check.ts
-import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile7 } from "fs/promises";
-import { join as join8, relative as relative4 } from "path";
+import { readFile as readFile5 } from "fs/promises";
 async function runCheck(options = {}) {
-  const config = await loadRspConfig();
+  const diagnostics = [];
+  const runtime = [];
+  let config;
+  try {
+    config = await loadRspConfig();
+  } catch (error) {
+    const result2 = {
+      command: "check",
+      ok: false,
+      focused: Boolean(options.focused),
+      diagnostics: [{ severity: "error", code: "invalid_config", path: ".rsp/config.yaml", message: toErrorMessage(error) }],
+      runtime,
+      summary: { changeFiles: 0, errors: 1, warnings: 0 }
+    };
+    if (options.json)
+      emitJson(result2, options);
+    else
+      console.error(`  ${pc.red("Error:")} ${toErrorMessage(error)}`);
+    return result2;
+  }
   const validKinds = resolveKinds(config);
   const requiredSections = resolveRequiredSections(config);
   const choosePlaceholderRe = /^<choose:/i;
-  const diagnostics = [];
-  const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
   const addDiagnostic = (diagnostic) => diagnostics.push(diagnostic);
-  if (existsSync8(FOCUS_DIR)) {
-    const entries = await walkFiles(FOCUS_DIR, { onError: reportRuntime });
-    for (const entryPath of entries) {
-      const entryContent = normalizeLogicalPath(relative4(FOCUS_DIR, entryPath));
-      let markerContent = "";
-      try {
-        markerContent = (await readFile7(entryPath, "utf-8")).trim();
-      } catch (error) {
-        addDiagnostic({
-          severity: "error",
-          code: "focus_marker_read_failed",
-          path: `focus.d/${entryContent}`,
-          change: entryContent,
-          message: "unable to read focus marker file",
-          hint: toErrorMessage(error)
-        });
-        reportRuntime({
-          code: "focus_marker_read_failed",
-          operation: "readFile",
-          path: entryPath,
-          message: toErrorMessage(error)
-        });
-        continue;
-      }
-      if (markerContent) {
-        addDiagnostic({
-          severity: "warning",
-          code: "focus_marker_not_empty",
-          path: `focus.d/${entryContent}`,
-          message: "should be an empty marker file; path is the source of truth"
-        });
-      }
-      const fp = join8(CHANGES_DIR, `${entryContent}.md`);
-      if (!existsSync8(fp)) {
-        addDiagnostic({
-          severity: "error",
-          code: "focused_change_missing",
-          path: `focus.d/${entryContent}`,
-          change: entryContent,
-          message: `focuses "${entryContent}" but changes/${entryContent}.md not found`
-        });
-      }
+  const focusTree = await inspectFocusTree();
+  for (const diagnostic of focusTree.diagnostics) {
+    addDiagnostic({
+      severity: "error",
+      code: diagnostic.code,
+      change: diagnostic.input,
+      path: diagnostic.path,
+      message: diagnostic.message
+    });
+  }
+  const focusedSet = options.focused ? new Set(focusTree.markers.map((marker) => marker.name)) : /* @__PURE__ */ new Set();
+  for (const marker of focusTree.markers) {
+    const entryPath = marker.path;
+    const entryContent = marker.name;
+    let markerContent = "";
+    try {
+      markerContent = (await readFile5(entryPath, "utf-8")).trim();
+    } catch (error) {
+      addDiagnostic({
+        severity: "error",
+        code: "focus_marker_read_failed",
+        path: `focus.d/${entryContent}`,
+        change: entryContent,
+        message: "unable to read focus marker file",
+        hint: toErrorMessage(error)
+      });
+      reportRuntime({
+        code: "focus_marker_read_failed",
+        operation: "readFile",
+        path: entryPath,
+        message: toErrorMessage(error)
+      });
+      continue;
+    }
+    if (markerContent) {
+      addDiagnostic({
+        severity: "warning",
+        code: "focus_marker_not_empty",
+        path: `focus.d/${entryContent}`,
+        message: "should be an empty marker file; path is the source of truth"
+      });
+    }
+    try {
+      resolveWorkRef(entryContent, { executable: true, mustExist: true });
+    } catch (error) {
+      if (!(error instanceof WorkRefError))
+        throw error;
+      addDiagnostic({
+        severity: "error",
+        code: error.code === "work_ref_not_found" ? "focused_change_missing" : error.code,
+        path: `focus.d/${entryContent}`,
+        change: entryContent,
+        message: error.code === "work_ref_not_found" ? `focuses "${entryContent}" but changes/${entryContent}.md not found` : error.message
+      });
+    }
+  }
+  const workTree = await inspectWorkTree();
+  for (const diagnostic of workTree.diagnostics) {
+    const inspectionIncomplete = diagnostic.code === "invalid_work_root" || diagnostic.code === "work_tree_read_failed";
+    if (inspectionIncomplete || !options.focused || focusedSet.has(diagnostic.input)) {
+      addDiagnostic({
+        severity: "error",
+        code: diagnostic.code,
+        change: diagnostic.input,
+        path: diagnostic.path,
+        message: diagnostic.message
+      });
     }
   }
-  const changeFiles = existsSync8(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
-  if (changeFiles.length === 0) {
+  const changeRefs = options.focused ? workTree.changes.filter((ref) => focusedSet.has(ref.name)) : workTree.changes;
+  const groupInspection = await inspectChangeGroups({ workTree, focusTree });
+  const focusedGroups = new Set(changeRefs.flatMap((ref) => ref.group ? [ref.group] : []));
+  for (const diagnostic of groupInspection.diagnostics) {
+    if (!options.focused || !diagnostic.change || focusedGroups.has(diagnostic.change))
+      addDiagnostic(diagnostic);
+  }
+  const dependencyInspection = await inspectChangeDependencies({ workTree });
+  for (const diagnostic of dependencyInspection.diagnostics) {
+    if (!options.focused || !diagnostic.change || focusedSet.has(diagnostic.change))
+      addDiagnostic(diagnostic);
+  }
+  if (changeRefs.length === 0) {
     const result2 = {
       command: "check",
       ok: diagnostics.every((d) => d.severity !== "error"),
+      focused: Boolean(options.focused),
       diagnostics,
       runtime,
       summary: {
@@ -1018,11 +640,13 @@ async function runCheck(options = {}) {
       }
     };
     if (options.json) {
-      emitJson(result2);
+      emitJson(result2, options);
       return result2;
     }
     console.log();
     console.log(`  ${pc.bold("RSP check")}`);
+    if (options.focused)
+      console.log(`  ${pc.dim("(focused only)")}`);
     console.log();
     if (diagnostics.length === 0) {
       console.log(`  ${pc.dim("No change files to check.")}
@@ -1044,11 +668,11 @@ async function runCheck(options = {}) {
 `);
     return result2;
   }
-  for (const fp of changeFiles) {
-    const name = changeNameFromPath(CHANGES_DIR, fp);
+  for (const ref of changeRefs) {
+    const { name, path: fp } = ref;
     let content;
     try {
-      content = await readFile7(fp, "utf-8");
+      content = await readFile5(fp, "utf-8");
     } catch (error) {
       addDiagnostic({
         severity: "error",
@@ -1159,6 +783,30 @@ async function runCheck(options = {}) {
         message: `delta markers found: ${parts.join(", ")}`
       });
     }
+    const placeholderLines = findUnfinishedTemplateLines(content);
+    if (placeholderLines.length > 0) {
+      addDiagnostic({
+        severity: "warning",
+        code: "unfinished_template_placeholders",
+        change: name,
+        path: fp,
+        message: "unfinished template placeholders found",
+        details: placeholderLines,
+        hint: "Replace angle-bracket template text with concrete change details before archiving."
+      });
+    }
+    const clarificationLines = findUnresolvedClarificationLines(content);
+    if (clarificationLines.length > 0) {
+      addDiagnostic({
+        severity: "warning",
+        code: "unresolved_clarifications",
+        change: name,
+        path: fp,
+        message: "unresolved clarification markers found",
+        details: clarificationLines,
+        hint: "Resolve or remove clarification markers once the open question is answered."
+      });
+    }
     const scenarios = parseScenarios(content);
     if (scenarios.length > 0) {
       const scenarioIssues = [];
@@ -1191,20 +839,23 @@ async function runCheck(options = {}) {
   const result = {
     command: "check",
     ok: diagnostics.every((d) => d.severity !== "error"),
+    focused: Boolean(options.focused),
     diagnostics,
     runtime,
     summary: {
-      changeFiles: changeFiles.length,
+      changeFiles: changeRefs.length,
       errors: diagnostics.filter((d) => d.severity === "error").length,
       warnings: diagnostics.filter((d) => d.severity === "warning").length
     }
   };
   if (options.json) {
-    emitJson(result);
+    emitJson(result, options);
     return result;
   }
   console.log();
   console.log(`  ${pc.bold("RSP check")}`);
+  if (options.focused)
+    console.log(`  ${pc.dim("(focused only)")}`);
   console.log();
   for (const diagnostic of diagnostics) {
     const icon = diagnostic.severity === "error" ? pc.red("\u2717") : diagnostic.severity === "warning" ? pc.yellow("\u26A0") : pc.dim("\u2139");
@@ -1218,77 +869,288 @@ async function runCheck(options = {}) {
   }
   console.log();
   if (result.summary.errors === 0 && result.summary.warnings === 0)
-    console.log(`  ${pc.green("\u2713")} All ${changeFiles.length} change file(s) valid.
+    console.log(`  ${pc.green("\u2713")} All ${changeRefs.length} change file(s) valid.
 `);
   else
-    console.log(`  ${pc.red(String(result.summary.errors))} error(s), ${pc.yellow(String(result.summary.warnings))} warning(s) in ${changeFiles.length} change file(s).
+    console.log(`  ${pc.red(String(result.summary.errors))} error(s), ${pc.yellow(String(result.summary.warnings))} warning(s) in ${changeRefs.length} change file(s).
 `);
   return result;
 }
+function findUnfinishedTemplateLines(content) {
+  const placeholderRe = /<[^>\n]*(?:choose:|one-line|what |why |which |who |how |new |updated |expected |actual |specific |concrete |exact |verifiable |user |capability |behavior |context |action |path|directory|module|subsystem|command|scenario|constraint|requirement|question|uncertainty|implementation)[^>\n]*>/i;
+  return collectMatchingLines(content, (line) => {
+    const trimmed = stripInlineCodeSpans(line).trim();
+    return trimmed.startsWith("<!--") === false && placeholderRe.test(trimmed);
+  });
+}
+function findUnresolvedClarificationLines(content) {
+  return collectMatchingLines(content, (line) => /\[(?:NEEDS|TODO|TBD)\s+CLARIFICATION(?::[^\]]*)?\]/i.test(stripInlineCodeSpans(line)));
+}
+function stripInlineCodeSpans(line) {
+  return line.replace(/`[^`]*`/g, "");
+}
+function collectMatchingLines(content, predicate) {
+  const matches = [];
+  const lines = content.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (predicate(line))
+      matches.push(`line ${index + 1}: ${line.trim()}`);
+  }
+  return matches.slice(0, 10);
+}
 
 // src/commands/create.ts
-import { existsSync as existsSync9 } from "fs";
-import { mkdir as mkdir5, writeFile as writeFile6 } from "fs/promises";
-import { dirname as dirname7, join as join9 } from "path";
-async function createChange(name, summary = "", kind) {
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir4, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+async function createChange(name, summary = "", kind, options = {}) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp create <name> [summary]`);
     process.exit(1);
   }
-  if (!isValidChangeName(name)) {
-    console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
+  guardRspInitialized();
+  try {
+    return await withRspLock("create-change", async () => {
+      const workRef = await resolveExecutableChange(name);
+      const changePath = workRef.path;
+      const existed = existsSync4(changePath);
+      if (!existed) {
+        const focusEntry = resolveFocusMarkerPath(workRef);
+        const content = generateChangeContent(name, summary, kind, { lite: Boolean(options.lite) });
+        await mkdir4(dirname2(changePath), { recursive: true });
+        let changeCreated = false;
+        try {
+          await writeFile3(changePath, content, { flag: "wx" });
+          changeCreated = true;
+          await mkdir4(FOCUS_DIR, { recursive: true });
+          await mkdir4(dirname2(focusEntry), { recursive: true });
+          await writeManagedFile(focusEntry, "", "focus marker");
+        } catch (error) {
+          if (changeCreated) {
+            try {
+              await unlink4(changePath);
+              await cleanupEmptyParentDirs(changePath, CHANGES_DIR);
+            } catch {
+            }
+          }
+          throw error;
+        }
+      }
+      const label = existed ? "Using" : pc.green("Created");
+      console.log(`  ${label}: ${changePath}`);
+      if (existed)
+        console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${name}`);
+      else
+        console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${name}`);
+      console.log(`  ${pc.cyan("Next:")} ${options.lite ? "fill the lite change details, then implement and verify" : "fill proposal/spec/design first, then implement and complete the tasks"}
+`);
+    });
+  } catch (error) {
+    if (error instanceof WorkRefError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync6 } from "fs";
+import { readdir, readFile as readFile7, stat } from "fs/promises";
+import { basename as basename4, join as join6, relative as relative3 } from "path";
+
+// src/commands/update.ts
+import { existsSync as existsSync5 } from "fs";
+import { mkdir as mkdir5, readFile as readFile6, rm, rmdir } from "fs/promises";
+import { join as join5 } from "path";
+var SKILL_REFRESH_HINT = "  Note: if you use package-bundled RSP Skills, refresh them too:\n    rsp skills install --dry-run\n    rsp skills install --force\n";
+async function updateProject(options = {}) {
+  if (!existsSync5(RSP_DIR)) {
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
     process.exit(1);
   }
-  guardRspInitialized();
-  return withRspLock("create-change", async () => {
-    const changePath = join9(CHANGES_DIR, `${name}.md`);
-    await mkdir5(dirname7(changePath), { recursive: true });
-    const existed = existsSync9(changePath);
-    if (!existed) {
-      const content = generateChangeContent(name, summary, kind);
-      await writeFile6(changePath, content);
-      await mkdir5(FOCUS_DIR, { recursive: true });
-      const focusEntry = join9(FOCUS_DIR, name);
-      await mkdir5(dirname7(focusEntry), { recursive: true });
-      await writeFile6(focusEntry, "");
-    }
-    const label = existed ? "Using" : pc.green("Created");
-    console.log(`  ${label}: ${changePath}`);
-    if (existed)
-      console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${name}`);
-    else
-      console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${name}`);
-    console.log(`  ${pc.cyan("Next:")} fill proposal/spec/design first, then implement and complete the tasks
+  return withRspLock("update", async () => {
+    const agentsPath = "AGENTS.md";
+    const agentsInspection = inspectManagedFile(agentsPath, "AGENTS.md", { allowMissing: true });
+    if (agentsInspection.issue)
+      throw agentsInspection.issue;
+    let updated = false;
+    const actions = [];
+    clearConfigCache();
+    const configInspection = await inspectRspConfig();
+    if (configInspection.issues.length > 0)
+      throw new Error(configInspection.issues.join("; "));
+    const decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+    const decisionRecordsFilesystemIssue = await validateDecisionRecordsFilesystemPath(decisionRecordsPath);
+    if (decisionRecordsFilesystemIssue)
+      throw new Error(decisionRecordsFilesystemIssue);
+    const changesInspection = inspectManagedDirectory(CHANGES_DIR, "open work root", { allowMissing: true });
+    if (changesInspection.issue)
+      throw changesInspection.issue;
+    if (!changesInspection.exists) {
+      await mkdir5(CHANGES_DIR, { recursive: true });
+      await ensureManagedFile(join5(CHANGES_DIR, ".gitkeep"), "", "changes placeholder");
+      actions.push("changes/ directory restored");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} changes/ directory restored`);
+      updated = true;
+    }
+    const bundledRules = await readFile6(join5(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    const rulesInspection = inspectManagedFile(RSP_RULES_PATH, "fallback protocol", { allowMissing: true });
+    if (rulesInspection.issue)
+      throw rulesInspection.issue;
+    const existingRules = rulesInspection.exists ? await readFile6(RSP_RULES_PATH, "utf-8") : null;
+    if (existingRules !== bundledRules) {
+      await writeManagedFile(RSP_RULES_PATH, bundledRules, "fallback protocol");
+      actions.push("rsp-rules.md updated");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} rsp-rules.md updated`);
+      updated = true;
+    }
+    if (existsSync5(OBSOLETE_RSP_RULES_PATH)) {
+      await rm(OBSOLETE_RSP_RULES_PATH);
+      actions.push("obsolete rules/rsp-rules.md removed");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} obsolete rules/rsp-rules.md removed`);
+      updated = true;
+    }
+    try {
+      await rmdir(join5(RSP_DIR, "rules"));
+      actions.push("empty rules directory removed");
+      updated = true;
+    } catch (error) {
+      if (!["ENOENT", "ENOTEMPTY"].includes(error.code || ""))
+        throw error;
+    }
+    let inspection = await inspectUnsupportedRules();
+    if (inspection.diagnostics.length === 0 && inspection.directoryRemaining && inspection.entries.every((entry) => entry.kind === "directory")) {
+      const directories = inspection.entries.map((entry) => entry.path).sort((left, right) => right.split("/").length - left.split("/").length);
+      for (const path of directories)
+        await rmdir(join5(RSP_DIR, "rules", path));
+      await rmdir(join5(RSP_DIR, "rules"));
+      actions.push("empty rules directory tree removed");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} empty rules directory tree removed`);
+      updated = true;
+      inspection = await inspectUnsupportedRules();
+    }
+    const residualEntries = inspection.entries.map((entry) => entry.path);
+    if (!options.quiet && inspection.diagnostics.length > 0) {
+      console.log(`  ${pc.red("Error:")} migration inspection incomplete:`);
+      for (const diagnostic of inspection.diagnostics)
+        console.log(`    ${diagnostic.path}: ${diagnostic.message}`);
+      console.log(`  ${pc.dim("Fix access to .rsp/rules/, then run rsp update again.")}`);
+      console.log();
+    }
+    if (!options.quiet && residualEntries.length > 0) {
+      console.log(`  ${pc.yellow("Warning:")} these entries are no longer read by RSP:`);
+      for (const path of residualEntries)
+        console.log(`    .rsp/rules/${path}`);
+      console.log(`  ${pc.dim("Move stable scoped instructions to the nearest project-owned AGENTS.md, then remove the old files.")}`);
+      console.log(`  ${pc.dim("Run: rsp doctor")}`);
+      console.log();
+    }
+    const projectName = await detectProjectName();
+    const baseAgents = agentsInspection.exists ? await readFile6(agentsPath, "utf-8") : `# ${projectName}
+
+`;
+    const nextAgents = upsertRspAgentsBlock(baseAgents);
+    if (!agentsInspection.exists || nextAgents.changed) {
+      await writeManagedFile(agentsPath, nextAgents.content, "AGENTS.md");
+      actions.push("AGENTS.md managed block refreshed");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} AGENTS.md managed block refreshed`);
+      updated = true;
+    }
+    if (await ensureDecisionRecordsDirectory(decisionRecordsPath)) {
+      actions.push(`Decision Record directory ensured: ${decisionRecordsPath}`);
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} Decision Record directory ensured: ${decisionRecordsPath}`);
+      updated = true;
+    }
+    const specsIndexChanged = await buildSpecsIndex({ acquireLock: false, quiet: options.quiet });
+    const archiveIndexChanged = await buildArchiveIndex({ acquireLock: false, quiet: options.quiet });
+    if (specsIndexChanged || archiveIndexChanged) {
+      actions.push("generated indexes rebuilt");
+      updated = true;
+    }
+    if (!options.quiet && inspection.diagnostics.length > 0) {
+      console.log(`  ${pc.red("Managed update incomplete; migration inspection failed.")}
+`);
+      console.log(SKILL_REFRESH_HINT);
+    } else if (!options.quiet && residualEntries.length > 0) {
+      console.log(`  ${pc.yellow(updated ? "Managed update complete; manual migration remains." : "Managed files are up to date; manual migration remains.")}
+`);
+      console.log(SKILL_REFRESH_HINT);
+    } else if (!options.quiet && !updated) {
+      console.log(`  ${pc.dim("Already up to date.")}
+`);
+      console.log(SKILL_REFRESH_HINT);
+    } else if (!options.quiet) {
+      console.log(`  ${pc.green("Update complete.")}
 `);
+      console.log(SKILL_REFRESH_HINT);
+    }
+    return {
+      actions,
+      migration: {
+        inspectionComplete: inspection.diagnostics.length === 0,
+        manualMigrationRequired: inspection.directoryRemaining,
+        residualEntries,
+        diagnostics: inspection.diagnostics
+      }
+    };
   });
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile8 } from "fs/promises";
-import { basename as basename5, join as join10, relative as relative5 } from "path";
 async function runDoctor(options = {}) {
+  const fixed = [];
+  let repairIssue = null;
+  if (options.fix && existsSync6(RSP_DIR)) {
+    try {
+      const update = await updateProject({ quiet: Boolean(options.json) });
+      fixed.push(...update.actions);
+    } catch (error) {
+      repairIssue = `safe deterministic repair could not run: ${toErrorMessage(error)}`;
+    }
+  }
   const checks = [];
+  if (repairIssue) {
+    checks.push({
+      status: "issue",
+      label: "safe deterministic repairs completed",
+      message: repairIssue,
+      hint: "Resolve the reported configuration or filesystem issue, then run rsp doctor --fix again."
+    });
+  }
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
-  const rspRulesPath = join10(RSP_DIR, "rules", "rsp-rules.md");
-  const designPath = join10(RSP_DIR, "specs", "design.md");
-  const specsIndexPath = join10(RSP_DIR, "specs", "INDEX.md");
-  const archivesIndexPath = join10(RSP_DIR, "archives", "INDEX.md");
-  reportCheck(checks, ".rsp exists", existsSync10(RSP_DIR), "Run: rsp init");
-  reportCheck(checks, "rules/rsp-rules.md exists", existsSync10(rspRulesPath), "Run: rsp init");
-  reportCheck(checks, "specs/design.md exists", existsSync10(designPath), "Run: rsp init");
-  reportCheck(checks, "specs/INDEX.md exists", existsSync10(specsIndexPath), "Run: rsp update");
-  reportCheck(checks, "archives/INDEX.md exists", existsSync10(archivesIndexPath), "Run: rsp update");
+  const designPath = join6(RSP_DIR, "specs", "design.md");
+  const specsIndexPath = join6(RSP_DIR, "specs", "INDEX.md");
+  const archivesIndexPath = join6(RSP_DIR, "archives", "INDEX.md");
+  reportCheck(checks, ".rsp exists", existsSync6(RSP_DIR), "Run: rsp init");
+  reportFallbackProtocol(checks);
+  await reportUnsupportedRules(checks, reportRuntime);
+  reportCheck(checks, "specs/design.md exists", existsSync6(designPath), "Run: rsp init");
+  reportCheck(checks, "specs/INDEX.md exists", existsSync6(specsIndexPath), "Run: rsp update");
+  reportCheck(checks, "archives/INDEX.md exists", existsSync6(archivesIndexPath), "Run: rsp update");
   await checkAgents(checks, reportRuntime);
-  await checkGeneratedIndex(checks, reportRuntime, specsIndexPath, "_Auto-generated by `rsp update`._", "specs/INDEX.md has generated signature", "Run: rsp update");
-  await checkGeneratedIndex(checks, reportRuntime, archivesIndexPath, "_Auto-generated by `rsp update`._", "archives/INDEX.md has generated signature", "Run: rsp update");
-  await checkArchiveNaming(checks, reportRuntime);
-  await checkConfigSemantics(checks, reportRuntime);
-  await checkActiveChangeConsistency(checks, reportRuntime);
+  await checkGeneratedIndex(checks, reportRuntime, specsIndexPath, "specs", "specs/INDEX.md has generated-index metadata", "Run: rsp update");
+  await checkGeneratedIndex(checks, reportRuntime, archivesIndexPath, "archives", "archives/INDEX.md has generated-index metadata", "Run: rsp update");
+  await checkArchiveNaming(checks);
+  const decisionRecordsConfigValid = await checkConfigSemantics(checks, reportRuntime);
+  if (decisionRecordsConfigValid) {
+    await checkDecisionRecordsDirectory(checks, reportRuntime);
+    await checkInactiveDefaultDecisionRecords(checks, reportRuntime);
+  }
+  await checkActiveChangeConsistency(checks);
   const result = {
     command: "doctor",
     ok: checks.every((check) => check.status !== "issue"),
+    fixed,
     checks,
     runtime,
     summary: {
@@ -1296,12 +1158,19 @@ async function runDoctor(options = {}) {
     }
   };
   if (options.json) {
-    emitJson(result);
+    emitJson(result, options);
     return result;
   }
   console.log();
   console.log(`  ${pc.bold("RSP doctor")}`);
   console.log();
+  if (fixed.length > 0) {
+    console.log(`  ${pc.green("Fixed:")} ${fixed.join(", ")}`);
+    console.log();
+  } else if (options.fix && !repairIssue && existsSync6(RSP_DIR)) {
+    console.log(`  ${pc.dim("No safe fixes needed.")}`);
+    console.log();
+  }
   for (const check of checks)
     printDoctorCheck(check);
   if (result.summary.issues === 0)
@@ -1314,6 +1183,57 @@ async function runDoctor(options = {}) {
 `);
   return result;
 }
+function reportFallbackProtocol(checks) {
+  const canonical = inspectManagedFile(RSP_RULES_PATH, "fallback protocol", { allowMissing: true });
+  const obsoleteExists = existsSync6(OBSOLETE_RSP_RULES_PATH);
+  if (canonical.issue) {
+    checks.push({
+      status: "issue",
+      label: "rsp-rules.md is a regular managed file",
+      message: canonical.issue.message,
+      hint: "Replace the unsupported entry with a project-local regular file, then run: rsp update"
+    });
+  } else if (canonical.exists) {
+    checks.push({ status: "ok", label: "rsp-rules.md exists" });
+  } else if (!obsoleteExists) {
+    checks.push({
+      status: "issue",
+      label: "rsp-rules.md exists",
+      hint: existsSync6(RSP_DIR) ? "Run: rsp update" : "Run: rsp init"
+    });
+  }
+  if (obsoleteExists) {
+    checks.push({
+      status: "issue",
+      label: "obsolete fallback protocol path detected",
+      message: "obsolete fallback protocol path detected",
+      hint: "Run: rsp update"
+    });
+  }
+}
+async function reportUnsupportedRules(checks, reportRuntime) {
+  const inspection = await inspectUnsupportedRules();
+  for (const diagnostic of inspection.diagnostics)
+    reportRuntime(diagnostic);
+  if (inspection.diagnostics.length > 0) {
+    checks.push({
+      status: "issue",
+      label: "unable to inspect .rsp/rules/",
+      message: "unable to inspect .rsp/rules/; migration status is unknown",
+      hint: "Fix directory access, then run: rsp doctor"
+    });
+    return;
+  }
+  if (!inspection.directoryRemaining)
+    return;
+  const entries = inspection.entries.map((entry) => entry.path);
+  checks.push({
+    status: "issue",
+    label: "unsupported .rsp/rules/ entries",
+    message: entries.length > 0 ? `unsupported .rsp/rules/ entries: ${entries.join(", ")}` : "unsupported empty .rsp/rules/ directory remains",
+    hint: "Move stable scoped instructions to the nearest project-owned AGENTS.md, remove obsolete entries, then run rsp update"
+  });
+}
 function reportCheck(checks, label, ok, fixHint) {
   if (ok) {
     checks.push({ status: "ok", label });
@@ -1337,13 +1257,23 @@ function printDoctorCheck(check) {
     console.log(`    ${pc.dim(check.hint)}`);
 }
 async function checkAgents(checks, reportRuntime) {
-  if (!existsSync10("AGENTS.md")) {
+  const inspection = inspectManagedFile("AGENTS.md", "AGENTS.md", { allowMissing: true });
+  if (inspection.issue) {
+    checks.push({
+      status: "issue",
+      label: "AGENTS.md is a regular managed file",
+      message: inspection.issue.message,
+      hint: "Replace the unsupported entry with a project-local regular file, then run: rsp update"
+    });
+    return;
+  }
+  if (!inspection.exists) {
     checks.push({ status: "issue", label: "AGENTS.md contains managed RSP block", message: "AGENTS.md missing", hint: "Run: rsp init" });
     return;
   }
   let agents;
   try {
-    agents = await readFile8("AGENTS.md", "utf-8");
+    agents = await readFile7("AGENTS.md", "utf-8");
   } catch (error) {
     reportRuntime({
       code: "agents_read_failed",
@@ -1360,12 +1290,17 @@ async function checkAgents(checks, reportRuntime) {
   }
   checks.push({ status: "issue", label: "AGENTS.md contains managed RSP block", message: "AGENTS.md missing managed RSP block", hint: "Run: rsp init" });
 }
-async function checkGeneratedIndex(checks, reportRuntime, path, signature, label, fixHint) {
-  if (!existsSync10(path))
+async function checkGeneratedIndex(checks, reportRuntime, path, expectedIndexType, label, fixHint) {
+  const indexFile = inspectManagedFile(path, label, { allowMissing: true });
+  if (indexFile.issue) {
+    checks.push({ status: "issue", label, message: indexFile.issue.message, hint: fixHint });
+    return;
+  }
+  if (!indexFile.exists)
     return;
   let content;
   try {
-    content = await readFile8(path, "utf-8");
+    content = await readFile7(path, "utf-8");
   } catch (error) {
     reportRuntime({
       code: "generated_index_read_failed",
@@ -1376,16 +1311,38 @@ async function checkGeneratedIndex(checks, reportRuntime, path, signature, label
     checks.push({ status: "issue", label, message: `${label} could not be read`, hint: fixHint });
     return;
   }
-  if (content.includes(signature)) {
-    checks.push({ status: "ok", label });
+  try {
+    const fm = parseFrontmatter(content);
+    if (fm?.kind === "generated-index" && fm.index_type === expectedIndexType) {
+      checks.push({ status: "ok", label });
+      return;
+    }
+  } catch (error) {
+    reportRuntime({
+      code: "generated_index_frontmatter_parse_failed",
+      operation: "parseFrontmatter",
+      path,
+      message: toErrorMessage(error)
+    });
+    checks.push({ status: "issue", label, message: `${label} could not parse metadata`, hint: fixHint });
     return;
   }
   checks.push({ status: "issue", label, hint: fixHint });
 }
-async function checkArchiveNaming(checks, reportRuntime) {
-  const archivesDir = join10(RSP_DIR, "archives");
-  const archiveFiles = existsSync10(archivesDir) ? (await walkMarkdownFiles(archivesDir, { onError: reportRuntime })).filter((fp) => relative5(archivesDir, fp) !== "INDEX.md") : [];
-  const invalidFiles = archiveFiles.map((fp) => normalizeLogicalPath(relative5(archivesDir, fp))).filter((fp) => /^\d{4}-\d{2}-\d{2}_.+\.md$/.test(basename5(fp)) === false);
+async function checkArchiveNaming(checks) {
+  const archivesDir = join6(RSP_DIR, "archives");
+  const inspection = await inspectArchiveTree({ archivesDir });
+  if (inspection.diagnostics.length > 0) {
+    checks.push({
+      status: "issue",
+      label: "archives use supported managed paths",
+      message: inspection.diagnostics.map((diagnostic) => diagnostic.message).join("; "),
+      hint: "Keep archives flat or one real group directory deep; remove symlinks and unsupported entries."
+    });
+    return;
+  }
+  checks.push({ status: "ok", label: "archives use supported managed paths" });
+  const invalidFiles = inspection.files.map((fp) => normalizeLogicalPath(relative3(archivesDir, fp))).filter((fp) => /^\d{4}-\d{2}-\d{2}_.+\.md$/.test(basename4(fp)) === false);
   if (invalidFiles.length === 0) {
     checks.push({ status: "ok", label: "archived change files follow the date_name.md convention" });
     return;
@@ -1398,69 +1355,172 @@ async function checkArchiveNaming(checks, reportRuntime) {
   });
 }
 async function checkConfigSemantics(checks, reportRuntime) {
-  if (!existsSync10(CONFIG_PATH))
-    return;
-  let content;
+  clearConfigCache();
+  let inspection;
   try {
-    content = await readFile8(CONFIG_PATH, "utf-8");
+    inspection = await inspectRspConfig();
   } catch (error) {
+    const message = toErrorMessage(error);
     reportRuntime({
-      code: "config_read_failed",
-      operation: "readFile",
-      path: CONFIG_PATH,
-      message: toErrorMessage(error)
+      code: "invalid_config",
+      operation: "inspectRspConfig",
+      path: ".rsp/config.yaml",
+      message
+    });
+    checks.push({
+      status: "issue",
+      code: "invalid_config",
+      label: "config.yaml semantic checks",
+      message,
+      hint: "Fix the reported config file, YAML, or managed-path issue."
+    });
+    return false;
+  }
+  for (const issue of inspection.issues) {
+    checks.push({
+      status: "issue",
+      code: "invalid_config",
+      label: "config.yaml semantic checks",
+      message: issue,
+      hint: issue.includes("decisions") ? "Use .rsp/specs/decisions or one project-relative path outside .rsp/." : "Remove the unsupported field or provide the documented value type."
     });
-    checks.push({ status: "issue", label: "config.yaml semantic checks", message: "config.yaml could not be read", hint: "Check .rsp/config.yaml permissions or recreate it with rsp init" });
-    return;
   }
-  let parsed;
+  if (inspection.issues.length === 0 && inspection.config.kinds !== void 0)
+    checks.push({ status: "ok", label: 'config.yaml field "kinds" has valid list semantics' });
+  return inspection.issues.length === 0;
+}
+async function checkDecisionRecordsDirectory(checks, reportRuntime) {
+  const decisionRecordsPath = resolveDecisionRecordsPath(await loadRspConfig());
   try {
-    parsed = parseYamlText(content);
+    const filesystemError = await validateDecisionRecordsFilesystemPath(decisionRecordsPath);
+    if (filesystemError) {
+      checks.push({
+        status: "issue",
+        label: `${decisionRecordsPath} is the authoritative Decision Record directory`,
+        message: filesystemError,
+        hint: "Choose a project-relative directory that does not escape through a symlink."
+      });
+      return;
+    }
+    const info = await stat(decisionRecordsPath);
+    if (info.isDirectory())
+      await readdir(decisionRecordsPath);
+    reportCheck(
+      checks,
+      `${decisionRecordsPath} is the authoritative Decision Record directory`,
+      info.isDirectory(),
+      "Run: rsp update"
+    );
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    checks.push({ status: "issue", label: "config.yaml semantic checks", message: "config.yaml is not valid YAML", hint: message });
-    return;
-  }
-  reportConfigListField(checks, parsed, "kinds");
-  if ("required_sections" in parsed) {
+    if (error.code !== "ENOENT") {
+      reportRuntime({
+        code: "decision_records_path_stat_failed",
+        operation: "stat",
+        path: decisionRecordsPath,
+        message: toErrorMessage(error)
+      });
+    }
     checks.push({
       status: "issue",
-      label: "config.yaml semantic checks",
-      message: 'config.yaml field "required_sections" is no longer supported',
-      hint: 'RSP keeps the core change section structure fixed. Remove "required_sections" from .rsp/config.yaml.'
+      label: `${decisionRecordsPath} is the authoritative Decision Record directory`,
+      message: `${decisionRecordsPath} Decision Record directory is missing or unreadable`,
+      hint: "Run: rsp update"
     });
   }
 }
-function reportConfigListField(checks, parsed, key) {
-  if (!(key in parsed))
+async function checkInactiveDefaultDecisionRecords(checks, reportRuntime) {
+  const decisionRecordsPath = resolveDecisionRecordsPath(await loadRspConfig());
+  if (decisionRecordsPath === DEFAULT_DECISION_RECORDS_PATH || !existsSync6(DEFAULT_DECISION_RECORDS_PATH))
     return;
-  const value = parsed[key];
-  if (!Array.isArray(value)) {
+  let inspectionFailed = false;
+  const inactiveRecords = (await walkMarkdownFiles(DEFAULT_DECISION_RECORDS_PATH, {
+    onError: (diagnostic) => {
+      inspectionFailed = true;
+      reportRuntime(diagnostic);
+    }
+  })).map((path) => normalizeLogicalPath(relative3(DEFAULT_DECISION_RECORDS_PATH, path))).sort();
+  if (inspectionFailed) {
     checks.push({
       status: "issue",
-      label: "config.yaml semantic checks",
-      message: `config.yaml field "${key}" must be a YAML list`,
-      hint: `Update .rsp/config.yaml so "${key}" is a YAML sequence (for example: ${key}: [item])`
+      label: "inactive default Decision Records are inspectable",
+      message: `unable to inspect inactive default Decision Records under ${DEFAULT_DECISION_RECORDS_PATH}`,
+      hint: "Restore directory access, then run rsp doctor again."
     });
     return;
   }
-  const items = value.map(String);
-  const duplicates = [...new Set(items.filter((item, index) => items.indexOf(item) !== index))];
-  if (duplicates.length === 0) {
-    checks.push({ status: "ok", label: `config.yaml field "${key}" has valid list semantics` });
+  if (inactiveRecords.length === 0)
     return;
-  }
   checks.push({
     status: "issue",
-    label: "config.yaml semantic checks",
-    message: `config.yaml field "${key}" contains duplicate entries: ${duplicates.join(", ")}`,
-    hint: `Remove duplicate values from .rsp/config.yaml:${key}`
+    label: "inactive default Decision Records are migrated",
+    message: `inactive default Decision Records: ${inactiveRecords.join(", ")}`,
+    hint: `Move lasting rationale to ${decisionRecordsPath}, then remove the inactive files from ${DEFAULT_DECISION_RECORDS_PATH}.`
   });
 }
-async function checkActiveChangeConsistency(checks, reportRuntime) {
-  const changeFiles = existsSync10(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
-  const changeNames = new Set(changeFiles.map((fp) => changeNameFromPath(CHANGES_DIR, fp)));
-  const focusNames = await getFocusedChangeNames({ onError: reportRuntime });
+async function checkActiveChangeConsistency(checks) {
+  const workTree = await inspectWorkTree();
+  const focusTree = await inspectFocusTree();
+  const groupInspection = await inspectChangeGroups({ workTree, focusTree });
+  const dependencyInspection = await inspectChangeDependencies({ workTree });
+  const changeNames = new Set(workTree.changes.map((ref) => ref.name));
+  const structureIssues = workTree.diagnostics.map((diagnostic) => diagnostic.message);
+  structureIssues.push(...focusTree.diagnostics.map((diagnostic) => diagnostic.message));
+  const rawFocusNames = new Set(focusTree.markers.map((marker) => marker.name));
+  const focusNames = /* @__PURE__ */ new Set();
+  for (const name of rawFocusNames) {
+    try {
+      focusNames.add(resolveWorkRef(name, { executable: true }).name);
+    } catch (error) {
+      if (!(error instanceof WorkRefError))
+        throw error;
+      structureIssues.push(`focus.d/${name}: ${error.message}`);
+    }
+  }
+  const uniqueStructureIssues = [...new Set(structureIssues)];
+  if (uniqueStructureIssues.length === 0) {
+    checks.push({ status: "ok", label: "open work uses supported WorkRef shapes" });
+  } else {
+    checks.push({
+      status: "issue",
+      label: "open work uses supported WorkRef shapes",
+      message: uniqueStructureIssues.join("; "),
+      hint: "Keep work flat or use one group directory with direct Change files. Use rsp unfocus <group>/brief to clear an accidental Group Brief marker."
+    });
+  }
+  const groupStructureIssues = workTree.diagnostics.filter((diagnostic) => diagnostic.code === "group_brief_missing" || diagnostic.path.endsWith(`/${GROUP_BRIEF_FILENAME}`)).map((diagnostic) => diagnostic.message);
+  const groupIssues = [
+    ...groupInspection.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message),
+    ...groupStructureIssues
+  ];
+  const groupWarnings = groupInspection.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+  if (groupIssues.length === 0) {
+    checks.push({ status: "ok", label: "Change Group contracts are valid" });
+  } else {
+    checks.push({
+      status: "issue",
+      label: "Change Group contracts are valid",
+      message: [...new Set(groupIssues)].join("; "),
+      hint: `Keep one ${GROUP_BRIEF_FILENAME} per group and make its Slices list match direct open or archived child Changes.`
+    });
+  }
+  if (groupWarnings.length > 0) {
+    checks.push({
+      status: "info",
+      label: "Change Group completion guidance",
+      message: [...new Set(groupWarnings.map((diagnostic) => diagnostic.message))].join("; ")
+    });
+  }
+  const dependencyIssues = dependencyInspection.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  if (dependencyIssues.length === 0) {
+    checks.push({ status: "ok", label: "Change dependency graph is valid" });
+  } else {
+    checks.push({
+      status: "issue",
+      label: "Change dependency graph is valid",
+      message: [...new Set(dependencyIssues.map((diagnostic) => diagnostic.message))].join("; "),
+      hint: "Use exact existing Change WorkRefs, remove self-dependencies, and break dependency cycles."
+    });
+  }
   const missingChangeFiles = [...focusNames].filter((name) => !changeNames.has(name));
   const unfocusedChangeFiles = [...changeNames].filter((name) => !focusNames.has(name));
   if (missingChangeFiles.length === 0) {
@@ -1488,119 +1548,454 @@ async function checkActiveChangeConsistency(checks, reportRuntime) {
 }
 
 // src/commands/focus.ts
-import { existsSync as existsSync11 } from "fs";
-import { mkdir as mkdir6, unlink as unlink3, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname8, join as join11 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir6, unlink as unlink5 } from "fs/promises";
+import { dirname as dirname3 } from "path";
 async function focusChange(name) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp focus <name>`);
     process.exit(1);
   }
-  if (!isValidChangeName(name)) {
-    console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
-    process.exit(1);
-  }
   guardRspInitialized();
-  const changePath = join11(CHANGES_DIR, `${name}.md`);
-  if (!existsSync11(changePath)) {
-    console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
-    process.exit(1);
+  try {
+    return await withRspLock("focus-change", async () => {
+      const workRef = await resolveExecutableChange(name, { mustExist: true });
+      const focusEntry = resolveFocusMarkerPath(workRef);
+      await mkdir6(FOCUS_DIR, { recursive: true });
+      await mkdir6(dirname3(focusEntry), { recursive: true });
+      await writeManagedFile(focusEntry, "", "focus marker");
+      console.log(`  ${pc.green("Focused:")} ${name}`);
+      console.log(`  ${pc.dim("focus.d")} \u2192 ${name}`);
+      console.log();
+    });
+  } catch (error) {
+    exitWorkRefError(error);
   }
-  return withRspLock("focus-change", async () => {
-    await mkdir6(FOCUS_DIR, { recursive: true });
-    const focusEntry = join11(FOCUS_DIR, name);
-    await mkdir6(dirname8(focusEntry), { recursive: true });
-    await writeFile7(focusEntry, "");
-    console.log(`  ${pc.green("Focused:")} ${name}`);
-    console.log(`  ${pc.dim("focus.d")} \u2192 ${name}`);
-    console.log();
-  });
 }
 async function unfocusChange(name) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp unfocus <name>`);
     process.exit(1);
   }
-  if (!isValidChangeName(name)) {
-    console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
-    process.exit(1);
-  }
   guardRspInitialized();
-  const focusEntry = join11(FOCUS_DIR, name);
-  if (!existsSync11(focusEntry)) {
-    console.error(`  ${pc.red("Focus marker not found:")} .rsp/focus.d/${name}`);
-    process.exit(1);
+  try {
+    return await withRspLock("unfocus-change", async () => {
+      const workRef = resolveWorkRef(name, { executable: false, mustExist: false });
+      const focusEntry = resolveFocusMarkerPath(workRef);
+      if (!existsSync7(focusEntry))
+        throw new WorkRefError("focus_marker_not_found", `.rsp/focus.d/${name}`, name);
+      await unlink5(focusEntry);
+      await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
+      console.log(`  ${pc.green("Unfocused:")} ${name}`);
+      console.log(`  ${pc.dim("focus.d cleared")} \u2192 ${name}`);
+      console.log();
+    });
+  } catch (error) {
+    exitWorkRefError(error);
   }
-  return withRspLock("unfocus-change", async () => {
-    await unlink3(focusEntry);
-    await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
-    console.log(`  ${pc.green("Unfocused:")} ${name}`);
-    console.log(`  ${pc.dim("focus.d cleared")} \u2192 ${name}`);
-    console.log();
-  });
+}
+function exitWorkRefError(error) {
+  if (error instanceof WorkRefError) {
+    if (error.code === "focus_marker_not_found")
+      console.error(`  ${pc.red("Focus marker not found:")} ${error.message}`);
+    else
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+    process.exit(1);
+  }
+  throw error;
+}
+
+// src/commands/group.ts
+import { mkdir as mkdir7, rename as rename2, writeFile as writeFile4 } from "fs/promises";
+import { join as join7 } from "path";
+var ChangeGroupError = class extends Error {
+  name = "ChangeGroupError";
+};
+async function createChangeGroup(name, goal = "") {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp group create <name> [goal]`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  try {
+    await withRspLock("create-change-group", async () => {
+      const ref = resolveWorkRef(`${name}/brief`);
+      if (ref.kind !== "group-brief")
+        throw new WorkRefError("invalid_work_ref", `invalid Change Group name: ${name}`, name);
+      if (await hasArchivedGroupBrief(name))
+        throw new ChangeGroupError(`archived Change Group cannot be reopened: ${name}`);
+      const groupDirectory = resolveManagedDirectoryChain(CHANGES_DIR, [name], "Change Group path");
+      await mkdir7(groupDirectory, { recursive: true });
+      try {
+        await writeFile4(ref.path, generateGroupBriefContent(name, goal), { flag: "wx" });
+      } catch (error) {
+        if (error.code === "EEXIST")
+          throw new ChangeGroupError(`Change Group already exists: ${name}`);
+        throw error;
+      }
+      console.log(`  ${pc.green("Created Change Group:")} ${name}`);
+      console.log(`  ${pc.dim("Unfocused Group Brief:")} ${ref.path}`);
+      console.log(`  ${pc.cyan("Next:")} fill the brief, then create direct child Changes with rsp create ${name}/<change>
+`);
+    });
+  } catch (error) {
+    if (error instanceof WorkRefError || error instanceof ChangeGroupError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+async function closeChangeGroup(name) {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp group close <name>`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  try {
+    await withRspLock("close-change-group", async () => {
+      const ref = resolveWorkRef(`${name}/brief`, { mustExist: true });
+      if (ref.kind !== "group-brief")
+        throw new ChangeGroupError(`invalid Change Group name: ${name}`);
+      const inspection = await inspectChangeGroups();
+      const group = inspection.groups.find((candidate) => candidate.name === name);
+      if (!group)
+        throw new ChangeGroupError(`Change Group not found: ${name}`);
+      const reasons = collectCloseReasons(group, inspection.diagnostics.filter((diagnostic) => diagnostic.change === name && diagnostic.severity === "error").map((diagnostic) => diagnostic.message));
+      if (reasons.length > 0)
+        throw new ChangeGroupError(`Change Group "${name}" is not ready to close: ${reasons.join("; ")}`);
+      const archiveDirectory = resolveArchiveDirectory(ref);
+      const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const archiveName = resolveArchiveName(archiveDirectory, date, "brief");
+      await mkdir7(archiveDirectory, { recursive: true });
+      await rename2(ref.path, join7(archiveDirectory, archiveName));
+      const warnings = [];
+      try {
+        await cleanupEmptyParentDirs(ref.path, CHANGES_DIR);
+      } catch (error) {
+        warnings.push(`changes directory cleanup failed: ${toErrorMessage(error)}`);
+      }
+      try {
+        await buildArchiveIndex({ acquireLock: false });
+      } catch (error) {
+        warnings.push(`archive index rebuild failed: ${toErrorMessage(error)}`);
+      }
+      console.log(`  ${pc.green("Closed Change Group:")} ${name}`);
+      console.log(`  ${pc.dim("Archived Group Brief:")} ${join7(archiveDirectory, archiveName)}
+`);
+      for (const warning of warnings)
+        console.log(`  ${pc.yellow("\u26A0")} ${warning}`);
+      if (warnings.length > 0)
+        console.log(`  ${pc.yellow("Group close completed, but follow-up cleanup was only partially successful.")}
+`);
+    });
+  } catch (error) {
+    if (error instanceof WorkRefError || error instanceof ChangeGroupError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+function collectCloseReasons(group, errors) {
+  const reasons = [...errors, ...group.warnings];
+  const open = group.slices.filter((slice) => slice.state === "open").map((slice) => slice.name);
+  const missing = group.slices.filter((slice) => slice.state === "missing").map((slice) => slice.name);
+  if (open.length > 0)
+    reasons.push(`open slices: ${open.join(", ")}`);
+  if (missing.length > 0)
+    reasons.push(`missing slices: ${missing.join(", ")}`);
+  if (group.completion.total === 0)
+    reasons.push("no completion conditions are declared");
+  else if (group.completion.done !== group.completion.total)
+    reasons.push(`completion conditions incomplete: ${group.completion.done}/${group.completion.total}`);
+  if (group.blockers)
+    reasons.push("active group blockers remain");
+  return [...new Set(reasons)];
+}
+
+// src/commands/history.ts
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var GROUP_RE = /^[a-z0-9-]+$/;
+var WORK_REF_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)?$/;
+async function showHistory(input = {}, options = {}) {
+  guardRspInitialized();
+  const mode = input.workRef ? "detail" : "list";
+  const validation = validateHistoryQuery(input);
+  if (!validation.ok)
+    return emitHistoryError(mode, input, validation.error, [], emptyCollectionSummary(), [], options);
+  const inspection = await inspectArchiveHistory();
+  if (!historyInspectionComplete(inspection)) {
+    return emitHistoryError(mode, input, {
+      code: "archive_inspection_incomplete",
+      message: "archive history inspection is incomplete; resolve the reported diagnostics before querying history"
+    }, inspection.diagnostics, inspection.diagnosticSummary, inspection.runtime, options);
+  }
+  if (input.workRef) {
+    try {
+      const selected = selectArchiveHistoryRecord(inspection.records, { workRef: input.workRef });
+      const record = await readArchiveHistoryDetail(selected);
+      const result2 = {
+        command: "history",
+        ok: true,
+        mode: "detail",
+        query: { workRef: input.workRef },
+        record,
+        diagnostics: [],
+        diagnosticSummary: emptyCollectionSummary(),
+        runtime: inspection.runtime
+      };
+      if (options.json)
+        emitJson(result2, options);
+      else
+        printHistoryDetail(result2);
+      return result2;
+    } catch (error) {
+      if (error instanceof ArchiveHistoryError) {
+        return emitHistoryError(mode, input, {
+          code: error.code,
+          message: error.message,
+          candidates: error.candidates.length > 0 ? error.candidates : void 0,
+          candidateSummary: error.candidateTotal > 0 ? { total: error.candidateTotal, returned: error.candidates.length, hasMore: error.candidatesTruncated } : void 0
+        }, [], emptyCollectionSummary(), inspection.runtime, options);
+      }
+      throw error;
+    }
+  }
+  const query = validation.query;
+  const listed = queryArchiveHistory(inspection.records, query);
+  const result = {
+    command: "history",
+    ok: true,
+    mode: "list",
+    query: {
+      limit: query.limit ?? HISTORY_DEFAULT_LIMIT,
+      since: query.since ?? null,
+      until: query.until ?? null,
+      kind: query.kind ?? null,
+      group: query.group ?? null
+    },
+    records: listed.records,
+    summary: listed.summary,
+    diagnostics: [],
+    diagnosticSummary: emptyCollectionSummary(),
+    runtime: inspection.runtime
+  };
+  if (options.json)
+    emitJson(result, options);
+  else
+    printHistoryList(result);
+  return result;
+}
+function validateHistoryQuery(input) {
+  if ((input.positionalCount ?? (input.workRef ? 1 : 0)) > 1)
+    return invalid("history_positional_args_unsupported", "history accepts at most one positional WorkRef");
+  if (input.workRef) {
+    if (!WORK_REF_RE.test(input.workRef) || input.workRef.endsWith("/brief") || input.workRef.endsWith("/00-brief"))
+      return invalid("invalid_history_work_ref", "history WorkRef must be a flat or one-Group-level executable Change identity");
+    if (input.limit !== void 0 || input.since !== void 0 || input.until !== void 0 || input.kind !== void 0 || input.group !== void 0)
+      return invalid("history_detail_filters_unsupported", "list filters cannot be combined with an exact history detail lookup");
+    return { ok: true, query: {} };
+  }
+  const limit = input.limit === void 0 ? HISTORY_DEFAULT_LIMIT : Number(input.limit);
+  if (input.limit !== void 0 && !/^[1-9]\d*$/.test(input.limit) || !Number.isInteger(limit) || limit < 1 || limit > HISTORY_MAX_LIMIT)
+    return invalid("invalid_history_limit", `--limit must be an integer from 1 through ${HISTORY_MAX_LIMIT}`);
+  if (input.since && !isCalendarDate(input.since))
+    return invalid("invalid_history_since", "--since must be a valid YYYY-MM-DD date");
+  if (input.until && !isCalendarDate(input.until))
+    return invalid("invalid_history_until", "--until must be a valid YYYY-MM-DD date");
+  if (input.since && input.until && input.since > input.until)
+    return invalid("invalid_history_date_range", "--since must be on or before --until");
+  if (input.kind !== void 0 && input.kind.trim() === "")
+    return invalid("invalid_history_kind", "--kind must be a non-empty exact historical kind");
+  if (input.group !== void 0 && !GROUP_RE.test(input.group))
+    return invalid("invalid_history_group", "--group must be one lowercase kebab-case Group name");
+  return {
+    ok: true,
+    query: {
+      limit,
+      since: input.since,
+      until: input.until,
+      kind: input.kind?.trim(),
+      group: input.group
+    }
+  };
+}
+function invalid(code, message) {
+  return { ok: false, error: { code, message } };
+}
+function isCalendarDate(value) {
+  if (!DATE_RE.test(value))
+    return false;
+  const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+function emitHistoryError(mode, query, error, diagnostics, diagnosticSummary, runtime, options) {
+  const result = {
+    command: "history",
+    ok: false,
+    mode,
+    query,
+    records: [],
+    record: null,
+    diagnostics,
+    diagnosticSummary,
+    runtime,
+    error: {
+      code: error.code,
+      message: error.message,
+      ...error.candidates && { candidates: error.candidates },
+      ...error.candidateSummary && { candidateSummary: error.candidateSummary }
+    }
+  };
+  if (options.json) {
+    emitJson(result, options);
+  } else {
+    console.error(`  ${pc.red("Error:")} ${error.message}`);
+    for (const diagnostic of diagnostics)
+      console.error(`  ${pc.dim(`${diagnostic.path ?? "archive"} \u2014 ${diagnostic.message}`)}`);
+    if (diagnosticSummary.hasMore)
+      console.error(`  ${pc.dim(`${diagnosticSummary.total - diagnosticSummary.returned} additional diagnostic(s) omitted`)}`);
+    for (const candidate of error.candidates ?? [])
+      console.error(`  ${pc.dim(candidate)}`);
+    if (error.candidateSummary?.hasMore)
+      console.error(`  ${pc.dim(`${error.candidateSummary.total - error.candidateSummary.returned} additional candidate(s) omitted`)}`);
+  }
+  return result;
+}
+function emptyCollectionSummary() {
+  return { total: 0, returned: 0, hasMore: false };
+}
+function printHistoryList(result) {
+  console.log();
+  console.log(`  ${pc.bold("Archived Changes")}`);
+  console.log();
+  if (result.records.length === 0) {
+    console.log(`  ${pc.dim("No archived Changes match the query.")}
+`);
+    return;
+  }
+  for (const record of result.records) {
+    console.log(`  ${pc.dim(record.date)}  ${pc.cyan(record.workRef)}  ${pc.dim(`[${record.kind}]`)}`);
+    console.log(`    ${record.summary}${record.summaryTruncated ? "\u2026" : ""}`);
+    console.log(`    ${pc.dim(record.path)}`);
+  }
+  console.log();
+  console.log(`  ${pc.dim(`${result.summary.returned}/${result.summary.matched} matching archive(s) returned${result.summary.hasMore ? "; narrow filters or raise --limit for more" : ""}.`)}
+`);
+}
+function printHistoryDetail(result) {
+  const record = result.record;
+  console.log();
+  console.log(`  ${pc.bold("Archived Change:")} ${pc.cyan(record.workRef)}`);
+  console.log(`  ${pc.dim("Date:")} ${record.date}`);
+  console.log(`  ${pc.dim("Kind:")} ${record.kind}`);
+  console.log(`  ${pc.dim("Path:")} ${record.path}`);
+  console.log(`  ${pc.dim("Summary:")} ${record.summary}${record.summaryTruncated ? "\u2026" : ""}`);
+  console.log(`  ${pc.dim("Scenarios:")} ${record.scenarioCount}`);
+  console.log(`  ${pc.dim("Tasks:")} ${record.checkboxes.tasks.done}/${record.checkboxes.tasks.total}`);
+  console.log(`  ${pc.dim("Verify:")} ${record.checkboxes.verify.done}/${record.checkboxes.verify.total}`);
+  for (const [label, evidence] of Object.entries(record.evidence)) {
+    console.log();
+    console.log(`  ${pc.bold(`${label[0].toUpperCase()}${label.slice(1)}:`)}`);
+    if (evidence.items.length === 0)
+      console.log(`    ${pc.dim("none")}`);
+    else
+      evidence.items.forEach((item) => console.log(`    ${item}`));
+    if (evidence.truncated)
+      console.log(`    ${pc.dim("(truncated)")}`);
+  }
+  console.log();
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync12 } from "fs";
-import { mkdir as mkdir7, readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
-import { join as join12 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir8, readFile as readFile8 } from "fs/promises";
+import { join as join8 } from "path";
 function generateConfigTemplate() {
   const fmtList = (items, indent) => items.map((i) => `${" ".repeat(indent)}# - ${i}`).join("\n");
   return `# RSP project configuration
-# Uncomment any section below to customize classification values.
+# Omit kinds or use [] to retain the built-in defaults.
+# A non-empty kinds list replaces the built-in defaults; it does not extend them.
+# Every entry must be a unique non-empty string.
 #
 # Built-in defaults:
 #   kinds:               ${VALID_KINDS.join(", ")}
 #
 # kinds:
 ${fmtList(VALID_KINDS, 2)}
+
+# Decision Records default to .rsp/specs/decisions.
+# Set exactly one project-relative authoritative directory when the Host Project already owns Decision Records elsewhere.
+# decisions:
+#   path: docs/adr
 `;
 }
 async function ensureFile(path, content) {
-  if (existsSync12(path))
-    return false;
-  await writeFile8(path, content);
-  return true;
+  return ensureManagedFile(path, content, "managed file");
 }
 function toTitle(projectName) {
   return projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
 }
 async function initProject(args = {}) {
-  const isNew = !existsSync12(RSP_DIR);
+  const isNew = !existsSync8(RSP_DIR);
   const projectName = await detectProjectName();
   const mode = args.agentsMode ?? "managed";
   if (mode !== "managed" && mode !== "print") {
     console.error(`  ${pc.red("Error:")} unsupported --agents-mode "${mode}". Use: managed or print`);
     process.exit(1);
   }
+  const agentsPath = "AGENTS.md";
+  const initialAgentsInspection = inspectManagedFile(agentsPath, "AGENTS.md", { allowMissing: true });
+  if (initialAgentsInspection.issue)
+    throw initialAgentsInspection.issue;
   return withRspLock("init", async () => {
+    const agentsInspection = inspectManagedFile(agentsPath, "AGENTS.md", { allowMissing: true });
+    if (agentsInspection.issue)
+      throw agentsInspection.issue;
+    if (existsSync8(CONFIG_PATH)) {
+      clearConfigCache();
+      const existingConfig = await inspectRspConfig();
+      if (existingConfig.issues.length > 0)
+        throw new Error(existingConfig.issues.join("; "));
+      const existingDecisionRecordsPath = resolveDecisionRecordsPath(existingConfig.config);
+      const filesystemIssue = await validateDecisionRecordsFilesystemPath(existingDecisionRecordsPath);
+      if (filesystemIssue)
+        throw new Error(filesystemIssue);
+    }
     const dirs = [
-      join12(RSP_DIR, "rules"),
-      join12(RSP_DIR, "specs"),
-      CHANGES_DIR,
-      FOCUS_DIR,
-      join12(RSP_DIR, "archives")
+      { path: join8(RSP_DIR, "specs"), label: "specs root" },
+      { path: CHANGES_DIR, label: "open work root" },
+      { path: FOCUS_DIR, label: "focus root" },
+      { path: join8(RSP_DIR, "archives"), label: "archive root" }
     ];
-    for (const d of dirs)
-      await mkdir7(d, { recursive: true });
+    for (const directory of dirs)
+      requireManagedDirectory(directory.path, directory.label, { allowMissing: true });
+    for (const directory of dirs)
+      await mkdir8(directory.path, { recursive: true });
     let created = false;
-    const bundledRules = await readFile9(join12(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
-    created = await ensureFile(join12(RSP_DIR, "rules", "rsp-rules.md"), bundledRules) || created;
-    created = await ensureFile(join12(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
-    const createdSpecsIndex = await ensureFile(join12(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Additional project-level specs beyond `design.md`._\n");
+    const bundledRules = await readFile8(join8(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    created = await ensureFile(RSP_RULES_PATH, bundledRules) || created;
+    created = await ensureFile(join8(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
+    clearConfigCache();
+    const configInspection = await inspectRspConfig();
+    if (configInspection.issues.length > 0)
+      throw new Error(configInspection.issues.join("; "));
+    const decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+    created = await ensureDecisionRecordsDirectory(decisionRecordsPath) || created;
+    const createdSpecsIndex = await ensureFile(join8(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Additional project-level specs beyond `design.md`._\n");
     created = createdSpecsIndex || created;
-    const createdDesign = await ensureFile(join12(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
+    const createdDesign = await ensureFile(join8(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
     created = createdDesign || created;
-    const createdArchivesIndex = await ensureFile(join12(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
+    const createdArchivesIndex = await ensureFile(join8(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
     created = createdArchivesIndex || created;
-    created = await ensureFile(join12(CHANGES_DIR, ".gitkeep"), "") || created;
-    created = await ensureFile(join12(FOCUS_DIR, ".gitkeep"), "") || created;
-    created = await ensureFile(join12(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
-    if (args.withProjectRules)
-      created = await ensureFile(join12(RSP_DIR, "rules", "project-rules.md"), generateProjectRulesContent(projectName)) || created;
+    created = await ensureFile(join8(CHANGES_DIR, ".gitkeep"), "") || created;
+    created = await ensureFile(join8(FOCUS_DIR, ".gitkeep"), "") || created;
+    created = await ensureFile(join8(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
     if (args.withProjectSetup) {
-      const changePath = join12(CHANGES_DIR, "project-setup.md");
-      const focusMarker = join12(FOCUS_DIR, "project-setup");
+      const projectSetupRef = resolveWorkRef("project-setup", { executable: true });
+      const changePath = projectSetupRef.path;
+      const focusMarker = resolveFocusMarkerPath(projectSetupRef);
       created = await ensureFile(changePath, generateChangeContent("project-setup")) || created;
       created = await ensureFile(focusMarker, "") || created;
     }
@@ -1608,27 +2003,26 @@ async function initProject(args = {}) {
       await buildSpecsIndex({ acquireLock: false });
     if (createdArchivesIndex)
       await buildArchiveIndex({ acquireLock: false });
-    const agentsPath = "AGENTS.md";
     const title = toTitle(projectName);
     let agentsUpdated = false;
-    if (!existsSync12(agentsPath)) {
-      await writeFile8(agentsPath, `# ${title}
+    if (!agentsInspection.exists) {
+      await writeManagedFile(agentsPath, `# ${title}
 
 ${upsertRspAgentsBlock("").content}
-`);
+`, "AGENTS.md");
       created = true;
       agentsUpdated = true;
     } else {
-      const existing = await readFile9(agentsPath, "utf-8");
+      const existing = await readFile8(agentsPath, "utf-8");
       const next = upsertRspAgentsBlock(existing);
       if (next.changed) {
-        await writeFile8(agentsPath, next.content);
+        await writeManagedFile(agentsPath, next.content, "AGENTS.md");
         created = true;
         agentsUpdated = true;
       }
     }
     if (mode === "print") {
-      const managed = await readFile9(agentsPath, "utf-8");
+      const managed = await readFile8(agentsPath, "utf-8");
       console.log(`
 ${managed}
 `);
@@ -1640,8 +2034,9 @@ ${managed}
       console.log(`
   ${pc.green("RSP scaffolded.")}
 `);
-      console.log(`  Created: .rsp/rules/
+      console.log(`  Created: .rsp/rsp-rules.md
            .rsp/specs/
+           ${decisionRecordsPath}/
            .rsp/changes/
            .rsp/focus.d/
            .rsp/archives/
@@ -1665,210 +2060,744 @@ ${managed}
   });
 }
 
-// src/commands/status.ts
-import { existsSync as existsSync13 } from "fs";
-import { readFile as readFile10, stat } from "fs/promises";
-import { join as join13 } from "path";
-var COL_CHANGE = 32;
-var COL_KIND = 10;
-var COL_AGE = 7;
-var COL_PROGRESS = 10;
-async function showStatus(options = {}, runOptions = {}) {
+// src/commands/ready.ts
+import { readFile as readFile9 } from "fs/promises";
+function exitReadyError(name, error, options) {
+  if (options.json) {
+    emitJson({
+      command: "ready",
+      ok: false,
+      change: name || null,
+      path: null,
+      warnings: [],
+      runtime: [],
+      error
+    }, options);
+  } else {
+    console.error(`  ${pc.red("Error:")} ${error.message}`);
+  }
+  process.exit(1);
+}
+async function showReady(name, options = {}) {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp ready <name>`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  let workRef;
+  try {
+    workRef = await resolveExecutableChange(name, { mustExist: true });
+  } catch (error) {
+    if (error instanceof WorkRefError)
+      exitReadyError(name, { code: error.code, message: error.message }, options);
+    throw error;
+  }
+  const srcPath = workRef.path;
   const runtime = [];
-  const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(runOptions.verbose) && !runOptions.json);
-  const focusedSet = await getFocusedChangeNames({ onError: reportRuntime });
-  const changeFiles = existsSync13(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
-  const changeMap = {};
-  for (const fp of changeFiles)
-    changeMap[changeNameFromPath(CHANGES_DIR, fp)] = fp;
-  const allNames = [.../* @__PURE__ */ new Set([...Object.keys(changeMap), ...focusedSet])].sort();
-  const records = [];
-  const outputRecords = [];
-  for (const name of allNames) {
-    const fp = changeMap[name];
-    let kind = "\u2014";
-    let progress = "\u2014";
-    let ageDays = null;
-    const isFocused = focusedSet.has(name);
-    let isBlocked = false;
-    let done = 0;
-    let total = 0;
-    if (fp) {
-      try {
-        const content = await readFile10(fp, "utf-8");
-        try {
-          const fm = parseFrontmatter(content);
-          kind = fm?.kind ? String(fm.kind) : "\u2014";
-        } catch (error) {
-          kind = "(invalid)";
-          reportRuntime({
-            code: "frontmatter_parse_failed",
-            operation: "parseFrontmatter",
-            path: fp,
-            message: toErrorMessage(error)
-          });
-        }
-        isBlocked = hasMeaningfulBlockers(content);
-        const cb = countCheckboxes(content);
-        done = cb.done;
-        total = cb.total;
-        progress = `${done}/${total}`;
-      } catch (error) {
-        reportRuntime({
-          code: "change_read_failed",
-          operation: "readFile",
-          path: fp,
-          message: toErrorMessage(error)
-        });
-      }
-      try {
-        const s = await stat(fp);
-        ageDays = Math.floor((Date.now() - s.mtime.getTime()) / (1e3 * 60 * 60 * 24));
-      } catch (error) {
-        reportRuntime({
-          code: "change_stat_failed",
-          operation: "stat",
-          path: fp,
-          message: toErrorMessage(error)
-        });
-      }
-    } else {
-      kind = "(missing)";
-      reportRuntime({
-        code: "focused_change_missing",
-        operation: "resolveChange",
-        path: join13(CHANGES_DIR, `${name}.md`),
-        message: "focus marker points to a missing change file"
-      });
+  let content;
+  try {
+    content = await readFile9(srcPath, "utf-8");
+  } catch {
+    console.error(`  ${pc.red("Error:")} unable to read .rsp/changes/${name}.md`);
+    process.exit(1);
+  }
+  const dependencyInspection = await inspectChangeDependencies();
+  const readinessDetails = collectArchiveReadiness(content, {
+    activeBlockers: dependencyInspection.activeBlockers.get(name)
+  });
+  const checklist = readinessDetails.warnings;
+  const readiness = {
+    incompleteTasks: readinessDetails.taskTodos.length,
+    incompleteVerify: readinessDetails.verifyTodos.length,
+    activeBlockers: readinessDetails.activeBlockers,
+    missingScenarios: readinessDetails.missingScenarios,
+    deterministic: readinessDetails.deterministic,
+    semantic: readinessDetails.semantic,
+    archiveReady: readinessDetails.archiveReady
+  };
+  let decisionRecordsPath;
+  try {
+    const configInspection = await inspectRspConfig();
+    if (configInspection.issues.length > 0)
+      exitReadyError(name, { code: "invalid_config", message: configInspection.issues.join("; ") }, options);
+    decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+    const filesystemIssue = await validateDecisionRecordsFilesystemPath(decisionRecordsPath);
+    if (filesystemIssue)
+      exitReadyError(name, { code: "invalid_decision_records_path", message: filesystemIssue }, options);
+  } catch (error) {
+    exitReadyError(name, { code: "invalid_config", message: `.rsp/config.yaml could not be parsed: ${toErrorMessage(error)}` }, options);
+  }
+  const durableReview = buildDurableReviewGuidance(getDurableReviewCandidateTargets(), decisionRecordsPath);
+  const result = {
+    command: "ready",
+    ok: true,
+    change: name,
+    path: normalizeLogicalPath(srcPath),
+    readiness,
+    durableReview,
+    warnings: checklist,
+    runtime
+  };
+  if (options.json) {
+    emitJson(result, options);
+    return result;
+  }
+  console.log();
+  console.log(`  ${pc.bold("Archive readiness for")} ${pc.cyan(name)}`);
+  console.log();
+  if (checklist.length === 0) {
+    console.log(`  ${pc.green("\u2713")} Ready to archive. No deterministic warnings found.
+`);
+  } else {
+    for (const line of checklist)
+      console.log(`  ${pc.yellow("\u26A0")} ${line}`);
+    console.log();
+    console.log(`  ${pc.dim("Review the warnings above before treating this work as fully closed.")}`);
+  }
+  console.log(`  ${pc.dim("Deterministic readiness:")} ${readiness.deterministic === "pass" ? pc.green("pass") : pc.yellow("warnings")}`);
+  console.log(`  ${pc.dim("Semantic review:")} ${pc.yellow("needed")}`);
+  console.log(`  ${pc.dim("Archive ready:")} ${formatArchiveReady(readiness.archiveReady)}
+`);
+  console.log(`  ${pc.bold("Durable review:")}`);
+  console.log(`    ${pc.dim("Current-fact options:")} ${durableReview.factDecisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Rationale options:")} ${durableReview.rationaleDecisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Current-fact targets:")} ${durableReview.factCandidateTargets.join(", ")}`);
+  console.log(`    ${pc.dim("Decision Record path:")} ${durableReview.decisionRecordsPath}`);
+  console.log(`    ${pc.dim(durableReview.note)}
+`);
+  return result;
+}
+function formatArchiveReady(value) {
+  switch (value) {
+    case "yes":
+      return pc.green("yes");
+    case "no":
+      return pc.yellow("no");
+    case "judgment":
+      return pc.yellow("judgment");
+  }
+}
+
+// src/commands/show.ts
+import { readFile as readFile10 } from "fs/promises";
+function exitShowError(error, options) {
+  const nextActions = error.code === "no_focused_change" ? ["Run: rsp status", "Run: rsp focus <name>", "Or run: rsp create <name>"] : [];
+  if (options.json) {
+    emitJson({
+      command: "show",
+      ok: false,
+      change: null,
+      contextPaths: [],
+      runtime: [],
+      nextActions,
+      error
+    }, options);
+  } else {
+    console.error(`  ${pc.red("Error:")} ${error.message}`);
+    for (const action of nextActions)
+      console.error(`  ${pc.dim(action)}`);
+  }
+  process.exit(1);
+}
+async function showChange(nameOrFocused, options = {}) {
+  const runtime = [];
+  const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
+  guardRspInitialized();
+  const focusTree = await inspectFocusTree();
+  if (focusTree.diagnostics.length > 0) {
+    const diagnostic = focusTree.diagnostics[0];
+    exitShowError({ code: diagnostic.code, message: diagnostic.message }, options);
+  }
+  const focused = new Set(focusTree.markers.map((marker) => marker.name));
+  let name;
+  if (options.focused) {
+    if (focused.size === 0) {
+      exitShowError({ code: "no_focused_change", message: "no focused change exists" }, options);
     }
-    const age = ageDays === null ? "\u2014" : String(ageDays);
-    records.push({ name, kind, progress, age, isFocused, isBlocked });
-    outputRecords.push({
+    if (focused.size > 1) {
+      exitShowError({
+        code: "multiple_focused_changes",
+        message: `multiple focused changes exist (${[...focused].join(", ")}). Specify a name or focus exactly one change.`
+      }, options);
+    }
+    name = [...focused][0];
+  } else if (nameOrFocused) {
+    name = nameOrFocused;
+  } else {
+    exitShowError({ code: "missing_change_name", message: "Usage: rsp show <name|--focused> [--json] [--verbose]" }, options);
+  }
+  let workRef;
+  try {
+    workRef = await resolveExecutableChange(name, { mustExist: true });
+  } catch (error) {
+    if (error instanceof WorkRefError)
+      exitShowError({ code: error.code, message: error.message }, options);
+    throw error;
+  }
+  const srcPath = workRef.path;
+  let content;
+  try {
+    content = await readFile10(srcPath, "utf-8");
+  } catch {
+    exitShowError({ code: "change_read_failed", message: `unable to read .rsp/changes/${name}.md` }, options);
+  }
+  let kind = "\u2014";
+  try {
+    const fm = parseFrontmatter(content);
+    kind = fm?.kind ? String(fm.kind) : "\u2014";
+  } catch (error) {
+    kind = "(invalid)";
+    reportRuntime({
+      code: "frontmatter_parse_failed",
+      operation: "parseFrontmatter",
+      path: srcPath,
+      message: toErrorMessage(error)
+    });
+  }
+  const isFocused = focused.has(name);
+  const dependencyInspection = await inspectChangeDependencies();
+  const cb = countCheckboxes(content);
+  const blockers = dependencyInspection.activeBlockers.get(name) ?? hasMeaningfulBlockers(content);
+  const scenarios = parseScenarios(content);
+  const readinessDetails = collectArchiveReadiness(content, { activeBlockers: blockers });
+  const readiness = {
+    incompleteTasks: readinessDetails.taskTodos.length,
+    incompleteVerify: readinessDetails.verifyTodos.length,
+    activeBlockers: readinessDetails.activeBlockers,
+    missingScenarios: readinessDetails.missingScenarios,
+    deterministic: readinessDetails.deterministic,
+    semantic: readinessDetails.semantic,
+    archiveReady: readinessDetails.archiveReady
+  };
+  const factCandidateTargets = getDurableReviewCandidateTargets();
+  let decisionRecordsPath;
+  try {
+    const configInspection = await inspectRspConfig();
+    if (configInspection.issues.length > 0)
+      exitShowError({ code: "invalid_config", message: configInspection.issues.join("; ") }, options);
+    decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+    const filesystemIssue = await validateDecisionRecordsFilesystemPath(decisionRecordsPath);
+    if (filesystemIssue)
+      exitShowError({ code: "invalid_decision_records_path", message: filesystemIssue }, options);
+  } catch (error) {
+    exitShowError({ code: "invalid_config", message: `.rsp/config.yaml could not be parsed: ${toErrorMessage(error)}` }, options);
+  }
+  const groupContextPaths = workRef.group ? [normalizeLogicalPath(resolveWorkRef(`${workRef.group}/brief`, { mustExist: true }).path)] : [];
+  const contextPaths = [...groupContextPaths, ...factCandidateTargets, decisionRecordsPath];
+  const durableReview = buildDurableReviewGuidance(factCandidateTargets, decisionRecordsPath);
+  const result = {
+    command: "show",
+    ok: true,
+    change: {
       name,
+      path: normalizeLogicalPath(srcPath),
       kind,
-      progress: { done, total },
-      ageDays,
       isFocused,
-      isBlocked,
-      path: fp ? normalizeLogicalPath(fp) : null
+      progress: { done: cb.done, total: cb.total },
+      blockers,
+      scenarioCount: scenarios.length,
+      readiness
+    },
+    contextPaths,
+    durableReview,
+    runtime
+  };
+  if (options.json) {
+    emitJson(result, options);
+    return result;
+  }
+  console.log();
+  console.log(`  ${pc.bold("Change:")} ${pc.cyan(name)}`);
+  console.log(`  ${pc.dim("Path:")} ${normalizeLogicalPath(srcPath)}`);
+  console.log(`  ${pc.dim("Kind:")} ${kind}`);
+  console.log(`  ${pc.dim("Focused:")} ${isFocused ? pc.green("yes") : pc.dim("no")}`);
+  console.log(`  ${pc.dim("Progress:")} ${cb.done}/${cb.total}`);
+  console.log(`  ${pc.dim("Blockers:")} ${blockers ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`  ${pc.dim("Scenarios:")} ${scenarios.length}`);
+  console.log();
+  console.log(`  ${pc.bold("Readiness:")}`);
+  console.log(`    ${pc.dim("Incomplete tasks:")} ${readiness.incompleteTasks > 0 ? pc.yellow(String(readiness.incompleteTasks)) : pc.green("0")}`);
+  console.log(`    ${pc.dim("Incomplete verify:")} ${readiness.incompleteVerify > 0 ? pc.yellow(String(readiness.incompleteVerify)) : pc.green("0")}`);
+  console.log(`    ${pc.dim("Active blockers:")} ${readiness.activeBlockers ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`    ${pc.dim("Missing scenarios:")} ${readiness.missingScenarios ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`    ${pc.dim("Deterministic:")} ${readiness.deterministic === "pass" ? pc.green("pass") : pc.yellow("warnings")}`);
+  console.log(`    ${pc.dim("Semantic review:")} ${pc.yellow("needed")}`);
+  console.log(`    ${pc.dim("Archive ready:")} ${formatArchiveReady2(readiness.archiveReady)}`);
+  console.log();
+  console.log(`  ${pc.bold("Context paths:")}`);
+  for (const cp of contextPaths)
+    console.log(`    ${pc.dim(cp)}`);
+  console.log();
+  console.log(`  ${pc.bold("Durable review:")}`);
+  console.log(`    ${pc.dim("Current-fact options:")} ${durableReview.factDecisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Rationale options:")} ${durableReview.rationaleDecisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Current-fact targets:")} ${durableReview.factCandidateTargets.join(", ")}`);
+  console.log(`    ${pc.dim("Decision Record path:")} ${durableReview.decisionRecordsPath}`);
+  console.log(`    ${pc.dim(durableReview.note)}`);
+  console.log();
+  return result;
+}
+function formatArchiveReady2(value) {
+  switch (value) {
+    case "yes":
+      return pc.green("yes");
+    case "no":
+      return pc.yellow("no");
+    case "judgment":
+      return pc.yellow("judgment");
+  }
+}
+
+// src/commands/skills.ts
+import { randomUUID } from "crypto";
+import { lstatSync } from "fs";
+import { chmod, copyFile, mkdir as mkdir9, readdir as readdir2, readFile as readFile11, rename as rename3, rm as rm2 } from "fs/promises";
+import { dirname as dirname4, join as join9, relative as relative4 } from "path";
+function unsupportedEntry(path, label) {
+  return new ManagedPathError(path, `unsupported entry in the ${label} tree: ${path}`);
+}
+function inspectDirectoryIdentity(path, label) {
+  const inspection = inspectManagedDirectory(path, label);
+  if (inspection.issue)
+    throw inspection.issue;
+  const stats = lstatSync(path);
+  return { path, dev: stats.dev, ino: stats.ino };
+}
+function assertDirectoryIdentities(identities, label) {
+  for (const identity of identities) {
+    const current = inspectDirectoryIdentity(identity.path, label);
+    if (current.dev !== identity.dev || current.ino !== identity.ino)
+      throw new ManagedPathError(identity.path, `${label} changed after validation: ${identity.path}`);
+  }
+}
+async function prepareTargetRoot(projectRoot, targetRoot) {
+  const projectIdentity = inspectDirectoryIdentity(projectRoot, "project Skills root");
+  const agentsRoot = join9(projectRoot, ".agents");
+  const identities = [projectIdentity];
+  assertDirectoryIdentities(identities, "project Skills root");
+  await mkdir9(agentsRoot).catch((error) => {
+    if (error.code !== "EEXIST")
+      throw error;
+  });
+  assertDirectoryIdentities(identities, "project Skills root");
+  identities.push(inspectDirectoryIdentity(agentsRoot, "project Skills root"));
+  assertDirectoryIdentities(identities, "project Skills root");
+  await mkdir9(targetRoot).catch((error) => {
+    if (error.code !== "EEXIST")
+      throw error;
+  });
+  assertDirectoryIdentities(identities, "project Skills root");
+  identities.push(inspectDirectoryIdentity(targetRoot, "project Skills root"));
+  return identities;
+}
+async function inspectPackagedSkills(packageRoot) {
+  const skillsRoot = join9(packageRoot, "skills");
+  const rootInspection = inspectManagedDirectory(skillsRoot, "packaged Skills root");
+  if (rootInspection.issue)
+    throw rootInspection.issue;
+  const entries = await readdir2(skillsRoot, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith("."))
+      continue;
+    const root = join9(skillsRoot, entry.name);
+    if (!entry.isDirectory())
+      throw unsupportedEntry(root, "packaged Skills");
+    const inspection = await inspectManagedFileTree(root, `packaged Skill ${entry.name}`);
+    if (inspection.issues.length > 0)
+      throw inspection.issues[0];
+    skills.push({
+      name: entry.name,
+      root,
+      files: inspection.files.map((path) => relative4(root, path))
     });
   }
-  const filteredRecords = records.filter((record) => {
-    if (options.focused && !record.isFocused)
+  return skills;
+}
+function inspectTarget(path, name) {
+  try {
+    const stats = lstatSync(path);
+    if (stats.isDirectory())
+      return "directory";
+    throw unsupportedEntry(path, `installed Skill ${name}`);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return "missing";
+    throw error;
+  }
+}
+async function treesEqual(source, targetRoot) {
+  const target = await inspectManagedFileTree(targetRoot, `installed Skill ${source.name}`);
+  if (target.issues.length > 0)
+    throw target.issues[0];
+  const targetFiles = target.files.map((path) => relative4(targetRoot, path));
+  if (source.files.length !== targetFiles.length || source.files.some((path, index) => path !== targetFiles[index]))
+    return false;
+  for (const path of source.files) {
+    const sourcePath = join9(source.root, path);
+    const targetPath = join9(targetRoot, path);
+    const [sourceStats, targetStats] = [lstatSync(sourcePath), lstatSync(targetPath)];
+    if (!sourceStats.isFile() || !targetStats.isFile())
+      throw unsupportedEntry(!sourceStats.isFile() ? sourcePath : targetPath, `Skill ${source.name}`);
+    if ((sourceStats.mode & 511) !== (targetStats.mode & 511))
       return false;
-    if (options.blocked && !record.isBlocked)
+    const [sourceContent, targetContent] = await Promise.all([readFile11(sourcePath), readFile11(targetPath)]);
+    if (!sourceContent.equals(targetContent))
       return false;
-    if (typeof options.stale === "number") {
-      const ageDays = Number(record.age);
-      if (!Number.isFinite(ageDays) || ageDays < options.stale)
-        return false;
+  }
+  return true;
+}
+async function copySkillTree(source, targetRoot) {
+  await mkdir9(targetRoot, { recursive: true });
+  for (const path of source.files) {
+    const sourcePath = join9(source.root, path);
+    const targetPath = join9(targetRoot, path);
+    const stats = lstatSync(sourcePath);
+    if (!stats.isFile())
+      throw unsupportedEntry(sourcePath, `packaged Skill ${source.name}`);
+    await mkdir9(dirname4(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+    await chmod(targetPath, stats.mode & 511);
+  }
+}
+async function installPackagedSkills(args = {}, options = {}) {
+  const packageRoot = options.packageRoot ?? PKG_ROOT;
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const renamePath = options.renamePath ?? rename3;
+  const skills = await inspectPackagedSkills(packageRoot);
+  const targetRoot = resolveManagedDirectoryChain(projectRoot, [".agents", "skills"], "project Skills root");
+  const result = { installed: [], unchanged: [], replaced: [] };
+  const conflicts = [];
+  const targetTreeIdentities = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    const target = join9(targetRoot, skill.name);
+    if (inspectTarget(target, skill.name) === "missing") {
+      result.installed.push(skill.name);
+      continue;
     }
-    return true;
-  });
-  const filteredOutputRecords = outputRecords.filter((record) => {
-    if (options.focused && !record.isFocused)
+    const targetIdentity = inspectDirectoryIdentity(target, `installed Skill ${skill.name}`);
+    if (await treesEqual(skill, target)) {
+      result.unchanged.push(skill.name);
+      continue;
+    }
+    assertDirectoryIdentities([targetIdentity], `installed Skill ${skill.name}`);
+    if (args.force) {
+      result.replaced.push(skill.name);
+      targetTreeIdentities.set(skill.name, targetIdentity);
+    } else {
+      conflicts.push(skill.name);
+    }
+  }
+  if (conflicts.length > 0)
+    throw new Error(`conflicting packaged Skills: ${conflicts.join(", ")}; rerun with --force to replace only these package-owned directories`);
+  if (args.dryRun)
+    return result;
+  await options.onMutationStep?.({ phase: "before-target-root-mutation", targetRoot });
+  const targetIdentities = await prepareTargetRoot(projectRoot, targetRoot);
+  const stagingRoot = join9(targetRoot, `.rsp-skills-install-${randomUUID()}`);
+  const nextRoot = join9(stagingRoot, "next");
+  const previousRoot = join9(stagingRoot, "previous");
+  const failedRoot = join9(stagingRoot, "failed");
+  const movedPrevious = [];
+  const activated = [];
+  let removeStaging = true;
+  try {
+    assertDirectoryIdentities(targetIdentities, "project Skills root");
+    await mkdir9(nextRoot, { recursive: true });
+    await mkdir9(previousRoot);
+    await mkdir9(failedRoot);
+    for (const skill of skills) {
+      if (result.unchanged.includes(skill.name))
+        continue;
+      await copySkillTree(skill, join9(nextRoot, skill.name));
+    }
+    for (const name of result.installed) {
+      const target = join9(targetRoot, name);
+      if (inspectTarget(target, name) !== "missing")
+        throw new ManagedPathError(target, `installed Skill changed after preflight: ${target}`);
+    }
+    for (const name of result.replaced) {
+      assertDirectoryIdentities([targetTreeIdentities.get(name)], `installed Skill ${name}`);
+    }
+    for (const name of result.replaced) {
+      assertDirectoryIdentities(targetIdentities, "project Skills root");
+      assertDirectoryIdentities([targetTreeIdentities.get(name)], `installed Skill ${name}`);
+      await renamePath(join9(targetRoot, name), join9(previousRoot, name));
+      movedPrevious.push(name);
+    }
+    for (const name of [...result.installed, ...result.replaced].sort()) {
+      const target = join9(targetRoot, name);
+      assertDirectoryIdentities(targetIdentities, "project Skills root");
+      await options.onMutationStep?.({ phase: "before-activate", name, target });
+      assertDirectoryIdentities(targetIdentities, "project Skills root");
+      if (inspectTarget(target, name) !== "missing")
+        throw new ManagedPathError(target, `installed Skill changed after preflight: ${target}`);
+      await renamePath(join9(nextRoot, name), target);
+      activated.push(name);
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const name of activated.reverse()) {
+      const target = join9(targetRoot, name);
+      try {
+        assertDirectoryIdentities(targetIdentities, "project Skills root");
+        if (inspectTarget(target, name) === "directory")
+          await renamePath(target, join9(failedRoot, name));
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError instanceof Error ? rollbackError.message : String(rollbackError));
+      }
+    }
+    for (const name of movedPrevious.reverse()) {
+      const target = join9(targetRoot, name);
+      const previous = join9(previousRoot, name);
+      try {
+        assertDirectoryIdentities(targetIdentities, "project Skills root");
+        await options.onMutationStep?.({ phase: "before-rollback-restore", name, target, previous });
+        assertDirectoryIdentities(targetIdentities, "project Skills root");
+        if (inspectTarget(target, name) !== "missing")
+          throw new ManagedPathError(target, `cannot restore installed Skill because the target is occupied: ${target}`);
+        await renamePath(previous, target);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError instanceof Error ? rollbackError.message : String(rollbackError));
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      removeStaging = false;
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`${message}; rollback incomplete; recover original Skills from ${previousRoot}; ${rollbackErrors.join("; ")}`);
+    }
+    throw error;
+  } finally {
+    if (removeStaging)
+      await rm2(stagingRoot, { recursive: true, force: true });
+  }
+  return result;
+}
+function printSkillInstallResult(result, dryRun = false) {
+  const prefix = dryRun ? "would be " : "";
+  for (const status of ["installed", "unchanged", "replaced"]) {
+    if (result[status].length > 0)
+      console.log(`  ${prefix}${status}: ${result[status].join(", ")}`);
+  }
+}
+
+// src/status/derive.ts
+function deriveStatusView(snapshot, options = {}) {
+  const query = {
+    focused: Boolean(options.focused),
+    blocked: Boolean(options.blocked),
+    stale: typeof options.stale === "number" ? options.stale : null
+  };
+  const records = snapshot.records.filter(({ output: record }) => {
+    if (query.focused && !record.isFocused)
       return false;
-    if (options.blocked && !record.isBlocked)
+    if (query.blocked && !record.isBlocked)
+      return false;
+    if (query.stale !== null && (record.ageDays === null || record.ageDays < query.stale))
       return false;
-    if (typeof options.stale === "number") {
-      if (record.ageDays === null || record.ageDays < options.stale)
-        return false;
-    }
     return true;
   });
-  const blockedCount = filteredOutputRecords.filter((r) => r.isBlocked).length;
-  const statusResult = {
-    command: "status",
-    ok: true,
-    filters: {
-      focused: Boolean(options.focused),
-      blocked: Boolean(options.blocked),
-      stale: typeof options.stale === "number" ? options.stale : null
-    },
-    focused: [...focusedSet].sort(),
-    records: filteredOutputRecords,
+  const filtered = query.focused || query.blocked || query.stale !== null;
+  const ok = snapshot.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+  const nextActions = ok ? buildStatusNextActions(snapshot.focused.length, snapshot.records.map((record) => record.output), snapshot.groups, filtered) : ["Run: rsp doctor"];
+  return {
+    query,
+    focused: snapshot.focused,
+    records,
+    groups: snapshot.groups,
+    plan: filterDependencyPlan(snapshot.plan, new Set(records.map((record) => record.output.name))),
     summary: {
-      total: filteredOutputRecords.length,
-      focused: filteredOutputRecords.filter((r) => r.isFocused).length,
-      blocked: blockedCount
+      total: records.length,
+      focused: records.filter((record) => record.output.isFocused).length,
+      blocked: records.filter((record) => record.output.isBlocked).length
     },
-    archiveTrend: await readArchiveTrend(runtime, runOptions),
-    runtime
+    nextActions,
+    archiveTrend: snapshot.archiveTrend,
+    diagnostics: snapshot.diagnostics,
+    runtime: snapshot.runtime,
+    hasExecutableChanges: snapshot.records.length > 0,
+    ok
   };
-  if (runOptions.json) {
-    emitJson(statusResult);
-    return statusResult;
+}
+function buildStatusNextActions(focusedCount, records, groups, filtered) {
+  const openChanges = records.map((record) => record.name).sort();
+  if (focusedCount > 0)
+    return [];
+  const readyGroup = groups.find((group) => group.readyToClose);
+  if (readyGroup)
+    return [`Run: rsp group close ${readyGroup.name}`];
+  if (openChanges.length === 0 && groups.length > 0)
+    return [`Review Group Brief: ${groups[0].path}`];
+  if (openChanges.length === 0)
+    return ["Run: rsp create <name>"];
+  if (filtered) {
+    return [
+      "Run: rsp status",
+      "Run: rsp focus <name>",
+      "Or run: rsp create <name>"
+    ];
   }
+  const firstChanges = openChanges.slice(0, 3).join(", ");
+  const extra = openChanges.length > 3 ? ` (+${openChanges.length - 3} more)` : "";
+  const recommendation = recommendOpenChange(records, groups);
+  return [
+    `Open changes: ${firstChanges}${extra}`,
+    recommendation ? `Run: rsp focus ${recommendation}` : "Resolve blockers before focusing an open change.",
+    "Or run: rsp create <name>"
+  ];
+}
+function recommendOpenChange(records, groups) {
+  const recordsByName = new Map(records.map((record) => [record.name, record]));
+  const candidates = records.filter((record) => !record.name.includes("/") && !record.isBlocked).map((record) => ({ name: record.name, owner: record.name }));
+  for (const group of groups) {
+    if (group.blockers)
+      continue;
+    const slice = group.slices.find((candidate) => {
+      const record = recordsByName.get(candidate.name);
+      return candidate.state === "open" && record !== void 0 && !record.isBlocked;
+    });
+    if (slice)
+      candidates.push({ name: slice.name, owner: group.name });
+  }
+  return candidates.sort((left, right) => left.owner.localeCompare(right.owner) || left.name.localeCompare(right.name))[0]?.name ?? null;
+}
+function filterDependencyPlan(plan, names) {
+  const included = new Set(names);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of plan.edges) {
+      if (included.has(edge.change) && !included.has(edge.requires)) {
+        included.add(edge.requires);
+        changed = true;
+      }
+    }
+  }
+  const waves = plan.waves.map((wave) => wave.filter((name) => included.has(name))).filter((wave) => wave.length > 0);
+  return {
+    nodes: plan.nodes.filter((node) => included.has(node.name)).map((node) => ({ ...node, selection: names.has(node.name) ? "selected" : "prerequisite" })),
+    ready: waves[0] ?? [],
+    edges: plan.edges.filter((edge) => included.has(edge.change)),
+    blocked: plan.blocked.filter((blocker) => included.has(blocker.change)),
+    waves
+  };
+}
+
+// src/status/plain.ts
+var COL_CHANGE = 32;
+var COL_KIND = 10;
+var COL_AGE = 7;
+var COL_PROGRESS = 10;
+function printStatusRuntimeDiagnostics(runtime) {
+  for (const diagnostic of runtime)
+    console.error(`  ${pc.dim(`[verbose] ${diagnostic.operation} ${diagnostic.path}: ${diagnostic.message}`)}`);
+}
+function printStatusPlain(view) {
   console.log();
   console.log(`  ${pc.bold("RSP status")}`);
   console.log();
-  if (focusedSet.size > 0) {
-    console.log(`  ${pc.cyan("Focused:")} ${[...focusedSet].join(", ")}`);
+  for (const diagnostic of view.diagnostics) {
+    const label = diagnostic.change ?? diagnostic.path;
+    console.log(`  ${pc.red("\u2717")} ${label ? `${label} \u2014 ` : ""}${diagnostic.message}`);
+  }
+  if (view.diagnostics.length > 0)
+    console.log();
+  if (view.focused.length > 0) {
+    console.log(`  ${pc.cyan("Focused:")} ${view.focused.join(", ")}`);
     console.log();
   } else {
-    console.log(`  ${pc.dim("No focused change.")} Run: rsp create <name> or rsp focus <name>`);
+    console.log(`  ${pc.dim("No focused change.")}`);
+    for (const action of view.nextActions)
+      console.log(`    ${pc.dim(action)}`);
     console.log();
   }
-  if (allNames.length === 0) {
-    console.log(`  ${pc.dim("No changes found.")} Run: rsp create <name>
+  printChangeGroups(view.groups);
+  printDependencyPlan(view.plan, view.records);
+  if (!view.hasExecutableChanges) {
+    if (view.ok)
+      console.log(`  ${pc.dim("No executable changes found.")} ${view.groups.length === 0 ? "Run: rsp create <name>" : "Review the Change Group guidance above."}
+`);
+    else
+      console.log(`  ${pc.dim("No executable changes can be shown until the work-tree issues are resolved.")}
 `);
-    return statusResult;
+    return;
   }
-  if (filteredRecords.length === 0) {
+  if (view.records.length === 0) {
     console.log(`  ${pc.dim("No changes match the current filters.")}
 `);
-    return statusResult;
-  }
-  const pad = (s, w) => s.padEnd(w);
-  console.log(`  ${pad("Change", COL_CHANGE)} ${pad("Kind", COL_KIND)} ${pad("Age(d)", COL_AGE)} ${pad("Progress", COL_PROGRESS)}`);
-  console.log(`  ${"\u2500".repeat(COL_CHANGE)} ${"\u2500".repeat(COL_KIND)} ${"\u2500".repeat(COL_AGE)} ${"\u2500".repeat(COL_PROGRESS)}`);
-  for (const r of filteredRecords) {
-    const marker = r.isFocused ? pc.cyan("*") : " ";
-    const namePadded = r.name.padEnd(COL_CHANGE - 1);
-    const kindPadded = r.kind.padEnd(COL_KIND);
-    const agePadded = r.age.padEnd(COL_AGE);
-    const progressPadded = r.progress.padEnd(COL_PROGRESS);
-    const nameDisplay = r.isBlocked ? pc.yellow(namePadded) : namePadded;
-    const ageDisplay = r.isFocused ? pc.cyan(agePadded) : agePadded;
-    console.log(`  ${marker}${nameDisplay} ${kindPadded} ${ageDisplay} ${progressPadded}`);
+    return;
+  }
+  if ((process.stdout.columns ?? 100) < 88 || view.records.some((record) => record.output.name.length >= COL_CHANGE)) {
+    for (const { output: record, progressKnown } of view.records) {
+      const state = [record.isFocused ? "focused" : "open", record.isBlocked ? "blocked" : null].filter(Boolean).join(" \xB7 ");
+      console.log(`  ${pc.bold("Change:")} ${record.isBlocked ? pc.yellow(record.name) : record.name}`);
+      console.log(`    ${state} \xB7 ${record.kind} \xB7 age ${record.ageDays ?? "\u2014"}d \xB7 progress ${progressKnown ? `${record.progress.done}/${record.progress.total}` : "\u2014"}`);
+    }
+  } else {
+    const pad = (value, width) => value.padEnd(width);
+    console.log(`  ${pad("Change", COL_CHANGE)} ${pad("Kind", COL_KIND)} ${pad("Age(d)", COL_AGE)} ${pad("Progress", COL_PROGRESS)}`);
+    console.log(`  ${"\u2500".repeat(COL_CHANGE)} ${"\u2500".repeat(COL_KIND)} ${"\u2500".repeat(COL_AGE)} ${"\u2500".repeat(COL_PROGRESS)}`);
+    for (const { output: record, progressKnown } of view.records) {
+      const marker = record.isFocused ? pc.cyan("*") : " ";
+      const namePadded = record.name.padEnd(COL_CHANGE - 1);
+      const kindPadded = record.kind.padEnd(COL_KIND);
+      const agePadded = (record.ageDays === null ? "\u2014" : String(record.ageDays)).padEnd(COL_AGE);
+      const progressPadded = (progressKnown ? `${record.progress.done}/${record.progress.total}` : "\u2014").padEnd(COL_PROGRESS);
+      const nameDisplay = record.isBlocked ? pc.yellow(namePadded) : namePadded;
+      const ageDisplay = record.isFocused ? pc.cyan(agePadded) : agePadded;
+      console.log(`  ${marker}${nameDisplay} ${kindPadded} ${ageDisplay} ${progressPadded}`);
+    }
   }
   console.log();
-  console.log(`  ${pc.bold("Summary:")} ${statusResult.summary.total} change(s), ${statusResult.summary.focused} focused, ${pc.yellow(String(statusResult.summary.blocked))} blocked`);
+  console.log(`  ${pc.bold("Summary:")} ${view.summary.total} change(s), ${view.summary.focused} focused, ${pc.yellow(String(view.summary.blocked))} blocked`);
   console.log();
-  printArchiveTrend(statusResult.archiveTrend);
-  if (statusResult.summary.blocked > 0) {
-    const blocked = filteredRecords.filter((r) => r.isBlocked);
-    console.log(`  ${pc.yellow("Blocked:")} ${blocked.map((r) => r.name).join(", ")}`);
-    console.log();
-  }
-  return statusResult;
+  printArchiveTrend(view.archiveTrend);
 }
-async function readArchiveTrend(runtime, runOptions) {
-  const indexPath = join13(ARCHIVES_DIR, "INDEX.md");
-  if (!existsSync13(indexPath))
-    return [];
-  try {
-    const content = await readFile10(indexPath, "utf-8");
-    const dateRe = /^\| (\d{4}-\d{2})-\d{2} \|/gm;
-    const counts = {};
-    let match;
-    while ((match = dateRe.exec(content)) !== null) {
-      const month = match[1];
-      counts[month] = (counts[month] || 0) + 1;
-    }
-    const months = Object.keys(counts).sort();
-    if (months.length === 0)
-      return [];
-    return months.map((month) => ({ month, count: counts[month] }));
-  } catch (error) {
-    recordRuntimeDiagnostic(runtime, {
-      code: "archive_index_read_failed",
-      operation: "readFile",
-      path: indexPath,
-      message: toErrorMessage(error)
-    }, Boolean(runOptions.verbose) && !runOptions.json);
-    return [];
+function printChangeGroups(groups) {
+  if (groups.length === 0)
+    return;
+  console.log(`  ${pc.bold("Change Groups")}`);
+  for (const group of groups) {
+    const archived = group.slices.filter((slice) => slice.state === "archived").length;
+    const readiness = group.readyToClose ? pc.green("ready to close") : pc.dim("not ready");
+    const blocked = group.blockers ? ` ${pc.yellow("blocked")}` : "";
+    console.log(`  ${group.name}: ${archived}/${group.slices.length} archived, completion ${group.completion.done}/${group.completion.total}, ${readiness}${blocked}`);
   }
+  console.log();
+}
+function printDependencyPlan(plan, records) {
+  console.log(`  ${pc.bold("Dependency graph")}`);
+  console.log(`  ${pc.dim("(parent requires children)")}`);
+  const roots = projectDependencyForest(plan);
+  const detailColumn = Math.max(40, ...plan.nodes.map((node) => node.name.length + 8));
+  const renderNode = (node, prefix, last) => {
+    const connector = last === null ? "" : last ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const symbol = node.selection === "selected" ? "\u25CE" : node.state === "ready" ? "\u25CF" : node.state === "archived" ? "\u2713" : node.state === "missing" || node.state === "blocked" ? "!" : "\u25CB";
+    const identity = `${prefix}${connector}${symbol} ${node.name}`.padEnd(detailColumn);
+    const record = records.find((candidate) => candidate.output.name === node.name);
+    const ownership = node.selection === "prerequisite" ? "prerequisite" : record?.output.isFocused ? "focused" : "open";
+    const state = node.state === "archived" ? "resolved" : node.state;
+    console.log(`  ${identity} ${ownership} \xB7 ${state}${node.shared ? " \xB7 \u21A9 shared" : ""}${node.reason ? ` \u2014 ${node.reason}` : ""}`);
+    const childPrefix = prefix + (last === null ? "" : last ? "    " : "\u2502   ");
+    for (const [index, child] of node.children.entries())
+      renderNode(child, childPrefix, index === node.children.length - 1);
+  };
+  if (roots.length === 0)
+    console.log(`  ${pc.dim("none")}`);
+  else
+    roots.forEach((node) => renderNode(node, "", null));
+  const external = plan.blocked.filter((blocker) => blocker.external).map((blocker) => blocker.change);
+  if (external.length > 0)
+    console.log(`  ${pc.dim("External blockers:")} ${external.join(", ")}`);
+  const implementationReady = plan.ready.filter((name) => {
+    const record = records.find((candidate) => candidate.output.name === name);
+    return !record || record.readiness.incompleteTasks > 0 || record.readiness.incompleteVerify > 0;
+  });
+  const completedReady = plan.ready.filter((name) => !implementationReady.includes(name));
+  const next = implementationReady.length > 0 ? implementationReady.join(", ") : completedReady.length > 0 ? `review for durable update/archive: ${completedReady.join(", ")}` : pc.dim("none");
+  console.log(`  ${pc.dim("Next action:")} ${next}`);
+  console.log(`  ${pc.dim("Legend:")} \u25CE focused/open  \u25CF ready  \u25CB waiting  \u2713 resolved prerequisite  ! blocked`);
+  console.log();
 }
 function printArchiveTrend(trend) {
   if (trend.length === 0)
@@ -1879,54 +2808,102 @@ function printArchiveTrend(trend) {
   console.log();
 }
 
-// src/commands/update.ts
-import { existsSync as existsSync14 } from "fs";
-import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
-import { join as join14 } from "path";
-var SKILL_REFRESH_HINT = "  Note: if you use the published RSP skill, refresh it too:\n    npx skills add oevery/rsp\n";
-async function updateProject() {
-  if (!existsSync14(RSP_DIR)) {
-    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
-    console.error(`  ${pc.dim("Run: rsp init")}`);
-    process.exit(1);
-  }
-  return withRspLock("update", async () => {
-    let updated = false;
-    const bundledRules = await readFile11(join14(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
-    const rulesPath = join14(RSP_DIR, "rules", "rsp-rules.md");
-    await mkdir8(join14(RSP_DIR, "rules"), { recursive: true });
-    const existingRules = existsSync14(rulesPath) ? await readFile11(rulesPath, "utf-8") : null;
-    if (existingRules !== bundledRules) {
-      await writeFile9(rulesPath, bundledRules);
-      console.log(`  ${pc.green("\u2713")} rules/rsp-rules.md updated`);
-      updated = true;
-    }
-    const agentsPath = "AGENTS.md";
-    const projectName = await detectProjectName();
-    const baseAgents = existsSync14(agentsPath) ? await readFile11(agentsPath, "utf-8") : `# ${projectName}
+// src/status/v3-json.ts
+function toStatusJson(view) {
+  return {
+    command: "status",
+    ok: view.ok,
+    filters: view.query,
+    focused: view.focused,
+    records: view.records.map((record) => record.output),
+    groups: view.groups,
+    plan: view.plan,
+    summary: view.summary,
+    nextActions: view.nextActions,
+    archiveTrend: view.archiveTrend,
+    diagnostics: view.diagnostics,
+    runtime: view.runtime
+  };
+}
+function toStatusJsonError(error, options) {
+  return {
+    command: "status",
+    ok: false,
+    filters: {
+      focused: options.focused,
+      blocked: options.blocked,
+      stale: null
+    },
+    focused: [],
+    records: [],
+    groups: [],
+    plan: {
+      nodes: [],
+      ready: [],
+      edges: [],
+      blocked: [],
+      waves: []
+    },
+    summary: {
+      total: 0,
+      focused: 0,
+      blocked: 0
+    },
+    archiveTrend: [],
+    nextActions: [],
+    diagnostics: [],
+    runtime: [],
+    error
+  };
+}
 
-`;
-    const nextAgents = upsertRspAgentsBlock(baseAgents);
-    if (!existsSync14(agentsPath) || nextAgents.changed) {
-      await writeFile9(agentsPath, nextAgents.content);
-      console.log(`  ${pc.green("\u2713")} AGENTS.md managed block refreshed`);
-      updated = true;
-    }
-    await buildSpecsIndex({ acquireLock: false });
-    await buildArchiveIndex({ acquireLock: false });
-    if (!updated) {
-      console.log(`  ${pc.dim("Already up to date.")}
-`);
-      console.log(SKILL_REFRESH_HINT);
-    } else {
-      console.log(`  ${pc.green("Update complete.")}
-`);
-      console.log(SKILL_REFRESH_HINT);
-    }
-  });
+// src/commands/status.ts
+async function showStatus(options = {}, runOptions = {}) {
+  const snapshot = await inspectProjectStatus();
+  if (runOptions.verbose && !runOptions.json)
+    printStatusRuntimeDiagnostics(snapshot.runtime);
+  const view = deriveStatusView(snapshot, options);
+  const result = toStatusJson(view);
+  if (runOptions.json)
+    emitJson(result, runOptions);
+  else
+    printStatusPlain(view);
+  return result;
+}
+
+// src/tui/route.ts
+function isInteractiveTerminal(environment) {
+  return environment.stdinTty && environment.stdoutTty && environment.term !== "dumb";
+}
+function shouldAutoLaunchUi(args, environment) {
+  return args.length === 0 && isInteractiveTerminal(environment) && (environment.ci === void 0 || environment.ci === "false");
+}
+function validateUiArgs(args) {
+  let lang = "auto";
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument !== "--lang")
+      throw new Error(`Unknown rsp ui option: ${argument}`);
+    const value = args[index + 1];
+    if (value !== "auto" && value !== "en" && value !== "zh-CN")
+      throw new Error("--lang must be auto, en, or zh-CN");
+    lang = value;
+    index += 1;
+  }
+  return { lang };
 }
 
 // src/cli.ts
+var COMPACT_JSON_COMMANDS = /* @__PURE__ */ new Set(["status", "show", "ready", "check", "doctor", "history"]);
+function validateCompactInvocation(rawArgs) {
+  if (!rawArgs.includes("--compact"))
+    return;
+  const command = rawArgs[0];
+  if (!command || !COMPACT_JSON_COMMANDS.has(command))
+    throw new Error(`--compact is unsupported for rsp${command ? ` ${command}` : ""}`);
+  if (!rawArgs.includes("--json"))
+    throw new Error("--compact requires --json");
+}
 var initCommand = defineCommand({
   meta: {
     name: "init",
@@ -1938,11 +2915,6 @@ var initCommand = defineCommand({
       description: "How to handle AGENTS.md output: managed or print",
       default: "managed"
     },
-    "with-project-rules": {
-      type: "boolean",
-      description: "Create .rsp/rules/project-rules.md",
-      default: false
-    },
     "with-project-setup": {
       type: "boolean",
       description: "Create .rsp/changes/project-setup.md and focus it",
@@ -1952,7 +2924,6 @@ var initCommand = defineCommand({
   async run({ args }) {
     await initProject({
       agentsMode: args["agents-mode"] === "print" ? "print" : "managed",
-      withProjectRules: Boolean(args["with-project-rules"]),
       withProjectSetup: Boolean(args["with-project-setup"])
     });
   }
@@ -1971,27 +2942,58 @@ var createCommand = defineCommand({
     kind: {
       type: "string",
       description: "Optional kind for a kind-aware template (feature, fix, refactor, docs, ops, research)"
+    },
+    lite: {
+      type: "boolean",
+      description: "Use a shorter change template while keeping the required RSP sections",
+      default: false
     }
   },
   async run({ args }) {
     const summary = Array.isArray(args._) && args._.length > 1 ? args._.slice(1).join(" ") : "";
-    await createChange(args.name, summary, args.kind);
+    await createChange(args.name, summary, args.kind, { lite: Boolean(args.lite) });
   }
 });
-var addRulesCommand = defineCommand({
+var groupCreateCommand = defineCommand({
   meta: {
-    name: "rules",
-    description: "Create .rsp/rules/<name>.md"
+    name: "create",
+    description: "Create an unfocused .rsp/changes/<group>/00-brief.md"
   },
   args: {
     name: {
       type: "positional",
-      description: "Rules file name",
+      description: "Change Group name",
       required: true
     }
   },
   async run({ args }) {
-    await addRules(args.name);
+    const goal = Array.isArray(args._) && args._.length > 1 ? args._.slice(1).join(" ") : "";
+    await createChangeGroup(args.name, goal);
+  }
+});
+var groupCommand = defineCommand({
+  meta: {
+    name: "group",
+    description: "Create and close shallow Change Groups"
+  },
+  subCommands: {
+    create: groupCreateCommand,
+    close: defineCommand({
+      meta: {
+        name: "close",
+        description: "Archive a completed Group Brief after all child Changes are archived"
+      },
+      args: {
+        name: {
+          type: "positional",
+          description: "Change Group name",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await closeChangeGroup(args.name);
+      }
+    })
   }
 });
 var addSpecCommand = defineCommand({
@@ -2013,10 +3015,9 @@ var addSpecCommand = defineCommand({
 var addCommand = defineCommand({
   meta: {
     name: "add",
-    description: "Add optional rules or spec files"
+    description: "Add an optional durable spec file"
   },
   subCommands: {
-    rules: addRulesCommand,
     spec: addSpecCommand
   }
 });
@@ -2026,14 +3027,19 @@ var archiveCommand = defineCommand({
     description: "Archive an open change into .rsp/archives/"
   },
   args: {
-    name: {
+    "name": {
       type: "positional",
       description: "Change name",
       required: true
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Preview archive readiness without moving the change",
+      default: false
     }
   },
   async run({ args }) {
-    await archiveChange(args.name);
+    await archiveChange(args.name, { dryRun: Boolean(args["dry-run"]) });
   }
 });
 var focusCommand = defineCommand({
@@ -2093,6 +3099,11 @@ var statusCommand = defineCommand({
       description: "Print machine-readable JSON output",
       default: false
     },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    },
     verbose: {
       type: "boolean",
       description: "Print runtime diagnostics for suppressed I/O issues",
@@ -2101,41 +3112,54 @@ var statusCommand = defineCommand({
   },
   async run({ args }) {
     const stale = args.stale === void 0 ? void 0 : Number(args.stale);
-    if (args.stale !== void 0 && (Number.isFinite(stale) === false || Number.isInteger(stale) === false || stale < 0)) {
+    if (stale !== void 0 && (Number.isFinite(stale) === false || Number.isInteger(stale) === false || stale < 0)) {
       if (args.json) {
-        emitStatusJsonError({
+        emitJson(toStatusJsonError({
           code: "invalid_stale_filter",
           message: "--stale must be a non-negative integer number of days"
         }, {
           focused: Boolean(args.focused),
           blocked: Boolean(args.blocked)
-        });
+        }), { compact: Boolean(args.compact) });
       } else {
         console.error(`  Error: --stale must be a non-negative integer number of days`);
       }
       process.exit(1);
     }
-    await showStatus({
+    const result = await showStatus({
       focused: Boolean(args.focused),
       blocked: Boolean(args.blocked),
       stale
     }, {
       json: Boolean(args.json),
+      compact: Boolean(args.compact),
       verbose: Boolean(args.verbose)
     });
+    if (!result.ok)
+      process.exit(1);
   }
 });
 var checkCommand = defineCommand({
   meta: {
     name: "check",
-    description: "Validate changes (frontmatter, sections, deltas, scenarios)"
+    description: "Validate changes (frontmatter, sections, template text, deltas, scenarios)"
   },
   args: {
+    focused: {
+      type: "boolean",
+      description: "Only validate currently focused changes",
+      default: false
+    },
     json: {
       type: "boolean",
       description: "Print machine-readable JSON output",
       default: false
     },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    },
     verbose: {
       type: "boolean",
       description: "Print runtime diagnostics for suppressed I/O issues",
@@ -2143,7 +3167,12 @@ var checkCommand = defineCommand({
     }
   },
   async run({ args }) {
-    const result = await runCheck({ json: Boolean(args.json), verbose: Boolean(args.verbose) });
+    const result = await runCheck({
+      focused: Boolean(args.focused),
+      json: Boolean(args.json),
+      compact: Boolean(args.compact),
+      verbose: Boolean(args.verbose)
+    });
     if (!result.ok)
       process.exit(1);
   }
@@ -2151,10 +3180,46 @@ var checkCommand = defineCommand({
 var updateCommand = defineCommand({
   meta: {
     name: "update",
-    description: "Refresh RSP project structure after upgrade (rules, AGENTS, indices)"
+    description: "Refresh RSP project structure after upgrade (fallback protocol, AGENTS, indices)"
   },
   async run() {
-    await updateProject();
+    const result = await updateProject();
+    if (!result.migration.inspectionComplete)
+      process.exit(1);
+  }
+});
+var skillsInstallCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Install this package's bundled Skills into .agents/skills"
+  },
+  args: {
+    "dry-run": {
+      type: "boolean",
+      description: "Preflight all packaged Skills without changing files",
+      default: false
+    },
+    "force": {
+      type: "boolean",
+      description: "Replace divergent package-owned Skill directories",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const result = await installPackagedSkills({
+      dryRun: Boolean(args["dry-run"]),
+      force: Boolean(args.force)
+    });
+    printSkillInstallResult(result, Boolean(args["dry-run"]));
+  }
+});
+var skillsCommand = defineCommand({
+  meta: {
+    name: "skills",
+    description: "Manage package-bundled project Skills"
+  },
+  subCommands: {
+    install: skillsInstallCommand
   }
 });
 var doctorCommand = defineCommand({
@@ -2168,49 +3233,220 @@ var doctorCommand = defineCommand({
       description: "Print machine-readable JSON output",
       default: false
     },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    },
     verbose: {
       type: "boolean",
       description: "Print runtime diagnostics for suppressed I/O issues",
       default: false
+    },
+    fix: {
+      type: "boolean",
+      description: "Run safe deterministic repairs before reporting diagnostics",
+      default: false
     }
   },
   async run({ args }) {
-    const result = await runDoctor({ json: Boolean(args.json), verbose: Boolean(args.verbose) });
+    const result = await runDoctor({ json: Boolean(args.json), compact: Boolean(args.compact), verbose: Boolean(args.verbose), fix: Boolean(args.fix) });
     if (!result.ok)
       process.exit(1);
   }
 });
+var readyCommand = defineCommand({
+  meta: {
+    name: "ready",
+    description: "Preview archive readiness for a change without moving it"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Change name",
+      required: true
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON output",
+      default: false
+    },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    },
+    verbose: {
+      type: "boolean",
+      description: "Print runtime diagnostics for suppressed I/O issues",
+      default: false
+    }
+  },
+  async run({ args }) {
+    await showReady(args.name, { json: Boolean(args.json), compact: Boolean(args.compact), verbose: Boolean(args.verbose) });
+  }
+});
+var showCommand = defineCommand({
+  meta: {
+    name: "show",
+    description: "Show change context with readiness signals and relevant paths"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Change name (use --focused instead to show the currently focused change)",
+      required: false
+    },
+    focused: {
+      type: "boolean",
+      description: "Show the currently focused change",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON output",
+      default: false
+    },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    },
+    verbose: {
+      type: "boolean",
+      description: "Print runtime diagnostics for suppressed I/O issues",
+      default: false
+    }
+  },
+  async run({ args }) {
+    await showChange(args.name, {
+      focused: Boolean(args.focused),
+      json: Boolean(args.json),
+      compact: Boolean(args.compact),
+      verbose: Boolean(args.verbose)
+    });
+  }
+});
+var historyCommand = defineCommand({
+  meta: {
+    name: "history",
+    description: "Query bounded archived Change summaries or one exact archived WorkRef"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Optional exact archived Change WorkRef for detail",
+      required: false
+    },
+    limit: {
+      type: "string",
+      description: "Maximum list records from 1 through 100 (default: 20)"
+    },
+    since: {
+      type: "string",
+      description: "Include archives on or after YYYY-MM-DD"
+    },
+    until: {
+      type: "string",
+      description: "Include archives on or before YYYY-MM-DD"
+    },
+    kind: {
+      type: "string",
+      description: "Match one exact historical Change kind"
+    },
+    group: {
+      type: "string",
+      description: "Match one exact Change Group"
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON output",
+      default: false
+    },
+    compact: {
+      type: "boolean",
+      description: "Print JSON without indentation (requires --json)",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const result = await showHistory({
+      workRef: args.name,
+      limit: args.limit,
+      since: args.since,
+      until: args.until,
+      kind: args.kind,
+      group: args.group,
+      positionalCount: args._?.length ?? (args.name ? 1 : 0)
+    }, { json: Boolean(args.json), compact: Boolean(args.compact) });
+    if (!result.ok)
+      process.exitCode = 1;
+  }
+});
 async function runCli(rawArgs = process.argv.slice(2)) {
+  const terminalEnvironment = {
+    stdinTty: Boolean(process.stdin.isTTY),
+    stdoutTty: Boolean(process.stdout.isTTY),
+    term: process.env.TERM,
+    ci: process.env.CI
+  };
+  const explicitUi = rawArgs[0] === "ui";
+  if (explicitUi || shouldAutoLaunchUi(rawArgs, terminalEnvironment)) {
+    const { lang } = validateUiArgs(explicitUi ? rawArgs.slice(1) : []);
+    if (!isInteractiveTerminal(terminalEnvironment)) {
+      if (explicitUi)
+        throw new Error("rsp ui requires an interactive terminal; use rsp status or rsp status --json instead");
+    } else {
+      const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
+      const locale = resolveUiLocale(lang, process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? Intl.DateTimeFormat().resolvedOptions().locale);
+      const { runTui } = await import("./entry-LAPR3TNI.mjs");
+      const exitCode = await runTui(locale);
+      if (exitCode !== 0)
+        process.exitCode = exitCode;
+      return;
+    }
+  }
+  validateCompactInvocation(rawArgs);
   const version = await getVersion();
   const main = defineCommand({
     meta: {
       name: "rsp",
       version,
-      description: "RSP (Rules, Specs, Plans) workflow for lightweight AI-assisted change management"
+      description: "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents"
     },
     subCommands: {
       init: initCommand,
       add: addCommand,
       create: createCommand,
+      group: groupCommand,
       focus: focusCommand,
       unfocus: unfocusCommand,
       archive: archiveCommand,
+      ready: readyCommand,
+      show: showCommand,
+      history: historyCommand,
       status: statusCommand,
       check: checkCommand,
       update: updateCommand,
-      doctor: doctorCommand
+      doctor: doctorCommand,
+      skills: skillsCommand
     }
   });
   await runMain(main, { rawArgs });
 }
-var isMain = process.argv[1] && fileURLToPath2(import.meta.url) === resolve(process.argv[1]);
-if (isMain) {
-  runCli().catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
+async function runCliMain(rawArgs = process.argv.slice(2)) {
+  try {
+    await runCli(rawArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     console.error(`  Error: ${message}`);
-    process.exit(1);
-  });
+    process.exitCode = 1;
+  }
 }
+var isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isMain)
+  await runCliMain();
 export {
-  runCli
+  runCli,
+  runCliMain
 };