@oevery/rsp 3.1.0-beta.3 → 3.1.0-beta.5

package/dist/{chunk-OTJFL6XH.mjs → chunk-UVYEXKYS.mjs}

@@ -215,6 +215,162 @@ async function validateDecisionRecordsFilesystemPath(pathValue) {
   return null;
 }
 
+// src/core/document-model.ts
+var CHANGE_DOCUMENT_SCHEMA = {
+  titlePrefix: "# Change:",
+  sections: [
+    { id: "proposal", heading: "Proposal" },
+    { id: "spec", heading: "Spec" },
+    { id: "design", heading: "Design" },
+    { id: "tasks", heading: "Tasks" },
+    { id: "verify", heading: "Verify" },
+    { id: "blockers", heading: "Blockers" }
+  ]
+};
+var GROUP_BRIEF_DOCUMENT_SCHEMA = {
+  titlePrefix: "# Change Group:",
+  sections: [
+    { id: "goal", heading: "Goal" },
+    { id: "scope", heading: "Scope" },
+    { id: "sharedConstraints", heading: "Shared Constraints" },
+    { id: "slices", heading: "Slices" },
+    { id: "completionConditions", heading: "Completion Conditions" },
+    { id: "durableOutcomes", heading: "Durable Outcomes" },
+    { id: "blockers", heading: "Blockers" }
+  ]
+};
+var DocumentSectionCardinalityError = class extends Error {
+  constructor(sectionId, count) {
+    super(`document must contain exactly one ${sectionId} section; found ${count}`);
+    this.sectionId = sectionId;
+    this.count = count;
+    this.name = "DocumentSectionCardinalityError";
+  }
+  sectionId;
+  count;
+};
+function parseRspDocument(source, schema) {
+  const definitionsByHeading = new Map(schema.sections.map((definition) => [definition.heading, definition]));
+  const observedHeadings = collectLevelTwoHeadings(source);
+  const sections = /* @__PURE__ */ new Map();
+  const unknownHeadings = [];
+  for (let index = 0; index < observedHeadings.length; index++) {
+    const observed = observedHeadings[index];
+    const definition = definitionsByHeading.get(observed.heading);
+    if (!definition) {
+      unknownHeadings.push(observed.heading);
+      continue;
+    }
+    const nextHeading = observedHeadings[index + 1];
+    const bodyEnd = nextHeading ? lineBreakStart(source, nextHeading.start) : source.length;
+    const section = {
+      id: definition.id,
+      heading: definition.heading,
+      canonical: observed.canonical,
+      body: source.slice(observed.end, bodyEnd).trim(),
+      headingStart: observed.start,
+      headingEnd: observed.end,
+      bodyStart: observed.end,
+      bodyEnd
+    };
+    const matches = sections.get(definition.id) ?? [];
+    matches.push(section);
+    sections.set(definition.id, matches);
+  }
+  const missingSections = schema.sections.filter((definition) => !sections.has(definition.id)).map((definition) => definition.id);
+  const duplicateSections = schema.sections.filter((definition) => (sections.get(definition.id)?.length ?? 0) > 1).map((definition) => definition.id);
+  const titleOccurrences = collectDocumentTitles(source, schema.titlePrefix);
+  const titles = titleOccurrences.map((title) => title.value);
+  return {
+    source,
+    schema,
+    title: titles[0] ?? null,
+    titles,
+    titleOccurrences,
+    sections,
+    unknownHeadings,
+    missingSections,
+    duplicateSections
+  };
+}
+function getDocumentTitles(document, compatibility = "broad") {
+  if (compatibility === "broad")
+    return document.titles;
+  return document.titleOccurrences.filter((title) => compatibility === "identity" ? title.identityCompatible : title.spaced).map((title) => title.value);
+}
+function getDocumentTitle(document, compatibility = "broad") {
+  return getDocumentTitles(document, compatibility)[0] ?? null;
+}
+function getDocumentSections(document, sectionId) {
+  return document.sections.get(sectionId) ?? [];
+}
+function getDocumentSection(document, sectionId) {
+  return getDocumentSections(document, sectionId)[0];
+}
+function getDocumentSectionBody(document, sectionId) {
+  return getDocumentSection(document, sectionId)?.body ?? "";
+}
+function getDocumentSectionDefinitionByHeading(schema, heading) {
+  return schema.sections.find((candidate) => candidate.heading === heading);
+}
+function getCanonicalSectionHeadings(schema) {
+  return schema.sections.map((section) => section.heading);
+}
+function renderDocumentSectionHeading(schema, sectionId) {
+  const definition = schema.sections.find((candidate) => candidate.id === sectionId);
+  if (!definition)
+    throw new Error(`unknown document section: ${sectionId}`);
+  return `## ${definition.heading}`;
+}
+function renderDocumentTitle(schema, title) {
+  return `${schema.titlePrefix} ${title}`;
+}
+function appendDocumentSectionItem(document, sectionId, item) {
+  const matches = getDocumentSections(document, sectionId);
+  if (matches.length !== 1)
+    throw new DocumentSectionCardinalityError(sectionId, matches.length);
+  const insertAt = matches[0].bodyEnd;
+  const before = document.source.slice(0, insertAt);
+  const separator = before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  return `${before}${separator}${item}
+${document.source.slice(insertAt)}`;
+}
+function collectLevelTwoHeadings(source) {
+  const headings = [];
+  const pattern = /^## ([^\r\n]+)\r?$/gm;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const heading = match[1].trimEnd();
+    headings.push({
+      heading,
+      canonical: heading === match[1],
+      start: match.index,
+      end: match.index + match[0].length
+    });
+  }
+  return headings;
+}
+function collectDocumentTitles(source, prefix) {
+  const titles = [];
+  for (const line of source.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(prefix))
+      continue;
+    const identity = line.startsWith(prefix) ? line.slice(prefix.length).match(/^\s+(\S+)\s*$/) : null;
+    titles.push({
+      value: trimmed.slice(prefix.length).trim(),
+      identityCompatible: identity !== null,
+      spaced: line.startsWith(`${prefix} `)
+    });
+  }
+  return titles;
+}
+function lineBreakStart(source, headingStart) {
+  if (headingStart > 0 && source[headingStart - 1] === "\n")
+    return headingStart - 1;
+  return headingStart;
+}
+
 // src/core/helpers.ts
 import { existsSync as existsSync2 } from "fs";
 import { readdir as readdir3, readFile, rmdir } from "fs/promises";
