@fission-ai/openspec 1.13.1 → 1.14.0

package/README.md

@@ -122,7 +122,7 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.**
+**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
 
 Install OpenSpec globally:
 
@@ -130,6 +130,12 @@ Install OpenSpec globally:
 npm install -g @fission-ai/openspec@latest
 ```
 
+Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+
+```bash
+brew install openspec
+```
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -137,7 +143,7 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 Now talk to your AI:
 
@@ -151,7 +157,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
 >
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
 
 ## Docs
 
@@ -208,6 +214,12 @@ AI coding assistants are powerful but unpredictable when requirements live only
 npm install -g @fission-ai/openspec@latest
 ```
 
+If you installed OpenSpec with Homebrew:
+
+```bash
+brew upgrade openspec
+```
+
 **Refresh agent instructions**
 
 Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'url';
 import { existsSync, promises as fs } from 'fs';
 import { AI_TOOLS, TOOL_ID_ALIASES } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
-import { getAvailableCliUpdate, displayCliUpdateNote, shouldOfferUpgrade, getInstallDir, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, isSourceCheckout, } from '../core/version-check.js';
+import { getAvailableCliUpdate, displayCliUpdateNote, shouldOfferUpgrade, getInstallDir, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, isSourceCheckout, checkForCliUpdate, getCliInstallInfo, getCliUpdateCommand, canSelfUpgrade, buildVersionReportLines, } from '../core/version-check.js';
 import { ListCommand } from '../core/list.js';
 import { ArchiveCommand } from '../core/archive.js';
 import { ViewCommand } from '../core/view.js';
@@ -118,6 +118,37 @@ program
     .version(version);
 // Global options
 program.option('--no-color', 'Disable color output');
+program
+    .command('version')
+    .description('Report the installed OpenSpec version and update availability')
+    .option('--json', 'Output as JSON')
+    .option('--check', 'Check the registry for a newer version')
+    .action(async (options) => {
+    const install = getCliInstallInfo();
+    const update = options.check ? await checkForCliUpdate() : undefined;
+    const command = update?.status === 'available' ? getCliUpdateCommand(install) : null;
+    const output = {
+        schemaVersion: 1,
+        version,
+        install,
+        ...(update
+            ? {
+                update: {
+                    ...update,
+                    command,
+                    canSelfUpgrade: update.status === 'available'
+                        ? canSelfUpgrade(install.location, process.cwd())
+                        : false,
+                },
+            }
+            : {}),
+    };
+    if (options.json) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(buildVersionReportLines(version, install, update, command).join('\n'));
+});
 // Apply global flags and telemetry before any command runs
 // Note: preAction receives (thisCommand, actionCommand) where:
 // - thisCommand: the command where hook was added (root program)
@@ -296,12 +327,17 @@ program
     .description('List items (changes by default). Use --specs to list specs.')
     .option('--specs', 'List specs instead of changes')
     .option('--changes', 'List changes explicitly (default)')
