@fission-ai/openspec 1.13.1 → 1.14.0

package/dist/core/project-config.js

@@ -181,6 +181,50 @@ function parseDeclarationList(raw) {
     return byId.size > 0 ? [...byId.values()] : undefined;
 }
 export const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit, shared with the references index
+/**
+ * Build the warning for an artifact whose `rules:` list is not an array of
+ * strings. Names the offending index and what YAML actually produced there, so
+ * a config that silently loses an entire rule set can be fixed without
+ * bisecting the list by hand. A bare `-` item containing an unquoted ": " is the
+ * common cause: YAML reads it as a mapping, so the hint points at quoting.
+ */
+function describeRulesShapeError(artifactId, rules) {
+    const base = `Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`;
+    if (!Array.isArray(rules)) {
+        return `${base}. rules.${artifactId} is ${describeYamlType(rules)}`;
+    }
+    const bad = rules
+        .map((rule, index) => ({ rule, index }))
+        .filter(({ rule }) => typeof rule !== 'string');
+    if (bad.length === 0) {
+        return base;
+    }
+    // Name every offending index with its own shape, so a mixed list does not
+    // have to be re-bisected one item at a time.
+    const details = bad
+        .map(({ rule, index }) => `rules.${artifactId}[${index}] is ${describeYamlType(rule)}`)
+        .join('; ');
+    // A bare `-` item with an unquoted ": " is the common cause: YAML reads it as
+    // a mapping. Say so rather than leaving the reader to work out the quoting.
+    const hasMapping = bad.some(({ rule }) => rule !== null && typeof rule === 'object' && !Array.isArray(rule));
+    const hint = hasMapping
+        ? ' — an unquoted ": " makes YAML read the item as a key/value pair; quote the whole scalar to keep it a string.'
+        : '';
+    return `${base}. ${details}${hint}`;
+}
+/** Name a YAML value's shape in a warning, e.g. "a mapping" or "a number". */
+function describeYamlType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'a nested list';
+    const type = typeof value;
+    if (type === 'object')
+        return 'a mapping';
+    if (type === 'number' || type === 'boolean')
+        return `a ${type}`;
+    return `a ${type}`;
+}
 /**
  * Read and parse openspec/config.yaml from project root.
  * Uses resilient parsing - validates each field independently using Zod safeParse.
@@ -265,7 +309,7 @@ export function readProjectConfig(projectRoot) {
                         }
                     }
                     else {
-                        console.warn(`Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`);
+                        console.warn(describeRulesShapeError(artifactId, rules));
                     }
                 }
                 if (hasValidRules) {

package/dist/core/references.js

@@ -191,7 +191,9 @@ export function renderReferencedStoresSection(entries) {
  * let hostile content forge instruction lines (slice 6.1 hardening).
  */
 export function sanitizeInline(value, maxLength = 300) {
-    const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    const flattened = value
+        .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u206f]+/g, ' ')
+        .trim();
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
 }
 /**

package/dist/core/root-selection.d.ts

@@ -94,6 +94,12 @@ export declare function toRootOutput(root: ResolvedOpenSpecRoot): RootOutput;
 export declare function isStoreSelectedRoot(root: ResolvedOpenSpecRoot): root is ResolvedOpenSpecRoot & {
     storeId: string;
 };
+/**
+ * The project on the current path whose `store:` pointer names `storeId`,
+ * as a canonical path (the root walk resolves aliases). Null when the
+ * nearest root is a real planning root or points at a different store.
+ */
+export declare function findDeclaringProjectRoot(storeId: string, startPath?: string): string | null;
 /**
  * Human-mode verification signal for a selected store. Written to stderr so
  * raw-Markdown and agent-consumed stdout payloads stay clean.

package/dist/core/root-selection.js

@@ -309,6 +309,22 @@ export function toRootOutput(root) {
 export function isStoreSelectedRoot(root) {
     return root.storeId !== undefined;
 }
+/**
+ * The project on the current path whose `store:` pointer names `storeId`,
+ * as a canonical path (the root walk resolves aliases). Null when the
+ * nearest root is a real planning root or points at a different store.
+ */
+export function findDeclaringProjectRoot(storeId, startPath = process.cwd()) {
+    const nearestRoot = findQualifyingRootSync(startPath);
+    if (!nearestRoot) {
+        return null;
+    }
+    const { hasPlanningShape, pointer } = classifyOpenSpecDir(nearestRoot);
+    if (hasPlanningShape || pointer.value !== storeId) {
+        return null;
+    }
+    return nearestRoot;
+}
 /**
  * Human-mode verification signal for a selected store. Written to stderr so
  * raw-Markdown and agent-consumed stdout payloads stay clean.

package/dist/core/schemas/base.schema.d.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod';
 export declare const ScenarioSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     rawText: z.ZodString;
 }, z.core.$strip>;
 export declare const RequirementSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     text: z.ZodString;
     scenarios: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         rawText: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/core/schemas/base.schema.js

@@ -1,9 +1,15 @@
 import { z } from 'zod';
 import { VALIDATION_MESSAGES } from '../validation/constants.js';
 export const ScenarioSchema = z.object({
+    // Header text without `####`, the closing `#` run, and the `Scenario:`
+    // prefix. Optional so objects built outside the parser still validate.
+    name: z.string().optional(),
     rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
 });
 export const RequirementSchema = z.object({
+    // Header text without `###` and the `Requirement:` prefix: the name archive
+    // matches MODIFIED, REMOVED and RENAMED entries against.
+    name: z.string().optional(),
     // SHALL/MUST body-keyword enforcement lives in the imperative validator
     // (Validator.applySpecRules), not here: the parser collapses the requirement
     // header into `text`, so a Zod refine on `text` cannot tell "keyword in header

package/dist/core/schemas/change.schema.d.ts

@@ -15,14 +15,18 @@ export declare const DeltaSchema: z.ZodObject<{
     }>;
     description: z.ZodString;
     requirement: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
@@ -45,14 +49,18 @@ export declare const ChangeSchema: z.ZodObject<{
         }>;
         description: z.ZodString;
         requirement: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             text: z.ZodString;
             scenarios: z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
                 rawText: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             text: z.ZodString;
             scenarios: z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
                 rawText: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;

package/dist/core/schemas/spec.schema.d.ts

@@ -3,8 +3,10 @@ export declare const SpecSchema: z.ZodObject<{
     name: z.ZodString;
     overview: z.ZodString;
     requirements: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/dist/core/specs-apply.d.ts

@@ -102,6 +102,26 @@ export declare function retireSpec(update: SpecUpdate, mainSpecsDir: string, opt
     displacedPath?: string;
 }>;
 export declare function finalizeRetiredSpec(target: string, displacedPath: string, mainSpecsDir: string): Promise<void>;
+/**
+ * Remove now-empty directories from `startDir` upward, never leaving the real
+ * `boundaryDir` and never removing that directory itself.
+ *
+ * The boundary is a parameter rather than the specs root directly so the walk's
+ * containment is stated at the call site, where the root it must not escape is
+ * the thing being reasoned about.
+ *
+ * The guard re-runs every iteration, so stepping to the LEXICAL parent is safe:
+ * a parent that is not the real one is simply re-resolved and rejected. Errors
+ * are swallowed and end the walk - ENOTEMPTY and ENOENT are correct outcomes (a
+ * file arriving mid-walk must win), and a permissions failure leaves an empty
+ * directory behind, which the next successful archive clears.
+ *
+ * Not race-free: an attacker who can swap an ancestor between the check and the
+ * `rmdir` could get an empty directory outside the root removed. Closing that
+ * needs fd-relative syscalls Node does not expose, and it requires local write
+ * access to `openspec/specs` during an archive.
+ */
+export declare function pruneEmptyDirs(startDir: string, boundaryDir: string): Promise<void>;
 /**
  * Write an updated spec to disk.
  */

