@oevery/rsp 1.0.3 → 1.2.0

package/dist/cli.mjs

@@ -5,10 +5,10 @@ import { resolve } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { defineCommand, runMain } from "citty";
 
-// src/commands/archive-index.ts
+// src/commands/add-rules.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
-import { basename, dirname as dirname2, join as join3, relative as relative2 } from "path";
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { basename, dirname as dirname2, join as join3 } from "path";
 
 // src/core/config.ts
 import { existsSync as existsSync2 } from "fs";
@@ -21,6 +21,8 @@ import pc from "picocolors";
 import { existsSync } from "fs";
 import { readdir, stat } from "fs/promises";
 import { join, relative } from "path";
+var RSP_AGENTS_BEGIN = "<!-- rsp:begin -->";
+var RSP_AGENTS_END = "<!-- rsp:end -->";
 function parseYamlLines(lines) {
   const result = {};
   let currentKey = null;
@@ -59,7 +61,7 @@ function parseYamlLines(lines) {
   return result;
 }
 function parseFrontmatter(content) {
-  const m = content.match(/^---\n([\s\S]*?)\n(?:---|\.\.\.)\n/);
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\r?\n/);
   if (!m)
     return null;
   return parseYamlLines(m[1].split("\n"));
@@ -76,6 +78,8 @@ async function walkMarkdownFiles(dir) {
   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 walkMarkdownFiles(filePath));
@@ -91,6 +95,8 @@ async function walkFiles(dir) {
   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));
@@ -106,17 +112,51 @@ function featureNameFromPath(featuresDir, filePath) {
   return rel.replace(/\.md$/, "");
 }
 function generateFeatureContent(name, summary = "") {
+  if (name === "project-setup") {
+    return `---
+status: draft
+priority: medium
+tags:
+---
+
+# Feature: project-setup
+
+## Spec
+- Summary: ${summary || "Capture the project model, boundaries, and stable local constraints"}
+- Requirements:
+  - Project purpose, scope, and structure are reflected in .rsp/specs/design.md
+  - Stable validation or workflow constraints are reflected in .rsp/rules/project-rules.md when needed
+- Constraints:
+  - Avoid duplicating durable project facts across feature notes, specs, and rules
+
+## Plan
+- [ ] Review the repository structure, entrypoints, and primary outputs
+- [ ] Fill .rsp/specs/design.md with durable architecture facts
+- [ ] Add .rsp/rules/project-rules.md if stable local rules or validation steps exist
+
+## Tests
+- [ ] Run rsp doctor
+- [ ] Run project-native validation if available
+
+## Notes (optional)
+- <facts discovered during project setup>
+
+## Blockers
+-
+`;
+  }
   return `---
 status: draft
 priority: medium
 tags:
 ---
+
 # Feature: ${name}
 
 ## Spec
 - Summary: ${summary || "<one-line summary>"}
 - Requirements:
-  - [ ] <verifiable requirement>
+  - <verifiable requirement>
 - Constraints:
   -
 
@@ -134,6 +174,111 @@ tags:
 -
 `;
 }
