@fission-ai/openspec 1.13.0 → 1.13.1

package/dist/core/store/git.js

@@ -4,7 +4,40 @@ import * as path from 'node:path';
 import { promisify } from 'node:util';
 import { StoreError } from './errors.js';
 const fs = nodeFs.promises;
-const execFileAsync = promisify(execFile);
+const rawExecFileAsync = promisify(execFile);
+/**
+ * Bounds every read-only git probe. Without a timeout a wedged network mount, an
+ * fsmonitor daemon, or a credential/GPG prompt hangs the CLI forever; without a
+ * raised maxBuffer a very large dirty tree makes `git status --porcelain` throw
+ * ENOBUFS, which the probes below would otherwise report as "no git facts".
+ * A probe writes nothing, so a hard kill is safe.
+ */
+export const GIT_EXEC_OPTIONS = {
+    encoding: 'utf8',
+    timeout: 15_000,
+    killSignal: 'SIGKILL',
+    maxBuffer: 16 * 1024 * 1024,
+};
+/**
+ * Writes get their own bounds, and deliberately NOT SIGKILL: git traps SIGTERM
+ * to remove `.git/index.lock` on its way out, and a signal it cannot catch
+ * leaves that lock behind - every later git command in the user's store then
+ * fails with "Another git process seems to be running", including the
+ * best-effort unstage below. The timeout is also far longer, because a signed
+ * commit can legitimately sit waiting on pinentry or a hardware key.
+ */
+export const GIT_WRITE_EXEC_OPTIONS = {
+    encoding: 'utf8',
+    timeout: 120_000,
+    maxBuffer: 16 * 1024 * 1024,
+};
+function execFileAsync(file, args, options = {}) {
+    return rawExecFileAsync(file, args, { ...GIT_EXEC_OPTIONS, ...options });
+}
+/** Same as execFileAsync, for commands that modify the user's repository. */
+function execGitWrite(args, options = {}) {
+    return rawExecFileAsync('git', args, { ...GIT_WRITE_EXEC_OPTIONS, ...options });
+}
 /**
  * Git mechanics for stores: repository detection, setup-time init and
  * commit, and the read-only facts doctor reports. Nothing here clones, pulls,
@@ -31,7 +64,7 @@ export async function initGitRepository(storeRoot) {
         return false;
     }
     try {
-        await execFileAsync('git', ['init'], { cwd: storeRoot });
+        await execGitWrite(['init'], { cwd: storeRoot });
     }
     catch (error) {
         throw new StoreError(`Failed to initialize Git repository: ${error instanceof Error ? error.message : String(error)}`, 'store_git_init_failed', {
@@ -74,13 +107,13 @@ export async function commitStoreFiles(storeRoot, id, pathspecs) {
         return false;
     }
     try {
-        await execFileAsync('git', ['add', '--', ...pathspecs], { cwd: storeRoot });
-        await execFileAsync('git', ['commit', '-m', `Initialize OpenSpec store ${id}`, '--', ...pathspecs], { cwd: storeRoot });
+        await execGitWrite(['add', '--', ...pathspecs], { cwd: storeRoot });
+        await execGitWrite(['commit', '-m', `Initialize OpenSpec store ${id}`, '--', ...pathspecs], { cwd: storeRoot });
     }
     catch (error) {
         // Best-effort unstage so a failed commit (gpg signing, hooks) does not
         // leave setup's files in the user's index after rollback deletes them.
-        await execFileAsync('git', ['rm', '--cached', '-r', '-f', '-q', '--', ...pathspecs], {
+        await execGitWrite(['rm', '--cached', '-r', '-f', '-q', '--', ...pathspecs], {
             cwd: storeRoot,
         }).catch(() => undefined);
         throw new StoreError(`Failed to create the initial store commit: ${error instanceof Error ? error.message : String(error)}`, 'store_git_commit_failed', {
@@ -90,12 +123,33 @@ export async function commitStoreFiles(storeRoot, id, pathspecs) {
     }
     return true;
 }
+/**
+ * A probe that hit a resource limit rather than an ordinary Git answer: the
+ * command was killed by the timeout above, or its output exceeded maxBuffer.
+ * Both produce the same `null` as "not a repository", so without this the CLI
+ * would quietly stop reporting facts it is capable of reporting.
+ */
+export function isProbeResourceFailure(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { code, killed, signal } = error;
+    return (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' ||
+        code === 'ETIMEDOUT' ||
+        (killed === true && signal === 'SIGKILL'));
+}
 async function gitProbe(storeRoot, args) {
     try {
         const { stdout } = await execFileAsync('git', ['-C', storeRoot, ...args]);
         return stdout;
     }
-    catch {
+    catch (error) {
+        // "git is absent" and "this is not a repository" are expected answers and
+        // stay silent; a probe that timed out or overflowed its buffer is a
+        // degraded result the user should know about, since callers cannot tell
+        // the two apart from the null alone.
+        if (isProbeResourceFailure(error)) {
+            process.emitWarning(`git ${args.join(' ')} did not complete in ${storeRoot}; store Git facts are unavailable for this run.`, 'OpenSpecGitProbeWarning');
+        }
         return null;
     }
 }

package/dist/core/store/operations.d.ts

@@ -100,7 +100,7 @@ export declare function expandUserPath(inputPath: string): string;
  * no-ops), and always honoring an explicit --init-git/--no-init-git.
  */
 export declare function resolveSetupGitEnabled(prepared: PreparedStoreSetup, initGit?: boolean): boolean;