@@ -314,85 +470,79 @@ 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>");
+  const placeholder = "<\u2026>";
+  const proposalSummary = summary || placeholder;
+  const issueFrontmatter = renderIssueFrontmatter(options.issues ?? []);
   if (name === "project-setup") {
     return `---
 kind: ops
----
+${issueFrontmatter}---
 
-# Change: project-setup
+${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, "project-setup")}
 
-## Proposal
+${changeSectionHeading("proposal")}
 - Outcome: ${proposalSummary}
 - Why:
-  - Establish a durable project model before normal implementation work starts
+  - ${placeholder}
 - 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
+  - ${placeholder}
 - Non-goals:
-  - Do not duplicate durable project facts across this change, specs, and AGENTS.md
+  - ${placeholder}
 
-## Spec
+${changeSectionHeading("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
+- Requirement: ${placeholder}
+  - ${placeholder}
 
 ### 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
+#### Scenario: ${placeholder}
+- GIVEN ${placeholder}
+- WHEN ${placeholder}
+- THEN ${placeholder}
 
-## Design
+${changeSectionHeading("design")}
 - Approach:
-  - Keep bootstrap work in this single Change while returning durable outcomes to their existing project owners
+  - ${placeholder}
 - Boundaries:
-  - Specs own stable current facts; project-owned CONTEXT.md and AGENTS.md retain their navigation, context, and instruction roles
+  - ${placeholder}
 - Affected areas:
   - .rsp/specs/design.md
-  - Project-owned CONTEXT.md or AGENTS.md when applicable
+  - CONTEXT.md
+  - AGENTS.md
 - 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
+  - Current facts: ${placeholder}
+  - Lasting rationale: ${placeholder}
 - Constraints:
-  - Keep the setup lightweight and avoid duplicating durable project facts
+  - ${placeholder}
 
-## 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
+${changeSectionHeading("tasks")}
+- [ ] .rsp/specs/design.md: ${placeholder}
+- [ ] CONTEXT.md: ${placeholder}
+- [ ] AGENTS.md: ${placeholder}
 
-## Verify
+${changeSectionHeading("verify")}
 - Automated:
-  - [ ] Run rsp doctor \u2014 proves: the initialized RSP workspace is structurally valid
+  - [ ] rsp doctor \u2014 proves: ${placeholder}
 - Manual or environment:
-  - [ ] Review .rsp/specs/design.md and project-owned context or instructions and confirm they match the repository
+  - [ ] ${placeholder}
 - Coverage:
-  - none
+  - ${placeholder}
 
-## Blockers
+${changeSectionHeading("blockers")}
 - none
 `;
   }
   const frontmatterKind = kind ?? "<choose: feature | fix | refactor | docs | ops | research>";
   if (options.lite)
