@fission-ai/openspec 1.10.0 → 1.12.0

package/dist/core/validation/purpose-placeholder.js

@@ -0,0 +1,117 @@
+import { buildCodeFenceMask } from '../parsers/code-fence.js';
+import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX } from './constants.js';
+/**
+ * A `TBD` or `TODO` opening the Purpose. The lookahead keeps it off a longer
+ * word that merely begins with those letters, like "TBDs" or "TODOs", while
+ * still allowing the punctuation a marker is usually written with: `TODO:`,
+ * `TBD -`. It rejects any letter, digit or combining mark rather than only the
+ * ASCII ones `\b` knows about, because a Purpose is prose and prose is not
+ * always written in Latin script - `TBD` followed by an Arabic-Indic digit is
+ * as much a longer word as `TBDs` is.
+ */
+const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
+const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
+const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
+/**
+ * The lines of `text` that sit outside a fenced code block, with line endings
+ * normalised first.
+ *
+ * `buildCodeFenceMask` is the masker the requirement and structure parsers
+ * already share, and its own reason for existing is that a second, private
+ * notion of what a fence is drifts from the first. This check reads Markdown
+ * for the same purpose they do, so it reads fences the same way they do.
+ */
+function unfencedLines(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    return lines.filter((_, index) => !fenced[index]);
+}
+/**
+ * True when the text carries the sentence archive writes. Matched as its two
+ * fixed halves in order, because the change name between them varies - so the
+ * check follows the writer's own definition instead of a second copy of it.
+ */
+function generatedPlaceholderPrefixIndex(text) {
+    let suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX);
+    while (suffixAt !== -1) {
+        // Use the closest prefix before this suffix. An authored explanation can
+        // mention the prefix above the real placeholder; choosing the first prefix
+        // would then point the diagnostic at the explanation instead of the text
+        // the user needs to replace.
+        const prefixAt = text.lastIndexOf(PURPOSE_PLACEHOLDER_PREFIX, suffixAt);
+        if (prefixAt !== -1)
+            return prefixAt;
+        suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX, suffixAt + 1);
+    }
+    return undefined;
+}
+/**
+ * Reports the Purpose of a main spec as an unwritten placeholder, or null when
+ * it reads as authored content.
+ *
+ * An empty Purpose is not reported here - `SPEC_PURPOSE_EMPTY` already covers
+ * it, and reporting both would put two findings on one line. That falls out of
+ * the two rules rather than needing a case of its own.
+ */
+export function findPurposePlaceholderIssue(overview, content) {
+    // An empty Purpose needs no branch of its own: neither rule matches empty
+    // text, so it falls through to null on the line below. An early return for it
+    // would be a guard no test could hold, which is worse than none. A Purpose
+    // that is nothing but a fenced block reduces to the same empty text here, and
+    // is left to the brevity and empty-Purpose rules for the same reason.
+    const prose = unfencedLines(overview).join('\n').trim();
+    const leading = LEADING_MARKER.test(prose);
+    if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
+        return null;
+    // Which rule matched decides where the placeholder is, so the locator is told.
+    // When both match the leading marker wins: it sits at or above the generated
+    // sentence, and the earliest marker is the one a reader scanning down meets.
+    return { line: content === undefined ? undefined : findPlaceholderLine(content, leading) };
+}
+/**
+ * The line inside the `## Purpose` section carrying the placeholder, so the
+ * warning points at the text to replace rather than at the file.
+ *
+ * Which line that is depends on the rule that matched. A leading marker is the
+ * section's first non-blank line by definition. The generated sentence is not:
+ * it can follow prose somebody wrote, and naming the first non-blank line then
+ * points at that prose - a line the reader can see is fine, which reads as the
+ * check being wrong rather than the Purpose being unwritten.
+ *
+ * Fenced lines are skipped on the way, for the reason detection skips them, and
+ * so a `## Requirements` quoted inside a fence cannot end the section early.
+ *
+ * Undefined when the placeholder cannot be located - no section header, or a
+ * generated sentence no single line carries. The caller then reports the finding
+ * without a line rather than with a guessed one, since a wrong line number is
+ * worse than none.
+ *
+ * Line endings are normalised first, so the same spec reports the same line
+ * whether it was saved on Windows or on macOS/Linux.
+ */
+function findPlaceholderLine(content, leading) {
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    const headerIndex = lines.findIndex((line, index) => !fenced[index] && PURPOSE_HEADER.test(line));
+    if (headerIndex === -1)
+        return undefined;
+    const purposeLines = [];
+    for (let i = headerIndex + 1; i < lines.length; i++) {
+        if (fenced[i])
+            continue;
+        if (TOP_LEVEL_HEADER.test(lines[i]))
+            break;
+        if (leading && lines[i].trim())
+            return i + 1;
+        purposeLines.push({ line: i + 1, text: lines[i] });
+    }
+    if (leading)
+        return undefined;
+    const purpose = purposeLines.map(({ text }) => text).join('\n');
+    const prefixAt = generatedPlaceholderPrefixIndex(purpose);
+    if (prefixAt === undefined)
+        return undefined;
+    const lineOffset = purpose.slice(0, prefixAt).split('\n').length - 1;
+    return purposeLines[lineOffset]?.line;
+}
+//# sourceMappingURL=purpose-placeholder.js.map

