@oevery/rsp 3.2.0 → 3.3.0

package/dist/{chunk-ZORUJTVS.mjs → chunk-TSUDEX5Y.mjs}

@@ -4,45 +4,160 @@ import {
   CHANGES_DIR,
   CHANGE_DOCUMENT_SCHEMA,
   CONFIG_PATH,
+  DEFAULT_DECISION_RECORDS_PATH,
   FOCUS_DIR,
   GROUP_BRIEF_DOCUMENT_SCHEMA,
   ManagedPathError,
-  collectArchiveReadiness,
+  OBSOLETE_RSP_RULES_PATH,
+  RSP_DIR,
+  RSP_RULES_PATH,
+  classifyVerifyCheckboxes,
+  collectVerifyCheckboxLines,
   countCheckboxes,
   extractBlockerLines,
   getCanonicalSectionHeadings,
   getDocumentSectionBody,
   getDocumentTitle,
   getDocumentTitles,
+  getOpenCheckboxes,
   hasMeaningfulBlockerBody,
   hasMeaningfulBlockers,
   inspectManagedDirectory,
+  inspectManagedFile,
+  inspectManagedFileTree,
   inspectRspConfig,
-  normalizeLogicalPath,
+  isEmptyBlockerLine,
   parseFrontmatter,
   parseRspDocument,
   parseScenarios,
+  pc,
   renderDocumentSectionHeading,
   renderDocumentTitle,
   requireManagedDirectory,
   requireManagedFile,
+  resolveDecisionRecordsPath,
   resolveLanguagePolicy,
   resolveManagePolicy,
-  toErrorMessage
-} from "./chunk-SEGJLWRE.mjs";
+  toErrorMessage,
+  validateDecisionRecordsFilesystemPath
+} from "./chunk-7HXQNBIG.mjs";
 
 // src/status/inspect.ts
-import { readFile as readFile5, stat } from "fs/promises";
+import { readFile as readFile4, stat } from "fs/promises";
 
 // src/core/change-group.ts
-import { readFile } from "fs/promises";
-import { dirname, join as join2, relative as relative2 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { dirname as dirname2, join as join3, relative as relative3 } from "path";
+
+// src/core/filesystem.ts
+import { existsSync } from "fs";
+import { readdir, readFile, rmdir } from "fs/promises";
+import { basename, dirname, join, relative, sep } from "path";
+async function walkMarkdownFiles(dir, options = {}) {
+  const all = await walkFiles(dir, options);
+  return all.filter((f) => f.endsWith(".md"));
+}
+async function inspectUnsupportedRules() {
+  const rulesDir = join(RSP_DIR, "rules");
+  const diagnostics = [];
+  const rawEntries = await walkAllEntries(rulesDir, diagnostics);
+  const entries = rawEntries.filter((entry) => entry.path !== OBSOLETE_RSP_RULES_PATH).map((entry) => ({ path: normalizeLogicalPath(relative(rulesDir, entry.path)), kind: entry.kind }));
+  const obsoleteFallbackPresent = existsSync(OBSOLETE_RSP_RULES_PATH);
+  return {
+    entries,
+    diagnostics,
+    directoryRemaining: existsSync(rulesDir) && (!obsoleteFallbackPresent || entries.length > 0)
+  };
+}
+async function walkAllEntries(dir, diagnostics) {
+  const entries = [];
+  try {
+    const items = await readdir(dir, { withFileTypes: true });
+    for (const item of items) {
+      const path = join(dir, item.name);
+      const kind = item.isDirectory() ? "directory" : "file";
+      entries.push({ path, kind });
+      if (kind === "directory")
+        entries.push(...await walkAllEntries(path, diagnostics));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      diagnostics.push({ code: "walk_failed", operation: "readdir", path: dir, message: toErrorMessage(error) });
+    }
+  }
+  return entries;
+}
+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 normalizeLogicalPath(pathValue) {
+  return pathValue.split(sep).join("/").replace(/\\/g, "/");
+}
+var SPEC_NAME_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+function isValidSpecName(name) {
+  return SPEC_NAME_RE.test(name);
+}
+function guardRspInitialized() {
+  const designPath = join(RSP_DIR, "specs", "design.md");
+  const rules = inspectManagedFile(RSP_RULES_PATH, "fallback protocol", { allowMissing: true });
+  const design = inspectManagedFile(designPath, "design Spec", { allowMissing: true });
+  if (rules.issue || design.issue || !rules.exists || !design.exists) {
+    const initialized = existsSync(RSP_DIR);
+    console.error(`  ${pc.red("Error:")} ${initialized ? "RSP project requires an update" : "RSP is not initialized in this project"}`);
+    console.error(`  ${pc.dim(initialized ? "Run: rsp update" : "Run: rsp init")}`);
+    process.exit(1);
+  }
+}
+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());
+}
 
 // src/core/work-ref.ts
 import { Buffer } from "buffer";
 import { lstatSync, readdirSync } from "fs";
-import { readdir } from "fs/promises";
-import { isAbsolute, join, relative } from "path";
+import { readdir as readdir2 } from "fs/promises";
+import { isAbsolute, join as join2, relative as relative2 } from "path";
 var WORK_SEGMENT_RE = /^[\p{Ll}\p{Lo}\p{Lm}\p{M}\p{Nd}]+(?:-[\p{Ll}\p{Lo}\p{Lm}\p{M}\p{Nd}]+)*$/u;
 var WORK_SEGMENT_MAX_CODE_POINTS = 100;
 var WORK_SEGMENT_MAX_UTF8_BYTES = 200;
