@fission-ai/openspec 1.13.0 → 1.13.2

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.',