@fission-ai/openspec 1.12.0 → 1.13.1

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;
     }
@@ -253,7 +259,34 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion, option
             generatedByVersion = currentVersion;
         }
     }
-    const needsUpdate = configured && (generatedByVersion === null || generatedByVersion !== currentVersion);
+    // 3. A version marker in a skill file only proves the SKILL files came from
+    //    this CLI. It says nothing about the command files written beside them,
+    //    which a user may have hand-edited or a partial write may have truncated.
+    //    Without this, `update` answered "all tools up to date" while a damaged
+    //    command file sat on disk, repairable only by knowing to pass --force.
+    //    The content comparison already exists; it was simply never consulted
+    //    once a skill file supplied a version.
+    //
+    //    Scoped to tools that have BOTH, so the commands-only path above keeps
+    //    its exact behaviour, and skipped when the delivery mode generates no
+    //    commands for this tool - there would be nothing to compare against, and
+    //    `areCommandFilesUpToDate` reports an empty command set as "not current".
+    let commandsDrifted = false;
+    if (skillConfigured && commandConfigured) {
+        let generatesCommands = true;
+        try {
+            generatesCommands = shouldGenerateCommandsForTool(toolId, getGlobalConfig().delivery ?? 'both');
+        }
+        catch {
+            generatesCommands = true;
+        }
+        commandsDrifted =
+            generatesCommands && !areCommandFilesUpToDate(projectRoot, toolId, options);
+    }
+    const needsUpdate = configured &&
+        (generatedByVersion === null ||
+            generatedByVersion !== currentVersion ||
+            commandsDrifted);
     return {
         toolId,
         toolName: tool.name,