@fission-ai/openspec 1.12.0 → 1.13.1

package/dist/telemetry/index.js

@@ -20,9 +20,10 @@
  * versions and broke installs (#1390).
  */
 import { randomUUID } from 'crypto';
-import { getGlobalConfig } from '../core/global-config.js';
+import { getGlobalConfig, isGlobalConfigUnreadable } from '../core/global-config.js';
 import { isCiEnvironment } from '../utils/ci.js';
 import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
+import { isTelemetryOptedOutByEnv } from './opt-out.js';
 // PostHog API key - public key for client-side analytics
 // This is safe to embed as it only allows sending events, not reading data
 const POSTHOG_API_KEY = 'phc_Hthu8YvaIJ9QaFKyTG4TbVwkbd5ktcAFzVTKeMmoW2g';
@@ -59,22 +60,21 @@ async function safeTelemetryFetch(url, options) {
  * Check if telemetry is enabled.
  *
  * Precedence (first match wins):
- * 1. OPENSPEC_TELEMETRY=0 → disabled
- * 2. DO_NOT_TRACK=1 → disabled
+ * 1. OPENSPEC_TELEMETRY set to anything but an on-value (1/true/yes/on) → disabled
+ * 2. DO_NOT_TRACK set to anything but an off-value (0/false/no/off) → disabled
  * 3. CI set to a truthy/on value → disabled (same rule as version-check)
  * 4. global config telemetry.enabled === false → disabled
- * 5. otherwise enabled (unset config means on; opt-out model)
+ * 5. global config file exists but cannot be parsed → disabled
+ * 6. otherwise enabled (unset config means on; opt-out model)
  *
  * Kept synchronous so call sites need not become async. Reads config via
  * sync getGlobalConfig() rather than async getTelemetryConfig().
  */
 export function isTelemetryEnabled() {
-    // Check explicit opt-out
-    if (process.env.OPENSPEC_TELEMETRY === '0') {
-        return false;
-    }
-    // Respect DO_NOT_TRACK standard
-    if (process.env.DO_NOT_TRACK === '1') {
+    // Explicit opt-out, and the DO_NOT_TRACK standard. Both are read
+    // tolerantly (see opt-out.ts): an opt-out that only worked for one exact
+    // spelling would leave users tracked who believe they are not.
+    if (isTelemetryOptedOutByEnv()) {
         return false;
     }
     // Auto-disable in CI environments (providers use true/1/yes/…)
@@ -85,6 +85,11 @@ export function isTelemetryEnabled() {
     if (getGlobalConfig().telemetry?.enabled === false) {
         return false;
     }
+    // A config file that cannot be parsed reads as defaults, which carry no
+    // opt-out, but the file itself may hold one. Unknown is not consent.
+    if (isGlobalConfigUnreadable()) {
+        return false;
+    }
     return true;
 }
 /**
@@ -144,6 +149,13 @@ export async function trackCommand(commandName, version) {
         return;
     }
     try {
+        // Disclosure before collection. A --json run defers the notice (printing
+        // it would corrupt machine-readable output), and for a user whose runs
+        // are all --json it may never have appeared — so nothing is sent, and no
+        // anonymous id is created, until the notice has actually been shown.
+        if (!(await getTelemetryConfig()).noticeSeen) {
+            return;
+        }
         const userId = await getOrCreateAnonymousId();
         sendEvent(userId, 'command_executed', {
             command: commandName,

package/dist/telemetry/opt-out.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Telemetry opt-out signals, shared by telemetry and the version check so both
+ * outbound surfaces honor exactly the same values.
+ *
+ * Parsing is tolerant in the style of isCiEnvironment(): a user who wrote
+ * DO_NOT_TRACK=true meant it, and an exact-match test that silently kept
+ * sending would be a privacy control that does not work. Ambiguity fails
+ * safe — a value we cannot read as "on" suppresses the request rather than
+ * enabling it.
+ */
+/** True when `DO_NOT_TRACK` is set to anything but an explicit off-value. */
+export declare function isDoNotTrackSet(env?: NodeJS.ProcessEnv): boolean;
+/** True when `OPENSPEC_TELEMETRY` is set to anything but an explicit on-value. */
+export declare function isTelemetryDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+/** True when either opt-out signal asks us to stay off the network. */
+export declare function isTelemetryOptedOutByEnv(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=opt-out.d.ts.map

package/dist/telemetry/opt-out.js

@@ -0,0 +1,27 @@
+/**
+ * Telemetry opt-out signals, shared by telemetry and the version check so both
+ * outbound surfaces honor exactly the same values.
+ *
+ * Parsing is tolerant in the style of isCiEnvironment(): a user who wrote
+ * DO_NOT_TRACK=true meant it, and an exact-match test that silently kept
+ * sending would be a privacy control that does not work. Ambiguity fails
+ * safe — a value we cannot read as "on" suppresses the request rather than
+ * enabling it.
+ */
+const ON_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const OFF_VALUES = new Set(['', '0', 'false', 'no', 'off']);
+/** True when `DO_NOT_TRACK` is set to anything but an explicit off-value. */
+export function isDoNotTrackSet(env = process.env) {
+    const value = env.DO_NOT_TRACK;
+    return value !== undefined && !OFF_VALUES.has(value.trim().toLowerCase());
+}
+/** True when `OPENSPEC_TELEMETRY` is set to anything but an explicit on-value. */
+export function isTelemetryDisabledByEnv(env = process.env) {
+    const value = env.OPENSPEC_TELEMETRY;
+    return value !== undefined && !ON_VALUES.has(value.trim().toLowerCase());
+}
+/** True when either opt-out signal asks us to stay off the network. */
+export function isTelemetryOptedOutByEnv(env = process.env) {
+    return isTelemetryDisabledByEnv(env) || isDoNotTrackSet(env);
+}
+//# sourceMappingURL=opt-out.js.map

package/dist/utils/nested-change.d.ts

@@ -0,0 +1,35 @@
+/** A namespace folder under `changes/` and the change directories buried in it. */
+export interface NestedChangeFinding {
+    /** The directory name directly under `changes/` that is not a change. */
+    name: string;
+    /**
+     * Slash-separated paths of the nested change directories, relative to
+     * `changes/`, sorted. Always at least one entry.
+     */
+    nested: string[];
+}
+/**
+ * Reports whether the directory `changes/<name>/` is a namespace folder holding
+ * one or more nested change directories rather than a change of its own.
+ *
+ * Returns undefined for every ordinary change, including a scaffolded one with
+ * no artifacts yet: only a *nested* change directory distinguishes the two.
+ */
+export declare function findNestedChangesIn(changesDir: string, name: string): Promise<NestedChangeFinding | undefined>;
+/**
+ * The same check across every candidate directory under `changes/`, for the
+ * commands that enumerate rather than resolve a single name.
+ */
+export declare function findNestedChanges(changesDir: string, names: string[]): Promise<NestedChangeFinding[]>;
+/**
+ * The stable phrase every nested-change diagnostic contains. Callers that have
+ * only the rendered message - `validate`'s next-steps, which branches on the
+ * exact issue it is advising about - recognise the case by this.
+ */
+export declare const NESTED_CHANGE_ISSUE_MARKER = "is not a change: it is a folder wrapping";
+/**
+ * The one explanation every surface prints, so the constraint and the way out
+ * read identically wherever a user meets them.
+ */
+export declare function describeNestedChange(finding: NestedChangeFinding): string;
+//# sourceMappingURL=nested-change.d.ts.map

package/dist/utils/nested-change.js

@@ -0,0 +1,186 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { artifactOutputExists } from '../core/artifact-graph/outputs.js';
+import { resolveSchema } from '../core/artifact-graph/resolver.js';
+import { METADATA_FILENAME, resolveSchemaForChange } from './change-metadata.js';
+import { hasAnyFileUnder } from './spec-discovery.js';
+/**
+ * Files that only ever sit at the root of a change directory. Their presence
+ * inside a directory that is *not* directly under `changes/` is one of the two
+ * signals that someone laid a change out in a namespace folder
+ * (`changes/<area>/<name>/`), which OpenSpec does not support: a change is a
+ * directory directly under `changes/` and nothing else (#1846).
+ *
+ * The list is deliberately short. Every entry is written by OpenSpec itself for
+ * the default schema - `.openspec.yaml` by `openspec new change` for *every*
+ * schema. A custom schema whose root artifacts are named differently can still
+ * be missed when the directory was created by hand rather than by the CLI; that
+ * misses the diagnostic and behaves exactly as it did before, which is the safe
+ * way round.
+ */
+const CHANGE_ROOT_MARKERS = [
+    METADATA_FILENAME,
+    'proposal.md',
+    'tasks.md',
+    'design.md',
+];
+/** Delta specs live here inside a change, at any depth below it. */
+const DELTA_SPECS_DIR = 'specs';
+/**
+ * How far below a candidate directory to look for a nested change. One level
+ * covers the layout the issue describes (`changes/mobile/refresh-token/`); the
+ * extra levels cover a store namespaced by more than one axis
+ * (`changes/mobile/ios/refresh-token/`) without turning this into an unbounded
+ * walk of every change's spec tree.
+ */
+const MAX_NESTING_DEPTH = 3;
+async function hasChangeRootMarker(dir) {
+    for (const marker of CHANGE_ROOT_MARKERS) {
+        const stats = await fs.stat(path.join(dir, marker)).catch(() => undefined);
+        if (stats?.isFile())
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `dir` is a change rather than a folder wrapping one.
+ *
+ * Two independent signals, because either alone leaves a hole. A root artifact
+ * covers the CLI-created change and the hand-made one that starts from a
+ * proposal. A populated `specs/` covers the change that starts from its delta
+ * specs - the case that arrives here most often, since a nested change is
+ * always hand-made (`openspec new change` rejects a name with a separator) and
+ * "mkdir the tree, write the deltas" is how someone gets there.
+ *
+ * The `specs/` signal is what keeps a custom schema safe. A schema may generate
+ * every root artifact into a subdirectory (`generates: rfc/proposal.md`), and
+ * such a change, created by hand so it has no `.openspec.yaml`, would otherwise
+ * look exactly like a namespace folder wrapping a change called `rfc`. Its
+ * delta specs still live under `specs/`, so it is recognised as the change it
+ * is. `specs/**\/*.md` is fixed by the delta format itself, not by the schema.
+ */
+async function looksLikeChange(dir, projectRoot) {
+    if (await hasChangeRootMarker(dir))
+        return true;
+    if (await hasAnyFileUnder(path.join(dir, DELTA_SPECS_DIR)).catch(() => false))
+        return true;
+    return hasSchemaOutput(dir, projectRoot);
+}
+/**
+ * Whether `dir` already holds a file exactly where the schema it resolves to
+ * would generate one - the signal `openspec status` itself uses to call an
+ * artifact done. It covers the subdirectory-rooted custom schema before any
+ * delta spec exists, when neither other signal can. A schema that cannot be
+ * resolved gives no signal, which leaves the other two in charge.
+ */
+function hasSchemaOutput(dir, projectRoot) {
+    try {
+        const schema = resolveSchema(resolveSchemaForChange(dir, undefined, projectRoot), projectRoot);
+        return schema.artifacts.some((artifact) => artifactOutputExists(dir, artifact.generates));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `dir` holds any file of its own. A change directory with content at
+ * its root - a custom schema's artifact under a name this module does not know,
+ * a README, a note - is never reported as a namespace folder. A namespace
+ * folder someone created with `mkdir` holds nothing but directories.
+ */
+async function hasOwnFile(dir) {
+    const entries = await fs
+        .readdir(dir, { withFileTypes: true })
+        .catch(() => []);
+    return entries.some((entry) => !entry.name.startsWith('.') && !entry.isDirectory());
+}
+/**
+ * Subdirectories of `dir`, or none when it cannot be read. This probe only ever
+ * adds a diagnostic, so an unreadable directory falls back to the behaviour
+ * that existed before it rather than failing the command around it.
+ */
+async function readSubdirectories(dir) {
+    const entries = await fs
+        .readdir(dir, { withFileTypes: true })
+        .catch(() => []);
+    return entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name);
+}
+/**
+ * Collects the nested change directories under `dir`, deepest search bounded by
+ * `MAX_NESTING_DEPTH`. A directory that carries a marker is reported and not
+ * descended into: its own `specs/` tree is part of that change, not a further
+ * nesting level.
+ */
+async function collectNested(dir, prefix, depth, found, projectRoot) {
+    if (depth > MAX_NESTING_DEPTH)
+        return;
+    for (const child of await readSubdirectories(dir)) {
+        const childPath = path.join(dir, child);
+        const id = `${prefix}/${child}`;
+        if (await looksLikeChange(childPath, projectRoot)) {
+            found.push(id);
+            continue;
+        }
+        await collectNested(childPath, id, depth + 1, found, projectRoot);
+    }
+}
+/**
+ * Reports whether the directory `changes/<name>/` is a namespace folder holding
+ * one or more nested change directories rather than a change of its own.
+ *
+ * Returns undefined for every ordinary change, including a scaffolded one with
+ * no artifacts yet: only a *nested* change directory distinguishes the two.
+ */
+export async function findNestedChangesIn(changesDir, name) {
+    // `archive` is not a change and never was, so its dated entries must not be
+    // read as nested changes and offered up for renaming. `list`, `status` and
+    // `validate` already exclude it; `change show` does not.
+    if (name === 'archive' || name.startsWith('.'))
+        return undefined;
+    const dir = path.join(changesDir, name);
+    // changes/ is always <root>/openspec/changes, for project and store roots.
+    const projectRoot = path.resolve(changesDir, '..', '..');
+    if (await looksLikeChange(dir, projectRoot))
+        return undefined;
+    if (await hasOwnFile(dir))
+        return undefined;
+    const nested = [];
+    await collectNested(dir, name, 1, nested, projectRoot);
+    if (nested.length === 0)
+        return undefined;
+    return { name, nested: nested.sort() };
+}
+/**
+ * The same check across every candidate directory under `changes/`, for the
+ * commands that enumerate rather than resolve a single name.
+ */
+export async function findNestedChanges(changesDir, names) {
+    const findings = await Promise.all(names.map((name) => findNestedChangesIn(changesDir, name)));
+    return findings.filter((finding) => finding !== undefined);
+}
+/**
+ * The stable phrase every nested-change diagnostic contains. Callers that have
+ * only the rendered message - `validate`'s next-steps, which branches on the
+ * exact issue it is advising about - recognise the case by this.
+ */
+export const NESTED_CHANGE_ISSUE_MARKER = 'is not a change: it is a folder wrapping';
+/** Flattens a namespace path into the change name OpenSpec would accept. */
+function flatten(nestedId) {
+    return nestedId.split('/').join('-');
+}
+/**
+ * The one explanation every surface prints, so the constraint and the way out
+ * read identically wherever a user meets them.
+ */
+export function describeNestedChange(finding) {
+    const list = finding.nested.map((id) => `openspec/changes/${id}/`).join(', ');
+    const example = flatten(finding.nested[0]);
+    return (`"${finding.name}" ${NESTED_CHANGE_ISSUE_MARKER} ${list}. ` +
+        'A change must be a directory directly under openspec/changes/, so those ' +
+        'nested directories are invisible to OpenSpec while the folder around them ' +
+        'is reported as a change. Nested paths are supported under openspec/specs/ ' +
+        `only. Rename each nested change to a flat name (for example "${example}").`);
+}
+//# sourceMappingURL=nested-change.js.map

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

@@ -21,6 +21,26 @@ export interface DiscoveredSpec {
  * recreate the exact data-loss class #1353 is closing.
  */
 export declare function discoverSpecFiles(specsRoot: string): Promise<DiscoveredSpec[]>;
+export interface UnreadDeltaFile {
+    /** File path relative to the specs root, forward-slash separated. */
+    path: string;
+    /** The spec.md the merge path reads for it, relative to the specs root. */
+    expected: string;
+}
+/**
+ * Markdown files under a change's specs/ that carry delta sections but are not
+ * a capability's `spec.md`, so discoverSpecFiles, and with it validate and
+ * archive, never reads them: `specs/user-auth.md`, or `specs/user-auth/delta.md`
+ * beside or instead of the capability's spec.md. The artifact graph's
+ * recursive specs/ markdown glob does match them, so status and apply report
+ * the specs as written while archive has nothing to merge. A `spec.md` at the
+ * specs/ root has its own check (#1385) and is not repeated here. Notes with
+ * no delta section are not deltas and are not reported. The walk matches
+ * discoverSpecFiles: dot entries are skipped, symlinked directories are not
+ * followed, and a dangling link is skipped. A missing root yields an empty
+ * list; any other read failure is thrown. Results are sorted by path.
+ */
+export declare function findUnreadDeltaFiles(specsRoot: string): Promise<UnreadDeltaFile[]>;
 /**
  * True when any regular non-dot file exists anywhere under the given
  * directory. Used by validate/archive to detect content under a change's

package/dist/utils/spec-discovery.js

@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
+import { parseDeltaSpec } from '../core/parsers/requirement-blocks.js';
 function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
     try {
         FileSystemUtils.assertPathWithin(specsRoot, specFile);
@@ -73,6 +74,64 @@ export async function discoverSpecFiles(specsRoot) {
     // guarantees the deterministic output the docstring promises.
     return results.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
+/**
+ * Markdown files under a change's specs/ that carry delta sections but are not
+ * a capability's `spec.md`, so discoverSpecFiles, and with it validate and
+ * archive, never reads them: `specs/user-auth.md`, or `specs/user-auth/delta.md`
+ * beside or instead of the capability's spec.md. The artifact graph's
+ * recursive specs/ markdown glob does match them, so status and apply report
+ * the specs as written while archive has nothing to merge. A `spec.md` at the
+ * specs/ root has its own check (#1385) and is not repeated here. Notes with
+ * no delta section are not deltas and are not reported. The walk matches
+ * discoverSpecFiles: dot entries are skipped, symlinked directories are not
+ * followed, and a dangling link is skipped. A missing root yields an empty
+ * list; any other read failure is thrown. Results are sorted by path.
+ */
+export async function findUnreadDeltaFiles(specsRoot) {
+    const results = [];
+    const walk = async (dir, segments) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR')
+                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]);
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            if (entry.name === 'spec.md' || !entry.name.toLowerCase().endsWith('.md'))
+                continue;
+            const filePath = path.join(dir, entry.name);
+            let content;
+            try {
+                if (entry.isSymbolicLink() && !(await fs.stat(filePath)).isFile())
+                    continue;
+                content = await fs.readFile(filePath, 'utf-8');
+            }
+            catch (err) {
+                // A dangling link is not content; anything else fails loudly.
+                if (err?.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+            if (!Object.values(parseDeltaSpec(content).sectionPresence).some(Boolean))
+                continue;
+            const capability = segments.length > 0 ? segments.join('/') : entry.name.slice(0, -'.md'.length);
+            results.push({ path: [...segments, entry.name].join('/'), expected: `${capability}/spec.md` });
+        }
+    };
+    await walk(specsRoot, []);
+    return results.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 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

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

@@ -1,5 +1,5 @@
 export interface ParsedTask {
-    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    /** Checkbox state: `[x]`/`[X]` is done, every other marker (and none) is not. */
     done: boolean;
     /** Task text after the checkbox, trimmed (may be empty). */
     description: string;

package/dist/utils/task-progress.js

@@ -3,22 +3,54 @@ import path from 'path';
 import { resolveArtifactOutputs, resolveSchema } from '../core/artifact-graph/index.js';
 import { resolveSchemaForChange } from './change-metadata.js';
 /**
- * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
+ * A Markdown task line: a list item carrying a checkbox that holds at most one
+ * non-whitespace marker - `[ ]`, `[x]`, `[]`, `[~]`, `[ x ]` all qualify - under
+ * any CommonMark list marker - `-`, `*`, `+`, or an ordered `1.` / `1)` of up
+ * to nine digits. Reading only `-` and `*` left an unchecked `1. [ ]` or
+ * `+ [ ]` task out of every count, so archive reported "✓ Complete" over it.
  *
  * 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.
  *
+ * The marker is no longer restricted to ` `/`x`/`X`, because a checkbox this
+ * pattern rejects is a line that counts toward neither the numerator nor the
+ * denominator: a tasks.md whose remaining work was written `- [~] ...`
+ * reported "✓ Complete" and archived with no incomplete-task warning, and
+ * marking items `[~]` *shrank* the denominator instead of leaving them counted
+ * as not-done (#1761). An empty `[]` and a padded `[ x]` were lost the same
+ * silent way. Only `x`/`X` means done, so every unrecognised marker reads as
+ * not-done - the conservative default, and no new concept: OpenSpec does not
+ * adopt `[~]` or any other marker's meaning, it just stops dropping the line.
+ *
  * 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.
+ * tightened here drops lines that used to count, and a task this parser drops
+ * is a task `openspec archive` stops warning about. The cost of the wide class
+ * is over-counting - `- [1] ...` in a tasks file now reads as one unfinished
+ * task - which is a loud, correctable false positive, unlike the silent loss.
+ *
+ * Where the width stops, and why: the marker is one token, so a *multi*
+ * character bracket stays unmatched. Widening to `[^\]]*` would swallow the
+ * commonest bullet in Markdown - `- [Some doc](./doc.md)`, whose `]` is
+ * followed by `(`, not by a space - and turn every link list into phantom
+ * unfinished work. A dropped `- [WIP] ...` is the accepted residue of keeping
+ * link bullets out; report it as a bug in this trade, not in the marker set.
+ *
+ * One-character labels need the same guard, which the width alone does not
+ * give: `- [A](https://example.com)` and `- [1](./one)` are a link bullet and
+ * a reference-link bullet, not tasks, yet their label is a single token and
+ * would match. So the closing bracket may not be followed by `(` or `[`, the
+ * only two characters that continue Markdown link syntax. A checkbox is
+ * followed by its description or by end of line, and `- [x]done` still parses.
+ * The one exception is a whitespace-only box: `- [ ](...)` and `- [ ][...]`
+ * matched the strict pattern as unfinished tasks, so they still count. The guard
+ * may drop only lines that could never hide open work.
  *
  * 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*(.*)/;
+const TASK_LINE_PATTERN = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s]?)\s*\](?![([])|\s+\])\s*(.*)/;
 /**
  * Parses every task line in a tasks file, in document order.
  *
@@ -34,7 +66,7 @@ export function parseTaskLines(content) {
     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() });
+            tasks.push({ done: (match[1] ?? '').toLowerCase() === 'x', description: match[2].trim() });
         }
     }
     return tasks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -44,20 +44,20 @@
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
-    "@vitest/ui": "^3.2.6",
+    "@vitest/ui": "^4.1.11",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^3.2.6"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "@inquirer/core": "^11.2.1",
     "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
-    "diff": "^9.0.0",
     "cross-spawn": "7.0.6",
+    "diff": "^9.0.0",
     "fast-glob": "^3.3.3",
     "ora": "^9.4.1",
     "yaml": "^2.8.3",

package/schemas/spec-driven/schema.yaml

@@ -18,7 +18,19 @@ artifacts:
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
       IMPORTANT: The Capabilities section is critical. It creates the contract between
-      proposal and specs phases. Research existing specs before filling this in.
+      proposal and specs phases. Research existing specs before filling this in:
+      run `openspec list --specs` for the project's capability inventory, then
+      `openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+      look related - that returns a capability's purpose and requirement texts
+      without pulling whole spec files into context. Append `--store "<id>"` to
+      both commands only for a registered standalone store, and keep `--type
+      spec`: a change and a spec sharing a name is otherwise an ambiguous-item
+      error. `openspec list` without `--specs` lists in-flight changes, not
+      specs - it never shows what the project already covers. Reuse an existing
+      capability's exact path instead of introducing a near-duplicate name.
+      The filtered read is only an overview. Before deciding what is already
+      covered or what should change, read each relevant spec in full, including
+      scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
       Each capability listed here will need a corresponding spec file.
 
       Every change must either declare at least one capability (new or
@@ -63,7 +75,7 @@ artifacts:
       `<capability-path>` is the spec directory relative to `specs/` (for example,
       `user-auth` or `identity/user-auth`). Preserve the full path:
       - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
-      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
       There must be at least one spec file unless the change's `.openspec.yaml`
       sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
@@ -83,7 +95,7 @@ artifacts:
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
 
-      New capabilities only: start the delta spec with a `## Purpose` section -
+      New capabilities only: the delta spec's first section is `## Purpose` -
       one or two sentences (50+ characters, or `openspec validate --strict`
       reports it as too brief) describing what the capability is for. Archive
       copies it into the main spec it creates; without it the new main spec is
@@ -108,8 +120,10 @@ artifacts:
       Common pitfall: Using MODIFIED with partial content loses detail at archive time.
       If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example (a new capability, so it opens with `## Purpose`):
+      Example (a new capability, so its first section is `## Purpose`):
       ```
+      # Spec Delta
+
       ## Purpose
 
       Lets users take their data out of the product in a portable format.
@@ -181,7 +195,10 @@ artifacts:
       bake an unstated assumption into the task list.
 
       **IMPORTANT: Follow the template below exactly.** The apply phase parses
-      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+      checkbox format to track progress. A box holding only `x` counts as done,
+      upper or lower case and with any spacing, so `- [ x]` is done too. Every
+      other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
+      unfinished. A line with no checkbox is not tracked at all.
 
       Guidelines:
       - Group related tasks under ## numbered headings
@@ -196,6 +213,8 @@ artifacts:
 
       Example:
       ```
+      # Tasks
+
       ## 1. Setup
 
       - [ ] 1.1 Create new module structure and verify expected files are present

package/schemas/spec-driven/templates/design.md

@@ -1,3 +1,5 @@
+# Design
+
 ## Context
 
 <!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->

package/schemas/spec-driven/templates/proposal.md

@@ -1,3 +1,5 @@
+# Proposal
+
 ## Why
 
 <!-- Explain the motivation for this change. What problem does this solve? Why now? -->

package/schemas/spec-driven/templates/spec.md

@@ -1,3 +1,5 @@
+# Spec Delta
+
 ## Purpose
 <!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
 

package/schemas/spec-driven/templates/tasks.md

@@ -1,3 +1,5 @@
+# Tasks
+
 ## 1. <!-- Task Group Name -->
 
 - [ ] 1.1 <!-- Task description -->