@fission-ai/openspec 1.13.0 → 1.13.1

package/dist/core/parsers/requirement-text.d.ts

@@ -15,8 +15,17 @@ export { buildCodeFenceMask } from './code-fence.js';
  * as a scenario, so the delta counter must too (parity). The delta/loss path
  * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
  * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ * A header alone is not yet a scenario on either path: see hasScenarioBody.
  */
 export declare const SCENARIO_HEADER: RegExp;
+/**
+ * Whether a scenario's body has content. The spec path
+ * (`MarkdownParser.parseScenarios`) drops a scenario whose body is empty, so
+ * the delta counter must too (parity): otherwise `validate` accepts a
+ * requirement whose only scenario is a bare header, and archive rejects it when
+ * it validates the rebuilt spec.
+ */
+export declare function hasScenarioBody(body: string): boolean;
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept
@@ -49,8 +58,10 @@ export declare function extractRequirementBody(bodyLines: string[]): string;
 export declare function extractRequirementText(headerTitle: string, bodyLines: string[]): string;
 /**
  * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
- * lines. A `#### Scenario:` that lives inside a fenced example is not a real
- * scenario and is not counted.
+ * lines whose body has content. A `#### Scenario:` that lives inside a fenced
+ * example is not a real scenario and is not counted.
  */
 export declare function countScenarios(bodyLines: string[]): number;
+/** Count the `#### ` headers in a requirement block that have no body under them. */
+export declare function countEmptyScenarios(bodyLines: string[]): number;
 //# sourceMappingURL=requirement-text.d.ts.map

package/dist/core/parsers/requirement-text.js

@@ -22,8 +22,21 @@ const HEADER_LINE = /^#{1,6}\s/;
  * as a scenario, so the delta counter must too (parity). The delta/loss path
  * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
  * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ * A header alone is not yet a scenario on either path: see hasScenarioBody.
  */
 export const SCENARIO_HEADER = /^####\s+/;
+/** A header at scenario level or above (`#` to `####`): where a scenario body ends. */
+const SCENARIO_BODY_END = /^#{1,4}\s/;
+/**
+ * Whether a scenario's body has content. The spec path
+ * (`MarkdownParser.parseScenarios`) drops a scenario whose body is empty, so
+ * the delta counter must too (parity): otherwise `validate` accepts a
+ * requirement whose only scenario is a bare header, and archive rejects it when
+ * it validates the rebuilt spec.
+ */
+export function hasScenarioBody(body) {
+    return body.trim().length > 0;
+}
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept
@@ -82,18 +95,32 @@ export function extractRequirementText(headerTitle, bodyLines) {
 }
 /**
  * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
- * lines. A `#### Scenario:` that lives inside a fenced example is not a real
- * scenario and is not counted.
+ * lines whose body has content. A `#### Scenario:` that lives inside a fenced
+ * example is not a real scenario and is not counted.
  */
 export function countScenarios(bodyLines) {
+    return readScenarioBodies(bodyLines).filter(hasScenarioBody).length;
+}
+/** Count the `#### ` headers in a requirement block that have no body under them. */
+export function countEmptyScenarios(bodyLines) {
+    return readScenarioBodies(bodyLines).filter((body) => !hasScenarioBody(body)).length;
+}
+/**
+ * The body of each scenario in a requirement block. A body runs to the next
+ * non-fenced header of level 4 or above, the boundary the spec path uses, so a
+ * fenced block or a deeper `#####` header is part of it.
+ */
+function readScenarioBodies(bodyLines) {
     const mask = buildCodeFenceMask(bodyLines);
-    let count = 0;
+    const bodies = [];
     for (let i = 0; i < bodyLines.length; i++) {
-        if (mask[i])
+        if (mask[i] || !SCENARIO_HEADER.test(bodyLines[i]))
             continue;
-        if (SCENARIO_HEADER.test(bodyLines[i]))
-            count++;
+        let end = i + 1;
+        while (end < bodyLines.length && (mask[end] || !SCENARIO_BODY_END.test(bodyLines[end])))
+            end++;
+        bodies.push(bodyLines.slice(i + 1, end).join('\n'));
     }
-    return count;
+    return bodies;
 }
 //# sourceMappingURL=requirement-text.js.map