-    return generateLiteChangeContent(name, proposalSummary, frontmatterKind);
+    return generateLiteChangeContent(name, proposalSummary, frontmatterKind, issueFrontmatter);
   const template = getChangeTemplateByKind(kind);
   return `---
 kind: "${frontmatterKind}"
----
+${issueFrontmatter}---
 
-# Change: ${name}
+${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, name)}
 
-## Proposal
+${changeSectionHeading("proposal")}
 - Outcome: ${proposalSummary}
 - Why:
   - ${template.why}
@@ -401,199 +551,125 @@ kind: "${frontmatterKind}"
 - Non-goals:
   - ${template.nonGoals}
 
-## Spec
+${changeSectionHeading("spec")}
 ${template.specSection}
 
 ### Acceptance
 ${template.acceptanceSection}
 
-## Design
+${changeSectionHeading("design")}
 - Approach:
   - ${template.approach}
 - Boundaries:
-  - <module, interface, data, document, or ownership boundary affected>
+  - ${placeholder}
 - Affected areas:
   - ${template.affectedArea1}
   - ${template.affectedArea2}
 - Constraints:
   - ${template.constraints}
 
-## Tasks
+${changeSectionHeading("tasks")}
 - [ ] ${template.task}
 
-## Verify
+${changeSectionHeading("verify")}
 - Automated:
-  - [ ] ${template.automatedVerify} \u2014 proves: <behavior or scope covered>
+  - [ ] ${template.automatedVerify} \u2014 proves: ${placeholder}
 - Manual or environment:
   - [ ] ${template.manualVerify}
 - Coverage:
-  - <omitted or unavailable relevant coverage and reason, or none>
+  - ${placeholder}
 
-## Blockers
+${changeSectionHeading("blockers")}
 - none
 `;
 }
