@fission-ai/openspec 1.5.0 → 1.6.0

package/dist/core/store/operations.js

@@ -4,6 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { promisify } from 'node:util';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { classifyOpenSpecDir, storePointerProblem, } from '../project-config.js';
 import { ANCHORED_OPENSPEC_DIRS, DIRECTORY_ANCHOR_FILE_NAME, OPENSPEC_ROOT_DIR, ensureOpenSpecRoot, inspectOpenSpecRoot, rollbackCreatedPaths, } from '../openspec-root.js';
 import { STORE_METADATA_DIR_NAME, getStoreMetadataDir, getStoreMetadataPath, getStoreRegistryPath, listStoreRegistryEntries, readStoreRegistryState, readOptionalStoreMetadataState, resolveGitStoreBackendConfig, validateStoreId, writeStoreMetadataState, } from './foundation.js';
 import { StoreError, makeStoreDiagnostic } from './errors.js';
@@ -53,6 +54,23 @@ function alreadyRegisteredDiagnostic(id) {
         target: 'store.registry',
     });
 }
+function assertNotConfigOnlyPointerRoot(storeRoot) {
+    const { hasPlanningShape, pointer } = classifyOpenSpecDir(storeRoot);
+    if (hasPlanningShape || pointer.filePath === null)
+        return;
+    if (pointer.malformed) {
+        throw new StoreError(`The store declaration in ${pointer.filePath} is invalid (${storePointerProblem(pointer.malformed)}).`, 'invalid_store_pointer', {
+            target: 'store.pointer',
+            fix: `Fix or remove the store: line in ${pointer.filePath} before registering this path as a store.`,
+        });
+    }
+    if (pointer.value !== undefined) {
+        throw new StoreError(`This repo's planning is externalized to store '${pointer.value}' (${pointer.filePath}); it is not itself a store root.`, 'store_root_pointer_declared', {
+            target: 'store.pointer',
+            fix: 'Register the checkout for the declared store, or remove the store: line first to convert this repo into a local store root.',
+        });
+    }
+}
 function createdPath(relativePath, absolutePath, kind) {
     return {
         relativePath,
@@ -233,6 +251,7 @@ async function prepareSetupPlan(input) {
     let metadata = null;
     let backend;
     if (kind === 'directory') {
+        assertNotConfigOnlyPointerRoot(storeRoot);
         metadata = await readStoreMetadataForOperation(storeRoot);
         if (metadata) {
             if (metadata.id !== id) {
@@ -442,6 +461,7 @@ export async function registerExistingStore(input) {
             fix: 'Pass an existing store directory.',
         });
     }
+    assertNotConfigOnlyPointerRoot(storeRoot);
     const openspecRoot = await inspectOpenSpecRoot(storeRoot);
     if (!openspecRoot.healthy) {
         const problems = openspecRoot.diagnostics.map((diagnostic) => diagnostic.message).join(' ') ||

package/dist/core/templates/skill-templates.d.ts

@@ -8,6 +8,7 @@ export { getExploreSkillTemplate, getOpsxExploreCommandTemplate } from './workfl
 export { getNewChangeSkillTemplate, getOpsxNewCommandTemplate } from './workflows/new-change.js';
 export { getContinueChangeSkillTemplate, getOpsxContinueCommandTemplate } from './workflows/continue-change.js';
 export { getApplyChangeSkillTemplate, getOpsxApplyCommandTemplate } from './workflows/apply-change.js';
+export { getUpdateChangeSkillTemplate, getOpsxUpdateCommandTemplate } from './workflows/update-change.js';
 export { getFfChangeSkillTemplate, getOpsxFfCommandTemplate } from './workflows/ff-change.js';
 export { getSyncSpecsSkillTemplate, getOpsxSyncCommandTemplate } from './workflows/sync-specs.js';
 export { getArchiveChangeSkillTemplate, getOpsxArchiveCommandTemplate } from './workflows/archive-change.js';

package/dist/core/templates/skill-templates.js

@@ -7,6 +7,7 @@ export { getExploreSkillTemplate, getOpsxExploreCommandTemplate } from './workfl
 export { getNewChangeSkillTemplate, getOpsxNewCommandTemplate } from './workflows/new-change.js';
 export { getContinueChangeSkillTemplate, getOpsxContinueCommandTemplate } from './workflows/continue-change.js';
 export { getApplyChangeSkillTemplate, getOpsxApplyCommandTemplate } from './workflows/apply-change.js';
+export { getUpdateChangeSkillTemplate, getOpsxUpdateCommandTemplate } from './workflows/update-change.js';
 export { getFfChangeSkillTemplate, getOpsxFfCommandTemplate } from './workflows/ff-change.js';
 export { getSyncSpecsSkillTemplate, getOpsxSyncCommandTemplate } from './workflows/sync-specs.js';
 export { getArchiveChangeSkillTemplate, getOpsxArchiveCommandTemplate } from './workflows/archive-change.js';

package/dist/core/templates/workflows/update-change.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Skill Template Workflow Modules
+ *
+ * This file is generated by splitting the legacy monolithic
+ * templates file into workflow-focused modules.
+ */
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getUpdateChangeSkillTemplate(): SkillTemplate;
+export declare function getOpsxUpdateCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=update-change.d.ts.map

package/dist/core/templates/workflows/update-change.js

@@ -0,0 +1,167 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+export function getUpdateChangeSkillTemplate() {
+    return {
+        name: 'openspec-update-change',
+        description: "Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.",
+        instructions: `Revise a change's existing planning artifacts and keep them coherent. Never edit code.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from \`schema\` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from \`lastModified\` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Get the change's artifacts**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+   Parse the JSON to understand current state. The response includes:
+   - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
+   - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
+   - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
+
+   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
+
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+
+3. **Understand the request**
+   - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
+   - If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
+
+4. **Read and reconcile**
+   - Read the artifact(s) the request touches and the change's other existing artifacts.
+   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Note everything that is now inconsistent, missing, or contradictory.
+   - Revise only files that already exist (\`existingOutputPaths\`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to \`/opsx:continue\` to create them.
+   - If the change is already coherent, say so and make no edits.
+
+5. **Confirm and apply, one artifact at a time**
+   - Show each proposed revision and why. Write only after the user confirms.
+   - If the user rejects a revision, do not write it - leave that artifact unchanged.
+   - When a substantial rewrite is needed, get that artifact's rules and template first:
+     \`\`\`bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     \`\`\`
+
+6. **Point to the next step (guidance only - NEVER act on it)**
+   - Artifacts still missing -> suggest \`/opsx:continue\` to create them.
+   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest \`/opsx:apply\` to carry the delta into code.
+   - Everything done and implemented -> suggest \`/opsx:archive\`.
+
+**Output**
+
+After each invocation, show:
+- Which artifacts were revised (and which proposed revisions were rejected)
+- Anything deferred to \`/opsx:continue\` (not-yet-created artifacts or files)
+- Where the change stands and the recommended next command
+
+**Guardrails**
+- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`/opsx:apply\`.
+- Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
+- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
+- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
+- Confirm every edit with the user before writing.
+- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).`,
+        license: 'MIT',
+        compatibility: 'Requires openspec CLI.',
+        metadata: { author: 'openspec', version: '1.0' },
+    };
+}
+export function getOpsxUpdateCommandTemplate() {
+    return {
+        name: 'OPSX: Update',
+        description: "Update a change - revise existing planning artifacts and keep them coherent (Experimental)",
+        category: 'Workflow',
+        tags: ['workflow', 'artifacts', 'experimental'],
+        content: `Revise a change's existing planning artifacts and keep them coherent. Never edit code.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: Optionally specify a change name after \`/opsx:update\` (e.g., \`/opsx:update add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from \`schema\` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from \`lastModified\` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Get the change's artifacts**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+   Parse the JSON to understand current state. The response includes:
+   - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
+   - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
+   - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
+
+   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
+
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+
+3. **Understand the request**
+   - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
+   - If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
+
+4. **Read and reconcile**
+   - Read the artifact(s) the request touches and the change's other existing artifacts.
+   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Note everything that is now inconsistent, missing, or contradictory.
+   - Revise only files that already exist (\`existingOutputPaths\`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to \`/opsx:continue\` to create them.
+   - If the change is already coherent, say so and make no edits.
+
+5. **Confirm and apply, one artifact at a time**
+   - Show each proposed revision and why. Write only after the user confirms.
+   - If the user rejects a revision, do not write it - leave that artifact unchanged.
+   - When a substantial rewrite is needed, get that artifact's rules and template first:
+     \`\`\`bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     \`\`\`
+
+6. **Point to the next step (guidance only - NEVER act on it)**
+   - Artifacts still missing -> suggest \`/opsx:continue\` to create them.
+   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest \`/opsx:apply\` to carry the delta into code.
+   - Everything done and implemented -> suggest \`/opsx:archive\`.
+
+**Output**
+
+After each invocation, show:
+- Which artifacts were revised (and which proposed revisions were rejected)
+- Anything deferred to \`/opsx:continue\` (not-yet-created artifacts or files)
+- Where the change stands and the recommended next command
+
+**Guardrails**
+- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`/opsx:apply\`.
+- Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
+- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
+- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
+- Confirm every edit with the user before writing.
+- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).`
+    };
+}
+//# sourceMappingURL=update-change.js.map

package/dist/core/update.js

@@ -130,8 +130,8 @@ export class UpdateCommand {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for tools where filename === command name (oh-my-pi, opencode, pi)
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi' || tool.value === 'oh-my-pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
@@ -523,8 +523,8 @@ export class UpdateCommand {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for tools where filename === command name (oh-my-pi, opencode, pi)
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi' || tool.value === 'oh-my-pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }

package/dist/core/validation/validator.d.ts

@@ -18,6 +18,13 @@ export declare class Validator {
      * - No duplicates within sections; no cross-section conflicts per spec
      */
     validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    /**
+     * Recursively collect every delta `spec.md` under a change's specs directory,
+     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
+     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
+     * Returns absolute paths, sorted for deterministic issue ordering.
+     */
+    private findDeltaSpecFiles;
     private convertZodErrors;
     private applySpecRules;
     private applyChangeRules;

package/dist/core/validation/validator.js

@@ -4,7 +4,8 @@ import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 export class Validator {
@@ -98,12 +99,12 @@ export class Validator {
         const missingHeaderSpecs = [];
         const emptySectionSpecs = [];
         try {
-            const entries = await fs.readdir(specsDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                const specName = entry.name;
-                const specFile = path.join(specsDir, specName, 'spec.md');
+            // Discover delta specs at any depth so the nested multi-area layout
+            // (specs/<area>/<capability>/spec.md) is validated, not just the
+            // one-level specs/<capability>/spec.md layout (#1182b). The spec-driven
+            // specs glob is specs/**/*.md; delta files are always named spec.md.
+            const specFiles = await this.findDeltaSpecFiles(specsDir);
+            for (const specFile of specFiles) {
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
@@ -112,7 +113,24 @@ export class Validator {
                     continue;
                 }
                 const plan = parseDeltaSpec(content);
-                const entryPath = `${specName}/spec.md`;
+                const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
+                // Surface (as INFO, never a failure) the non-canonical level-3 headers
+                // the delta reader skipped while parsing ADDED/MODIFIED sections —
+                // without this note a stray divider like "### Documentation
+                // Requirements" would pass validate <change> while failing
+                // archive/validate <spec>. The list comes from the parse itself, so it
+                // reflects exactly what the reader skipped.
+                for (const stray of plan.skippedHeaders) {
+                    const nameless = /^requirement:?$/i.test(stray.header);
+                    issues.push({
+                        level: 'INFO',
+                        path: entryPath,
+                        line: stray.line,
+                        message: nameless
+                            ? `Header "### ${stray.header}" in ${stray.section} is missing a requirement name and is ignored by validation. Add a name, e.g. "### Requirement: <name>".`
+                            : `Header "### ${stray.header}" in ${stray.section} is not a "### Requirement:" header and is ignored by validation. Use "### Requirement: ${stray.header}" if it should be validated as a requirement.`,
+                    });
+                }
                 const sectionNames = [];
                 if (plan.sectionPresence.added)
                     sectionNames.push('## ADDED Requirements');
@@ -147,10 +165,16 @@ export class Validator {
                     }
                     const requirementText = this.extractRequirementText(block.raw);
                     if (!requirementText) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" is missing requirement text` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: this.containsShallOrMust(block.name)
+                                ? this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name)
+                                : `ADDED "${block.name}" is missing requirement text`,
+                        });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('ADDED', block.name) });
+                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name) });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -169,10 +193,16 @@ export class Validator {
                     }
                     const requirementText = this.extractRequirementText(block.raw);
                     if (!requirementText) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" is missing requirement text` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: this.containsShallOrMust(block.name)
+                                ? this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name)
+                                : `MODIFIED "${block.name}" is missing requirement text`,
+                        });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage('MODIFIED', block.name) });
+                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name) });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -256,6 +286,35 @@ export class Validator {
         }
         return this.createReport(issues);
     }
