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

package/dist/chunk-OTJFL6XH.mjs

@@ -0,0 +1,1022 @@
+#!/usr/bin/env node
+
+// src/core/config.ts
+import { readFile as readFile2 } from "fs/promises";
+import { dirname as dirname3, join as join4 } from "path";
+import { fileURLToPath } from "url";
+import pc from "picocolors";
+
+// src/core/decisions.ts
+import { existsSync } from "fs";
+import { mkdir, readdir as readdir2, realpath, stat } from "fs/promises";
+import { dirname, isAbsolute, join as join2, posix, relative, resolve, sep } from "path";
+
+// src/core/managed-path.ts
+import { lstatSync } from "fs";
+import { readdir, writeFile } from "fs/promises";
+import { join } from "path";
+var ManagedPathError = class extends Error {
+  constructor(path, message) {
+    super(message);
+    this.path = path;
+    this.name = "ManagedPathError";
+  }
+  path;
+};
+function inspectManagedDirectory(path, label, options = {}) {
+  try {
+    const stats = lstatSync(path);
+    if (stats.isDirectory())
+      return { exists: true, issue: null };
+    return {
+      exists: true,
+      issue: new ManagedPathError(path, `${label} must be a real directory: ${path}`)
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (options.allowMissing)
+        return { exists: false, issue: null };
+      return {
+        exists: false,
+        issue: new ManagedPathError(path, `${label} must be a real directory: ${path}`)
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exists: false,
+      issue: new ManagedPathError(path, `unable to inspect ${label} ${path}: ${message}`)
+    };
+  }
+}
+function requireManagedDirectory(path, label, options = {}) {
+  const inspection = inspectManagedDirectory(path, label, options);
+  if (inspection.issue)
+    throw inspection.issue;
+  return inspection.exists;
+}
+function inspectManagedFile(path, label, options = {}) {
+  try {
+    const stats = lstatSync(path);
+    if (stats.isFile())
+      return { exists: true, issue: null };
+    return {
+      exists: true,
+      issue: new ManagedPathError(path, `${label} must be a regular file: ${path}`)
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (options.allowMissing)
+        return { exists: false, issue: null };
+      return {
+        exists: false,
+        issue: new ManagedPathError(path, `${label} must be a regular file: ${path}`)
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exists: false,
+      issue: new ManagedPathError(path, `unable to inspect ${label} ${path}: ${message}`)
+    };
+  }
+}
+function requireManagedFile(path, label, options = {}) {
+  const inspection = inspectManagedFile(path, label, options);
+  if (inspection.issue)
+    throw inspection.issue;
+  return inspection.exists;
+}
+async function ensureManagedFile(path, content, label) {
+  if (requireManagedFile(path, label, { allowMissing: true }))
+    return false;
+  await writeFile(path, content, { flag: "wx" });
+  return true;
+}
+async function writeManagedFile(path, content, label) {
+  const exists = requireManagedFile(path, label, { allowMissing: true });
+  if (exists)
+    await writeFile(path, content);
+  else
+    await writeFile(path, content, { flag: "wx" });
+}
+function resolveManagedDirectoryChain(root, segments, label) {
+  requireManagedDirectory(root, `${label} root`);
+  let current = root;
+  for (const segment of segments) {
+    if (!segment || segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\"))
+      throw new ManagedPathError(current, `${label} contains an invalid directory segment: ${segment}`);
+    current = join(current, segment);
+    requireManagedDirectory(current, label, { allowMissing: true });
+  }
+  return current;
+}
+async function inspectManagedFileTree(root, label, options = {}) {
+  const result = { rootExists: false, files: [], issues: [] };
+  const rootInspection = inspectManagedDirectory(root, `${label} root`, options);
+  if (rootInspection.issue) {
+    result.issues.push(rootInspection.issue);
+    return result;
+  }
+  if (!rootInspection.exists)
+    return result;
+  result.rootExists = true;
+  await collectManagedFiles(root, label, result);
+  result.files.sort();
+  return result;
+}
+async function collectManagedFiles(directory, label, result) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    result.issues.push(new ManagedPathError(directory, `unable to inspect the ${label} tree at ${directory}: ${message}`));
+    return;
+  }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith("."))
+      continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await collectManagedFiles(path, label, result);
+      continue;
+    }
+    if (entry.isFile()) {
+      result.files.push(path);
+      continue;
+    }
+    result.issues.push(new ManagedPathError(path, `unsupported entry in the ${label} tree: ${path}`));
+  }
+}
+
+// src/core/decisions.ts
+var DEFAULT_DECISION_RECORDS_PATH = ".rsp/specs/decisions";
+function normalizeDecisionRecordsPath(pathValue) {
+  return posix.normalize(pathValue.trim().replace(/\\/g, "/")).replace(/^\.\//, "").replace(/\/$/, "");
+}
+function validateDecisionRecordsPath(pathValue) {
+  if (typeof pathValue !== "string" || pathValue.trim() === "")
+    return 'config.yaml field "decisions.path" must be a non-empty string';
+  const raw = pathValue.trim();
+  const portable = raw.replace(/\\/g, "/");
+  if (isAbsolute(raw) || posix.isAbsolute(portable) || /^[a-z]:[\\/]/i.test(raw))
+    return 'config.yaml field "decisions.path" must be project-relative';
+  const normalized = normalizeDecisionRecordsPath(raw);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../"))
+    return 'config.yaml field "decisions.path" must stay inside the Host Project';
+  if ((normalized === ".rsp" || normalized.startsWith(".rsp/")) && normalized !== DEFAULT_DECISION_RECORDS_PATH)
+    return `config.yaml field "decisions.path" must use ${DEFAULT_DECISION_RECORDS_PATH} or a path outside .rsp/`;
+  return null;
+}
+function getDecisionRecordsConfigIssue(config) {
+  if (!("decisions" in config))
+    return null;
+  const decisions = config.decisions;
+  if (!decisions || typeof decisions !== "object" || Array.isArray(decisions))
+    return 'config.yaml field "decisions" must be a mapping with one path';
+  const keys = Object.keys(decisions);
+  if (keys.length !== 1 || keys[0] !== "path")
+    return 'config.yaml field "decisions" supports only "path"';
+  return validateDecisionRecordsPath(decisions.path);
+}
+function resolveDecisionRecordsPath(config) {
+  const configured = config.decisions?.path;
+  return configured && validateDecisionRecordsPath(configured) === null ? normalizeDecisionRecordsPath(configured) : DEFAULT_DECISION_RECORDS_PATH;
+}
+async function ensureDecisionRecordsDirectory(pathValue) {
+  const filesystemError = await validateDecisionRecordsFilesystemPath(pathValue);
+  if (filesystemError)
+    throw new Error(filesystemError);
+  const existed = existsSync(pathValue);
+  await mkdir(pathValue, { recursive: true });
+  const entries = await readdir2(pathValue);
+  if (entries.length === 0) {
+    await ensureManagedFile(join2(pathValue, ".gitkeep"), "", "Decision Record placeholder");
+    return true;
+  }
+  if (entries.includes(".gitkeep"))
+    requireManagedFile(join2(pathValue, ".gitkeep"), "Decision Record placeholder");
+  return !existed;
+}
+async function validateDecisionRecordsFilesystemPath(pathValue) {
+  const projectRoot = await realpath(".");
+  let existingAncestor = resolve(pathValue);
+  while (!existsSync(existingAncestor)) {
+    const parent = dirname(existingAncestor);
+    if (parent === existingAncestor)
+      return `Decision Record path "${pathValue}" has no accessible Host Project ancestor`;
+    existingAncestor = parent;
+  }
+  const resolvedAncestor = await realpath(existingAncestor);
+  const rel = relative(projectRoot, resolvedAncestor);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+    return `Decision Record path "${pathValue}" resolves outside the Host Project through ${existingAncestor}`;
+  if (existsSync(resolve(pathValue)) && !(await stat(resolve(pathValue))).isDirectory())
+    return `Decision Record path "${pathValue}" must be a directory`;
+  return null;
+}
+
+// src/core/helpers.ts
+import { existsSync as existsSync2 } from "fs";
+import { readdir as readdir3, readFile, rmdir } from "fs/promises";
+import { basename, dirname as dirname2, join as join3, relative as relative2, sep as sep2 } from "path";
+import { parse } from "yaml";
+var RSP_AGENTS_BEGIN = "<!-- rsp:begin -->";
+var RSP_AGENTS_END = "<!-- rsp:end -->";
+function parseYamlText(text) {
+  const parsed = parse(text);
+  if (parsed === null || parsed === void 0)
+    return {};
+  if (typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("YAML document must be a mapping/object");
+  return parsed;
+}
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\r?\n/);
+  if (!m)
+    return null;
+  return parseYamlText(m[1]);
+}
+function countCheckboxes(content) {
+  const todo = (content.match(/\[ \]/g) || []).length;
+  const progress = (content.match(/\[\/\]/g) || []).length;
+  const done = (content.match(/\[x\]/g) || []).length;
+  const dropped = (content.match(/\[-\]/g) || []).length;
+  return { todo, progress, done, dropped, total: todo + progress + done + dropped };
+}
+async function walkMarkdownFiles(dir, options = {}) {
+  const all = await walkFiles(dir, options);
+  return all.filter((f) => f.endsWith(".md"));
+}
+async function inspectUnsupportedRules() {
+  const rulesDir = join3(RSP_DIR, "rules");
+  const diagnostics = [];
+  const rawEntries = await walkAllEntries(rulesDir, diagnostics);
+  const entries = rawEntries.filter((entry) => entry.path !== OBSOLETE_RSP_RULES_PATH).map((entry) => ({
+    path: normalizeLogicalPath(relative2(rulesDir, entry.path)),
+    kind: entry.kind
+  }));
+  const obsoleteFallbackPresent = existsSync2(OBSOLETE_RSP_RULES_PATH);
+  return {
+    entries,
+    diagnostics,
+    directoryRemaining: existsSync2(rulesDir) && (!obsoleteFallbackPresent || entries.length > 0)
+  };
+}
+async function walkAllEntries(dir, diagnostics) {
+  const entries = [];
+  try {
+    const items = await readdir3(dir, { withFileTypes: true });
+    for (const item of items) {
+      const path = join3(dir, item.name);
+      const kind = item.isDirectory() ? "directory" : "file";
+      entries.push({ path, kind });
+      if (kind === "directory")
+        entries.push(...await walkAllEntries(path, diagnostics));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      diagnostics.push({
+        code: "walk_failed",
+        operation: "readdir",
+        path: dir,
+        message: toErrorMessage(error)
+      });
+    }
+  }
+  return entries;
+}
+async function walkFiles(dir, options = {}) {
+  const files = [];
+  try {
+    const items = await readdir3(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (item.name.startsWith("."))
+        continue;
+      const filePath = join3(dir, item.name);
+      if (item.isDirectory())
+        files.push(...await walkFiles(filePath, options));
+      else
+        files.push(filePath);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      options.onError?.({
+        code: "walk_failed",
+        operation: "readdir",
+        path: dir,
+        message: toErrorMessage(error)
+      });
+    }
+  }
+  return files;
+}
+function normalizeLogicalPath(pathValue) {
+  return pathValue.split(sep2).join("/").replace(/\\/g, "/");
+}
+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 `---
+kind: ops
+---
+
+# Change: project-setup
+
+## Proposal
+- Outcome: ${proposalSummary}
+- Why:
+  - Establish a durable project model before normal implementation work starts
+- Scope:
+  - Review the repository structure, entrypoints, and primary outputs
+  - Fill .rsp/specs/design.md with durable architecture facts
+  - Add stable navigation, context, instructions, or validation steps to project-owned CONTEXT.md or the nearest AGENTS.md when those conventions exist
+- Non-goals:
+  - Do not duplicate durable project facts across this change, specs, and AGENTS.md
+
+## Spec
+### ADDED
+- Requirement: project bootstrap capture
+  - The repository's purpose, scope, and structure are reflected in .rsp/specs/design.md
+
+### MODIFIED
+- Requirement: stable project-owned context and instructions
+  - Stable navigation and context are reflected in project-owned CONTEXT.md when that convention exists
+  - Stable agent instructions are reflected in the nearest project-owned AGENTS.md when needed
+
+### Acceptance
+#### Scenario: project model captured
+- GIVEN an initialized RSP project
+- WHEN project setup is completed
+- THEN .rsp/specs/design.md reflects durable project facts
+- AND project-owned CONTEXT.md and the nearest AGENTS.md contain only the stable context and instructions assigned to them by Host Project conventions
+
+## Design
+- Approach:
+  - Keep bootstrap work in this single Change while returning durable outcomes to their existing project owners
+- Boundaries:
+  - Specs own stable current facts; project-owned CONTEXT.md and AGENTS.md retain their navigation, context, and instruction roles
+- Affected areas:
+  - .rsp/specs/design.md
+  - Project-owned CONTEXT.md or AGENTS.md when applicable
+- Durable outcome targets:
+  - Current facts: .rsp/specs/design.md, existing scoped Specs, CONTEXT.md, or AGENTS.md as applicable
+  - Lasting rationale: one Decision Record under the configured authoritative path, only when a hard-to-reverse tradeoff exists
+- Constraints:
+  - Keep the setup lightweight and avoid duplicating durable project facts
+
+## Tasks
+- [ ] Review the repository structure, entrypoints, and primary outputs
+- [ ] Review project-owned CONTEXT.md and AGENTS.md and confirm the RSP entry points to the right project files
+- [ ] Fill .rsp/specs/design.md with durable architecture facts
+- [ ] Add stable project-owned context, instructions, or validation steps only where the Host Project convention requires them
+
+## Verify
+- Automated:
+  - [ ] Run rsp doctor \u2014 proves: the initialized RSP workspace is structurally valid
+- Manual or environment:
+  - [ ] Review .rsp/specs/design.md and project-owned context or instructions and confirm they match the repository
+- Coverage:
+  - none
+
+## Blockers
+- none
+`;
+  }
+  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}"
+---
+
+# Change: ${name}
+
+## Proposal
+- Outcome: ${proposalSummary}
+- Why:
+  - ${template.why}
+- Scope:
+  - ${template.scope}
+- Non-goals:
+  - ${template.nonGoals}
+
+## Spec
+${template.specSection}
+
+### Acceptance
+${template.acceptanceSection}
+
+## Design
+- Approach:
+  - ${template.approach}
+- Boundaries:
+  - <module, interface, data, document, or ownership boundary affected>
+- Affected areas:
+  - ${template.affectedArea1}
+  - ${template.affectedArea2}
+- Constraints:
+  - ${template.constraints}
+
+## Tasks
+- [ ] ${template.task}
+
+## Verify
+- Automated:
+  - [ ] ${template.automatedVerify} \u2014 proves: <behavior or scope covered>
+- Manual or environment:
+  - [ ] ${template.manualVerify}
+- Coverage:
+  - <omitted or unavailable relevant coverage and reason, or none>
+
+## Blockers
+- none
+`;
+}
+function generateLiteChangeContent(name, proposalSummary, frontmatterKind) {
+  return `---
+kind: "${frontmatterKind}"
+---
+
+# Change: ${name}
+
+## Proposal
+- Outcome: ${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>
+- Boundaries:
+  - <primary ownership or interface boundary>
+- Affected areas:
+  - <primary file, directory, or doc path>
+- Constraints:
+  - <important constraint, or none>
+
+## Tasks
+- [ ] Implement the small change
+
+## Verify
+- Automated:
+  - [ ] <cheapest decisive check; retain a new test only when justified, or not applicable: reason> \u2014 proves: <behavior or scope covered>
+- Manual or environment:
+  - [ ] <exact acceptance scenario, or unavailable/not applicable: owner and reason>
+- Coverage:
+  - <omitted or unavailable relevant coverage and reason, or none>
+
+## Blockers
+- none
+`;
+}
+function getChangeTemplateByKind(kind) {
+  const automatedVerify = "<cheapest decisive check; retain a new test only when justified, or not applicable: reason>";
+  switch (kind) {
+    case "feature":
+      return {
+        why: "<what user need or capability gap this addresses>",
+        scope: "<what new behavior or capability will be delivered>",
+        nonGoals: "<what related capabilities are explicitly out of scope>",
+        specSection: "<!-- 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>",
+        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
+        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
+        task: "<implement the new behavior and its acceptance scenario in the affected areas>",
+        automatedVerify,
+        manualVerify: "<exact end-to-end user scenario to validate the new capability, or unavailable/not applicable: owner and reason>"
+      };
+    case "fix":
+      return {
+        why: "<what current behavior is wrong or broken>",
+        scope: "<what specific defect is being corrected>",
+        nonGoals: "<what related but separate issues are out of scope>",
+        specSection: "<!-- 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: "<confirmed cause and correction strategy, or exact evidence needed to establish the cause>",
+        affectedArea1: "<concrete file path, directory, module, or subsystem containing the defect>",
+        affectedArea2: "<secondary path, dependency, or test file if needed>",
+        constraints: "<regression, backward-compatibility, safety, or scope constraint that must hold>",
+        task: "<identify the root cause and apply the minimal fix>",
+        automatedVerify,
+        manualVerify: "<exact steps to reproduce the original issue and confirm it no longer occurs, or unavailable/not applicable: owner and reason>"
+      };
+    case "refactor":
+      return {
+        why: "<what maintainability, readability, or structural issue motivates this>",
+        scope: "<what code areas are being restructured>",
+        nonGoals: "<no behavior change is expected or intended>",
+        specSection: "<!-- 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>",
+        affectedArea2: "<secondary path, dependency, or test file if needed>",
+        constraints: "<observable behavior must remain unchanged; compatibility, performance, and safety constraints must still hold>",
+        task: "<restructure the code while keeping behavior identical>",
+        automatedVerify,
+        manualVerify: "<exact scenario to spot-check that behavior is unchanged after the refactor, or unavailable/not applicable: owner and reason>"
+      };
+    case "docs":
+      return {
+        why: "<why the documentation change matters>",
+        scope: "<which docs, readers, or workflows will be updated>",
+        nonGoals: "<what documentation behavior or audience is out of scope>",
+        specSection: "<!-- 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>",
+        affectedArea2: "<secondary doc path or reference file if needed>",
+        constraints: "<durable wording, consistency, scope, or audience constraint that must hold>",
+        task: "<update the target documentation and supporting references>",
+        automatedVerify,
+        manualVerify: "<exact reader or operator scenario to confirm the updated guidance is accurate, or unavailable/not applicable: owner and reason>"
+      };
+    case "research":
+      return {
+        why: "<what question or uncertainty this research resolves>",
+        scope: "<what system area, option set, or hypothesis is being examined>",
+        nonGoals: "<what implementation work is explicitly out of scope>",
+        specSection: "<!-- 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>",
+        affectedArea2: "<secondary path, dependency, environment, or evidence source if needed>",
+        constraints: "<time, evidence, safety, or scope constraint for the investigation>",
+        task: "<gather evidence, record the recommendation or finding, and note any follow-up implementation work if needed>",
+        automatedVerify,
+        manualVerify: "<exact review of the findings to confirm they answer the original question and identify follow-up work if needed, or unavailable/not applicable: owner and reason>"
+      };
+    case "ops":
+      return {
+        why: "<why this operational or environment change matters>",
+        scope: "<what environment, workflow, or operational path changes>",
+        nonGoals: "<what product or feature behavior will not change>",
+        specSection: "<!-- 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>",
+        affectedArea2: "<secondary script, config path, dependency, or environment surface if needed>",
+        constraints: "<rollback, safety, reliability, environment, or scope constraint that must hold>",
+        task: "<apply and verify the operational change>",
+        automatedVerify,
+        manualVerify: "<exact operator workflow or environment scenario to confirm the operational result, or unavailable/not applicable: owner and reason>"
+      };
+    default:
+      return {
+        why: "<why this change matters>",
+        scope: "<what this change will do>",
+        nonGoals: "<what this change will not do>",
+        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>",
+        affectedArea2: "<concrete file path, directory, module, or subsystem 2 if needed>",
+        constraints: "<behavior, compatibility, performance, safety, or scope constraint that must hold>",
+        task: "<implement the core change in the affected areas>",
+        automatedVerify,
+        manualVerify: "<exact acceptance scenario, or unavailable/not applicable: owner and reason>"
+      };
+  }
+}
+function renderRspAgentsBlock() {
+  return `${RSP_AGENTS_BEGIN}
+## RSP Entry
+
+RSP tracks current work, stable specs, and archives under \`.rsp/\`.
+
+Read in order:
+1. Nearest \`AGENTS.md\` for project or module instructions.
+2. Root \`CONTEXT-MAP.md\` if present, then the relevant nearest \`CONTEXT.md\`.
+3. The \`rsp\` skill; if unavailable, read \`.rsp/rsp-rules.md\` as the fallback protocol.
+4. \`.rsp/focus.d/\`; for grouped work read the sibling Group Brief, then the explicitly selected focused Change.
+5. Only the relevant Specs and Decision Records under the configured authoritative path.
+
+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.
+Do not treat \`.rsp/specs/\` or \`.rsp/changes/\` as replacements for nearest \`AGENTS.md\` or \`CONTEXT.md\`.
+${RSP_AGENTS_END}`;
+}
+function upsertRspAgentsBlock(content) {
+  const block = renderRspAgentsBlock();
+  const managedRe = /<!-- rsp:begin -->[\s\S]*?<!-- rsp:end -->/;
+  if (managedRe.test(content)) {
+    const next2 = content.replace(managedRe, block);
+    return { content: next2, changed: next2 !== content };
+  }
+  const trimmed = content.trimStart();
+  const next = trimmed ? `${block}
+
+${trimmed}` : `${block}
+`;
+  return { content: next, changed: true };
+}
+function hasRspAgentsBlock(content) {
+  return content.includes(RSP_AGENTS_BEGIN) && content.includes(RSP_AGENTS_END);
+}
+var SPEC_NAME_RE = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+function isValidSpecName(name) {
+  return SPEC_NAME_RE.test(name);
+}
+function guardRspInitialized() {
+  const designPath = join3(RSP_DIR, "specs", "design.md");
+  const rules = inspectManagedFile(RSP_RULES_PATH, "fallback protocol", { allowMissing: true });
+  const design = inspectManagedFile(designPath, "design Spec", { allowMissing: true });
+  if (rules.issue || design.issue || !rules.exists || !design.exists) {
+    const initialized = existsSync2(RSP_DIR);
+    console.error(`  ${pc.red("Error:")} ${initialized ? "RSP project requires an update" : "RSP is not initialized in this project"}`);
+    console.error(`  ${pc.dim(initialized ? "Run: rsp update" : "Run: rsp init")}`);
+    process.exit(1);
+  }
+}
+function getOpenCheckboxes(sectionText) {
+  return sectionText.split("\n").map((line) => line.trim()).filter((line) => /^- \[[ /]\]/.test(line));
+}
+async function cleanupEmptyParentDirs(path, stopDir) {
+  let parent = dirname2(path);
+  while (parent !== stopDir) {
+    try {
+      const remaining = await readdir3(parent);
+      if (remaining.length === 0)
+        await rmdir(parent);
+      else
+        break;
+    } catch {
+      break;
+    }
+    parent = dirname2(parent);
+  }
+}
+async function detectProjectName() {
+  try {
+    if (existsSync2("package.json")) {
+      const raw = await readFile("package.json", "utf-8");
+      const pkg = JSON.parse(raw);
+      if (pkg.name && pkg.name !== "")
+        return pkg.name;
+    }
+  } catch {
+  }
+  return basename(process.cwd());
+}
+function generateDesignContent(projectName) {
+  return `# Project Design: ${projectName}
+
+## Purpose
+- <what this project is responsible for>
+- <who or what it serves>
+
+## Stable Facts
+- <durable fact that future agents or developers must know>
+- <key architectural invariant>
+
+## Boundaries
+- In scope:
+  - <major capability or boundary>
+- Out of scope:
+  - <intentional non-goal>
+
+## Structure
+- <important directory or subsystem> \u2014 <responsibility>
+
+## Constraints
+- <cross-cutting technical or operational constraint, when it affects architecture>
+`;
+}
+function generateSpecContent(name) {
+  const title = toTitleCase(name);
+  return `# ${title}
+
+## Purpose
+- <why this project-level spec exists>
+
+## Stable Facts
+- <durable fact that future work must know>
+
+## Boundaries
+- In scope:
+  - <what this spec covers>
+- Out of scope:
+  - <what this spec does not cover>
+
+## Constraints
+- <stable constraint, if any>
+`;
+}
+function toTitleCase(value) {
+  return value.split(/[-/]/g).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function extractSection(content, heading) {
+  const lines = content.split("\n");
+  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
+  if (start === -1)
+    return "";
+  const body = [];
+  for (let index = start + 1; index < lines.length; index++) {
+    const line = lines[index];
+    if (line.startsWith("## "))
+      break;
+    body.push(line);
+  }
+  return body.join("\n").trim();
+}
+function extractBlockerLines(content) {
+  const uncommented = content.replace(/<!--[\s\S]*?-->/g, "");
+  return extractSection(uncommented, "Blockers").split("\n").map((line) => line.trim()).filter(Boolean);
+}
+function hasMeaningfulBlockers(content) {
+  const lines = extractBlockerLines(content);
+  if (lines.length === 0)
+    return false;
+  return lines.some((line) => !/^[-*]\s*(?:none)?$/i.test(line) && !/^none$/i.test(line));
+}
+function detectDeltaSections(content) {
+  const body = extractSection(content, "Spec");
+  return {
+    added: /^###\s*ADDED/im.test(body),
+    modified: /^###\s*MODIFIED/im.test(body),
+    removed: /^###\s*REMOVED/im.test(body)
+  };
+}
+function collectArchiveReadiness(content, options = {}) {
+  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 = options.activeBlockers ?? hasMeaningfulBlockers(content);
+  if (activeBlockers)
+    warnings.push("active blockers are present in the change file");
+  const scenarios = parseScenarios(content);
+  const missingScenarios = scenarios.length === 0;
+  if (missingScenarios)
+    warnings.push("no Scenario blocks found (some changes do not need them)");
+  const archiveReady = 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(factCandidateTargets, decisionRecordsPath) {
+  return {
+    required: true,
+    factDecisions: [
+      "No current-fact update needed",
+      "Update existing spec or scoped instruction",
+      "Create a new durable spec"
+    ],
+    rationaleDecisions: [
+      "No Decision Record needed",
+      "Create or update a Decision Record"
+    ],
+    factCandidateTargets,
+    decisionRecordsPath,
+    note: "Semantic review decides current-fact and lasting-rationale updates independently. The CLI never infers scoped instruction or Decision Record filenames and never promotes Change content automatically."
+  };
+}
+function getDurableReviewCandidateTargets() {
+  return [".rsp/specs/design.md"];
+}
+function collectArchiveChecklist(content, options = {}) {
+  return collectArchiveReadiness(content, options).warnings;
+}
+function parseScenarios(content) {
+  const scenarios = [];
+  const regex = /^#{3,4}\s*Scenario:\s*(.+)$/gim;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const heading = match[1].trim();
+    const startPos = match.index + match[0].length;
+    const restContent = content.slice(startPos);
+    const nextSection = restContent.match(/^#{3,4}\s/m);
+    const block = nextSection ? restContent.slice(0, nextSection.index) : restContent;
+    const steps = block.split("\n").map((s) => s.trim()).filter((s) => s.startsWith("-") && /GIVEN|WHEN|THEN|AND|BUT/i.test(s)).map((s) => s.replace(/^[-*]\s*/, ""));
+    if (steps.length > 0)
+      scenarios.push({ heading, steps });
+  }
+  return scenarios;
+}
+
+// src/core/config.ts
+var __dirname = dirname3(fileURLToPath(import.meta.url));
+var PKG_ROOT = join4(__dirname, "..");
+var RSP_DIR = ".rsp";
+var RSP_RULES_PATH = join4(RSP_DIR, "rsp-rules.md");
+var OBSOLETE_RSP_RULES_PATH = join4(RSP_DIR, "rules", "rsp-rules.md");
+var CHANGES_DIR = join4(RSP_DIR, "changes");
+var FOCUS_DIR = join4(RSP_DIR, "focus.d");
+var ARCHIVES_DIR = join4(RSP_DIR, "archives");
+var LOCK_PATH = join4(RSP_DIR, ".lock");
+var CONFIG_PATH = join4(RSP_DIR, "config.yaml");
+var VALID_KINDS = ["feature", "fix", "refactor", "docs", "ops", "research"];
+var DEFAULT_REQUIRED_SECTIONS = ["Proposal", "Spec", "Design", "Tasks", "Verify", "Blockers"];
+var DEFAULT_MANAGE_POLICY = { activation: "explicit", closeout: "local" };
+var FAILED_CLOSED_MANAGE_POLICY = { activation: "explicit", closeout: "manual" };
+var MANAGE_ACTIVATIONS = ["explicit", "auto"];
+var MANAGE_CLOSEOUTS = ["manual", "lifecycle", "local"];
+var _configCache = null;
+async function loadRspConfig() {
+  const inspection = await inspectRspConfig();
+  if (inspection.issues.length > 0)
+    throw new Error(inspection.issues.join("; "));
+  return inspection.config;
+}
+async function inspectRspConfig() {
+  const cwd = process.cwd();
+  if (_configCache?.cwd === cwd)
+    return _configCache.inspection;
+  const configFile = inspectManagedFile(CONFIG_PATH, "config file", { allowMissing: true });
+  if (configFile.issue)
+    throw configFile.issue;
+  if (!configFile.exists) {
+    const inspection2 = { config: {}, issues: [] };
+    _configCache = { cwd, inspection: inspection2 };
+    return inspection2;
+  }
+  const raw = await readFile2(CONFIG_PATH, "utf-8");
+  const parsed = parseYamlText(raw);
+  const issues = validateRspConfig(parsed);
+  const decisions = parsed.decisions && typeof parsed.decisions === "object" && !Array.isArray(parsed.decisions) ? parsed.decisions : void 0;
+  const decisionPath = decisions?.path;
+  const manageValue = parsed.manage && typeof parsed.manage === "object" && !Array.isArray(parsed.manage) ? parsed.manage : void 0;
+  const activation = MANAGE_ACTIVATIONS.includes(manageValue?.activation) ? manageValue?.activation : void 0;
+  const closeout = MANAGE_CLOSEOUTS.includes(manageValue?.closeout) ? manageValue?.closeout : void 0;
+  const kinds = Array.isArray(parsed.kinds) && parsed.kinds.every((value) => typeof value === "string" && value.trim() !== "") ? parsed.kinds.map((value) => value.trim()) : void 0;
+  const decisionRecordsIssue = getDecisionRecordsConfigIssue(parsed);
+  const inspection = {
+    config: {
+      kinds,
+      decisions: decisionRecordsIssue === null && validateDecisionRecordsPath(decisionPath) === null ? { path: normalizeDecisionRecordsPath(String(decisionPath)) } : void 0,
+      manage: manageValue ? { activation, closeout } : void 0
+    },
+    issues
+  };
+  _configCache = { cwd, inspection };
+  return inspection;
+}
+function validateRspConfig(parsed) {
+  const issues = [];
+  const supported = /* @__PURE__ */ new Set(["kinds", "decisions", "manage"]);
+  for (const key of Object.keys(parsed)) {
+    if (key === "required_sections") {
+      issues.push('config.yaml field "required_sections" is no longer supported');
+    } else if (!supported.has(key)) {
+      issues.push(`config.yaml field "${key}" is not supported`);
+    }
+  }
+  if ("kinds" in parsed) {
+    if (!Array.isArray(parsed.kinds)) {
+      issues.push('config.yaml field "kinds" must be a YAML list');
+    } else if (!parsed.kinds.every((value) => typeof value === "string" && value.trim() !== "")) {
+      issues.push('config.yaml field "kinds" must contain only non-empty strings');
+    } else {
+      const kinds = parsed.kinds.map((value) => value.trim());
+      const duplicates = [...new Set(kinds.filter((value, index) => kinds.indexOf(value) !== index))];
+      if (duplicates.length > 0)
+        issues.push(`config.yaml field "kinds" contains duplicate entries: ${duplicates.join(", ")}`);
+    }
+  }
+  const decisionRecordsIssue = getDecisionRecordsConfigIssue(parsed);
+  if (decisionRecordsIssue)
+    issues.push(decisionRecordsIssue);
+  if ("manage" in parsed) {
+    if (!parsed.manage || typeof parsed.manage !== "object" || Array.isArray(parsed.manage)) {
+      issues.push('config.yaml field "manage" must be a YAML mapping');
+    } else {
+      const manage = parsed.manage;
+      const supportedManageFields = /* @__PURE__ */ new Set(["activation", "closeout"]);
+      for (const key of Object.keys(manage)) {
+        if (!supportedManageFields.has(key))
+          issues.push(`config.yaml field "manage.${key}" is not supported`);
+      }
+      if ("activation" in manage && !MANAGE_ACTIVATIONS.includes(manage.activation))
+        issues.push('config.yaml field "manage.activation" must be one of: explicit, auto');
+      if ("closeout" in manage && !MANAGE_CLOSEOUTS.includes(manage.closeout))
+        issues.push('config.yaml field "manage.closeout" must be one of: manual, lifecycle, local');
+    }
+  }
+  return issues;
+}
+function clearConfigCache() {
+  _configCache = null;
+}
+function resolveKinds(config) {
+  return config.kinds && config.kinds.length > 0 ? config.kinds : [...VALID_KINDS];
+}
+function resolveRequiredSections(_config) {
+  return [...DEFAULT_REQUIRED_SECTIONS];
+}
+function resolveManagePolicy(config, options = {}) {
+  if (options.configValid === false)
+    return { ...FAILED_CLOSED_MANAGE_POLICY };
+  return {
+    activation: config.manage?.activation ?? DEFAULT_MANAGE_POLICY.activation,
+    closeout: config.manage?.closeout ?? DEFAULT_MANAGE_POLICY.closeout
+  };
+}
+async function getVersion() {
+  const { version } = JSON.parse(await readFile2(join4(PKG_ROOT, "package.json"), "utf-8"));
+  return version;
+}
+
+// src/core/output.ts
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function emitJson(data, options = {}) {
+  const indentation = options.compact ? void 0 : 2;
+  process.stdout.write(`${JSON.stringify(data, null, indentation)}
+`);
+}
+function recordRuntimeDiagnostic(runtime, diagnostic, verbose = false) {
+  runtime.push(diagnostic);
+  if (verbose) {
+    console.error(`  ${pc.dim(`[verbose] ${diagnostic.operation} ${diagnostic.path}: ${diagnostic.message}`)}`);
+  }
+}
+
+export {
+  ManagedPathError,
+  inspectManagedDirectory,
+  requireManagedDirectory,
+  inspectManagedFile,
+  requireManagedFile,
+  ensureManagedFile,
+  writeManagedFile,
+  resolveManagedDirectoryChain,
+  inspectManagedFileTree,
+  DEFAULT_DECISION_RECORDS_PATH,
+  resolveDecisionRecordsPath,
+  ensureDecisionRecordsDirectory,
+  validateDecisionRecordsFilesystemPath,
+  toErrorMessage,
+  emitJson,
+  recordRuntimeDiagnostic,
+  parseFrontmatter,
+  countCheckboxes,
+  walkMarkdownFiles,
+  inspectUnsupportedRules,
+  normalizeLogicalPath,
+  generateChangeContent,
+  upsertRspAgentsBlock,
+  hasRspAgentsBlock,
+  isValidSpecName,
+  guardRspInitialized,
+  cleanupEmptyParentDirs,
+  detectProjectName,
+  generateDesignContent,
+  generateSpecContent,
+  extractSection,
+  extractBlockerLines,
+  hasMeaningfulBlockers,
+  detectDeltaSections,
+  collectArchiveReadiness,
+  buildDurableReviewGuidance,
+  getDurableReviewCandidateTargets,
+  collectArchiveChecklist,
+  parseScenarios,
+  pc,
+  PKG_ROOT,
+  RSP_DIR,
+  RSP_RULES_PATH,
+  OBSOLETE_RSP_RULES_PATH,
+  CHANGES_DIR,
+  FOCUS_DIR,
+  ARCHIVES_DIR,
+  LOCK_PATH,
+  CONFIG_PATH,
+  VALID_KINDS,
+  loadRspConfig,
+  inspectRspConfig,
+  clearConfigCache,
+  resolveKinds,
+  resolveRequiredSections,
+  resolveManagePolicy,
+  getVersion
+};