+function renderRspAgentsBlock() {
+  return `${RSP_AGENTS_BEGIN}
+## RSP Entry
+
+Read in order:
+1. .rsp/rules/*.md
+2. .rsp/specs/INDEX.md
+3. .rsp/specs/design.md
+4. .rsp/active.d/ and matching .rsp/features/*.md
+
+Guidelines:
+- .rsp/rules/rsp-rules.md is required
+- .rsp/rules/project-rules.md is optional
+- Keep project design in .rsp/specs/
+- Add extra spec files only when they have durable value
+${RSP_AGENTS_END}`;
+}
+function upsertRspAgentsBlock(content) {
+  const block = renderRspAgentsBlock();
+  const managedRe = /<!-- rsp:begin -->[\s\S]*?<!-- rsp:end -->/;
+  if (managedRe.test(content)) {
+    const next2 = content.replace(managedRe, block);
+    return { content: next2, changed: next2 !== content };
+  }
+  const trimmed = content.trimStart();
+  const next = trimmed ? `${block}
+
+${trimmed}` : `${block}
+`;
+  return { content: next, changed: true };
+}
+function hasRspAgentsBlock(content) {
+  return content.includes(RSP_AGENTS_BEGIN) && content.includes(RSP_AGENTS_END);
+}
+function generateDesignContent(projectName) {
+  return `# Project Design: ${projectName}
+
+## Purpose
+- <what this project is responsible for>
+- <who or what it serves>
+
+## Scope
+- In scope:
+  - <major capability or boundary>
+- Out of scope:
+  - <intentional non-goal>
+
+## Structure
+- <important directory or subsystem> \u2014 <responsibility>
+
+## Constraints
+- <cross-cutting technical or operational constraint, when it affects architecture>
+`;
+}
+function generateProjectRulesContent(projectName) {
+  return `---
+name: project-rules
+description: Project-specific rules for ${projectName}
+---
+
+# Project Rules
+
+## Scope
+- <stable local rules, workflow constraints, or validation expectations>
+
+## Validation
+- <preferred stable validation commands, not temporary troubleshooting steps>
+
+## Conventions
+- <project-specific conventions>
+`;
+}
+function generateRulesContent(name) {
+  const title = toTitleCase(name);
+  return `---
+name: ${name}
+description: Project-specific rules for ${title}
+---
+
+# ${title}
+
+## Scope
+- <what this rules file governs>
+
+## Rules
+- <stable local rule>
+
+## Validation
+- <relevant validation command or check>
+`;
+}
+function generateSpecContent(name) {
+  const title = toTitleCase(name);
+  return `# ${title}
+
+## Purpose
+- <why this project-level spec exists>
+
+## Details
+- <important project-level detail>
+`;
+}
+function toTitleCase(value) {
+  return value.split(/[-/]/g).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
 function detectDeltaSections(content) {
   const match = content.match(/^## Spec\n([\s\S]*?)(?=\n## |\n---|\n\.\.\.)/m);
   if (!match) {
@@ -204,6 +349,7 @@ var __dirname = dirname(fileURLToPath(import.meta.url));
 var PKG_ROOT = join2(__dirname, "..");
 var RSP_DIR = ".rsp";
 var ACTIVE_DIR = join2(RSP_DIR, "active.d");
+var ARCHIVES_DIR = join2(RSP_DIR, "archives");
 var LOCK_PATH = join2(RSP_DIR, ".lock");
 var CONFIG_PATH = join2(RSP_DIR, "config.yaml");
 var VALID_STATUSES = ["draft", "ready", "in-progress", "blocked", "done"];
@@ -295,40 +441,204 @@ ${(/* @__PURE__ */ new Date()).toISOString()}`, { flag: "wx" });
   }
 }
 
-// src/commands/archive-index.ts
-async function buildArchiveIndex({ acquireLock = true } = {}) {
+// src/commands/add-rules.ts
+var NAME_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+async function detectProjectName() {
+  try {
+    if (existsSync3("package.json")) {
+      const raw = await readFile3("package.json", "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.name && pkg.name !== "")
+        return pkg.name;
+    }
+  } catch {
+  }
+  return basename(process.cwd());
+}
+async function addRules(name, projectName = "project") {
+  if (!name || !NAME_RE.test(name)) {
+    console.error(`  ${pc.red("Error:")} rule name must be kebab-case with optional subdirectory`);
+    process.exit(1);
+  }
+  const rspRulesPath = join3(RSP_DIR, "rules", "rsp-rules.md");
+  const designPath = join3(RSP_DIR, "specs", "design.md");
+  if (!existsSync3(rspRulesPath) || !existsSync3(designPath)) {
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
+    process.exit(1);
+  }
+  return withRspLock("add-rules", async () => {
+    const dir = join3(RSP_DIR, "rules");
+    const path = join3(dir, `${name}.md`);
+    if (existsSync3(path)) {
+      console.error(`  ${pc.red("Error:")} rule file already exists: .rsp/rules/${name}.md`);
+      process.exit(1);
+    }
+    await mkdir2(dirname2(path), { recursive: true });
+    const resolvedProjectName = projectName === "project" ? await detectProjectName() : projectName;
+    const content = name === "project-rules" ? generateProjectRulesContent(resolvedProjectName) : generateRulesContent(name);
+    await writeFile2(path, content);
+    console.log(`  ${pc.green("Created:")} .rsp/rules/${name}.md
+`);
+  });
+}
+
+// src/commands/add-spec.ts
+import { existsSync as existsSync5 } from "fs";
+import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
+import { basename as basename3, dirname as dirname3, join as join5 } from "path";
+
+// src/commands/specs-index.ts
+import { existsSync as existsSync4 } from "fs";
+import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { basename as basename2, join as join4, relative as relative2 } from "path";
+async function buildSpecsIndex({ acquireLock = true } = {}) {
   if (acquireLock)
-    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false }));
-  const archiveDir = join3(RSP_DIR, "archive");
-  if (!existsSync3(archiveDir)) {
-    console.log(`  ${pc.dim("No archive directory.")}
+    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false }));
+  const specsDir = join4(RSP_DIR, "specs");
+  if (!existsSync4(specsDir)) {
+    console.log(`  ${pc.dim("No specs directory.")}
 `);
     return;
   }
-  const archiveFiles = (await walkMarkdownFiles(archiveDir)).filter((fp) => basename(fp) !== "INDEX.md").sort();
-  if (archiveFiles.length === 0) {
-    console.log(`  ${pc.dim("No archived features.")}
+  const specFiles = (await walkMarkdownFiles(specsDir)).filter((fp) => basename2(fp) !== "INDEX.md").sort();
+  const lines = [];
+  lines.push("# Specs Index");
+  lines.push("");
+  lines.push("_Project-level specs and design notes._");
+  lines.push("");
+  if (specFiles.length === 0) {
+    lines.push("_No project-level specs yet._");
+  } else {
+    lines.push("| File | Title | Summary |");
+    lines.push("|------|-------|---------|");
+    for (const fp of specFiles) {
+      const rel = relative2(specsDir, fp);
+      const content = await readFile4(fp, "utf-8");
+      const fm = parseFrontmatter(content);
+      const title = extractTitle(content) || rel.replace(/\.md$/, "");
+      const summary = extractSummary(content, fm?.summary);
+      lines.push(`| ${escapeCell(rel)} | ${escapeCell(title)} | ${escapeCell(summary || "\u2014")} |`);
+    }
+  }
+  lines.push("");
+  lines.push("_Auto-generated by `rsp specs-index`._");
+  await writeFile3(join4(specsDir, "INDEX.md"), lines.join("\n"));
+  console.log(`  ${pc.green("INDEX.md updated:")} ${specFiles.length} spec file(s).
+`);
+}
+function extractTitle(content) {
+  for (const rawLine of content.split("\n")) {
+    if (!rawLine.startsWith("# "))
+      continue;
+    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) {
+    const line = rawLine.trim();
+    if (line === "---" || line === "...") {
+      inFrontmatter = !inFrontmatter;
+      continue;
+    }
+    if (inFrontmatter || line === "")
+      continue;
+    if (line.startsWith("#"))
+      continue;
+    if (line.startsWith("##"))
+      continue;
+    return line.replace(/^[-*]\s*/, "").trim();
+  }
+  return "";
+}
+function escapeCell(value) {
+  return value.replace(/\|/g, "\\|");
+}
+
+// src/commands/add-spec.ts
+var NAME_RE2 = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+async function detectProjectName2() {
+  try {
+    if (existsSync5("package.json")) {
+      const raw = await readFile5("package.json", "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.name && pkg.name !== "")
+        return pkg.name;
+    }
+  } catch {
+  }
+  return basename3(process.cwd());
+}
+async function addSpec(name, projectName = "project") {
+  if (!name || !NAME_RE2.test(name)) {
+    console.error(`  ${pc.red("Error:")} spec name must be kebab-case with optional subdirectory`);
+    process.exit(1);
+  }
+  const rspRulesPath = join5(RSP_DIR, "rules", "rsp-rules.md");
+  const designPath = join5(RSP_DIR, "specs", "design.md");
+  if (!existsSync5(rspRulesPath) || !existsSync5(designPath)) {
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
+    process.exit(1);
+  }
+  return withRspLock("add-spec", async () => {
+    const dir = join5(RSP_DIR, "specs");
+    const path = join5(dir, `${name}.md`);
+    if (existsSync5(path)) {
+      console.error(`  ${pc.red("Error:")} spec file already exists: .rsp/specs/${name}.md`);
+      process.exit(1);
+    }
+    await mkdir3(dirname3(path), { recursive: true });
+    const resolvedProjectName = projectName === "project" ? await detectProjectName2() : projectName;
+    const content = name === "design" ? generateDesignContent(resolvedProjectName) : generateSpecContent(name);
+    await writeFile4(path, content);
+    await buildSpecsIndex({ acquireLock: false });
+    console.log(`  ${pc.green("Created:")} .rsp/specs/${name}.md
+`);
+  });
+}
+
+// src/commands/archive-index.ts
+import { existsSync as existsSync6 } from "fs";
+import { readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
+import { basename as basename4, dirname as dirname4, join as join6, relative as relative3 } from "path";
+async function buildArchiveIndex({ acquireLock = true } = {}) {
+  if (acquireLock)
+    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false }));
+  const archiveDir = join6(RSP_DIR, "archives");
+  if (!existsSync6(archiveDir)) {
+    console.log(`  ${pc.dim("No archives directory.")}
 `);
     return;
   }
+  const archiveFiles = (await walkMarkdownFiles(archiveDir)).filter((fp) => basename4(fp) !== "INDEX.md").sort();
   const lines = [];
   lines.push("# Archive Index");
   lines.push("");
   lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
   lines.push("");
-  lines.push("| Date | Feature | Summary |");
-  lines.push("|------|---------|---------|");
+  if (archiveFiles.length === 0) {
+    lines.push("_No archived features yet._");
+  } else {
+    lines.push("| Date | Feature | Summary |");
+    lines.push("|------|---------|---------|");
+  }
   for (const fp of archiveFiles) {
-    const base = basename(fp);
-    const archiveRel = relative2(archiveDir, fp);
-    const archiveDirPart = dirname2(archiveRel);
+    const base = basename4(fp);
+    const archiveRel = relative3(archiveDir, fp);
+    const archiveDirPart = dirname4(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 featureName = archiveDirPart !== "." ? `${archiveDirPart}/${baseName}` : baseName;
     let summary = "";
     try {
-      const content = await readFile3(fp, "utf-8");
+      const content = await readFile6(fp, "utf-8");
       const fm = parseFrontmatter(content);
       if (fm?.summary)
         summary = String(fm.summary);
@@ -344,18 +654,18 @@ async function buildArchiveIndex({ acquireLock = true } = {}) {
   }
   lines.push("");
   lines.push("_Auto-generated by `rsp archive-index`._");
-  const indexPath = join3(archiveDir, "INDEX.md");
-  await writeFile2(indexPath, lines.join("\n"));
+  const indexPath = join6(archiveDir, "INDEX.md");
+  await writeFile5(indexPath, lines.join("\n"));
   console.log(`  ${pc.green("INDEX.md updated:")} ${archiveFiles.length} archived feature(s).
 `);
 }
 
 // src/commands/check.ts
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
-import { join as join4, relative as relative3 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join7, relative as relative4 } from "path";
 async function runCheck() {
-  const featuresDir = join4(RSP_DIR, "features");
+  const featuresDir = join7(RSP_DIR, "features");
   const config = await loadRspConfig();
   const validStatuses = resolveStatuses(config);
   const validPriorities = resolvePriorities(config);
@@ -365,34 +675,34 @@ async function runCheck() {
   console.log();
   console.log(`  ${pc.bold("RSP check")}`);
   console.log();
-  if (existsSync4(ACTIVE_DIR)) {
+  if (existsSync7(ACTIVE_DIR)) {
     const entries = await walkFiles(ACTIVE_DIR);
     for (const entryPath of entries) {
-      const entryContent = relative3(ACTIVE_DIR, entryPath);
-      const markerContent = (await readFile4(entryPath, "utf-8")).trim();
+      const entryContent = relative4(ACTIVE_DIR, entryPath);
+      const markerContent = (await readFile7(entryPath, "utf-8")).trim();
       if (markerContent) {
         console.log(`  ${pc.yellow("\u26A0")} active.d/${entryContent} should be an empty marker file; path is the source of truth`);
         warnings++;
       }
-      const fp = join4(featuresDir, `${entryContent}.md`);
-      if (!existsSync4(fp)) {
+      const fp = join7(featuresDir, `${entryContent}.md`);
+      if (!existsSync7(fp)) {
         console.log(`  ${pc.red("\u2717")} active.d/${entryContent} points to "${entryContent}" but features/${entryContent}.md not found`);
         errors++;
       }
     }
   }
-  const featureFiles = existsSync4(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
+  const featureFiles = existsSync7(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
   if (featureFiles.length === 0) {
     console.log(`  ${pc.dim("No feature files to check.")}
 `);
-    return;
+    return 0;
   }
   const allDeps = /* @__PURE__ */ new Map();
   for (const fp of featureFiles) {
     const name = featureNameFromPath(featuresDir, fp);
     let content;
     try {
-      content = await readFile4(fp, "utf-8");
+      content = await readFile7(fp, "utf-8");
     } catch {
       console.log(`  ${pc.red("\u2717")} ${name} \u2014 unable to read file`);
       errors++;
@@ -487,8 +797,8 @@ async function runCheck() {
         }
         seen.add(dep);
         allDeps.set(name, [...allDeps.get(name) || [], dep]);
-        const depFp = join4(featuresDir, `${dep}.md`);
-        if (!existsSync4(depFp)) {
+        const depFp = join7(featuresDir, `${dep}.md`);
+        if (!existsSync7(depFp)) {
           console.log(`  ${pc.red("\u2717")} ${name} \u2014 depends on "${dep}" but features/${dep}.md not found`);
           errors++;
         }
@@ -511,9 +821,9 @@ async function runCheck() {
 }
 
 // src/commands/close-feature.ts
-import { existsSync as existsSync5 } from "fs";
-import { appendFile, mkdir as mkdir2, readdir as readdir2, readFile as readFile5, rename, rmdir, unlink as unlink2, writeFile as writeFile3 } from "fs/promises";
-import { basename as basename2, dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir4, readdir as readdir2, readFile as readFile8, rename, rmdir, unlink as unlink2 } from "fs/promises";
+import { basename as basename5, dirname as dirname5, join as join8 } from "path";
 async function closeFeature(name) {
   return withRspLock("close-feature", async () => {
     if (!name) {
@@ -524,128 +834,104 @@ async function closeFeature(name) {
       console.error(`  ${pc.red("Error:")} feature name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
       process.exit(1);
     }
-    const srcPath = join5(RSP_DIR, "features", `${name}.md`);
-    if (!existsSync5(srcPath)) {
+    const srcPath = join8(RSP_DIR, "features", `${name}.md`);
+    if (!existsSync8(srcPath)) {
       console.error(`  ${pc.red("Feature not found:")} .rsp/features/${name}.md`);
       process.exit(1);
     }
+    const dependents = await findDependents(name);
+    if (dependents.length > 0) {
+      console.error(`  ${pc.red("Error:")} cannot close "${name}" because it is still referenced by: ${dependents.join(", ")}`);
+      console.error(`  ${pc.dim("Remove or update those depends-on entries before archiving this feature.")}`);
+      process.exit(1);
+    }
     const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    const dir = dirname3(name);
-    const base = basename2(name);
-    const archiveSubdir = dir !== "." ? join5(RSP_DIR, "archive", dir) : join5(RSP_DIR, "archive");
+    const dir = dirname5(name);
+    const base = basename5(name);
+    const archiveSubdir = dir !== "." ? join8(ARCHIVES_DIR, dir) : ARCHIVES_DIR;
     const archiveName = `${date}_${base}.md`;
-    await mkdir2(archiveSubdir, { recursive: true });
-    await rename(srcPath, join5(archiveSubdir, archiveName));
+    await mkdir4(archiveSubdir, { recursive: true });
+    await rename(srcPath, join8(archiveSubdir, archiveName));
     let activeCleared = false;
-    const activeEntry = join5(ACTIVE_DIR, name);
-    if (existsSync5(activeEntry)) {
+    const activeEntry = join8(ACTIVE_DIR, name);
+    if (existsSync8(activeEntry)) {
       await unlink2(activeEntry);
-      let parent = dirname3(activeEntry);
-      while (parent !== ACTIVE_DIR) {
-        try {
-          const remaining = await readdir2(parent);
-          if (remaining.length === 0)
-            await rmdir(parent);
-          else
-            break;
-        } catch {
-          break;
-        }
-        parent = dirname3(parent);
-      }
+      await cleanupEmptyParentDirs(activeEntry, ACTIVE_DIR);
       activeCleared = true;
     }
+    await cleanupEmptyParentDirs(srcPath, join8(RSP_DIR, "features"));
     const clearedMsg = activeCleared ? `  ${pc.dim("active.d cleared")}
 ` : "";
     console.log(`  ${pc.green("Archived:")} ${archiveName}
 ${clearedMsg}`);
     await buildArchiveIndex({ acquireLock: false });
     await runCheckIfHasDependents(name);
-    await updateSpecIndex(name, date);
-    if (existsSync5(".git")) {
-      const archiveRelPath = dir !== "." ? join5(dir, archiveName) : archiveName;
+    if (existsSync8(".git")) {
+      const archiveRelPath = dir !== "." ? join8(dir, archiveName) : archiveName;
       console.log(`  ${pc.cyan("Git workflow:")}
 `);
-      console.log(`    git add .rsp/archive/${archiveRelPath}`);
+      console.log(`    git add .rsp/archives/${archiveRelPath}`);
       console.log(`    git commit -m "feat: complete ${name}"`);
       console.log();
     }
   });
 }
+async function findDependents(name) {
+  const featuresDir = join8(RSP_DIR, "features");
+  const allFeatureFiles = await walkMarkdownFiles(featuresDir);
+  const dependents = [];
+  for (const fp of allFeatureFiles) {
+    const featureName = fp === join8(featuresDir, `${name}.md`) ? name : fp.replace(`${featuresDir}/`, "").replace(/\.md$/, "");
+    if (featureName === name)
+      continue;
+    const content = await readFile8(fp, "utf-8");
+    const fm = parseFrontmatter(content);
+    if (!fm || !fm["depends-on"])
+      continue;
+    const deps = Array.isArray(fm["depends-on"]) ? fm["depends-on"] : [fm["depends-on"]];
+    if (deps.includes(name))
+      dependents.push(featureName);
+  }
+  return dependents.sort();
+}
 async function runCheckIfHasDependents(name) {
   try {
-    const featuresDir = join5(RSP_DIR, "features");
-    const allFeatureFiles = await walkMarkdownFiles(featuresDir);
-    let hasDependents = false;
-    for (const fp of allFeatureFiles) {
-      const content = await readFile5(fp, "utf-8");
-      const fm = parseFrontmatter(content);
-      if (!fm || !fm["depends-on"])
-        continue;
-      const deps = Array.isArray(fm["depends-on"]) ? fm["depends-on"] : [fm["depends-on"]];
-      if (deps.includes(name)) {
-        hasDependents = true;
-        break;
-      }
-    }
+    const hasDependents = (await findDependents(name)).length > 0;
     if (hasDependents)
       await runCheck();
   } catch {
     console.warn(`  ${pc.dim("\u26A0 could not verify dependents for")} "${name}"`);
   }
 }
-async function updateSpecIndex(name, date) {
-  const specIndexPath = join5(RSP_DIR, "specs", "INDEX.md");
-  const archiveDir = join5(RSP_DIR, "archive");
-  const escaped = name.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
-  const lineRe = new RegExp(`^\\| \\d{4}-\\d{2}-\\d{2} \\| ${escaped} \\|`, "m");
-  const archiveFile = await (async () => {
-    try {
-      const entries = await walkMarkdownFiles(archiveDir);
-      return entries.find((fp) => basename2(fp).startsWith(`${date}_`) && basename2(fp).endsWith(".md"));
-    } catch {
-      return null;
-    }
-  })();
-  let summary = "\u2014";
-  if (archiveFile) {
+async function cleanupEmptyParentDirs(path, stopDir) {
+  let parent = dirname5(path);
+  while (parent !== stopDir) {
     try {
-      const content = await readFile5(join5(archiveDir, archiveFile), "utf-8");
-      const m = content.match(/^## Spec[\s\S]*?\n- Summary:[ \t]*([^\n]+)$/m);
-      if (m)
-        summary = m[1].trim();
+      const remaining = await readdir2(parent);
+      if (remaining.length === 0)
+        await rmdir(parent);
+      else
+        break;
     } catch {
+      break;
     }
-  }
-  const line = `| ${date} | ${name} | ${summary} |
-`;
-  try {
-    let existing = "";
-    if (existsSync5(specIndexPath))
-      existing = await readFile5(specIndexPath, "utf-8");
-    if (lineRe.test(existing))
-      return;
-    if (!existing.includes("| Date | Feature | Summary |")) {
-      await writeFile3(specIndexPath, `# Specs Index
-
-| Date | Feature | Summary |
-|------|---------|---------|
-${line}
-`);
-    } else {
-      await appendFile(specIndexPath, line);
-    }
-  } catch {
+    parent = dirname5(parent);
   }
 }
 
 // src/commands/deps.ts
-import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile6 } from "fs/promises";
-import { join as join6 } from "path";
-async function showDependencies(mermaid = false) {
-  const featuresDir = join6(RSP_DIR, "features");
-  const featureFiles = existsSync6(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join9 } from "path";
+async function showDependencies(options = false) {
+  const resolved = typeof options === "boolean" ? { mermaid: options } : options;
+  const mermaid = Boolean(resolved.mermaid);
+  const focus = resolved.focus?.trim();
+  const reverse = resolved.reverse?.trim();
+  if (focus && reverse)
+    throw new Error("Use either --focus or --reverse, not both");
+  const featuresDir = join9(RSP_DIR, "features");
+  const featureFiles = existsSync9(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
   console.log();
   console.log(`  ${pc.bold("RSP dependencies")}`);
   console.log();
@@ -660,7 +946,7 @@ async function showDependencies(mermaid = false) {
     const name = featureNameFromPath(featuresDir, fp);
     let content;
     try {
-      content = await readFile6(fp, "utf-8");
+      content = await readFile9(fp, "utf-8");
     } catch {
       continue;
     }
@@ -674,18 +960,41 @@ async function showDependencies(mermaid = false) {
       dependents.set(dep, list);
     }
   }
+  let visibleRecords = [...records];
+  if (focus) {
+    const related = /* @__PURE__ */ new Set([focus]);
+    const target = records.find((record) => record.name === focus);
+    if (target) {
+      for (const dep of target.deps)
+        related.add(dep);
+    }
+    for (const dependent of dependents.get(focus) || [])
+      related.add(dependent);
+    visibleRecords = records.filter((record) => related.has(record.name));
+  } else if (reverse) {
+    const related = new Set(dependents.get(reverse) || []);
+    visibleRecords = records.filter((record) => related.has(record.name));
+  }
+  if ((focus || reverse) && visibleRecords.length === 0) {
+    console.log(`  ${pc.dim("No dependency matches found for the current filter.")}
+`);
+    return;
+  }
   if (mermaid) {
     console.log("```mermaid");
     console.log("graph LR");
     const safeId = (s) => s.replace(/\//g, "__slash__").replace(/\W/g, "_");
-    for (const { name } of records) {
+    for (const { name } of visibleRecords) {
       const id = safeId(name);
       const label = name.replace(/"/g, "#quot;");
       console.log(`    ${id}["${label}"]`);
     }
-    for (const { name, deps } of records) {
+    const visibleNames = new Set(visibleRecords.map((record) => record.name));
+    for (const { name, deps } of visibleRecords) {
       const fromId = safeId(name);
       for (const dep of deps) {
+        if (!visibleNames.has(dep))
+          continue;
         const toId = safeId(dep);
         console.log(`    ${fromId} --> ${toId}`);
       }
@@ -696,7 +1005,7 @@ async function showDependencies(mermaid = false) {
   }
   console.log(`  ${"Feature".padEnd(28)} ${"Depends On".padEnd(28)} Dependents`);
   console.log(`  ${"\u2500".repeat(28)} ${"\u2500".repeat(28)} \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
-  for (const { name, deps } of records.sort((a, b) => a.name.localeCompare(b.name))) {
+  for (const { name, deps } of visibleRecords.sort((a, b) => a.name.localeCompare(b.name))) {
     const depText = deps.length > 0 ? deps.join(", ") : "\u2014";
     const dependentText = (dependents.get(name) || []).length > 0 ? pc.dim((dependents.get(name) || []).join(", ")) : "\u2014";
     console.log(`  ${name.padEnd(28)} ${depText.padEnd(28)} ${dependentText}`);
@@ -704,36 +1013,149 @@ async function showDependencies(mermaid = false) {
   console.log();
 }
 
-// src/commands/init.ts
-import { existsSync as existsSync7 } from "fs";
-import { cp, mkdir as mkdir3, readFile as readFile7, writeFile as writeFile4 } from "fs/promises";
-import { basename as basename3, join as join7 } from "path";
-async function detectProjectName() {
-  try {
-    if (existsSync7("package.json")) {
-      const raw = await readFile7("package.json", "utf-8");
-      const pkg = JSON.parse(raw);
-      if (pkg.name && pkg.name !== "")
-        return pkg.name;
-    }
-  } catch {
+// src/commands/doctor.ts
+import { existsSync as existsSync10 } from "fs";
+import { readFile as readFile10 } from "fs/promises";
+import { join as join10, relative as relative5 } from "path";
+async function runDoctor() {
+  let issues = 0;
+  console.log();
+  console.log(`  ${pc.bold("RSP doctor")}`);
+  console.log();
+  const rspRulesPath = join10(RSP_DIR, "rules", "rsp-rules.md");
+  const designPath = join10(RSP_DIR, "specs", "design.md");
+  const specsIndexPath = join10(RSP_DIR, "specs", "INDEX.md");
+  const archivesIndexPath = join10(RSP_DIR, "archives", "INDEX.md");
+  issues += reportCheck(".rsp exists", existsSync10(RSP_DIR), "Run: rsp init");
+  issues += reportCheck("rules/rsp-rules.md exists", existsSync10(rspRulesPath), "Run: rsp init");
+  issues += reportCheck("specs/design.md exists", existsSync10(designPath), "Run: rsp init");
+  issues += reportCheck("specs/INDEX.md exists", existsSync10(specsIndexPath), "Run: rsp specs-index");
+  issues += reportCheck("archives/INDEX.md exists", existsSync10(archivesIndexPath), "Run: rsp archive-index");
+  issues += await checkAgents();
+  issues += await checkGeneratedIndex(specsIndexPath, "_Auto-generated by `rsp specs-index`._", "specs/INDEX.md has generated signature", "Run: rsp specs-index");
+  issues += await checkGeneratedIndex(archivesIndexPath, "_Auto-generated by `rsp archive-index`._", "archives/INDEX.md has generated signature", "Run: rsp archive-index");
+  issues += await checkArchiveNaming();
+  issues += await checkConfigSemantics();
+  issues += await checkActiveFeatureConsistency();
+  if (issues === 0)
+    console.log(`
+  ${pc.green("\u2713")} RSP setup looks healthy.
+`);
+  else
+    console.log(`
+  ${pc.yellow(String(issues))} issue(s) detected.
+`);
+  return issues;
+}
+function reportCheck(label, ok, fixHint) {
+  if (ok) {
+    console.log(`  ${pc.green("\u2713")} ${label}`);
+    return 0;
   }
-  return basename3(process.cwd());
+  console.log(`  ${pc.yellow("!")} ${label}`);
+  if (fixHint)
+    console.log(`    ${pc.dim(fixHint)}`);
+  return 1;
+}
+async function checkAgents() {
+  if (!existsSync10("AGENTS.md")) {
+    console.log(`  ${pc.yellow("!")} AGENTS.md missing`);
+    console.log(`    ${pc.dim("Run: rsp init --agents-mode managed")}`);
+    return 1;
+  }
+  const agents = await readFile10("AGENTS.md", "utf-8");
+  if (hasRspAgentsBlock(agents)) {
+    console.log(`  ${pc.green("\u2713")} AGENTS.md contains managed RSP block`);
+    return 0;
+  }
+  console.log(`  ${pc.yellow("!")} AGENTS.md missing managed RSP block`);
+  console.log(`    ${pc.dim("Run: rsp init --agents-mode managed")}`);
+  return 1;
+}
+async function checkGeneratedIndex(path, signature, label, fixHint) {
+  if (!existsSync10(path))
+    return 0;
+  const content = await readFile10(path, "utf-8");
+  if (content.includes(signature)) {
+    console.log(`  ${pc.green("\u2713")} ${label}`);
+    return 0;
+  }
+  console.log(`  ${pc.yellow("!")} ${label}`);
+  console.log(`    ${pc.dim(fixHint)}`);
+  return 1;
+}
+async function checkArchiveNaming() {
+  const archivesDir = join10(RSP_DIR, "archives");
+  const archiveFiles = existsSync10(archivesDir) ? (await walkMarkdownFiles(archivesDir)).filter((fp) => relative5(archivesDir, fp) !== "INDEX.md") : [];
+  const invalidFiles = archiveFiles.map((fp) => relative5(archivesDir, fp)).filter((fp) => /^\d{4}-\d{2}-\d{2}_.+\.md$/.test(fp.split("/").at(-1) || "") === false);
+  if (invalidFiles.length === 0) {
+    console.log(`  ${pc.green("\u2713")} archived feature files follow the date_name.md convention`);
+    return 0;
+  }
+  console.log(`  ${pc.yellow("!")} archived feature files with invalid names: ${invalidFiles.join(", ")}`);
+  console.log(`    ${pc.dim("Rename archive files to YYYY-MM-DD_name.md and run: rsp archive-index")}`);
+  return 1;
+}
+async function checkConfigSemantics() {
+  if (!existsSync10(CONFIG_PATH))
+    return 0;
+  const content = await readFile10(CONFIG_PATH, "utf-8");
+  const parsed = parseYamlLines(content.split("\n"));
+  let issues = 0;
+  issues += reportConfigListField(parsed, "statuses");
+  issues += reportConfigListField(parsed, "priorities");
+  issues += reportConfigListField(parsed, "required_sections");
+  return issues;
+}
+function reportConfigListField(parsed, key) {
+  if (!(key in parsed))
+    return 0;
+  const value = parsed[key];
+  if (!Array.isArray(value)) {
+    console.log(`  ${pc.yellow("!")} config.yaml field "${key}" must be a YAML list`);
+    console.log(`    ${pc.dim(`Update .rsp/config.yaml so "${key}" uses "key:" followed by indented "- item" entries`)}`);
+    return 1;
+  }
+  const items = value.map(String);
+  const duplicates = [...new Set(items.filter((item, index) => items.indexOf(item) !== index))];
+  if (duplicates.length === 0) {
+    console.log(`  ${pc.green("\u2713")} config.yaml field "${key}" has valid list semantics`);
+    return 0;
+  }
+  console.log(`  ${pc.yellow("!")} config.yaml field "${key}" contains duplicate entries: ${duplicates.join(", ")}`);
+  console.log(`    ${pc.dim(`Remove duplicate values from .rsp/config.yaml:${key}`)}`);
+  return 1;
+}
+async function checkActiveFeatureConsistency() {
+  const featuresDir = join10(RSP_DIR, "features");
+  const featureFiles = existsSync10(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
+  const featureNames = new Set(featureFiles.map((fp) => relative5(featuresDir, fp).replace(/\.md$/, "")));
+  const activeEntries = existsSync10(ACTIVE_DIR) ? await walkFiles(ACTIVE_DIR) : [];
+  const activeNames = new Set(activeEntries.map((fp) => relative5(ACTIVE_DIR, fp)));
+  const missingFeatureFiles = [...activeNames].filter((name) => !featureNames.has(name));
+  const unstagedActiveMarkers = [...featureNames].filter((name) => !activeNames.has(name));
+  let issues = 0;
+  if (missingFeatureFiles.length === 0) {
+    console.log(`  ${pc.green("\u2713")} every active marker maps to a feature file`);
+  } else {
+    console.log(`  ${pc.yellow("!")} active markers without matching feature files: ${missingFeatureFiles.join(", ")}`);
+    console.log(`    ${pc.dim("Run: remove stale files in .rsp/active.d/ or recreate the feature with rsp new <name>")}`);
+    issues++;
+  }
+  if (unstagedActiveMarkers.length === 0) {
+    console.log(`  ${pc.green("\u2713")} every feature file has an active marker`);
+  } else {
+    console.log(`  ${pc.yellow("!")} feature files without active markers: ${unstagedActiveMarkers.join(", ")}`);
+    console.log(`    ${pc.dim("Run: recreate the marker with rsp new <name> or archive the feature with rsp close <name>")}`);
+    issues++;
+  }
+  return issues;
 }
-var AGENTS_BODY = `## Collaboration Mode
-This project uses **RSP** (Rules, Specs, Plans) \u2014 see \`.rsp/rules/\` for the full workflow definition (start with \`rsp-rules.md\`).
-
-Key conventions:
-- \`.rsp/rules/\` \u2014 technical constraints and coding conventions
-- \`.rsp/specs/\` \u2014 project-level architecture and design reference
-- \`.rsp/features/<name>.md\` \u2014 feature definitions (spec + plan + tests)
-- \`.rsp/active.d/\` \u2014 currently active features (path = feature name)
-- \`.rsp/archive/\` \u2014 completed features
 
-## Workflow
-- Run \`rsp status\` to see current project state
-- Run \`rsp new <name>\` to start a new feature
-- Run \`rsp close <name>\` to archive a completed feature`;
+// src/commands/init.ts
+import { existsSync as existsSync11 } from "fs";
+import { mkdir as mkdir5, readFile as readFile11, writeFile as writeFile6 } from "fs/promises";
+import { basename as basename6, join as join11 } from "path";
 var CONFIG_TEMPLATE = `# RSP project configuration
 # Uncomment any section below to override defaults.
 #
@@ -759,82 +1181,111 @@ var CONFIG_TEMPLATE = `# RSP project configuration
 #   - Spec
 #   - Plan
 `;
-async function initProject() {
-  const isNew = !existsSync7(RSP_DIR);
+async function detectProjectName3() {
+  try {
+    if (existsSync11("package.json")) {
+      const raw = await readFile11("package.json", "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.name && pkg.name !== "")
+        return pkg.name;
+    }
+  } catch {
+  }
+  return basename6(process.cwd());
+}
+async function ensureFile(path, content) {
+  if (existsSync11(path))
+    return false;
+  await writeFile6(path, content);
+  return true;
+}
+function toTitle(projectName) {
+  return projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
+}
+async function initProject(args = {}) {
+  const isNew = !existsSync11(RSP_DIR);
+  const projectName = await detectProjectName3();
   return withRspLock("init", async () => {
     const dirs = [
-      join7(RSP_DIR, "rules"),
-      join7(RSP_DIR, "specs"),
-      join7(RSP_DIR, "features"),
-      join7(RSP_DIR, "archive")
+      join11(RSP_DIR, "rules"),
+      join11(RSP_DIR, "specs"),
+      join11(RSP_DIR, "features"),
+      join11(RSP_DIR, "active.d"),
+      join11(RSP_DIR, "archives")
     ];
-    let created = false;
     for (const d of dirs)
-      await mkdir3(d, { recursive: true });
-    const rulesDest = join7(RSP_DIR, "rules", "rsp-rules.md");
-    if (!existsSync7(rulesDest)) {
-      await cp(join7(PKG_ROOT, "rules", "rsp-rules.md"), rulesDest);
-      created = true;
-    }
-    const configPath = join7(RSP_DIR, "config.yaml");
-    if (!existsSync7(configPath)) {
-      await writeFile4(configPath, CONFIG_TEMPLATE);
-      created = true;
-    }
-    const specIndexPath = join7(RSP_DIR, "specs", "INDEX.md");
-    if (!existsSync7(specIndexPath)) {
-      await writeFile4(specIndexPath, "# Specs Index\n\n_Extracted from archived features._\n");
-      created = true;
-    }
-    const gitignorePath = join7(RSP_DIR, ".gitignore");
-    if (!existsSync7(gitignorePath)) {
-      await writeFile4(gitignorePath, "# Transient files that should not be committed\n.lock\n");
-      created = true;
+      await mkdir5(d, { recursive: true });
+    let created = false;
+    const bundledRules = await readFile11(join11(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    created = await ensureFile(join11(RSP_DIR, "rules", "rsp-rules.md"), bundledRules) || created;
+    created = await ensureFile(join11(RSP_DIR, "config.yaml"), CONFIG_TEMPLATE) || created;
+    const createdSpecsIndex = await ensureFile(join11(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Project-level specs and design notes._\n");
+    created = createdSpecsIndex || created;
+    const createdDesign = await ensureFile(join11(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
+    created = createdDesign || created;
+    const createdArchivesIndex = await ensureFile(join11(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
+    created = createdArchivesIndex || created;
+    created = await ensureFile(join11(RSP_DIR, "features", ".gitkeep"), "") || created;
+    created = await ensureFile(join11(RSP_DIR, "active.d", ".gitkeep"), "") || created;
+    created = await ensureFile(join11(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
+    if (args.withProjectRules)
+      created = await ensureFile(join11(RSP_DIR, "rules", "project-rules.md"), generateProjectRulesContent(projectName)) || created;
+    if (args.withProjectSetup) {
+      const featurePath = join11(RSP_DIR, "features", "project-setup.md");
+      const activeMarker = join11(RSP_DIR, "active.d", "project-setup");
+      created = await ensureFile(featurePath, generateFeatureContent("project-setup")) || created;
+      created = await ensureFile(activeMarker, "") || created;
     }
+    if (createdSpecsIndex || createdDesign)
+      await buildSpecsIndex({ acquireLock: false });
+    if (createdArchivesIndex)
+      await buildArchiveIndex({ acquireLock: false });
     const agentsPath = "AGENTS.md";
-    const projectName = await detectProjectName();
-    if (existsSync7(agentsPath)) {
-      const existing = await readFile7(agentsPath, "utf-8");
-      const rspRe = /\bRSP\b/;
-      if (!rspRe.test(existing)) {
-        const h2Match = existing.match(/^## /m);
-        if (h2Match) {
-          const before = existing.slice(0, h2Match.index);
-          const after = existing.slice(h2Match.index);
-          await writeFile4(agentsPath, `${before}${AGENTS_BODY}
+    const title = toTitle(projectName);
+    const mode = args.agentsMode ?? "managed";
+    if (!existsSync11(agentsPath)) {
+      if (mode === "managed") {
+        await writeFile6(agentsPath, `# ${title}
 
----
-
-${after}`);
-        } else {
-          await writeFile4(agentsPath, `${existing}
-
-${AGENTS_BODY}
+${upsertRspAgentsBlock("").content}
 `);
-        }
         created = true;
       }
-    } else {
-      const title = projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
-      await writeFile4(agentsPath, `# ${title}
+    } else if (mode === "managed") {
+      const existing = await readFile11(agentsPath, "utf-8");
+      const next = upsertRspAgentsBlock(existing);
+      if (next.changed) {
+        await writeFile6(agentsPath, next.content);
+        created = true;
+      }
+    }
+    if (mode === "print") {
+      const managed = existsSync11(agentsPath) ? upsertRspAgentsBlock(await readFile11(agentsPath, "utf-8")).content : `# ${title}
 
-${AGENTS_BODY}
+${renderRspAgentsBlock()}
+`;
+      console.log(`
+${managed}
 `);
-      created = true;
     }
     if (isNew) {
+      const createdProjectSetup = args.withProjectSetup ? "\n           .rsp/features/project-setup.md\n           .rsp/active.d/project-setup" : "";
+      const next = args.withProjectSetup ? "fill .rsp/features/project-setup.md" : "rsp new project-setup";
       console.log(`
   ${pc.green("RSP scaffolded.")}
 `);
       console.log(`  Created: .rsp/rules/
            .rsp/specs/
            .rsp/features/
-           .rsp/archive/
+           .rsp/active.d/
+           .rsp/archives/
            .rsp/.gitignore
            .rsp/config.yaml
+           .rsp/specs/design.md${createdProjectSetup}
            AGENTS.md
 `);
-      console.log(`  ${pc.cyan("Next:")} rsp new <name>
+      console.log(`  ${pc.cyan("Next:")} ${next}
+  ${pc.dim("Then:")} fill .rsp/specs/design.md
   ${pc.dim("Also:")} rsp status  rsp deps
 `);
     } else if (created) {
@@ -850,34 +1301,40 @@ ${AGENTS_BODY}
 }
 
 // src/commands/new-feature.ts
-import { existsSync as existsSync8 } from "fs";
-import { mkdir as mkdir4, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname4, join as join8 } from "path";
+import { existsSync as existsSync12 } from "fs";
+import { mkdir as mkdir6, writeFile as writeFile7 } from "fs/promises";
+import { dirname as dirname6, join as join12 } from "path";
 async function newFeature(name, summary = "") {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp new <name> [summary]`);
+    process.exit(1);
+  }
+  if (/^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/.test(name) === false) {
+    console.error(`  ${pc.red("Error:")} feature name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
+    process.exit(1);
+  }
+  const rspRulesPath = join12(RSP_DIR, "rules", "rsp-rules.md");
+  const designPath = join12(RSP_DIR, "specs", "design.md");
+  if (!existsSync12(rspRulesPath) || !existsSync12(designPath)) {
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
+    process.exit(1);
+  }
   return withRspLock("new-feature", async () => {
-    if (!name) {
-      console.error(`  ${pc.red("Usage:")} rsp new <name> [summary]`);
-      process.exit(1);
-    }
-    if (/^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/.test(name) === false) {
-      console.error(`  ${pc.red("Error:")} feature name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
-      process.exit(1);
-    }
-    const featurePath = join8(RSP_DIR, "features", `${name}.md`);
-    await mkdir4(dirname4(featurePath), { recursive: true });
-    const existed = existsSync8(featurePath);
+    const featurePath = join12(RSP_DIR, "features", `${name}.md`);
+    await mkdir6(dirname6(featurePath), { recursive: true });
+    const existed = existsSync12(featurePath);
     if (!existed) {
       const content = generateFeatureContent(name, summary);
-      await writeFile5(featurePath, content);
+      await writeFile7(featurePath, content);
     }
-    await mkdir4(ACTIVE_DIR, { recursive: true });
-    const activeEntry = join8(ACTIVE_DIR, name);
-    await mkdir4(dirname4(activeEntry), { recursive: true });
-    await writeFile5(activeEntry, "");
+    await mkdir6(ACTIVE_DIR, { recursive: true });
+    const activeEntry = join12(ACTIVE_DIR, name);
+    await mkdir6(dirname6(activeEntry), { recursive: true });
+    await writeFile7(activeEntry, "");
     if (!existed) {
-      const archiveDir = join8(RSP_DIR, "archive");
-      const archiveIndex = join8(archiveDir, "INDEX.md");
-      if (existsSync8(archiveIndex))
+      const archiveIndex = join12(ARCHIVES_DIR, "INDEX.md");
+      if (existsSync12(archiveIndex))
         await buildArchiveIndex({ acquireLock: false });
     }
     const label = existed ? "Using" : pc.green("Created");
@@ -888,27 +1345,27 @@ async function newFeature(name, summary = "") {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile8, stat as stat2 } from "fs/promises";
-import { join as join9, relative as relative4 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { readFile as readFile12, stat as stat2 } from "fs/promises";
+import { join as join13, relative as relative6 } from "path";
 var COL_FEATURE = 30;
 var COL_STATUS = 16;
 var COL_AGE = 7;
 var COL_PROGRESS = 10;
-async function showStatus() {
-  const featuresDir = join9(RSP_DIR, "features");
+async function showStatus(options = {}) {
+  const featuresDir = join13(RSP_DIR, "features");
   const activeSet = /* @__PURE__ */ new Set();
-  if (existsSync9(ACTIVE_DIR)) {
+  if (existsSync13(ACTIVE_DIR)) {
     try {
       const entries = await walkFiles(ACTIVE_DIR);
       for (const entryPath of entries) {
-        const name = relative4(ACTIVE_DIR, entryPath);
+        const name = relative6(ACTIVE_DIR, entryPath);
         activeSet.add(name);
       }
     } catch {
     }
   }
-  const featureFiles = existsSync9(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
+  const featureFiles = existsSync13(featuresDir) ? await walkMarkdownFiles(featuresDir) : [];
   const featureMap = {};
   for (const fp of featureFiles) {
     const name = featureNameFromPath(featuresDir, fp);
@@ -941,7 +1398,7 @@ async function showStatus() {
     let isBlocked = false;
     if (fp) {
       try {
-        const content = await readFile8(fp, "utf-8");
+        const content = await readFile12(fp, "utf-8");
         const fm = parseFrontmatter(content);
         status = fm?.status || "\u2014";
         isBlocked = status === "blocked";
@@ -960,11 +1417,28 @@ async function showStatus() {
     }
     records.push({ name, status, progress, age, depends, isActive, isBlocked });
   }
+  const filteredRecords = records.filter((record) => {
+    if (options.active && !record.isActive)
+      return false;
+    if (options.blocked && !record.isBlocked)
+      return false;
+    if (typeof options.stale === "number") {
+      const ageDays = Number(record.age);
+      if (!Number.isFinite(ageDays) || ageDays < options.stale)
+        return false;
+    }
+    return true;
+  });
+  if (filteredRecords.length === 0) {
+    console.log(`  ${pc.dim("No features match the current filters.")}`);
+    console.log();
+    return;
+  }
   const pad = (s, w) => s.padEnd(w);
   console.log(`  ${pad("Feature", COL_FEATURE)} ${pad("Status", COL_STATUS)} ${pad("Age(d)", COL_AGE)} ${pad("Progress", COL_PROGRESS)} Depends On`);
   console.log(`  ${"\u2500".repeat(COL_FEATURE)} ${"\u2500".repeat(COL_STATUS)} ${"\u2500".repeat(COL_AGE)} ${"\u2500".repeat(COL_PROGRESS)} ${"\u2500".repeat(30)}`);
   let blockedCount = 0;
-  for (const r of records) {
+  for (const r of filteredRecords) {
     const marker = r.isActive ? pc.cyan("*") : " ";
     const namePadded = r.name.padEnd(COL_FEATURE - 1);
     const statusPadded = String(r.status).padEnd(COL_STATUS);
@@ -978,24 +1452,25 @@ async function showStatus() {
       blockedCount++;
   }
   console.log();
-  const total = records.length;
-  const doneCount = records.filter((r) => r.status === "done").length;
-  console.log(`  ${pc.bold("Summary:")} ${total} feature(s), ${activeSet.size} active, ${doneCount} done, ${pc.yellow(String(blockedCount))} blocked`);
+  const total = filteredRecords.length;
+  const doneCount = filteredRecords.filter((r) => r.status === "done").length;
+  const activeCount = filteredRecords.filter((r) => r.isActive).length;
+  console.log(`  ${pc.bold("Summary:")} ${total} feature(s), ${activeCount} active, ${doneCount} done, ${pc.yellow(String(blockedCount))} blocked`);
   console.log();
   await showArchiveTrend();
   if (blockedCount > 0) {
-    const blocked = records.filter((r) => r.isBlocked);
+    const blocked = filteredRecords.filter((r) => r.isBlocked);
     console.log(`  ${pc.yellow("Blocked:")} ${blocked.map((r) => r.name).join(", ")}`);
     console.log();
   }
 }
 async function showArchiveTrend() {
-  const archiveDir = join9(RSP_DIR, "archive");
-  const indexPath = join9(archiveDir, "INDEX.md");
-  if (!existsSync9(indexPath))
+  const archiveDir = join13(RSP_DIR, "archives");
+  const indexPath = join13(archiveDir, "INDEX.md");
+  if (!existsSync13(indexPath))
     return;
   try {
-    const content = await readFile8(indexPath, "utf-8");
+    const content = await readFile12(indexPath, "utf-8");
     const dateRe = /^\| (\d{4}-\d{2})-\d{2} \|/gm;
     const counts = {};
     let match;
@@ -1023,8 +1498,29 @@ var initCommand = defineCommand({
     name: "init",
     description: "Scaffold .rsp/ + AGENTS.md in current project"
   },
-  async run() {
-    await initProject();
+  args: {
+    "agents-mode": {
+      type: "string",
+      description: "How to update AGENTS.md: managed, skip, or print",
+      default: "managed"
+    },
+    "with-project-rules": {
+      type: "boolean",
+      description: "Create .rsp/rules/project-rules.md",
+      default: false
+    },
+    "with-project-setup": {
+      type: "boolean",
+      description: "Create .rsp/features/project-setup.md and mark it active",
+      default: false
+    }
+  },
+  async run({ args }) {
+    await initProject({
+      agentsMode: args["agents-mode"] === "skip" || args["agents-mode"] === "print" ? args["agents-mode"] : "managed",
+      withProjectRules: Boolean(args["with-project-rules"]),
+      withProjectSetup: Boolean(args["with-project-setup"])
+    });
   }
 });
 var newFeatureCommand = defineCommand({
@@ -1044,10 +1540,52 @@ var newFeatureCommand = defineCommand({
     await newFeature(args.name, summary);
   }
 });
+var addRulesCommand = defineCommand({
+  meta: {
+    name: "rules",
+    description: "Create .rsp/rules/<name>.md"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Rules file name",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await addRules(args.name);
+  }
+});
+var addSpecCommand = defineCommand({
+  meta: {
+    name: "spec",
+    description: "Create .rsp/specs/<name>.md and rebuild specs index"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Spec file name",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await addSpec(args.name);
+  }
+});
+var addCommand = defineCommand({
+  meta: {
+    name: "add",
+    description: "Add optional rules or spec files"
+  },
+  subCommands: {
+    rules: addRulesCommand,
+    spec: addSpecCommand
+  }
+});
 var closeFeatureCommand = defineCommand({
   meta: {
     name: "close",
-    description: "Archive to .rsp/archive/"
+    description: "Archive to .rsp/archives/"
   },
   args: {
     name: {
@@ -1065,8 +1603,33 @@ var statusCommand = defineCommand({
     name: "status",
     description: "Show project status summary"
   },
-  async run() {
-    await showStatus();
+  args: {
+    active: {
+      type: "boolean",
+      description: "Show only active features",
+      default: false
+    },
+    blocked: {
+      type: "boolean",
+      description: "Show only blocked features",
+      default: false
+    },
+    stale: {
+      type: "string",
+      description: "Show only features with age >= days"
+    }
+  },
+  async run({ args }) {
+    const stale = args.stale === void 0 ? void 0 : Number(args.stale);
+    if (args.stale !== void 0 && (Number.isFinite(stale) === false || Number.isInteger(stale) === false || stale < 0)) {
+      console.error(`  Error: --stale must be a non-negative integer number of days`);
+      process.exit(1);
+    }
+    await showStatus({
+      active: Boolean(args.active),
+      blocked: Boolean(args.blocked),
+      stale
+    });
   }
 });
 var checkCommand = defineCommand({
@@ -1090,21 +1653,53 @@ var depsCommand = defineCommand({
       type: "boolean",
       description: "Output as Mermaid.js graph",
       default: false
+    },
+    focus: {
+      type: "string",
+      description: "Show only a feature and its direct dependency neighborhood"
+    },
+    reverse: {
+      type: "string",
+      description: "Show only features that depend on the given feature"
     }
   },
   async run({ args }) {
-    await showDependencies(Boolean(args.mermaid));
+    await showDependencies({
+      mermaid: Boolean(args.mermaid),
+      focus: typeof args.focus === "string" ? args.focus : void 0,
+      reverse: typeof args.reverse === "string" ? args.reverse : void 0
+    });
   }
 });
 var archiveIndexCommand = defineCommand({
   meta: {
     name: "archive-index",
-    description: "Regenerate archive INDEX.md"
+    description: "Regenerate archives INDEX.md"
   },
   async run() {
     await buildArchiveIndex();
   }
 });
+var specsIndexCommand = defineCommand({
+  meta: {
+    name: "specs-index",
+    description: "Regenerate specs INDEX.md"
+  },
+  async run() {
+    await buildSpecsIndex();
+  }
+});
+var doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Check RSP setup health and common integration issues"
+  },
+  async run() {
+    const issues = await runDoctor();
+    if (issues > 0)
+      process.exit(1);
+  }
+});
 async function runCli(rawArgs = process.argv.slice(2)) {
   const version = await getVersion();
   const main = defineCommand({
@@ -1115,12 +1710,15 @@ async function runCli(rawArgs = process.argv.slice(2)) {
     },
     subCommands: {
       "init": initCommand,
+      "add": addCommand,
       "new": newFeatureCommand,
       "close": closeFeatureCommand,
       "status": statusCommand,
       "check": checkCommand,
       "deps": depsCommand,
-      "archive-index": archiveIndexCommand
+      "archive-index": archiveIndexCommand,
+      "specs-index": specsIndexCommand,
+      "doctor": doctorCommand
     }
   });
   await runMain(main, { rawArgs });