-function generateLiteChangeContent(name, proposalSummary, frontmatterKind) {
+function generateLiteChangeContent(name, proposalSummary, frontmatterKind, issueFrontmatter) {
+  const placeholder = "<\u2026>";
   return `---
 kind: "${frontmatterKind}"
----
+${issueFrontmatter}---
 
-# Change: ${name}
+${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, name)}
 
-## Proposal
+${changeSectionHeading("proposal")}
 - Outcome: ${proposalSummary}
 - Why:
-  - <why this small change matters>
+  - ${placeholder}
 - Scope:
-  - <what will change>
+  - ${placeholder}
 - Non-goals:
   - none
 
-## Spec
+${changeSectionHeading("spec")}
 ### MODIFIED
-- Requirement: <observable outcome>
-  - <what should be true after this change>
+- Requirement: ${placeholder}
+  - ${placeholder}
 
 ### Acceptance
-#### Scenario: change is complete
-- GIVEN <current context>
-- WHEN <the change is applied>
-- THEN <expected outcome>
+#### Scenario: ${placeholder}
+- GIVEN ${placeholder}
+- WHEN ${placeholder}
+- THEN ${placeholder}
 
-## Design
+${changeSectionHeading("design")}
 - Approach:
-  - <minimal implementation approach>
+  - ${placeholder}
 - Boundaries:
-  - <primary ownership or interface boundary>
+  - ${placeholder}
 - Affected areas:
-  - <primary file, directory, or doc path>
+  - ${placeholder}
 - Constraints:
-  - <important constraint, or none>
+  - ${placeholder}
 
-## Tasks
-- [ ] Implement the small change
+${changeSectionHeading("tasks")}
+- [ ] ${placeholder}
 
-## Verify
+${changeSectionHeading("verify")}
 - Automated:
-  - [ ] <cheapest decisive check; retain a new test only when justified, or not applicable: reason> \u2014 proves: <behavior or scope covered>
+  - [ ] ${placeholder} \u2014 proves: ${placeholder}
 - Manual or environment:
-  - [ ] <exact acceptance scenario, or unavailable/not applicable: owner and reason>
+  - [ ] ${placeholder}
 - Coverage:
-  - <omitted or unavailable relevant coverage and reason, or none>
+  - ${placeholder}
 
-## Blockers
+${changeSectionHeading("blockers")}
 - none
 `;
 }
+function renderIssueFrontmatter(issues) {
+  if (issues.length === 0)
+    return "";
+  return `issues:
+${issues.map((issue) => `  - url: ${JSON.stringify(issue.url)}
+    relation: ${issue.relation}`).join("\n")}
+`;
+}
 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>"
-      };
-  }
+  const placeholder = "<\u2026>";
+  const delta = kind === "feature" || kind === "research" || kind === void 0 ? "ADDED" : "MODIFIED";
+  return {
+    why: placeholder,
+    scope: placeholder,
+    nonGoals: placeholder,
+    specSection: `<!-- ${placeholder} -->
+### ${delta}
+- Requirement: ${placeholder}
+  - ${placeholder}`,
+    acceptanceSection: `#### Scenario: ${placeholder}
+- GIVEN ${placeholder}
+- WHEN ${placeholder}
+- THEN ${placeholder}`,
+    approach: placeholder,
+    affectedArea1: placeholder,
+    affectedArea2: placeholder,
+    constraints: placeholder,
+    task: placeholder,
+    automatedVerify: placeholder,
+    manualVerify: placeholder
+  };
+}
+function changeSectionHeading(sectionId) {
+  return renderDocumentSectionHeading(CHANGE_DOCUMENT_SCHEMA, sectionId);
 }
 function renderRspAgentsBlock() {
   return `${RSP_AGENTS_BEGIN}
@@ -675,78 +751,73 @@ async function detectProjectName() {
   return basename(process.cwd());
 }
 function generateDesignContent(projectName) {
+  const placeholder = "<\u2026>";
   return `# Project Design: ${projectName}
 
 ## Purpose
-- <what this project is responsible for>
-- <who or what it serves>
+- ${placeholder}
 
 ## Stable Facts
-- <durable fact that future agents or developers must know>
-- <key architectural invariant>
+- ${placeholder}
 
 ## Boundaries
 - In scope:
-  - <major capability or boundary>
+  - ${placeholder}
 - Out of scope:
-  - <intentional non-goal>
+  - ${placeholder}
 
 ## Structure
-- <important directory or subsystem> \u2014 <responsibility>
+- ${placeholder}
 
 ## Constraints
-- <cross-cutting technical or operational constraint, when it affects architecture>
+- ${placeholder}
 `;
 }
 function generateSpecContent(name) {
   const title = toTitleCase(name);
+  const placeholder = "<\u2026>";
   return `# ${title}
 
 ## Purpose
-- <why this project-level spec exists>
+- ${placeholder}
 
 ## Stable Facts
-- <durable fact that future work must know>
+- ${placeholder}
 
 ## Boundaries
 - In scope:
-  - <what this spec covers>
+  - ${placeholder}
 - Out of scope:
-  - <what this spec does not cover>
+  - ${placeholder}
 
 ## Constraints
-- <stable constraint, if any>
+- ${placeholder}
 `;
 }
 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);
+  const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
+  return normalizeBlockerBody(getDocumentSectionBody(document, "blockers"));
+}
+function hasMeaningfulBlockerBody(body) {
+  return hasMeaningfulBlockerLines(normalizeBlockerBody(body));
+}
+function normalizeBlockerBody(body) {
+  return body.replace(/<!--[\s\S]*?-->/g, "").split("\n").map((line) => line.trim()).filter(Boolean);
 }
 function hasMeaningfulBlockers(content) {
-  const lines = extractBlockerLines(content);
+  return hasMeaningfulBlockerLines(extractBlockerLines(content));
+}
+function hasMeaningfulBlockerLines(lines) {
   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");
+  const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
+  const body = getDocumentSectionBody(document, "spec");
   return {
     added: /^###\s*ADDED/im.test(body),
     modified: /^###\s*MODIFIED/im.test(body),
@@ -755,8 +826,9 @@ function detectDeltaSections(content) {
 }
 function collectArchiveReadiness(content, options = {}) {
   const warnings = [];
-  const tasksSection = extractSection(content, "Tasks");
-  const verifySection = extractSection(content, "Verify");
+  const document = parseRspDocument(content, CHANGE_DOCUMENT_SCHEMA);
+  const tasksSection = getDocumentSectionBody(document, "tasks");
+  const verifySection = getDocumentSectionBody(document, "verify");
   const taskTodos = getOpenCheckboxes(tasksSection);
   if (taskTodos.length > 0)
     warnings.push(`${taskTodos.length} task item(s) still incomplete`);
@@ -835,7 +907,7 @@ 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_REQUIRED_SECTIONS = getCanonicalSectionHeadings(CHANGE_DOCUMENT_SCHEMA);
 var DEFAULT_MANAGE_POLICY = { activation: "explicit", closeout: "local" };
 var FAILED_CLOSED_MANAGE_POLICY = { activation: "explicit", closeout: "manual" };
 var MANAGE_ACTIVATIONS = ["explicit", "auto"];
@@ -865,6 +937,7 @@ async function inspectRspConfig() {
   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 languageValue = parsed.language && typeof parsed.language === "object" && !Array.isArray(parsed.language) ? parsed.language : 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;
@@ -873,7 +946,8 @@ async function inspectRspConfig() {
     config: {
       kinds,
       decisions: decisionRecordsIssue === null && validateDecisionRecordsPath(decisionPath) === null ? { path: normalizeDecisionRecordsPath(String(decisionPath)) } : void 0,
-      manage: manageValue ? { activation, closeout } : void 0
+      manage: manageValue ? { activation, closeout } : void 0,
+      language: parseLanguageConfig(languageValue)
     },
     issues
   };
@@ -882,7 +956,7 @@ async function inspectRspConfig() {
 }
 function validateRspConfig(parsed) {
   const issues = [];
-  const supported = /* @__PURE__ */ new Set(["kinds", "decisions", "manage"]);
+  const supported = /* @__PURE__ */ new Set(["kinds", "decisions", "manage", "language"]);
   for (const key of Object.keys(parsed)) {
     if (key === "required_sections") {
       issues.push('config.yaml field "required_sections" is no longer supported');
@@ -921,6 +995,24 @@ function validateRspConfig(parsed) {
         issues.push('config.yaml field "manage.closeout" must be one of: manual, lifecycle, local');
     }
   }
+  if ("language" in parsed) {
+    if (!parsed.language || typeof parsed.language !== "object" || Array.isArray(parsed.language)) {
+      issues.push('config.yaml field "language" must be a YAML mapping');
+    } else {
+      const language = parsed.language;
+      const supportedLanguageFields = /* @__PURE__ */ new Set(["default", "artifacts", "commit"]);
+      for (const key of Object.keys(language)) {
+        if (!supportedLanguageFields.has(key))
+          issues.push(`config.yaml field "language.${key}" is not supported`);
+      }
+      if (!("default" in language))
+        issues.push('config.yaml field "language.default" is required when language is configured');
+      for (const key of supportedLanguageFields) {
+        if (key in language && canonicalizeLanguageTag(language[key]) === null)
+          issues.push(`config.yaml field "language.${key}" must be a non-empty valid BCP 47 language tag`);
+      }
+    }
+  }
   return issues;
 }
 function clearConfigCache() {
@@ -940,6 +1032,37 @@ function resolveManagePolicy(config, options = {}) {
     closeout: config.manage?.closeout ?? DEFAULT_MANAGE_POLICY.closeout
   };
 }
+function resolveLanguagePolicy(config, options = {}) {
+  if (options.configValid === false || !config.language)
+    return { artifacts: null, commit: null };
+  return {
+    artifacts: config.language.artifacts ?? config.language.default,
+    commit: config.language.commit ?? config.language.default
+  };
+}
+function parseLanguageConfig(value) {
+  if (!value)
+    return void 0;
+  const defaultLanguage = canonicalizeLanguageTag(value.default);
+  if (defaultLanguage === null)
+    return void 0;
+  const artifacts = canonicalizeLanguageTag(value.artifacts);
+  const commit = canonicalizeLanguageTag(value.commit);
+  return {
+    default: defaultLanguage,
+    artifacts: artifacts ?? void 0,
+    commit: commit ?? void 0
+  };
+}
+function canonicalizeLanguageTag(value) {
+  if (typeof value !== "string" || value.trim() === "")
+    return null;
+  try {
+    return Intl.getCanonicalLocales(value.trim())[0] ?? null;
+  } catch {
+    return null;
+  }
+}
 async function getVersion() {
   const { version } = JSON.parse(await readFile2(join4(PKG_ROOT, "package.json"), "utf-8"));
   return version;
@@ -975,6 +1098,19 @@ export {
   resolveDecisionRecordsPath,
   ensureDecisionRecordsDirectory,
   validateDecisionRecordsFilesystemPath,
+  CHANGE_DOCUMENT_SCHEMA,
+  GROUP_BRIEF_DOCUMENT_SCHEMA,
+  DocumentSectionCardinalityError,
+  parseRspDocument,
+  getDocumentTitles,
+  getDocumentTitle,
+  getDocumentSections,
+  getDocumentSectionBody,
+  getDocumentSectionDefinitionByHeading,
+  getCanonicalSectionHeadings,
+  renderDocumentSectionHeading,
+  renderDocumentTitle,
+  appendDocumentSectionItem,
   toErrorMessage,
   emitJson,
   recordRuntimeDiagnostic,
@@ -992,8 +1128,8 @@ export {
   detectProjectName,
   generateDesignContent,
   generateSpecContent,
-  extractSection,
   extractBlockerLines,
+  hasMeaningfulBlockerBody,
   hasMeaningfulBlockers,
   detectDeltaSections,
   collectArchiveReadiness,
@@ -1018,5 +1154,6 @@ export {
   resolveKinds,
   resolveRequiredSections,
   resolveManagePolicy,
+  resolveLanguagePolicy,
   getVersion
 };