@fission-ai/openspec 1.14.2 → 1.15.0

package/dist/core/specs-apply.js

@@ -15,6 +15,7 @@ import { MarkdownParser } from './parsers/markdown-parser.js';
 import { MIN_PURPOSE_LENGTH, PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from './validation/constants.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { assertSpecFileWithin } from '../utils/spec-path-containment.js';
 import { matchLineEnding } from '../utils/line-endings.js';
 function isLexicallyWithin(allowedDirectory, targetPath) {
     const relative = path.relative(path.resolve(allowedDirectory), path.resolve(targetPath));
@@ -29,7 +30,7 @@ function resolveTrustedSpecPath(specsRoot, specPath, projectRoot) {
     }
     try {
         // Preserve spec.md links that remain inside the overall specs tree.
-        FileSystemUtils.assertPathWithin(specsRoot, specPath);
+        assertSpecFileWithin(specsRoot, specPath);
         const root = FileSystemUtils.canonicalizeExistingPath(specsRoot);
         return {
             root,
@@ -52,7 +53,7 @@ function resolveTrustedSpecPath(specsRoot, specPath, projectRoot) {
             process.emitWarning(`Capability '${path.basename(path.dirname(specPath))}' links outside the project; writing to ${root}`, 'OpenSpecExternalSpecWrite');
         }
         const file = path.join(root, path.basename(specPath));
-        FileSystemUtils.assertPathWithin(root, file);
+        assertSpecFileWithin(root, file);
         return { root, file };
     }
 }
@@ -60,7 +61,7 @@ function assertTrustedSpecPath(root, specPath) {
     if (FileSystemUtils.canonicalizeExistingPath(root) !== path.resolve(root)) {
         throw new Error(`Path is outside the allowed directory: ${specPath}`);
     }
-    FileSystemUtils.assertPathWithin(root, specPath);
+    assertSpecFileWithin(root, specPath);
 }
 // -----------------------------------------------------------------------------
 // Public API
@@ -1042,6 +1043,14 @@ export async function pruneEmptyDirs(startDir, boundaryDir) {
  */
 export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
     assertTrustedSpecPath(update.targetRoot, update.target);
+    // Pin what the assertion just checked. A capability's spec.md may be a link
+    // to the file the project keeps elsewhere, so the write follows a link by
+    // design - and resolving it once, here, is what keeps that from becoming a
+    // redirect: a link repointed after this line, including from inside
+    // `beforeMutate`, cannot send the write to a file nothing verified. The
+    // bytes still land in the same place a path-based write would have put them,
+    // which keeps the in-place semantics below intact.
+    const verifiedTarget = FileSystemUtils.canonicalizeExistingPath(update.target);
     // Create target directory if needed
     const targetDir = path.dirname(update.target);
     await fs.mkdir(targetDir, { recursive: true });
@@ -1051,17 +1060,26 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
     // requirement moved. A spec that does not exist yet stays LF.
     // Only a missing file means "no convention to match". Swallowing every error
     // would read an existing but unreadable spec as absent and rewrite it as LF.
-    const previous = await fs.readFile(update.target, 'utf-8').catch((error) => {
+    const previous = await fs.readFile(verifiedTarget, 'utf-8').catch((error) => {
         if (error.code === 'ENOENT')
             return undefined;
         throw error;
     });
     const toWrite = previous === undefined ? rebuilt : matchLineEnding(rebuilt, previous);
     await options.beforeMutate?.();
+    // `beforeMutate` awaits arbitrary work, so it is the widest gap between the
+    // check above and the write below. Re-check there, and refuse unless the
+    // target still resolves to the very file that was verified: pinning a
+    // pathname is not enough on its own, because the pinned path can itself be
+    // replaced by a link to somewhere else.
+    assertTrustedSpecPath(update.targetRoot, update.target);
+    if (FileSystemUtils.canonicalizeExistingPath(update.target) !== verifiedTarget) {
+        throw new Error(`Spec target for '${update.id}' changed before it could be written: ${update.target}`);
+    }
     // Preserve the established in-place write semantics: symlink referents,
     // hard-linked specs, ACLs, extended attributes, and filesystems without hard
     // links must continue to behave as they did before capability retirement.
-    await fs.writeFile(update.target, toWrite);
+    await fs.writeFile(verifiedTarget, toWrite);
     if (options.silent)
         return;
     const specName = update.id;

package/dist/core/standalone-tip.d.ts

@@ -0,0 +1,6 @@
+export declare const STANDALONE_TIP_MESSAGE = "Tip: OpenSpec also comes as a standalone app that runs without Node.js. To switch, run 'openspec install'.";
+/** Never throws: a hint must not break a command. */
+export declare function maybeShowStandaloneTip(options?: {
+    silent?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=standalone-tip.d.ts.map

package/dist/core/standalone-tip.js

@@ -0,0 +1,38 @@
+/**
+ * One-time note telling package-manager users that the standalone install
+ * exists. It only offers: people who chose npm may have a reason, so it is
+ * shown once, never repeated, and never changes anything.
+ *
+ * Shown on stderr after `openspec update` (the moment people think about
+ * versions), and only for a global package-manager install. Deferred, not
+ * consumed, when nobody would read it: stderr that is not a terminal (agents,
+ * pipes) and CI.
+ */
+import { isCiEnvironment } from '../utils/ci.js';
+import { markConfigFlag, readRawConfig } from './completion-tip.js';
+import { getCliInstallInfo, getStandaloneBinaryPath } from './version-check.js';
+export const STANDALONE_TIP_MESSAGE = "Tip: OpenSpec also comes as a standalone app that runs without Node.js. To switch, run 'openspec install'.";
+/** Never throws: a hint must not break a command. */
+export async function maybeShowStandaloneTip(options = {}) {
+    if (isCiEnvironment() || getStandaloneBinaryPath()) {
+        return;
+    }
+    try {
+        const raw = readRawConfig();
+        if (raw === null || raw.standaloneTipSeen === true || options.silent) {
+            return;
+        }
+        // Project dependencies, npx runs and source checkouts have nothing to switch.
+        if (getCliInstallInfo().scope !== 'global') {
+            return;
+        }
+        // Record before printing: if the flag cannot be saved, staying quiet beats
+        // repeating the note on every run.
+        await markConfigFlag('standaloneTipSeen');
+        console.error(`\n${STANDALONE_TIP_MESSAGE}`);
+    }
+    catch {
+        // Silent failure - a hint should never break the CLI.
+    }
+}
+//# sourceMappingURL=standalone-tip.js.map

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

@@ -14,8 +14,8 @@ const PLANNING_COMPLETE_HANDOFF = optionalWorkflow('apply', 'You can now impleme
  */
 const PARTIAL_ARTIFACT_CHECK = `**Before anything else, finish a partly written artifact**:
    - An artifact whose output is a glob pattern (e.g. \`specs/**/*.md\`) reads \`done\` as soon as one matching file exists, so a run interrupted while writing its files leaves it \`done\` with some still missing
-   - For each such \`done\` artifact, first get its instructions and read any completed dependencies needed to determine the expected files. Then compare those files with \`artifactPaths.<id>.existingOutputPaths\`. For spec-driven's \`specs\`, read the proposal and check for one \`specs/<capability-path>/spec.md\` per capability it lists; resolve each expected path against \`changeRoot\` before comparing path identity
-   - If any are missing, write only the missing files, and STOP - that counts as this invocation's ONE artifact. If you cannot tell whether a file was left out on purpose, ask the user`;
+   - For each such \`done\` artifact, first get its instructions and read any completed dependencies needed to determine the expected files. Then compare those files with \`artifactPaths.<id>.existingOutputPaths\`. For spec-driven's \`specs\`, read the proposal and check for one \`specs/<capability-path>/spec.md\` per capability it lists; resolve each expected path against \`changeRoot\` before comparing path identity, and verify each one remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists
+   - Never write an expected path that fails that check; stop and tell the user. If any are missing, write only the missing files, each at its checked path - when the \`instruction\` field delegates creation to a skill or command, invoke it only if it can write each file to its checked path; otherwise stop and tell the user - and STOP - that counts as this invocation's ONE artifact. If you cannot tell whether a file was left out on purpose, ask the user`;
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
@@ -88,10 +88,13 @@ ${PROJECT_ROOT_GUARD}
      - \`skipped\`/\`warning\`: present when the change declares skip_specs and this artifact must NOT be created - pick another artifact
    - **Create the artifact file**:
      - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
-     - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-     - Otherwise use \`template\` as the structure - fill in its sections
-     - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
-     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and the change's context
+     - Choose the output path before creating anything. If the \`resolvedOutputPath\` specified in instructions is a glob pattern, choose a concrete path inside \`changeRoot\` using the schema instruction and the change's context, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+     - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user
+     - Otherwise, write it yourself:
+       - Use \`template\` as the structure - fill in its sections
+       - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
+       - Write the file to that output path
+     - Either way, verify the artifact file exists at that output path
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 
@@ -119,7 +122,7 @@ After each invocation, show:
 
 The artifact types and their purpose depend on the schema. The \`instruction\` field from the instructions output is the authoritative guidance for each artifact - follow it even when the artifact has a familiar name (proposal.md, tasks.md, etc.), since custom schemas may define different content or a different process for the same file names.
 
-If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly.
+If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there.
 
 **Guardrails**
 - Create ONE artifact per invocation
@@ -210,10 +213,13 @@ ${PROJECT_ROOT_GUARD}
      - \`skipped\`/\`warning\`: present when the change declares skip_specs and this artifact must NOT be created - pick another artifact
    - **Create the artifact file**:
      - Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
-     - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-     - Otherwise use \`template\` as the structure - fill in its sections
-     - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
-     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and the change's context
+     - Choose the output path before creating anything. If the \`resolvedOutputPath\` specified in instructions is a glob pattern, choose a concrete path inside \`changeRoot\` using the schema instruction and the change's context, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+     - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user
+     - Otherwise, write it yourself:
+       - Use \`template\` as the structure - fill in its sections
+       - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
+       - Write the file to that output path
+     - Either way, verify the artifact file exists at that output path
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 
@@ -241,7 +247,7 @@ After each invocation, show:
 
 The artifact types and their purpose depend on the schema. The \`instruction\` field from the instructions output is the authoritative guidance for each artifact - follow it even when the artifact has a familiar name (proposal.md, tasks.md, etc.), since custom schemas may define different content or a different process for the same file names.
 
-If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly.
+If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there.
 
 **Guardrails**
 - Create ONE artifact per invocation

package/dist/core/templates/workflows/explore.js

@@ -156,7 +156,7 @@ If the user asks you to capture the exploration as a new change, that request is
 
 1. Run \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) before creating any artifacts. Never create a new change directory under \`openspec/changes/\` by hand; the CLI scaffold creates required metadata such as \`.openspec.yaml\`. Keep the selected \`--store <id>\` on every applicable follow-up \`status\` and \`instructions\` command.
 2. Run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is \`ready\`, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own \`instruction\` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run \`openspec instructions "<prerequisite-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) for that prerequisite whether it is \`ready\` or \`blocked\`. If its own \`instruction\` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
-3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to \`resolvedOutputPath\`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
+3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. Choose the output path before creating anything: when \`resolvedOutputPath\` is a glob, use the instruction to choose a concrete path inside \`changeRoot\` and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`. If the instruction delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Otherwise write the artifact to that output path. Verify that the selected concrete output exists at that output path.
 4. After creating each artifact, re-run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) and continue until every requested artifact is \`done\`, \`skipped\`, or was deliberately skipped because its own \`instruction\` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still \`blocked\` only because you deliberately skipped a conditional prerequisite, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
 
 Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status. When the requested capture is done, stop there and name where the work continues: ${CAPTURE_PLANNING_HANDOFF}, and ${CAPTURE_APPLY_HANDOFF}. Capturing artifacts never starts implementing them.
@@ -491,7 +491,7 @@ If the user asks you to capture the exploration as a new change, that request is
 
 1. Run \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) before creating any artifacts. Never create a new change directory under \`openspec/changes/\` by hand; the CLI scaffold creates required metadata such as \`.openspec.yaml\`. Keep the selected \`--store <id>\` on every applicable follow-up \`status\` and \`instructions\` command.
 2. Run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is \`ready\`, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own \`instruction\` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run \`openspec instructions "<prerequisite-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) for that prerequisite whether it is \`ready\` or \`blocked\`. If its own \`instruction\` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
-3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to \`resolvedOutputPath\`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
+3. Follow the returned \`template\` and \`instruction\` fields. Read completed dependency files listed in \`dependencies\`, and apply \`context\` and \`rules\` as constraints without copying them into the artifact. Choose the output path before creating anything: when \`resolvedOutputPath\` is a glob, use the instruction to choose a concrete path inside \`changeRoot\` and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`. If the instruction delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Otherwise write the artifact to that output path. Verify that the selected concrete output exists at that output path.
 4. After creating each artifact, re-run \`openspec status --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) and continue until every requested artifact is \`done\`, \`skipped\`, or was deliberately skipped because its own \`instruction\` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still \`blocked\` only because you deliberately skipped a conditional prerequisite, run \`openspec instructions "<artifact-id>" --change "<name>" --json\` (append the confirmed \`--store "<id>"\` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
 
 Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status. When the requested capture is done, stop there and name where the work continues: ${CAPTURE_PLANNING_HANDOFF}, and ${CAPTURE_APPLY_HANDOFF}. Capturing artifacts never starts implementing them.

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

@@ -73,8 +73,9 @@ ${PROJECT_ROOT_GUARD}
         - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
         - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
         - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
-      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-      - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
+      - Choose the output path before creating anything. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose a concrete path inside \`changeRoot\` that matches the glob, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Then verify the artifact file exists at that output path
+      - Otherwise create the artifact file using \`template\` as the structure and write it to that output path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "✓ Created <artifact-id>"
 
@@ -108,7 +109,7 @@ After completing all artifacts, summarize:
 **Artifact Creation Guidelines**
 
 - Follow the \`instruction\` field from \`openspec instructions\` for each artifact type - it is the authoritative guidance, even for familiar artifact names
-- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
+- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use \`template\` as the structure for your output file - fill in its sections
@@ -191,8 +192,9 @@ ${PROJECT_ROOT_GUARD}
         - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
         - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
         - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
-      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-      - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
+      - Choose the output path before creating anything. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose a concrete path inside \`changeRoot\` that matches the glob, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Then verify the artifact file exists at that output path
+      - Otherwise create the artifact file using \`template\` as the structure and write it to that output path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "✓ Created <artifact-id>"
 
@@ -226,7 +228,7 @@ After completing all artifacts, summarize:
 **Artifact Creation Guidelines**
 
 - Follow the \`instruction\` field from \`openspec instructions\` for each artifact type - it is the authoritative guidance, even for familiar artifact names
-- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
+- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use \`template\` as the structure for your output file - fill in its sections

package/dist/core/templates/workflows/propose.js

@@ -119,8 +119,9 @@ ${PROJECT_ROOT_GUARD}
         - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
         - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
         - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
-      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-      - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
+      - Choose the output path before creating anything. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose a concrete path inside \`changeRoot\` that matches the glob, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Then verify the artifact file exists at that output path
+      - Otherwise create the artifact file using \`template\` as the structure and write it to that output path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
@@ -154,7 +155,7 @@ After completing all artifacts, summarize:
 **Artifact Creation Guidelines**
 
 - Follow the \`instruction\` field from \`openspec instructions\` for each artifact type - it is the authoritative guidance, even for familiar artifact names
-- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
+- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use \`template\` as the structure for your output file - fill in its sections
@@ -283,8 +284,9 @@ ${PROJECT_ROOT_GUARD}
         - Identify the target project from the request and project context; the planning home may be separate from the code. If the target is unclear, ask. For greenfield or non-code changes, inspect the available structure and relevant documents. If source is unavailable, state the limitation and ask when it materially affects the plan.
         - Ground scope, approach, and tasks in what you find. Distinguish observed behavior from assumptions and proposed additions; surface conflicts with existing specs instead of silently deciding which is correct.
         - Do this discovery now, rather than leaving generic "explore the codebase" or "make a plan" tasks for implementation. Keep any necessary follow-up investigation specific to an unresolved question.
-      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at \`resolvedOutputPath\`
-      - Otherwise create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose the concrete file path
+      - Choose the output path before creating anything. If \`resolvedOutputPath\` is a glob, follow \`instruction\` to choose a concrete path inside \`changeRoot\` that matches the glob, and verify it remains inside \`changeRoot\` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is \`resolvedOutputPath\`
+      - If the \`instruction\` field delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Then verify the artifact file exists at that output path
+      - Otherwise create the artifact file using \`template\` as the structure and write it to that output path
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "Created <artifact-id>"
 
@@ -318,7 +320,7 @@ After completing all artifacts, summarize:
 **Artifact Creation Guidelines**
 
 - Follow the \`instruction\` field from \`openspec instructions\` for each artifact type - it is the authoritative guidance, even for familiar artifact names
-- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
+- If the \`instruction\` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly - but only once you have chosen and checked the output path, and only if it can write there
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use \`template\` as the structure for your output file - fill in its sections

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

@@ -87,8 +87,8 @@ ${PROJECT_ROOT_GUARD}
        - Add CRITICAL issue: "Requirement not found: <requirement name>"
        - Recommendation: "Implement requirement X: <description>"
      - For each REMOVED requirement, the change asks for the behavior to be gone, so invert the check:
-       - A REMOVED block carries only the requirement name and any \`**Reason**\`/\`**Migration**\` notes, so the delta does not describe the behavior itself. Before searching, read the baseline requirement in the main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`, using the same capability path as the delta spec. Match it by normalized name, scanning that file's requirement headings rather than string-matching the delta's exact title. Its body and scenarios are the evidence for the behavior that must be gone; never search from the requirement name alone.
-       - If that file holds no such requirement under this or a near-equivalent name - for example because an earlier sync already applied the removal - recover the baseline from the same file's history, in the planning repository rather than the current directory: \`git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md\`, or \`git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md\` once you have identified the commit that applied the removal. Empty output means the pathspec matched nothing, not that there is no baseline: \`git log\` reports an unmatched path as success, so re-check the path before drawing any conclusion from silence.
+       - A REMOVED block carries only the requirement name and any \`**Reason**\`/\`**Migration**\` notes, so the delta does not describe the behavior itself. Before searching, read the baseline requirement in the main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`, using the same capability path as the delta spec. Match it by exact normalized name, the rule OpenSpec uses when it applies REMOVED blocks: the heading text after \`Requirement:\`, trimmed, with a closing \`#\` run dropped only when a space or tab precedes it (so \`C#\` keeps its \`#\`), compared case-sensitively. A similarly worded heading is not a match; a rename belongs under RENAMED. Its body and scenarios are the evidence for the behavior that must be gone; never search from the requirement name alone.
+       - If that file holds no requirement with that exact normalized name - for example because an earlier sync already applied the removal, or a similarly named ADDED requirement replaced it - recover the baseline from the same file's history, in the planning repository rather than the current directory: \`git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md\`, or \`git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md\` once you have identified the commit that applied the removal. Empty output means the pathspec matched nothing, not that there is no baseline: \`git log\` reports an unmatched path as success, so re-check the path before drawing any conclusion from silence.
        - A baseline that adds nothing to its own title - no body beyond a restatement of the name, no scenarios - is unusable evidence, the same as a missing one. If no usable baseline is available in either place, mark **Spec Coverage** as not verified for that entry with the reason and stop there: do not search, and never count an unsearched removal as passing.
        - Search codebase for that behavior. Matches in \`openspec/\` artifacts or docs, or in code that serves only the Migration note or an ADDED requirement, are not evidence by themselves. Report any code path that still delivers the removed behavior, including one shared with an ADDED requirement.
        - Finding no implementation is the expected result, but only once the baseline behavior was the thing you searched for. Never report a REMOVED requirement as "Requirement not found" or recommend implementing it.
@@ -299,8 +299,8 @@ ${PROJECT_ROOT_GUARD}
        - Add CRITICAL issue: "Requirement not found: <requirement name>"
        - Recommendation: "Implement requirement X: <description>"
      - For each REMOVED requirement, the change asks for the behavior to be gone, so invert the check:
-       - A REMOVED block carries only the requirement name and any \`**Reason**\`/\`**Migration**\` notes, so the delta does not describe the behavior itself. Before searching, read the baseline requirement in the main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`, using the same capability path as the delta spec. Match it by normalized name, scanning that file's requirement headings rather than string-matching the delta's exact title. Its body and scenarios are the evidence for the behavior that must be gone; never search from the requirement name alone.
-       - If that file holds no such requirement under this or a near-equivalent name - for example because an earlier sync already applied the removal - recover the baseline from the same file's history, in the planning repository rather than the current directory: \`git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md\`, or \`git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md\` once you have identified the commit that applied the removal. Empty output means the pathspec matched nothing, not that there is no baseline: \`git log\` reports an unmatched path as success, so re-check the path before drawing any conclusion from silence.
+       - A REMOVED block carries only the requirement name and any \`**Reason**\`/\`**Migration**\` notes, so the delta does not describe the behavior itself. Before searching, read the baseline requirement in the main spec at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`, using the same capability path as the delta spec. Match it by exact normalized name, the rule OpenSpec uses when it applies REMOVED blocks: the heading text after \`Requirement:\`, trimmed, with a closing \`#\` run dropped only when a space or tab precedes it (so \`C#\` keeps its \`#\`), compared case-sensitively. A similarly worded heading is not a match; a rename belongs under RENAMED. Its body and scenarios are the evidence for the behavior that must be gone; never search from the requirement name alone.
+       - If that file holds no requirement with that exact normalized name - for example because an earlier sync already applied the removal, or a similarly named ADDED requirement replaced it - recover the baseline from the same file's history, in the planning repository rather than the current directory: \`git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md\`, or \`git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md\` once you have identified the commit that applied the removal. Empty output means the pathspec matched nothing, not that there is no baseline: \`git log\` reports an unmatched path as success, so re-check the path before drawing any conclusion from silence.
        - A baseline that adds nothing to its own title - no body beyond a restatement of the name, no scenarios - is unusable evidence, the same as a missing one. If no usable baseline is available in either place, mark **Spec Coverage** as not verified for that entry with the reason and stop there: do not search, and never count an unsearched removal as passing.
        - Search codebase for that behavior. Matches in \`openspec/\` artifacts or docs, or in code that serves only the Migration note or an ADDED requirement, are not evidence by themselves. Report any code path that still delivers the removed behavior, including one shared with an ADDED requirement.
        - Finding no implementation is the expected result, but only once the baseline behavior was the thing you searched for. Never report a REMOVED requirement as "Requirement not found" or recommend implementing it.

package/dist/core/update-plan.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Update Plan
+ *
+ * The write seam `update` uses for every file it generates or removes.
+ *
+ * A real run forwards to the filesystem. A dry run records what the same call
+ * would have done and writes nothing, so the preview and the real update come
+ * from one code path instead of two descriptions of it.
+ */
+import type { FileView } from './file-view.js';
+export type UpdatePlanAction = 'add' | 'update' | 'delete';
+export interface UpdatePlanChange {
+    /** Project-relative POSIX path, or an absolute path (home collapsed to `~`) for files outside the project. */
+    path: string;
+    action: UpdatePlanAction;
+    /**
+     * Tool the file belongs to, as configured (e.g. `claude`), or `openspec`
+     * for OpenSpec's own files: the global config and legacy-artifact cleanup.
+     */
+    tool: string;
+}
+/**
+ * What the plan cannot settle by itself: a step a terminal user is asked
+ * about, which the plan lists as a non-interactive run makes it. Stable
+ * identifiers, for a caller that branches on them.
+ */
+export type UpdatePlanNoteCode = 'legacy-tool-directories' | 'legacy-artifacts';
+export interface UpdatePlanNote {
+    code: UpdatePlanNoteCode;
+    message: string;
+}
+export interface UpdatePlanFailure {
+    tool: string;
+    error: string;
+}
+export interface UpdatePlan {
+    changes: UpdatePlanChange[];
+    /**
+     * Steps a terminal user would be asked about. `changes` lists them as a
+     * non-interactive run makes them. Empty for an ordinary refresh.
+     */
+    notes: UpdatePlanNote[];
+    /**
+     * Tools the real update would fail on. Reported rather than thrown: one
+     * broken tool must not cost the caller the rest of the plan.
+     */
+    failures: UpdatePlanFailure[];
+}
+/** Every filesystem mutation `update` makes while generating artifacts. */
+export interface UpdateFileOps {
+    writeFile(filePath: string, content: string, tool: string): Promise<void>;
+    removeFile(filePath: string, tool: string): Promise<void>;
+    removeDirectory(dirPath: string, tool: string): Promise<void>;
+    /** Removes a directory already known to be empty. */
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+}
+export declare const realFileOps: UpdateFileOps;
+export declare class UpdatePlanRecorder implements UpdateFileOps {
+    private readonly projectPath;
+    private readonly notes;
+    private readonly failures;
+    /**
+     * The tree as the real update would have it so far: absolute path to planned
+     * content, a moved directory, or null once planned away (a removed directory
+     * takes everything under it). Steps that read what an earlier step left
+     * behind read this through `view`.
+     */
+    private readonly staged;
+    /** Every file path the plan has touched, with the tool that touched it last. */
+    private readonly touched;
+    constructor(projectPath: string);
+    writeFile(filePath: string, content: string, tool: string): Promise<void>;
+    removeFile(filePath: string, tool: string): Promise<void>;
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+    removeDirectory(dirPath: string, tool: string): Promise<void>;
+    /**
+     * A rename, as the legacy-root migration makes it: whatever the entry is
+     * moves, a directory with everything in it.
+     */
+    moveFile(source: string, destination: string, tool: string): Promise<void>;
+    /**
+     * The tree with every planned write, move and removal applied. A path the
+     * plan has not touched answers exactly as the disk does.
+     */
+    readonly view: FileView;
+    addNote(code: UpdatePlanNoteCode, message: string): void;
+    addFailure(tool: string, error: string): void;
+    /**
+     * Each touched path, compared as it is on disk now with how the plan leaves
+     * it. A file written and then removed, or rewritten with the bytes it
+     * already had, is no change at all.
+     */
+    getPlan(): UpdatePlan;
+    private stage;
+    /**
+     * What the plan has put at a path: content, a moved directory, null once
+     * planned away, or undefined when the plan has not touched it.
+     */
+    private stagedEntry;
+    /** Whether the plan has put any file or directory below `directory`. */
+    private hasStagedDescendant;
+    /** Files under a directory in the tree as planned: those on disk, and those the plan added. */
+    private filesUnder;
+    /**
+     * What is at a path in the tree as planned, and whether that is what is on
+     * disk (so its permissions are real).
+     */
+    private entryKind;
+    /**
+     * Fails the way the real write would, without writing: a directory where the
+     * file belongs, a file where one of its directories belongs, or no
+     * permission. Recording the write instead would plan past the point where
+     * the real update stops for this tool, listing files it never writes.
+     */
+    private probeWrite;
+    /** Fails the way unlinking the file would. */
+    private probeRemove;
+    /**
+     * The nearest existing ancestor has to be a directory the update can create
+     * entries in; anything it would create below that starts out empty.
+     */
+    private probeCreatableIn;
+    private toDisplayPath;
+}
+/** Human-readable rendering of a dry-run plan. */
+export declare function formatUpdatePlan(plan: UpdatePlan): string;
+//# sourceMappingURL=update-plan.d.ts.map