package/dist/core/parsers/spec-structure.js

@@ -1,4 +1,5 @@
 import { buildCodeFenceMask } from './code-fence.js';
+import { normalizeRequirementName } from './requirement-blocks.js';
 const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
 const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
@@ -53,7 +54,9 @@ export function findMainSpecStructureIssues(content) {
             });
             continue;
         }
-        const requirementName = requirementMatch[1].trim();
+        // The same name every other reader uses, so a closed heading
+        // (`### Requirement: Foo ###`) duplicates `### Requirement: Foo`.
+        const requirementName = normalizeRequirementName(requirementMatch[1]);
         const previousLine = requirementLines.get(requirementName);
         if (previousLine !== undefined) {
             issues.push({

package/dist/core/project-config.d.ts

@@ -116,7 +116,10 @@ export declare function resolveConfigFilePath(projectRoot: string): string | nul
 /** Human rendering of a malformed pointer reason, shared by every surface. */
 export declare function storePointerProblem(reason: 'unparseable' | 'non_string'): string;
 export interface OpenSpecDirClassification {
-    /** True when openspec/specs or openspec/changes exists as a directory. */
+    /**
+     * True when openspec/specs or openspec/changes exists as a directory
+     * that is not itself a store root.
+     */
     hasPlanningShape: boolean;
     pointer: StorePointerRead;
 }
@@ -124,6 +127,11 @@ export interface OpenSpecDirClassification {
  * One classification for "real root vs config-only pointer dir", shared
  * by root resolution and the init pointer guard so they can never
  * disagree (slice 3.2).
+ *
+ * A specs/ or changes/ directory carrying store metadata is a store at
+ * the recommended `~/openspec/<id>` layout whose id is `specs` or
+ * `changes`, not planning content of the directory above it. Counting it
+ * would make $HOME the phantom root the qualifying walk exists to prevent.
  */
 export declare function classifyOpenSpecDir(projectRoot: string): OpenSpecDirClassification;
 //# sourceMappingURL=project-config.d.ts.map

package/dist/core/project-config.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
+import { getStoreMetadataPath } from './store/foundation.js';
 export const OPERATION_IDS = ['apply', 'archive'];
 const OperationConfigSchema = z.object({
     guidance: z.array(z.string()).optional(),
@@ -455,13 +456,21 @@ export function storePointerProblem(reason) {
  * One classification for "real root vs config-only pointer dir", shared
  * by root resolution and the init pointer guard so they can never
  * disagree (slice 3.2).
+ *
+ * A specs/ or changes/ directory carrying store metadata is a store at
+ * the recommended `~/openspec/<id>` layout whose id is `specs` or
+ * `changes`, not planning content of the directory above it. Counting it
+ * would make $HOME the phantom root the qualifying walk exists to prevent.
  */
 export function classifyOpenSpecDir(projectRoot) {
     const openspecDir = path.join(projectRoot, 'openspec');
-    const hasPlanningShape = isDirectorySync(path.join(openspecDir, 'specs')) ||
-        isDirectorySync(path.join(openspecDir, 'changes'));
+    const hasPlanningShape = isPlanningDirectorySync(path.join(openspecDir, 'specs')) ||
+        isPlanningDirectorySync(path.join(openspecDir, 'changes'));
     return { hasPlanningShape, pointer: readStorePointer(projectRoot) };
 }
+function isPlanningDirectorySync(candidatePath) {
+    return isDirectorySync(candidatePath) && !existsSync(getStoreMetadataPath(candidatePath));
+}
 function isDirectorySync(candidatePath) {
     try {
         return statSync(candidatePath).isDirectory();

package/dist/core/references.d.ts

@@ -36,6 +36,26 @@ export declare function renderReferencedStoresSection(entries: ReferenceIndexEnt
  * let hostile content forge instruction lines (slice 6.1 hardening).
  */
 export declare function sanitizeInline(value: string, maxLength?: number): string;
+/**
+ * Neutralize the envelope's own tags - opening and closing - in repo-supplied
+ * text, so it cannot close the block that frames it as data nor forge a new
+ * block that carries authority.
+ *
+ * Deliberately narrow: only this fixed vocabulary is touched. Escaping every
+ * angle bracket also works, but it mangles ordinary content for everyone.
+ * OpenSpec's own spec-driven schema writes `### Requirement: <name>` and
+ * `openspec show "<spec-id>"`; custom templates carry `<details>`; and
+ * `context:` routinely holds `R&D`, `pnpm build && pnpm test` or
+ * `Result<T, E>`. All of those would reach the agent entity-encoded - a real
+ * cost paid by every user, against a threat only these tags can carry.
+ */
+export declare function escapeEnvelopeTags(value: string): string;
+/**
+ * Attribute values are ids and directory names, never prose, so escaping every
+ * metacharacter here costs nothing and stops a quote from closing the
+ * attribute and forging siblings on the tag.
+ */
+export declare function escapeEnvelopeAttribute(value: string): string;
 export interface AssembleReferenceIndexInput {
     references: DeclarationEntry[];
     resolvedRoot: ResolvedOpenSpecRoot;

package/dist/core/references.js

@@ -194,6 +194,62 @@ export function sanitizeInline(value, maxLength = 300) {
     const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
 }
+/**
+ * The tags the instruction printer uses to frame its blocks. A block ends at
+ * its own closing tag and nowhere else, so this is the entire breakout
+ * surface: neutralize these and repo-supplied text cannot escape the element
+ * that marks it as data.
+ */
+const ENVELOPE_TAGS = [
+    'artifact',
+    'dependencies',
+    'dependency',
+    'description',
+    'instruction',
+    'output',
+    'path',
+    'project_context',
+    'rules',
+    'success_criteria',
+    'task',
+    'template',
+    'unlocks',
+    'warning',
+];
+// The attribute tail uses `[^<>]` rather than `[^>]` so a run of unterminated
+// `<task ...` openers cannot make each start position scan to end of input,
+// which is how the first version of this escape became quadratic. The separator
+// is `\s`, not a space or tab: XML allows a line break before `>` or an
+// attribute, so a multiline repo value could otherwise split a tag past this.
+const ENVELOPE_TAG = new RegExp(`<(/?)(${ENVELOPE_TAGS.join('|')})(\\s[^<>]*)?>`, 'gi');
+/**
+ * Neutralize the envelope's own tags - opening and closing - in repo-supplied
+ * text, so it cannot close the block that frames it as data nor forge a new
+ * block that carries authority.
+ *
+ * Deliberately narrow: only this fixed vocabulary is touched. Escaping every
+ * angle bracket also works, but it mangles ordinary content for everyone.
+ * OpenSpec's own spec-driven schema writes `### Requirement: <name>` and
+ * `openspec show "<spec-id>"`; custom templates carry `<details>`; and
+ * `context:` routinely holds `R&D`, `pnpm build && pnpm test` or
+ * `Result<T, E>`. All of those would reach the agent entity-encoded - a real
+ * cost paid by every user, against a threat only these tags can carry.
+ */
+export function escapeEnvelopeTags(value) {
+    return value.replace(ENVELOPE_TAG, (_match, slash, tag, attrs) => `&lt;${slash}${tag}${attrs ?? ''}&gt;`);
+}
+/**
+ * Attribute values are ids and directory names, never prose, so escaping every
+ * metacharacter here costs nothing and stops a quote from closing the
+ * attribute and forging siblings on the tag.
+ */
+export function escapeEnvelopeAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
 function renderEntryLines(entry) {
     const lines = [];
     if (entry.root !== undefined) {

package/dist/core/shared/skill-content-equivalence.js

@@ -11,7 +11,11 @@ function normalizeGeneratedSkill(content) {
     const frontmatter = normalized.match(/^---\n[\s\S]*?\n---(?:\n|$)/)?.[0];
     if (!frontmatter)
         return normalized;
-    const versionLine = /^(\s*generatedBy:\s*)(?:"([^"\n]+)"|'([^'\n]+)'|([^\s"'#]+))\s*$/m;
+    // `[ \t]` rather than `\s` so a leading/trailing whitespace run can never
+    // cross a newline: an `m`-anchored `\s*` re-scans from every line start,
+    // which is quadratic on a whitespace-heavy frontmatter. YAML indentation is
+    // spaces and tabs only, so matching is unchanged.
+    const versionLine = /^([ \t]*generatedBy:[ \t]*)(?:"([^"\n]+)"|'([^'\n]+)'|([^\s"'#]+))[ \t]*$/m;
     const normalizedFrontmatter = frontmatter.replace(versionLine, (line, prefix, doubleQuoted, singleQuoted, bare) => {
         const version = doubleQuoted ?? singleQuoted ?? bare;
         return version && GENERATED_VERSION.test(version)

package/dist/core/shared/skill-generation.js

@@ -4,7 +4,24 @@
  * Shared utilities for generating skill and command files.
  */
 import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getUpdateChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxUpdateCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, } from '../templates/skill-templates.js';
+import { assertWorkflowConditionalsResolved, resolveOptionalWorkflows, } from '../templates/optional-workflow.js';
+import { ALL_WORKFLOWS } from '../profiles.js';
 import { OPENSPEC_CLI_ALLOWED_TOOLS } from './allowed-tools.js';
+/**
+ * The workflow set a template body is rendered against.
+ *
+ * `workflowFilter` is both the list of workflows to install and the set a
+ * template may refer to, so resolving optional-workflow conditionals here —
+ * the one place every generation path (init, update, migration, the skills.sh
+ * distribution) already funnels through — keeps a reference to an uninstalled
+ * workflow out of every generated file (#1734, umbrella #919).
+ *
+ * With no filter, every workflow is installed (that is what an unfiltered call
+ * means), so the installed branch is kept.
+ */
+function resolveInstalledWorkflows(workflowFilter) {
+    return new Set(workflowFilter ?? ALL_WORKFLOWS);
+}
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -25,10 +42,15 @@ export function getSkillTemplates(workflowFilter) {
         { template: getOnboardSkillTemplate(), dirName: 'openspec-onboard', workflowId: 'onboard' },
         { template: getOpsxProposeSkillTemplate(), dirName: 'openspec-propose', workflowId: 'propose' },
     ];
-    if (!workflowFilter)
-        return all;
-    const filterSet = new Set(workflowFilter);
-    return all.filter(entry => filterSet.has(entry.workflowId));
+    const installed = resolveInstalledWorkflows(workflowFilter);
+    const selected = workflowFilter ? all.filter(entry => installed.has(entry.workflowId)) : all;
+    return selected.map(entry => ({
+        ...entry,
+        template: {
+            ...entry.template,
+            instructions: resolveOptionalWorkflows(entry.template.instructions, installed),
+        },
+    }));
 }
 /**
  * Gets command templates with their IDs, optionally filtered by workflow IDs.
@@ -50,10 +72,15 @@ export function getCommandTemplates(workflowFilter) {
         { template: getOpsxOnboardCommandTemplate(), id: 'onboard' },
         { template: getOpsxProposeCommandTemplate(), id: 'propose' },
     ];
-    if (!workflowFilter)
-        return all;
-    const filterSet = new Set(workflowFilter);
-    return all.filter(entry => filterSet.has(entry.id));
+    const installed = resolveInstalledWorkflows(workflowFilter);
+    const selected = workflowFilter ? all.filter(entry => installed.has(entry.id)) : all;
+    return selected.map(entry => ({
+        ...entry,
+        template: {
+            ...entry.template,
+            content: resolveOptionalWorkflows(entry.template.content, installed),
+        },
+    }));
 }
 /**
  * Converts command templates to CommandContent array, optionally filtered by workflow IDs.
@@ -82,6 +109,7 @@ export function generateSkillContent(template, generatedByVersion, transformInst
     const instructions = transformInstructions
         ? transformInstructions(template.instructions)
         : template.instructions;
+    assertWorkflowConditionalsResolved(instructions, `Skill '${template.name}' was generated without resolving its optional-workflow blocks`);
     return `---
 name: ${template.name}
 description: ${template.description}

package/dist/core/shared/tool-detection.js

@@ -191,9 +191,15 @@ export function extractGeneratedByVersion(skillFilePath) {
         //   version: "1.0"
         //   generatedBy: "0.23.0"
         // ---
-        const generatedByMatch = content.match(/^\s*generatedBy:\s*["']?([^"'\n]+)["']?\s*$/m);
-        if (generatedByMatch && generatedByMatch[1]) {
-            return generatedByMatch[1].trim();
+        // Scanned per line, and with `[ \t]` rather than `\s`, so the leading
+        // whitespace run can never cross a newline. A single `m`-anchored `\s*`
+        // over the whole file re-scans it from every line start, which is
+        // quadratic on a whitespace-heavy SKILL.md.
+        for (const line of content.split(/\r\n?|\n/)) {
+            const generatedByMatch = line.match(/^[ \t]*generatedBy:[ \t]*["']?([^"'\n]+)["']?[ \t]*$/);
+            if (generatedByMatch && generatedByMatch[1]) {
+                return generatedByMatch[1].trim();
+            }
         }
         return null;
     }

package/dist/core/specs-apply.js

@@ -22,7 +22,7 @@ function isLexicallyWithin(allowedDirectory, targetPath) {
             !relative.startsWith(`..${path.sep}`) &&
             !path.isAbsolute(relative)));
 }
-function resolveTrustedSpecPath(specsRoot, specPath) {
+function resolveTrustedSpecPath(specsRoot, specPath, projectRoot) {
     if (!isLexicallyWithin(specsRoot, specPath)) {
         throw new Error(`Path is outside the allowed directory: ${specPath}`);
     }
@@ -42,6 +42,14 @@ function resolveTrustedSpecPath(specsRoot, specPath) {
         // Freeze their canonical location as the trust root so later swaps are
         // rejected while a nested spec.md link still cannot escape.
         const root = FileSystemUtils.canonicalizeExistingPath(path.dirname(specPath));
+        // An external capability link is deliberate and supported (see
+        // assertDiscoveredSpecPath), so it is not refused here. What was wrong is
+        // that the write was silent: the CLI reported the in-project path while
+        // writing somewhere else entirely, so a link swapped underneath a repo
+        // left nothing on screen to notice. Name the real destination instead.
+        if (projectRoot && !isLexicallyWithin(FileSystemUtils.canonicalizeExistingPath(projectRoot), root)) {
+            process.emitWarning(`Capability '${path.basename(path.dirname(specPath))}' links outside the project; writing to ${root}`, 'OpenSpecExternalSpecWrite');
+        }
         const file = path.join(root, path.basename(specPath));
         FileSystemUtils.assertPathWithin(root, file);
         return { root, file };
@@ -69,7 +77,10 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
     for (const { id, specFile } of discovered) {
         const targetFile = path.join(mainSpecsDir, ...id.split('/'), 'spec.md');
         const source = resolveTrustedSpecPath(changeSpecsDir, specFile);
-        const target = resolveTrustedSpecPath(mainSpecsDir, targetFile);
+        // Main specs always live at `<project root>/openspec/specs`, so the
+        // project root is the grandparent - a linked capability directory may not
+        // leave it.
+        const target = resolveTrustedSpecPath(mainSpecsDir, targetFile, path.dirname(path.dirname(mainSpecsDir)));
         // Check if target exists
         let exists = false;
         try {
@@ -110,6 +121,29 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // Parse deltas from the change spec file
     const plan = parseDeltaSpec(changeContent);
     const specName = update.id;
+    // A FROM:/TO: line that never formed a pair means the RENAMED section does not
+    // say what the author meant. Refuse rather than apply the pairing the reader
+    // happened to form: with interleaved lines that pairing renames a requirement
+    // the delta never named, under a name written for a different one.
+    if (plan.unpairedRenames.length > 0) {
+        const first = plan.unpairedRenames[0];
+        const missing = first.side === 'FROM' ? 'TO' : 'FROM';
+        throw new Error(`${specName} validation failed - RENAMED entry on line ${first.line} has no matching ${missing}: ` +
+            `for header "### Requirement: ${first.name}". ` +
+            `Write each rename as a FROM: line followed immediately by its TO: line.`);
+    }
+    // A well-formed requirement written outside every delta section is not
+    // applied. Say so here as well as in validate: archive is the last point at
+    // which the author can still notice, and the block reads exactly like one
+    // that would have applied.
+    for (const orphan of plan.orphanedRequirements) {
+        const where = orphan.section
+            ? `under "## ${orphan.section}"`
+            : 'above the first "## " section';
+        warn(`${specName} - requirement "${orphan.name}" (line ${orphan.line}) is ${where}, ` +
+            `which is not a delta section, so it was not applied. ` +
+            `Move it under ADDED/MODIFIED/REMOVED/RENAMED Requirements.`);
+    }
     // Pre-validate duplicates within sections
     const addedNames = new Set();
     for (const add of plan.added) {
@@ -287,6 +321,13 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (nameToBlock.has(to)) {
             throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`);
         }
+        // A target that differs from another requirement only in case or interior
+        // whitespace would leave two copies of one requirement. The source itself
+        // is exempt, so a case-only rename of a requirement stays allowed.
+        const targetNearMiss = [...nameToBlock.keys()].find((k) => k !== from && foldRequirementName(k) === foldRequirementName(to));
+        if (targetNearMiss !== undefined) {
+            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - "### Requirement: ${nameToBlock.get(targetNearMiss).name}" already exists and differs only in case or spacing; choose a distinct name`);
+        }
         const block = nameToBlock.get(from);
         const newHeader = `### Requirement: ${to}`;
         const rawLines = block.raw.split('\n');
@@ -369,6 +410,15 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             }
             throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`);
         }
+        // A name that differs from an existing requirement only in case or
+        // interior whitespace is that requirement written again: adding it would
+        // leave two contradicting copies in the spec. Like the exact check above,
+        // this compares against the spec as it stands after the earlier operations,
+        // so a variant of a requirement this delta removed or renamed away is fine.
+        const nearMiss = [...nameToBlock.keys()].find((k) => foldRequirementName(k) === foldRequirementName(key));
+        if (nearMiss !== undefined) {
+            throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - "### Requirement: ${nameToBlock.get(nearMiss).name}" already exists and differs only in case or spacing; use MODIFIED with that exact header to change it, or choose a distinct name`);
+        }
         nameToBlock.set(key, add);
         addedApplied++;
     }
@@ -1011,15 +1061,36 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
 /** Blank out `<!-- ... -->` spans, preserving line count so indices stay aligned. */
 function maskHtmlComments(content) {
     const blank = (text) => text.replace(/[^\n]/g, ' ');
-    // `--!>` is a comment terminator as well as `-->`.
-    const masked = content.replace(/<!--[\s\S]*?--!?>/g, blank);
-    // A comment that is never closed runs to end of file, so everything after it
-    // is commented out too. Without this an unterminated `<!--` above a
-    // `## Purpose` left the commented-out header looking real (#1413).
-    const unterminated = masked.indexOf('<!--');
-    if (unterminated === -1)
-        return masked;
-    return masked.slice(0, unterminated) + blank(masked.slice(unterminated));
+    // Linear scan: every character is visited once. A `/<!--[\s\S]*?--!?>/g`
+    // replace re-scans to end of file from every `<!--`, which is quadratic on a
+    // spec dense in comment openers.
+    let out = '';
+    let index = 0;
+    for (;;) {
+        const open = content.indexOf('<!--', index);
+        if (open === -1)
+            return out + content.slice(index);
+        out += content.slice(index, open);
+        // `--!>` is a comment terminator as well as `-->`.
+        let close = -1;
+        for (let i = open + 4; i < content.length; i++) {
+            if (content.startsWith('-->', i)) {
+                close = i + 3;
+                break;
+            }
+            if (content.startsWith('--!>', i)) {
+                close = i + 4;
+                break;
+            }
+        }
+        // A comment that is never closed runs to end of file, so everything after
+        // it is commented out too. Without this an unterminated `<!--` above a
+        // `## Purpose` left the commented-out header looking real (#1413).
+        if (close === -1)
+            return out + blank(content.slice(open));
+        out += blank(content.slice(open, close));
+        index = close;
+    }
 }
 /**
  * Read the body of a `## Purpose` section, ignoring markdown that only appears

package/dist/core/store/git.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Bounds every read-only git probe. Without a timeout a wedged network mount, an
+ * fsmonitor daemon, or a credential/GPG prompt hangs the CLI forever; without a
+ * raised maxBuffer a very large dirty tree makes `git status --porcelain` throw
+ * ENOBUFS, which the probes below would otherwise report as "no git facts".
+ * A probe writes nothing, so a hard kill is safe.
+ */
+export declare const GIT_EXEC_OPTIONS: {
+    readonly encoding: "utf8";
+    readonly timeout: 15000;
+    readonly killSignal: "SIGKILL";
+    readonly maxBuffer: number;
+};
+/**
+ * Writes get their own bounds, and deliberately NOT SIGKILL: git traps SIGTERM
+ * to remove `.git/index.lock` on its way out, and a signal it cannot catch
+ * leaves that lock behind - every later git command in the user's store then
+ * fails with "Another git process seems to be running", including the
+ * best-effort unstage below. The timeout is also far longer, because a signed
+ * commit can legitimately sit waiting on pinentry or a hardware key.
+ */
+export declare const GIT_WRITE_EXEC_OPTIONS: {
+    readonly encoding: "utf8";
+    readonly timeout: 120000;
+    readonly maxBuffer: number;
+};
 export declare function isGitRepositoryAtRoot(storeRoot: string): Promise<boolean>;
 export declare function initGitRepository(storeRoot: string): Promise<boolean>;
 /**
@@ -11,6 +37,13 @@ export declare function assertGitCommitIdentity(probeCwd: string): Promise<void>
  * Pathspecs may be files or directories.
  */
 export declare function commitStoreFiles(storeRoot: string, id: string, pathspecs: string[]): Promise<boolean>;
+/**
+ * A probe that hit a resource limit rather than an ordinary Git answer: the
+ * command was killed by the timeout above, or its output exceeded maxBuffer.
+ * Both produce the same `null` as "not a repository", so without this the CLI
+ * would quietly stop reporting facts it is capable of reporting.
+ */
+export declare function isProbeResourceFailure(error: unknown): boolean;
 export declare function gitHasCommits(storeRoot: string): Promise<boolean | null>;
 export declare function gitHasUncommittedChanges(storeRoot: string): Promise<boolean | null>;
 export declare function gitHasRemote(storeRoot: string): Promise<boolean | null>;