@fission-ai/openspec 1.4.1 → 1.6.0-beta.1

package/README.md

@@ -47,6 +47,14 @@ Our philosophy:
 ## See it in action
 
 ```text
+You: /opsx:explore
+AI:  What would you like to explore?
+You: I want dark mode but I'm not sure how to do it cleanly.
+AI:  Let me look at your styling setup...
+     Cleanest path here: CSS variables + a small theme context,
+     with system-preference detection. No new dependencies. Scope it?
+You: Yes, let's do it.
+
 You: /opsx:propose add-dark-mode
 AI:  Created openspec/changes/add-dark-mode/
      ✓ proposal.md — why we're doing this, what's changing
@@ -77,6 +85,18 @@ AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
 
 </details>
 
+## Why teams adopt OpenSpec
+
+Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
+
+**[Stores](docs/stores-beta/user-guide.md)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
+
+- **Cross-repo features** — one change, one plan, even when the code lands in three repos.
+- **Shared requirements** — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
+- **Plan before code** — capture the plan in the store now; the code repos catch up later.
+
+> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
+
 ## Quick Start
 
 **Requires Node.js 20.19.0 or higher.**
@@ -94,9 +114,12 @@ cd your-project
 openspec init
 ```
 
-Now tell your AI: `/opsx:propose <what-you-want-to-build>`
+Now talk to your AI:
 
-If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
+- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
+
+Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
@@ -105,14 +128,24 @@ If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/
 
 ## Docs
 
+**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
+
 → **[Getting Started](docs/getting-started.md)**: first steps<br>
+→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
+→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
+→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
+→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
 → **[Workflows](docs/workflows.md)**: combos and patterns<br>
+→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
+→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
 → **[Commands](docs/commands.md)**: slash commands & skills<br>
 → **[CLI](docs/cli.md)**: terminal reference<br>
+→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
 → **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours
+→ **[Customization](docs/customization.md)**: make it yours<br>
+→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 
 ## Community schemas
@@ -129,7 +162,7 @@ AI coding assistants are powerful but unpredictable when requirements live only
 - **Agree before you build** — human and AI align on specs before code gets written
 - **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
 - **Work fluidly** — update any artifact anytime, no rigid phase gates
-- **Use your tools** — works with 20+ AI assistants via slash commands
+- **Use your tools** — works with 30+ AI assistants via slash commands
 
 ### How we compare
 

package/dist/cli/index.d.ts

@@ -1,5 +1,10 @@
 import { Command } from 'commander';
 declare const program: Command;
+/**
+ * Get the full command path for nested commands.
+ * For example: 'change show' -> 'change:show'
+ */
+export declare function getCommandPath(command: Command): string;
 export { program };
 export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -1,14 +1,16 @@
-import { Command } from 'commander';
+import { asStatus } from '../commands/shared-output.js';
+import { Command, Option } from 'commander';
 import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { promises as fs } from 'fs';
-import { AI_TOOLS, OPENSPEC_DIR_NAME } from '../core/config.js';
+import { AI_TOOLS } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
 import { ListCommand } from '../core/list.js';
 import { ArchiveCommand } from '../core/archive.js';
 import { ViewCommand } from '../core/view.js';
+import { resolveRootForCommand, toRootOutput } from '../core/root-selection.js';
 import { registerSpecCommand } from '../commands/spec.js';
 import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
@@ -17,12 +19,37 @@ import { CompletionCommand } from '../commands/completion.js';
 import { FeedbackCommand } from '../commands/feedback.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerSchemaCommand } from '../commands/schema.js';
-import { registerWorkspaceCommand } from '../commands/workspace.js';
-import { registerContextStoreCommand } from '../commands/context-store.js';
-import { registerInitiativeCommand } from '../commands/initiative.js';
-import { findWorkspaceRoot } from '../core/workspace/index.js';
-import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, setChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { registerStoreCommand } from '../commands/store.js';
+import { registerDoctorCommand } from '../commands/doctor.js';
+import { registerContextCommand } from '../commands/context.js';
+import { registerWorksetCommand } from '../commands/workset.js';
+import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
+const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
+// Deliberate rejection path: --store-path stays registered (hidden) so the
+// resolver can explain that registering the path is the supported route,
+// instead of Commander emitting a generic unknown-option error (or, for
+// `show`, silently ignoring it via allowUnknownOption).
+function hiddenStorePathOption() {
+    return new Option('--store-path <path>', 'Not supported; register the path with "openspec store register <path>" and use --store <id>').hideHelp();
+}
+function failWithError(error, json) {
+    // The agent contract: every --json failure leaves exactly one JSON
+    // document on stdout (the command's null-shape plus a status array).
+    if (json?.enabled) {
+        console.log(JSON.stringify({ ...(json.payload ?? {}), status: [asStatus(error, json.fallbackCode ?? 'command_error')] }, null, 2));
+        process.exitCode = 1;
+        return;
+    }
+    ora().fail(`Error: ${error.message}`);
+    // Resolution and store errors carry a pasteable fix - never drop it.
+    const fix = error.diagnostic?.fix;
+    if (fix) {
+        console.error(`Fix: ${fix}`);
+    }
+    process.exitCode = process.exitCode ?? 1;
+}
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -30,7 +57,7 @@ const { version } = require('../../package.json');
  * Get the full command path for nested commands.
  * For example: 'change show' -> 'change:show'
  */
