@fission-ai/openspec 1.13.2 → 1.14.1

package/dist/core/version-check.js

@@ -6,6 +6,7 @@ import { createRequire } from 'module';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
@@ -268,22 +269,34 @@ function fetchLatestVersion() {
     });
 }
 /**
- * Returns the published version when the installed CLI is behind it, otherwise
- * null. Never throws and never blocks for longer than the request timeout.
+ * Checks the registry while preserving enough detail for callers to explain
+ * why no newer version was reported. Never throws.
  */
-export async function getAvailableCliUpdate() {
-    if (!isCheckEnabled())
-        return null;
+export async function checkForCliUpdate() {
+    if (!isCheckEnabled() || registryUrl() === null) {
+        return { status: 'disabled', latest: null };
+    }
     try {
         const latest = await fetchLatestVersion();
         if (!latest)
-            return null;
-        return compareVersions(latest, OPENSPEC_VERSION) > 0 ? latest : null;
+            return { status: 'offline', latest: null };
+        return {
+            status: compareVersions(latest, OPENSPEC_VERSION) > 0 ? 'available' : 'current',
+            latest,
+        };
     }
     catch {
-        return null;
+        return { status: 'offline', latest: null };
     }
 }
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Kept as the compatibility surface used by `openspec update`.
+ */
+export async function getAvailableCliUpdate() {
+    const result = await checkForCliUpdate();
+    return result.status === 'available' ? result.latest : null;
+}
 /**
  * Directory the running CLI was loaded from, or null when it cannot be
  * resolved. Shown in the upgrade hint so anyone who upgraded but still runs an
@@ -312,8 +325,8 @@ export function isProjectLocalInstall(installDir, projectPath = '.') {
     // Windows paths differ in case and drive-letter casing between sources.
     const normalize = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
     try {
-        let dir = path.resolve(projectPath);
-        const target = normalize(installDir);
+        let dir = FileSystemUtils.canonicalizeExistingPath(projectPath);
+        const target = normalize(FileSystemUtils.canonicalizeExistingPath(installDir));
         for (;;) {
             if (target.startsWith(normalize(path.join(dir, 'node_modules') + path.sep))) {
                 return true;
@@ -443,32 +456,29 @@ export function isSourceCheckout(installDir) {
         return false;
     }
 }
-/**
- * The package manager that owns this copy, so the printed command is one the
- * user's setup will actually honor.
- */
-export function detectPackageManager(installDir) {
-    // Lowercased because the Windows directories are capitalized and undotted:
-    // %LOCALAPPDATA%\\Volta, \\Yarn\\Data, \\pnpm-cache.
+function detectKnownPackageManager(installDir) {
     const segments = (installDir ?? '').split(/[\\/]/).map((segment) => segment.toLowerCase());
     const has = (...names) => names.some((name) => segments.includes(name));
-    // The undotted spelling exists for Windows (%LOCALAPPDATA%\Volta), whose
-    // layout nests tools\image; require both segments so a user or project
-    // directory merely named "volta" (even one with its own "tools" dir) does
-    // not steal the install.
     if (has('.volta') || (has('volta') && has('tools') && has('image')))
         return 'volta';
-    if (has('.bun'))
+    if (has('.bun', '_bunx', 'bun-cache'))
         return 'bun';
-    // These two need a corroborating segment: a directory merely named "pnpm" or
-    // "yarn" (a user's home, a project) is not a global install of one.
-    if (has('.pnpm-global', 'pnpm-cache'))
+    if (has('_npx'))
+        return 'npm';
+    if (has('.pnpm', '.pnpm-global', 'pnpm-cache'))
         return 'pnpm';
     if (has('pnpm') && has('global', 'dlx', 'store'))
         return 'pnpm';
     if (has('.yarn') || (has('yarn') && has('global')))
         return 'yarn';
-    return 'npm';
+    return null;
+}
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export function detectPackageManager(installDir) {
+    return detectKnownPackageManager(installDir) ?? 'npm';
 }
 const GLOBAL_UPGRADE_COMMANDS = {
     npm: `npm install -g ${PACKAGE_NAME}@latest`,
@@ -477,6 +487,82 @@ const GLOBAL_UPGRADE_COMMANDS = {
     yarn: `yarn global add ${PACKAGE_NAME}@latest`,
     volta: `volta install ${PACKAGE_NAME}@latest`,
 };
+function detectGlobalPackageManager(installDir) {
+    if (isNpmGlobalInstall(installDir))
+        return 'npm';
+    if (!installDir)
+        return null;
+    const segments = installDir.split(/[\\/]/).map((segment) => segment.toLowerCase());
+    const has = (...names) => names.some((name) => segments.includes(name));
+    const hasSequence = (...names) => segments.some((_, index) => names.every((name, offset) => segments[index + offset] === name));
+    if (hasSequence('.volta', 'tools', 'image') || hasSequence('volta', 'tools', 'image')) {
+        return 'volta';
+    }
+    if (has('.pnpm-global') || hasSequence('pnpm', 'global'))
+        return 'pnpm';
+    if (hasSequence('yarn', 'global') || hasSequence('yarn', 'data', 'global'))
+        return 'yarn';
+    if (hasSequence('.bun', 'install', 'global'))
+        return 'bun';
+    return null;
+}
+/** Describes the running copy without guessing when its owner is ambiguous. */
+export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.') {
+    if (!installDir) {
+        return { location: null, packageManager: null, scope: null };
+    }
+    if (isSourceCheckout(installDir)) {
+        return { location: installDir, packageManager: null, scope: 'source' };
+    }
+    if (isEphemeralRunnerInstall(installDir)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'temporary',
+        };
+    }
+    if (isProjectLocalInstall(installDir, projectPath)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'project',
+        };
+    }
+    const packageManager = detectGlobalPackageManager(installDir);
+    return {
+        location: installDir,
+        packageManager,
+        scope: packageManager ? 'global' : null,
+    };
+}
+/** Returns a safe update command only for an install with known global ownership. */
+export function getCliUpdateCommand(install) {
+    if (install.scope !== 'global' || install.packageManager === null)
+        return null;
+    return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
+}
+/** Builds the concise human-readable form of the version report. */
+export function buildVersionReportLines(version, install, update, command = null) {
+    const details = [install.packageManager, install.scope].filter(Boolean).join(', ');
+    const lines = [`OpenSpec ${version}${details ? ` (${details})` : ''}`];
+    if (!update)
+        return lines;
+    if (update.status === 'available') {
+        lines.push(`Update available: ${update.latest}`);
+        if (command)
+            lines.push(`  ${command}`);
+    }
+    else if (update.status === 'current') {
+        lines.push('OpenSpec is up to date.');
+    }
+    else if (update.status === 'disabled') {
+        lines.push('Update check disabled.');
+    }
+    else {
+        lines.push('Could not check for updates.');
+    }
+    return lines;
+}
 /**
  * Builds the hint, with the upgrade command chosen for how this copy of the CLI
  * was installed. Pure so every branch is assertable.

package/dist/core/view.d.ts

@@ -3,6 +3,8 @@ export declare class ViewCommand {
     private getChangesData;
     private getSpecsData;
     private displaySummary;
+    private sanitizeWorkflowText;
+    private formatWorkflowArtifacts;
     private createProgressBar;
 }
 //# sourceMappingURL=view.d.ts.map

package/dist/core/view.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { loadChangeContext, formatChangeStatus } from './artifact-graph/index.js';
 export class ViewCommand {
     async execute(targetPath = '.') {
         const openspecDir = path.join(targetPath, 'openspec');
@@ -30,12 +31,17 @@ export class ViewCommand {
         if (changesData.active.length > 0) {
             console.log(chalk.bold.cyan('\nActive Changes'));
             console.log('─'.repeat(60));
+            const maxNameLength = Math.min(48, Math.max(30, ...changesData.active.map((change) => change.name.length)));
             changesData.active.forEach((change) => {
                 const progressBar = this.createProgressBar(change.progress.completed, change.progress.total);
                 const percentage = change.progress.total > 0
                     ? Math.round((change.progress.completed / change.progress.total) * 100)
                     : 0;
-                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(30))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(maxNameLength))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                if (change.workflowStatus) {
+                    const { schemaName, artifacts } = change.workflowStatus;
+                    console.log(`    ${chalk.dim(`└─ [${this.sanitizeWorkflowText(schemaName)}]`)} ${this.formatWorkflowArtifacts(artifacts)}`);
+                }
             });
         }
         // Display completed changes
@@ -62,6 +68,7 @@ export class ViewCommand {
     }
     async getChangesData(openspecDir) {
         const changesDir = path.join(openspecDir, 'changes');
+        const projectRoot = path.dirname(openspecDir);
         if (!fs.existsSync(changesDir)) {
             return { draft: [], active: [], completed: [] };
         }
@@ -82,7 +89,15 @@ export class ViewCommand {
                 }
                 else {
                     // Has tasks but not all complete
-                    active.push({ name: entry.name, progress });
+                    let workflowStatus;
+                    try {
+                        workflowStatus = formatChangeStatus(loadChangeContext(projectRoot, entry.name));
+                    }
+                    catch (error) {
+                        // Preserve task progress even when this change's workflow cannot be loaded.
+                        console.warn(chalk.yellow(this.sanitizeWorkflowText(`Could not load workflow status for "${entry.name}": ${error instanceof Error ? error.message : String(error)}`)));
+                    }
+                    active.push({ name: entry.name, progress, workflowStatus });
                 }
             }
         }
@@ -149,6 +164,25 @@ export class ViewCommand {
             console.log(`  ${chalk.magenta('●')} Task Progress: ${chalk.bold(`${completedTasks}/${totalTasks}`)} (${overallProgress}% complete)`);
         }
     }
+    sanitizeWorkflowText(value) {
+        // Metadata may contain terminal controls; mask them before adding our own colors.
+        return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+    }
+    formatWorkflowArtifacts(artifacts) {
+        return artifacts.map((artifact) => {
+            const id = this.sanitizeWorkflowText(artifact.id);
+            switch (artifact.status) {
+                case 'done':
+                    return `${id}${chalk.green('✓')}`;
+                case 'ready':
+                    return `${id}${chalk.cyan('→')}`;
+                case 'skipped':
+                    return chalk.dim(`${id} (skipped)`);
+                case 'blocked':
+                    return chalk.dim(id);
+            }
+        }).join(' ');
+    }
     createProgressBar(completed, total, width = 20) {
         if (total === 0)
             return chalk.dim('─'.repeat(width));

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

@@ -1,6 +1,25 @@
-import { type ChangeMetadata } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-metadata/index.js';
 import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export declare function formatUnknownChangeMetadataKeysMessage(keys: string[]): string;
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export declare function readUnknownChangeMetadataKeys(changeDir: string): string[];
 /**
  * Error thrown when change metadata validation fails.
  */