@@ -100,7 +215,7 @@ function resolveWorkRef(name, options = {}) {
   assertValidWorkRoot(changesDir, normalizedName);
   assertNoNormalizationCollision(changesDir, segments, normalizedName, isGroupBrief);
   assertNoIdentityCollision(changesDir, segments, normalizedName, isGroupBrief ? GROUP_BRIEF_FILENAME : void 0);
-  const path = join(changesDir, ...segments.slice(0, -1), isGroupBrief ? GROUP_BRIEF_FILENAME : `${segments.at(-1)}.md`);
+  const path = join2(changesDir, ...segments.slice(0, -1), isGroupBrief ? GROUP_BRIEF_FILENAME : `${segments.at(-1)}.md`);
   const ref = segments.length === 1 ? { kind: "change", name: normalizedName, path, group: null } : isGroupBrief ? { kind: "group-brief", name: normalizedName, path, group: segments[0] } : { kind: "group-change", name: normalizedName, path, group: segments[0] };
   if (ref.kind === "group-change" && options.executable !== false)
     assertGroupBrief(changesDir, ref);
@@ -115,7 +230,7 @@ function resolveWorkRef(name, options = {}) {
   return ref;
 }
 function assertGroupBrief(changesDir, ref) {
-  const briefPath = join(changesDir, ref.group, GROUP_BRIEF_FILENAME);
+  const briefPath = join2(changesDir, ref.group, GROUP_BRIEF_FILENAME);
   const kind = getPathKind(briefPath, ref.name);
   if (kind === "missing") {
     throw new WorkRefError(
@@ -159,7 +274,7 @@ function assertRegularWorkFile(ref, mustExist) {
 }
 function resolveWorkRefPath(path, options = {}) {
   const changesDir = options.changesDir ?? CHANGES_DIR;
-  const logicalPath = normalizeLogicalPath2(relative(changesDir, path));
+  const logicalPath = normalizeLogicalPath2(relative2(changesDir, path));
   if (isAbsolute(logicalPath) || logicalPath === ".." || logicalPath.startsWith("../") || !logicalPath.endsWith(".md")) {
     throw new WorkRefError(
       "invalid_work_ref_path",
@@ -187,13 +302,13 @@ function resolveFocusMarkerPath(ref, options = {}) {
   assertNoManagedNormalizationCollision(focusDir, ref.name.split("/"), ref.name, "invalid_focus_path");
   if (ref.group) {
     assertOptionalManagedDirectory(
-      join(focusDir, ref.group),
+      join2(focusDir, ref.group),
       ref.name,
       "invalid_focus_path",
       "focus path"
     );
   }
-  const markerPath = join(focusDir, ...ref.name.split("/"));
+  const markerPath = join2(focusDir, ...ref.name.split("/"));
   try {
     requireManagedFile(markerPath, "focus marker", { allowMissing: true });
   } catch (error) {
@@ -209,7 +324,7 @@ function resolveArchiveDirectory(ref, options = {}) {
   if (!ref.group)
     return archivesDir;
   assertNoManagedNormalizationCollision(archivesDir, [ref.group], ref.name, "invalid_archive_path");
-  const groupPath = join(archivesDir, ref.group);
+  const groupPath = join2(archivesDir, ref.group);
   assertOptionalManagedDirectory(groupPath, ref.name, "invalid_archive_path", "archive path");
   return groupPath;
 }
@@ -228,7 +343,7 @@ async function inspectFocusTree(options = {}) {
   if (!rootEntries)
     return result;
   for (const entry of rootEntries) {
-    const path = join(focusDir, entry.name);
+    const path = join2(focusDir, entry.name);
     if (entry.name === ".gitkeep" && entry.isFile())
       continue;
     if (entry.isDirectory()) {
@@ -271,7 +386,7 @@ async function inspectArchiveTree(options = {}) {
   if (!rootEntries)
     return result;
   for (const entry of rootEntries) {
-    const path = join(archivesDir, entry.name);
+    const path = join2(archivesDir, entry.name);
     if (entry.name === "INDEX.md" && entry.isFile())
       continue;
     if (entry.isDirectory()) {
@@ -309,7 +424,7 @@ async function inspectWorkTree(options = {}) {
   const rootMarkdownNames = new Set(rootEntries.filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name.slice(0, -3)));
   const collidingGroups = new Set([...rootDirectories].filter((name) => rootMarkdownNames.has(name)));
   for (const entry of rootEntries) {
-    const path = join(changesDir, entry.name);
+    const path = join2(changesDir, entry.name);
     if (entry.name === ".gitkeep" && entry.isFile())
       continue;
     if (entry.isDirectory()) {
@@ -356,17 +471,17 @@ async function inspectGroupDirectory(group, groupPath, changesDir, result, colli
       "group_brief_missing",
       `Change Group "${group}" requires a Group Brief; run: rsp group create ${group}`,
       group
-    ), join(groupPath, GROUP_BRIEF_FILENAME));
+    ), join2(groupPath, GROUP_BRIEF_FILENAME));
   } else if (!briefEntry.isFile()) {
     addDiagnostic(result, new WorkRefError(
       "work_ref_not_file",
-      `Group Brief must be a regular file: ${join(groupPath, GROUP_BRIEF_FILENAME)}`,
+      `Group Brief must be a regular file: ${join2(groupPath, GROUP_BRIEF_FILENAME)}`,
       group
-    ), join(groupPath, GROUP_BRIEF_FILENAME));
+    ), join2(groupPath, GROUP_BRIEF_FILENAME));
   }
   for (const entry of entries) {
     const input = `${group}/${entry.name}`;
-    const path = join(groupPath, entry.name);
+    const path = join2(groupPath, entry.name);
     if (entry.name === GROUP_BRIEF_FILENAME && !entry.isFile())
       continue;
     if (entry.name === "brief.md") {
@@ -395,7 +510,7 @@ async function inspectFocusGroup(group, groupPath, changesDir, result) {
     return;
   for (const entry of entries) {
     const input = `${group}/${entry.name}`;
-    const path = join(groupPath, entry.name);
+    const path = join2(groupPath, entry.name);
     if (entry.isDirectory()) {
       addDiagnostic(result, new WorkRefError(
         "unsupported_work_depth",
@@ -421,7 +536,7 @@ async function inspectArchiveGroup(group, groupPath, result) {
     return;
   for (const entry of entries) {
     const input = `${group}/${entry.name}`;
-    const path = join(groupPath, entry.name);
+    const path = join2(groupPath, entry.name);
     if (!entry.isFile() || !entry.name.endsWith(".md")) {
       addArchivePathDiagnostic(result, input, path);
       continue;
@@ -454,7 +569,7 @@ function collectResolvedPath(path, changesDir, result) {
 }
 async function readDirectory(path, input, result) {
   try {
-    return (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    return (await readdir2(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
   } catch (error) {
     addDiagnostic(result, asReadFailure(path, input, error), path);
     return null;
@@ -515,7 +630,7 @@ function normalizeWorkRefName(name, allowGroupBrief) {
 }
 function assertNoNormalizationCollision(changesDir, segments, input, isGroupBrief) {
   for (let depth = 0; depth < segments.length; depth++) {
-    const parent = join(changesDir, ...segments.slice(0, depth));
+    const parent = join2(changesDir, ...segments.slice(0, depth));
     const parentKind = getPathKind(parent, input);
     if (parentKind === "missing")
       return;
@@ -548,7 +663,7 @@ function assertNoNormalizationCollision(changesDir, segments, input, isGroupBrie
 }
 function assertNoManagedNormalizationCollision(root, segments, input, code) {
   for (let depth = 0; depth < segments.length; depth++) {
-    const parent = join(root, ...segments.slice(0, depth));
+    const parent = join2(root, ...segments.slice(0, depth));
     const parentKind = getPathKind(parent, input);
     if (parentKind === "missing")
       return;
@@ -573,8 +688,8 @@ function assertNoManagedNormalizationCollision(root, segments, input, code) {
 }
 function assertNoIdentityCollision(changesDir, segments, input, finalFilename) {
   for (let depth = 1; depth <= segments.length; depth++) {
-    const identityPath = join(changesDir, ...segments.slice(0, depth));
-    const filePath = finalFilename && depth === segments.length ? join(changesDir, ...segments.slice(0, -1), finalFilename) : `${identityPath}.md`;
+    const identityPath = join2(changesDir, ...segments.slice(0, depth));
+    const filePath = finalFilename && depth === segments.length ? join2(changesDir, ...segments.slice(0, -1), finalFilename) : `${identityPath}.md`;
     const fileKind = getPathKind(filePath, input);
     const identityKind = getPathKind(identityPath, input);
     const isPrefix = depth < segments.length;
@@ -753,12 +868,12 @@ async function inspectChangeGroups(options = {}) {
   const archivedGroupBriefPaths = /* @__PURE__ */ new Map();
   const openGroupNames = new Set(workTree.briefs.map((brief) => brief.group));
   for (const path of archiveTree.files) {
-    const archivePath = normalizeLogicalPath(relative2(ARCHIVES_DIR, path));
+    const archivePath = normalizeLogicalPath(relative3(ARCHIVES_DIR, path));
     const archiveGroup = archivePath.includes("/") ? archivePath.split("/")[0] : null;
     if (!archiveGroup || !openGroupNames.has(archiveGroup))
       continue;
     try {
-      const content = await readFile(path, "utf-8");
+      const content = await readFile2(path, "utf-8");
       const archivedChange = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
       const identity = getDocumentTitle(archivedChange, "identity");
       if (identity?.includes("/")) {
@@ -799,7 +914,7 @@ async function inspectChangeGroups(options = {}) {
   for (const brief of workTree.briefs) {
     let content;
     try {
-      content = await readFile(brief.path, "utf-8");
+      content = await readFile2(brief.path, "utf-8");
     } catch (error) {
       diagnostics.push({
         severity: "error",
@@ -828,7 +943,7 @@ async function inspectChangeGroups(options = {}) {
     for (const diagnostic of archiveTree.diagnostics.filter((item) => {
       if (item.code === "invalid_archive_root")
         return true;
-      const archivePath = normalizeLogicalPath(relative2(ARCHIVES_DIR, item.path));
+      const archivePath = normalizeLogicalPath(relative3(ARCHIVES_DIR, item.path));
       return archivePath === brief.group || archivePath.startsWith(`${brief.group}/`);
     })) {
       diagnostics.push({
@@ -919,10 +1034,10 @@ function hasExplicitGroupReopenEvidence(content, retainedEvidence, retainedGroup
   return getGroupReopenEvidence(content).some((item) => item.active && retainedGroupBriefPaths.has(item.sourcePath) && !retainedEvidence.has(item.key));
 }
 async function requireDeclaredGroupSlice(ref) {
-  const briefPath = join2(dirname(ref.path), GROUP_BRIEF_FILENAME);
+  const briefPath = join3(dirname2(ref.path), GROUP_BRIEF_FILENAME);
   let content;
   try {
-    content = await readFile(briefPath, "utf-8");
+    content = await readFile2(briefPath, "utf-8");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new WorkRefError("work_tree_read_failed", `unable to read Group Brief ${briefPath}: ${message}`, ref.name);
@@ -952,11 +1067,11 @@ async function hasArchivedGroupBrief(group) {
   }
   const groupPrefix = `${group}/`;
   for (const path of archiveTree.files) {
-    if (!normalizeLogicalPath(relative2(ARCHIVES_DIR, path)).startsWith(groupPrefix))
+    if (!normalizeLogicalPath(relative3(ARCHIVES_DIR, path)).startsWith(groupPrefix))
       continue;
     let content;
     try {
-      content = await readFile(path, "utf-8");
+      content = await readFile2(path, "utf-8");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new WorkRefError("work_tree_read_failed", `unable to inspect archived Change Group identity at ${path}: ${message}`, group);
@@ -1029,14 +1144,187 @@ function groupSectionHeading(sectionId) {
 }
 
 // src/core/dependency-plan.ts
-import { readFile as readFile4 } from "fs/promises";
-
-// src/history/query.ts
 import { readFile as readFile3 } from "fs/promises";
 
+// src/history/current-file.ts
+import { Buffer as Buffer2 } from "buffer";
+import { constants } from "fs";
+import { lstat, open, realpath } from "fs/promises";
+import { isAbsolute as isAbsolute2, relative as relative4, resolve, sep as sep2 } from "path";
+
+// src/history/model.ts
+var HISTORY_DEFAULT_LIMIT = 20;
+var HISTORY_MAX_LIMIT = 100;
+var HISTORY_MAX_TEXT_CODE_POINTS = 500;
+var HISTORY_MAX_EVIDENCE_ITEMS = 20;
+var HISTORY_MAX_DIAGNOSTICS = 20;
+var HISTORY_MAX_CANDIDATES = 20;
+var HISTORY_MAX_FILE_BYTES = 512 * 1024;
+var ArchiveHistoryError = class extends Error {
+  constructor(code, message, candidates = []) {
+    super(message);
+    this.code = code;
+    this.name = "ArchiveHistoryError";
+    const ordered = [...candidates].sort();
+    this.candidateTotal = ordered.length;
+    this.candidates = ordered.slice(0, HISTORY_MAX_CANDIDATES);
+    this.candidatesTruncated = this.candidateTotal > this.candidates.length;
+  }
+  code;
+  candidates;
+  candidateTotal;
+  candidatesTruncated;
+};
+
+// src/history/current-file.ts
+var READ_NO_FOLLOW_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
+async function readCurrentArchiveFile(options) {
+  const sourcePath = resolve(options.sourcePath);
+  const archivesDir = resolve(options.archivesDir);
+  const relativePath = relative4(archivesDir, sourcePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep2}`) || isAbsolute2(relativePath)) {
+    throw changed(options.projectPath);
+  }
+  let inspectedRoot;
+  let inspected;
+  let realArchivesDir;
+  try {
+    inspectedRoot = await lstat(archivesDir, { bigint: true });
+    if (!inspectedRoot.isDirectory())
+      throw changed(options.projectPath);
+    inspected = await lstat(sourcePath, { bigint: true });
+    realArchivesDir = await realpath(archivesDir);
+    const resolvedSource = await realpath(sourcePath);
+    const expectedSource = resolve(realArchivesDir, relativePath);
+    if (!inspected.isFile() || resolvedSource !== expectedSource || !isContained(realArchivesDir, resolvedSource)) {
+      throw changed(options.projectPath);
+    }
+  } catch (error) {
+    if (error instanceof ArchiveHistoryError)
+      throw error;
+    if (isPermissionError(error))
+      throw readFailed(options.projectPath);
+    throw changed(options.projectPath);
+  }
+  let handle;
+  try {
+    handle = await open(sourcePath, READ_NO_FOLLOW_FLAGS);
+  } catch (error) {
+    if (isPermissionError(error))
+      throw readFailed(options.projectPath);
+    throw changed(options.projectPath);
+  }
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const currentRoot = await realpath(archivesDir);
+    const currentSource = await realpath(sourcePath);
+    if (!opened.isFile() || currentRoot !== realArchivesDir || currentSource !== resolve(currentRoot, relativePath) || !isContained(currentRoot, currentSource) || !sameIdentity(inspected, opened) || !sameSnapshot(inspected, opened)) {
+      throw changed(options.projectPath);
+    }
+    if (opened.size > BigInt(options.maxFileBytes))
+      throw tooLarge(options.projectPath, options.maxFileBytes);
+    if (options.expectedSnapshot !== void 0 && !sameFileSnapshot(options.expectedSnapshot, opened)) {
+      throw changed(options.projectPath);
+    }
+    const content = await readBoundedArchive(handle, opened, options.projectPath, options.maxFileBytes);
+    await validateCurrentArchivePath({
+      sourcePath,
+      archivesDir,
+      relativePath,
+      realArchivesDir,
+      inspectedRoot,
+      finalHandle: content.final,
+      projectPath: options.projectPath
+    });
+    return {
+      sourcePath,
+      archivesDir,
+      content: content.content,
+      bytes: content.bytes,
+      snapshot: {
+        device: content.final.dev,
+        inode: content.final.ino,
+        size: content.final.size,
+        mtimeNs: content.final.mtimeNs,
+        ctimeNs: content.final.ctimeNs
+      }
+    };
+  } catch (error) {
+    if (error instanceof ArchiveHistoryError)
+      throw error;
+    throw changed(options.projectPath);
+  } finally {
+    await handle.close();
+  }
+}
+async function readBoundedArchive(handle, opened, projectPath, maxFileBytes) {
+  const buffer = Buffer2.allocUnsafe(maxFileBytes + 1);
+  let bytes = 0;
+  while (bytes < buffer.length) {
+    const result = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+    if (result.bytesRead === 0)
+      break;
+    bytes += result.bytesRead;
+  }
+  const final = await handle.stat({ bigint: true });
+  if (bytes > maxFileBytes || final.size > BigInt(maxFileBytes))
+    throw tooLarge(projectPath, maxFileBytes);
+  if (!sameIdentity(opened, final) || !sameSnapshot(opened, final) || final.size !== BigInt(bytes)) {
+    throw changed(projectPath);
+  }
+  return {
+    content: buffer.subarray(0, bytes).toString("utf-8"),
+    bytes,
+    final
+  };
+}
+async function validateCurrentArchivePath(options) {
+  const currentRoot = await lstat(options.archivesDir, { bigint: true });
+  const currentSource = await lstat(options.sourcePath, { bigint: true });
+  const realCurrentRoot = await realpath(options.archivesDir);
+  const realCurrentSource = await realpath(options.sourcePath);
+  if (!currentRoot.isDirectory() || !currentSource.isFile() || !sameIdentity(options.inspectedRoot, currentRoot) || realCurrentRoot !== options.realArchivesDir || realCurrentSource !== resolve(realCurrentRoot, options.relativePath) || !isContained(realCurrentRoot, realCurrentSource) || !sameIdentity(currentSource, options.finalHandle) || !sameSnapshot(currentSource, options.finalHandle)) {
+    throw changed(options.projectPath);
+  }
+}
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+  return left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function sameFileSnapshot(left, right) {
+  return left.device === right.dev && left.inode === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function isContained(root, path) {
+  const candidate = relative4(root, path);
+  return candidate !== "" && candidate !== ".." && !candidate.startsWith(`..${sep2}`) && !isAbsolute2(candidate);
+}
+function changed(projectPath) {
+  return new ArchiveHistoryError(
+    "archive_file_changed",
+    `archived Change is no longer the inspected readable regular file: ${projectPath}`
+  );
+}
+function tooLarge(projectPath, maxFileBytes) {
+  return new ArchiveHistoryError(
+    "archive_file_too_large",
+    `archived Change exceeds the ${maxFileBytes}-byte inspection limit: ${projectPath}`
+  );
+}
+function readFailed(projectPath) {
+  return new ArchiveHistoryError(
+    "archive_read_failed",
+    `unable to read archived Change ${projectPath}`
+  );
+}
+function isPermissionError(error) {
+  const code = error.code;
+  return code === "EACCES" || code === "EPERM";
+}
+
 // src/history/inspect.ts
-import { readFile as readFile2 } from "fs/promises";
-import { basename, dirname as dirname2, relative as relative3 } from "path";
+import { basename as basename2, dirname as dirname3, relative as relative5, resolve as resolve2 } from "path";
 
 // src/core/issue-relationship.ts
 var ISSUE_RELATIONS = /* @__PURE__ */ new Set(["relates", "closes"]);
@@ -1101,33 +1389,11 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// src/history/model.ts
-var HISTORY_DEFAULT_LIMIT = 20;
-var HISTORY_MAX_LIMIT = 100;
-var HISTORY_MAX_TEXT_CODE_POINTS = 500;
-var HISTORY_MAX_EVIDENCE_ITEMS = 20;
-var HISTORY_MAX_DIAGNOSTICS = 20;
-var HISTORY_MAX_CANDIDATES = 20;
-var ArchiveHistoryError = class extends Error {
-  constructor(code, message, candidates = []) {
-    super(message);
-    this.code = code;
-    this.name = "ArchiveHistoryError";
-    const ordered = [...candidates].sort();
-    this.candidateTotal = ordered.length;
-    this.candidates = ordered.slice(0, HISTORY_MAX_CANDIDATES);
-    this.candidatesTruncated = this.candidateTotal > this.candidates.length;
-  }
-  code;
-  candidates;
-  candidateTotal;
-  candidatesTruncated;
-};
-
 // src/history/inspect.ts
 var ARCHIVE_NAME_RE = /^(\d{4}-\d{2}-\d{2})_(.+)\.md$/;
 async function inspectArchiveHistory(options = {}) {
-  const archivesDir = options.archivesDir ?? ARCHIVES_DIR;
+  const archivesDir = resolve2(options.archivesDir ?? ARCHIVES_DIR);
+  const maxFileBytes = options.maxFileBytes ?? HISTORY_MAX_FILE_BYTES;
   const tree = options.archiveTree ?? await inspectArchiveTree({ archivesDir });
   const diagnostics = tree.diagnostics.map((diagnostic) => ({
     severity: "error",
@@ -1148,15 +1414,21 @@ async function inspectArchiveHistory(options = {}) {
   }
   for (const sourcePath of tree.files) {
     const path = archiveOutputPath(sourcePath, archivesDir);
-    let content;
+    let current;
     try {
-      content = await readFile2(sourcePath, "utf-8");
+      current = await readCurrentArchiveFile({
+        sourcePath,
+        archivesDir,
+        projectPath: path,
+        maxFileBytes
+      });
     } catch (error) {
-      const message = toErrorMessage(error);
-      diagnostics.push({ severity: "error", code: "archive_read_failed", path, message: `unable to read archived work: ${message}` });
+      const code = error instanceof ArchiveHistoryError ? error.code : "archive_read_failed";
+      const message = error instanceof ArchiveHistoryError ? error.message : `unable to read archived work: ${toErrorMessage(error)}`;
+      diagnostics.push({ severity: "error", code, path, message });
       continue;
     }
-    const parsed = parseArchiveEntry(sourcePath, path, archivesDir, content);
+    const parsed = parseArchiveEntry(current, path, maxFileBytes);
     if (parsed.diagnostic)
       diagnostics.push(parsed.diagnostic);
     if (parsed.record)
@@ -1182,14 +1454,15 @@ async function inspectArchiveHistory(options = {}) {
     runtime
   };
 }
-function parseArchiveEntry(sourcePath, path, archivesDir, content) {
-  const nameMatch = basename(sourcePath).match(ARCHIVE_NAME_RE);
+function parseArchiveEntry(current, path, maxFileBytes) {
+  const { sourcePath, archivesDir, content } = current;
+  const nameMatch = basename2(sourcePath).match(ARCHIVE_NAME_RE);
   if (!nameMatch || !isCalendarDate(nameMatch[1])) {
     return { diagnostic: errorDiagnostic("archive_name_invalid", path, "archive filename must use a valid YYYY-MM-DD_name.md date") };
   }
   const date = nameMatch[1];
   const archiveStem = nameMatch[2];
-  const relativeDirectory = normalizeLogicalPath(relative3(archivesDir, dirname2(sourcePath)));
+  const relativeDirectory = normalizeLogicalPath(relative5(archivesDir, dirname3(sourcePath)));
   const archiveGroup = relativeDirectory === "." || relativeDirectory === "" ? null : relativeDirectory;
   if (archiveGroup && !isCanonicalWorkRefSegment(archiveGroup))
     return { diagnostic: errorDiagnostic("archive_identity_mismatch", path, "archive group path is not a valid one-segment Group identity") };
@@ -1248,6 +1521,9 @@ function parseArchiveEntry(sourcePath, path, archivesDir, content) {
       path,
       ...issues === void 0 ? {} : { issues },
       sourcePath,
+      archivesDir,
+      sourceSnapshot: current.snapshot,
+      maxFileBytes,
       searchSummary: rawSummary
     }
   };
@@ -1264,10 +1540,10 @@ function isCalendarDate(value) {
   return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
 }
 function archiveOutputPath(sourcePath, archivesDir) {
-  return `.rsp/archives/${normalizeLogicalPath(relative3(archivesDir, sourcePath))}`;
+  return `.rsp/archives/${normalizeLogicalPath(relative5(resolve2(archivesDir), resolve2(sourcePath)))}`;
 }
 function normalizeOutputPath(path, archivesDir) {
-  const relativePath = normalizeLogicalPath(relative3(archivesDir, path));
+  const relativePath = normalizeLogicalPath(relative5(resolve2(archivesDir), resolve2(path)));
   return relativePath === "" ? ".rsp/archives" : `.rsp/archives/${relativePath}`;
 }
 function errorDiagnostic(code, path, message) {
@@ -1348,17 +1624,28 @@ function selectArchivedGroupBrief(records, selector) {
   return matches[0];
 }
 async function readArchiveHistoryDetail(record) {
+  return (await readArchiveHistoryDocument(record)).detail;
+}
+async function readArchiveHistoryDocument(record) {
   let content;
   try {
-    content = await readFile3(record.sourcePath, "utf-8");
+    content = (await readCurrentArchiveFile({
+      sourcePath: record.sourcePath,
+      archivesDir: record.archivesDir,
+      projectPath: record.path,
+      maxFileBytes: record.maxFileBytes,
+      expectedSnapshot: record.sourceSnapshot
+    })).content;
   } catch (error) {
+    if (error instanceof ArchiveHistoryError)
+      throw error;
     throw new ArchiveHistoryError("archive_read_failed", `unable to read archived Change ${record.path}: ${error instanceof Error ? error.message : String(error)}`);
   }
   const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
   const tasks = getDocumentSectionBody(document, "tasks");
   const verify = getDocumentSectionBody(document, "verify");
   const blockers = getDocumentSectionBody(document, "blockers");
-  return {
+  const detail = {
     ...toOutputRecord(record),
     scenarioCount: parseScenarios(content).length,
     checkboxes: {
@@ -1371,12 +1658,20 @@ async function readArchiveHistoryDetail(record) {
       blockers: boundEvidence(blockers, true)
     }
   };
+  return { content, detail };
 }
 function historyInspectionComplete(inspection) {
   return inspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
 }
 function toOutputRecord(record) {
-  const { searchSummary: _searchSummary, sourcePath: _sourcePath, ...output } = record;
+  const {
+    searchSummary: _searchSummary,
+    sourcePath: _sourcePath,
+    archivesDir: _archivesDir,
+    sourceSnapshot: _sourceSnapshot,
+    maxFileBytes: _maxFileBytes,
+    ...output
+  } = record;
   return output;
 }
 function boundEvidence(section, omitNone = false) {
@@ -1398,7 +1693,6 @@ function compareHistoryRecords2(left, right) {
 }
 
 // src/core/dependency-plan.ts
-var NONE_BLOCKER_RE = /^[-*]\s*(?:none)?$/i;
 var REQUIRES_RE = /^[-*]\s+requires\s+`([^`]+)`:[ \t]*(\S.*)$/i;
 async function inspectChangeDependencies(options = {}) {
   const workTree = options.workTree ?? await inspectWorkTree();
@@ -1420,7 +1714,7 @@ async function inspectChangeDependencies(options = {}) {
     diagnostics.push(...archiveHistory.diagnostics);
   for (const brief of workTree.briefs) {
     try {
-      if (hasMeaningfulBlockers(await readFile4(brief.path, "utf-8")))
+      if (hasMeaningfulBlockers(await readFile3(brief.path, "utf-8")))
         blockedGroups.add(brief.group);
     } catch (error) {
       diagnostics.push({
@@ -1434,7 +1728,7 @@ async function inspectChangeDependencies(options = {}) {
   }
   for (const ref of workTree.changes) {
     try {
-      const parsed = parseDependencyBlockers(await readFile4(ref.path, "utf-8"));
+      const parsed = parseDependencyBlockers(await readFile3(ref.path, "utf-8"));
       if (ref.group && blockedGroups.has(ref.group))
         parsed.external = true;
       parsedByName.set(ref.name, parsed);
@@ -1540,7 +1834,7 @@ function parseDependencyBlockers(content) {
   let external = false;
   const malformed = [];
   for (const line of extractBlockerLines(content)) {
-    if (!line || NONE_BLOCKER_RE.test(line) || /^none$/i.test(line))
+    if (!line || isEmptyBlockerLine(line))
       continue;
     const dependency = line.match(REQUIRES_RE);
     if (dependency) {
@@ -1564,13 +1858,13 @@ function buildWaves(names, edges, blockersByName, preferredOrder) {
   const excluded = new Set(
     [...blockersByName].filter(([, blockers]) => blockers.external).map(([name]) => name)
   );
-  let changed = true;
-  while (changed) {
-    changed = false;
+  let changed2 = true;
+  while (changed2) {
+    changed2 = false;
     for (const edge of edges) {
       if ((edge.state === "missing" || excluded.has(edge.requires)) && !excluded.has(edge.change)) {
         excluded.add(edge.change);
-        changed = true;
+        changed2 = true;
       }
     }
   }
@@ -1648,6 +1942,82 @@ function findCycleDiagnostics(edges) {
   return diagnostics;
 }
 
+// src/core/readiness.ts
+function collectArchiveReadiness(content, options = {}) {
+  const warnings = [];
+  const documentDiagnostics = options.documentDiagnostics ?? [];
+  warnings.push(...documentDiagnostics.map((diagnostic) => diagnostic.message));
+  const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
+  const tasksSection = getDocumentSectionBody(document, "tasks");
+  const verifySection = getDocumentSectionBody(document, "verify");
+  const taskTodos = getOpenCheckboxes(tasksSection);
+  if (taskTodos.length > 0)
+    warnings.push(`${taskTodos.length} task item(s) still incomplete`);
+  const verifyCriticality = classifyVerifyCheckboxes(verifySection);
+  const verifyLines = collectVerifyCheckboxLines(verifySection);
+  const requiredVerifyTodos = getOpenCheckboxes([...verifyLines.required, ...verifyLines.unclassified].join("\n"));
+  const optionalVerifyTodos = getOpenCheckboxes(verifyLines.optional.join("\n"));
+  const verifyTodos = [...requiredVerifyTodos, ...optionalVerifyTodos];
+  if (requiredVerifyTodos.length > 0)
+    warnings.push(`${requiredVerifyTodos.length} required Verify item(s) are still incomplete`);
+  if (optionalVerifyTodos.length > 0)
+    warnings.push(`${optionalVerifyTodos.length} optional Verify item(s) are still incomplete`);
+  const activeBlockers = options.activeBlockers ?? hasMeaningfulBlockers(content);
+  if (activeBlockers)
+    warnings.push("active blockers are present in the change file");
+  const scenarios = parseScenarios(content);
+  const missingScenarios = scenarios.length === 0;
+  if (missingScenarios)
+    warnings.push("no Scenario blocks found (some changes do not need them)");
+  const archiveReady = documentDiagnostics.some((diagnostic) => diagnostic.severity === "error") || activeBlockers || taskTodos.length > 0 || requiredVerifyTodos.length > 0 ? "no" : "yes";
+  return {
+    taskTodos,
+    verifyTodos,
+    requiredVerifyTodos,
+    optionalVerifyTodos,
+    verifyCriticality,
+    activeBlockers,
+    scenarioCount: scenarios.length,
+    missingScenarios,
+    deterministic: warnings.length === 0 ? "pass" : "warnings",
+    semantic: "needs-review",
+    archiveReady,
+    warnings,
+    documentDiagnostics
+  };
+}
+function toArchiveReadinessOutput(readiness) {
+  return {
+    incompleteTasks: readiness.taskTodos.length,
+    incompleteVerify: readiness.verifyTodos.length,
+    incompleteRequiredVerify: readiness.requiredVerifyTodos.length,
+    incompleteOptionalVerify: readiness.optionalVerifyTodos.length,
+    requiredVerify: readiness.verifyCriticality.required,
+    optionalVerify: readiness.verifyCriticality.optional,
+    legacyVerify: readiness.verifyCriticality.legacy,
+    completionGate: readiness.archiveReady === "no" ? "blocked" : "pass",
+    coverageWarnings: readiness.optionalVerifyTodos.length,
+    activeBlockers: readiness.activeBlockers,
+    missingScenarios: readiness.missingScenarios,
+    deterministic: readiness.deterministic,
+    semantic: readiness.semantic,
+    archiveReady: readiness.archiveReady
+  };
+}
+function buildDurableReviewGuidance(factCandidateTargets, decisionRecordsPath) {
+  return {
+    required: true,
+    factDecisions: ["No current-fact update needed", "Update existing spec or scoped instruction", "Create a new durable spec"],
+    rationaleDecisions: ["No Decision Record needed", "Create or update a Decision Record"],
+    factCandidateTargets,
+    decisionRecordsPath,
+    note: "Semantic review decides current-fact and lasting-rationale updates independently. The CLI never infers scoped instruction or Decision Record filenames and never promotes Change content automatically."
+  };
+}
+function getDurableReviewCandidateTargets() {
+  return [".rsp/specs/design.md"];
+}
+
 // src/status/inspect.ts
 async function inspectProjectStatus(options = {}) {
   const runtime = [];
@@ -1746,7 +2116,7 @@ async function inspectProjectStatus(options = {}) {
     let issues = [];
     if (path) {
       try {
-        const content = await readFile5(path, "utf-8");
+        const content = await readFile4(path, "utf-8");
         title = extractChangeTitle(content) ?? name;
         summary = extractChangeSummary(content);
         blockerEntries = extractBlockerEntries(content);
@@ -1774,20 +2144,13 @@ async function inspectProjectStatus(options = {}) {
           });
         }
         isBlocked = dependencyInspection.activeBlockers.get(name) ?? hasMeaningfulBlockers(content);
-        const checkboxes = countCheckboxes(content);
-        done = checkboxes.done;
-        total = checkboxes.total;
-        progressKnown = true;
         const details = collectArchiveReadiness(content, { activeBlockers: isBlocked });
-        readiness = {
-          incompleteTasks: details.taskTodos.length,
-          incompleteVerify: details.verifyTodos.length,
-          activeBlockers: details.activeBlockers,
-          missingScenarios: details.missingScenarios,
-          deterministic: details.deterministic,
-          semantic: details.semantic,
-          archiveReady: details.archiveReady
-        };
+        const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
+        const taskCheckboxes = countCheckboxes(getDocumentSectionBody(document, "tasks"));
+        done = taskCheckboxes.done + details.verifyCriticality.required.done;
+        total = taskCheckboxes.total + details.verifyCriticality.required.total;
+        progressKnown = true;
+        readiness = toArchiveReadinessOutput(details);
       } catch (error) {
         diagnostics.push({
           severity: "error",
@@ -1874,6 +2237,13 @@ function emptyReadiness(activeBlockers) {
   return {
     incompleteTasks: 0,
     incompleteVerify: 0,
+    incompleteRequiredVerify: 0,
+    incompleteOptionalVerify: 0,
+    requiredVerify: { todo: 0, progress: 0, done: 0, dropped: 0, total: 0 },
+    optionalVerify: { todo: 0, progress: 0, done: 0, dropped: 0, total: 0 },
+    legacyVerify: false,
+    completionGate: activeBlockers ? "blocked" : "pass",
+    coverageWarnings: 0,
     activeBlockers,
     missingScenarios: false,
     deterministic: "pass",
@@ -1897,6 +2267,670 @@ function deriveArchiveTrend(records) {
   return [...counts].sort(([left], [right]) => left.localeCompare(right)).map(([month, count]) => ({ month, count }));
 }
 
+// src/specs/model.ts
+var SPECS_DEFAULT_RESULT_LIMIT = 20;
+var SPECS_MAX_RESULT_LIMIT = 100;
+var SPECS_MAX_CANDIDATES = 1e3;
+var SPECS_MAX_FILE_BYTES = 512 * 1024;
+var SPECS_SEARCH_EXCERPT_CODE_POINTS = 240;
+var SPECS_DETAIL_CONTENT_CODE_POINTS = 12e3;
+var SPECS_MAX_DIAGNOSTICS = 20;
+
+// src/specs/query.ts
+import { Buffer as Buffer3 } from "buffer";
+import { spawnSync } from "child_process";
+import { constants as constants2 } from "fs";
+import { lstat as lstat2, open as open2, realpath as realpath2 } from "fs/promises";
+import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute3, join as join4, relative as relative6, resolve as resolve3, sep as sep3 } from "path";
+var SPECS_ROOT = join4(RSP_DIR, "specs");
+var GENERATED_INDEX_FILENAME = "00-index.md";
+var LEGACY_GENERATED_INDEX_FILENAME = "INDEX.md";
+var READ_NO_FOLLOW_FLAGS2 = constants2.O_RDONLY | (constants2.O_NOFOLLOW ?? 0);
+var SpecsQueryError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SpecsQueryError";
+  }
+  code;
+};
+async function inspectSpecs(options = {}) {
+  const projectRoot = await realpath2(resolve3(options.cwd ?? process.cwd()));
+  const specsRoot = resolve3(projectRoot, SPECS_ROOT);
+  const maxCandidates = options.maxCandidates ?? SPECS_MAX_CANDIDATES;
+  const maxFileBytes = options.maxFileBytes ?? SPECS_MAX_FILE_BYTES;
+  validatePositiveBound(maxCandidates, "maxCandidates");
+  validatePositiveBound(maxFileBytes, "maxFileBytes");
+  const configInspection = await inspectRspConfig(projectRoot);
+  if (configInspection.issues.length > 0)
+    throw new SpecsQueryError("invalid_config", configInspection.issues.join("; "));
+  const decisionRecordsPath = resolveDecisionRecordsPath(configInspection.config);
+  const decisionPathIssue = await validateDecisionRecordsFilesystemPath(decisionRecordsPath, projectRoot);
+  if (decisionPathIssue)
+    throw new SpecsQueryError("invalid_decision_records_path", decisionPathIssue);
+  const decisionRecordsRoot = resolve3(projectRoot, decisionRecordsPath);
+  const accumulator = {
+    documents: [],
+    generatedIndexes: [],
+    diagnostics: [],
+    candidateCount: 0,
+    candidateLimitReported: false
+  };
+  const excludedSpecDirectories = [DEFAULT_DECISION_RECORDS_PATH, decisionRecordsPath].map((path) => resolve3(projectRoot, path)).filter((path) => isInside(specsRoot, path));
+  await inspectDocumentRoot({
+    projectRoot,
+    root: specsRoot,
+    label: "Specs",
+    kind: "spec",
+    excludedDirectories: excludedSpecDirectories,
+    accumulator,
+    maxCandidates,
+    maxFileBytes,
+    allowMissing: false
+  });
+  await inspectDocumentRoot({
+    projectRoot,
+    root: decisionRecordsRoot,
+    label: "Decision Records",
+    kind: "decision-record",
+    excludedDirectories: [],
+    accumulator,
+    maxCandidates,
+    maxFileBytes,
+    allowMissing: options.allowMissingDecisionRecords === true
+  });
+  detectPathCollisions(accumulator);
+  accumulator.documents.sort(compareDocument);
+  accumulator.generatedIndexes.sort((left, right) => left.path.localeCompare(right.path));
+  const boundedDiagnostics = accumulator.diagnostics.slice(0, SPECS_MAX_DIAGNOSTICS);
+  return {
+    source: await inspectSourceIdentity(projectRoot),
+    roots: {
+      specs: toProjectPath(projectRoot, specsRoot),
+      decisions: toProjectPath(projectRoot, decisionRecordsRoot)
+    },
+    tree: buildDirectoryTree(projectRoot, specsRoot, "spec", accumulator.documents),
+    decisionRecords: buildDirectoryTree(projectRoot, decisionRecordsRoot, "decision-record", accumulator.documents),
+    documents: accumulator.documents.map(stripSource),
+    generatedIndexes: accumulator.generatedIndexes,
+    diagnostics: boundedDiagnostics,
+    diagnosticSummary: {
+      total: accumulator.diagnostics.length,
+      returned: boundedDiagnostics.length,
+      hasMore: accumulator.diagnostics.length > boundedDiagnostics.length
+    },
+    runtime: [],
+    limits: {
+      candidates: maxCandidates,
+      fileBytes: maxFileBytes,
+      results: SPECS_MAX_RESULT_LIMIT,
+      searchExcerptCodePoints: SPECS_SEARCH_EXCERPT_CODE_POINTS,
+      detailContentCodePoints: SPECS_DETAIL_CONTENT_CODE_POINTS
+    }
+  };
+}
+function specsInspectionComplete(inspection) {
+  return inspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+}
+async function readSpecsDetail(inspection, projectPath) {
+  const current = await readCurrentSpecsDocument(inspection, projectPath);
+  const bounded = boundCodePoints(current.content, SPECS_DETAIL_CONTENT_CODE_POINTS);
+  return {
+    ...current,
+    content: bounded.value,
+    contentTruncated: bounded.truncated
+  };
+}
+async function readCurrentSpecsDocument(inspection, projectPath) {
+  const normalized = normalizeRequestedPath(projectPath);
+  const document = inspection.documents.find((candidate) => candidate.path === normalized);
+  if (!document)
+    throw new SpecsQueryError("specs_document_not_found", `Specs document not found: ${projectPath}`);
+  const sourcePath = resolve3(inspection.source.root, normalized);
+  const current = await readCurrentDocument(
+    sourcePath,
+    inspection.source.root,
+    document.path,
+    inspection.limits.fileBytes
+  );
+  const currentDocument = parseDocumentRecord(current.content, current.bytes, document.path, document.kind);
+  return {
+    ...currentDocument,
+    content: current.content
+  };
+}
+async function searchSpecs(inspection, literal, options = {}) {
+  return (await searchSpecsWithSources(inspection, literal, options)).result;
+}
+async function searchSpecsWithSources(inspection, literal, options = {}) {
+  const query = literal.trim();
+  if (query === "")
+    throw new SpecsQueryError("invalid_specs_search", "Specs search literal must be non-empty");
+  const limit = options.limit ?? 20;
+  if (!Number.isInteger(limit) || limit < 1 || limit > SPECS_MAX_RESULT_LIMIT)
+    throw new SpecsQueryError("invalid_specs_limit", `Specs search limit must be an integer from 1 through ${SPECS_MAX_RESULT_LIMIT}`);
+  const excerptCodePoints = options.excerptCodePoints ?? SPECS_SEARCH_EXCERPT_CODE_POINTS;
+  if (!Number.isInteger(excerptCodePoints) || excerptCodePoints < 40 || excerptCodePoints > 1e3)
+    throw new SpecsQueryError("invalid_specs_excerpt", "Specs search excerpt must be an integer from 40 through 1000 code points");
+  const lowered = query.toLowerCase();
+  const matches = [];
+  const documents = /* @__PURE__ */ new Map();
+  let matched = 0;
+  for (const document of inspection.documents) {
+    const current = await readCurrentDocument(
+      resolve3(inspection.source.root, document.path),
+      inspection.source.root,
+      document.path,
+      inspection.limits.fileBytes
+    );
+    const currentDocument = parseDocumentRecord(current.content, current.bytes, document.path, document.kind);
+    const lines = current.content.split(/\r?\n/);
+    let heading = null;
+    for (let index = 0; index < lines.length; index++) {
+      const parsedHeading = parseMarkdownHeading(lines[index]);
+      if (parsedHeading)
+        heading = parsedHeading.title;
+      const position = lines[index].toLowerCase().indexOf(lowered);
+      if (position < 0)
+        continue;
+      matched += 1;
+      if (matches.length < limit) {
+        if (!documents.has(document.path)) {
+          documents.set(document.path, {
+            ...currentDocument,
+            content: current.content
+          });
+        }
+        matches.push({
+          path: document.path,
+          kind: document.kind,
+          title: currentDocument.title,
+          heading,
+          line: index + 1,
+          excerpt: excerptAround(
+            lines[index],
+            [...lines[index].slice(0, position)].length,
+            [...query].length,
+            excerptCodePoints
+          )
+        });
+      }
+    }
+  }
+  return {
+    result: {
+      matches,
+      summary: {
+        candidates: inspection.documents.length,
+        searched: inspection.documents.length,
+        matched,
+        returned: matches.length,
+        hasMore: matched > matches.length
+      }
+    },
+    documents
+  };
+}
+async function inspectDocumentRoot(options) {
+  const inspection = await inspectManagedFileTree(options.root, options.label, { allowMissing: options.allowMissing });
+  for (const issue of inspection.issues) {
+    options.accumulator.diagnostics.push({
+      severity: "error",
+      code: "specs_tree_invalid",
+      path: toProjectPath(options.projectRoot, issue.path),
+      message: issue.message
+    });
+  }
+  if (!inspection.rootExists)
+    return;
+  for (const path of inspection.files) {
+    if (options.excludedDirectories.some((directory) => isInside(directory, path)))
+      continue;
+    const projectPath = toProjectPath(options.projectRoot, path);
+    const reserved = reservedIndexKind(options.root, path);
+    if (reserved) {
+      await classifyGeneratedIndex(path, options.projectRoot, projectPath, options.maxFileBytes, options.accumulator);
+      continue;
+    }
+    if (!path.endsWith(".md"))
+      continue;
+    options.accumulator.candidateCount += 1;
+    if (options.accumulator.candidateCount > options.maxCandidates) {
+      if (!options.accumulator.candidateLimitReported) {
+        options.accumulator.diagnostics.push({
+          severity: "error",
+          code: "specs_candidate_limit_exceeded",
+          path: projectPath,
+          message: `Specs candidate limit exceeded (${options.maxCandidates})`
+        });
+        options.accumulator.candidateLimitReported = true;
+      }
+      continue;
+    }
+    await inspectDocument(path, options.projectRoot, projectPath, options.kind, options.maxFileBytes, options.accumulator);
+  }
+}
+async function classifyGeneratedIndex(path, projectRoot, projectPath, maxFileBytes, accumulator) {
+  try {
+    const current = await readCurrentDocument(path, projectRoot, projectPath, maxFileBytes);
+    const recognized = isRecognizedGeneratedSpecsIndex(current.content, projectPath);
+    accumulator.generatedIndexes.push({
+      path: projectPath,
+      classification: recognized ? "safe-removal" : "owner-controlled",
+      reason: recognized ? "metadata recognizes the reserved path as a generated Specs index" : "reserved path content is not recognized generated Specs-index output"
+    });
+    if (!recognized) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "unrecognized_reserved_specs_index",
+        path: projectPath,
+        message: `reserved Specs index is owner-controlled and cannot be treated as generated content: ${projectPath}`
+      });
+    }
+  } catch (error) {
+    accumulator.generatedIndexes.push({
+      path: projectPath,
+      classification: "owner-controlled",
+      reason: "reserved path could not be boundedly inspected as generated Specs-index output"
+    });
+    accumulator.diagnostics.push({
+      severity: "error",
+      code: error instanceof SpecsQueryError ? error.code : "specs_index_read_failed",
+      path: projectPath,
+      message: `unable to inspect reserved Specs index ${projectPath}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+}
+function isRecognizedGeneratedSpecsIndex(content, projectPath) {
+  const metadata = parseFrontmatter(content);
+  const expectedSourceDirectory = normalizeLogicalPath(dirname4(projectPath));
+  return metadata?.kind === "generated-index" && metadata.index_type === "specs" && metadata.source_dir === expectedSourceDirectory;
+}
+async function inspectDocument(path, projectRoot, projectPath, kind, maxFileBytes, accumulator) {
+  try {
+    const current = await readCurrentDocument(path, projectRoot, projectPath, maxFileBytes);
+    const metadata = parseFrontmatter(current.content);
+    if (metadata?.kind === "generated-index")
+      return;
+    accumulator.documents.push({
+      sourcePath: path,
+      ...parseDocumentRecord(current.content, current.bytes, projectPath, kind)
+    });
+  } catch (error) {
+    accumulator.diagnostics.push({
+      severity: "error",
+      code: error instanceof SpecsQueryError ? error.code : "specs_file_read_failed",
+      path: projectPath,
+      message: `unable to read Specs document ${projectPath}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+}
+function detectPathCollisions(accumulator) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const document of accumulator.documents) {
+    const canonical = document.path.normalize("NFC");
+    const existing = seen.get(canonical);
+    if (existing && existing !== document.path) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "specs_path_collision",
+        path: document.path,
+        message: `Specs path normalization collision: ${existing} and ${document.path}`
+      });
+    } else {
+      seen.set(canonical, document.path);
+    }
+    if (canonical !== document.path) {
+      accumulator.diagnostics.push({
+        severity: "error",
+        code: "specs_path_not_canonical",
+        path: document.path,
+        message: `Specs path must use canonical NFC form: ${document.path}`
+      });
+    }
+  }
+}
+function buildDirectoryTree(projectRoot, root, kind, documents) {
+  const rootPath = toProjectPath(projectRoot, root);
+  const tree = {
+    name: basename3(root),
+    path: rootPath,
+    directories: [],
+    documents: []
+  };
+  for (const document of documents.filter((candidate) => candidate.kind === kind)) {
+    const rel = relative6(root, document.sourcePath);
+    if (rel === ".." || rel.startsWith(`..${sep3}`) || isAbsolute3(rel))
+      continue;
+    const segments = normalizeLogicalPath(rel).split("/");
+    let current = tree;
+    for (const segment of segments.slice(0, -1)) {
+      let child = current.directories.find((directory) => directory.name === segment);
+      if (!child) {
+        child = {
+          name: segment,
+          path: `${current.path}/${segment}`,
+          directories: [],
+          documents: []
+        };
+        current.directories.push(child);
+        current.directories.sort((left, right) => left.name.localeCompare(right.name));
+      }
+      current = child;
+    }
+    current.documents.push(stripSource(document));
+    current.documents.sort(compareDocument);
+  }
+  return tree;
+}
+function extractHeadings(content) {
+  const headings = [];
+  const lines = content.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    const heading = parseMarkdownHeading(lines[index]);
+    if (!heading)
+      continue;
+    headings.push({
+      depth: heading.depth,
+      title: heading.title,
+      line: index + 1
+    });
+  }
+  return headings;
+}
+function parseMarkdownHeading(line) {
+  let depth = 0;
+  while (depth < 6 && line[depth] === "#")
+    depth += 1;
+  if (depth === 0 || line[depth] === "#" || !isWhitespace(line[depth]))
+    return null;
+  let contentStart = depth;
+  while (contentStart < line.length && isWhitespace(line[contentStart]))
+    contentStart += 1;
+  if (contentStart === line.length)
+    return null;
+  const rawTitle = line.slice(contentStart);
+  let titleEnd = rawTitle.length;
+  while (titleEnd > 0 && isSpaceOrTab(rawTitle[titleEnd - 1]))
+    titleEnd -= 1;
+  let closingStart = titleEnd;
+  while (closingStart > 0 && rawTitle[closingStart - 1] === "#")
+    closingStart -= 1;
+  const closingPredecessor = closingStart === 0 ? line[contentStart - 1] : rawTitle[closingStart - 1];
+  if (closingStart < titleEnd && isSpaceOrTab(closingPredecessor)) {
+    titleEnd = closingStart;
+    while (titleEnd > 0 && isSpaceOrTab(rawTitle[titleEnd - 1]))
+      titleEnd -= 1;
+  }
+  const title = rawTitle.slice(0, titleEnd).trim();
+  return { depth, title };
+}
+function isWhitespace(character) {
+  return character !== void 0 && character.trim() === "";
+}
+function isSpaceOrTab(character) {
+  return character === " " || character === "	";
+}
+function extractSummary(content, frontmatterSummary) {
+  if (typeof frontmatterSummary === "string" && frontmatterSummary.trim() !== "")
+    return frontmatterSummary.trim();
+  const frontmatter = content.match(/^---\r?\n[\s\S]*?\r?\n(?:---|\.\.\.)\r?\n/);
+  const body = frontmatter ? content.slice(frontmatter[0].length) : content;
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith("<!--"))
+      continue;
+    return line.replace(/^[-*]\s*/, "").trim() || null;
+  }
+  return null;
+}
+async function inspectSourceIdentity(projectRoot) {
+  const root = normalizeLogicalPath(projectRoot);
+  const head = runGit(["rev-parse", "HEAD"], projectRoot);
+  const branch = runGit(["symbolic-ref", "--quiet", "--short", "HEAD"], projectRoot);
+  const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=normal"], {
+    cwd: root,
+    encoding: "utf-8",
+    maxBuffer: 256 * 1024
+  });
+  return {
+    root,
+    gitHead: head,
+    gitBranch: branch,
+    dirty: status.status === 0 ? status.stdout.trim() !== "" : status.error && status.error.code === "ENOBUFS" ? true : null
+  };
+}
+function runGit(args, cwd) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 });
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+function normalizeRequestedPath(pathValue) {
+  const trimmed = pathValue.trim();
+  if (trimmed === "")
+    throw new SpecsQueryError("invalid_specs_path", "Specs detail path must be non-empty");
+  const normalized = normalizeLogicalPath(trimmed.replace(/^\.\//, ""));
+  if (isAbsolute3(trimmed) || normalized === ".." || normalized.startsWith("../"))
+    throw new SpecsQueryError("invalid_specs_path", "Specs detail path must be one project-relative path returned by rsp specs");
+  return normalized;
+}
+function reservedIndexKind(root, path) {
+  if (basename3(path) === GENERATED_INDEX_FILENAME)
+    return "current";
+  if (path === join4(root, LEGACY_GENERATED_INDEX_FILENAME))
+    return "legacy";
+  return null;
+}
+function excerptAround(line, matchStart, matchLength, limit) {
+  const codePoints = [...line];
+  if (codePoints.length <= limit)
+    return codePoints.join("").trim();
+  const before = Math.max(0, matchStart - Math.floor((limit - matchLength) / 2));
+  const value = codePoints.slice(before, before + limit).join("").trim();
+  return `${before > 0 ? "\u2026" : ""}${value}${before + limit < codePoints.length ? "\u2026" : ""}`;
+}
+async function readCurrentDocument(path, root, projectPath, maxFileBytes) {
+  const changed2 = () => new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${projectPath}`);
+  const sourcePath = resolve3(path);
+  const sourceRoot = resolve3(root);
+  const relativePath = relative6(sourceRoot, sourcePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep3}`) || isAbsolute3(relativePath)) {
+    throw changed2();
+  }
+  const inspection = inspectManagedFile(sourcePath, "Specs document");
+  if (inspection.issue)
+    throw changed2();
+  let inspectedRoot;
+  let inspected;
+  let realRoot;
+  try {
+    inspectedRoot = await lstat2(sourceRoot, { bigint: true });
+    inspected = await lstat2(sourcePath, { bigint: true });
+    realRoot = await realpath2(sourceRoot);
+    const resolvedPath = await realpath2(sourcePath);
+    if (!inspectedRoot.isDirectory() || !inspected.isFile() || resolvedPath !== resolve3(realRoot, relativePath) || !isContained2(realRoot, resolvedPath)) {
+      throw changed2();
+    }
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed2();
+  }
+  let handle;
+  try {
+    handle = await open2(sourcePath, READ_NO_FOLLOW_FLAGS2);
+  } catch {
+    throw changed2();
+  }
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const currentRoot = await realpath2(sourceRoot);
+    const currentPath = await realpath2(sourcePath);
+    if (!opened.isFile() || currentRoot !== realRoot || currentPath !== resolve3(currentRoot, relativePath) || !isContained2(currentRoot, currentPath) || !sameIdentity2(inspected, opened) || !sameSnapshot2(inspected, opened)) {
+      throw changed2();
+    }
+    if (opened.size > BigInt(maxFileBytes))
+      throw new SpecsQueryError("specs_file_too_large", `Specs document exceeds the ${maxFileBytes}-byte inspection limit: ${projectPath}`);
+    const current = await readBoundedDocument(handle, opened, projectPath, maxFileBytes);
+    await validateCurrentSpecsPath({
+      sourcePath,
+      sourceRoot,
+      relativePath,
+      realRoot,
+      inspectedRoot,
+      finalHandle: current.final,
+      projectPath
+    });
+    return {
+      content: current.content,
+      bytes: current.bytes
+    };
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed2();
+  } finally {
+    await handle.close();
+  }
+}
+async function readBoundedDocument(handle, opened, projectPath, maxFileBytes) {
+  const buffer = Buffer3.allocUnsafe(maxFileBytes + 1);
+  let bytes = 0;
+  while (bytes < buffer.length) {
+    const result = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+    if (result.bytesRead === 0)
+      break;
+    bytes += result.bytesRead;
+  }
+  const final = await handle.stat({ bigint: true });
+  if (bytes > maxFileBytes || final.size > BigInt(maxFileBytes))
+    throw new SpecsQueryError("specs_file_too_large", `Specs document exceeds the ${maxFileBytes}-byte inspection limit: ${projectPath}`);
+  if (!sameIdentity2(opened, final) || !sameSnapshot2(opened, final) || final.size !== BigInt(bytes)) {
+    throw new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${projectPath}`);
+  }
+  return {
+    content: buffer.subarray(0, bytes).toString("utf-8"),
+    bytes,
+    final
+  };
+}
+async function validateCurrentSpecsPath(options) {
+  const changed2 = () => new SpecsQueryError("specs_file_changed", `Specs document is no longer a readable regular file: ${options.projectPath}`);
+  try {
+    const currentRoot = await lstat2(options.sourceRoot, { bigint: true });
+    const currentPath = await lstat2(options.sourcePath, { bigint: true });
+    const realCurrentRoot = await realpath2(options.sourceRoot);
+    const realCurrentPath = await realpath2(options.sourcePath);
+    if (!currentRoot.isDirectory() || !currentPath.isFile() || !sameIdentity2(options.inspectedRoot, currentRoot) || realCurrentRoot !== options.realRoot || realCurrentPath !== resolve3(realCurrentRoot, options.relativePath) || !isContained2(realCurrentRoot, realCurrentPath) || !sameIdentity2(currentPath, options.finalHandle) || !sameSnapshot2(currentPath, options.finalHandle)) {
+      throw changed2();
+    }
+  } catch (error) {
+    if (error instanceof SpecsQueryError)
+      throw error;
+    throw changed2();
+  }
+}
+function sameIdentity2(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot2(left, right) {
+  return left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function isContained2(root, path) {
+  const candidate = relative6(root, path);
+  return candidate !== "" && candidate !== ".." && !candidate.startsWith(`..${sep3}`) && !isAbsolute3(candidate);
+}
+function boundCodePoints(value, limit) {
+  const codePoints = [...value];
+  return {
+    value: codePoints.slice(0, limit).join(""),
+    truncated: codePoints.length > limit
+  };
+}
+function stripSource(document) {
+  const { sourcePath: _sourcePath, ...record } = document;
+  return record;
+}
+function parseDocumentRecord(content, bytes, path, kind) {
+  const metadata = parseFrontmatter(content);
+  const headings = extractHeadings(content);
+  return {
+    path,
+    kind,
+    title: typeof metadata?.title === "string" && metadata.title.trim() !== "" ? metadata.title.trim() : headings.find((heading) => heading.depth === 1)?.title ?? basename3(path, ".md"),
+    summary: extractSummary(content, metadata?.summary),
+    bytes,
+    headings
+  };
+}
+function compareDocument(left, right) {
+  return left.path.localeCompare(right.path);
+}
+function validatePositiveBound(value, label) {
+  if (!Number.isInteger(value) || value < 1)
+    throw new SpecsQueryError("invalid_specs_bound", `${label} must be a positive integer`);
+}
+function isInside(directory, path) {
+  const rel = relative6(directory, path);
+  return rel === "" || !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep3}`);
+}
+function toProjectPath(projectRoot, path) {
+  return normalizeLogicalPath(relative6(projectRoot, path)) || ".";
+}
+
+// src/specs/projection.ts
+function projectSpecsTree(inspection) {
+  assertCompleteInspection(inspection);
+  return {
+    ...projectionBase(inspection),
+    mode: "tree",
+    tree: inspection.tree,
+    decisionRecords: inspection.decisionRecords,
+    documents: inspection.documents
+  };
+}
+async function projectSpecsDetail(inspection, path) {
+  assertCompleteInspection(inspection);
+  return {
+    ...projectionBase(inspection),
+    mode: "detail",
+    document: await readSpecsDetail(inspection, path)
+  };
+}
+async function projectSpecsSearch(inspection, literal, options) {
+  assertCompleteInspection(inspection);
+  const result = await searchSpecs(inspection, literal, options);
+  return {
+    ...projectionBase(inspection),
+    mode: "search",
+    query: {
+      literal,
+      limit: options.limit,
+      excerptCodePoints: options.excerptCodePoints
+    },
+    matches: result.matches,
+    summary: result.summary
+  };
+}
+function assertCompleteInspection(inspection) {
+  if (!specsInspectionComplete(inspection)) {
+    throw new SpecsQueryError(
+      "specs_inspection_incomplete",
+      "Specs inspection is incomplete; resolve the reported diagnostics before using the projection"
+    );
+  }
+}
+function projectionBase(inspection) {
+  return {
+    source: inspection.source,
+    roots: inspection.roots,
+    generatedIndexes: inspection.generatedIndexes,
+    diagnostics: inspection.diagnostics,
+    diagnosticSummary: inspection.diagnosticSummary,
+    runtime: inspection.runtime,
+    limits: inspection.limits
+  };
+}
+
 // src/status/dependency-forest.ts
 function defaultRoots(plan) {
   const selected = new Set(plan.nodes.filter((node) => node.selection === "selected").map((node) => node.name));
@@ -1933,11 +2967,22 @@ function projectDependencyForest(plan, requestedRoots = defaultRoots(plan)) {
 }
 
 export {
+  IssueRelationshipError,
+  parseIssueRelationships,
+  createIssueRelationship,
+  walkMarkdownFiles,
+  inspectUnsupportedRules,
+  normalizeLogicalPath,
+  isValidSpecName,
+  guardRspInitialized,
+  cleanupEmptyParentDirs,
+  detectProjectName,
   GROUP_BRIEF_FILENAME,
   WorkRefError,
   normalizeWorkRefSegment,
   normalizeExecutableWorkRef,
   resolveWorkRef,
+  resolveWorkRefPath,
   resolveFocusMarkerPath,
   resolveArchiveDirectory,
   inspectFocusTree,
@@ -1949,9 +2994,6 @@ export {
   inspectChangeGroups,
   getGroupReopenEvidence,
   hasArchivedGroupBrief,
-  IssueRelationshipError,
-  parseIssueRelationships,
-  createIssueRelationship,
   HISTORY_DEFAULT_LIMIT,
   HISTORY_MAX_LIMIT,
   ArchiveHistoryError,
@@ -1960,8 +3002,25 @@ export {
   selectArchiveHistoryRecord,
   selectArchivedGroupBrief,
   readArchiveHistoryDetail,
+  readArchiveHistoryDocument,
   historyInspectionComplete,
   inspectChangeDependencies,
+  SPECS_DEFAULT_RESULT_LIMIT,
+  SPECS_MAX_RESULT_LIMIT,
+  SPECS_MAX_FILE_BYTES,
+  SPECS_SEARCH_EXCERPT_CODE_POINTS,
+  SPECS_DETAIL_CONTENT_CODE_POINTS,
+  SpecsQueryError,
+  inspectSpecs,
+  specsInspectionComplete,
+  isRecognizedGeneratedSpecsIndex,
+  collectArchiveReadiness,
+  toArchiveReadinessOutput,
+  buildDurableReviewGuidance,
+  getDurableReviewCandidateTargets,
+  projectSpecsTree,
+  projectSpecsDetail,
+  projectSpecsSearch,
   inspectProjectStatus,
   projectDependencyForest
 };