+    .option('--archived', 'Show only archived changes')
+    .option('--all', 'Show both active and archived changes')
     .option('--sort <order>', 'Sort order: "recent" (default) or "name"', 'recent')
     .option('--json', 'Output as JSON (for programmatic use)')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
     .addOption(hiddenStorePathOption())
     .action(async (options) => {
     try {
+        if (options?.specs && (options.archived || options.all)) {
+            throw new Error('--archived and --all can only be used when listing changes.');
+        }
         const root = await resolveRootForCommand(options ?? {}, {
             json: options?.json,
             failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
@@ -318,6 +354,8 @@ program
         await listCommand.execute(root.path, mode, {
             sort,
             json: options?.json,
+            archived: options?.archived,
+            all: options?.all,
             ...(options?.json ? { root: toRootOutput(root) } : {}),
         });
     }

package/dist/commands/spec.js

@@ -45,6 +45,7 @@ function filterSpec(spec, options) {
     const filteredRequirements = (requirementIndex !== undefined
         ? [spec.requirements[requirementIndex]]
         : spec.requirements).map(req => ({
+        name: req.name,
         text: req.text,
         scenarios: includeScenarios ? req.scenarios : [],
     }));

package/dist/commands/workflow/instructions.js

@@ -7,7 +7,7 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { isSpecsArtifactPath } from '../../core/artifact-graph/outputs.js';
 import { findUnreadDeltaFiles } from '../../utils/spec-discovery.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
@@ -103,6 +103,14 @@ export function printInstructionsText(instructions, isBlocked) {
         ` change="${escapeEnvelopeAttribute(changeName)}"` +
         ` schema="${escapeEnvelopeAttribute(schemaName)}">`);
     console.log();
+    if (instructions.warnings) {
+        for (const warning of instructions.warnings) {
+            console.log('<warning>');
+            console.log(escapeEnvelopeTags(warning));
+            console.log('</warning>');
+            console.log();
+        }
+    }
     // Artifacts skipped via skip_specs get no creation directive: emitting the
     // task/template anyway would prompt an agent to write spec files that
     // validate then rejects as conflicting with the marker.
@@ -215,9 +223,16 @@ export function printInstructionsText(instructions, isBlocked) {
     // Closing tag
     console.log('</artifact>');
 }
-// -----------------------------------------------------------------------------
-// Apply Instructions Command
-// -----------------------------------------------------------------------------
+/** Adds one-based source locations to parsed tasks without changing task parsing. */
+function parseLocatedTasks(content, sourcePath) {
+    const tasks = [];
+    for (const [index, line] of content.split('\n').entries()) {
+        const [task] = parseTaskLines(line);
+        if (task)
+            tasks.push({ ...task, sourcePath, line: index + 1 });
+    }
+    return tasks;
+}
 /**
  * Turns parsed task lines into the listed task items.
  *
@@ -238,6 +253,8 @@ function toTaskItems(parsed) {
             id: `${tasks.length + 1}`,
             description: task.description,
             done: task.done,
+            sourcePath: task.sourcePath,
+            line: task.line,
         });
     }
     return tasks;
@@ -394,15 +411,28 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             contextFiles[artifact.id] = outputs;
         }
     }
-    // Parse tasks if tracking file exists
+    // Parse every concrete file matched by apply.tracks. A tracking path may be
+    // a glob owned by an artifact with any ID, so treating it as one literal
+    // path loses task evidence for valid custom schemas.
     let parsedTasks = [];
+    const unavailableTrackingFiles = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
-        tracksFileExists = fs.existsSync(tracksPath);
-        if (tracksFileExists) {
-            const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            parsedTasks = parseTaskLines(tasksContent);
+        const tracksPaths = resolveArtifactOutputs(changeDir, tracksFile);
+        tracksFileExists = tracksPaths.length > 0;
+        for (const tracksPath of tracksPaths) {
+            try {
+                const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
+                parsedTasks.push(...parseLocatedTasks(tasksContent, tracksPath));
+            }
+            catch (error) {
+                const code = error?.code;
+                const message = error instanceof Error ? error.message : String(error);
+                unavailableTrackingFiles.push({
+                    path: tracksPath,
+                    reason: code && !message.includes(code) ? `${code}: ${message}` : message,
+                });
+            }
         }
     }
     const tasks = toTaskItems(parsedTasks);
@@ -435,6 +465,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `The ${tracksFilename} file is missing and must be created.` +
                 `\n${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
+    else if (tracksFile && unavailableTrackingFiles.length > 0 && tasks.length === 0) {
+        state = 'blocked';
+        instruction = 'No readable task descriptions are available.';
+    }
     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.
@@ -444,7 +478,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             `The ${tracksFilename} file exists but contains no tasks to work on.` +
                 `\nAdd tasks to ${tracksFilename}, or rebuild it: ${describeArtifactRemedy(changeName, findArtifactIdFor(schema, tracksFile))}`;
     }
-    else if (tracksFile && remaining === 0 && total > 0) {
+    else if (tracksFile &&
+        unavailableTrackingFiles.length === 0 &&
+        remaining === 0 &&
+        total > 0) {
         state = 'all_done';
         instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
     }
@@ -457,13 +494,22 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
-    const warnings = await collectApplyWarnings({
-        state,
-        schema,
-        changeDir,
-        changeName,
-        skippedArtifacts: context.skippedArtifacts,
-    });
+    if (unavailableTrackingFiles.length > 0) {
+        const unavailableDetails = unavailableTrackingFiles
+            .map((file) => `- ${file.path}: ${file.reason}`)
+            .join('\n');
+        instruction += `\nTask completion is not verified because tracking evidence was unavailable:\n${unavailableDetails}`;
+    }
+    const warnings = [
+        ...(context.warnings ?? []),
+        ...(await collectApplyWarnings({
+            state,
+            schema,
+            changeDir,
+            changeName,
+            skippedArtifacts: context.skippedArtifacts,
+        })),
+    ];
     return {
         changeName,
         changeDir,
@@ -471,6 +517,8 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
+        taskTrackingConfigured: tracksFile !== null,
+        ...(unavailableTrackingFiles.length > 0 ? { unavailableTrackingFiles } : {}),
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         ...(missingPrerequisites.length > 0 ? { missingPrerequisites } : {}),

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

@@ -16,6 +16,8 @@ export interface TaskItem {
     id: string;
     description: string;
     done: boolean;
+    sourcePath: string;
+    line: number;
 }
 export interface ApplyInstructions {
     changeName: string;
@@ -28,6 +30,11 @@ export interface ApplyInstructions {
         remaining: number;
     };
     tasks: TaskItem[];
+    taskTrackingConfigured: boolean;
+    unavailableTrackingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
     state: 'blocked' | 'all_done' | 'ready';
     missingArtifacts?: string[];
     /**

package/dist/commands/workflow/status.js

@@ -6,7 +6,7 @@
 import ora from 'ora';
 import chalk from 'chalk';
 import { getChangeDir } from '../../core/planning-home.js';
-import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
+import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, findDeclaringProjectRoot, } from '../../core/root-selection.js';
 import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
 import { resolveNextStep } from '../../core/change-status-policy.js';
 import { asStatus } from '../shared-output.js';
@@ -43,12 +43,20 @@ export async function statusCommand(options) {
         // `Next:` line, so a store-selected root can never carry `--store` in one
         // and drop it from the other.
         const storeOptions = isStoreSelectedRoot(root) ? { storeId: root.storeId } : {};
+        // A store holds planning artifacts only; the project declaring it is
+        // where implementation edits go (#2013).
+        const implementationRoot = isStoreSelectedRoot(root)
+            ? findDeclaringProjectRoot(root.storeId)
+            : null;
+        const statusOptions = implementationRoot
+            ? { ...storeOptions, implementationRoot }
+            : storeOptions;
         // Single definition of "load one change's status" so the batch and
         // single-change payloads can never drift apart.
         const loadStatus = (changeName) => formatChangeStatus(loadChangeContext(projectRoot, changeName, options.schema, {
             changeDir: getChangeDir(planningHome, changeName),
             planningHome,
-        }), storeOptions);
+        }), statusOptions);
         // Handle no-changes case gracefully — status is informational,
         // so "no changes" is a valid state, not an error.
         if (!options.change) {
@@ -157,6 +165,11 @@ export function printStatusText(status, options = {}) {
     const total = status.artifacts.length - skippedCount;
     console.log(`Change: ${status.changeName}`);
     console.log(`Schema: ${status.schemaName}`);
+    if (status.warnings) {
+        for (const warning of status.warnings) {
+            console.log(chalk.yellow(`Warning: ${warning}`));
+        }
+    }
     if (status.changeRoot) {
         console.log(`Change root: ${status.changeRoot}`);
     }