-function getCommandPath(command) {
+export function getCommandPath(command) {
     const names = [];
     let current = command;
     while (current) {
@@ -70,21 +97,6 @@ program.hook('postAction', async () => {
 });
 const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
 const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
-async function hasRepoLocalOpenSpecProject(projectPath) {
-    try {
-        const stats = await fs.stat(path.join(projectPath, OPENSPEC_DIR_NAME));
-        return stats.isDirectory();
-    }
-    catch (error) {
-        const code = typeof error === 'object' && error !== null && 'code' in error
-            ? error.code
-            : undefined;
-        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-            throw error;
-        }
-        return false;
-    }
-}
 program
     .command('init [path]')
     .description('Initialize OpenSpec in your project')
@@ -122,8 +134,7 @@ program
         await initCommand.execute(targetPath);
     }
     catch (error) {
-        console.log(); // Empty line for spacing
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -144,8 +155,7 @@ program
         await initCommand.execute('.');
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -155,21 +165,11 @@ program
     .option('--force', 'Force update even when tools are up to date')
     .action(async (targetPath = '.', options) => {
     try {
-        const resolvedPath = path.resolve(targetPath);
         const updateCommand = new UpdateCommand({ force: options?.force });
-        if (await hasRepoLocalOpenSpecProject(resolvedPath)) {
-            await updateCommand.execute(resolvedPath);
-            return;
-        }
-        const workspaceRoot = await findWorkspaceRoot(resolvedPath);
-        if (workspaceRoot) {
-            throw new Error('OpenSpec workspace detected. Run `openspec workspace update` to refresh workspace-local guidance and skills.');
-        }
-        await updateCommand.execute(resolvedPath);
+        await updateCommand.execute(targetPath);
     }
     catch (error) {
-        console.log(); // Empty line for spacing
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -180,16 +180,32 @@ program
     .option('--changes', 'List changes explicitly (default)')
     .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 {
+        const root = await resolveRootForCommand(options ?? {}, {
+            json: options?.json,
+            failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+        });
+        if (!root) {
+            return;
+        }
         const listCommand = new ListCommand();
         const mode = options?.specs ? 'specs' : 'changes';
         const sort = options?.sort === 'name' ? 'name' : 'recent';
-        await listCommand.execute('.', mode, { sort, json: options?.json });
+        await listCommand.execute(root.path, mode, {
+            sort,
+            json: options?.json,
+            ...(options?.json ? { root: toRootOutput(root) } : {}),
+        });
     }
     catch (error) {
-        console.log(); // Empty line for spacing
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            fallbackCode: 'list_error',
+        });
         process.exit(1);
     }
 });
@@ -202,8 +218,7 @@ program
         await viewCommand.execute('.');
     }
     catch (error) {
-        console.log(); // Empty line for spacing
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -273,23 +288,26 @@ program
     .option('-y, --yes', 'Skip confirmation prompts')
     .option('--skip-specs', 'Skip spec update operations (useful for infrastructure, tooling, or doc-only changes)')
     .option('--no-validate', 'Skip validation (not recommended, requires confirmation)')
+    .option('--json', 'Output as JSON (non-interactive)')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (changeName, options) => {
     try {
         const archiveCommand = new ArchiveCommand();
         await archiveCommand.execute(changeName, options);
     }
     catch (error) {
-        console.log(); // Empty line for spacing
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
 registerSpecCommand(program);
 registerConfigCommand(program);
 registerSchemaCommand(program);
-registerWorkspaceCommand(program);
-registerContextStoreCommand(program);
-registerInitiativeCommand(program);
+registerStoreCommand(program);
+registerDoctorCommand(program);
+registerContextCommand(program);
+registerWorksetCommand(program);
 // Top-level validate command
 program
     .command('validate [item-name]')
@@ -302,14 +320,15 @@ program
     .option('--json', 'Output validation results as JSON')
     .option('--concurrency <n>', 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)')
     .option('--no-interactive', 'Disable interactive prompts')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (itemName, options) => {
     try {
         const validateCommand = new ValidateCommand();
         await validateCommand.execute(itemName, options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error, { enabled: options?.json, fallbackCode: 'validate_error' });
         process.exit(1);
     }
 });
@@ -327,6 +346,10 @@ program
     .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
     .option('--no-scenarios', 'JSON only: Exclude scenario content')
     .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    // Explicit registration required: allowUnknownOption would otherwise
+    // silently swallow --store-path instead of rejecting it deliberately.
+    .addOption(hiddenStorePathOption())
     // allow unknown options to pass-through to underlying command implementation
     .allowUnknownOption(true)
     .action(async (itemName, options) => {
@@ -335,8 +358,7 @@ program
         await showCommand.execute(itemName, options ?? {});
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error, { enabled: options?.json, fallbackCode: 'show_error' });
         process.exit(1);
     }
 });
