@fission-ai/openspec 1.12.0 → 1.13.1

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

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

@@ -1,14 +1,27 @@
+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 getBulkArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-bulk-archive-change',
-        description: 'Archive multiple completed changes at once. Use when archiving several parallel changes.',
+        description: 'Archive multiple completed OpenSpec changes at once. Use when archiving several parallel changes. Also use for a plural archive request - "openspec bulk-archive", "opsx bulk-archive", "openspec archive all", or "openspec archive these changes".',
         instructions: `Archive multiple completed changes in a single operation.
 
 This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
 
 ${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**: None required (prompts for selection)
@@ -64,7 +77,9 @@ ${STORE_SELECTION_GUIDANCE}
       - Note which artifacts are \`done\` vs other states
 
    b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
-      - Count \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
+      - Complete means the checkbox holds only \`x\`/\`X\`, ignoring spacing
+        (\`- [ x]\` is complete); every other marker is incomplete (\`- [ ]\`,
+        \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
       - If no tasks file exists, note as "No tasks"
 
    c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
@@ -75,6 +90,14 @@ ${STORE_SELECTION_GUIDANCE}
         lookup for that change; do not infer deltas from unrelated artifacts.
       - Evaluate this independently for every change, including mixed-schema
         batches where some schemas have no \`specs\` artifact.
+
+   d. **Archive target** - Compute each change's target name once and record it as that change's \`<target-name>\`
+      - Use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<name>\` (same rule as \`openspec archive\`)
+      - Check whether \`<planningHome.changesDir>/archive/<target-name>\` already exists
+      - If it exists, or another selected change resolves to the same target name, mark every such change \`Blocked\` with \`Archive directory already exists\`
+      - A blocked change is never synced or moved: show it as \`Blocked\` in the step 6 table, leave it out of conflict resolution (resolve its conflicts using only the other changes), and record it as Failed in step 8d
+      - Checking here, before any main spec is written, matches \`openspec archive\`: a collision found after sync would leave main specs rewritten for an archive that never happened
+
 4. **Detect spec conflicts**
 
    Build a map keyed by \`<capability-path>\`, the exact path relative to \`specs/\`:
@@ -147,8 +170,8 @@ ${STORE_SELECTION_GUIDANCE}
    Route on the answer by intent, not by exact label — you wrote these labels,
    so match what the user picked rather than the wording above:
    - "Cancel" — stop, do not archive. Report that nothing was archived and skip the remaining steps.
-   - The archive-everything option — proceed with every selected change
-   - The ready-only option — proceed with only the changes the step 6 table marks \`Ready\` or \`Ready*\`, and record the rest as Skipped in step 8d. If a \`Ready*\` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
+   - The archive-everything option — proceed with every selected change that is not \`Blocked\`
+   - The ready-only option — proceed with only the changes the step 6 table marks \`Ready\` or \`Ready*\`, and record the rest as Skipped in step 8d, except \`Blocked\` changes, which stay Failed with \`Archive directory already exists\`. If a \`Ready*\` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
    - Anything else — ask again rather than archiving
 
    Before step 8 writes the first main spec or moves any change, fetch every
@@ -193,13 +216,20 @@ ${STORE_SELECTION_GUIDANCE}
 
    c. **Perform the archive**:
 
-      Target name: use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<name>\` (same rule as \`openspec archive\`).
+      Target name: use the \`<target-name>\` recorded for this change in step 3d, unchanged. Never recompute it here: a batch that runs past midnight would check one date in step 3 and move to another.
+
+      **Check if target already exists:**
+      - Check again immediately before the move, even though step 3 already checked: the target can appear mid-batch
+      - If yes: record this change as Failed with \`Archive directory already exists\`, leave \`changeRoot\` where it is, report any main specs step 8a already synced for it, and continue with the remaining changes
+      - If no: move \`changeRoot\` to the archive directory
 
       \`\`\`bash
       mkdir -p "<planningHome.changesDir>/archive"
       mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
       \`\`\`
 
+      **Confirm the move did not nest:** \`mv\` exits 0 even when the target appeared after the check, moving the change *inside* it. If \`<planningHome.changesDir>/archive/<target-name>/<change-directory-name>\` now exists (the last path segment of \`changeRoot\`), move that directory back to \`changeRoot\` and record this change as Failed with \`Archive directory already exists\`. Never report it as archived.
+
    d. **Track outcome** for each change:
       - Success: archived successfully
       - Failed: error during archive or spec verification (record error)
@@ -314,8 +344,9 @@ No active changes found. Create a new change to get started.
 - Never archive after the user cancels the confirmation — a cancelled batch archives nothing
 - Track and report all outcomes (success/skip/fail)
 - Preserve .openspec.yaml when moving to archive
-- Archive directory target uses current date: YYYY-MM-DD-<name>; a name that already starts with a \`YYYY-MM-DD-\` prefix is used as-is (never stack a second date)
+- Archive directory target uses the current date, computed once in step 3d and reused at the move: YYYY-MM-DD-<name>; a name that already starts with a \`YYYY-MM-DD-\` prefix is used as-is (never stack a second date)
 - If archive target exists, fail that change but continue with others
+- Check every archive target in step 3, before the first main-spec write; a change whose target exists is never synced or moved
 - If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven) for each change with included delta specs
 - Carry the per-delta \`includedDeltas\` and \`excludedDeltas\` decisions into execution; sync and verify only included deltas
 - Report every excluded delta as \`sync skipped\` without treating the archive itself as skipped
@@ -347,6 +378,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
 ${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**: None required (prompts for selection)
@@ -402,7 +435,9 @@ ${STORE_SELECTION_GUIDANCE}
       - Note which artifacts are \`done\` vs other states
 
    b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
-      - Count \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
+      - Complete means the checkbox holds only \`x\`/\`X\`, ignoring spacing
+        (\`- [ x]\` is complete); every other marker is incomplete (\`- [ ]\`,
+        \`- []\`, and unfamiliar ones such as \`- [~]\` or \`- [-]\`)
       - If no tasks file exists, note as "No tasks"
 
    c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
@@ -414,6 +449,13 @@ ${STORE_SELECTION_GUIDANCE}
       - Evaluate this independently for every change, including mixed-schema
         batches where some schemas have no \`specs\` artifact.
 
+   d. **Archive target** - Compute each change's target name once and record it as that change's \`<target-name>\`
+      - Use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<name>\` (same rule as \`openspec archive\`)
+      - Check whether \`<planningHome.changesDir>/archive/<target-name>\` already exists
+      - If it exists, or another selected change resolves to the same target name, mark every such change \`Blocked\` with \`Archive directory already exists\`
+      - A blocked change is never synced or moved: show it as \`Blocked\` in the step 6 table, leave it out of conflict resolution (resolve its conflicts using only the other changes), and record it as Failed in step 8d
+      - Checking here, before any main spec is written, matches \`openspec archive\`: a collision found after sync would leave main specs rewritten for an archive that never happened
+
 4. **Detect spec conflicts**
 
    Build a map keyed by \`<capability-path>\`, the exact path relative to \`specs/\`:
@@ -486,8 +528,8 @@ ${STORE_SELECTION_GUIDANCE}
    Route on the answer by intent, not by exact label — you wrote these labels,
    so match what the user picked rather than the wording above:
    - "Cancel" — stop, do not archive. Report that nothing was archived and skip the remaining steps.
-   - The archive-everything option — proceed with every selected change
-   - The ready-only option — proceed with only the changes the step 6 table marks \`Ready\` or \`Ready*\`, and record the rest as Skipped in step 8d. If a \`Ready*\` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
+   - The archive-everything option — proceed with every selected change that is not \`Blocked\`
+   - The ready-only option — proceed with only the changes the step 6 table marks \`Ready\` or \`Ready*\`, and record the rest as Skipped in step 8d, except \`Blocked\` changes, which stay Failed with \`Archive directory already exists\`. If a \`Ready*\` change's conflict partner is skipped, re-derive that conflict's resolution using only the changes being archived.
    - Anything else — ask again rather than archiving
 
    Before step 8 writes the first main spec or moves any change, fetch every
@@ -510,7 +552,7 @@ ${STORE_SELECTION_GUIDANCE}
    Process changes in the determined order (respecting conflict resolution):
 
    a. **Sync included delta specs**:
-      - Run the \`/opsx:sync\` workflow inline (agent-driven intelligent merge) only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - ${SYNC_INLINE_HANDOFF} only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
       - For conflicts, apply in resolved order.
       - Pass that change's fetched specs-rule snapshot into inline sync; inline
         sync must reuse it without fetching instructions again
@@ -532,13 +574,20 @@ ${STORE_SELECTION_GUIDANCE}
 
    c. **Perform the archive**:
 
-      Target name: use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<name>\` (same rule as \`openspec archive\`).
+      Target name: use the \`<target-name>\` recorded for this change in step 3d, unchanged. Never recompute it here: a batch that runs past midnight would check one date in step 3 and move to another.
+
+      **Check if target already exists:**
+      - Check again immediately before the move, even though step 3 already checked: the target can appear mid-batch
+      - If yes: record this change as Failed with \`Archive directory already exists\`, leave \`changeRoot\` where it is, report any main specs step 8a already synced for it, and continue with the remaining changes
+      - If no: move \`changeRoot\` to the archive directory
 
       \`\`\`bash
       mkdir -p "<planningHome.changesDir>/archive"
       mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
       \`\`\`
 
+      **Confirm the move did not nest:** \`mv\` exits 0 even when the target appeared after the check, moving the change *inside* it. If \`<planningHome.changesDir>/archive/<target-name>/<change-directory-name>\` now exists (the last path segment of \`changeRoot\`), move that directory back to \`changeRoot\` and record this change as Failed with \`Archive directory already exists\`. Never report it as archived.
+
    d. **Track outcome** for each change:
       - Success: archived successfully
       - Failed: error during archive or spec verification (record error)
@@ -653,9 +702,10 @@ No active changes found. Create a new change to get started.
 - Never archive after the user cancels the confirmation — a cancelled batch archives nothing
 - Track and report all outcomes (success/skip/fail)
 - Preserve .openspec.yaml when moving to archive
-- Archive directory target uses current date: YYYY-MM-DD-<name>; a name that already starts with a \`YYYY-MM-DD-\` prefix is used as-is (never stack a second date)
+- Archive directory target uses the current date, computed once in step 3d and reused at the move: YYYY-MM-DD-<name>; a name that already starts with a \`YYYY-MM-DD-\` prefix is used as-is (never stack a second date)
 - If archive target exists, fail that change but continue with others
-- If sync is requested, run the \`/opsx:sync\` workflow inline (agent-driven) for each change with included delta specs
+- Check every archive target in step 3, before the first main-spec write; a change whose target exists is never synced or moved
+- If sync is requested, ${SYNC_GUARDRAIL} for each change with included delta specs
 - Carry the per-delta \`includedDeltas\` and \`excludedDeltas\` decisions into execution; sync and verify only included deltas
 - Report every excluded delta as \`sync skipped\` without treating the archive itself as skipped
 - Never archive a change while a spec sync is still in flight — run the sync inline and verify main specs at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` before moving \`changeRoot\`