@fission-ai/openspec 1.7.0 → 1.9.0

package/dist/utils/task-progress.js

@@ -2,21 +2,49 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { resolveArtifactOutputs, resolveSchema } from '../core/artifact-graph/index.js';
 import { resolveSchemaForChange } from './change-metadata.js';
-const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
-const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
-export function countTasksFromContent(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++;
-            }
+/**
+ * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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*(.*)/;
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export function parseTaskLines(content) {
+    const tasks = [];
+    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() });
         }
     }
-    return { total, completed };
+    return tasks;
+}
+export function countTasksFromContent(content) {
+    const tasks = parseTaskLines(content);
+    return {
+        total: tasks.length,
+        completed: tasks.filter((task) => task.done).length,
+    };
 }
 /**
  * Identifies the change's tracked-tasks artifact: the artifact whose `generates`
@@ -36,24 +64,43 @@ function findTrackedTasksArtifact(schema) {
  * when the schema cannot be resolved or no tracked-tasks artifact exists.
  * `resolveSchema` throws on an unresolvable/misnamed schema; we swallow that so
  * the caller falls back to a single top-level `tasks.md` and never crashes.
+ * A `schemaGlobCache`, when supplied, memoizes the schema-name → glob lookup for
+ * the duration of one run.
  */
-function resolveTrackedTasksGlob(changeDir, projectRoot) {
+function resolveTrackedTasksGlob(changeDir, projectRoot, schemaGlobCache) {
     try {
         const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot);
+        if (schemaGlobCache?.has(schemaName))
+            return schemaGlobCache.get(schemaName);
         const schema = resolveSchema(schemaName, projectRoot);
-        return findTrackedTasksArtifact(schema)?.generates;
+        const generates = findTrackedTasksArtifact(schema)?.generates;
+        schemaGlobCache?.set(schemaName, generates);
+        return generates;
     }
     catch {
         return undefined;
     }
 }
-async function countSingleTopLevelTasksFile(changeDir) {
-    const tasksPath = path.join(changeDir, 'tasks.md');
+/** Resolves the task files selected by the schema's apply tracking rule. */
+export function resolveTaskFilesForChange(changeDir, projectRoot, schemaGlobCache) {
+    const generates = resolveTrackedTasksGlob(changeDir, projectRoot, schemaGlobCache);
+    return generates ? resolveArtifactOutputs(changeDir, generates) : [];
+}
+/**
+ * Reads one task file and counts its checkboxes. ENOENT (a glob file that
+ * vanished between resolve and read, or the absent single top-level `tasks.md`)
+ * means zero tasks, exactly as before. Any other error (permissions, I/O,
+ * ENOTDIR) is recorded in `unreadable` so a caller can surface it; the count
+ * still contributes zero, so existing callers see no change.
+ */
+async function countTaskFile(file, unreadable) {
     try {
-        const content = await fs.readFile(tasksPath, 'utf-8');
+        const content = await fs.readFile(file, 'utf-8');
         return countTasksFromContent(content);
     }
-    catch {
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            unreadable.push(file);
         return { total: 0, completed: 0 };
     }
 }
@@ -64,31 +111,36 @@ async function countSingleTopLevelTasksFile(changeDir) {
  * artifact (`resolveArtifactOutputs`) — so progress is no longer blind to nested
  * `tasks.md` files (#1202). Falls back to a single top-level `tasks.md` (exactly
  * as before) when the schema is unresolvable, no tracked-tasks artifact is found,
- * or the glob matches no file. Never throws.
+ * or the glob matches no file. Also reports task files that exist but could not
+ * be read. Per-file read errors are captured (never thrown); the only throw path
+ * is a malformed/unsafe schema whose glob resolution rejects (path traversal or
+ * a linked-directory cycle in `resolveArtifactOutputs`). Pass `schemaGlobCache`
+ * to memoize schema→glob resolution across many changes in one run.
  */
-export async function getTaskProgressForChange(changesDir, changeName, projectRoot) {
+export async function getTaskProgressDetailForChange(changesDir, changeName, projectRoot, schemaGlobCache) {
     const changeDir = path.join(changesDir, changeName);
-    const generates = resolveTrackedTasksGlob(changeDir, projectRoot);
-    if (generates) {
-        const files = resolveArtifactOutputs(changeDir, generates);
-        if (files.length > 0) {
-            let total = 0;
-            let completed = 0;
-            for (const file of files) {
-                try {
-                    const content = await fs.readFile(file, 'utf-8');
-                    const progress = countTasksFromContent(content);
-                    total += progress.total;
-                    completed += progress.completed;
-                }
-                catch {
-                    // Swallow files that vanish between glob and read, as before.
-                }
-            }
-            return { total, completed };
-        }
+    const files = resolveTaskFilesForChange(changeDir, projectRoot, schemaGlobCache);
+    const targets = files.length > 0 ? files : [path.join(changeDir, 'tasks.md')];
+    const unreadable = [];
+    let total = 0;
+    let completed = 0;
+    for (const file of targets) {
+        const progress = await countTaskFile(file, unreadable);
+        total += progress.total;
+        completed += progress.completed;
     }
-    return countSingleTopLevelTasksFile(changeDir);
+    return { total, completed, unreadable };
+}
+/**
+ * The task-completion counter `status`, `list`, and `archive` share. Delegates
+ * to `getTaskProgressDetailForChange` and drops the `unreadable` detail, so its
+ * returned totals are unchanged. Throws only on the same malformed/unsafe-schema
+ * glob-resolution path as that function (existing behavior; callers guard it as
+ * they did before).
+ */
+export async function getTaskProgressForChange(changesDir, changeName, projectRoot) {
+    const { total, completed } = await getTaskProgressDetailForChange(changesDir, changeName, projectRoot);
+    return { total, completed };
 }
 export function formatTaskStatus(progress) {
     if (progress.total === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/schemas/spec-driven/schema.yaml

@@ -13,8 +13,8 @@ artifacts:
       - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
       - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
       - **Capabilities**: Identify which specs will be created or modified:
-        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
-        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
       IMPORTANT: The Capabilities section is critical. It creates the contract between
@@ -60,8 +60,10 @@ artifacts:
       visible behavior, it likely does not belong in the spec.
 
       Create one spec file per capability listed in the proposal's Capabilities section.
-      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
-      - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
+      `<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.
 
       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`
@@ -89,10 +91,10 @@ artifacts:
       by hand. Do NOT add `## Purpose` to a delta for an existing capability -
       that spec already has one and the delta's is ignored. To change an
       existing capability's Purpose - including a leftover `TBD` placeholder -
-      edit `openspec/specs/<capability>/spec.md` directly.
+      edit `openspec/specs/<capability-path>/spec.md` directly.
 
       MODIFIED requirements workflow:
-      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+      1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
       2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
       3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
       4. Ensure header text matches exactly (whitespace-insensitive)

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

@@ -9,18 +9,20 @@
 ## Capabilities
 
 ### New Capabilities
-<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
-- `<name>`: <brief description of what this capability covers>
+<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
+     (e.g., user-auth or identity/user-auth) that follow the project's existing
+     spec organization. Each creates specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
 
 ### Modified Capabilities
 <!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
      Only list here if spec-level behavior changes. Each needs a delta spec file.
-     Use existing spec names from openspec/specs/. Leave empty if no requirement
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
      changes. A change with no capabilities at all (pure refactor, tooling, docs)
      must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
      a zero-delta change without that marker. Do not invent a requirement just to
      satisfy validation. -->
-- `<existing-name>`: <what requirement is changing>
+- `<existing-capability-path>`: <what requirement is changing>
 
 ## Impact