-export declare function prepareStoreSetup(input: Pick<SetupStoreInput, 'id' | 'path' | 'allowInsideGitRepository' | 'remote'>): Promise<PreparedStoreSetup>;
+export declare function prepareStoreSetup(input: Pick<SetupStoreInput, 'id' | 'path' | 'initGit' | 'allowInsideGitRepository' | 'remote'>): Promise<PreparedStoreSetup>;
 export declare function setupPreparedStore(prepared: PreparedStoreSetup, input?: Pick<SetupStoreInput, 'initGit'>): Promise<StoreMutationResult>;
 export declare function setupStore(input: SetupStoreInput): Promise<StoreMutationResult>;
 export declare function registerExistingStore(input: RegisterExistingStoreInput): Promise<StoreMutationResult>;

package/dist/core/store/operations.js

@@ -8,7 +8,7 @@ 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';
-import { assertGitCommitIdentity, commitStoreFiles, gitDirectoryHasTrackedFiles, gitHasCommits, gitHasRemote, gitHasUncommittedChanges, gitOriginUrl, initGitRepository, isGitRepositoryAtRoot, } from './git.js';
+import { GIT_EXEC_OPTIONS, assertGitCommitIdentity, commitStoreFiles, gitDirectoryHasTrackedFiles, gitHasCommits, gitHasRemote, gitHasUncommittedChanges, gitOriginUrl, initGitRepository, isGitRepositoryAtRoot, } from './git.js';
 import { getStoreRootForBackend, assertNoRegisteredStoreConflict, commitStoreRegistration, getRegisteredStore, listRegisteredStores, unregisterStoreRegistration, } from './registry.js';
 const fs = nodeFs.promises;
 const execFileAsync = promisify(execFile);
@@ -106,12 +106,7 @@ async function findContainingGitRepositoryRoot(storeRoot) {
             : null;
     };
     try {
-        const { stdout } = await execFileAsync('git', [
-            '-C',
-            nearestParent,
-            'rev-parse',
-            '--show-toplevel',
-        ]);
+        const { stdout } = await execFileAsync('git', ['-C', nearestParent, 'rev-parse', '--show-toplevel'], GIT_EXEC_OPTIONS);
         return gitRootContainsStore(stdout.trim());
     }
     catch {
@@ -244,9 +239,10 @@ async function prepareSetupPlan(input) {
         });
     }
     // Stores may be Git-backed, but creating one inside an implementation
