@fission-ai/openspec 1.6.0 → 1.8.0

package/dist/utils/file-system.js

@@ -87,6 +87,76 @@ export class FileSystemUtils {
             }
         }
     }
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory, targetPath) {
+        const resolvedDirectory = path.resolve(allowedDirectory);
+        const resolvedTarget = path.resolve(targetPath);
+        if (!this.isPathWithin(resolvedDirectory, resolvedTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+        const canonicalDirectory = this.canonicalizePotentialPath(resolvedDirectory);
+        const canonicalTarget = this.canonicalizePotentialPath(resolvedTarget);
+        if (!this.isPathWithin(canonicalDirectory, canonicalTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+    }
+    static resolveProjectArtifactPath(projectPath, artifactPath) {
+        if (path.isAbsolute(artifactPath)) {
+            throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);
+        }
+        const targetPath = path.join(projectPath, artifactPath);
+        this.assertPathWithin(projectPath, targetPath);
+        return targetPath;
+    }
+    static assertProjectArtifactPath(projectPath, targetPath) {
+        this.assertPathWithin(projectPath, targetPath);
+    }
+    static isPathWithin(allowedDirectory, targetPath) {
+        const relative = path.relative(allowedDirectory, targetPath);
+        return (relative === '' ||
+            (relative !== '..' &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative)));
+    }
+    static canonicalizePotentialPath(targetPath) {
+        let existingPath = targetPath;
+        const missingSegments = [];
+        while (true) {
+            try {
+                // lstat distinguishes a missing path from a dangling symlink. A
+                // dangling link cannot be proven confined, so realpath must fail it.
+                nodeFs.lstatSync(existingPath);
+                const canonicalExisting = nodeFs.realpathSync.native(existingPath);
+                return path.resolve(canonicalExisting, ...missingSegments);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOENT') {
+                    throw error;
+                }
+                try {
+                    if (nodeFs.lstatSync(existingPath).isSymbolicLink()) {
+                        throw new Error(`Cannot verify dangling symbolic link: ${existingPath}`);
+                    }
+                }
+                catch (lstatError) {
+                    if (lstatError.code !== 'ENOENT') {
+                        throw lstatError;
+                    }
+                }
+                const parent = path.dirname(existingPath);
+                if (parent === existingPath) {
+                    throw new Error(`Cannot resolve an existing parent for ${targetPath}`);
+                }
+                missingSegments.unshift(path.basename(existingPath));
+                existingPath = parent;
+            }
+        }
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/dist/utils/index.d.ts

@@ -2,5 +2,5 @@ export { validateChangeName, createChange } from './change-utils.js';
 export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
 export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
-export { transformToHyphenCommands } from './command-references.js';
+export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -5,5 +5,5 @@ export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, valida
 // File system utilities
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 // Command reference utilities
-export { transformToHyphenCommands } from './command-references.js';
+export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/interactive.d.ts

@@ -15,4 +15,27 @@ export type InteractiveOptions = {
  */
 export declare function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean;
 export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty.
+ */
+export declare function isNonInteractivePromptError(error: unknown, value?: boolean | InteractiveOptions): boolean;
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -18,4 +18,36 @@ export function isInteractive(value) {
         return false;
     return !!process.stdin.isTTY;
 }
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty.
+ */
+export function isNonInteractivePromptError(error, value) {
+    if (!(error instanceof Error))
+        return false;
+    const failedPrompt = error.name === 'ExitPromptError' || error.message.includes('force closed the prompt');
+    if (!failedPrompt)
+        return false;
+    if (error.message.includes('SIGINT'))
+        return false;
+    return !isInteractive(value);
+}
 //# sourceMappingURL=interactive.js.map

package/dist/utils/item-discovery.d.ts

@@ -1,4 +1,23 @@
+/**
+ * Returns the ids of active changes: every directory under openspec/changes/
+ * except the archive and hidden directories.
+ *
+ * A change is resolved by its directory alone - the same rule `list`,
+ * `status`, `instructions` and `validate` use (`getAvailableChanges`).
+ * Requiring proposal.md here made `openspec show` and shell completion miss
+ * changes those commands resolve: `openspec new change <name>` scaffolds only
+ * `.openspec.yaml`, and a custom schema need not define a proposal artifact at
+ * all (#1161).
+ */
 export declare function getActiveChangeIds(root?: string): Promise<string[]>;
 export declare function getSpecIds(root?: string): Promise<string[]>;
+/**
+ * Returns the ids of archived changes: every directory under
+ * openspec/changes/archive/ except hidden directories.
+ *
+ * Resolved by directory for the same reason as `getActiveChangeIds`: a change
+ * archived from a schema without a proposal artifact has no proposal.md, and
+ * gating on it hid those entries from shell completion.
+ */
 export declare function getArchivedChangeIds(root?: string): Promise<string[]>;
 //# sourceMappingURL=item-discovery.d.ts.map

package/dist/utils/item-discovery.js

@@ -1,23 +1,25 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { discoverSpecFiles } from './spec-discovery.js';
+/**
+ * Returns the ids of active changes: every directory under openspec/changes/
+ * except the archive and hidden directories.
+ *
+ * A change is resolved by its directory alone - the same rule `list`,
+ * `status`, `instructions` and `validate` use (`getAvailableChanges`).
+ * Requiring proposal.md here made `openspec show` and shell completion miss
+ * changes those commands resolve: `openspec new change <name>` scaffolds only
+ * `.openspec.yaml`, and a custom schema need not define a proposal artifact at
+ * all (#1161).
+ */
 export async function getActiveChangeIds(root = process.cwd()) {
     const changesPath = path.join(root, 'openspec', 'changes');
     try {
         const entries = await fs.readdir(changesPath, { withFileTypes: true });
-        const result = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
-                continue;
-            const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
-            try {
-                await fs.access(proposalPath);
-                result.push(entry.name);
-            }
-            catch {
-                // skip directories without proposal.md
-            }
-        }
-        return result.sort();
+        return entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
     }
     catch {
         return [];
@@ -25,45 +27,25 @@ export async function getActiveChangeIds(root = process.cwd()) {
 }
 export async function getSpecIds(root = process.cwd()) {
     const specsPath = path.join(root, 'openspec', 'specs');
-    const result = [];
-    try {
-        const entries = await fs.readdir(specsPath, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.'))
-                continue;
-            const specFile = path.join(specsPath, entry.name, 'spec.md');
-            try {
-                await fs.access(specFile);
-                result.push(entry.name);
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-    catch {
-        // ignore
-    }
-    return result.sort();
+    const discovered = await discoverSpecFiles(specsPath);
+    return discovered.map((spec) => spec.id);
 }
+/**
+ * Returns the ids of archived changes: every directory under
+ * openspec/changes/archive/ except hidden directories.
+ *
+ * Resolved by directory for the same reason as `getActiveChangeIds`: a change
+ * archived from a schema without a proposal artifact has no proposal.md, and
+ * gating on it hid those entries from shell completion.
+ */
 export async function getArchivedChangeIds(root = process.cwd()) {
     const archivePath = path.join(root, 'openspec', 'changes', 'archive');
     try {
         const entries = await fs.readdir(archivePath, { withFileTypes: true });
-        const result = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.'))
-                continue;
-            const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
-            try {
-                await fs.access(proposalPath);
-                result.push(entry.name);
-            }
-            catch {
-                // skip directories without proposal.md
-            }
-        }
-        return result.sort();
+        return entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
     }
     catch {
         return [];

package/dist/utils/shell-detection.d.ts

@@ -12,7 +12,7 @@ export interface ShellDetectionResult {
     detected: string | undefined;
 }
 /**
- * Detects the current user's shell based on environment variables
+ * Detects the current user's shell based on the parent process and environment
  *
  * @returns Detection result with supported shell and raw detected name
  */

package/dist/utils/shell-detection.js

@@ -1,21 +1,74 @@
+import { execFileSync } from 'node:child_process';
 /**
- * Detects the current user's shell based on environment variables
+ * Map a raw shell name/path to a supported shell, if any.
+ */
+function matchSupportedShell(name) {
+    // Match the executable basename exactly so lookalikes such as `fish-lsp` or
+    // `bash-language-server` don't get mistaken for the shell itself. Login
+    // shells report a leading dash (e.g. `-zsh`), so strip it first.
+    const executable = name.trim().toLowerCase().split('/').pop()?.replace(/^-/, '');
+    if (executable === 'zsh')
+        return 'zsh';
+    if (executable === 'bash')
+        return 'bash';
+    if (executable === 'fish')
+        return 'fish';
+    return undefined;
+}
+/**
+ * Detect the interactive shell from the parent process.
+ *
+ * `process.env.SHELL` is only the login shell, so users whose interactive shell
+ * differs from it (e.g. running fish while their login shell is bash) are
+ * misdetected. Inspecting the parent process reflects the shell that actually
+ * launched openspec. POSIX-only and best-effort — any failure returns undefined
+ * so the caller falls back to `$SHELL`.
+ *
+ * @returns The supported shell running as the parent process, or undefined
+ */
+function detectShellFromParentProcess() {
+    // `ps` is POSIX-only; Windows shells are handled via PSModulePath/COMSPEC.
+    if (process.platform === 'win32') {
+        return undefined;
+    }
+    const ppid = process.ppid;
+    if (!ppid || ppid <= 1) {
+        return undefined;
+    }
+    try {
+        const comm = execFileSync('ps', ['-p', String(ppid), '-o', 'comm='], {
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+        if (!comm) {
+            return undefined;
+        }
+        // Only trust the parent process when it maps to a supported shell; an
+        // unrelated parent (node, npm, sudo, a pager) falls through to `$SHELL`.
+        return matchSupportedShell(comm);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Detects the current user's shell based on the parent process and environment
  *
  * @returns Detection result with supported shell and raw detected name
  */
 export function detectShell() {
-    // Try SHELL environment variable first (Unix-like systems)
+    // Prefer the actual running shell (parent process) over `$SHELL`, which only
+    // reflects the login shell and misses users whose interactive shell differs.
+    const parentShell = detectShellFromParentProcess();
+    if (parentShell) {
+        return { shell: parentShell, detected: parentShell };
+    }
+    // Try SHELL environment variable next (Unix-like systems)
     const shellPath = process.env.SHELL;
     if (shellPath) {
-        const shellName = shellPath.toLowerCase();
-        if (shellName.includes('zsh')) {
-            return { shell: 'zsh', detected: 'zsh' };
-        }
-        if (shellName.includes('bash')) {
-            return { shell: 'bash', detected: 'bash' };
-        }
-        if (shellName.includes('fish')) {
-            return { shell: 'fish', detected: 'fish' };
+        const supported = matchSupportedShell(shellPath);
+        if (supported) {
+            return { shell: supported, detected: supported };
         }
         // Shell detected but not supported
         // Extract shell name from path (e.g., /bin/tcsh -> tcsh)

package/dist/utils/spec-discovery.d.ts

@@ -0,0 +1,40 @@
+export interface DiscoveredSpec {
+    /** Spec id relative to the specs root, forward-slash separated on every platform (e.g. "web" or "platform/session-layout"). */
+    id: string;
+    /** Path to the spec.md file (absolute if the specs root is absolute). */
+    specFile: string;
+}
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
+ * artifact graph's globs both count it as content, so dropping it here would
+ * silently lose the delta on archive. A link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export declare function discoverSpecFiles(specsRoot: string): Promise<DiscoveredSpec[]>;
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export declare function hasAnyFileUnder(dirPath: string): Promise<boolean>;
+//# sourceMappingURL=spec-discovery.d.ts.map

package/dist/utils/spec-discovery.js

@@ -0,0 +1,115 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
+    try {
+        FileSystemUtils.assertPathWithin(specsRoot, specFile);
+    }
+    catch {
+        // Direct capability directories may intentionally be external monorepo
+        // links. In that case, confine the file to the capability itself.
+        FileSystemUtils.assertPathWithin(capabilityDir, specFile);
+    }
+}
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
+ * artifact graph's globs both count it as content, so dropping it here would
+ * silently lose the delta on archive. A link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export async function discoverSpecFiles(specsRoot) {
+    const results = [];
+    const walk = async (dir, segments) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), [...segments, entry.name]);
+            }
+            else if (entry.name === 'spec.md' && segments.length > 0) {
+                const specFile = path.join(dir, entry.name);
+                if (entry.isFile()) {
+                    assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                    results.push({ id: segments.join('/'), specFile });
+                }
+                else if (entry.isSymbolicLink()) {
+                    try {
+                        if ((await fs.stat(specFile)).isFile()) {
+                            assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                            results.push({ id: segments.join('/'), specFile });
+                        }
+                    }
+                    catch (err) {
+                        // A dangling link is not content; anything else fails loudly.
+                        if (err?.code !== 'ENOENT')
+                            throw err;
+                    }
+                }
+            }
+        }
+    };
+    await walk(specsRoot, []);
+    // Plain code-point comparison, not localeCompare: the latter follows the
+    // process's ICU locale, so ordering could vary by OS/CI. Code-point ordering
+    // guarantees the deterministic output the docstring promises.
+    return results.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export async function hasAnyFileUnder(dirPath) {
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return false;
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        if (entry.isFile() || entry.isSymbolicLink()) {
+            return true;
+        }
+        if (entry.isDirectory() && (await hasAnyFileUnder(path.join(dirPath, entry.name)))) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=spec-discovery.js.map

package/dist/utils/task-progress.d.ts

@@ -1,3 +1,20 @@
+export interface ParsedTask {
+    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    done: boolean;
+    /** Task text after the checkbox, trimmed (may be empty). */
+    description: string;
+}
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export declare function parseTaskLines(content: string): ParsedTask[];
 export interface TaskProgress {
     total: number;
     completed: number;

package/dist/utils/task-progress.js

@@ -2,21 +2,49 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { resolveArtifactOutputs, resolveSchema } from '../core/artifact-graph/index.js';
 import { resolveSchemaForChange } from './change-metadata.js';
-const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
-const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
-export function countTasksFromContent(content) {
-    const lines = content.split('\n');
-    let total = 0;
-    let completed = 0;
-    for (const line of lines) {
-        if (line.match(TASK_PATTERN)) {
-            total++;
-            if (line.match(COMPLETED_TASK_PATTERN)) {
-                completed++;
-            }
+/**
+ * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
+ *
+ * Leading whitespace is allowed so nested sub-tasks count like their parents.
+ * Anchoring at column 0 made `  - [ ] 1.1.1 ...` invisible to progress, to the
+ * apply task list, and to archive's incomplete-task check, so a change with
+ * unfinished sub-tasks reported "✓ Complete" and archived without a warning.
+ *
+ * Permissive on purpose, and safe to keep that way: any character class
+ * tightened here - the `\s` inside the brackets, which lets a tab or
+ * non-breaking space stand for an empty box - drops lines that used to count,
+ * and a task this parser drops is a task `openspec archive` stops warning about.
+ *
+ * Deliberately unanchored at the end: `.` does not match `\r`, so writing the
+ * description group as `(.*)$` would reject every line of a CRLF tasks.md.
+ */
+const TASK_LINE_PATTERN = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export function parseTaskLines(content) {
+    const tasks = [];
+    for (const line of content.split('\n')) {
+        const match = line.match(TASK_LINE_PATTERN);
+        if (match) {
+            tasks.push({ done: match[1].toLowerCase() === 'x', description: match[2].trim() });
         }
     }
-    return { total, completed };
+    return tasks;
+}
+export function countTasksFromContent(content) {
+    const tasks = parseTaskLines(content);
+    return {
+        total: tasks.length,
+        completed: tasks.filter((task) => task.done).length,
+    };
 }
 /**
  * Identifies the change's tracked-tasks artifact: the artifact whose `generates`