@fission-ai/openspec 1.7.0 → 1.9.0

package/dist/commands/spec.js

@@ -1,12 +1,31 @@
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import path, { join } from 'path';
 import { MarkdownParser } from '../core/parsers/markdown-parser.js';
 import { Validator } from '../core/validation/validator.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 const SPECS_DIR = 'openspec/specs';
-function parseSpecFromFile(specPath, specId) {
+function assertSpecPath(specsDir, specPath) {
+    const relativePath = path.relative(path.resolve(specsDir), path.resolve(specPath));
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        throw new Error(`Path is outside the allowed directory: ${specPath}`);
+    }
+    try {
+        // Preserve confined spec.md links, including links to a sibling capability.
+        FileSystemUtils.assertPathWithin(specsDir, specPath);
+    }
+    catch {
+        // A capability directory may intentionally be a monorepo symlink. Treat it
+        // as the trust root while still rejecting a link outside that capability.
+        FileSystemUtils.assertPathWithin(path.dirname(specPath), specPath);
+    }
+}
+function parseSpecFromFile(specsDir, specPath, specId) {
+    assertSpecPath(specsDir, specPath);
     const content = readFileSync(specPath, 'utf-8');
     const parser = new MarkdownParser(content);
     return parser.parseSpec(specId);
@@ -41,7 +60,8 @@ function filterSpec(spec, options) {
  * Print the raw markdown content for a spec file without any formatting.
  * Raw-first behavior ensures text mode is a passthrough for deterministic output.
  */
-function printSpecTextRaw(specPath) {
+function printSpecTextRaw(specsDir, specPath) {
+    assertSpecPath(specsDir, specPath);
     const content = readFileSync(specPath, 'utf-8');
     console.log(content);
 }
@@ -70,6 +90,7 @@ export class SpecCommand {
             }
         }
         const specPath = join(this.specsDir, specId, 'spec.md');
+        assertSpecPath(this.specsDir, specPath);
         if (!existsSync(specPath)) {
             // Root-aware callers get the absolute path; the cwd-based noun form
             // keeps its historical forward-slash relative message on all platforms.
@@ -80,7 +101,7 @@ export class SpecCommand {
             if (options.requirements && options.requirement) {
                 throw new Error('Options --requirements and --requirement cannot be used together');
             }
-            const parsed = parseSpecFromFile(specPath, specId);
+            const parsed = parseSpecFromFile(this.specsDir, specPath, specId);
             const filtered = filterSpec(parsed, options);
             const output = {
                 id: specId,
@@ -94,7 +115,7 @@ export class SpecCommand {
             console.log(JSON.stringify(output, null, 2));
             return;
         }
-        printSpecTextRaw(specPath);
+        printSpecTextRaw(this.specsDir, specPath);
     }
 }
 export function registerSpecCommand(rootProgram) {
@@ -138,7 +159,8 @@ export function registerSpecCommand(rootProgram) {
             const specs = discovered
                 .map(({ id, specFile }) => {
                 try {
-                    const spec = parseSpecFromFile(specFile, id);
+                    assertSpecPath(SPECS_DIR, specFile);
+                    const spec = parseSpecFromFile(SPECS_DIR, specFile, id);
                     return {
                         id,
                         title: spec.name,
@@ -199,10 +221,12 @@ export function registerSpecCommand(rootProgram) {
                 }
             }
             const specPath = join(SPECS_DIR, specId, 'spec.md');
+            assertSpecPath(SPECS_DIR, specPath);
             if (!existsSync(specPath)) {
                 throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
             }
             const validator = new Validator(options.strict);
+            assertSpecPath(SPECS_DIR, specPath);
             const report = await validator.validateSpec(specPath);
             if (options.json) {
                 console.log(JSON.stringify(report, null, 2));

package/dist/commands/validate.d.ts

@@ -2,6 +2,7 @@ interface ExecuteOptions {
     all?: boolean;
     changes?: boolean;
     specs?: boolean;
+    archived?: boolean;
     type?: string;
     strict?: boolean;
     json?: boolean;
@@ -29,6 +30,28 @@ export declare class ValidateCommand {
     private printReport;
     private printNextSteps;
     private runBulkValidation;
+    /**
+     * Lists archived change ids from the resolved root's archive directory,
+     * mirroring `getArchivedChangeIds` but store-aware (uses `root.archiveDir`
+     * rather than a cwd-relative path). Directories only, hidden entries skipped.
+     *
+     * Only a missing archive directory (ENOENT) is an empty list; a permission
+     * error, an I/O error, or an `archive` path that is a file (ENOTDIR) is a real
+     * failure and must not read as "no archived changes" — that would let a
+     * pre-commit lint pass without inspecting anything (#205).
+     */
+    private listArchivedChangeIds;
+    /**
+     * Validates that every archived change has all of its tasks completed.
+     *
+     * An archived change is expected to be finished; an archived change with
+     * unchecked tasks is a real integrity problem the normal validate flow never
+     * surfaces, because active-change discovery excludes the archive directory
+     * (#205). Reuses the same task-progress counting `status`, `list`, and
+     * `archive` rely on, so what counts as a task never forks. Changes with no
+     * tasks pass (nothing to complete).
+     */
+    private runArchivedTaskValidation;
 }
 export {};
 //# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.js

@@ -7,15 +7,33 @@ import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { getAvailableChanges } from './workflow/shared.js';
 import { nearestMatches } from '../utils/match.js';
+import { promises as fs } from 'fs';
+import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 export class ValidateCommand {
     async execute(itemName, options = {}) {
-        const root = await resolveRootForCommand(options, { json: options.json });
+        const bulk = options.all || options.changes || options.specs;
+        const root = await resolveRootForCommand(options, {
+            json: options.json,
+            ...(bulk ? { allowImplicitRoot: false } : {}),
+        });
         if (!root) {
             return;
         }
         const interactive = isInteractive(options);
+        // Archived-task linting is its own scope: it checks task completion of
+        // already-archived changes, not delta specs (whose operations are already
+        // applied). Handled before the other bulk flags so `--archived` is explicit
+        // and never alters an existing invocation's behavior (#205).
+        if (options.archived) {
+            await this.runArchivedTaskValidation(root, {
+                json: !!options.json,
+                noInteractive: resolveNoInteractive(options),
+            });
+            return;
+        }
         // Handle bulk flags first
-        if (options.all || options.changes || options.specs) {
+        if (bulk) {
             await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
@@ -145,7 +163,10 @@ export class ValidateCommand {
         if (type === 'change') {
             const changeDir = path.join(root.changesDir, id);
             const start = Date.now();
-            const report = await validator.validateChangeDeltaSpecs(changeDir);
+            const report = await validator.validateChangeDeltaSpecs(changeDir, {
+                mainSpecsDir: root.specsDir,
+                projectRoot: root.path,
+            });
             const durationMs = Date.now() - start;
             this.printReport('change', id, report, durationMs, opts.json, root);
             // Non-zero exit if invalid (keeps enriched output test semantics)
@@ -222,7 +243,10 @@ export class ValidateCommand {
             queue.push(async () => {
                 const start = Date.now();
                 const changeDir = path.join(root.changesDir, id);
-                const report = await validator.validateChangeDeltaSpecs(changeDir);
+                const report = await validator.validateChangeDeltaSpecs(changeDir, {
+                    mainSpecsDir: root.specsDir,
+                    projectRoot: root.path,
+                });
                 const durationMs = Date.now() - start;
                 return { id, type: 'change', valid: report.valid, issues: report.issues, durationMs };
             });
@@ -322,6 +346,126 @@ export class ValidateCommand {
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }
+    /**
+     * Lists archived change ids from the resolved root's archive directory,
+     * mirroring `getArchivedChangeIds` but store-aware (uses `root.archiveDir`
+     * rather than a cwd-relative path). Directories only, hidden entries skipped.
+     *
+     * Only a missing archive directory (ENOENT) is an empty list; a permission
+     * error, an I/O error, or an `archive` path that is a file (ENOTDIR) is a real
+     * failure and must not read as "no archived changes" — that would let a
+     * pre-commit lint pass without inspecting anything (#205).
+     */
+    async listArchivedChangeIds(root) {
+        try {
+            const entries = await fs.readdir(root.archiveDir, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    /**
+     * Validates that every archived change has all of its tasks completed.
+     *
+     * An archived change is expected to be finished; an archived change with
+     * unchecked tasks is a real integrity problem the normal validate flow never
+     * surfaces, because active-change discovery excludes the archive directory
+     * (#205). Reuses the same task-progress counting `status`, `list`, and
+     * `archive` rely on, so what counts as a task never forks. Changes with no
+     * tasks pass (nothing to complete).
+     */
+    async runArchivedTaskValidation(root, opts) {
+        // List first (may throw on a real archive-read failure), then start the
+        // spinner so a thrown error never leaves a spinner spinning.
+        const ids = await this.listArchivedChangeIds(root);
+        const spinner = !opts.json && !opts.noInteractive ? ora('Validating archived changes...').start() : undefined;
+        // The archive is append-only and can hold thousands of changes; a single
+        // run resolves them all under one constant projectRoot (root.path), so
+        // memoize the schema→glob lookup to avoid re-parsing the same schema.yaml
+        // once per change. The loop is intentionally sequential: the per-change work
+        // is dominated by synchronous schema/config resolution, which a promise pool
+        // cannot overlap on Node's single thread — a pool would add complexity for
+        // no real gain here.
+        const schemaGlobCache = new Map();
+        const results = [];
+        let passed = 0;
+        let failed = 0;
+        for (const id of ids) {
+            const start = Date.now();
+            const issues = [];
+            try {
+                // The explicit root.path override is load-bearing: an archived change
+                // lives one directory deeper (changes/archive/<id>), so the default
+                // "../../.." projectRoot derivation would be wrong without it.
+                const progress = await getTaskProgressDetailForChange(root.archiveDir, id, root.path, schemaGlobCache);
+                // A tasks file that exists but cannot be read must fail loudly, not be
+                // silently counted as "no tasks" and pass. Report one issue per file,
+                // pathed like every other validate issue (POSIX, root-relative).
+                for (const file of progress.unreadable) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: FileSystemUtils.toPosixPath(path.relative(root.path, file)),
+                        message: 'could not read task file',
+                    });
+                }
+                const incomplete = Math.max(progress.total - progress.completed, 0);
+                if (incomplete > 0) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: 'tasks.md',
+                        message: `${incomplete} incomplete task${incomplete === 1 ? '' : 's'} (${progress.completed}/${progress.total} completed)`,
+                    });
+                }
+            }
+            catch (error) {
+                issues.push({ level: 'ERROR', path: 'tasks.md', message: error?.message || 'Unknown error' });
+            }
+            const valid = issues.length === 0;
+            if (valid)
+                passed++;
+            else
+                failed++;
+            results.push({ id, type: 'change', valid, issues, durationMs: Date.now() - start });
+        }
+        spinner?.stop();
+        const summary = {
+            totals: { items: results.length, passed, failed },
+            byType: { change: summarizeType(results, 'change') },
+        };
+        if (opts.json) {
+            const out = { items: results, summary, version: '1.0', root: toRootOutput(root) };
+            console.log(JSON.stringify(out, null, 2));
+            process.exitCode = failed > 0 ? 1 : 0;
+            return;
+        }
+        if (results.length === 0) {
+            console.log('No archived changes found.');
+            process.exitCode = 0;
+            return;
+        }
+        // Use the same `<type>/<id>` prefix bulk validation prints, so the plain
+        // output maps to the JSON `type` ('change') and stays greppable the same way.
+        for (const res of results) {
+            if (res.valid) {
+                console.log(`✓ change/${res.id}`);
+            }
+            else {
+                console.error(`✗ change/${res.id}`);
+                for (const issue of res.issues) {
+                    const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                    console.error(`  ${prefix} ${issue.message}`);
+                }
+            }
+        }
+        console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+        process.exitCode = failed > 0 ? 1 : 0;
+    }
 }
 function summarizeType(results, type) {
     const filtered = results.filter(r => r.type === type);

package/dist/commands/workflow/instructions.js

@@ -7,13 +7,14 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
 import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
 import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
 import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { loadOperationInputs, readProjectConfig, } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
+import { parseTaskLines } from '../../utils/task-progress.js';
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -206,25 +207,26 @@ export function printInstructionsText(instructions, isBlocked) {
 // Apply Instructions Command
 // -----------------------------------------------------------------------------
 /**
- * Parses tasks.md content and extracts task items with their completion status.
+ * Turns parsed task lines into the listed task items.
+ *
+ * A checkbox with no text after it is left out of the list: this is work for an
+ * agent to act on and tick off, and a bare `- [ ]` gives it nothing to match.
+ * It still counts toward progress, which is taken from every parsed line, so
+ * this list can be shorter than the totals beside it but never disagrees with
+ * `openspec list` or archive about how much work is left. An empty list is also
+ * what puts apply in its "nothing to work on" state, so a file of nothing but
+ * text-less checkboxes asks to be rewritten instead of being called done.
  */
-function parseTasksFile(content) {
+function toTaskItems(parsed) {
     const tasks = [];
-    const lines = content.split('\n');
-    let taskIndex = 0;
-    for (const line of lines) {
-        // Match checkbox patterns: - [ ] or - [x] or - [X]
-        const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]\s*(.+)\s*$/);
-        if (checkboxMatch) {
-            taskIndex++;
-            const done = checkboxMatch[1].toLowerCase() === 'x';
-            const description = checkboxMatch[2].trim();
-            tasks.push({
-                id: `${taskIndex}`,
-                description,
-                done,
-            });
-        }
+    for (const task of parsed) {
+        if (task.description.length === 0)
+            continue;
+        tasks.push({
+            id: `${tasks.length + 1}`,
+            description: task.description,
+            done: task.done,
+        });
     }
     return tasks;
 }
@@ -274,19 +276,21 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         }
     }
     // Parse tasks if tracking file exists
-    let tasks = [];
+    let parsedTasks = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = path.join(changeDir, tracksFile);
+        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
         tracksFileExists = fs.existsSync(tracksPath);
         if (tracksFileExists) {
             const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            tasks = parseTasksFile(tasksContent);
+            parsedTasks = parseTaskLines(tasksContent);
         }
     }
-    // Calculate progress
-    const total = tasks.length;
-    const complete = tasks.filter((t) => t.done).length;
+    const tasks = toTaskItems(parsedTasks);
+    // Calculate progress over every checkbox in the file, listed or not, so these
+    // numbers match `openspec list` and archive's incomplete-task check.
+    const total = parsedTasks.length;
+    const complete = parsedTasks.filter((task) => task.done).length;
     const remaining = total - complete;
     // Determine state and instruction
     let state;
@@ -301,11 +305,12 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'blocked';
         instruction = `The ${tracksFilename} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
     }
-    else if (tracksFile && tracksFileExists && total === 0) {
-        // Tracking file exists but contains no tasks
+    else if (tracksFile && tracksFileExists && tasks.length === 0) {
+        // Tracking file exists but lists nothing an agent can work on: either no
+        // checkboxes at all, or only checkboxes with no text after them.
         const tracksFilename = path.basename(tracksFile);
         state = 'blocked';
-        instruction = `The ${tracksFilename} file exists but contains no tasks.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
+        instruction = `The ${tracksFilename} file exists but contains no tasks to work on.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';

package/dist/commands/workflow/schemas.d.ts

@@ -5,6 +5,8 @@
  */
 export interface SchemasOptions {
     json?: boolean;
+    store?: string;
+    storePath?: string;
 }
 export declare function schemasCommand(options: SchemasOptions): Promise<void>;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/commands/workflow/schemas.js

@@ -5,12 +5,19 @@
  */
 import chalk from 'chalk';
 import { listSchemasWithInfo } from '../../core/artifact-graph/index.js';
+import { resolveRootForCommand } from '../../core/root-selection.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
 export async function schemasCommand(options) {
-    const projectRoot = process.cwd();
-    const schemas = listSchemasWithInfo(projectRoot);
+    const root = await resolveRootForCommand(options, {
+        json: options.json,
+        failurePayload: { schemas: [], root: null },
+    });
+    if (!root) {
+        return;
+    }
+    const schemas = listSchemasWithInfo(root.path);
     if (options.json) {
         console.log(JSON.stringify(schemas, null, 2));
         return;

package/dist/commands/workflow/status.js

@@ -89,9 +89,9 @@ export function printStatusText(status) {
         }
         console.log(line);
     }
-    if (status.isComplete) {
+    if (status.isPlanningComplete) {
         console.log();
-        console.log(chalk.green('All artifacts complete!'));
+        console.log(chalk.green('All planning artifacts complete!'));
     }
 }
 //# sourceMappingURL=status.js.map

package/dist/commands/workflow/templates.js

@@ -39,11 +39,21 @@ export async function templatesCommand(options) {
         else {
             source = 'package';
         }
-        const templates = graph.getAllArtifacts().map((artifact) => ({
-            artifactId: artifact.id,
-            templatePath: FileSystemUtils.canonicalizeExistingPath(path.join(schemaDir, 'templates', artifact.template)),
-            source,
-        }));
+        const templatesDir = path.join(schemaDir, 'templates');
+        const templates = graph.getAllArtifacts().map((artifact) => {
+            const templatePath = path.join(templatesDir, artifact.template);
+            try {
+                FileSystemUtils.assertPathWithin(templatesDir, templatePath);
+                return {
+                    artifactId: artifact.id,
+                    templatePath: FileSystemUtils.canonicalizeExistingPath(templatePath),
+                    source,
+                };
+            }
+            catch {
+                throw new Error(`Template '${artifact.template}' for artifact '${artifact.id}' points outside the schema templates directory`);
+            }
+        });
         spinner?.stop();
         if (options.json) {
             const output = {};

package/dist/core/archive.d.ts

@@ -1,3 +1,17 @@
+/**
+ * True when the ONLY thing wrong with a rebuilt spec is that it has no
+ * requirements. That is the exact failure retiring a capability replaces
+ * (#1302); anything else means the spec is broken in a way the author still has
+ * to fix, so archive must abort exactly as it always did instead of retiring.
+ *
+ * Asking the validator - rather than counting requirement blocks a second time -
+ * is what makes "this spec could not have been written anyway" true by
+ * construction. The two counts genuinely disagree: `MarkdownParser` accepts any
+ * `###` heading under `## Requirements` as a requirement, while the delta block
+ * parser only indexes canonical `### Requirement:` headers and sweeps the rest
+ * into the preamble, which survives into the rebuilt spec.
+ */
+export declare function isRetirableSpec(specName: string, rebuilt: string): Promise<boolean>;
 export interface ArchiveOptions {
     yes?: boolean;
     skipSpecs?: boolean;