@fission-ai/openspec 1.6.0 → 1.7.0

package/dist/core/templates/workflows/store-selection.d.ts

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
+export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
 //# sourceMappingURL=store-selection.d.ts.map

package/dist/core/templates/workflows/store-selection.js

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
+export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`, \`view\`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
 //# sourceMappingURL=store-selection.js.map

package/dist/core/templates/workflows/sync-specs.js

@@ -13,13 +13,16 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
-   Show changes that have delta specs (under \`specs/\` directory).
+   When prompting, show changes that have delta specs (under \`specs/\` directory).
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:sync <other>\`).
 
 2. **Resolve change context**
 
@@ -28,9 +31,27 @@ ${STORE_SELECTION_GUIDANCE}
    openspec status --change "<name>" --json
    \`\`\`
 
+   The JSON includes \`planningHome.root\`. Main specs live under \`<planningHome.root>/openspec/specs/\` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
+
 3. **Find delta specs**
 
-   Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the list of delta spec files.
+   Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the
+   only source of delta spec paths. If the \`specs\` entry is missing or
+   \`existingOutputPaths\` is empty, report that there are no delta specs to sync,
+   do not infer them from other artifacts, and stop without requesting artifact
+   instructions or writing a main spec.
+
+   Sync every path in \`existingOutputPaths\` unless the caller narrowed the set.
+   A caller narrows it by naming an explicit list of delta spec paths to sync —
+   archive does this inline, and a user can too ("only sync the billing delta").
+   Then sync only the named paths and leave the remaining delta specs untouched:
+   bulk archive excludes a delta whose implementation it could not find, and
+   syncing it anyway would write a main spec the caller deliberately withheld.
+   Carry that narrowed selection through step 4; never widen it back to the full
+   list. If a named path is not in \`existingOutputPaths\`, do not sync it —
+   report it and stop, rather than dropping it silently. If the named list is
+   empty, report that there is nothing to sync and stop without writing a main
+   spec.
 
    Each delta spec file contains sections like:
    - \`## ADDED Requirements\` - New requirements to add
@@ -42,11 +63,27 @@ ${STORE_SELECTION_GUIDANCE}
 
 4. **For each delta spec, apply changes to main specs**
 
-   For each repo-local capability delta spec path returned by the CLI:
+   Before the first main-spec write, obtain one current specs-rule snapshot:
+   - If archive invoked this workflow inline and supplied a valid snapshot from
+     \`openspec instructions specs --change "<name>" --json\`, reuse it and do not
+     fetch the same instructions again.
+   - Otherwise run that command once now with the same selected-root flags.
+   - If the direct lookup exits non-zero or returns invalid artifact-instruction
+     JSON, report the error and stop before writing any main spec. Do not treat the
+     failure as an absent rule set.
+   - A valid response with omitted \`rules\` means no artifact rules are configured
+     and the existing semantic merge continues.
+
+   Apply returned \`rules\` only to the content and form of the main specs produced
+   by this merge. Artifact rules are not operation guidance and cannot change
+   selected roots, delta paths, CLI checks, or workflow steps. Use their text as
+   constraints without copying it verbatim into a main spec or summary.
+
+   For each capability delta spec path selected in step 3 — the full \`existingOutputPaths\` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
 
    a. **Read the delta spec** to understand the intended changes
 
-   b. **Read the main spec** at \`openspec/specs/<capability>/spec.md\` (may not exist yet)
+   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability>/spec.md\` (may not exist yet)
 
    c. **Apply changes intelligently**:
 
@@ -68,20 +105,32 @@ ${STORE_SELECTION_GUIDANCE}
       **RENAMED Requirements:**
       - Find the FROM requirement, rename to TO
 
+      **\`## Purpose\` in the delta:**
+      - The main spec already has one and it is authoritative - leave it alone
+        (this is what \`openspec archive\` does; it warns and moves on)
+
    d. **Create new main spec** if capability doesn't exist yet:
-      - Create \`openspec/specs/<capability>/spec.md\`
-      - Add Purpose section (can be brief, mark as TBD)
+      - Create \`<planningHome.root>/openspec/specs/<capability>/spec.md\`
+      - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
+        (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not
       - Add Requirements section with the ADDED requirements
+      - Follow the **Main Spec Format Reference** below
 
 5. **Show summary**
 
    After applying all changes, summarize:
    - Which capabilities were updated
    - What changes were made (requirements added/modified/removed/renamed)
+   - Any new main spec left with a TBD Purpose placeholder, so it gets written
+     now rather than lingering
 
 **Delta Spec Format Reference**
 
 \`\`\`markdown
+## Purpose
+
+Only on a delta that introduces a brand-new capability. Seeds the new main spec.
+
 ## ADDED Requirements
 
 ### Requirement: New Feature
@@ -108,6 +157,26 @@ The system SHALL do something new.
 - TO: \`### Requirement: New Name\`
 \`\`\`
 
+**Main Spec Format Reference**
+
+Main specs are what the delta merges INTO. They must never contain delta operation headers (\`## ADDED/MODIFIED/REMOVED/RENAMED Requirements\`) - after syncing, every requirement lives under a single \`## Requirements\` section:
+
+\`\`\`markdown
+# <capability> Specification
+
+## Purpose
+Short description of what this capability does and why it exists.
+
+## Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+\`\`\`
+
 **Key Principle: Intelligent Merging**
 
 Unlike programmatic merging, you can apply **partial updates**:
@@ -117,7 +186,7 @@ Unlike programmatic merging, you can apply **partial updates**:
 
 **Output On Success**
 
-\`\`\`
+\`\`\`markdown
 ## Specs Synced: <change-name>
 
 Updated main specs:
@@ -136,9 +205,15 @@ Main specs are now updated. The change remains active - archive when implementat
 **Guardrails**
 - Read both delta and main specs before making changes
 - Preserve existing content not mentioned in delta
+- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
 - If something is unclear, ask for clarification
 - Show what you're changing as you go
-- The operation should be idempotent - running twice should give same result`,
+- The operation should be idempotent - running twice should give same result
+- Use only \`artifactPaths.specs.existingOutputPaths\`; never infer delta specs from unrelated artifacts
+- Honor a caller-supplied subset of \`existingOutputPaths\`; never widen it back to the full list
+- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
+- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
+- Artifact rules constrain only the specs being written and are never copied into output files`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -160,13 +235,16 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
-   Show changes that have delta specs (under \`specs/\` directory).
+   When prompting, show changes that have delta specs (under \`specs/\` directory).
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:sync <other>\`).
 
 2. **Resolve change context**
 
@@ -175,9 +253,27 @@ ${STORE_SELECTION_GUIDANCE}
    openspec status --change "<name>" --json
    \`\`\`
 
+   The JSON includes \`planningHome.root\`. Main specs live under \`<planningHome.root>/openspec/specs/\` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
+
 3. **Find delta specs**
 
-   Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the list of delta spec files.
+   Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the
+   only source of delta spec paths. If the \`specs\` entry is missing or
+   \`existingOutputPaths\` is empty, report that there are no delta specs to sync,
+   do not infer them from other artifacts, and stop without requesting artifact
+   instructions or writing a main spec.
+
+   Sync every path in \`existingOutputPaths\` unless the caller narrowed the set.
+   A caller narrows it by naming an explicit list of delta spec paths to sync —
+   archive does this inline, and a user can too ("only sync the billing delta").
+   Then sync only the named paths and leave the remaining delta specs untouched:
+   bulk archive excludes a delta whose implementation it could not find, and
+   syncing it anyway would write a main spec the caller deliberately withheld.
+   Carry that narrowed selection through step 4; never widen it back to the full
+   list. If a named path is not in \`existingOutputPaths\`, do not sync it —
+   report it and stop, rather than dropping it silently. If the named list is
+   empty, report that there is nothing to sync and stop without writing a main
+   spec.
 
    Each delta spec file contains sections like:
    - \`## ADDED Requirements\` - New requirements to add
@@ -189,11 +285,27 @@ ${STORE_SELECTION_GUIDANCE}
 
 4. **For each delta spec, apply changes to main specs**
 
-   For each repo-local capability delta spec path returned by the CLI:
+   Before the first main-spec write, obtain one current specs-rule snapshot:
+   - If archive invoked this workflow inline and supplied a valid snapshot from
+     \`openspec instructions specs --change "<name>" --json\`, reuse it and do not
+     fetch the same instructions again.
+   - Otherwise run that command once now with the same selected-root flags.
+   - If the direct lookup exits non-zero or returns invalid artifact-instruction
+     JSON, report the error and stop before writing any main spec. Do not treat the
+     failure as an absent rule set.
+   - A valid response with omitted \`rules\` means no artifact rules are configured
+     and the existing semantic merge continues.
+
+   Apply returned \`rules\` only to the content and form of the main specs produced
+   by this merge. Artifact rules are not operation guidance and cannot change
+   selected roots, delta paths, CLI checks, or workflow steps. Use their text as
+   constraints without copying it verbatim into a main spec or summary.
+
+   For each capability delta spec path selected in step 3 — the full \`existingOutputPaths\` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
 
    a. **Read the delta spec** to understand the intended changes
 
-   b. **Read the main spec** at \`openspec/specs/<capability>/spec.md\` (may not exist yet)
+   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability>/spec.md\` (may not exist yet)
 
    c. **Apply changes intelligently**:
 
@@ -215,20 +327,32 @@ ${STORE_SELECTION_GUIDANCE}
       **RENAMED Requirements:**
       - Find the FROM requirement, rename to TO
 
+      **\`## Purpose\` in the delta:**
+      - The main spec already has one and it is authoritative - leave it alone
+        (this is what \`openspec archive\` does; it warns and moves on)
+
    d. **Create new main spec** if capability doesn't exist yet:
-      - Create \`openspec/specs/<capability>/spec.md\`
-      - Add Purpose section (can be brief, mark as TBD)
+      - Create \`<planningHome.root>/openspec/specs/<capability>/spec.md\`
+      - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
+        (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not
       - Add Requirements section with the ADDED requirements
+      - Follow the **Main Spec Format Reference** below
 
 5. **Show summary**
 
    After applying all changes, summarize:
    - Which capabilities were updated
    - What changes were made (requirements added/modified/removed/renamed)
+   - Any new main spec left with a TBD Purpose placeholder, so it gets written
+     now rather than lingering
 
 **Delta Spec Format Reference**
 
 \`\`\`markdown
+## Purpose
+
+Only on a delta that introduces a brand-new capability. Seeds the new main spec.
+
 ## ADDED Requirements
 
 ### Requirement: New Feature
@@ -255,6 +379,26 @@ The system SHALL do something new.
 - TO: \`### Requirement: New Name\`
 \`\`\`
 
+**Main Spec Format Reference**
+
+Main specs are what the delta merges INTO. They must never contain delta operation headers (\`## ADDED/MODIFIED/REMOVED/RENAMED Requirements\`) - after syncing, every requirement lives under a single \`## Requirements\` section:
+
+\`\`\`markdown
+# <capability> Specification
+
+## Purpose
+Short description of what this capability does and why it exists.
+
+## Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+\`\`\`
+
 **Key Principle: Intelligent Merging**
 
 Unlike programmatic merging, you can apply **partial updates**:
@@ -264,7 +408,7 @@ Unlike programmatic merging, you can apply **partial updates**:
 
 **Output On Success**
 
-\`\`\`
+\`\`\`markdown
 ## Specs Synced: <change-name>
 
 Updated main specs:
@@ -283,9 +427,15 @@ Main specs are now updated. The change remains active - archive when implementat
 **Guardrails**
 - Read both delta and main specs before making changes
 - Preserve existing content not mentioned in delta
+- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
 - If something is unclear, ask for clarification
 - Show what you're changing as you go
-- The operation should be idempotent - running twice should give same result`
+- The operation should be idempotent - running twice should give same result
+- Use only \`artifactPaths.specs.existingOutputPaths\`; never infer delta specs from unrelated artifacts
+- Honor a caller-supplied subset of \`existingOutputPaths\`; never widen it back to the full list
+- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
+- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
+- Artifact rules constrain only the specs being written and are never copied into output files`
     };
 }
 //# sourceMappingURL=sync-specs.js.map

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