+    /**
+     * Recursively collect every delta `spec.md` under a change's specs directory,
+     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
+     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
+     * Returns absolute paths, sorted for deterministic issue ordering.
+     */
+    async findDeltaSpecFiles(specsDir) {
+        const results = [];
+        const walk = async (dir) => {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await walk(full);
+                }
+                else if (entry.isFile() && entry.name === 'spec.md') {
+                    results.push(full);
+                }
+            }
+        };
+        await walk(specsDir);
+        return results.sort();
+    }
     convertZodErrors(error) {
         return error.issues.map(err => {
             let message = err.message;
@@ -302,6 +361,23 @@ export class Validator {
                 });
             }
         });
+        // SHALL/MUST body-keyword enforcement for main specs (#1156). The main-spec
+        // parser collapses the requirement header into `text`, so we recover the
+        // header+body pairs here (the same source the delta path trusts) and reuse
+        // the delta detection: a body that omits the keyword errors, with the
+        // targeted "move it to the body line" hint when the keyword is in the header
+        // only and the generic message otherwise. Emitted exactly once per
+        // requirement (the Zod refine that used to emit a generic error is removed).
+        extractRequirementsSection(content).bodyBlocks.forEach((block, index) => {
+            const requirementText = this.extractRequirementText(block.raw);
+            if (!requirementText || !this.containsShallOrMust(requirementText)) {
+                issues.push({
+                    level: 'ERROR',
+                    path: `requirements[${index}]`,
+                    message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name),
+                });
+            }
+        });
         return issues;
     }
     applyChangeRules(change, content) {
@@ -376,30 +452,16 @@ export class Validator {
         return report.valid;
     }
     extractRequirementText(blockRaw) {
-        const lines = blockRaw.split('\n');
-        // Skip header line (index 0)
-        let i = 1;
-        // Find the first substantial text line, skipping metadata and blank lines
-        for (; i < lines.length; i++) {
-            const line = lines[i];
-            // Stop at scenario headers
-            if (/^####\s+/.test(line))
-                break;
-            const trimmed = line.trim();
-            // Skip blank lines
-            if (trimmed.length === 0)
-                continue;
-            // Skip metadata lines (lines starting with ** like **ID**, **Priority**, etc.)
-            if (/^\*\*[^*]+\*\*:/.test(trimmed))
-                continue;
-            // Found first non-metadata, non-blank line - this is the requirement text
-            return trimmed;
-        }
-        // No requirement text found
-        return undefined;
+        // Delegate to the shared, fence-/metadata-/multi-line-aware body reader.
+        // Validation intentionally does not use the parser/display header-title
+        // fallback for canonical `### Requirement:` blocks: #1280 requires a
+        // SHALL/MUST that appears only in the header to receive the body-keyword
+        // hint. Line 0 is the `### Requirement: ...` header.
+        const [, ...bodyLines] = blockRaw.split('\n');
+        return extractRequirementBodyShared(bodyLines) || undefined;
     }
     containsShallOrMust(text) {
-        return /\b(SHALL|MUST)\b/.test(text);
+        return containsShallOrMustShared(text);
     }
     /**
      * Build an error message for a requirement block whose body lacks SHALL/MUST.
@@ -411,16 +473,17 @@ export class Validator {
      * on the requirement body line (the line right after the header), so we point
      * the author at that exact fix when the keyword is found in the header only.
      */
-    buildMissingShallOrMustMessage(action, blockName) {
-        const base = `${action} "${blockName}" must contain SHALL or MUST`;
+    buildMissingShallOrMustMessage(prefix, blockName) {
+        const base = `${prefix} must contain SHALL or MUST`;
         if (this.containsShallOrMust(blockName)) {
             return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`;
         }
         return base;
     }
     countScenarios(blockRaw) {
-        const matches = blockRaw.match(/^####\s+/gm);
-        return matches ? matches.length : 0;
+        // Fence-aware count via the shared reader: a `#### Scenario:` inside a fenced
+        // example is not a real scenario. Drop the header line (index 0).
+        return countScenariosShared(blockRaw.split('\n').slice(1));
     }
     formatSectionList(sections) {
         if (sections.length === 0)

package/dist/core/view.js

@@ -70,7 +70,7 @@ export class ViewCommand {
         const entries = fs.readdirSync(changesDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'archive') {
-                const progress = await getTaskProgressForChange(changesDir, entry.name);
+                const progress = await getTaskProgressForChange(changesDir, entry.name, path.dirname(openspecDir));
                 if (progress.total === 0) {
                     // No tasks defined yet - still in planning/draft phase
                     draft.push({ name: entry.name });

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

@@ -3,6 +3,15 @@ export interface TaskProgress {
     completed: number;
 }
 export declare function countTasksFromContent(content: string): TaskProgress;
-export declare function getTaskProgressForChange(changesDir: string, changeName: string): Promise<TaskProgress>;
+/**
+ * Computes a change's task progress by resolving its tracked-tasks artifact and
+ * counting checkboxes across every file matched by that artifact's `generates`
+ * glob — the same file-resolution `openspec status` uses to detect the tasks
+ * 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.
+ */
+export declare function getTaskProgressForChange(changesDir: string, changeName: string, projectRoot: string): Promise<TaskProgress>;
 export declare function formatTaskStatus(progress: TaskProgress): string;
 //# sourceMappingURL=task-progress.d.ts.map

package/dist/utils/task-progress.js

@@ -1,5 +1,7 @@
 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) {
@@ -16,8 +18,37 @@ export function countTasksFromContent(content) {
     }
     return { total, completed };
 }
-export async function getTaskProgressForChange(changesDir, changeName) {
-    const tasksPath = path.join(changesDir, changeName, 'tasks.md');
+/**
+ * Identifies the change's tracked-tasks artifact: the artifact whose `generates`
+ * equals the schema's `apply.tracks` value, falling back to the artifact with id
+ * `tasks` when no `apply` block declares what it tracks. (`apply.tracks` is a
+ * filename that *selects* the artifact; the glob is that artifact's `generates`.)
+ */
+function findTrackedTasksArtifact(schema) {
+    const tracks = schema.apply?.tracks;
+    if (tracks != null) {
+        return schema.artifacts.find((a) => a.generates === tracks);
+    }
+    return schema.artifacts.find((a) => a.id === 'tasks');
+}
+/**
+ * Resolves the tracked-tasks artifact's output glob for a change, or undefined
+ * 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.
+ */
+function resolveTrackedTasksGlob(changeDir, projectRoot) {
+    try {
+        const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot);
+        const schema = resolveSchema(schemaName, projectRoot);
+        return findTrackedTasksArtifact(schema)?.generates;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function countSingleTopLevelTasksFile(changeDir) {
+    const tasksPath = path.join(changeDir, 'tasks.md');
     try {
         const content = await fs.readFile(tasksPath, 'utf-8');
         return countTasksFromContent(content);
@@ -26,6 +57,39 @@ export async function getTaskProgressForChange(changesDir, changeName) {
         return { total: 0, completed: 0 };
     }
 }
+/**
+ * Computes a change's task progress by resolving its tracked-tasks artifact and
+ * counting checkboxes across every file matched by that artifact's `generates`
+ * glob — the same file-resolution `openspec status` uses to detect the tasks
+ * 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.
+ */
+export async function getTaskProgressForChange(changesDir, changeName, projectRoot) {
+    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 };
+        }
+    }
+    return countSingleTopLevelTasksFile(changeDir);
+}
 export function formatTaskStatus(progress) {
     if (progress.total === 0)
         return 'No tasks';

package/package.json

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