-    // repo is almost always an accidental nested-repo setup.
+    // repo is almost always an accidental nested-repo setup. --no-init-git
+    // creates no repository, so there is nothing to nest.
     await assertSetupPathIsNotNestedInGitRepo(storeRoot, {
-        allowInsideGitRepository: input.allowInsideGitRepository,
+        allowInsideGitRepository: input.allowInsideGitRepository || input.initGit === false,
     });
     let metadata = null;
     let backend;
@@ -594,6 +590,29 @@ async function assertSafeToDeleteStoreRoot(storeRoot, id) {
     }
     return { exists: true };
 }
+/**
+ * Deleting a store root takes everything under it, including any other
+ * store registered inside it (a shared store vendored as a submodule, for
+ * example). `store remove <id>` never asked for that store to go.
+ */
+function assertNoRegisteredStoreInside(storeRoot, id, others) {
+    const root = normalizeRegistryPathForComparison(storeRoot);
+    const nested = others.filter((other) => {
+        const relative = path.relative(root, normalizeRegistryPathForComparison(other.storeRoot));
+        return (relative.length > 0 &&
+            relative !== '..' &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative));
+    });
+    if (nested.length === 0)
+        return;
+    const listed = nested.map((other) => `'${other.id}' (${other.storeRoot})`).join(', ');
+    const unregister = nested.map((other) => `openspec store unregister ${other.id}`).join(', then ');
+    throw new StoreError(`Store remove refuses to delete ${storeRoot}: it contains ${nested.length === 1 ? 'another registered store' : 'other registered stores'}: ${listed}.`, 'store_remove_contains_registered_store', {
+        target: 'store.root',
+        fix: `Unregister or remove ${nested.length === 1 ? 'that store' : 'those stores'} first (${unregister}), or run "openspec store unregister ${id}" to forget '${id}' without deleting files.`,
+    });
+}
 export async function removeStore(target) {
     const id = validateStoreId(target.id);
     const diagnostics = [];
@@ -606,9 +625,12 @@ export async function removeStore(target) {
         id,
         expectedBackend: target.backend,
         globalDataDir: target.globalDataDir,
-        beforeCommit: async (entry) => {
+        beforeCommit: async (entry, remaining) => {
             const safeTarget = await assertSafeToDeleteStoreRoot(entry.storeRoot, id);
             rootMissing = !safeTarget.exists;
+            if (safeTarget.exists) {
+                assertNoRegisteredStoreInside(entry.storeRoot, id, remaining);
+            }
         },
     });
     if (rootMissing) {

package/dist/core/store/registry.d.ts

@@ -15,7 +15,8 @@ export interface GetRegisteredStoreInput extends ResolveRegisteredStoreInput {
 export interface UnregisterStoreInput extends StorePathOptions {
     id: string;
     expectedBackend?: StoreGitBackendConfig;
-    beforeCommit?: (entry: RegisteredStoreEntry) => Promise<void>;
+    /** Runs under the registry lock, with the registrations that will remain. */
+    beforeCommit?: (entry: RegisteredStoreEntry, remaining: RegisteredStoreEntry[]) => Promise<void>;
 }
 export type ListRegisteredStoresOptions = StorePathOptions;
 export interface RegisteredStoreEntry extends StoreRegistryEntry {

package/dist/core/store/registry.js

@@ -236,7 +236,11 @@ export async function unregisterStoreRegistration(input) {
             ...result.removed,
             storeRoot: getStoreRootForBackend(result.removed.backend),
         };
-        await input.beforeCommit?.(removedEntry);
+        const remaining = listStoreRegistryEntries(result.next).map((entry) => ({
+            ...entry,
+            storeRoot: getStoreRootForBackend(entry.backend),
+        }));
+        await input.beforeCommit?.(removedEntry, remaining);
         removed = result.removed;
         return result.next;
     }, { globalDataDir: input.globalDataDir });

package/dist/core/templates/optional-workflow.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Optional-Workflow Conditionals
+ *
+ * Not every workflow is installed. The `core` profile ships six of the twelve
+ * (`propose`, `explore`, `apply`, `update`, `sync`, `archive`), and a `custom`
+ * profile can ship any subset. A template that names `/opsx:continue` is
+ * therefore writing a dead reference for anyone whose profile omits it — the
+ * agent is told to hand off to a workflow that was never generated (#1734,
+ * umbrella #919).
+ *
+ * `command-references.ts` rewrites how a reference is spelled; this module
+ * decides whether it is emitted at all. Templates author both branches with
+ * `optionalWorkflow()`, and `resolveOptionalWorkflows()` picks one at
+ * generation time against the resolved workflow set, so the generated file
+ * states one path instead of asking the model to check availability at runtime.
+ */
+/**
+ * Authors a passage whose wording depends on whether `workflowId` is installed.
+ *
+ * Both branches must read correctly on their own: the generated file contains
+ * exactly one of them, with no trace of the other.
+ *
+ * @param workflowId - Workflow id as it appears in ALL_WORKFLOWS (e.g. 'continue')
+ * @param whenInstalled - Text to emit when the workflow is part of the profile
+ * @param whenMissing - Text to emit otherwise, typically a CLI fallback
+ *
+ * @example
+ * optionalWorkflow('continue', 'suggest `/opsx:continue`', 'run `openspec status`')
+ */
+export declare function optionalWorkflow(workflowId: string, whenInstalled: string, whenMissing: string): string;
+/**
+ * A passage that is dropped entirely when `workflowId` is not installed.
+ *
+ * Use for a line that only makes sense alongside the workflow it names — a
+ * command-reference table row, a bullet listing one workflow. When the
+ * conditional is the whole line, the line goes with it rather than leaving a
+ * blank one behind.
+ *
+ * @param workflowId - Workflow id as it appears in ALL_WORKFLOWS
+ * @param whenInstalled - Text to emit when the workflow is part of the profile
+ */
+export declare function onlyWithWorkflow(workflowId: string, whenInstalled: string): string;
+/**
+ * Resolves every `optionalWorkflow()` passage in `text` against the workflows
+ * that will actually be installed.
+ *
+ * Runs before the command-reference transformers, so a reference in a branch
+ * that was dropped never reaches them.
+ *
+ * @param text - Template body, possibly containing conditionals
+ * @param installedWorkflows - The resolved workflow set for this installation
+ * @returns The body with one branch of each conditional kept
+ * @throws If a malformed conditional leaves a marker in the output
+ */
+export declare function resolveOptionalWorkflows(text: string, installedWorkflows: ReadonlySet<string>): string;
+/**
+ * Fails loudly if `text` still carries a conditional marker.
+ *
+ * Called at the end of resolution to catch a malformed block, and again at the
+ * points that write a generated file — so a body that skipped resolution
+ * altogether (a generation path that bypassed getSkillTemplates /
+ * getCommandTemplates) throws instead of shipping literal markers to a user.
+ *
+ * @param text - Text about to be written, or just resolved
+ * @param reason - What went wrong, used as the message prefix
+ * @throws If any `[[opsx:...]]` marker remains
+ */
+export declare function assertWorkflowConditionalsResolved(text: string, reason: string): void;
+//# sourceMappingURL=optional-workflow.d.ts.map

package/dist/core/templates/optional-workflow.js

@@ -0,0 +1,140 @@
+/**
+ * Optional-Workflow Conditionals
+ *
+ * Not every workflow is installed. The `core` profile ships six of the twelve
+ * (`propose`, `explore`, `apply`, `update`, `sync`, `archive`), and a `custom`
+ * profile can ship any subset. A template that names `/opsx:continue` is
+ * therefore writing a dead reference for anyone whose profile omits it — the
+ * agent is told to hand off to a workflow that was never generated (#1734,
+ * umbrella #919).
+ *
+ * `command-references.ts` rewrites how a reference is spelled; this module
+ * decides whether it is emitted at all. Templates author both branches with
+ * `optionalWorkflow()`, and `resolveOptionalWorkflows()` picks one at
+ * generation time against the resolved workflow set, so the generated file
+ * states one path instead of asking the model to check availability at runtime.
+ */
+const OPEN = '[[opsx:if-workflow ';
+const OPEN_END = ']]';
+const ELSE = '[[opsx:else]]';
+const END = '[[opsx:end]]';
+/**
+ * A conditional that occupies a whole line on its own. Matched first so a
+ * branch that resolves to empty takes its line with it — otherwise dropping a
+ * table row or a bullet would leave a blank line behind, which markdown reads
+ * as the end of the table or list.
+ */
+const WHOLE_LINE_PATTERN = /^([ \t]*)\[\[opsx:if-workflow ([a-z-]+)\]\]([^\n]*?)\[\[opsx:else\]\]([^\n]*?)\[\[opsx:end\]\][ \t]*\r?\n/gm;
+const CONDITIONAL_PATTERN = /\[\[opsx:if-workflow ([a-z-]+)\]\]([\s\S]*?)\[\[opsx:else\]\]([\s\S]*?)\[\[opsx:end\]\]/g;
+/** Any leftover marker, used to fail loudly on malformed authoring. */
+const RESIDUAL_MARKER_PATTERN = /\[\[opsx:(if-workflow|else|end)/;
+/** A single well-formed marker, in any position. */
+const MARKER_PATTERN = /\[\[opsx:(?:if-workflow [a-z-]+|else|end)\]\]/g;
+/** Anything that opens like a marker, well-formed or not. */
+const MARKER_LIKE_PATTERN = /\[\[opsx:/;
+/**
+ * Rejects a malformed conditional before any branch is chosen.
+ *
+ * Checking after resolution is not enough: the unselected branch is discarded
+ * first, so a truncated block inside it would pass for one profile and throw
+ * for another — the exact profile-dependent behavior this module exists to
+ * remove. Authoring is either valid for every profile or valid for none.
+ *
+ * @param text - Template body as authored
+ * @throws If a marker is unrecognized, or the blocks are not a flat sequence
+ *         of if / else / end
+ */
+function assertConditionalsWellFormed(text) {
+    const kinds = [];
+    const withoutMarkers = text.replace(MARKER_PATTERN, (marker) => {
+        kinds.push(marker.startsWith(OPEN) ? 'if' : marker === ELSE ? 'else' : 'end');
+        return '';
+    });
+    const unrecognized = MARKER_LIKE_PATTERN.exec(withoutMarkers);
+    if (unrecognized) {
+        throw new Error(`Malformed optional-workflow conditional: unrecognized marker at '${withoutMarkers
+            .slice(unrecognized.index, unrecognized.index + 40)
+            .split('\n')[0]}'. Markers are [[opsx:if-workflow <id>]], [[opsx:else]] and [[opsx:end]].`);
+    }
+    for (let i = 0; i < kinds.length; i += 3) {
+        if (kinds[i] !== 'if' || kinds[i + 1] !== 'else' || kinds[i + 2] !== 'end') {
+            throw new Error('Malformed optional-workflow conditional: markers are out of order or a ' +
+                'block is incomplete. Each block needs the full [[opsx:if-workflow <id>]] ' +
+                '... [[opsx:else]] ... [[opsx:end]] form, and blocks cannot nest.');
+        }
+    }
+}
+/**
+ * Authors a passage whose wording depends on whether `workflowId` is installed.
+ *
+ * Both branches must read correctly on their own: the generated file contains
+ * exactly one of them, with no trace of the other.
+ *
+ * @param workflowId - Workflow id as it appears in ALL_WORKFLOWS (e.g. 'continue')
+ * @param whenInstalled - Text to emit when the workflow is part of the profile
+ * @param whenMissing - Text to emit otherwise, typically a CLI fallback
+ *
+ * @example
+ * optionalWorkflow('continue', 'suggest `/opsx:continue`', 'run `openspec status`')
+ */
+export function optionalWorkflow(workflowId, whenInstalled, whenMissing) {
+    return `${OPEN}${workflowId}${OPEN_END}${whenInstalled}${ELSE}${whenMissing}${END}`;
+}
+/**
+ * A passage that is dropped entirely when `workflowId` is not installed.
+ *
+ * Use for a line that only makes sense alongside the workflow it names — a
+ * command-reference table row, a bullet listing one workflow. When the
+ * conditional is the whole line, the line goes with it rather than leaving a
+ * blank one behind.
+ *
+ * @param workflowId - Workflow id as it appears in ALL_WORKFLOWS
+ * @param whenInstalled - Text to emit when the workflow is part of the profile
+ */
+export function onlyWithWorkflow(workflowId, whenInstalled) {
+    return optionalWorkflow(workflowId, whenInstalled, '');
+}
+/**
+ * Resolves every `optionalWorkflow()` passage in `text` against the workflows
+ * that will actually be installed.
+ *
+ * Runs before the command-reference transformers, so a reference in a branch
+ * that was dropped never reaches them.
+ *
+ * @param text - Template body, possibly containing conditionals
+ * @param installedWorkflows - The resolved workflow set for this installation
+ * @returns The body with one branch of each conditional kept
+ * @throws If a malformed conditional leaves a marker in the output
+ */
+export function resolveOptionalWorkflows(text, installedWorkflows) {
+    assertConditionalsWellFormed(text);
+    const wholeLinesResolved = text.replace(WHOLE_LINE_PATTERN, (_match, indent, workflowId, whenInstalled, whenMissing) => {
+        const chosen = installedWorkflows.has(workflowId) ? whenInstalled : whenMissing;
+        return chosen === '' ? '' : `${indent}${chosen}\n`;
+    });
+    const resolved = wholeLinesResolved.replace(CONDITIONAL_PATTERN, (_match, workflowId, whenInstalled, whenMissing) => installedWorkflows.has(workflowId) ? whenInstalled : whenMissing);
+    assertWorkflowConditionalsResolved(resolved, 'Malformed optional-workflow conditional');
+    return resolved;
+}
+/**
+ * Fails loudly if `text` still carries a conditional marker.
+ *
+ * Called at the end of resolution to catch a malformed block, and again at the
+ * points that write a generated file — so a body that skipped resolution
+ * altogether (a generation path that bypassed getSkillTemplates /
+ * getCommandTemplates) throws instead of shipping literal markers to a user.
+ *
+ * @param text - Text about to be written, or just resolved
+ * @param reason - What went wrong, used as the message prefix
+ * @throws If any `[[opsx:...]]` marker remains
+ */
+export function assertWorkflowConditionalsResolved(text, reason) {
+    const residual = RESIDUAL_MARKER_PATTERN.exec(text);
+    if (residual) {
+        throw new Error(`${reason}: '${residual[0]}' is unresolved. Optional-workflow blocks are ` +
+            'resolved by getSkillTemplates()/getCommandTemplates() against the installed ' +
+            'workflow set, and each needs the full [[opsx:if-workflow <id>]] ... ' +
+            '[[opsx:else]] ... [[opsx:end]] form.');
+    }
+}
+//# sourceMappingURL=optional-workflow.js.map

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

@@ -1,4 +1,14 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * `/opsx:continue` is not in the `core` profile, so the blocked-state handoff
+ * is authored with a CLI fallback and resolved at generation time (see
+ * optional-workflow.ts).
+ */
+const BLOCKED_STATE_HANDOFF = optionalWorkflow('continue', 'suggest using `/opsx:continue` to create them.', 'suggest completing the missing artifacts. Run `openspec status --change "<name>" --json`, select the next `ready` artifact (not `skipped` or `blocked`), and use `openspec instructions "<artifact-id>" --change "<name>" --json` for its rules and template. Keep the selected `--store <id>` on both commands.');
+/** The archive handoff shown once every task is done. */
+const ARCHIVE_HANDOFF = optionalWorkflow('archive', 'You can archive this change with `/opsx:archive`.', 'You can archive this change by running `openspec archive "<name>"`.');
 /**
  * The apply workflow instructions, authored once and rendered by both the
  * skill and command surfaces. The surfaces are intentionally distinct, but
@@ -13,6 +23,8 @@ export function getApplyInstructions() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name (e.g., \`/opsx:apply add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -48,9 +60,12 @@ ${STORE_SELECTION_GUIDANCE}
    - Dynamic instruction based on current state
    - Optional \`context\`: current required project instruction input from the selected root
    - Optional \`operationGuidance\`: current advisory guidance for apply
+   - \`missingArtifacts\` (when present): required artifact ids with no output
 
    **Handle states:**
-   - If \`state: "blocked"\` (missing artifacts): show message, suggest using \`/opsx:continue\` (if it is not installed, run \`openspec status --change "<name>" --json\` to see the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` for how to create it)
+   - If \`state: "blocked"\`: show the message and pause implementation.
+     - If \`missingArtifacts\` is non-empty: ${BLOCKED_STATE_HANDOFF}
+     - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked.
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
@@ -139,7 +154,7 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! You can archive this change with \`/opsx:archive\`.
+All tasks complete! ${ARCHIVE_HANDOFF}
 \`\`\`
 
 **Output On Pause (Issue Encountered)**
@@ -189,7 +204,7 @@ This skill supports the "actions on a change" model:
 export function getApplyChangeSkillTemplate() {
     return {
         name: 'openspec-apply-change',
-        description: 'Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.',
+        description: 'Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".',
         instructions: getApplyInstructions(),
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',

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

@@ -1,12 +1,25 @@
+import { optionalWorkflow } from '../optional-workflow.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * Archiving must merge delta specs into the main specs; the `sync` workflow is
+ * how it normally does that. A profile that selects `archive` gets `sync`
+ * injected (see getProfileWorkflows), but an install whose workflow set was
+ * read back off disk can still be missing it — in which case the merge has to
+ * happen inline rather than be handed to a workflow that is not there.
+ */
+const SYNC_INLINE_HANDOFF = optionalWorkflow('sync', 'run the `/opsx:sync` workflow inline (agent-driven intelligent merge)', 'perform the delta-to-main-spec merge inline yourself (agent-driven intelligent merge)');
+const SYNC_GUARDRAIL = optionalWorkflow('sync', 'run the `/opsx:sync` workflow inline (agent-driven)', 'perform the delta-to-main-spec merge inline (agent-driven)');
 export function getArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-archive-change',
-        description: 'Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.',
+        description: 'Archive a completed OpenSpec change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. Also use when the user says "openspec archive" or "opsx archive".',
         instructions: `Archive a completed change in the experimental workflow.
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
 
 **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.
@@ -70,7 +83,11 @@ ${STORE_SELECTION_GUIDANCE}
 
    Read the tasks file (typically \`tasks.md\`) to check for incomplete tasks.
 
-   Count tasks marked with \`- [ ]\` (incomplete) vs \`- [x]\` (complete).
+   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.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
@@ -88,17 +105,23 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (use the store-aware \`planningHome.root\` from step 2, not a hardcoded repo path)
+   - A missing main spec is **not automatically** "already synced". For a new capability, the main spec is an *output* of the sync, not an input:
+     - If the delta has MODIFIED or RENAMED requirements, report that only ADDED requirements can create a new main spec and mark that capability as sync-blocked. Never invent a requirement that has no current version.
+     - Otherwise, if the delta has only REMOVED requirements and the change's \`.openspec.yaml\` declares \`retire_capabilities: true\`, the capability is already retired: count it as already synced, warn that there is nothing left to remove, and do not recreate the main spec. Apply this rule both now and when verifying a completed sync.
+     - Otherwise, if the delta has no ADDED requirements, report that no sync is possible and mark that capability as sync-blocked. For a REMOVED-only delta, warn that there is no main spec to remove from and leave the main-spec tree unchanged. \`openspec archive\` refuses the unmarked REMOVED-only case with \`Spec must have at least one requirement\`.
+     - Otherwise, count the capability as needing sync and name it in the summary (\`<capability-path>: new main spec will be created\`). If the delta also has REMOVED requirements, warn that they will be ignored because there is no main spec to remove from. The sync creates the main spec from only the delta's ADDED requirements, exactly as \`openspec archive\` does.
    - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
+   - Continue assessing the remaining capabilities even when one is sync-blocked. Show a combined summary before prompting.
 
    **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
+   - If any capability is sync-blocked: explain why and offer only "Archive without syncing", "Cancel"
+   - Otherwise, if changes needed: "Sync now (recommended)", "Archive without syncing"
+   - Otherwise, if already synced: "Archive now", "Sync anyway", "Cancel"
 
    Route on the answer:
    - "Cancel" — stop, do not archive
    - "Archive without syncing" or "Archive now" — proceed to archive
-   - "Sync now" or "Sync anyway" — sync, then verify (below)
+   - "Sync now" or "Sync anyway" — sync, then verify (below). Do not start any sync while a capability is sync-blocked; explain the blocker and repeat the available choices.
    - Anything else — ask again rather than archiving
 
    Before a selected sync writes any main spec, run
@@ -112,7 +135,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    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 re-run the comparison from the top of this step 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:
+   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
@@ -188,6 +211,8 @@ export function getOpsxArchiveCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
 
 **Input**: Optionally specify a change name after \`/opsx:archive\` (e.g., \`/opsx:archive add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
@@ -251,7 +276,11 @@ ${STORE_SELECTION_GUIDANCE}
 
    Read the tasks file (typically \`tasks.md\`) to check for incomplete tasks.
 
-   Count tasks marked with \`- [ ]\` (incomplete) vs \`- [x]\` (complete).
+   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.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
@@ -269,17 +298,23 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (use the store-aware \`planningHome.root\` from step 2, not a hardcoded repo path)
+   - A missing main spec is **not automatically** "already synced". For a new capability, the main spec is an *output* of the sync, not an input:
+     - If the delta has MODIFIED or RENAMED requirements, report that only ADDED requirements can create a new main spec and mark that capability as sync-blocked. Never invent a requirement that has no current version.
+     - Otherwise, if the delta has only REMOVED requirements and the change's \`.openspec.yaml\` declares \`retire_capabilities: true\`, the capability is already retired: count it as already synced, warn that there is nothing left to remove, and do not recreate the main spec. Apply this rule both now and when verifying a completed sync.
+     - Otherwise, if the delta has no ADDED requirements, report that no sync is possible and mark that capability as sync-blocked. For a REMOVED-only delta, warn that there is no main spec to remove from and leave the main-spec tree unchanged. \`openspec archive\` refuses the unmarked REMOVED-only case with \`Spec must have at least one requirement\`.
+     - Otherwise, count the capability as needing sync and name it in the summary (\`<capability-path>: new main spec will be created\`). If the delta also has REMOVED requirements, warn that they will be ignored because there is no main spec to remove from. The sync creates the main spec from only the delta's ADDED requirements, exactly as \`openspec archive\` does.
    - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
+   - Continue assessing the remaining capabilities even when one is sync-blocked. Show a combined summary before prompting.
 
    **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
+   - If any capability is sync-blocked: explain why and offer only "Archive without syncing", "Cancel"
+   - Otherwise, if changes needed: "Sync now (recommended)", "Archive without syncing"
+   - Otherwise, if already synced: "Archive now", "Sync anyway", "Cancel"
 
    Route on the answer:
    - "Cancel" — stop, do not archive
    - "Archive without syncing" or "Archive now" — proceed to archive
-   - "Sync now" or "Sync anyway" — sync, then verify (below)
+   - "Sync now" or "Sync anyway" — sync, then verify (below). Do not start any sync while a capability is sync-blocked; explain the blocker and repeat the available choices.
    - Anything else — ask again rather than archiving
 
    Before a selected sync writes any main spec, run
@@ -291,9 +326,9 @@ ${STORE_SELECTION_GUIDANCE}
    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 \`/opsx:sync\` 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 ${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.
 
-   Then re-run the comparison from the top of this step 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:
+   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
@@ -393,7 +428,7 @@ Target archive directory already exists.
 - 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 \`/opsx:sync\` workflow inline (agent-driven)
+- If sync is requested, ${SYNC_GUARDRAIL}
 - 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