@@ -351,8 +373,7 @@ program
         await feedbackCommand.execute(message, options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -369,8 +390,7 @@ completionCmd
         await completionCommand.generate({ shell });
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -384,8 +404,7 @@ completionCmd
         await completionCommand.install({ shell, verbose: options?.verbose });
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -399,8 +418,7 @@ completionCmd
         await completionCommand.uninstall({ shell, yes: options?.yes });
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -428,13 +446,14 @@ program
     .option('--change <id>', 'Change name to show status for')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (options) => {
     try {
         await statusCommand(options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error, { enabled: options.json, fallbackCode: 'change_error' });
         process.exit(1);
     }
 });
@@ -445,6 +464,8 @@ program
     .option('--change <id>', 'Change name')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
     .action(async (artifactId, options) => {
     try {
         // Special case: "apply" is not an artifact, but a command to get apply instructions
@@ -456,8 +477,7 @@ program
         }
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error, { enabled: options.json, fallbackCode: 'change_error' });
         process.exit(1);
     }
 });
@@ -472,8 +492,7 @@ program
         await templatesCommand(options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -487,8 +506,7 @@ program
         await schemasCommand(options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });
@@ -498,39 +516,21 @@ newCmd
     .command('change <name>')
     .description('Create a new change directory')
     .option('--description <text>', 'Description to add to README.md')
-    .option('--goal <text>', 'Workspace product goal to store with the change')
-    .option('--areas <names>', 'Comma-separated affected workspace link names')
-    .option('--initiative <id>', 'Link the repo-local change to an initiative')
-    .option('--store <id>', 'Context store id for --initiative')
-    .option('--store-path <path>', 'Existing local context store root for --initiative')
+    .option('--goal <text>', 'Optional goal metadata to store with the change')
     .option('--schema <name>', `Workflow schema to use (default: ${DEFAULT_SCHEMA})`)
     .option('--json', 'Output as JSON')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
+    // Removed options kept registered (hidden) so users get a deliberate
+    // explanation instead of a generic unknown-option error.
+    .addOption(new Option('--initiative <id>', 'No longer supported').hideHelp())
+    .addOption(new Option('--areas <names>', 'No longer supported').hideHelp())
     .action(async (name, options) => {
     try {
         await newChangeCommand(name, options);
     }
     catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
-        process.exit(1);
-    }
-});
-// Set command group
-const setCmd = program.command('set').description('Set checked-in OpenSpec metadata');
-setCmd
-    .command('change <name>')
-    .description('Set repo-local change metadata')
-    .option('--initiative <id>', 'Link the repo-local change to an initiative')
-    .option('--store <id>', 'Context store id for --initiative')
-    .option('--store-path <path>', 'Existing local context store root for --initiative')
-    .option('--json', 'Output as JSON')
-    .action(async (name, options) => {
-    try {
-        await setChangeCommand(name, options);
-    }
-    catch (error) {
-        console.log();
-        ora().fail(`Error: ${error.message}`);
+        failWithError(error);
         process.exit(1);
     }
 });

package/dist/commands/change.d.ts

