@fission-ai/openspec 1.13.0 → 1.13.1

package/dist/core/templates/workflows/verify-change.js

@@ -1,12 +1,15 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
 export function getVerifyChangeSkillTemplate() {
     return {
         name: 'openspec-verify-change',
-        description: 'Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.',
+        description: 'Verify implementation matches OpenSpec change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving. Also use when the user says "openspec verify" or "opsx verify".',
         instructions: `Verify that an implementation matches the change artifacts (specs, tasks, design).
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -54,7 +57,9 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Task Completion**:
    - If \`contextFiles.tasks\` exists, read every file path in it
-   - Parse checkboxes: \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
+   - Parse checkboxes: complete means the box holds only \`x\`/\`X\`, ignoring
+     spacing (\`- [ x]\` is complete); every other marker is incomplete
+     (\`- [ ]\`, \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
    - Count complete vs total tasks
    - If incomplete tasks exist:
      - Add CRITICAL issue for each incomplete task
@@ -181,6 +186,8 @@ export function getOpsxVerifyCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name after \`/opsx:verify\` (e.g., \`/opsx:verify add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -228,7 +235,9 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Task Completion**:
    - If \`contextFiles.tasks\` exists, read every file path in it
-   - Parse checkboxes: \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
+   - Parse checkboxes: complete means the box holds only \`x\`/\`X\`, ignoring
+     spacing (\`- [ x]\` is complete); every other marker is incomplete
+     (\`- [ ]\`, \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
    - Count complete vs total tasks
    - If incomplete tasks exist:
      - Add CRITICAL issue for each incomplete task

package/dist/core/update.d.ts

@@ -29,6 +29,18 @@ export declare class UpdateCommand {
      */
     execute(projectPath: string): Promise<void>;
     private syncCopilotCloudFiles;
+    /**
+     * Tools whose SKILL.md bodies no longer match what this CLI generates.
+     *
+     * Skill freshness was decided solely by the `generatedBy:` line, so a body
+     * edited after generation — a "helpful" PR touching `.claude/skills/**`, a
+     * dotfile sync, another agent — left `update` reporting the install healthy.
+     * Command files never had that gap: `areCommandFilesUpToDate` content-
+     * compares them, and the same comparison belongs on the higher-authority
+     * surface. A missing skill file is left to the profile-sync check, which
+     * already knows what a partial install means.
+     */
+    private findToolsWithDriftedSkills;
     /**
      * Display message when all tools are up to date.
      */

package/dist/core/update.js

@@ -13,7 +13,7 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
+import { getToolSkillStatus, getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, formatIdeRestart, } from './shared/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, omitToolLegacyArtifacts, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
@@ -27,6 +27,14 @@ import { resolveSharedSkillWriters, writeSharedSkillTarget, } from './shared-ski
 import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
+/**
+ * Checkout artifacts that are not real content drift: a UTF-8 BOM and the CRLF
+ * line endings a Windows clone with `core.autocrlf` reintroduces on every
+ * checkout of committed generated files.
+ */
+function normalizeGeneratedFile(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
 /**
  * Scans installed workflow artifacts (skills and managed commands) across all configured tools.
  * Returns the union of detected workflow IDs that match ALL_WORKFLOWS.
@@ -120,9 +128,11 @@ export class UpdateCommand {
         })
             .map((s) => s.toolId);
         const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools);
+        const toolsWithDriftedSkills = this.findToolsWithDriftedSkills(resolvedProjectPath, configuredTools, delivery, (toolId) => legacyWorkflowOverrides[toolId] ?? desiredWorkflows);
         const toolsToUpdateSet = new Set([
             ...toolsNeedingVersionUpdate,
             ...toolsNeedingConfigSync,
+            ...toolsWithDriftedSkills,
         ]);
         const toolsUpToDate = toolStatuses.filter((s) => !toolsToUpdateSet.has(s.toolId));
         if (!this.force && toolsToUpdateSet.size === 0 && newlyConfiguredTools.length === 0) {
@@ -146,7 +156,7 @@ export class UpdateCommand {
             console.log('No additional refresh needed after legacy migration.');
         }
         else {
-            this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate);
+            this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate, new Set(toolsWithDriftedSkills));
         }
         console.log();
         // 9. Determine what to generate based on delivery
@@ -375,6 +385,45 @@ export class UpdateCommand {
             console.warn(`Warning: failed to sync Copilot cloud agent files: ${message}`);
         }
     }
+    /**
+     * Tools whose SKILL.md bodies no longer match what this CLI generates.
+     *
+     * Skill freshness was decided solely by the `generatedBy:` line, so a body
+     * edited after generation — a "helpful" PR touching `.claude/skills/**`, a
+     * dotfile sync, another agent — left `update` reporting the install healthy.
+     * Command files never had that gap: `areCommandFilesUpToDate` content-
+     * compares them, and the same comparison belongs on the higher-authority
+     * surface. A missing skill file is left to the profile-sync check, which
+     * already knows what a partial install means.
+     */
+    findToolsWithDriftedSkills(projectPath, toolIds, delivery, workflowsForTool) {
+        return toolIds.filter((toolId) => {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (!tool || !toolSupportsSkills(tool))
+                return false;
+            if (!shouldGenerateSkillsForTool(tool.value, delivery))
+                return false;
+            // A shared skills root is generated with its owner's transformer, so
+            // only the owner may compare it. getToolSkillStatus settles ownership.
+            if (!getToolSkillStatus(projectPath, tool.value).configured)
+                return false;
+            const skillsDir = resolveToolSkillsDir(projectPath, tool);
+            const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+            return getSkillTemplates(workflowsForTool(toolId)).some(({ template, dirName }) => {
+                const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
+                if (!fs.existsSync(skillFile))
+                    return false;
+                try {
+                    const existing = fs.readFileSync(skillFile, 'utf-8');
+                    const generated = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                    return normalizeGeneratedFile(existing) !== normalizeGeneratedFile(generated);
+                }
+                catch {
+                    return true;
+                }
+            });
+        });
+    }
     /**
      * Display message when all tools are up to date.
      */
@@ -388,13 +437,18 @@ export class UpdateCommand {
     /**
      * Display the update plan showing which tools need updating.
      */
-    displayUpdatePlan(toolsToUpdate, statusByTool, upToDate) {
+    displayUpdatePlan(toolsToUpdate, statusByTool, upToDate, driftedSkills = new Set()) {
         const updates = toolsToUpdate.map((toolId) => {
             const status = statusByTool.get(toolId);
             if (status?.needsUpdate) {
                 const fromVersion = status.generatedByVersion ?? 'unknown';
                 return `${status.toolId} (${fromVersion} → ${OPENSPEC_VERSION})`;
             }
+            // Say why: a user who edited a SKILL.md on purpose is owed the reason
+            // their edit is about to be overwritten.
+            if (driftedSkills.has(toolId)) {
+                return `${toolId} (skill files differ from the generated content)`;
+            }
             return `${toolId} (config sync)`;
         });
         console.log(`Updating ${toolsToUpdate.length} tool(s): ${updates.join(', ')}`);
@@ -826,6 +880,7 @@ export class UpdateCommand {
                 return {
                     name: tool?.name || toolId,
                     value: toolId,
+                    searchAliases: tool?.searchAliases,
                     configured: false,
                     preSelected: true, // Pre-select all detected legacy tools
                 };

package/dist/core/validation/task-checkboxes.d.ts

@@ -0,0 +1,34 @@
+export interface TaskCheckboxDocument {
+    path: string;
+    content: string;
+}
+export interface TaskCheckboxIssue {
+    path: string;
+    line: number;
+    message: string;
+}
+/**
+ * Reports tracked task files that list work as plain bullets or numbered items
+ * instead of checkboxes (#354).
+ *
+ * Progress counts checkboxes and nothing else, so a tasks file written as a
+ * bare list is worse than an empty one: `openspec list` prints "No tasks",
+ * `openspec status` treats the change as having no work left, and
+ * `openspec archive` has no incomplete task to warn about. The file looks
+ * finished to the tool and unfinished to the reader.
+ *
+ * Reported only when the change's *whole* tracked set has zero checkboxes.
+ * One nested tasks file of prose beside a real checklist is not the failure
+ * this catches, and a change that is mid-authoring keeps its progress the
+ * moment a single checkbox exists.
+ *
+ * The scan for the offending line looks at rendered content only: fenced
+ * blocks, HTML comments, YAML front matter and top-level indented code are
+ * skipped. Every one of those
+ * exclusions can only *silence* a warning, never drop a real task — that is the
+ * opposite trade from the task parser, where fence awareness would hide work
+ * that `archive` must still refuse, and it is why the parser stays literal
+ * while this scan does not.
+ */
+export declare function findMissingTaskCheckboxIssues(documents: readonly TaskCheckboxDocument[]): TaskCheckboxIssue[];
+//# sourceMappingURL=task-checkboxes.d.ts.map

package/dist/core/validation/task-checkboxes.js

@@ -0,0 +1,181 @@
+import { parseTaskLines } from '../../utils/task-progress.js';
+/**
+ * A list item that carries text but no checkbox: `- item`, `* item`, `+ item`,
+ * `1. item`, `1) item`. Checkbox lines match this too, so callers must rule the
+ * document set out on checkbox count first.
+ *
+ * Matches at any indent; the caller decides how deep is too deep. See
+ * `CODE_BLOCK_COLUMN`.
+ *
+ * A thematic break (`---`, `***`, `- - -`) is not a list item: the run has no
+ * text after it, and this pattern requires a non-space character. `* * *` is
+ * the one break spelled like a list of `*` items, and it is accepted as a list
+ * item rather than special-cased, because a file whose only list-shaped line is
+ * a horizontal rule still has zero tasks — the warning stays true, it just
+ * points at an odd line.
+ *
+ * An ordered marker runs at most nine digits, as CommonMark and the scenario
+ * bullet pattern in `specs-apply.ts` both require.
+ */
+const LIST_ITEM = /^\s*(?:[-*+]|\d{1,9}[.)])\s+\S/;
+/**
+ * The indent at which a top-level line stops being content and becomes an
+ * indented code block, per CommonMark.
+ *
+ * The fence logic already treats four spaces as code; the list scan did not,
+ * so a sample of terminal output written as `    - example output` was
+ * reported as an uncheckboxed task list, and under `--strict` that false
+ * positive failed validation on a correct file.
+ *
+ * Genuine nested lists survive the cut, because this scan reports the *first*
+ * list item it finds and a nested item always sits under a shallower parent.
+ * That parent is what gets reported, exactly as before. A list-shaped line
+ * four columns deep with no shallower item above it is not nested under
+ * anything, which is precisely what makes it code.
+ */
+const CODE_BLOCK_COLUMN = 4;
+/** Leading whitespace of a line in visual columns, a tab counting as four. */
+function indentColumns(line) {
+    let column = 0;
+    for (const char of line) {
+        if (char === ' ')
+            column += 1;
+        else if (char === '\t')
+            column += CODE_BLOCK_COLUMN - (column % CODE_BLOCK_COLUMN);
+        else
+            break;
+    }
+    return column;
+}
+/**
+ * A fenced block delimiter: a run of three or more backticks or tildes, plus
+ * whatever follows it on the line (an info string on an opener, nothing on a
+ * valid closer).
+ *
+ * Indented by at most three spaces, as CommonMark requires: at four, the line is
+ * an indented code block rather than a fence, and treating it as an opener would
+ * leave the scan inside a block that never began and hide every list below it.
+ *
+ * Deliberately unanchored at the end: `.` does not match `\r`, so `(.*)$` would
+ * fail on every line of a CRLF file and blind the scan to fences entirely.
+ */
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)/;
+/**
+ * The YAML front-matter delimiter: exactly three dashes. A longer run is a
+ * thematic break, so `----` must not open a block that swallows the list under
+ * it until the next `---`.
+ */
+const FRONT_MATTER = /^-{3}\s*$/;
+const COMMENT_OPEN = '<!--';
+const COMMENT_CLOSE = '-->';
+/**
+ * Reports tracked task files that list work as plain bullets or numbered items
+ * instead of checkboxes (#354).
+ *
+ * Progress counts checkboxes and nothing else, so a tasks file written as a
+ * bare list is worse than an empty one: `openspec list` prints "No tasks",
+ * `openspec status` treats the change as having no work left, and
+ * `openspec archive` has no incomplete task to warn about. The file looks
+ * finished to the tool and unfinished to the reader.
+ *
+ * Reported only when the change's *whole* tracked set has zero checkboxes.
+ * One nested tasks file of prose beside a real checklist is not the failure
+ * this catches, and a change that is mid-authoring keeps its progress the
+ * moment a single checkbox exists.
+ *
+ * The scan for the offending line looks at rendered content only: fenced
+ * blocks, HTML comments, YAML front matter and top-level indented code are
+ * skipped. Every one of those
+ * exclusions can only *silence* a warning, never drop a real task — that is the
+ * opposite trade from the task parser, where fence awareness would hide work
+ * that `archive` must still refuse, and it is why the parser stays literal
+ * while this scan does not.
+ */
+export function findMissingTaskCheckboxIssues(documents) {
+    if (documents.length === 0)
+        return [];
+    if (documents.some((document) => parseTaskLines(document.content).length > 0))
+        return [];
+    const issues = [];
+    for (const document of documents) {
+        const line = findFirstListItemLine(document.content);
+        if (line === undefined)
+            continue;
+        issues.push({
+            path: document.path,
+            line,
+            message: 'This change counts as 0 tasks: no line in its tracked task files is a checkbox, ' +
+                'so "openspec list" and "openspec status" report no work and "openspec archive" ' +
+                'has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".',
+        });
+    }
+    return issues;
+}
+/** 1-based line of the first list item in rendered content, if any. */
+function findFirstListItemLine(content) {
+    const lines = content.split('\n');
+    let openFence;
+    let inComment = false;
+    let index = skipFrontMatter(lines);
+    for (; index < lines.length; index++) {
+        const line = lines[index];
+        if (inComment) {
+            if (line.includes(COMMENT_CLOSE))
+                inComment = false;
+            continue;
+        }
+        const fence = line.match(FENCE);
+        if (fence) {
+            const marker = fence[1][0];
+            const length = fence[1].length;
+            if (openFence === undefined) {
+                openFence = { marker, length };
+            }
+            else if (marker === openFence.marker &&
+                length >= openFence.length &&
+                fence[2].trim() === '') {
+                // CommonMark: a closer matches its opener's character, runs at least as
+                // long, and carries no info string. A shorter or annotated run inside a
+                // block is content, so a ```` ``` ```` sample nested in a ```` ```` ````
+                // block does not end the block early and expose its bullets.
+                openFence = undefined;
+            }
+            continue;
+        }
+        if (openFence !== undefined)
+            continue;
+        // Only a comment that opens the line hides it. `- [ ] 1.1 do it <!-- note`
+        // is a task line first, and the template's own `## 1. <!-- Task Group -->`
+        // must not swallow the checklist that follows it.
+        if (line.trimStart().startsWith(COMMENT_OPEN)) {
+            if (!line.includes(COMMENT_CLOSE, line.indexOf(COMMENT_OPEN) + COMMENT_OPEN.length)) {
+                inComment = true;
+            }
+            continue;
+        }
+        if (LIST_ITEM.test(line) && indentColumns(line) < CODE_BLOCK_COLUMN)
+            return index + 1;
+    }
+    return undefined;
+}
+/**
+ * Index of the first line after a YAML front-matter block, or 0 when the
+ * document does not open with one. A list under `tags:` is metadata about the
+ * file, never the work it tracks, and pointing a "write checkboxes" warning at
+ * it would name the wrong line.
+ */
+function skipFrontMatter(lines) {
+    // A UTF-8 BOM, prepended by Windows editors and PowerShell redirects, would
+    // otherwise hide the opener and expose a `tags:` list to the scan.
+    if (lines.length === 0 || !FRONT_MATTER.test(lines[0].replace(/^/, '').trimEnd())) {
+        return 0;
+    }
+    for (let index = 1; index < lines.length; index++) {
+        if (FRONT_MATTER.test(lines[index].trimEnd()))
+            return index + 1;
+    }
+    // An unterminated opener is a thematic break, not front matter: rewinding to
+    // the top keeps every list in the document visible to the scan.
+    return 0;
+}
+//# sourceMappingURL=task-checkboxes.js.map

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

@@ -29,7 +29,53 @@ export declare class Validator {
         mainSpecsDir?: string;
         projectRoot?: string;
     }): Promise<ValidationReport>;
-    private collectTaskNumberingIssues;
+    /**
+     * Lints the change's task files.
+     *
+     * Two checks with deliberately different reach. Checkbox formatting is read
+     * from whatever the change's own schema declares as its tracked task output,
+     * because every schema's progress, apply and archive behavior is computed by
+     * counting checkboxes in exactly those files. Numbering stays scoped to the
+     * built-in `spec-driven` schema, whose template is the one that numbers tasks
+     * in the first place.
+     *
+     * The checkbox check never falls back to a bare top-level `tasks.md`: a file
+     * no artifact declares is not a tracked task list, and warning about its
+     * formatting would be a guess about a file the tool does not read.
+     */
+    private collectTaskFileIssues;
+    /**
+     * Reads task files into change-relative documents, counting the ones that
+     * exist but could not be read. A file that is simply absent is not counted:
+     * the resolver only returns files it found, so the remaining read failures
+     * are permissions and I/O, and a check that reasons over the whole set needs
+     * to know its evidence was incomplete.
+     */
+    private readTaskDocuments;
+    /**
+     * Names a task file relative to its change, POSIX-separated.
+     *
+     * Both sides are canonicalized first. `resolveArtifactOutputs` hands back real
+     * paths, while `changeDir` carries whatever spelling the caller resolved, and
+     * the two can differ without being apart: on Windows a short 8.3 alias
+     * (`RUNNER~1`) against its expanded form turned `tasks.md` into a
+     * `../../../..`-prefixed absolute path in the report, and a symlinked project
+     * directory does the same elsewhere. Canonicalizing recovers the real
+     * relationship. The Windows CI job is the regression guard — the mismatch
+     * cannot be staged on POSIX, where the spawned CLI's `process.cwd()` is
+     * already physical.
+     *
+     * A path that still escapes would be a resolver bug rather than a spelling
+     * difference, but the report must never leak an absolute filesystem path, so
+     * the file name stands in.
+     */
+    private taskDocumentPath;
+    /**
+     * True when the change resolves to the package's own `spec-driven` schema. A
+     * project schema that merely reuses the name is not it, so checks written
+     * against the built-in template never fire on someone else's task format.
+     */
+    private usesBuiltInSpecDrivenSchema;
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
      * still carries. Uses the same comparison archive applies, so validate can
@@ -72,6 +118,12 @@ export declare class Validator {
      */
     private buildMissingShallOrMustMessage;
     private countScenarios;
+    /**
+     * Why a requirement with a visible scenario header still has no scenario:
+     * the header has no body, and the spec path archive validates against does
+     * not count it. Empty when the block has no bare scenario header.
+     */
+    private emptyScenarioHint;
     private formatSectionList;
 }
 //# sourceMappingURL=validator.d.ts.map