@oevery/rsp 2.0.3 → 2.0.4

package/dist/cli.mjs

@@ -119,7 +119,7 @@ function changeNameFromPath(changesDir, filePath) {
 function normalizeLogicalPath(pathValue) {
   return pathValue.split(sep).join("/").replace(/\\/g, "/");
 }
-function generateChangeContent(name, summary = "", kind) {
+function generateChangeContent(name, summary = "", kind, options = {}) {
   const proposalSummary = summary || (name === "project-setup" ? "Capture the project model, boundaries, and stable local constraints" : "<one-line summary>");
   if (name === "project-setup") {
     return `---
@@ -184,6 +184,8 @@ kind: ops
 `;
   }
   const frontmatterKind = kind ?? "<choose: feature | fix | refactor | docs | ops | research>";
+  if (options.lite)
+    return generateLiteChangeContent(name, proposalSummary, frontmatterKind);
   const template = getChangeTemplateByKind(kind);
   return `---
 kind: "${frontmatterKind}"
@@ -229,6 +231,58 @@ ${template.acceptanceSection}
   - [ ] Decide whether this change produced durable knowledge that belongs in \`.rsp/specs/\` or \`.rsp/rules/\`
   - [ ] If yes, write only stable facts to the smallest correct target file before archive; do not promote task history, debugging notes, or one-off implementation context
 
+## Blockers
+- none
+`;
+}
+function generateLiteChangeContent(name, proposalSummary, frontmatterKind) {
+  return `---
+kind: "${frontmatterKind}"
+---
+
+# Change: ${name}
+
+## Proposal
+- Summary: ${proposalSummary}
+- Why:
+  - <why this small change matters>
+- Scope:
+  - <what will change>
+- Non-goals:
+  - none
+
+## Spec
+### MODIFIED
+- Requirement: <observable outcome>
+  - <what should be true after this change>
+
+### Acceptance
+#### Scenario: change is complete
+- GIVEN <current context>
+- WHEN <the change is applied>
+- THEN <expected outcome>
+
+## Design
+- Approach:
+  - <minimal implementation approach>
+- Affected areas:
+  - <primary file, directory, or doc path>
+- Constraints:
+  - <important constraint, or none>
+
+## Tasks
+- [ ] Implement the small change
+- [ ] Verify the result
+
+## Verify
+- Automated:
+  - [ ] <exact command, or not needed: reason>
+- Manual:
+  - [ ] <exact scenario, or not needed: reason>
+- Durable updates:
+  - [ ] Decide whether this change produced durable knowledge that belongs in ".rsp/specs/" or ".rsp/rules/"
+  - [ ] If yes, write only stable facts to the smallest correct target file before archive
+
 ## Blockers
 - none
 `;
@@ -240,7 +294,7 @@ function getChangeTemplateByKind(kind) {
         why: "<what user need or capability gap this addresses>",
         scope: "<what new behavior or capability will be delivered>",
         nonGoals: "<what related capabilities are explicitly out of scope>",
-        specSection: "### ADDED\n- Requirement: <new user-facing behavior>\n  - <verifiable requirement for the new capability>",
+        specSection: "<!-- Describe observable behavior and requirements. Implementation notes belong in ## Design. -->\n### ADDED\n- Requirement: <new user-facing behavior>\n  - <verifiable requirement for the new capability>",
         acceptanceSection: "#### Scenario: user exercises the new capability\n- GIVEN <context>\n- WHEN <user action>\n- THEN <expected new behavior>",
         approach: "<how the new capability will be implemented>",
         affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
@@ -255,7 +309,7 @@ function getChangeTemplateByKind(kind) {
         why: "<what current behavior is wrong or broken>",
         scope: "<what specific defect is being corrected>",
         nonGoals: "<what related but separate issues are out of scope>",
-        specSection: "### MODIFIED\n- Requirement: correct behavior\n  - <expected correct behavior after the fix>",
+        specSection: "<!-- Describe expected correct behavior. Implementation notes belong in ## Design. -->\n### MODIFIED\n- Requirement: correct behavior\n  - <expected correct behavior after the fix>",
         acceptanceSection: "#### Scenario: defect is resolved\n- GIVEN <conditions that trigger the defect>\n- WHEN <action that previously failed>\n- THEN <expected correct outcome>\n- AND the original broken outcome no longer occurs",
         approach: "<root cause analysis and fix strategy>",
         affectedArea1: "<concrete file path, directory, module, or subsystem containing the defect>",
@@ -270,7 +324,7 @@ function getChangeTemplateByKind(kind) {
         why: "<what maintainability, readability, or structural issue motivates this>",
         scope: "<what code areas are being restructured>",
         nonGoals: "<no behavior change is expected or intended>",
-        specSection: "### MODIFIED\n- Requirement: internal structure improvement\n  - <desired structural outcome without observable behavior change>",
+        specSection: "<!-- Describe the desired structural outcome. Implementation notes belong in ## Design. -->\n### MODIFIED\n- Requirement: internal structure improvement\n  - <desired structural outcome without observable behavior change>",
         acceptanceSection: "#### Scenario: behavior is preserved after restructuring\n- GIVEN the existing codebase before the refactor\n- WHEN the refactored code runs against existing tests\n- THEN all existing tests pass unchanged",
         approach: "<how the code will be restructured (rename, extract, move, etc.)>",
         affectedArea1: "<concrete file path, directory, module, or subsystem being refactored>",
@@ -285,7 +339,7 @@ function getChangeTemplateByKind(kind) {
         why: "<why the documentation change matters>",
         scope: "<which docs, readers, or workflows will be updated>",
         nonGoals: "<what documentation behavior or audience is out of scope>",
-        specSection: "### MODIFIED\n- Requirement: documentation accuracy\n  - <what durable reader-facing behavior or explanation changes>",
+        specSection: "<!-- Describe what the reader should see or experience. Implementation notes belong in ## Design. -->\n### MODIFIED\n- Requirement: documentation accuracy\n  - <what durable reader-facing behavior or explanation changes>",
         acceptanceSection: "#### Scenario: reader follows the updated guidance\n- GIVEN the updated documentation\n- WHEN a reader follows the documented workflow\n- THEN the steps are accurate and sufficient",
         approach: "<how the documentation will be updated and organized>",
         affectedArea1: "<concrete doc path, directory, module doc, or documentation surface 1>",
@@ -300,7 +354,7 @@ function getChangeTemplateByKind(kind) {
         why: "<what question or uncertainty this research resolves>",
         scope: "<what system area, option set, or hypothesis is being examined>",
         nonGoals: "<what implementation work is explicitly out of scope>",
-        specSection: "### ADDED\n- Requirement: research outcome recording\n  - <what finding, option, or decision must be captured clearly>",
+        specSection: "<!-- Describe what finding or decision must be captured. Implementation notes belong in ## Design. -->\n### ADDED\n- Requirement: research outcome recording\n  - <what finding, option, or decision must be captured clearly>",
         acceptanceSection: "#### Scenario: research question is resolved\n- GIVEN the current uncertainty or open question\n- WHEN the investigation is completed\n- THEN the result is recorded clearly enough to guide follow-up work",
         approach: "<how the investigation will be performed and what evidence will be gathered>",
         affectedArea1: "<concrete file path, directory, module, subsystem, or source under investigation>",
@@ -315,7 +369,7 @@ function getChangeTemplateByKind(kind) {
         why: "<why this operational or environment change matters>",
         scope: "<what environment, workflow, or operational path changes>",
         nonGoals: "<what product or feature behavior will not change>",
-        specSection: "### MODIFIED\n- Requirement: operational behavior\n  - <what reliable operational outcome should change or stay true>",
+        specSection: "<!-- Describe the reliable operational outcome. Implementation notes belong in ## Design. -->\n### MODIFIED\n- Requirement: operational behavior\n  - <what reliable operational outcome should change or stay true>",
         acceptanceSection: "#### Scenario: operational path succeeds\n- GIVEN the target environment or workflow\n- WHEN the operational change is applied\n- THEN the expected operational outcome is reliable",
         approach: "<how the operational change will be applied safely>",
         affectedArea1: "<concrete script, config path, workflow, environment path, or operational surface 1>",
@@ -330,7 +384,7 @@ function getChangeTemplateByKind(kind) {
         why: "<why this change matters>",
         scope: "<what this change will do>",
         nonGoals: "<what this change will not do>",
-        specSection: "### ADDED\n- Requirement: <new or updated behavior>\n  - <verifiable requirement>",
+        specSection: "<!-- Describe observable behavior and requirements. Implementation notes belong in ## Design. -->\n### ADDED\n- Requirement: <new or updated behavior>\n  - <verifiable requirement>",
         acceptanceSection: "#### Scenario: <name>\n- GIVEN <context>\n- WHEN <action>\n- THEN <expected outcome>",
         approach: "<how the change will be implemented>",
         affectedArea1: "<concrete file path, directory, module, or subsystem 1>",
@@ -357,7 +411,7 @@ Read in order:
 5. .rsp/specs/INDEX.md
 6. only the relevant additional .rsp/rules/*.md and .rsp/specs/*.md files
 
-If \`.rsp/focus.d/\` is empty, ask what to work on or suggest \`npx -y @oevery/rsp create <name>\`.
+If \`.rsp/focus.d/\` is empty and the user has not provided a concrete task, ask what to work on or suggest \`npx -y @oevery/rsp create <name>\` for tracked work.
 If your agent supports Agent Skills, load \`rsp\` for setup, repair, and durable-decision tasks.
 ${RSP_AGENTS_END}`;
 }
@@ -547,6 +601,57 @@ function detectDeltaSections(content) {
     removed: /^###\s*REMOVED/im.test(body)
   };
 }
+function collectArchiveReadiness(content) {
+  const warnings = [];
+  const tasksSection = extractSection(content, "Tasks");
+  const verifySection = extractSection(content, "Verify");
+  const taskTodos = getOpenCheckboxes(tasksSection);
+  if (taskTodos.length > 0)
+    warnings.push(`${taskTodos.length} task item(s) still incomplete`);
+  const verifyTodos = getOpenCheckboxes(verifySection);
+  if (verifyTodos.length > 0)
+    warnings.push(`${verifyTodos.length} Verify checklist item(s) are still incomplete`);
+  const 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 = activeBlockers ? "no" : warnings.length === 0 ? "yes" : "judgment";
+  return {
+    taskTodos,
+    verifyTodos,
+    activeBlockers,
+    scenarioCount: scenarios.length,
+    missingScenarios,
+    deterministic: warnings.length === 0 ? "pass" : "warnings",
+    semantic: "needs-review",
+    archiveReady,
+    warnings
+  };
+}
+function buildDurableReviewGuidance(candidateTargets) {
+  return {
+    required: true,
+    decisions: [
+      "No durable update needed",
+      "Update existing spec or rule",
+      "Create a new durable spec"
+    ],
+    candidateTargets,
+    note: "Semantic review decides whether stable facts belong in specs or rules; the CLI never merges delta specs automatically."
+  };
+}
+function getDurableReviewCandidateTargets(options = {}) {
+  const targets = [".rsp/specs/design.md"];
+  if (options.projectRulesExists)
+    targets.push(".rsp/rules/project-rules.md");
+  return targets;
+}
+function collectArchiveChecklist(content) {
+  return collectArchiveReadiness(content).warnings;
+}
 function parseScenarios(content) {
   const scenarios = [];
   const regex = /^#{3,4}\s*Scenario:\s*(.+)$/gim;
@@ -692,20 +797,30 @@ import { dirname as dirname4, join as join5 } from "path";
 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 } = {}) {
+async function buildSpecsIndex({ acquireLock = true, quiet = false } = {}) {
   if (acquireLock)
-    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false }));
+    return withRspLock("specs-index", async () => buildSpecsIndex({ acquireLock: false, quiet }));
   const specsDir = join4(RSP_DIR, "specs");
   if (!existsSync4(specsDir)) {
-    console.log(`  ${pc.dim("No specs directory.")}
+    if (!quiet)
+      console.log(`  ${pc.dim("No specs directory.")}
 `);
-    return;
+    return false;
   }
   const specFiles = (await walkMarkdownFiles(specsDir)).filter((fp) => {
     const name = basename2(fp);
     return name !== "INDEX.md" && name !== "design.md";
   }).sort();
   const lines = [];
+  lines.push("---");
+  lines.push("title: Specs Index");
+  lines.push("summary: Additional project-level specs beyond design.md.");
+  lines.push("kind: generated-index");
+  lines.push("index_type: specs");
+  lines.push("source_dir: .rsp/specs");
+  lines.push(`entry_count: ${specFiles.length}`);
+  lines.push("---");
+  lines.push("");
   lines.push("# Specs Index");
   lines.push("");
   lines.push("_Additional project-level specs beyond `design.md`._");
@@ -725,11 +840,16 @@ async function buildSpecsIndex({ acquireLock = true } = {}) {
       lines.push(`| ${escapeCell(rel)} | ${escapeCell(title)} | ${escapeCell(summary || "\u2014")} |`);
     }
   }
-  lines.push("");
-  lines.push("_Auto-generated by `rsp update`._");
-  await writeFile3(join4(specsDir, "INDEX.md"), lines.join("\n"));
-  console.log(`  ${pc.green("INDEX.md updated:")} ${specFiles.length} spec file(s).
+  const indexPath = join4(specsDir, "INDEX.md");
+  const nextContent = lines.join("\n");
+  const existingContent = existsSync4(indexPath) ? await readFile4(indexPath, "utf-8") : null;
+  const changed = existingContent !== nextContent;
+  if (changed)
+    await writeFile3(indexPath, nextContent);
+  if (!quiet)
+    console.log(`  ${pc.green("INDEX.md updated:")} ${specFiles.length} spec file(s).
 `);
+  return changed;
 }
 function extractTitle(content) {
   for (const rawLine of content.split("\n")) {
@@ -796,25 +916,33 @@ import { basename as basename4, dirname as dirname6, join as join7 } from "path"
 import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import { basename as basename3, dirname as dirname5, join as join6, relative as relative3 } from "path";
-async function buildArchiveIndex({ acquireLock = true } = {}) {
+async function buildArchiveIndex({ acquireLock = true, quiet = false } = {}) {
   if (acquireLock)
-    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false }));
+    return withRspLock("archive-index", async () => buildArchiveIndex({ acquireLock: false, quiet }));
   if (!existsSync6(ARCHIVES_DIR)) {
-    console.log(`  ${pc.dim("No archives directory.")}
+    if (!quiet)
+      console.log(`  ${pc.dim("No archives directory.")}
 `);
-    return;
+    return false;
   }
   const archiveFiles = (await walkMarkdownFiles(ARCHIVES_DIR)).filter((fp) => basename3(fp) !== "INDEX.md").sort();
   const lines = [];
-  lines.push("# Archive Index");
+  lines.push("---");
+  lines.push("title: Archive Index");
+  lines.push("summary: Completed RSP changes.");
+  lines.push("kind: generated-index");
+  lines.push("index_type: archives");
+  lines.push("source_dir: .rsp/archives");
+  lines.push(`entry_count: ${archiveFiles.length}`);
+  lines.push("---");
   lines.push("");
-  lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
+  lines.push("# Archive Index");
   lines.push("");
   if (archiveFiles.length === 0) {
     lines.push("_No archived changes yet._");
   } else {
-    lines.push("| Date | Change | Summary |");
-    lines.push("|------|--------|---------|");
+    lines.push("| Date | Change | Kind | Summary |");
+    lines.push("|------|--------|------|---------|");
   }
   for (const fp of archiveFiles) {
     const base = basename3(fp);
@@ -825,27 +953,39 @@ async function buildArchiveIndex({ acquireLock = true } = {}) {
     const baseName = dateMatch ? dateMatch[2] : base.replace(/\.md$/, "");
     const changeName = archiveDirPart !== "." ? `${archiveDirPart}/${baseName}` : baseName;
     let summary = "";
+    let kind = "";
     try {
       const content = await readFile5(fp, "utf-8");
+      const fm = parseFrontmatter(content);
+      if (typeof fm?.kind === "string")
+        kind = fm.kind;
+      if (typeof fm?.summary === "string")
+        summary = fm.summary.trim();
       const proposal = extractSection(content, "Proposal");
       const summaryLine = proposal.split("\n").map((line) => line.trim()).find((line) => line.startsWith("- Summary:"));
-      if (summaryLine)
+      if (!summary && summaryLine)
         summary = summaryLine.slice("- Summary:".length).trim();
     } catch {
     }
-    const summaryCell = summary ? summary.replace(/\|/g, "\\|") : "\u2014";
-    lines.push(`| ${date} | ${changeName} | ${summaryCell} |`);
+    lines.push(`| ${date} | ${escapeCell2(changeName)} | ${escapeCell2(kind || "\u2014")} | ${escapeCell2(summary || "\u2014")} |`);
   }
-  lines.push("");
-  lines.push("_Auto-generated by `rsp update`._");
   const indexPath = join6(ARCHIVES_DIR, "INDEX.md");
-  await writeFile5(indexPath, lines.join("\n"));
-  console.log(`  ${pc.green("INDEX.md updated:")} ${archiveFiles.length} archived change(s).
+  const nextContent = lines.join("\n");
+  const existingContent = existsSync6(indexPath) ? await readFile5(indexPath, "utf-8") : null;
+  const changed = existingContent !== nextContent;
+  if (changed)
+    await writeFile5(indexPath, nextContent);
+  if (!quiet)
+    console.log(`  ${pc.green("INDEX.md updated:")} ${archiveFiles.length} archived change(s).
 `);
+  return changed;
+}
+function escapeCell2(value) {
+  return value.replace(/\|/g, "\\|");
 }
 
 // src/commands/archive.ts
-async function archiveChange(name) {
+async function archiveChange(name, options = {}) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp archive <name>`);
     process.exit(1);
@@ -860,6 +1000,24 @@ async function archiveChange(name) {
     console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
     process.exit(1);
   }
+  if (options.dryRun) {
+    const content = await readFile6(srcPath, "utf-8");
+    const checklist = collectArchiveChecklist(content);
+    console.log();
+    console.log(`  ${pc.bold("Archive dry-run for")} ${pc.cyan(name)}`);
+    console.log();
+    if (checklist.length === 0) {
+      console.log(`  ${pc.green("\u2713")} Ready to archive. No deterministic warnings found.
+`);
+    } else {
+      for (const line of checklist)
+        console.log(`  ${pc.yellow("\u26A0")} ${line}`);
+      console.log();
+      console.log(`  ${pc.dim("Review the warnings above before treating this work as fully closed.")}
+`);
+    }
+    return;
+  }
   return withRspLock("archive-change", async () => {
     const content = await readFile6(srcPath, "utf-8");
     const checklist = collectArchiveChecklist(content);
@@ -929,23 +1087,6 @@ function resolveArchiveName(archiveSubdir, date, base) {
   console.error(`  ${pc.red("Error:")} archive name collision exceeded ${MAX_SUFFIX} attempts for ${base}`);
   process.exit(1);
 }
-function collectArchiveChecklist(content) {
-  const warnings = [];
-  const tasksSection = extractSection(content, "Tasks");
-  const verifySection = extractSection(content, "Verify");
-  const taskTodos = getOpenCheckboxes(tasksSection);
-  if (taskTodos.length > 0)
-    warnings.push(`${taskTodos.length} task item(s) still incomplete`);
-  const verifyTodos = getOpenCheckboxes(verifySection);
-  if (verifyTodos.length > 0)
-    warnings.push(`${verifyTodos.length} Verify checklist item(s) are still incomplete`);
-  if (hasMeaningfulBlockers(content))
-    warnings.push("active blockers are present in the change file");
-  const scenarios = parseScenarios(content);
-  if (scenarios.length === 0)
-    warnings.push("no Scenario blocks found (some changes do not need them)");
-  return warnings;
-}
 
 // src/commands/check.ts
 import { existsSync as existsSync8 } from "fs";
@@ -960,6 +1101,10 @@ async function runCheck(options = {}) {
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
   const addDiagnostic = (diagnostic) => diagnostics.push(diagnostic);
+  let focusedSet = /* @__PURE__ */ new Set();
+  if (options.focused) {
+    focusedSet = await getFocusedChangeNames({ onError: reportRuntime });
+  }
   if (existsSync8(FOCUS_DIR)) {
     const entries = await walkFiles(FOCUS_DIR, { onError: reportRuntime });
     for (const entryPath of entries) {
@@ -1004,11 +1149,13 @@ async function runCheck(options = {}) {
       }
     }
   }
-  const changeFiles = existsSync8(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
+  const allChangeFiles = existsSync8(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
+  const changeFiles = options.focused ? allChangeFiles.filter((fp) => focusedSet.has(changeNameFromPath(CHANGES_DIR, fp))) : allChangeFiles;
   if (changeFiles.length === 0) {
     const result2 = {
       command: "check",
       ok: diagnostics.every((d) => d.severity !== "error"),
+      focused: Boolean(options.focused),
       diagnostics,
       runtime,
       summary: {
@@ -1023,6 +1170,8 @@ async function runCheck(options = {}) {
     }
     console.log();
     console.log(`  ${pc.bold("RSP check")}`);
+    if (options.focused)
+      console.log(`  ${pc.dim("(focused only)")}`);
     console.log();
     if (diagnostics.length === 0) {
       console.log(`  ${pc.dim("No change files to check.")}
@@ -1159,6 +1308,30 @@ async function runCheck(options = {}) {
         message: `delta markers found: ${parts.join(", ")}`
       });
     }
+    const placeholderLines = findUnfinishedTemplateLines(content);
+    if (placeholderLines.length > 0) {
+      addDiagnostic({
+        severity: "warning",
+        code: "unfinished_template_placeholders",
+        change: name,
+        path: fp,
+        message: "unfinished template placeholders found",
+        details: placeholderLines,
+        hint: "Replace angle-bracket template text with concrete change details before archiving."
+      });
+    }
+    const clarificationLines = findUnresolvedClarificationLines(content);
+    if (clarificationLines.length > 0) {
+      addDiagnostic({
+        severity: "warning",
+        code: "unresolved_clarifications",
+        change: name,
+        path: fp,
+        message: "unresolved clarification markers found",
+        details: clarificationLines,
+        hint: "Resolve or remove clarification markers once the open question is answered."
+      });
+    }
     const scenarios = parseScenarios(content);
     if (scenarios.length > 0) {
       const scenarioIssues = [];
@@ -1191,6 +1364,7 @@ async function runCheck(options = {}) {
   const result = {
     command: "check",
     ok: diagnostics.every((d) => d.severity !== "error"),
+    focused: Boolean(options.focused),
     diagnostics,
     runtime,
     summary: {
@@ -1205,6 +1379,8 @@ async function runCheck(options = {}) {
   }
   console.log();
   console.log(`  ${pc.bold("RSP check")}`);
+  if (options.focused)
+    console.log(`  ${pc.dim("(focused only)")}`);
   console.log();
   for (const diagnostic of diagnostics) {
     const icon = diagnostic.severity === "error" ? pc.red("\u2717") : diagnostic.severity === "warning" ? pc.yellow("\u26A0") : pc.dim("\u2139");
@@ -1225,12 +1401,35 @@ async function runCheck(options = {}) {
 `);
   return result;
 }
+function findUnfinishedTemplateLines(content) {
+  const placeholderRe = /<[^>\n]*(?:choose:|one-line|what |why |which |who |how |new |updated |expected |actual |specific |concrete |exact |verifiable |user |capability |behavior |context |action |path|directory|module|subsystem|command|scenario|constraint|requirement|question|uncertainty|implementation)[^>\n]*>/i;
+  return collectMatchingLines(content, (line) => {
+    const trimmed = stripInlineCodeSpans(line).trim();
+    return trimmed.startsWith("<!--") === false && placeholderRe.test(trimmed);
+  });
+}
+function findUnresolvedClarificationLines(content) {
+  return collectMatchingLines(content, (line) => /\[(?:NEEDS|TODO|TBD)\s+CLARIFICATION(?::[^\]]*)?\]/i.test(stripInlineCodeSpans(line)));
+}
+function stripInlineCodeSpans(line) {
+  return line.replace(/`[^`]*`/g, "");
+}
+function collectMatchingLines(content, predicate) {
+  const matches = [];
+  const lines = content.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (predicate(line))
+      matches.push(`line ${index + 1}: ${line.trim()}`);
+  }
+  return matches.slice(0, 10);
+}
 
 // src/commands/create.ts
 import { existsSync as existsSync9 } from "fs";
 import { mkdir as mkdir5, writeFile as writeFile6 } from "fs/promises";
 import { dirname as dirname7, join as join9 } from "path";
-async function createChange(name, summary = "", kind) {
+async function createChange(name, summary = "", kind, options = {}) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp create <name> [summary]`);
     process.exit(1);
@@ -1245,7 +1444,7 @@ async function createChange(name, summary = "", kind) {
     await mkdir5(dirname7(changePath), { recursive: true });
     const existed = existsSync9(changePath);
     if (!existed) {
-      const content = generateChangeContent(name, summary, kind);
+      const content = generateChangeContent(name, summary, kind, { lite: Boolean(options.lite) });
       await writeFile6(changePath, content);
       await mkdir5(FOCUS_DIR, { recursive: true });
       const focusEntry = join9(FOCUS_DIR, name);
@@ -1258,37 +1457,101 @@ async function createChange(name, summary = "", kind) {
       console.log(`  ${pc.dim("Unchanged focus.")} Run: rsp focus ${name}`);
     else
       console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${name}`);
-    console.log(`  ${pc.cyan("Next:")} fill proposal/spec/design first, then implement and complete the tasks
+    console.log(`  ${pc.cyan("Next:")} ${options.lite ? "fill the lite change details, then implement and verify" : "fill proposal/spec/design first, then implement and complete the tasks"}
 `);
   });
 }
 
 // src/commands/doctor.ts
+import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile9 } from "fs/promises";
+import { basename as basename5, join as join11, relative as relative5 } from "path";
+
+// src/commands/update.ts
 import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile8 } from "fs/promises";
-import { basename as basename5, join as join10, relative as relative5 } from "path";
+import { mkdir as mkdir6, readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
+import { join as join10 } from "path";
+var SKILL_REFRESH_HINT = "  Note: if you use the published RSP skill, refresh it too:\n    npx skills add oevery/rsp\n";
+async function updateProject(options = {}) {
+  if (!existsSync10(RSP_DIR)) {
+    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
+    console.error(`  ${pc.dim("Run: rsp init")}`);
+    process.exit(1);
+  }
+  return withRspLock("update", async () => {
+    let updated = false;
+    const actions = [];
+    const bundledRules = await readFile8(join10(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    const rulesPath = join10(RSP_DIR, "rules", "rsp-rules.md");
+    await mkdir6(join10(RSP_DIR, "rules"), { recursive: true });
+    const existingRules = existsSync10(rulesPath) ? await readFile8(rulesPath, "utf-8") : null;
+    if (existingRules !== bundledRules) {
+      await writeFile7(rulesPath, bundledRules);
+      actions.push("rules/rsp-rules.md updated");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} rules/rsp-rules.md updated`);
+      updated = true;
+    }
+    const agentsPath = "AGENTS.md";
+    const projectName = await detectProjectName();
+    const baseAgents = existsSync10(agentsPath) ? await readFile8(agentsPath, "utf-8") : `# ${projectName}
+
+`;
+    const nextAgents = upsertRspAgentsBlock(baseAgents);
+    if (!existsSync10(agentsPath) || nextAgents.changed) {
+      await writeFile7(agentsPath, nextAgents.content);
+      actions.push("AGENTS.md managed block refreshed");
+      if (!options.quiet)
+        console.log(`  ${pc.green("\u2713")} AGENTS.md managed block refreshed`);
+      updated = true;
+    }
+    const specsIndexChanged = await buildSpecsIndex({ acquireLock: false, quiet: options.quiet });
+    const archiveIndexChanged = await buildArchiveIndex({ acquireLock: false, quiet: options.quiet });
+    if (specsIndexChanged || archiveIndexChanged) {
+      actions.push("generated indexes rebuilt");
+      updated = true;
+    }
+    if (!options.quiet && !updated) {
+      console.log(`  ${pc.dim("Already up to date.")}
+`);
+      console.log(SKILL_REFRESH_HINT);
+    } else if (!options.quiet) {
+      console.log(`  ${pc.green("Update complete.")}
+`);
+      console.log(SKILL_REFRESH_HINT);
+    }
+    return actions;
+  });
+}
+
+// src/commands/doctor.ts
 async function runDoctor(options = {}) {
+  const fixed = [];
+  if (options.fix && existsSync11(RSP_DIR)) {
+    fixed.push(...await updateProject({ quiet: Boolean(options.json) }));
+  }
   const checks = [];
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
-  const rspRulesPath = join10(RSP_DIR, "rules", "rsp-rules.md");
-  const designPath = join10(RSP_DIR, "specs", "design.md");
-  const specsIndexPath = join10(RSP_DIR, "specs", "INDEX.md");
-  const archivesIndexPath = join10(RSP_DIR, "archives", "INDEX.md");
-  reportCheck(checks, ".rsp exists", existsSync10(RSP_DIR), "Run: rsp init");
-  reportCheck(checks, "rules/rsp-rules.md exists", existsSync10(rspRulesPath), "Run: rsp init");
-  reportCheck(checks, "specs/design.md exists", existsSync10(designPath), "Run: rsp init");
-  reportCheck(checks, "specs/INDEX.md exists", existsSync10(specsIndexPath), "Run: rsp update");
-  reportCheck(checks, "archives/INDEX.md exists", existsSync10(archivesIndexPath), "Run: rsp update");
+  const rspRulesPath = join11(RSP_DIR, "rules", "rsp-rules.md");
+  const designPath = join11(RSP_DIR, "specs", "design.md");
+  const specsIndexPath = join11(RSP_DIR, "specs", "INDEX.md");
+  const archivesIndexPath = join11(RSP_DIR, "archives", "INDEX.md");
+  reportCheck(checks, ".rsp exists", existsSync11(RSP_DIR), "Run: rsp init");
+  reportCheck(checks, "rules/rsp-rules.md exists", existsSync11(rspRulesPath), "Run: rsp init");
+  reportCheck(checks, "specs/design.md exists", existsSync11(designPath), "Run: rsp init");
+  reportCheck(checks, "specs/INDEX.md exists", existsSync11(specsIndexPath), "Run: rsp update");
+  reportCheck(checks, "archives/INDEX.md exists", existsSync11(archivesIndexPath), "Run: rsp update");
   await checkAgents(checks, reportRuntime);
-  await checkGeneratedIndex(checks, reportRuntime, specsIndexPath, "_Auto-generated by `rsp update`._", "specs/INDEX.md has generated signature", "Run: rsp update");
-  await checkGeneratedIndex(checks, reportRuntime, archivesIndexPath, "_Auto-generated by `rsp update`._", "archives/INDEX.md has generated signature", "Run: rsp update");
+  await checkGeneratedIndex(checks, reportRuntime, specsIndexPath, "specs", "specs/INDEX.md has generated-index metadata", "Run: rsp update");
+  await checkGeneratedIndex(checks, reportRuntime, archivesIndexPath, "archives", "archives/INDEX.md has generated-index metadata", "Run: rsp update");
   await checkArchiveNaming(checks, reportRuntime);
   await checkConfigSemantics(checks, reportRuntime);
   await checkActiveChangeConsistency(checks, reportRuntime);
   const result = {
     command: "doctor",
     ok: checks.every((check) => check.status !== "issue"),
+    fixed,
     checks,
     runtime,
     summary: {
@@ -1302,6 +1565,13 @@ async function runDoctor(options = {}) {
   console.log();
   console.log(`  ${pc.bold("RSP doctor")}`);
   console.log();
+  if (fixed.length > 0) {
+    console.log(`  ${pc.green("Fixed:")} ${fixed.join(", ")}`);
+    console.log();
+  } else if (options.fix) {
+    console.log(`  ${pc.dim("No safe fixes needed.")}`);
+    console.log();
+  }
   for (const check of checks)
     printDoctorCheck(check);
   if (result.summary.issues === 0)
@@ -1337,13 +1607,13 @@ function printDoctorCheck(check) {
     console.log(`    ${pc.dim(check.hint)}`);
 }
 async function checkAgents(checks, reportRuntime) {
-  if (!existsSync10("AGENTS.md")) {
+  if (!existsSync11("AGENTS.md")) {
     checks.push({ status: "issue", label: "AGENTS.md contains managed RSP block", message: "AGENTS.md missing", hint: "Run: rsp init" });
     return;
   }
   let agents;
   try {
-    agents = await readFile8("AGENTS.md", "utf-8");
+    agents = await readFile9("AGENTS.md", "utf-8");
   } catch (error) {
     reportRuntime({
       code: "agents_read_failed",
@@ -1360,12 +1630,12 @@ async function checkAgents(checks, reportRuntime) {
   }
   checks.push({ status: "issue", label: "AGENTS.md contains managed RSP block", message: "AGENTS.md missing managed RSP block", hint: "Run: rsp init" });
 }
-async function checkGeneratedIndex(checks, reportRuntime, path, signature, label, fixHint) {
-  if (!existsSync10(path))
+async function checkGeneratedIndex(checks, reportRuntime, path, expectedIndexType, label, fixHint) {
+  if (!existsSync11(path))
     return;
   let content;
   try {
-    content = await readFile8(path, "utf-8");
+    content = await readFile9(path, "utf-8");
   } catch (error) {
     reportRuntime({
       code: "generated_index_read_failed",
@@ -1376,15 +1646,27 @@ async function checkGeneratedIndex(checks, reportRuntime, path, signature, label
     checks.push({ status: "issue", label, message: `${label} could not be read`, hint: fixHint });
     return;
   }
-  if (content.includes(signature)) {
-    checks.push({ status: "ok", label });
+  try {
+    const fm = parseFrontmatter(content);
+    if (fm?.kind === "generated-index" && fm.index_type === expectedIndexType) {
+      checks.push({ status: "ok", label });
+      return;
+    }
+  } catch (error) {
+    reportRuntime({
+      code: "generated_index_frontmatter_parse_failed",
+      operation: "parseFrontmatter",
+      path,
+      message: toErrorMessage(error)
+    });
+    checks.push({ status: "issue", label, message: `${label} could not parse metadata`, hint: fixHint });
     return;
   }
   checks.push({ status: "issue", label, hint: fixHint });
 }
 async function checkArchiveNaming(checks, reportRuntime) {
-  const archivesDir = join10(RSP_DIR, "archives");
-  const archiveFiles = existsSync10(archivesDir) ? (await walkMarkdownFiles(archivesDir, { onError: reportRuntime })).filter((fp) => relative5(archivesDir, fp) !== "INDEX.md") : [];
+  const archivesDir = join11(RSP_DIR, "archives");
+  const archiveFiles = existsSync11(archivesDir) ? (await walkMarkdownFiles(archivesDir, { onError: reportRuntime })).filter((fp) => relative5(archivesDir, fp) !== "INDEX.md") : [];
   const invalidFiles = archiveFiles.map((fp) => normalizeLogicalPath(relative5(archivesDir, fp))).filter((fp) => /^\d{4}-\d{2}-\d{2}_.+\.md$/.test(basename5(fp)) === false);
   if (invalidFiles.length === 0) {
     checks.push({ status: "ok", label: "archived change files follow the date_name.md convention" });
@@ -1398,11 +1680,11 @@ async function checkArchiveNaming(checks, reportRuntime) {
   });
 }
 async function checkConfigSemantics(checks, reportRuntime) {
-  if (!existsSync10(CONFIG_PATH))
+  if (!existsSync11(CONFIG_PATH))
     return;
   let content;
   try {
-    content = await readFile8(CONFIG_PATH, "utf-8");
+    content = await readFile9(CONFIG_PATH, "utf-8");
   } catch (error) {
     reportRuntime({
       code: "config_read_failed",
@@ -1458,7 +1740,7 @@ function reportConfigListField(checks, parsed, key) {
   });
 }
 async function checkActiveChangeConsistency(checks, reportRuntime) {
-  const changeFiles = existsSync10(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
+  const changeFiles = existsSync11(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
   const changeNames = new Set(changeFiles.map((fp) => changeNameFromPath(CHANGES_DIR, fp)));
   const focusNames = await getFocusedChangeNames({ onError: reportRuntime });
   const missingChangeFiles = [...focusNames].filter((name) => !changeNames.has(name));
@@ -1488,9 +1770,9 @@ async function checkActiveChangeConsistency(checks, reportRuntime) {
 }
 
 // src/commands/focus.ts
-import { existsSync as existsSync11 } from "fs";
-import { mkdir as mkdir6, unlink as unlink3, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname8, join as join11 } from "path";
+import { existsSync as existsSync12 } from "fs";
+import { mkdir as mkdir7, unlink as unlink3, writeFile as writeFile8 } from "fs/promises";
+import { dirname as dirname8, join as join12 } from "path";
 async function focusChange(name) {
   if (!name) {
     console.error(`  ${pc.red("Usage:")} rsp focus <name>`);
@@ -1501,16 +1783,16 @@ async function focusChange(name) {
     process.exit(1);
   }
   guardRspInitialized();
-  const changePath = join11(CHANGES_DIR, `${name}.md`);
-  if (!existsSync11(changePath)) {
+  const changePath = join12(CHANGES_DIR, `${name}.md`);
+  if (!existsSync12(changePath)) {
     console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
     process.exit(1);
   }
   return withRspLock("focus-change", async () => {
-    await mkdir6(FOCUS_DIR, { recursive: true });
-    const focusEntry = join11(FOCUS_DIR, name);
-    await mkdir6(dirname8(focusEntry), { recursive: true });
-    await writeFile7(focusEntry, "");
+    await mkdir7(FOCUS_DIR, { recursive: true });
+    const focusEntry = join12(FOCUS_DIR, name);
+    await mkdir7(dirname8(focusEntry), { recursive: true });
+    await writeFile8(focusEntry, "");
     console.log(`  ${pc.green("Focused:")} ${name}`);
     console.log(`  ${pc.dim("focus.d")} \u2192 ${name}`);
     console.log();
@@ -1526,8 +1808,8 @@ async function unfocusChange(name) {
     process.exit(1);
   }
   guardRspInitialized();
-  const focusEntry = join11(FOCUS_DIR, name);
-  if (!existsSync11(focusEntry)) {
+  const focusEntry = join12(FOCUS_DIR, name);
+  if (!existsSync12(focusEntry)) {
     console.error(`  ${pc.red("Focus marker not found:")} .rsp/focus.d/${name}`);
     process.exit(1);
   }
@@ -1541,9 +1823,9 @@ async function unfocusChange(name) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync12 } from "fs";
-import { mkdir as mkdir7, readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
-import { join as join12 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile9 } from "fs/promises";
+import { join as join13 } from "path";
 function generateConfigTemplate() {
   const fmtList = (items, indent) => items.map((i) => `${" ".repeat(indent)}# - ${i}`).join("\n");
   return `# RSP project configuration
@@ -1557,16 +1839,16 @@ ${fmtList(VALID_KINDS, 2)}
 `;
 }
 async function ensureFile(path, content) {
-  if (existsSync12(path))
+  if (existsSync13(path))
     return false;
-  await writeFile8(path, content);
+  await writeFile9(path, content);
   return true;
 }
 function toTitle(projectName) {
   return projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
 }
 async function initProject(args = {}) {
-  const isNew = !existsSync12(RSP_DIR);
+  const isNew = !existsSync13(RSP_DIR);
   const projectName = await detectProjectName();
   const mode = args.agentsMode ?? "managed";
   if (mode !== "managed" && mode !== "print") {
@@ -1575,32 +1857,32 @@ async function initProject(args = {}) {
   }
   return withRspLock("init", async () => {
     const dirs = [
-      join12(RSP_DIR, "rules"),
-      join12(RSP_DIR, "specs"),
+      join13(RSP_DIR, "rules"),
+      join13(RSP_DIR, "specs"),
       CHANGES_DIR,
       FOCUS_DIR,
-      join12(RSP_DIR, "archives")
+      join13(RSP_DIR, "archives")
     ];
     for (const d of dirs)
-      await mkdir7(d, { recursive: true });
+      await mkdir8(d, { recursive: true });
     let created = false;
-    const bundledRules = await readFile9(join12(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
-    created = await ensureFile(join12(RSP_DIR, "rules", "rsp-rules.md"), bundledRules) || created;
-    created = await ensureFile(join12(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
-    const createdSpecsIndex = await ensureFile(join12(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Additional project-level specs beyond `design.md`._\n");
+    const bundledRules = await readFile10(join13(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    created = await ensureFile(join13(RSP_DIR, "rules", "rsp-rules.md"), bundledRules) || created;
+    created = await ensureFile(join13(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
+    const createdSpecsIndex = await ensureFile(join13(RSP_DIR, "specs", "INDEX.md"), "# Specs Index\n\n_Additional project-level specs beyond `design.md`._\n");
     created = createdSpecsIndex || created;
-    const createdDesign = await ensureFile(join12(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
+    const createdDesign = await ensureFile(join13(RSP_DIR, "specs", "design.md"), generateDesignContent(projectName));
     created = createdDesign || created;
-    const createdArchivesIndex = await ensureFile(join12(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
+    const createdArchivesIndex = await ensureFile(join13(RSP_DIR, "archives", "INDEX.md"), "# Archive Index\n");
     created = createdArchivesIndex || created;
-    created = await ensureFile(join12(CHANGES_DIR, ".gitkeep"), "") || created;
-    created = await ensureFile(join12(FOCUS_DIR, ".gitkeep"), "") || created;
-    created = await ensureFile(join12(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
+    created = await ensureFile(join13(CHANGES_DIR, ".gitkeep"), "") || created;
+    created = await ensureFile(join13(FOCUS_DIR, ".gitkeep"), "") || created;
+    created = await ensureFile(join13(RSP_DIR, ".gitignore"), "# Transient files that should not be committed\n.lock\n") || created;
     if (args.withProjectRules)
-      created = await ensureFile(join12(RSP_DIR, "rules", "project-rules.md"), generateProjectRulesContent(projectName)) || created;
+      created = await ensureFile(join13(RSP_DIR, "rules", "project-rules.md"), generateProjectRulesContent(projectName)) || created;
     if (args.withProjectSetup) {
-      const changePath = join12(CHANGES_DIR, "project-setup.md");
-      const focusMarker = join12(FOCUS_DIR, "project-setup");
+      const changePath = join13(CHANGES_DIR, "project-setup.md");
+      const focusMarker = join13(FOCUS_DIR, "project-setup");
       created = await ensureFile(changePath, generateChangeContent("project-setup")) || created;
       created = await ensureFile(focusMarker, "") || created;
     }
@@ -1611,24 +1893,24 @@ async function initProject(args = {}) {
     const agentsPath = "AGENTS.md";
     const title = toTitle(projectName);
     let agentsUpdated = false;
-    if (!existsSync12(agentsPath)) {
-      await writeFile8(agentsPath, `# ${title}
+    if (!existsSync13(agentsPath)) {
+      await writeFile9(agentsPath, `# ${title}
 
 ${upsertRspAgentsBlock("").content}
 `);
       created = true;
       agentsUpdated = true;
     } else {
-      const existing = await readFile9(agentsPath, "utf-8");
+      const existing = await readFile10(agentsPath, "utf-8");
       const next = upsertRspAgentsBlock(existing);
       if (next.changed) {
-        await writeFile8(agentsPath, next.content);
+        await writeFile9(agentsPath, next.content);
         created = true;
         agentsUpdated = true;
       }
     }
     if (mode === "print") {
-      const managed = await readFile9(agentsPath, "utf-8");
+      const managed = await readFile10(agentsPath, "utf-8");
       console.log(`
 ${managed}
 `);
@@ -1665,10 +1947,258 @@ ${managed}
   });
 }
 
+// src/commands/ready.ts
+import { existsSync as existsSync14 } from "fs";
+import { readFile as readFile11 } from "fs/promises";
+import { join as join14 } from "path";
+async function showReady(name, options = {}) {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp ready <name>`);
+    process.exit(1);
+  }
+  if (!isValidChangeName(name)) {
+    console.error(`  ${pc.red("Error:")} change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  const srcPath = join14(CHANGES_DIR, `${name}.md`);
+  if (!existsSync14(srcPath)) {
+    console.error(`  ${pc.red("Change not found:")} .rsp/changes/${name}.md`);
+    process.exit(1);
+  }
+  const runtime = [];
+  let content;
+  try {
+    content = await readFile11(srcPath, "utf-8");
+  } catch {
+    console.error(`  ${pc.red("Error:")} unable to read .rsp/changes/${name}.md`);
+    process.exit(1);
+  }
+  const readinessDetails = collectArchiveReadiness(content);
+  const checklist = readinessDetails.warnings;
+  const readiness = {
+    incompleteTasks: readinessDetails.taskTodos.length,
+    incompleteVerify: readinessDetails.verifyTodos.length,
+    activeBlockers: readinessDetails.activeBlockers,
+    missingScenarios: readinessDetails.missingScenarios,
+    deterministic: readinessDetails.deterministic,
+    semantic: readinessDetails.semantic,
+    archiveReady: readinessDetails.archiveReady
+  };
+  const durableReview = buildDurableReviewGuidance(getReadyDurableReviewCandidateTargets());
+  const result = {
+    command: "ready",
+    ok: true,
+    change: name,
+    path: normalizeLogicalPath(srcPath),
+    readiness,
+    durableReview,
+    warnings: checklist,
+    runtime
+  };
+  if (options.json) {
+    emitJson(result);
+    return result;
+  }
+  console.log();
+  console.log(`  ${pc.bold("Archive readiness for")} ${pc.cyan(name)}`);
+  console.log();
+  if (checklist.length === 0) {
+    console.log(`  ${pc.green("\u2713")} Ready to archive. No deterministic warnings found.
+`);
+  } else {
+    for (const line of checklist)
+      console.log(`  ${pc.yellow("\u26A0")} ${line}`);
+    console.log();
+    console.log(`  ${pc.dim("Review the warnings above before treating this work as fully closed.")}`);
+    console.log(`  ${pc.dim("Run:")} rsp archive ${name}
+`);
+  }
+  console.log(`  ${pc.dim("Deterministic readiness:")} ${readiness.deterministic === "pass" ? pc.green("pass") : pc.yellow("warnings")}`);
+  console.log(`  ${pc.dim("Semantic review:")} ${pc.yellow("needed")}`);
+  console.log(`  ${pc.dim("Archive ready:")} ${formatArchiveReady(readiness.archiveReady)}
+`);
+  console.log(`  ${pc.bold("Durable review:")}`);
+  console.log(`    ${pc.dim("Decision options:")} ${durableReview.decisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Candidate targets:")} ${durableReview.candidateTargets.join(", ")}`);
+  console.log(`    ${pc.dim(durableReview.note)}
+`);
+  return result;
+}
+function getReadyDurableReviewCandidateTargets() {
+  return getDurableReviewCandidateTargets({
+    projectRulesExists: existsSync14(join14(RSP_DIR, "rules", "project-rules.md"))
+  });
+}
+function formatArchiveReady(value) {
+  switch (value) {
+    case "yes":
+      return pc.green("yes");
+    case "no":
+      return pc.yellow("no");
+    case "judgment":
+      return pc.yellow("judgment");
+  }
+}
+
+// src/commands/show.ts
+import { existsSync as existsSync15 } from "fs";
+import { readFile as readFile12 } from "fs/promises";
+import { join as join15 } from "path";
+function exitShowError(error, options) {
+  const nextActions = error.code === "no_focused_change" ? ["Run: rsp status", "Run: rsp focus <name>", "Or run: rsp create <name>"] : [];
+  if (options.json) {
+    emitJson({
+      command: "show",
+      ok: false,
+      change: null,
+      contextPaths: [],
+      runtime: [],
+      nextActions,
+      error
+    });
+  } else {
+    console.error(`  ${pc.red("Error:")} ${error.message}`);
+    for (const action of nextActions)
+      console.error(`  ${pc.dim(action)}`);
+  }
+  process.exit(1);
+}
+async function showChange(nameOrFocused, options = {}) {
+  const runtime = [];
+  const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(options.verbose) && !options.json);
+  guardRspInitialized();
+  let name;
+  if (options.focused) {
+    const focused = await getFocusedChangeNames({ onError: reportRuntime });
+    if (focused.size === 0) {
+      exitShowError({ code: "no_focused_change", message: "no focused change exists" }, options);
+    }
+    if (focused.size > 1) {
+      exitShowError({
+        code: "multiple_focused_changes",
+        message: `multiple focused changes exist (${[...focused].join(", ")}). Specify a name or focus exactly one change.`
+      }, options);
+    }
+    name = [...focused][0];
+  } else if (nameOrFocused) {
+    if (!isValidChangeName(nameOrFocused)) {
+      exitShowError({
+        code: "invalid_change_name",
+        message: "change name must be kebab-case with optional subdirectory (lowercase, digits, hyphens, slashes)"
+      }, options);
+    }
+    name = nameOrFocused;
+  } else {
+    exitShowError({ code: "missing_change_name", message: "Usage: rsp show <name|--focused> [--json] [--verbose]" }, options);
+  }
+  const srcPath = join15(CHANGES_DIR, `${name}.md`);
+  if (!existsSync15(srcPath)) {
+    exitShowError({ code: "change_not_found", message: `.rsp/changes/${name}.md not found` }, options);
+  }
+  let content;
+  try {
+    content = await readFile12(srcPath, "utf-8");
+  } catch {
+    exitShowError({ code: "change_read_failed", message: `unable to read .rsp/changes/${name}.md` }, options);
+  }
+  let kind = "\u2014";
+  try {
+    const fm = parseFrontmatter(content);
+    kind = fm?.kind ? String(fm.kind) : "\u2014";
+  } catch (error) {
+    kind = "(invalid)";
+    reportRuntime({
+      code: "frontmatter_parse_failed",
+      operation: "parseFrontmatter",
+      path: srcPath,
+      message: toErrorMessage(error)
+    });
+  }
+  const focusedSet = await getFocusedChangeNames({ onError: reportRuntime });
+  const isFocused = focusedSet.has(name);
+  const cb = countCheckboxes(content);
+  const blockers = hasMeaningfulBlockers(content);
+  const scenarios = parseScenarios(content);
+  const readinessDetails = collectArchiveReadiness(content);
+  const readiness = {
+    incompleteTasks: readinessDetails.taskTodos.length,
+    incompleteVerify: readinessDetails.verifyTodos.length,
+    activeBlockers: readinessDetails.activeBlockers,
+    missingScenarios: readinessDetails.missingScenarios,
+    deterministic: readinessDetails.deterministic,
+    semantic: readinessDetails.semantic,
+    archiveReady: readinessDetails.archiveReady
+  };
+  const contextPaths = getDurableReviewCandidateTargets({
+    projectRulesExists: existsSync15(join15(RSP_DIR, "rules", "project-rules.md"))
+  });
+  const durableReview = buildDurableReviewGuidance(contextPaths);
+  const result = {
+    command: "show",
+    ok: true,
+    change: {
+      name,
+      path: normalizeLogicalPath(srcPath),
+      kind,
+      isFocused,
+      progress: { done: cb.done, total: cb.total },
+      blockers,
+      scenarioCount: scenarios.length,
+      readiness
+    },
+    contextPaths,
+    durableReview,
+    runtime
+  };
+  if (options.json) {
+    emitJson(result);
+    return result;
+  }
+  console.log();
+  console.log(`  ${pc.bold("Change:")} ${pc.cyan(name)}`);
+  console.log(`  ${pc.dim("Path:")} ${normalizeLogicalPath(srcPath)}`);
+  console.log(`  ${pc.dim("Kind:")} ${kind}`);
+  console.log(`  ${pc.dim("Focused:")} ${isFocused ? pc.green("yes") : pc.dim("no")}`);
+  console.log(`  ${pc.dim("Progress:")} ${cb.done}/${cb.total}`);
+  console.log(`  ${pc.dim("Blockers:")} ${blockers ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`  ${pc.dim("Scenarios:")} ${scenarios.length}`);
+  console.log();
+  console.log(`  ${pc.bold("Readiness:")}`);
+  console.log(`    ${pc.dim("Incomplete tasks:")} ${readiness.incompleteTasks > 0 ? pc.yellow(String(readiness.incompleteTasks)) : pc.green("0")}`);
+  console.log(`    ${pc.dim("Incomplete verify:")} ${readiness.incompleteVerify > 0 ? pc.yellow(String(readiness.incompleteVerify)) : pc.green("0")}`);
+  console.log(`    ${pc.dim("Active blockers:")} ${readiness.activeBlockers ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`    ${pc.dim("Missing scenarios:")} ${readiness.missingScenarios ? pc.yellow("yes") : pc.green("no")}`);
+  console.log(`    ${pc.dim("Deterministic:")} ${readiness.deterministic === "pass" ? pc.green("pass") : pc.yellow("warnings")}`);
+  console.log(`    ${pc.dim("Semantic review:")} ${pc.yellow("needed")}`);
+  console.log(`    ${pc.dim("Archive ready:")} ${formatArchiveReady2(readiness.archiveReady)}`);
+  console.log();
+  console.log(`  ${pc.bold("Context paths:")}`);
+  for (const cp of contextPaths)
+    console.log(`    ${pc.dim(cp)}`);
+  console.log();
+  console.log(`  ${pc.bold("Durable review:")}`);
+  console.log(`    ${pc.dim("Decision options:")} ${durableReview.decisions.join(" | ")}`);
+  console.log(`    ${pc.dim("Candidate targets:")} ${durableReview.candidateTargets.join(", ")}`);
+  console.log(`    ${pc.dim(durableReview.note)}`);
+  console.log();
+  return result;
+}
+function formatArchiveReady2(value) {
+  switch (value) {
+    case "yes":
+      return pc.green("yes");
+    case "no":
+      return pc.yellow("no");
+    case "judgment":
+      return pc.yellow("judgment");
+  }
+}
+
 // src/commands/status.ts
-import { existsSync as existsSync13 } from "fs";
-import { readFile as readFile10, stat } from "fs/promises";
-import { join as join13 } from "path";
+import { existsSync as existsSync16 } from "fs";
+import { readFile as readFile13, stat } from "fs/promises";
+import { join as join16 } from "path";
 var COL_CHANGE = 32;
 var COL_KIND = 10;
 var COL_AGE = 7;
@@ -1677,7 +2207,7 @@ async function showStatus(options = {}, runOptions = {}) {
   const runtime = [];
   const reportRuntime = (diagnostic) => recordRuntimeDiagnostic(runtime, diagnostic, Boolean(runOptions.verbose) && !runOptions.json);
   const focusedSet = await getFocusedChangeNames({ onError: reportRuntime });
-  const changeFiles = existsSync13(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
+  const changeFiles = existsSync16(CHANGES_DIR) ? await walkMarkdownFiles(CHANGES_DIR, { onError: reportRuntime }) : [];
   const changeMap = {};
   for (const fp of changeFiles)
     changeMap[changeNameFromPath(CHANGES_DIR, fp)] = fp;
@@ -1695,7 +2225,7 @@ async function showStatus(options = {}, runOptions = {}) {
     let total = 0;
     if (fp) {
       try {
-        const content = await readFile10(fp, "utf-8");
+        const content = await readFile13(fp, "utf-8");
         try {
           const fm = parseFrontmatter(content);
           kind = fm?.kind ? String(fm.kind) : "\u2014";
@@ -1737,7 +2267,7 @@ async function showStatus(options = {}, runOptions = {}) {
       reportRuntime({
         code: "focused_change_missing",
         operation: "resolveChange",
-        path: join13(CHANGES_DIR, `${name}.md`),
+        path: join16(CHANGES_DIR, `${name}.md`),
         message: "focus marker points to a missing change file"
       });
     }
@@ -1777,6 +2307,7 @@ async function showStatus(options = {}, runOptions = {}) {
     return true;
   });
   const blockedCount = filteredOutputRecords.filter((r) => r.isBlocked).length;
+  const nextActions = buildStatusNextActions(focusedSet.size, Object.keys(changeMap).sort(), Boolean(options.focused || options.blocked || typeof options.stale === "number"));
   const statusResult = {
     command: "status",
     ok: true,
@@ -1792,6 +2323,7 @@ async function showStatus(options = {}, runOptions = {}) {
       focused: filteredOutputRecords.filter((r) => r.isFocused).length,
       blocked: blockedCount
     },
+    nextActions,
     archiveTrend: await readArchiveTrend(runtime, runOptions),
     runtime
   };
@@ -1806,7 +2338,9 @@ async function showStatus(options = {}, runOptions = {}) {
     console.log(`  ${pc.cyan("Focused:")} ${[...focusedSet].join(", ")}`);
     console.log();
   } else {
-    console.log(`  ${pc.dim("No focused change.")} Run: rsp create <name> or rsp focus <name>`);
+    console.log(`  ${pc.dim("No focused change.")}`);
+    for (const action of nextActions)
+      console.log(`    ${pc.dim(action)}`);
     console.log();
   }
   if (allNames.length === 0) {
@@ -1843,12 +2377,32 @@ async function showStatus(options = {}, runOptions = {}) {
   }
   return statusResult;
 }
+function buildStatusNextActions(focusedCount, openChanges, filtered) {
+  if (focusedCount > 0)
+    return [];
+  if (openChanges.length === 0)
+    return ["Run: rsp create <name>"];
+  if (filtered) {
+    return [
+      "Run: rsp status",
+      "Run: rsp focus <name>",
+      "Or run: rsp create <name>"
+    ];
+  }
+  const firstChanges = openChanges.slice(0, 3).join(", ");
+  const extra = openChanges.length > 3 ? ` (+${openChanges.length - 3} more)` : "";
+  return [
+    `Open changes: ${firstChanges}${extra}`,
+    `Run: rsp focus ${openChanges[0]}`,
+    "Or run: rsp create <name>"
+  ];
+}
 async function readArchiveTrend(runtime, runOptions) {
-  const indexPath = join13(ARCHIVES_DIR, "INDEX.md");
-  if (!existsSync13(indexPath))
+  const indexPath = join16(ARCHIVES_DIR, "INDEX.md");
+  if (!existsSync16(indexPath))
     return [];
   try {
-    const content = await readFile10(indexPath, "utf-8");
+    const content = await readFile13(indexPath, "utf-8");
     const dateRe = /^\| (\d{4}-\d{2})-\d{2} \|/gm;
     const counts = {};
     let match;
@@ -1879,53 +2433,6 @@ function printArchiveTrend(trend) {
   console.log();
 }
 
-// src/commands/update.ts
-import { existsSync as existsSync14 } from "fs";
-import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
-import { join as join14 } from "path";
-var SKILL_REFRESH_HINT = "  Note: if you use the published RSP skill, refresh it too:\n    npx skills add oevery/rsp\n";
-async function updateProject() {
-  if (!existsSync14(RSP_DIR)) {
-    console.error(`  ${pc.red("Error:")} RSP is not initialized in this project`);
-    console.error(`  ${pc.dim("Run: rsp init")}`);
-    process.exit(1);
-  }
-  return withRspLock("update", async () => {
-    let updated = false;
-    const bundledRules = await readFile11(join14(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
-    const rulesPath = join14(RSP_DIR, "rules", "rsp-rules.md");
-    await mkdir8(join14(RSP_DIR, "rules"), { recursive: true });
-    const existingRules = existsSync14(rulesPath) ? await readFile11(rulesPath, "utf-8") : null;
-    if (existingRules !== bundledRules) {
-      await writeFile9(rulesPath, bundledRules);
-      console.log(`  ${pc.green("\u2713")} rules/rsp-rules.md updated`);
-      updated = true;
-    }
-    const agentsPath = "AGENTS.md";
-    const projectName = await detectProjectName();
-    const baseAgents = existsSync14(agentsPath) ? await readFile11(agentsPath, "utf-8") : `# ${projectName}
-
-`;
-    const nextAgents = upsertRspAgentsBlock(baseAgents);
-    if (!existsSync14(agentsPath) || nextAgents.changed) {
-      await writeFile9(agentsPath, nextAgents.content);
-      console.log(`  ${pc.green("\u2713")} AGENTS.md managed block refreshed`);
-      updated = true;
-    }
-    await buildSpecsIndex({ acquireLock: false });
-    await buildArchiveIndex({ acquireLock: false });
-    if (!updated) {
-      console.log(`  ${pc.dim("Already up to date.")}
-`);
-      console.log(SKILL_REFRESH_HINT);
-    } else {
-      console.log(`  ${pc.green("Update complete.")}
-`);
-      console.log(SKILL_REFRESH_HINT);
-    }
-  });
-}
-
 // src/cli.ts
 var initCommand = defineCommand({
   meta: {
@@ -1971,11 +2478,16 @@ var createCommand = defineCommand({
     kind: {
       type: "string",
       description: "Optional kind for a kind-aware template (feature, fix, refactor, docs, ops, research)"
+    },
+    lite: {
+      type: "boolean",
+      description: "Use a shorter change template while keeping the required RSP sections",
+      default: false
     }
   },
   async run({ args }) {
     const summary = Array.isArray(args._) && args._.length > 1 ? args._.slice(1).join(" ") : "";
-    await createChange(args.name, summary, args.kind);
+    await createChange(args.name, summary, args.kind, { lite: Boolean(args.lite) });
   }
 });
 var addRulesCommand = defineCommand({
@@ -2026,14 +2538,19 @@ var archiveCommand = defineCommand({
     description: "Archive an open change into .rsp/archives/"
   },
   args: {
-    name: {
+    "name": {
       type: "positional",
       description: "Change name",
       required: true
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Preview archive readiness without moving the change",
+      default: false
     }
   },
   async run({ args }) {
-    await archiveChange(args.name);
+    await archiveChange(args.name, { dryRun: Boolean(args["dry-run"]) });
   }
 });
 var focusCommand = defineCommand({
@@ -2128,9 +2645,14 @@ var statusCommand = defineCommand({
 var checkCommand = defineCommand({
   meta: {
     name: "check",
-    description: "Validate changes (frontmatter, sections, deltas, scenarios)"
+    description: "Validate changes (frontmatter, sections, template text, deltas, scenarios)"
   },
   args: {
+    focused: {
+      type: "boolean",
+      description: "Only validate currently focused changes",
+      default: false
+    },
     json: {
       type: "boolean",
       description: "Print machine-readable JSON output",
@@ -2143,7 +2665,11 @@ var checkCommand = defineCommand({
     }
   },
   async run({ args }) {
-    const result = await runCheck({ json: Boolean(args.json), verbose: Boolean(args.verbose) });
+    const result = await runCheck({
+      focused: Boolean(args.focused),
+      json: Boolean(args.json),
+      verbose: Boolean(args.verbose)
+    });
     if (!result.ok)
       process.exit(1);
   }
@@ -2172,14 +2698,80 @@ var doctorCommand = defineCommand({
       type: "boolean",
       description: "Print runtime diagnostics for suppressed I/O issues",
       default: false
+    },
+    fix: {
+      type: "boolean",
+      description: "Run safe deterministic repairs before reporting diagnostics",
+      default: false
     }
   },
   async run({ args }) {
-    const result = await runDoctor({ json: Boolean(args.json), verbose: Boolean(args.verbose) });
+    const result = await runDoctor({ json: Boolean(args.json), verbose: Boolean(args.verbose), fix: Boolean(args.fix) });
     if (!result.ok)
       process.exit(1);
   }
 });
+var readyCommand = defineCommand({
+  meta: {
+    name: "ready",
+    description: "Preview archive readiness for a change without moving it"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Change name",
+      required: true
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON output",
+      default: false
+    },
+    verbose: {
+      type: "boolean",
+      description: "Print runtime diagnostics for suppressed I/O issues",
+      default: false
+    }
+  },
+  async run({ args }) {
+    await showReady(args.name, { json: Boolean(args.json), verbose: Boolean(args.verbose) });
+  }
+});
+var showCommand = defineCommand({
+  meta: {
+    name: "show",
+    description: "Show change context with readiness signals and relevant paths"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Change name (use --focused instead to show the currently focused change)",
+      required: false
+    },
+    focused: {
+      type: "boolean",
+      description: "Show the currently focused change",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON output",
+      default: false
+    },
+    verbose: {
+      type: "boolean",
+      description: "Print runtime diagnostics for suppressed I/O issues",
+      default: false
+    }
+  },
+  async run({ args }) {
+    await showChange(args.name, {
+      focused: Boolean(args.focused),
+      json: Boolean(args.json),
+      verbose: Boolean(args.verbose)
+    });
+  }
+});
 async function runCli(rawArgs = process.argv.slice(2)) {
   const version = await getVersion();
   const main = defineCommand({
@@ -2195,6 +2787,8 @@ async function runCli(rawArgs = process.argv.slice(2)) {
       focus: focusCommand,
       unfocus: unfocusCommand,
       archive: archiveCommand,
+      ready: readyCommand,
+      show: showCommand,
       status: statusCommand,
       check: checkCommand,
       update: updateCommand,