package/dist/core/specs-apply.js

@@ -8,13 +8,14 @@ import { promises as fs } from 'fs';
 import { randomUUID } from 'crypto';
 import path from 'path';
 import chalk from 'chalk';
-import { extractRequirementsSection, findMissingCurrentScenarios, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { MIN_PURPOSE_LENGTH, PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from './validation/constants.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { matchLineEnding } from '../utils/line-endings.js';
 function isLexicallyWithin(allowedDirectory, targetPath) {
     const relative = path.relative(path.resolve(allowedDirectory), path.resolve(targetPath));
     return (relative === '' ||
@@ -383,9 +384,9 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }
-        const missingScenarios = findMissingCurrentScenarios(currentBlock, mod);
-        if (missingScenarios.length > 0) {
-            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
+        const scenarioDiff = diffScenarioNames(currentBlock, mod);
+        if (scenarioDiff.missing.length > 0) {
+            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${scenarioDiff.missing.map(name => `"${name}"`).join(', ')}. ${describeScenarioBalance(scenarioDiff)} Refresh the change spec before archiving to avoid dropping scenarios.`);
         }
         // Identical content means the modification was already synced to the
         // baseline (early-sync pattern) — count only real replacements, so a
@@ -995,7 +996,7 @@ async function isInsideRealDir(realPath, dir) {
  * needs fd-relative syscalls Node does not expose, and it requires local write
  * access to `openspec/specs` during an archive.
  */
-async function pruneEmptyDirs(startDir, boundaryDir) {
+export async function pruneEmptyDirs(startDir, boundaryDir) {
     let boundary;
     try {
         boundary = await fs.realpath(boundaryDir);
@@ -1040,11 +1041,23 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
     // Create target directory if needed
     const targetDir = path.dirname(update.target);
     await fs.mkdir(targetDir, { recursive: true });
+    // The parsers normalize CRLF to LF on read, so `rebuilt` is always LF. Write
+    // it back with the convention the file already used, or a Windows checkout
+    // (core.autocrlf=true) sees every line of the spec change when one
+    // requirement moved. A spec that does not exist yet stays LF.
+    // Only a missing file means "no convention to match". Swallowing every error
+    // would read an existing but unreadable spec as absent and rewrite it as LF.
+    const previous = await fs.readFile(update.target, 'utf-8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    const toWrite = previous === undefined ? rebuilt : matchLineEnding(rebuilt, previous);
     await options.beforeMutate?.();
     // Preserve the established in-place write semantics: symlink referents,
     // hard-linked specs, ACLs, extended attributes, and filesystems without hard
     // links must continue to behave as they did before capability retirement.
-    await fs.writeFile(update.target, rebuilt);
+    await fs.writeFile(update.target, toWrite);
     if (options.silent)
         return;
     const specName = update.id;

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

@@ -56,7 +56,7 @@ ${PROJECT_ROOT_GUARD}
    This returns:
    - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
    - Progress (total, complete, remaining)
-   - Task list with status
+   - Task list with status, source path, and source line
    - Dynamic instruction based on current state
    - Optional \`context\`: current required project instruction input from the selected root
    - Optional \`operationGuidance\`: current advisory guidance for apply
@@ -108,7 +108,9 @@ ${PROJECT_ROOT_GUARD}
    - Show which task is being worked on
    - Make the code changes required
    - Keep changes minimal and focused
-   - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
+   - Before editing, confirm the checkbox at the returned \`sourcePath\` and \`line\` still matches the task description; if it does not, rerun the apply instructions and use the refreshed location
+   - Mark the task complete at its returned \`sourcePath\` and \`line\`: \`- [ ]\` → \`- [x]\`
+   - Rerun the apply instructions and confirm that task is now done and progress changed
    - Continue to next task
 
    **Pause if:**
@@ -188,6 +190,7 @@ What would you like to do?
 - When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
 - Only mark a task \`- [x]\` when its specified behavior is fully implemented, not when it is partially done or deferred
 - Use contextFiles from CLI output, don't assume specific file names
+- Use each task's sourcePath and line to update its exact checkbox
 - Do not use context or operation guidance as proof that a task is complete
 - Apply relevant project context; report conflicts with controlling workflow inputs
 - Consider every guidance entry; explain any inapplicable or conflicting advice

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

@@ -81,20 +81,27 @@ ${PROJECT_ROOT_GUARD}
 
 3. **Check task completion status**
 
-   Read the tasks file (typically \`tasks.md\`) to check for incomplete tasks.
-
-   A checkbox is complete when its only content is \`x\` or \`X\`; spacing inside
-   the brackets does not matter, so \`- [ x]\` counts as complete too. Every
-   other marker is incomplete - \`- [ ]\`, an empty \`- []\`, and markers OpenSpec
-   assigns no meaning to such as \`- [~]\` or \`- [-]\`. Never read an unfamiliar
-   marker as complete.
+   Run \`openspec list --json\` with the same selected-root flags and find the
+   entry in \`changes\` whose \`name\` exactly matches the selected change.
+   Require exactly one match and nonnegative integer \`totalTasks\` and
+   \`completedTasks\`, with \`completedTasks <= totalTasks\`. The CLI resolves
+   the schema's tracked task files, including custom artifact names, output
+   paths, and globs.
+   Incomplete tasks = \`totalTasks - completedTasks\`.
+
+   Do not infer task completion from artifact status or the absence of a
+   top-level \`tasks.md\`. If the lookup fails, returns invalid JSON, omits or
+   duplicates the selected change, or returns invalid counts, report the problem
+   and stop before syncing or archiving.
+   The CLI counts only \`x\`/\`X\` checkbox markers as complete;
+   other markers, including unfamiliar ones, remain incomplete.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
    - Ask the user to confirm they want to proceed
    - Proceed if user confirms
 
-   **If no tasks file exists:** Proceed without task-related warning.
+   **If \`totalTasks\` is zero:** Proceed without a task-related warning.
 
 4. **Assess delta spec sync state**
 
@@ -133,12 +140,23 @@ ${PROJECT_ROOT_GUARD}
    form of main specs produced by this merge; do not use them as archive guidance,
    change CLI behavior, or copy the rule text into any output file.
 
-   Then run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
+   Then ${optionalWorkflow('sync', 'run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge)', 'perform the delta-to-main-spec merge inline yourself (agent-driven intelligent merge)')} for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
+
+   If the sync reports any stop or blocking condition, treat the sync as failed.
+   Stop the archive immediately. Do not perform the post-sync content comparison and do not move its \`changeRoot\`.
+   Nothing has moved, so the user can fix the blocking condition or re-run the sync.
+
+   After the sync writes each main spec, verify its structure against the canonical sync contract:
+   - A new main spec starts with a \`# <capability> Specification\` title. An existing main spec keeps its title exactly as it is.
+   - Preserve existing \`## Purpose\` sections completely untouched for established main specs.
+   - For a new main spec, copy the delta \`## Purpose\` verbatim. Warn only if the purpose text is shorter than standard validation expects. Do not regenerate or rewrite existing authored purpose. If no usable \`## Purpose\` is provided, use the existing TBD Purpose behavior and warning.
+   - Verify that no delta-style section headers (\`## ADDED Requirements\`, \`## MODIFIED Requirements\`, \`## REMOVED Requirements\`, \`## RENAMED Requirements\`) remain in the main spec, adhering strictly to the sync workflow formatting rules.
+   - Requirement blocks the sync wrote or changed use \`### Requirement:\` headings, and their scenarios use \`#### Scenario:\` headings, under the spec's \`## Requirements\` section. Leave content the delta does not mention exactly as it is.
 
    Then re-run the comparison from the top of this step, including the explicitly retired, missing-spec case, against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
    - ADDED requirements present
    - MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
-   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
    - RENAMED requirements present under the new name and absent under the old one
 
    If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and \`changeRoot\` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
@@ -188,7 +206,7 @@ ${PROJECT_ROOT_GUARD}
 - Don't block archive on warnings - just inform and confirm
 - Preserve .openspec.yaml when moving to archive (it moves with the directory)
 - Show clear summary of what happened
-- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven)
+- If sync is requested, ${optionalWorkflow('sync', 'run the `openspec-sync-specs` workflow inline (agent-driven)', 'perform the delta-to-main-spec merge inline (agent-driven)')}
 - Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving \`changeRoot\`
 - If delta specs exist, always run the sync assessment and show the combined summary before prompting
 - Apply relevant runtime context and report conflicts; operation guidance remains advisory
@@ -274,20 +292,27 @@ ${PROJECT_ROOT_GUARD}
 
 3. **Check task completion status**
 
-   Read the tasks file (typically \`tasks.md\`) to check for incomplete tasks.
-
-   A checkbox is complete when its only content is \`x\` or \`X\`; spacing inside
-   the brackets does not matter, so \`- [ x]\` counts as complete too. Every
-   other marker is incomplete - \`- [ ]\`, an empty \`- []\`, and markers OpenSpec
-   assigns no meaning to such as \`- [~]\` or \`- [-]\`. Never read an unfamiliar
-   marker as complete.
+   Run \`openspec list --json\` with the same selected-root flags and find the
+   entry in \`changes\` whose \`name\` exactly matches the selected change.
+   Require exactly one match and nonnegative integer \`totalTasks\` and
+   \`completedTasks\`, with \`completedTasks <= totalTasks\`. The CLI resolves
+   the schema's tracked task files, including custom artifact names, output
+   paths, and globs.
+   Incomplete tasks = \`totalTasks - completedTasks\`.
+
+   Do not infer task completion from artifact status or the absence of a
+   top-level \`tasks.md\`. If the lookup fails, returns invalid JSON, omits or
+   duplicates the selected change, or returns invalid counts, report the problem
+   and stop before syncing or archiving.
+   The CLI counts only \`x\`/\`X\` checkbox markers as complete;
+   other markers, including unfamiliar ones, remain incomplete.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
    - Prompt user for confirmation to continue
    - Proceed if user confirms
 
-   **If no tasks file exists:** Proceed without task-related warning.
+   **If \`totalTasks\` is zero:** Proceed without a task-related warning.
 
 4. **Assess delta spec sync state**
 
@@ -328,10 +353,21 @@ ${PROJECT_ROOT_GUARD}
 
    Then ${SYNC_INLINE_HANDOFF} for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
 
+   If the sync reports any stop or blocking condition, treat the sync as failed.
+   Stop the archive immediately. Do not perform the post-sync content comparison and do not move its \`changeRoot\`.
+   Nothing has moved, so the user can fix the blocking condition or re-run the sync.
+
+   After the sync writes each main spec, verify its structure against the canonical sync contract:
+   - A new main spec starts with a \`# <capability> Specification\` title. An existing main spec keeps its title exactly as it is.
+   - Preserve existing \`## Purpose\` sections completely untouched for established main specs.
+   - For a new main spec, copy the delta \`## Purpose\` verbatim. Warn only if the purpose text is shorter than standard validation expects. Do not regenerate or rewrite existing authored purpose. If no usable \`## Purpose\` is provided, use the existing TBD Purpose behavior and warning.
+   - Verify that no delta-style section headers (\`## ADDED Requirements\`, \`## MODIFIED Requirements\`, \`## REMOVED Requirements\`, \`## RENAMED Requirements\`) remain in the main spec, adhering strictly to the sync workflow formatting rules.
+   - Requirement blocks the sync wrote or changed use \`### Requirement:\` headings, and their scenarios use \`#### Scenario:\` headings, under the spec's \`## Requirements\` section. Leave content the delta does not mention exactly as it is.
+
    Then re-run the comparison from the top of this step, including the explicitly retired, missing-spec case, against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
    - ADDED requirements present
    - MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
-   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
    - RENAMED requirements present under the new name and absent under the old one
 
    If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and \`changeRoot\` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.

package/dist/core/templates/workflows/bulk-archive-change.js

@@ -37,7 +37,7 @@ ${PROJECT_ROOT_GUARD}
 2. **Prompt for change selection**
 
    Ask the user to choose changes (multi-select):
-   - Show each change with its schema
+   - Show each change name and task status from the list output
    - Include an option for "All changes"
    - Allow any number of selections (1+ works, 2+ is the typical use case)
 
@@ -70,17 +70,24 @@ ${PROJECT_ROOT_GUARD}
 
 3. **Batch validation - gather status for all selected changes**
 
+   Run \`openspec list --json\` once with the same selected-root flags for task
+   progress. If the lookup fails, returns invalid JSON, or omits any selected
+   change, contains a duplicate selected change, or returns invalid counts,
+   report the problem and stop before syncing or archiving the batch.
+
    For each selected change, collect:
 
    a. **Artifact status** - Run \`openspec status --change "<name>" --json\`
       - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-   b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
-      - Complete means the checkbox holds only \`x\`/\`X\`, ignoring spacing
-        (\`- [ x]\` is complete); every other marker is incomplete (\`- [ ]\`,
-        \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
-      - If no tasks file exists, note as "No tasks"
+   b. **Task completion** - Find the \`changes\` entry from the list response whose \`name\` exactly matches this change
+      - Require nonnegative integer \`totalTasks\` and \`completedTasks\`, with \`completedTasks <= totalTasks\`
+      - Incomplete tasks = \`totalTasks - completedTasks\`
+      - The CLI resolves the schema's tracked task files, including custom artifact names, output paths, and globs
+      - Do not infer task completion from artifact status, an artifact id of \`tasks\`, or the absence of a top-level \`tasks.md\`
+      - The CLI counts only \`x\`/\`X\` checkbox markers as complete; other markers remain incomplete
+      - If \`totalTasks\` is zero, note as "No tasks"
 
    c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
       - List which capability specs exist
@@ -194,7 +201,9 @@ ${PROJECT_ROOT_GUARD}
    Process changes in the determined order (respecting conflict resolution):
 
    a. **Sync included delta specs**:
-      - Run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - ${optionalWorkflow('sync', 'Run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge)', 'Perform the delta-to-main-spec merge inline yourself (agent-driven intelligent merge)')} only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - If the sync reports any stop or blocking condition, treat the sync as failed. Stop processing that change immediately. Before continuing to the next change, record this change's outcome as Failed in the batch results, including the sync blocking/error condition.
+      - Do not perform the post-sync content comparison and do not move its \`changeRoot\`; leave the change intact.
       - For conflicts, apply in resolved order.
       - Pass that change's fetched specs-rule snapshot into inline sync; inline
         sync must reuse it without fetching instructions again
@@ -209,7 +218,7 @@ ${PROJECT_ROOT_GUARD}
       - Verify that main specs are updated:
         - ADDED requirements present
         - MODIFIED requirements carrying scenario and description changes named in the delta, with their other scenarios intact
-        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
         - RENAMED requirements present under the new name and absent under the old one
       - Do not verify delta specs in \`excludedDeltas\`; they are intentionally left unsynced.
       - If sync failed or any capability does not match verification, report what differs and fail/skip moving that change's \`changeRoot\` — do not archive that change. \`changeRoot\` remains intact.
@@ -347,7 +356,7 @@ No active changes found. Create a new change to get started.
 - Archive directory target uses the current date, computed once in step 3d and reused at the move: YYYY-MM-DD-<name>; a name that already starts with a \`YYYY-MM-DD-\` prefix is used as-is (never stack a second date)
 - If archive target exists, fail that change but continue with others
 - Check every archive target in step 3, before the first main-spec write; a change whose target exists is never synced or moved
-- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven) for each change with included delta specs
+- If sync is requested, ${optionalWorkflow('sync', 'run the `openspec-sync-specs` workflow inline (agent-driven)', 'perform the delta-to-main-spec merge inline (agent-driven)')} for each change with included delta specs
 - Carry the per-delta \`includedDeltas\` and \`excludedDeltas\` decisions into execution; sync and verify only included deltas
 - Report every excluded delta as \`sync skipped\` without treating the archive itself as skipped
 - Never archive a change while a spec sync is still in flight — run the sync inline and verify main specs at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` before moving \`changeRoot\`
@@ -395,7 +404,7 @@ ${PROJECT_ROOT_GUARD}
 2. **Prompt for change selection**
 
    Ask the user to choose changes (multi-select):
-   - Show each change with its schema
+   - Show each change name and task status from the list output
    - Include an option for "All changes"
    - Allow any number of selections (1+ works, 2+ is the typical use case)
 
@@ -428,17 +437,24 @@ ${PROJECT_ROOT_GUARD}
 
 3. **Batch validation - gather status for all selected changes**
 
+   Run \`openspec list --json\` once with the same selected-root flags for task
+   progress. If the lookup fails, returns invalid JSON, or omits any selected
+   change, contains a duplicate selected change, or returns invalid counts,
+   report the problem and stop before syncing or archiving the batch.
+
    For each selected change, collect:
 
    a. **Artifact status** - Run \`openspec status --change "<name>" --json\`
       - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-   b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
-      - Complete means the checkbox holds only \`x\`/\`X\`, ignoring spacing
-        (\`- [ x]\` is complete); every other marker is incomplete (\`- [ ]\`,
-        \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
-      - If no tasks file exists, note as "No tasks"
+   b. **Task completion** - Find the \`changes\` entry from the list response whose \`name\` exactly matches this change
+      - Require nonnegative integer \`totalTasks\` and \`completedTasks\`, with \`completedTasks <= totalTasks\`
+      - Incomplete tasks = \`totalTasks - completedTasks\`
+      - The CLI resolves the schema's tracked task files, including custom artifact names, output paths, and globs
+      - Do not infer task completion from artifact status, an artifact id of \`tasks\`, or the absence of a top-level \`tasks.md\`
+      - The CLI counts only \`x\`/\`X\` checkbox markers as complete; other markers remain incomplete
+      - If \`totalTasks\` is zero, note as "No tasks"
 
    c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
       - List which capability specs exist
@@ -553,6 +569,8 @@ ${PROJECT_ROOT_GUARD}
 
    a. **Sync included delta specs**:
       - ${SYNC_INLINE_HANDOFF} only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - If the sync reports any stop or blocking condition, treat the sync as failed. Stop processing that change immediately. Before continuing to the next change, record this change's outcome as Failed in the batch results, including the sync blocking/error condition.
+      - Do not perform the post-sync content comparison and do not move its \`changeRoot\`; leave the change intact.
       - For conflicts, apply in resolved order.
       - Pass that change's fetched specs-rule snapshot into inline sync; inline
         sync must reuse it without fetching instructions again
@@ -567,7 +585,7 @@ ${PROJECT_ROOT_GUARD}
       - Verify that main specs are updated:
         - ADDED requirements present
         - MODIFIED requirements carrying scenario and description changes named in the delta, with their other scenarios intact
-        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
         - RENAMED requirements present under the new name and absent under the old one
       - Do not verify delta specs in \`excludedDeltas\`; they are intentionally left unsynced.
       - If sync failed or any capability does not match verification, report what differs and fail/skip moving that change's \`changeRoot\` — do not archive that change. \`changeRoot\` remains intact.

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

@@ -30,7 +30,6 @@ ${PROJECT_ROOT_GUARD}
 
    When prompting, 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)
 
@@ -149,7 +148,6 @@ ${PROJECT_ROOT_GUARD}
 
    When prompting, 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)
 

package/dist/core/templates/workflows/explore.js

@@ -128,7 +128,7 @@ openspec list --json
 
 This tells you:
 - If there are active changes
-- Their names, schemas, and status
+- Their names and task status
 - What the user might be working on
 
 That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:
@@ -459,7 +459,7 @@ openspec list --json
 
 This tells you:
 - If there are active changes
-- Their names, schemas, and status
+- Their names and task status
 - What the user might be working on
 
 That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:

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

@@ -88,7 +88,7 @@ ${PROJECT_ROOT_GUARD}
       - Dependencies are enablers, not gates: if a required artifact is still \`blocked\` only because you skipped a conditional dependency, write it anyway
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
-   c. **If an artifact requires user input** (unclear context):
+   c. **If an artifact requires user input** (critically unclear context):
       - Ask the user to clarify
       - Then continue with creation
 
@@ -206,7 +206,7 @@ ${PROJECT_ROOT_GUARD}
       - Dependencies are enablers, not gates: if a required artifact is still \`blocked\` only because you skipped a conditional dependency, write it anyway
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
-   c. **If an artifact requires user input** (unclear context):
+   c. **If an artifact requires user input** (critically unclear context):
       - Ask the user to clarify
       - Then continue with creation