@@ -1,6 +1,9 @@
+import type { RootOutput } from '../core/root-selection.js';
 export declare class ChangeCommand {
     private converter;
-    constructor();
+    private rootPath?;
+    constructor(rootPath?: string);
+    private getChangesPath;
     /**
      * Show a change proposal.
      * - Text mode: raw markdown passthrough (no filters)
@@ -12,6 +15,7 @@ export declare class ChangeCommand {
         requirementsOnly?: boolean;
         deltasOnly?: boolean;
         noInteractive?: boolean;
+        rootOutput?: RootOutput;
     }): Promise<void>;
     /**
      * List active changes.
@@ -29,7 +33,6 @@ export declare class ChangeCommand {
     }): Promise<void>;
     private getActiveChanges;
     private extractTitle;
-    private countTasks;
     private printNextSteps;
 }
 //# sourceMappingURL=change.d.ts.map

package/dist/commands/change.js

@@ -5,14 +5,20 @@ import { Validator } from '../core/validation/validator.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
+import { getTaskProgressForChange } from '../utils/task-progress.js';
 // Constants for better maintainability
 const ARCHIVE_DIR = 'archive';
-const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
-const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
 export class ChangeCommand {
     converter;
-    constructor() {
+    rootPath;
+    // rootPath is set only by root-aware callers (top-level `show`); the
+    // deprecated noun-form commands stay cwd-based.
+    constructor(rootPath) {
         this.converter = new JsonConverter();
+        this.rootPath = rootPath;
+    }
+    getChangesPath() {
+        return path.join(this.rootPath ?? process.cwd(), 'openspec', 'changes');
     }
     /**
      * Show a change proposal.
@@ -21,7 +27,7 @@ export class ChangeCommand {
      *   Note: --requirements-only is deprecated alias for --deltas-only
      */
     async show(changeName, options) {
-        const changesPath = path.join(process.cwd(), 'openspec', 'changes');
+        const changesPath = this.getChangesPath();
         if (!changeName) {
             const canPrompt = isInteractive(options);
             const changes = await this.getActiveChanges(changesPath);
@@ -62,19 +68,14 @@ export class ChangeCommand {
             const title = this.extractTitle(contentForTitle, changeName);
             const id = parsed.name;
             const deltas = parsed.deltas || [];
-            if (options.requirementsOnly || options.deltasOnly) {
-                const output = { id, title, deltaCount: deltas.length, deltas };
-                console.log(JSON.stringify(output, null, 2));
-            }
-            else {
-                const output = {
-                    id,
-                    title,
-                    deltaCount: deltas.length,
-                    deltas,
-                };
-                console.log(JSON.stringify(output, null, 2));
-            }
+            const output = {
+                id,
+                title,
+                deltaCount: deltas.length,
+                deltas,
+                ...(options.rootOutput ? { root: options.rootOutput } : {}),
+            };
+            console.log(JSON.stringify(output, null, 2));
         }
         else {
             const content = await fs.readFile(proposalPath, 'utf-8');
@@ -92,23 +93,14 @@ export class ChangeCommand {
         if (options?.json) {
             const changeDetails = await Promise.all(changes.map(async (changeName) => {
                 const proposalPath = path.join(changesPath, changeName, 'proposal.md');
-                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
                 try {
                     const content = await fs.readFile(proposalPath, 'utf-8');
                     const changeDir = path.join(changesPath, changeName);
                     const parser = new ChangeParser(content, changeDir);
                     const change = await parser.parseChangeWithDeltas(changeName);
-                    let taskStatus = { total: 0, completed: 0 };
-                    try {
-                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-                        taskStatus = this.countTasks(tasksContent);
-                    }
-                    catch (error) {
-                        // Tasks file may not exist, which is okay
-                        if (process.env.DEBUG) {
-                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
-                        }
-                    }
+                    // Resolve task progress through the shared tracked-tasks helper so
+                    // this deprecated noun-form list cannot re-fork the resolution (#1202).
+                    const taskStatus = await getTaskProgressForChange(changesPath, changeName, process.cwd());
                     return {
                         id: changeName,
                         title: this.extractTitle(content, changeName),
@@ -142,21 +134,11 @@ export class ChangeCommand {
             // Long format: id: title and minimal counts
             for (const changeName of sorted) {
                 const proposalPath = path.join(changesPath, changeName, 'proposal.md');
-                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
                 try {
                     const content = await fs.readFile(proposalPath, 'utf-8');
                     const title = this.extractTitle(content, changeName);
-                    let taskStatusText = '';
-                    try {
-                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-                        const { total, completed } = this.countTasks(tasksContent);
-                        taskStatusText = ` [tasks ${completed}/${total}]`;
-                    }
-                    catch (error) {
-                        if (process.env.DEBUG) {
-                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
-                        }
-                    }
+                    const { total, completed } = await getTaskProgressForChange(changesPath, changeName, process.cwd());
+                    const taskStatusText = total > 0 ? ` [tasks ${completed}/${total}]` : '';
                     const changeDir = path.join(changesPath, changeName);
                     const parser = new ChangeParser(await fs.readFile(proposalPath, 'utf-8'), changeDir);
                     const change = await parser.parseChangeWithDeltas(changeName);
@@ -251,20 +233,6 @@ export class ChangeCommand {
         const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/im);
         return match ? match[1].trim() : changeName;
     }
-    countTasks(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++;
-                }
-            }
-        }
-        return { total, completed };
-    }
     printNextSteps() {
         const bullets = [];
         bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');