package/dist/utils/change-metadata.js

@@ -1,10 +1,66 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, ChangeMetadataSchema, } from '../core/change-metadata/index.js';
 import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { sanitizeInline } from '../core/references.js';
 export const METADATA_FILENAME = '.openspec.yaml';
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export function listUnknownChangeMetadataKeys(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
+    return Object.keys(parsed)
+        .filter((key) => !known.has(key))
+        .sort();
+}
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export function formatUnknownChangeMetadataKeysMessage(keys) {
+    // The keys come from the file as written, so a quoted key can carry a
+    // terminal escape; it is printed as inline text.
+    const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
+    const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
+    let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
+        `Known keys: ${known}. Unknown keys are ignored and have no effect.`;
+    if (keys.includes('skip_design')) {
+        message +=
+            ' skip_design is not a supported key; only skip_specs exists, and it only skips artifacts whose generates path lives under specs/.';
+    }
+    return message;
+}
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export function readUnknownChangeMetadataKeys(changeDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    return listUnknownChangeMetadataKeys(parsed);
+}
 /**
  * Error thrown when change metadata validation fails.
  */

package/dist/utils/command-references.d.ts

@@ -71,7 +71,7 @@ export declare function getSkillReferenceTransformer(toolId: string): (text: str
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/command-references.js

@@ -67,7 +67,7 @@ const SKILL_INVOCATION_PREFIX = {
  * Skill references for these tools are spelled as prose ("the openspec-propose
  * skill") so skills-only delivery does not advertise unregistered commands.
  */
-const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev', 'codeassistant']);
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['gsd', 'rovodev', 'codeassistant']);
 /**
  * Whether a tool references skills by natural language rather than a slash
  * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
@@ -146,7 +146,7 @@ export function getSkillReferenceTransformer(toolId) {
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/index.d.ts

@@ -1,6 +1,6 @@
 export { validateChangeName, createChange } from './change-utils.js';
 export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
-export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, listUnknownChangeMetadataKeys, readUnknownChangeMetadataKeys, formatUnknownChangeMetadataKeysMessage, CHANGE_METADATA_KNOWN_KEYS, } from './change-metadata.js';
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -1,7 +1,7 @@
 // Shared utilities
 export { validateChangeName, createChange } from './change-utils.js';
 // Change metadata utilities
-export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, listUnknownChangeMetadataKeys, readUnknownChangeMetadataKeys, formatUnknownChangeMetadataKeysMessage, CHANGE_METADATA_KNOWN_KEYS, } from './change-metadata.js';
 // File system utilities
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 // Command reference utilities

package/package.json

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

package/schemas/spec-driven/schema.yaml

@@ -13,7 +13,7 @@ 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/<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.
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. 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.
 
@@ -77,6 +77,17 @@ artifacts:
       - 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`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
+      Write the spec files one at a time, so the user sees progress and an
+      interrupted run keeps the files it already wrote:
+      - Before writing anything, compare the capabilities the proposal lists
+        with the `specs/<capability-path>/spec.md` files that already exist,
+        and start with the first capability that has no file. Do not rewrite
+        an existing file unless the user asks you to.
+      - Before each file, say in one line which capability you are writing.
+      - Write each file as soon as you have drafted it. Do not plan every file
+        before writing the first.
+      - Stop when every capability the proposal lists has its file.
+
       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`
       rejects a zero-delta change without that marker. If the proposal lists no
@@ -94,6 +105,7 @@ artifacts:
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
+      - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
       New capabilities only: the delta spec's first section is `## Purpose` -
       one or two sentences (50+ characters, or `openspec validate --strict`
@@ -194,17 +206,22 @@ artifacts:
       would change what gets built, resolve them with the user first - do not
       bake an unstated assumption into the task list.
 
-      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      **IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
       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
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Group related tracked tasks under ## numbered headings
+      - Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
       - Tasks should be small enough to complete in one session
       - Order tasks by dependency (what must be done first?)
+      - Track implementation and verification work that can be completed before
+        archive. If the requested workflow includes archive or work that requires
+        this change to be archived, preserve those steps as plain bullets in an
+        optional `## Workflow follow-up` section at the end of tasks.md. These
+        bullets are reference information outside tracked task progress.
       - Each task MUST state how to verify completion (a test, command,
         observable behavior, or delivered artifact). Put the verification in
         that task's checkbox description. Use a separate verification task only
@@ -234,6 +251,14 @@ artifacts:
       - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
       ```
 
+      When applicable, append workflow follow-up as plain bullets, for example:
+      ```
+      ## Workflow follow-up
+
+      - Archive the change after the project's review requirements are satisfied.
+      - Verify the archived result.
+      ```
+
       Reference specs for what needs to be built, design for how to build it.
     requires:
       - specs

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

@@ -11,9 +11,12 @@
 ## Capabilities
 
 ### New Capabilities
-<!-- 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. -->
+<!-- Capabilities being introduced. Name each capability for a cohesive system
+     behavior that can own related requirements as the system evolves. Do not name
+     implementation tasks or proposal sections. Avoid broad catch-all names. 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