@oevery/rsp 3.1.0-beta.2 → 3.1.0-beta.4

package/dist/cli.mjs

@@ -4,7 +4,7 @@ import {
   installPackagedSkills,
   printPackagedSkillInventory,
   printSkillInstallResult
-} from "./chunk-4K53353L.mjs";
+} from "./chunk-D7XDXBFO.mjs";
 import {
   ArchiveHistoryError,
   GROUP_BRIEF_FILENAME,
@@ -21,6 +21,8 @@ import {
   inspectFocusTree,
   inspectProjectStatus,
   inspectWorkTree,
+  normalizeExecutableWorkRef,
+  normalizeWorkRefSegment,
   projectDependencyForest,
   queryArchiveHistory,
   readArchiveHistoryDetail,
@@ -29,12 +31,14 @@ import {
   resolveFocusMarkerPath,
   resolveWorkRef,
   selectArchiveHistoryRecord
-} from "./chunk-EALHA3ZS.mjs";
+} from "./chunk-FI3SYHVH.mjs";
 import {
   ARCHIVES_DIR,
   CHANGES_DIR,
+  CHANGE_DOCUMENT_SCHEMA,
   CONFIG_PATH,
   DEFAULT_DECISION_RECORDS_PATH,
+  DocumentSectionCardinalityError,
   FOCUS_DIR,
   LOCK_PATH,
   OBSOLETE_RSP_RULES_PATH,
@@ -42,6 +46,7 @@ import {
   RSP_DIR,
   RSP_RULES_PATH,
   VALID_KINDS,
+  appendDocumentSectionItem,
   buildDurableReviewGuidance,
   cleanupEmptyParentDirs,
   clearConfigCache,
@@ -53,10 +58,11 @@ import {
   emitJson,
   ensureDecisionRecordsDirectory,
   ensureManagedFile,
-  extractSection,
   generateChangeContent,
   generateDesignContent,
   generateSpecContent,
+  getDocumentSectionDefinitionByHeading,
+  getDocumentSections,
   getDurableReviewCandidateTargets,
   getVersion,
   guardRspInitialized,
@@ -71,6 +77,7 @@ import {
   loadRspConfig,
   normalizeLogicalPath,
   parseFrontmatter,
+  parseRspDocument,
   parseScenarios,
   pc,
   recordRuntimeDiagnostic,
@@ -84,7 +91,7 @@ import {
   validateDecisionRecordsFilesystemPath,
   walkMarkdownFiles,
   writeManagedFile
-} from "./chunk-OTJFL6XH.mjs";
+} from "./chunk-FJVH7ZYU.mjs";
 
 // src/cli.ts
 import { resolve } from "path";
@@ -92,7 +99,7 @@ import { fileURLToPath } from "url";
 import { defineCommand, runMain } from "citty";
 
 // src/commands/add-spec.ts
-import { mkdir as mkdir2, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir2, unlink as unlink3, writeFile as writeFile2 } from "fs/promises";
 import { join as join2 } from "path";
 
 // src/core/lock.ts
@@ -157,12 +164,51 @@ ${(/* @__PURE__ */ new Date()).toISOString()}`, { flag: "wx" });
 }
 
 // src/commands/specs-index.ts
-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 } = {}) {
+import { readFile as readFile2, unlink as unlink2 } from "fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "path";
+var SPECS_INDEX_FILENAME = "00-index.md";
+var LEGACY_SPECS_INDEX_FILENAME = "INDEX.md";
+async function buildSpecsIndex(options = {}) {
+  const { acquireLock = true, quiet = false, affectedDirectory } = options;
   if (acquireLock)
-    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false, quiet }));
+    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false, quiet, affectedDirectory }));
+  const plan = await planSpecsIndexes(affectedDirectory);
+  for (const write of plan.writes)
+    await writeManagedFile(write.path, write.content, "Specs index");
+  for (const path of plan.removals)
+    await unlink2(path);
+  const changed = plan.writes.length > 0 || plan.removals.length > 0;
+  if (!quiet) {
+    if (changed)
+      console.log(`  ${pc.green("Specs indexes updated:")} ${plan.writes.length} written, ${plan.removals.length} removed.
+`);
+    else
+      console.log(`  ${pc.dim("Specs indexes already up to date.")}
+`);
+  }
+  return changed;
+}
+async function inspectSpecsIndexHealth() {
+  try {
+    const plan = await planSpecsIndexes();
+    return {
+      ok: plan.writes.length === 0 && plan.removals.length === 0,
+      expectedPaths: plan.expectedPaths.map(toProjectPath),
+      stalePaths: plan.writes.map((write) => toProjectPath(write.path)),
+      obsoletePaths: plan.removals.map(toProjectPath),
+      issues: []
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      expectedPaths: [],
+      stalePaths: [],
+      obsoletePaths: [],
+      issues: [error instanceof Error ? error.message : String(error)]
+    };
+  }
+}
+async function planSpecsIndexes(affectedDirectory) {
   const specsDir = join(RSP_DIR, "specs");
   const configInspection = await inspectRspConfig();
   if (configInspection.issues.length > 0)
@@ -171,91 +217,154 @@ async function buildSpecsIndex({ acquireLock = true, quiet = false } = {}) {
   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 false;
+  if (!inspection.rootExists)
+    return { writes: [], removals: [], expectedPaths: [] };
+  const excludedDirectories = [DEFAULT_DECISION_RECORDS_PATH, decisionRecordsPath].filter((path) => isInside(specsDir, path));
+  const isExcluded = (path) => excludedDirectories.some((directory) => isInside(directory, path));
+  const managedIndexFiles = inspection.files.filter((path) => !isExcluded(path)).filter((path) => basename(path) === SPECS_INDEX_FILENAME || path === join(specsDir, LEGACY_SPECS_INDEX_FILENAME));
+  const recognizedIndexes = /* @__PURE__ */ new Set();
+  for (const path of managedIndexFiles) {
+    let metadata;
+    try {
+      metadata = parseFrontmatter(await readFile2(path, "utf-8"));
+    } catch (error) {
+      throw new Error(`unable to inspect reserved Specs index ${toProjectPath(path)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const expectedSourceDirectory = path === join(specsDir, LEGACY_SPECS_INDEX_FILENAME) ? toProjectPath(specsDir) : toProjectPath(dirname(path));
+    if (metadata?.kind !== "generated-index" || metadata.index_type !== "specs" || metadata.source_dir !== expectedSourceDirectory) {
+      throw new Error(`reserved Specs index is not recognized generated content: ${toProjectPath(path)}`);
+    }
+    recognizedIndexes.add(path);
+  }
+  const specFiles = inspection.files.filter((path) => path.endsWith(".md")).filter((path) => !isExcluded(path)).filter((path) => basename(path) !== SPECS_INDEX_FILENAME).filter((path) => path !== join(specsDir, LEGACY_SPECS_INDEX_FILENAME)).sort();
+  const directories = /* @__PURE__ */ new Set([specsDir]);
+  for (const file of specFiles) {
+    let current = dirname(file);
+    while (isInside(specsDir, current)) {
+      directories.add(current);
+      if (current === specsDir)
+        break;
+      current = dirname(current);
+    }
+  }
+  const orderedDirectories = [...directories].sort();
+  const expectedPaths = orderedDirectories.map((directory) => join(directory, SPECS_INDEX_FILENAME));
+  const expectedSet = new Set(expectedPaths);
+  const writableDirectories = affectedDirectory ? new Set(ancestorDirectories(specsDir, affectedDirectory)) : directories;
+  const writes = [];
+  for (const directory of orderedDirectories) {
+    if (!writableDirectories.has(directory))
+      continue;
+    const directFiles = specFiles.filter((path2) => dirname(path2) === directory);
+    const directDirectories = orderedDirectories.filter((path2) => path2 !== directory && dirname(path2) === directory);
+    const content = await renderSpecsIndex(specsDir, directory, directFiles, directDirectories);
+    const path = join(directory, SPECS_INDEX_FILENAME);
+    const existingContent = recognizedIndexes.has(path) ? await readFile2(path, "utf-8") : null;
+    if (existingContent !== content)
+      writes.push({ path, content });
+  }
+  const removals = [...recognizedIndexes].filter((path) => path === join(specsDir, LEGACY_SPECS_INDEX_FILENAME) || !expectedSet.has(path) && !affectedDirectory).sort();
+  return { writes, removals, expectedPaths };
+}
+async function renderSpecsIndex(specsDir, directory, files, directories) {
+  const sourceDir = toProjectPath(directory);
+  const scope = normalizeLogicalPath(relative(specsDir, directory));
+  const title = scope === "" ? "Specs Index" : `Specs: ${scope}`;
+  const entries = [];
+  for (const childDirectory of directories) {
+    const name = basename(childDirectory);
+    entries.push({
+      sortKey: `${name}/`,
+      line: `| [${escapeLabel(`${name}/`)}](${encodeLink(`${name}/${SPECS_INDEX_FILENAME}`)}) | directory | ${escapeCell(name)} | \u2014 |`
+    });
+  }
+  for (const path of files) {
+    const name = basename(path);
+    const content = await readFile2(path, "utf-8");
+    const metadata = parseFrontmatter(content);
+    const metadataTitle = metadata && typeof metadata.title === "string" ? metadata.title : "";
+    const entryTitle = metadataTitle || extractTitle(content) || name.replace(/\.md$/, "");
+    const summary = extractSummary(content, metadata?.summary);
+    entries.push({
+      sortKey: name,
+      line: `| [${escapeLabel(name)}](${encodeLink(name)}) | spec | ${escapeCell(entryTitle)} | ${escapeCell(summary || "\u2014")} |`
+    });
   }
-  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`._");
-  lines.push("");
-  if (specFiles.length === 0) {
-    lines.push("_No additional project-level specs yet._");
+  entries.sort((left, right) => left.sortKey < right.sortKey ? -1 : left.sortKey > right.sortKey ? 1 : 0);
+  const lines = [
+    "---",
+    `title: ${JSON.stringify(title)}`,
+    `summary: ${JSON.stringify(`Direct Specs and child Spec directories under ${sourceDir}.`)}`,
+    "kind: generated-index",
+    "index_type: specs",
+    `source_dir: ${JSON.stringify(sourceDir)}`,
+    `entry_count: ${entries.length}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    "_Generated direct-child navigation. Edit the linked Specs, then run `rsp update`._",
+    ""
+  ];
+  if (entries.length === 0) {
+    lines.push("_No Specs or child Spec directories yet._");
   } else {
-    lines.push("| File | Title | Summary |");
-    lines.push("|------|-------|---------|");
-    for (const fp of specFiles) {
-      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$/, "");
-      const summary = extractSummary(content, fm?.summary);
-      lines.push(`| ${escapeCell(rel)} | ${escapeCell(title)} | ${escapeCell(summary || "\u2014")} |`);
-    }
-  }
-  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);
+    lines.push("| Entry | Kind | Title | Summary |");
+    lines.push("|-------|------|-------|---------|");
+    lines.push(...entries.map((entry) => entry.line));
+  }
+  return lines.join("\n");
+}
+function ancestorDirectories(root, directory) {
+  if (!isInside(root, directory))
+    throw new Error(`affected Spec directory must stay inside ${toProjectPath(root)}: ${directory}`);
+  const result = [];
+  let current = directory;
+  while (true) {
+    result.push(current);
+    if (current === root)
+      return result;
+    current = dirname(current);
+  }
+}
+function isInside(directory, path) {
+  const rel = relative(directory, path);
   return rel === "" || !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
 }