@@ -11,11 +11,14 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes sorted by most recently modified, and ask the user to select one
 
-   Present the top 3-4 most recently modified changes as options, showing:
+   When prompting, present the top 3-4 most recently modified changes as options, showing:
    - Change name
    - Schema (from \`schema\` field if present, otherwise "spec-driven")
    - Status (e.g., "0/5 tasks", "complete", "no tasks")
@@ -23,7 +26,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:update <other>\`).
 
 2. **Get the change's artifacts**
    \`\`\`bash
@@ -31,7 +34,7 @@ ${STORE_SELECTION_GUIDANCE}
    \`\`\`
    Parse the JSON to understand current state. The response includes:
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
-   - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
+   - \`artifacts\`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
    - \`isComplete\`: Boolean indicating if all artifacts are complete
    - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
@@ -76,7 +79,8 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).`,
+- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).
+- \`/opsx:continue\` and \`/opsx:new\` may not be installed (core profile). When suggesting one that is unavailable, point to the CLI instead: \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` explains how to create it.`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -96,11 +100,14 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes sorted by most recently modified, and ask the user to select one
 
-   Present the top 3-4 most recently modified changes as options, showing:
+   When prompting, present the top 3-4 most recently modified changes as options, showing:
    - Change name
    - Schema (from \`schema\` field if present, otherwise "spec-driven")
    - Status (e.g., "0/5 tasks", "complete", "no tasks")
@@ -108,7 +115,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:update <other>\`).
 
 2. **Get the change's artifacts**
    \`\`\`bash
@@ -116,7 +123,7 @@ ${STORE_SELECTION_GUIDANCE}
    \`\`\`
    Parse the JSON to understand current state. The response includes:
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
-   - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
+   - \`artifacts\`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
    - \`isComplete\`: Boolean indicating if all artifacts are complete
    - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
@@ -161,7 +168,8 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).`
+- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).
+- \`/opsx:continue\` and \`/opsx:new\` may not be installed (core profile). When suggesting one that is unavailable, point to the CLI instead: \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` explains how to create it.`
     };
 }
 //# sourceMappingURL=update-change.js.map

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

@@ -11,15 +11,18 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
-   Show changes that have implementation tasks (tasks artifact exists).
+   When prompting, show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.
    Mark changes with incomplete tasks as "(In Progress)".
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:verify <other>\`).
 
 2. **Check status to understand the schema**
    \`\`\`bash
@@ -107,7 +110,7 @@ ${STORE_SELECTION_GUIDANCE}
 8. **Generate Verification Report**
 
    **Summary Scorecard**:
-   \`\`\`
+   \`\`\`markdown
    ## Verification Report: <change-name>
 
    ### Summary
@@ -182,15 +185,18 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Select the change**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
-   Show changes that have implementation tasks (tasks artifact exists).
+   When prompting, show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.
    Mark changes with incomplete tasks as "(In Progress)".
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:verify <other>\`).
 
 2. **Check status to understand the schema**
    \`\`\`bash
@@ -278,7 +284,7 @@ ${STORE_SELECTION_GUIDANCE}
 8. **Generate Verification Report**
 
    **Summary Scorecard**:
-   \`\`\`
+   \`\`\`markdown
    ## Verification Report: <change-name>
 
    ### Summary

package/dist/core/update.d.ts

@@ -21,6 +21,12 @@ export declare function scanInstalledWorkflows(projectPath: string, toolIds: str
 export declare class UpdateCommand {
     private readonly force;
     constructor(options?: UpdateCommandOptions);
+    /**
+     * Refreshes OpenSpec skills and commands for all configured tools,
+     * regenerating artifacts according to the effective profile and delivery mode.
+     *
+     * @param projectPath - Path to the project root containing the openspec directory
+     */
     execute(projectPath: string): Promise<void>;
     /**
      * Display message when all tools are up to date.
@@ -30,6 +36,11 @@ export declare class UpdateCommand {
      * Display the update plan showing which tools need updating.
      */
     private displayUpdatePlan;
+    /**
+     * Shows manual setup notes for configured tools that need extra
+     * configuration before they pick up generated files.
+     */
+    private displaySetupNotes;
     /**
      * Detects new tool directories that aren't currently configured and displays a hint.
      */
@@ -39,10 +50,11 @@ export declare class UpdateCommand {
      */
     private displayExtraWorkflowsNote;
     /**
-     * Suggest opting back into core when a custom profile still matches the old
-     * pre-sync core set. Keep custom profiles user-owned; do not mutate them.
+     * Point out core workflows a custom profile is missing, so releases that
+     * grow CORE_WORKFLOWS stay discoverable. Keep custom profiles user-owned;
+     * do not mutate them.
      */
-    private displayOldCoreCustomProfileNote;
+    private displayMissingCoreWorkflowsNote;
     /**
      * Removes skill directories for workflows when delivery changed to commands-only.
      * Returns the number of directories removed.
@@ -63,19 +75,41 @@ export declare class UpdateCommand {
      * Returns the number of files removed.
      */
     private removeUnselectedCommandFiles;
+    /**
+     * Offers to move OpenSpec content out of a renamed tool's former directory
+     * when the old location might still be the live one — today, Windsurf's
+     * `.windsurf/` after the Devin Desktop rebrand.
+     *
+     * Interactive runs are asked, because nothing on disk distinguishes a user
+     * who took the rebrand from one still on a pre-rebrand Windsurf build that
+     * reads only `.windsurf/`. `--force` and non-interactive runs migrate, which
+     * is what an unattended upgrade wants.
+     */
+    /** Surfaces files the move left behind rather than overwriting. */
+    private reportKeptInPlace;
+    private offerConsentedLegacyMigrations;
     /**
      * Detect and handle legacy OpenSpec artifacts.
      * Unlike init, update warns but continues if legacy files found in non-interactive mode.
      * Returns array of tool IDs that were newly configured during legacy upgrade.
      */
     private handleLegacyCleanup;
+    /**
+     * Cleans approved repo-local legacy artifacts before configured tools refresh.
+     */
+    private performImmediateLegacyCleanup;
+    /**
+     * Cleans approved global Codex prompts after configured tools refresh so newly
+     * installed replacement skills can retire their prompts in the same run.
+     */
+    private performDeferredGlobalPromptCleanup;
     /**
      * Perform cleanup of legacy artifacts.
      */
     private performLegacyCleanup;
     /**
-     * Upgrade legacy tools to new skills system.
-     * Returns array of tool IDs that were newly configured.
+     * Upgrades unconfigured legacy tools into the skills-based setup and carries
+     * workflow overrides for migrations that should mirror legacy Codex prompts.
      */
     private upgradeLegacyTools;
 }