package/dist/core/validation/validator.d.ts

@@ -19,9 +19,10 @@ export declare class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
-     * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
-     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * against the current main specs for scenario loss (#1477), and merge
+     * conflicts are reported as INFO without changing the verdict (#1112).
+     * When `options.projectRoot` is given, the schema's tracked task files are
+     * checked for ambiguous numbering (#1520). Omitting either
      * option keeps existing library and archive callers behaving as before.
      */
     validateChangeDeltaSpecs(changeDir: string, options?: {
@@ -47,6 +48,14 @@ export declare class Validator {
     private applyChangeRules;
     private enrichTopLevelError;
     private extractNameFromPath;
+    /**
+     * Dry-run archive's merge builder without writing its result. Reusing the
+     * builder preserves its already-synced delta rules instead of duplicating them.
+     * INFO leaves the verdict unchanged: a missing target can be a typo or a
+     * requirement introduced by a sibling change that has not archived yet.
+     * This does not run archive's later merged-spec validation or retirement checks.
+     */
+    private findArchiveBlockers;
     private createReport;
     isValid(report: ValidationReport): boolean;
     private extractRequirementText;

package/dist/core/validation/validator.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
+import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
 import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
@@ -12,6 +13,7 @@ import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.j
 import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
+import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
@@ -111,9 +113,10 @@ export class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
-     * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
-     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * against the current main specs for scenario loss (#1477), and merge
+     * conflicts are reported as INFO without changing the verdict (#1112).
+     * When `options.projectRoot` is given, the schema's tracked task files are
+     * checked for ambiguous numbering (#1520). Omitting either
      * option keeps existing library and archive callers behaving as before.
      */
     async validateChangeDeltaSpecs(changeDir, options = {}) {
@@ -329,6 +332,20 @@ export class Validator {
                     }
                 }
             }
+            // Reuse archive's merge builder to report conflicts with the main specs.
+            // Keep structural errors and scenario loss in their existing diagnostics.
+            if (options.mainSpecsDir) {
+                issues.push(...(await this.findArchiveBlockers(changeDir, options.mainSpecsDir, [
+                    ...issues.filter((issue) => issue.level === 'ERROR').map((issue) => issue.path),
+                    // Collected in the loop above but not turned into issues until
+                    // after this try block, so they are invisible to the filter. A
+                    // delta with no parsed sections has nothing for the merge to
+                    // apply, which it reports as a failure of its own - on top of the
+                    // error that actually names the mistake.
+                    ...missingHeaderSpecs,
+                    ...emptySectionSpecs.map((spec) => spec.path),
+                ])));
+            }
         }
         catch (error) {
             // A missing specs dir (or a stray `specs` file) means no deltas;
@@ -557,7 +574,21 @@ export class Validator {
                 message: structuralIssue.message,
             });
         }
-        if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+        // The placeholder is longer than MIN_PURPOSE_LENGTH, so the brevity check
+        // below cannot reach it; it is reported on its own terms instead. Checked
+        // first because a hand-written "TBD" is both a placeholder and too brief,
+        // and only one of those two tells the author what to do. (A "TODO" opening
+        // the Purpose reads the same way, so it is the same finding.)
+        const placeholder = findPurposePlaceholderIssue(spec.overview, content);
+        if (placeholder) {
+            issues.push({
+                level: 'WARNING',
+                path: 'overview',
+                line: placeholder.line,
+                message: VALIDATION_MESSAGES.PURPOSE_IS_PLACEHOLDER,
+            });
+        }
+        else if (spec.overview.length < MIN_PURPOSE_LENGTH) {
             issues.push({
                 level: 'WARNING',
                 path: 'overview',
@@ -656,6 +687,61 @@ export class Validator {
         const dotIndex = fileName.lastIndexOf('.');
         return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
     }
+    /**
+     * Dry-run archive's merge builder without writing its result. Reusing the
+     * builder preserves its already-synced delta rules instead of duplicating them.
+     * INFO leaves the verdict unchanged: a missing target can be a typo or a
+     * requirement introduced by a sibling change that has not archived yet.
+     * This does not run archive's later merged-spec validation or retirement checks.
+     */
+    async findArchiveBlockers(changeDir, mainSpecsDir, alreadyReportedPaths) {
+        const alreadyReported = new Set(alreadyReportedPaths);
+        // Only ever reaches a generated skeleton's placeholder Purpose, which this
+        // dry run discards.
+        const changeName = path.basename(changeDir);
+        const issues = [];
+        let updates;
+        try {
+            updates = await findSpecUpdates(changeDir, mainSpecsDir);
+        }
+        catch (error) {
+            // An incomplete advisory check must not discard the validation report.
+            // Source discovery already ran above; archive retains its own path guards.
+            return [{
+                    level: 'INFO',
+                    path: 'specs',
+                    message: `Could not check archive merge conflicts: ${error instanceof Error ? error.message : String(error)}`,
+                }];
+        }
+        for (const update of updates) {
+            // discoverSpecFiles builds both this id and the entryPath the checks
+            // above report under, from the same walk.
+            const entryPath = FileSystemUtils.toPosixPath(`${update.id}/spec.md`);
+            // A delta those checks already rejected would be reported twice, the
+            // second time in archive's wording rather than the wording that names
+            // the actual mistake.
+            if (alreadyReported.has(entryPath))
+                continue;
+            try {
+                await buildUpdatedSpec(update, changeName, { silent: true });
+            }
+            catch (error) {
+                // Only the thrown preconditions, which carry no errno. A filesystem
+                // error says nothing about whether the delta applies, and `validate
+                // --all` reads six changes at once, so a transient EMFILE would report
+                // a collision that is not there - the same reason the scenario-loss
+                // check above reads only the codes that mean the file is unusable.
+                if (error?.code !== undefined)
+                    continue;
+                issues.push({
+                    level: 'INFO',
+                    path: entryPath,
+                    message: `Archive would refuse this delta: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+        return issues;
+    }
     createReport(issues) {
         const errors = issues.filter(i => i.level === 'ERROR').length;
         const warnings = issues.filter(i => i.level === 'WARNING').length;

package/dist/utils/command-references.js

@@ -60,15 +60,14 @@ const SKILL_INVOCATION_PREFIX = {
     codex: '$',
 };
 /**
- * Tools that have no slash-command surface at all: skills are matched
- * automatically or invoked by natural-language prompts, never by typing a
- * `/<name>` command. Rovo Dev CLI is such a tool — `/skills` only manages
- * skills, and any `/openspec-*` form would be a dead command (see
- * docs/supported-tools.md). References for these tools are spelled as prose
- * ("the openspec-propose skill") so generated content never tells the user to
- * type a command their CLI does not register.
+ * Tools with no documented slash invocation for skills: use automatic
+ * matching or natural-language prompts instead. SourceCraft Code Assistant
+ * supports separate command files, but its skills use description matching.
+ * Rovo Dev's `/skills` only manages skills (see docs/supported-tools.md).
+ * Skill references for these tools are spelled as prose ("the openspec-propose
+ * skill") so skills-only delivery does not advertise unregistered commands.
  */
-const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev']);
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev', 'codeassistant']);
 /**
  * Whether a tool references skills by natural language rather than a slash
  * command (see NATURAL_LANGUAGE_SKILL_TOOLS).

package/dist/utils/requirement-diff.d.ts

@@ -0,0 +1,42 @@
+/** A main-spec requirement block, and how its header matched the delta's. */
+export interface MatchedRequirementBlock {
+    raw: string;
+    /** The header name as the main spec spells it. */
+    name: string;
+    /**
+     * False when the two headers differ only in case or interior spacing. Archive
+     * matches names exactly, so an inexact match is a real problem to report even
+     * though the diff below it is still the one the author meant.
+     */
+    exact: boolean;
+}
+/**
+ * Find the raw markdown block for a requirement by name in a spec file.
+ *
+ * Delegates to extractRequirementsSection() which already handles code fences,
+ * section boundaries, and requirement header parsing. We just look up by name:
+ * exactly first, then falling back to the shared case/whitespace fold so a
+ * header that differs only in spelling still shows its diff, flagged inexact.
+ *
+ * Returns null if no requirement header matches either way.
+ */
+export declare function extractRequirementBlock(specContent: string, requirementName: string): MatchedRequirementBlock | null;
+/**
+ * Compute a unified diff between a main-spec requirement block and the delta
+ * block that replaces it. A null main block (new capability) diffs against the
+ * empty string, so every line reads as an addition.
+ *
+ * Uses structuredPatch to retain unified-diff hunk ranges while omitting the
+ * synthetic file headers, since the caller provides its own labeling.
+ */
+export declare function diffRequirementBlock(baseBlock: string | null, deltaBlock: string, label: string): string;
+/**
+ * Build a map from folded RENAMED TO name to the original main-spec name.
+ * Renames apply in source order, so a chain such as A -> B -> C maps C back to
+ * A. That is the block a later MODIFIED C replaces.
+ */
+export declare function buildRenameMap(renames: Array<{
+    from: string;
+    to: string;
+}>): Map<string, string>;
+//# sourceMappingURL=requirement-diff.d.ts.map

package/dist/utils/requirement-diff.js

@@ -0,0 +1,61 @@
+import { formatPatch, OMIT_HEADERS, structuredPatch } from 'diff';
+import { extractRequirementsSection, foldRequirementName, normalizeRequirementName, } from '../core/parsers/requirement-blocks.js';
+/**
+ * Find the raw markdown block for a requirement by name in a spec file.
+ *
+ * Delegates to extractRequirementsSection() which already handles code fences,
+ * section boundaries, and requirement header parsing. We just look up by name:
+ * exactly first, then falling back to the shared case/whitespace fold so a
+ * header that differs only in spelling still shows its diff, flagged inexact.
+ *
+ * Returns null if no requirement header matches either way.
+ */
+export function extractRequirementBlock(specContent, requirementName) {
+    const parts = extractRequirementsSection(specContent);
+    const targetName = normalizeRequirementName(requirementName);
+    const foldedTarget = foldRequirementName(targetName);
+    let folded = null;
+    for (const block of parts.bodyBlocks) {
+        const name = normalizeRequirementName(block.name);
+        if (name === targetName) {
+            return { raw: block.raw, name, exact: true };
+        }
+        if (!folded && foldRequirementName(name) === foldedTarget) {
+            folded = { raw: block.raw, name, exact: false };
+        }
+    }
+    return folded;
+}
+/**
+ * Compute a unified diff between a main-spec requirement block and the delta
+ * block that replaces it. A null main block (new capability) diffs against the
+ * empty string, so every line reads as an addition.
+ *
+ * Uses structuredPatch to retain unified-diff hunk ranges while omitting the
+ * synthetic file headers, since the caller provides its own labeling.
+ */
+export function diffRequirementBlock(baseBlock, deltaBlock, label) {
+    const base = ensureTrailingNewline(baseBlock ?? '');
+    const delta = ensureTrailingNewline(deltaBlock);
+    const patch = structuredPatch(label, label, base, delta);
+    return formatPatch(patch, OMIT_HEADERS).trimEnd();
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith('\n') ? s : s + '\n';
+}
+/**
+ * Build a map from folded RENAMED TO name to the original main-spec name.
+ * Renames apply in source order, so a chain such as A -> B -> C maps C back to
+ * A. That is the block a later MODIFIED C replaces.
+ */
+export function buildRenameMap(renames) {
+    const map = new Map();
+    for (const r of renames) {
+        const from = foldRequirementName(r.from);
+        const original = map.get(from) ?? normalizeRequirementName(r.from);
+        map.delete(from);
+        map.set(foldRequirementName(r.to), original);
+    }
+    return map;
+}
+//# sourceMappingURL=requirement-diff.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -41,8 +41,8 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.1",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
     "@vitest/ui": "^3.2.6",
     "eslint": "^10.5.0",
@@ -56,6 +56,7 @@
     "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
+    "diff": "^9.0.0",
     "cross-spawn": "7.0.6",
     "fast-glob": "^3.3.3",
     "ora": "^9.4.1",