@fission-ai/openspec 1.13.0 → 1.13.2

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.13.0",
+  "version": "1.13.2",
   "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/core": "^12.0.0",
     "@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

@@ -95,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
@@ -120,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.
@@ -193,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
@@ -205,9 +210,18 @@ artifacts:
         that task's checkbox description. Use a separate verification task only
         when it checks broader integration or system behavior that spans
         multiple implementation tasks.
+      - Each task group MUST land the tests and documentation its own work
+        calls for. Do NOT collect testing or documentation into a final group -
+        when a late group first exercises work from an early one, the failures
+        cascade back through every group in between and force rework. A group
+        whose work calls for neither, such as scaffolding or dependency setup,
+        carries neither. A final group is for integration checks only, not for
+        the tests and docs an earlier group owed.
 
       Example:
       ```
+      # Tasks
+
       ## 1. Setup
 
       - [ ] 1.1 Create new module structure and verify expected files are present
@@ -217,6 +231,7 @@ artifacts:
 
       - [ ] 2.1 Implement data export function and verify the export test passes
       - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+      - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
       ```
 
       Reference specs for what needs to be built, design for how to build it.

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 -->