+function toProjectPath(path) {
+  return normalizeLogicalPath(relative(".", path));
+}
 function extractTitle(content) {
   for (const rawLine of content.split("\n")) {
-    if (!rawLine.startsWith("# "))
-      continue;
-    return rawLine.slice(2).trim();
+    if (rawLine.startsWith("# "))
+      return rawLine.slice(2).trim();
   }
   return "";
 }
 function extractSummary(content, frontmatterSummary) {
   if (typeof frontmatterSummary === "string" && frontmatterSummary.trim() !== "")
     return frontmatterSummary.trim();
-  const lines = content.split("\n");
   let inFrontmatter = false;
-  for (const rawLine of lines) {
+  for (const rawLine of content.split("\n")) {
     const line = rawLine.trim();
     if (line === "---" || line === "...") {
       inFrontmatter = !inFrontmatter;
       continue;
     }
-    if (inFrontmatter || line === "")
-      continue;
-    if (line.startsWith("#"))
-      continue;
-    if (line.startsWith("##"))
+    if (inFrontmatter || line === "" || line.startsWith("#"))
       continue;
     return line.replace(/^[-*]\s*/, "").trim();
   }
   return "";
 }
 function escapeCell(value) {
-  return value.replace(/\|/g, "\\|");
+  return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function escapeLabel(value) {
+  return value.replace(/([\\[\]])/g, "\\$1");
+}
+function encodeLink(value) {
+  return encodeURI(value).replace(/\(/g, "%28").replace(/\)/g, "%29");
 }
 
 // src/commands/add-spec.ts
@@ -268,6 +377,10 @@ async function addSpec(name, projectName = "project") {
     console.error(`  ${pc.red("Error:")} .rsp/specs/decisions/ is reserved for Decision Records`);
     process.exit(1);
   }
+  if (["index", "00-index"].includes(name.split("/").at(-1) || "")) {
+    console.error(`  ${pc.red("Error:")} spec name "index" is reserved for generated local navigation`);
+    process.exit(1);
+  }
   guardRspInitialized();
   try {
     const configInspection = await inspectRspConfig();
@@ -294,11 +407,11 @@ async function addSpec(name, projectName = "project") {
     try {
       await writeFile2(path, content, { flag: "wx" });
       created = true;
-      await buildSpecsIndex({ acquireLock: false });
+      await buildSpecsIndex({ acquireLock: false, affectedDirectory: parent });
     } catch (error) {
       if (created) {
         try {
-          await unlink2(path);
+          await unlink3(path);
           await cleanupEmptyParentDirs(path, specsDir);
         } catch {
         }
@@ -313,129 +426,25 @@ async function addSpec(name, projectName = "project") {
 }
 
 // src/commands/archive.ts
-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 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, 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 false;
-  }
-  const archiveFiles = inspection.files;
-  const lines = [];
-  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("# Archive Index");
-  lines.push("");
-  if (archiveFiles.length === 0) {
-    lines.push("_No archived changes yet._");
-  } else {
-    lines.push("| Date | Change | Kind | Summary |");
-    lines.push("|------|--------|------|---------|");
-  }
-  for (const fp of archiveFiles) {
-    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 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 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 {
-    }
-    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, options = {}) {
+import { existsSync, readdirSync } from "fs";
+import { mkdir as mkdir3, readFile as readFile3, rename, unlink as unlink4 } from "fs/promises";
+import { basename as basename2, join as join3 } from "path";
+async function archiveChange(name) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp archive <name>`);
     process.exit(1);
   }
   guardRspInitialized();
-  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;
-  }
   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 content = await readFile3(srcPath, "utf-8");
       const dependencyInspection = await inspectChangeDependencies();
       const checklist = collectArchiveChecklist(content, {
-        activeBlockers: dependencyInspection.activeBlockers.get(name)
+        activeBlockers: dependencyInspection.activeBlockers.get(workRef.name)
       });
       for (const line of checklist)
         console.log(`  ${pc.yellow("\u26A0")} ${line}`);
@@ -443,15 +452,15 @@ async function archiveChange(name, options = {}) {
         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 base = basename3(workRef.name);
+      const base = basename2(workRef.name);
       await mkdir3(archiveSubdir, { recursive: true });
       const archiveName = resolveArchiveName(archiveSubdir, date, base);
-      await rename(srcPath, join4(archiveSubdir, archiveName));
+      await rename(srcPath, join3(archiveSubdir, archiveName));
       const postArchiveWarnings = [];
       let focusCleared = false;
-      if (existsSync3(focusEntry)) {
+      if (existsSync(focusEntry)) {
         try {
-          await unlink3(focusEntry);
+          await unlink4(focusEntry);
           await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
           focusCleared = true;
         } catch (error) {
@@ -467,17 +476,12 @@ async function archiveChange(name, options = {}) {
 ` : "";
       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.")}
 `);
-      if (existsSync3(".git")) {
+      if (existsSync(".git")) {
         console.log(`  ${pc.cyan("Git delivery:")}
 `);
         console.log(`    git status --short`);
@@ -493,28 +497,14 @@ ${clearedMsg}`);
     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 (!existsSync3(join4(archiveSubdir, initialName)))
+  if (!archiveNameExists(archiveSubdir, initialName))
     return initialName;
   const MAX_SUFFIX = 9999;
   for (let index = 2; index <= MAX_SUFFIX; index++) {
     const candidate = `${date}_${base}-${index}.md`;
-    if (!existsSync3(join4(archiveSubdir, candidate)))
+    if (!archiveNameExists(archiveSubdir, candidate))
       return candidate;
   }
   throw new WorkRefError(
@@ -523,9 +513,25 @@ function resolveArchiveName(archiveSubdir, date, base) {
     base
   );
 }
+function archiveNameExists(archiveSubdir, name) {
+  if (!existsSync(archiveSubdir))
+    return false;
+  return readdirSync(archiveSubdir).some((entry) => {
+    if (entry.normalize("NFC") !== name)
+      return false;
+    if (entry !== name) {
+      throw new WorkRefError(
+        "work_ref_collision",
+        `archive name has a Unicode normalization collision: ${entry} and ${name}`,
+        name
+      );
+    }
+    return true;
+  });
+}
 
 // src/commands/check.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 async function runCheck(options = {}) {
   const diagnostics = [];
   const runtime = [];
@@ -568,7 +574,7 @@ async function runCheck(options = {}) {
     const entryContent = marker.name;
     let markerContent = "";
     try {
-      markerContent = (await readFile5(entryPath, "utf-8")).trim();
+      markerContent = (await readFile4(entryPath, "utf-8")).trim();
     } catch (error) {
       addDiagnostic({
         severity: "error",
@@ -679,7 +685,7 @@ async function runCheck(options = {}) {
     const { name, path: fp } = ref;
     let content;
     try {
-      content = await readFile5(fp, "utf-8");
+      content = await readFile4(fp, "utf-8");
     } catch (error) {
       addDiagnostic({
         severity: "error",
@@ -714,8 +720,10 @@ async function runCheck(options = {}) {
         message: "missing YAML frontmatter"
       });
     }
+    const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
     for (const section of requiredSections) {
-      if (!new RegExp(`^## ${section}$`, "m").test(content)) {
+      const definition = getDocumentSectionDefinitionByHeading(CHANGE_DOCUMENT_SCHEMA, section);
+      if (!definition || !getDocumentSections(document, definition.id).some((candidate) => candidate.canonical)) {
         addDiagnostic({
           severity: "error",
           code: "missing_section",
@@ -752,16 +760,14 @@ async function runCheck(options = {}) {
         });
       }
     }
-    const headingLine = content.split("\n").map((line) => line.trim()).find((line) => line.startsWith("# Change:"));
-    if (headingLine) {
-      const heading = headingLine.slice("# Change:".length).trim();
-      if (heading !== name) {
+    if (document.title !== null) {
+      if (document.title !== name) {
         addDiagnostic({
           severity: "error",
           code: "heading_mismatch",
           change: name,
           path: fp,
-          message: `# Change: heading "${heading}" differs from change name`
+          message: `# Change: heading "${document.title}" differs from change name`
         });
       }
     } else {
@@ -884,7 +890,7 @@ async function runCheck(options = {}) {
   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;
+  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);
@@ -908,8 +914,8 @@ function collectMatchingLines(content, predicate) {
 }
 
 // src/commands/create.ts
-import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir4, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir4, unlink as unlink5, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname2 } from "path";
 async function createChange(name, summary = "", kind, options = {}) {
   if (!name) {
@@ -921,10 +927,10 @@ async function createChange(name, summary = "", kind, options = {}) {
     return await withRspLock("create-change", async () => {
       const workRef = await resolveExecutableChange(name);
       const changePath = workRef.path;
-      const existed = existsSync4(changePath);
+      const existed = existsSync2(changePath);
       if (!existed) {
         const focusEntry = resolveFocusMarkerPath(workRef);
-        const content = generateChangeContent(name, summary, kind, { lite: Boolean(options.lite) });
+        const content = generateChangeContent(workRef.name, summary, kind, { lite: Boolean(options.lite) });
         await mkdir4(dirname2(changePath), { recursive: true });
         let changeCreated = false;
         try {
@@ -936,7 +942,7 @@ async function createChange(name, summary = "", kind, options = {}) {
         } catch (error) {
           if (changeCreated) {
             try {
-              await unlink4(changePath);
+              await unlink5(changePath);
               await cleanupEmptyParentDirs(changePath, CHANGES_DIR);
             } catch {
             }
@@ -947,9 +953,9 @@ async function createChange(name, summary = "", kind, options = {}) {
       const label = existed ? "Using" : pc.green("Created");
       console.log(`  ${label}: ${changePath}`);
       if (existed)
-        console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${name}`);
+        console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${workRef.name}`);
       else
-        console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${name}`);
+        console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${workRef.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"}
 `);
     });
@@ -963,17 +969,39 @@ async function createChange(name, summary = "", kind, options = {}) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { readdir, readFile as readFile7, stat } from "fs/promises";
-import { basename as basename4, join as join6, relative as relative3 } from "path";
+import { basename as basename3, join as join6, relative as relative2 } from "path";
 
 // src/commands/update.ts
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { mkdir as mkdir5, readFile as readFile6, rm, rmdir } from "fs/promises";
 import { join as join5 } from "path";
+
+// src/commands/archive-index-migration.ts
+import { readFile as readFile5, unlink as unlink6 } from "fs/promises";
+import { join as join4 } from "path";
+async function removeLegacyArchiveIndex() {
+  const path = join4(ARCHIVES_DIR, "INDEX.md");
+  const inspection = inspectManagedFile(path, "legacy archive index", { allowMissing: true });
+  if (!inspection.exists || inspection.issue)
+    return false;
+  let frontmatter;
+  try {
+    frontmatter = parseFrontmatter(await readFile5(path, "utf-8"));
+  } catch {
+    return false;
+  }
+  if (frontmatter?.kind !== "generated-index" || frontmatter.index_type !== "archives")
+    return false;
+  await unlink6(path);
+  return true;
+}
+
+// src/commands/update.ts
 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)) {
+  if (!existsSync3(RSP_DIR)) {
     console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
     console.error(`  ${pc.dim("Run: rsp init")}`);
     process.exit(1);
@@ -1004,6 +1032,9 @@ async function updateProject(options = {}) {
         console.log(`  ${pc.green("\u2713")} changes/ directory restored`);
       updated = true;
     }
+    const archivesInspection = inspectManagedDirectory(join5(RSP_DIR, "archives"), "archive root", { allowMissing: true });
+    if (archivesInspection.issue)
+      throw archivesInspection.issue;
     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)
@@ -1016,7 +1047,7 @@ async function updateProject(options = {}) {
         console.log(`  ${pc.green("\u2713")} rsp-rules.md updated`);
       updated = true;
     }
-    if (existsSync5(OBSOLETE_RSP_RULES_PATH)) {
+    if (existsSync3(OBSOLETE_RSP_RULES_PATH)) {
       await rm(OBSOLETE_RSP_RULES_PATH);
       actions.push("obsolete rules/rsp-rules.md removed");
       if (!options.quiet)
@@ -1078,9 +1109,14 @@ async function updateProject(options = {}) {
       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");
+    if (specsIndexChanged) {
+      actions.push("generated Specs indexes reconciled");
+      updated = true;
+    }
+    if (await removeLegacyArchiveIndex()) {
+      actions.push("legacy Archive Index removed");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} legacy Archive Index removed`);
       updated = true;
     }
     if (!options.quiet && inspection.diagnostics.length > 0) {
@@ -1116,7 +1152,7 @@ async function updateProject(options = {}) {
 async function runDoctor(options = {}) {
   const fixed = [];
   let repairIssue = null;
-  if (options.fix && existsSync6(RSP_DIR)) {
+  if (options.fix && existsSync4(RSP_DIR)) {
     try {
       const update = await updateProject({ quiet: Boolean(options.json) });
       fixed.push(...update.actions);
@@ -1136,17 +1172,12 @@ async function runDoctor(options = {}) {
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
   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");
+  reportCheck(checks, ".rsp exists", existsSync4(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");
+  reportCheck(checks, "specs/design.md exists", existsSync4(designPath), "Run: rsp init");
   await checkAgents(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 checkSpecsIndexes(checks, reportRuntime);
   await checkArchiveNaming(checks);
   const decisionRecordsConfigValid = await checkConfigSemantics(checks, reportRuntime);
   if (decisionRecordsConfigValid) {
@@ -1174,7 +1205,7 @@ async function runDoctor(options = {}) {
   if (fixed.length > 0) {
     console.log(`  ${pc.green("Fixed:")} ${fixed.join(", ")}`);
     console.log();
-  } else if (options.fix && !repairIssue && existsSync6(RSP_DIR)) {
+  } else if (options.fix && !repairIssue && existsSync4(RSP_DIR)) {
     console.log(`  ${pc.dim("No safe fixes needed.")}`);
     console.log();
   }
@@ -1192,7 +1223,7 @@ async function runDoctor(options = {}) {
 }
 function reportFallbackProtocol(checks) {
   const canonical = inspectManagedFile(RSP_RULES_PATH, "fallback protocol", { allowMissing: true });
-  const obsoleteExists = existsSync6(OBSOLETE_RSP_RULES_PATH);
+  const obsoleteExists = existsSync4(OBSOLETE_RSP_RULES_PATH);
   if (canonical.issue) {
     checks.push({
       status: "issue",
@@ -1206,7 +1237,7 @@ function reportFallbackProtocol(checks) {
     checks.push({
       status: "issue",
       label: "rsp-rules.md exists",
-      hint: existsSync6(RSP_DIR) ? "Run: rsp update" : "Run: rsp init"
+      hint: existsSync4(RSP_DIR) ? "Run: rsp update" : "Run: rsp init"
     });
   }
   if (obsoleteExists) {
@@ -1297,44 +1328,31 @@ 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, expectedIndexType, label, fixHint) {
-  const indexFile = inspectManagedFile(path, label, { allowMissing: true });
-  if (indexFile.issue) {
-    checks.push({ status: "issue", label, message: indexFile.issue.message, hint: fixHint });
+async function checkSpecsIndexes(checks, reportRuntime) {
+  const health = await inspectSpecsIndexHealth();
+  if (health.ok) {
+    checks.push({ status: "ok", label: "hierarchical Specs indexes are current generated files" });
     return;
   }
-  if (!indexFile.exists)
-    return;
-  let content;
-  try {
-    content = await readFile7(path, "utf-8");
-  } catch (error) {
-    reportRuntime({
-      code: "generated_index_read_failed",
-      operation: "readFile",
-      path,
-      message: toErrorMessage(error)
-    });
-    checks.push({ status: "issue", label, message: `${label} could not be read`, hint: fixHint });
-    return;
-  }
-  try {
-    const fm = parseFrontmatter(content);
-    if (fm?.kind === "generated-index" && fm.index_type === expectedIndexType) {
-      checks.push({ status: "ok", label });
-      return;
-    }
-  } catch (error) {
+  for (const message of health.issues) {
     reportRuntime({
-      code: "generated_index_frontmatter_parse_failed",
-      operation: "parseFrontmatter",
-      path,
-      message: toErrorMessage(error)
+      code: "specs_index_inspection_failed",
+      operation: "inspectSpecsIndexHealth",
+      path: ".rsp/specs",
+      message
     });
-    checks.push({ status: "issue", label, message: `${label} could not parse metadata`, hint: fixHint });
-    return;
   }
-  checks.push({ status: "issue", label, hint: fixHint });
+  const details = [
+    ...health.issues,
+    health.stalePaths.length > 0 ? `missing or stale: ${health.stalePaths.join(", ")}` : "",
+    health.obsoletePaths.length > 0 ? `recognized obsolete indexes: ${health.obsoletePaths.join(", ")}` : ""
+  ].filter(Boolean);
+  checks.push({
+    status: "issue",
+    label: "hierarchical Specs indexes are current generated files",
+    message: details.join("; "),
+    hint: "Run: rsp update"
+  });
 }
 async function checkArchiveNaming(checks) {
   const archivesDir = join6(RSP_DIR, "archives");
@@ -1349,7 +1367,7 @@ async function checkArchiveNaming(checks) {
     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);
+  const invalidFiles = inspection.files.map((fp) => normalizeLogicalPath(relative2(archivesDir, fp))).filter((fp) => /^\d{4}-\d{2}-\d{2}_.+\.md$/.test(basename3(fp)) === false);
   if (invalidFiles.length === 0) {
     checks.push({ status: "ok", label: "archived change files follow the date_name.md convention" });
     return;
@@ -1437,7 +1455,7 @@ async function checkDecisionRecordsDirectory(checks, reportRuntime) {
 }
 async function checkInactiveDefaultDecisionRecords(checks, reportRuntime) {
   const decisionRecordsPath = resolveDecisionRecordsPath(await loadRspConfig());
-  if (decisionRecordsPath === DEFAULT_DECISION_RECORDS_PATH || !existsSync6(DEFAULT_DECISION_RECORDS_PATH))
+  if (decisionRecordsPath === DEFAULT_DECISION_RECORDS_PATH || !existsSync4(DEFAULT_DECISION_RECORDS_PATH))
     return;
   let inspectionFailed = false;
   const inactiveRecords = (await walkMarkdownFiles(DEFAULT_DECISION_RECORDS_PATH, {
@@ -1445,7 +1463,7 @@ async function checkInactiveDefaultDecisionRecords(checks, reportRuntime) {
       inspectionFailed = true;
       reportRuntime(diagnostic);
     }
-  })).map((path) => normalizeLogicalPath(relative3(DEFAULT_DECISION_RECORDS_PATH, path))).sort();
+  })).map((path) => normalizeLogicalPath(relative2(DEFAULT_DECISION_RECORDS_PATH, path))).sort();
   if (inspectionFailed) {
     checks.push({
       status: "issue",
@@ -1555,8 +1573,8 @@ async function checkActiveChangeConsistency(checks) {
 }
 
 // src/commands/focus.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir6, unlink as unlink5 } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
+import { mkdir as mkdir6, unlink as unlink7 } from "fs/promises";
 import { dirname as dirname3 } from "path";
 async function focusChange(name) {
   if (!name) {
@@ -1571,8 +1589,8 @@ async function focusChange(name) {
       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(`  ${pc.green("Focused:")} ${workRef.name}`);
+      console.log(`  ${pc.dim("focus.d")} \u2192 ${workRef.name}`);
       console.log();
     });
   } catch (error) {
@@ -1589,12 +1607,12 @@ async function unfocusChange(name) {
     return await withRspLock("unfocus-change", async () => {
       const workRef = resolveWorkRef(name, { executable: false, mustExist: false });
       const focusEntry = resolveFocusMarkerPath(workRef);
-      if (!existsSync7(focusEntry))
+      if (!existsSync5(focusEntry))
         throw new WorkRefError("focus_marker_not_found", `.rsp/focus.d/${name}`, name);
-      await unlink5(focusEntry);
+      await unlink7(focusEntry);
       await cleanupEmptyParentDirs(focusEntry, FOCUS_DIR);
-      console.log(`  ${pc.green("Unfocused:")} ${name}`);
-      console.log(`  ${pc.dim("focus.d cleared")} \u2192 ${name}`);
+      console.log(`  ${pc.green("Unfocused:")} ${workRef.name}`);
+      console.log(`  ${pc.dim("focus.d cleared")} \u2192 ${workRef.name}`);
       console.log();
     });
   } catch (error) {
@@ -1629,20 +1647,21 @@ async function createChangeGroup(name, goal = "") {
       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");
+      const groupName = ref.group;
+      if (await hasArchivedGroupBrief(groupName))
+        throw new ChangeGroupError(`archived Change Group cannot be reopened: ${groupName}`);
+      const groupDirectory = resolveManagedDirectoryChain(CHANGES_DIR, [groupName], "Change Group path");
       await mkdir7(groupDirectory, { recursive: true });
       try {
-        await writeFile4(ref.path, generateGroupBriefContent(name, goal), { flag: "wx" });
+        await writeFile4(ref.path, generateGroupBriefContent(groupName, goal), { flag: "wx" });
       } catch (error) {
         if (error.code === "EEXIST")
-          throw new ChangeGroupError(`Change Group already exists: ${name}`);
+          throw new ChangeGroupError(`Change Group already exists: ${groupName}`);
         throw error;
       }
-      console.log(`  ${pc.green("Created Change Group:")} ${name}`);
+      console.log(`  ${pc.green("Created Change Group:")} ${groupName}`);
       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>
+      console.log(`  ${pc.cyan("Next:")} fill the brief, then create direct child Changes with rsp create ${groupName}/<change>
 `);
     });
   } catch (error) {
@@ -1665,12 +1684,13 @@ async function closeChangeGroup(name) {
       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);
+      const groupName = ref.group;
+      const group = inspection.groups.find((candidate) => candidate.name === groupName);
       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));
+        throw new ChangeGroupError(`Change Group not found: ${groupName}`);
+      const reasons = collectCloseReasons(group, inspection.diagnostics.filter((diagnostic) => diagnostic.change === groupName && diagnostic.severity === "error").map((diagnostic) => diagnostic.message));
       if (reasons.length > 0)
-        throw new ChangeGroupError(`Change Group "${name}" is not ready to close: ${reasons.join("; ")}`);
+        throw new ChangeGroupError(`Change Group "${groupName}" 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");
@@ -1682,12 +1702,7 @@ async function closeChangeGroup(name) {
       } 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.green("Closed Change Group:")} ${groupName}`);
       console.log(`  ${pc.dim("Archived Group Brief:")} ${join7(archiveDirectory, archiveName)}
 `);
       for (const warning of warnings)
@@ -1723,8 +1738,6 @@ function collectCloseReasons(group, errors) {
 
 // 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";
@@ -1738,15 +1751,15 @@ async function showHistory(input = {}, options = {}) {
       message: "archive history inspection is incomplete; resolve the reported diagnostics before querying history"
     }, inspection.diagnostics, inspection.diagnosticSummary, inspection.runtime, options);
   }
-  if (input.workRef) {
+  if (validation.workRef) {
     try {
-      const selected = selectArchiveHistoryRecord(inspection.records, { workRef: input.workRef });
+      const selected = selectArchiveHistoryRecord(inspection.records, { workRef: validation.workRef });
       const record = await readArchiveHistoryDetail(selected);
       const result2 = {
         command: "history",
         ok: true,
         mode: "detail",
-        query: { workRef: input.workRef },
+        query: { workRef: validation.workRef },
         record,
         diagnostics: [],
         diagnosticSummary: emptyCollectionSummary(),
@@ -1780,7 +1793,8 @@ async function showHistory(input = {}, options = {}) {
       since: query.since ?? null,
       until: query.until ?? null,
       kind: query.kind ?? null,
-      group: query.group ?? null
+      group: query.group ?? null,
+      search: query.search ?? null
     },
     records: listed.records,
     summary: listed.summary,
@@ -1798,11 +1812,15 @@ 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"))
+    let workRef;
+    try {
+      workRef = normalizeExecutableWorkRef(input.workRef);
+    } catch {
       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)
+    }
+    if (input.limit !== void 0 || input.since !== void 0 || input.until !== void 0 || input.kind !== void 0 || input.group !== void 0 || input.search !== void 0)
       return invalid("history_detail_filters_unsupported", "list filters cannot be combined with an exact history detail lookup");
-    return { ok: true, query: {} };
+    return { ok: true, query: {}, workRef };
   }
   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)
@@ -1815,8 +1833,16 @@ function validateHistoryQuery(input) {
     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");
+  let group = input.group;
+  if (group !== void 0) {
+    try {
+      group = normalizeWorkRefSegment(group);
+    } catch {
+      return invalid("invalid_history_group", "--group must be one safe Unicode Group name");
+    }
+  }
+  if (input.search !== void 0 && input.search.trim() === "")
+    return invalid("invalid_history_search", "--search must be non-empty");
   return {
     ok: true,
     query: {
@@ -1824,7 +1850,8 @@ function validateHistoryQuery(input) {
       since: input.since,
       until: input.until,
       kind: input.kind?.trim(),
-      group: input.group
+      group,
+      search: input.search?.trim()
     }
   };
 }
@@ -1916,7 +1943,7 @@ function printHistoryDetail(result) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { mkdir as mkdir8, readFile as readFile8 } from "fs/promises";
 import { join as join8 } from "path";
 function generateConfigTemplate() {
@@ -1932,9 +1959,16 @@ function generateConfigTemplate() {
 # kinds:
 ${fmtList(VALID_KINDS, 0)}
 
+# Set one shared project default for durable artifact and commit prose.
+# Optional artifacts or commit values override that durable surface independently.
+# Response language remains user/session-owned and is never read from this project mapping.
+# Omit this mapping to keep durable language selection under scoped project authority.
+# language:
+#   default: en
+
 # New projects default to automatic Manage routing with lifecycle-only closeout.
 # Use activation: explicit to require a named managed request.
-# closeout accepts manual, lifecycle, or local; local may authorize an eligible local commit but never push or publication.
+# closeout accepts manual, lifecycle, or local; local routes a qualified clean terminal non-small boundary to one local commit but never push or publication.
 manage:
   activation: auto
   closeout: lifecycle
@@ -1952,7 +1986,7 @@ function toTitle(projectName) {
   return projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
 }
 async function initProject(args = {}) {
-  const isNew = !existsSync8(RSP_DIR);
+  const isNew = !existsSync6(RSP_DIR);
   const projectName = await detectProjectName();
   const mode = args.agentsMode ?? "managed";
   if (mode !== "managed" && mode !== "print") {
@@ -1967,7 +2001,7 @@ async function initProject(args = {}) {
     const agentsInspection = inspectManagedFile(agentsPath, "AGENTS.md", { allowMissing: true });
     if (agentsInspection.issue)
       throw agentsInspection.issue;
-    if (existsSync8(CONFIG_PATH)) {
+    if (existsSync6(CONFIG_PATH)) {
       clearConfigCache();
       const existingConfig = await inspectRspConfig();
       if (existingConfig.issues.length > 0)
@@ -1997,12 +2031,9 @@ async function initProject(args = {}) {
       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(join8(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
     created = createdDesign || created;
-    const createdArchivesIndex = await ensureFile(join8(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
-    created = createdArchivesIndex || created;
+    created = await removeLegacyArchiveIndex() || 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;
@@ -2013,10 +2044,7 @@ async function initProject(args = {}) {
       created = await ensureFile(changePath, generateChangeContent("project-setup")) || created;
       created = await ensureFile(focusMarker, "") || created;
     }
-    if (createdSpecsIndex || createdDesign)
-      await buildSpecsIndex({ acquireLock: false });
-    if (createdArchivesIndex)
-      await buildArchiveIndex({ acquireLock: false });
+    created = await buildSpecsIndex({ acquireLock: false }) || created;
     const title = toTitle(projectName);
     let agentsUpdated = false;
     if (!agentsInspection.exists) {
@@ -2192,8 +2220,124 @@ function formatArchiveReady(value) {
   }
 }
 
+// src/commands/reopen.ts
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir9, readFile as readFile10, unlink as unlink8, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+async function reopenChange(name, options) {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp reopen <name> --reason <text> [--from <archive-path>]`);
+    process.exit(1);
+  }
+  const reason = options.reason?.trim();
+  if (!reason || /[\r\n]/.test(reason)) {
+    console.error(`  ${pc.red("Error:")} --reason must be one non-empty line`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  try {
+    await withRspLock("reopen-change", async () => {
+      const normalizedName = normalizeExecutableWorkRef(name);
+      const inspection = await inspectArchiveHistory();
+      if (!historyInspectionComplete(inspection)) {
+        throw new ArchiveHistoryError(
+          "archive_inspection_incomplete",
+          "archive history inspection is incomplete; resolve the reported diagnostics before reopening work"
+        );
+      }
+      const record = selectArchiveHistoryRecord(
+        inspection.records,
+        options.from ? { path: options.from } : { workRef: normalizedName }
+      );
+      if (record.workRef !== normalizedName) {
+        throw new ArchiveHistoryError(
+          "archive_identity_mismatch",
+          `selected archive belongs to ${record.workRef}, not ${normalizedName}`
+        );
+      }
+      let workRef;
+      try {
+        workRef = resolveWorkRef(normalizedName, { executable: true });
+      } catch (error) {
+        if (error instanceof WorkRefError && error.code === "group_brief_missing") {
+          throw new ArchiveHistoryError(
+            "archived_group_closed",
+            `cannot reopen ${name} because its Change Group is closed; reopen the Group through a separately authorized lifecycle operation first`
+          );
+        }
+        throw error;
+      }
+      if (existsSync7(workRef.path))
+        throw new ArchiveHistoryError("open_change_exists", `open Change already exists: ${name}`);
+      const focusEntry = resolveFocusMarkerPath(workRef);
+      if (existsSync7(focusEntry))
+        throw new ArchiveHistoryError("focus_marker_exists", `focus marker already exists for non-open Change: ${name}; run rsp doctor`);
+      const archivedContent = await readFile10(record.sourcePath, "utf-8");
+      const reopenedContent = appendChecklistItem(
+        appendChecklistItem(archivedContent, "tasks", `- [ ] Resolve reopened concern: ${reason}`),
+        "verify",
+        `- [ ] Verify reopened concern: ${reason}`
+      );
+      await mkdir9(dirname4(workRef.path), { recursive: true });
+      let changeCreated = false;
+      try {
+        await writeFile5(workRef.path, reopenedContent, { flag: "wx" });
+        changeCreated = true;
+        await mkdir9(FOCUS_DIR, { recursive: true });
+        await mkdir9(dirname4(focusEntry), { recursive: true });
+        await writeManagedFile(focusEntry, "", "focus marker");
+      } catch (error) {
+        if (changeCreated) {
+          try {
+            await unlink8(workRef.path);
+            await cleanupEmptyParentDirs(workRef.path, CHANGES_DIR);
+          } catch {
+          }
+        }
+        throw error;
+      }
+      console.log(`  ${pc.green("Reopened:")} ${workRef.name}`);
+      console.log(`  ${pc.dim("retained archive")} \u2192 ${record.path}`);
+      console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${workRef.name}`);
+      console.log(`  ${pc.cyan("Next:")} refine the reopened Task and Verify evidence, then resolve the concern
+`);
+      if (existsSync7(".git")) {
+        console.log(`  ${pc.cyan("Git delivery:")}`);
+        console.log(`    git status --short`);
+        console.log(`    Inspect the complete reopen transition; stage and commit only with separate Git authority.`);
+        console.log();
+      }
+    });
+  } catch (error) {
+    if (error instanceof ArchiveHistoryError || error instanceof WorkRefError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      if (error instanceof ArchiveHistoryError) {
+        for (const candidate of error.candidates)
+          console.error(`    ${candidate}`);
+        if (error.candidatesTruncated)
+          console.error(`    ... ${error.candidateTotal - error.candidates.length} more`);
+      }
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+function appendChecklistItem(content, sectionId, item) {
+  try {
+    return appendDocumentSectionItem(parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA), sectionId, item);
+  } catch (error) {
+    if (!(error instanceof DocumentSectionCardinalityError))
+      throw error;
+    const heading = CHANGE_DOCUMENT_SCHEMA.sections.find((section) => section.id === sectionId).heading;
+    throw new ArchiveHistoryError(
+      "archive_section_invalid",
+      `archived Change must contain exactly one required section: ${heading}`
+    );
+  }
+}
+
 // src/commands/show.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } 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) {
@@ -2251,7 +2395,7 @@ async function showChange(nameOrFocused, options = {}) {
   const srcPath = workRef.path;
   let content;
   try {
-    content = await readFile10(srcPath, "utf-8");
+    content = await readFile11(srcPath, "utf-8");
   } catch {
     exitShowError({ code: "change_read_failed", message: `unable to read .rsp/changes/${name}.md` }, options);
   }
@@ -2383,6 +2527,7 @@ function deriveStatusView(snapshot, options = {}) {
   const nextActions = ok ? buildStatusNextActions(snapshot.focused.length, snapshot.records.map((record) => record.output), snapshot.groups, filtered) : ["Run: rsp doctor"];
   return {
     manage: snapshot.manage,
+    language: snapshot.language,
     query,
     focused: snapshot.focused,
     records,
@@ -2479,6 +2624,8 @@ function printStatusPlain(view) {
   console.log(`  ${pc.bold("RSP status")}`);
   console.log();
   console.log(`  ${pc.bold("Manage:")} activation ${view.manage.activation} \xB7 closeout ${view.manage.closeout}`);
+  if (view.language.artifacts !== null || view.language.commit !== null)
+    console.log(`  ${pc.bold("Language:")} artifacts ${view.language.artifacts ?? "unset"} \xB7 commit ${view.language.commit ?? "unset"}`);
   console.log();
   for (const diagnostic of view.diagnostics) {
     const label = diagnostic.change ?? diagnostic.path;
@@ -2598,6 +2745,7 @@ function toStatusJson(view) {
     command: "status",
     ok: view.ok,
     manage: view.manage,
+    language: view.language,
     filters: view.query,
     focused: view.focused,
     records: view.records.map((record) => record.output),
@@ -2615,6 +2763,7 @@ function toStatusJsonError(error, options) {
     command: "status",
     ok: false,
     manage: { activation: "explicit", closeout: "manual" },
+    language: { artifacts: null, commit: null },
     filters: {
       focused: options.focused,
       blocked: options.blocked,
@@ -2788,7 +2937,7 @@ var groupCommand = defineCommand({
 var addSpecCommand = defineCommand({
   meta: {
     name: "spec",
-    description: "Create .rsp/specs/<name>.md and rebuild specs index"
+    description: "Create .rsp/specs/<name>.md and refresh local Specs indexes"
   },
   args: {
     name: {
@@ -2823,12 +2972,42 @@ var archiveCommand = defineCommand({
     },
     "dry-run": {
       type: "boolean",
-      description: "Preview archive readiness without moving the change",
+      description: "Deprecated compatibility route to rsp ready; never moves the Change",
       default: false
     }
   },
   async run({ args }) {
-    await archiveChange(args.name, { dryRun: Boolean(args["dry-run"]) });
+    if (args["dry-run"]) {
+      console.error("  Deprecated: use `rsp ready <name>` for read-only archive readiness.");
+      await showReady(args.name);
+      return;
+    }
+    await archiveChange(args.name);
+  }
+});
+var reopenCommand = defineCommand({
+  meta: {
+    name: "reopen",
+    description: "Restore one archived Change as focused open work while retaining history"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Archived Change WorkRef",
+      required: true
+    },
+    from: {
+      type: "string",
+      description: "Exact .rsp/archives/... path when the WorkRef has multiple archives"
+    },
+    reason: {
+      type: "string",
+      description: "One-line concern that makes the restored Change unfinished",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await reopenChange(args.name, { from: args.from, reason: args.reason });
   }
 });
 var focusCommand = defineCommand({
@@ -2969,7 +3148,7 @@ var checkCommand = defineCommand({
 var updateCommand = defineCommand({
   meta: {
     name: "update",
-    description: "Refresh RSP project structure after upgrade (fallback protocol, AGENTS, indices)"
+    description: "Refresh RSP-managed project files after upgrade; does not update packaged Skills"
   },
   async run() {
     const result = await updateProject();
@@ -3176,6 +3355,10 @@ var historyCommand = defineCommand({
       type: "string",
       description: "Match one exact Change Group"
     },
+    search: {
+      type: "string",
+      description: "Case-insensitive literal match over WorkRef and summary"
+    },
     json: {
       type: "boolean",
       description: "Print machine-readable JSON output",
@@ -3195,6 +3378,7 @@ var historyCommand = defineCommand({
       until: args.until,
       kind: args.kind,
       group: args.group,
+      search: args.search,
       positionalCount: args._?.length ?? (args.name ? 1 : 0)
     }, { json: Boolean(args.json), compact: Boolean(args.compact) });
     if (!result.ok)
@@ -3212,7 +3396,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
   if (shouldLaunchSkillsUi(rawArgs, terminalEnvironment)) {
     const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
     const locale = resolveUiLocale("auto", process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-    const { runSkillsTui } = await import("./entry-UWUX3HM7.mjs");
+    const { runSkillsTui } = await import("./entry-5OPKUZHF.mjs");
     const selection = await runSkillsTui(locale);
     if (selection.kind === "confirmed") {
       const result = await installPackagedSkills({ names: selection.names, force: selection.force });
@@ -3230,7 +3414,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
     } 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 ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-      const { runTui } = await import("./entry-N7WLWGTI.mjs");
+      const { runTui } = await import("./entry-FVUG6YW2.mjs");
       const exitCode = await runTui(locale);
       if (exitCode !== 0)
         process.exitCode = exitCode;
@@ -3253,6 +3437,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
       focus: focusCommand,
       unfocus: unfocusCommand,
       archive: archiveCommand,
+      reopen: reopenCommand,
       ready: readyCommand,
       show: showCommand,
       history: historyCommand,