@fission-ai/openspec 1.14.1 → 1.14.2

package/README.md

@@ -33,11 +33,6 @@ Our philosophy:
 → scalable from personal projects to enterprises
 ```
 
-> [!TIP]
-> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
->
-> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
-
 <p align="center">
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
@@ -112,13 +107,13 @@ OpenSpec is built with OpenSpec — browse this repo's live [specs](openspec/spe
 
 Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
 
-**[Stores](docs/stores-beta/user-guide.md)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
+**[Stores](https://openspec.dev/docs/stores)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
 
 - **Cross-repo features** — one change, one plan, even when the code lands in three repos.
 - **Shared requirements** — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
 - **Plan before code** — capture the plan in the store now; the code repos catch up later.
 
-> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
+> Stores are in **beta**. Start with the [Stores guide](https://openspec.dev/docs/stores).
 
 ## Quick Start
 
@@ -143,44 +138,33 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](https://openspec.dev/docs/installation#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 Now talk to your AI:
 
-- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Explore guide](docs/explore.md))
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Quickstart](https://openspec.dev/docs/quickstart))
 - **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
 
 Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
-`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [How To Invoke](docs/supported-tools.md#how-to-invoke).
+`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [Supported Tools](https://openspec.dev/docs/supported-tools).
 
 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
+> Not sure if your tool is supported? [View the full list](https://openspec.dev/docs/supported-tools) – we support 30+ tools and growing.
 >
-> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
 
 ## Docs
 
-**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
-
-→ **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
-→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
-→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
-→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
-→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
-→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
-→ **[Commands](docs/commands.md)**: slash commands & skills<br>
-→ **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
-→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
-→ **[Concepts](docs/concepts.md)**: how it all fits<br>
-→ **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours<br>
-→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
-→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
+Full documentation lives at **[openspec.dev/docs](https://openspec.dev/docs)**.
 
+→ **[Quickstart](https://openspec.dev/docs/quickstart)**: your first change, start to finish<br>
+→ **[Set up your project](https://openspec.dev/docs/setup)**: what `openspec init` installs<br>
+→ **[CLI](https://openspec.dev/docs/cli)**: terminal reference<br>
+→ **[Supported Tools](https://openspec.dev/docs/supported-tools)**: tool integrations & install paths<br>
+→ **[Customize](https://openspec.dev/docs/customize)**: profiles, project config, and schemas<br>
+→ **[Stores](https://openspec.dev/docs/stores)**: plan in a separate repo, shared across your team (beta)<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec
 
 ## Community schemas
 

package/dist/cli/index.d.ts

@@ -27,6 +27,11 @@ export declare function isJsonRun(command: Command): boolean;
  * completions is noise, and `__complete` would burn the one-shot tip invisibly.
  */
 export declare function isCompletionRun(commandPath: string): boolean;
+/**
+ * True for the hidden `__complete` resolver alone. It runs on every Tab press,
+ * so the hooks skip telemetry and the completion tip for it entirely.
+ */
+export declare function isTabCompletionRun(commandPath: string): boolean;
 /**
  * True when the first-run completions tip must be deferred rather than shown.
  *

package/dist/cli/index.js

@@ -90,6 +90,13 @@ export function isJsonRun(command) {
 export function isCompletionRun(commandPath) {
     return commandPath.split(':')[0] === 'completion' || commandPath === '__complete';
 }
+/**
+ * True for the hidden `__complete` resolver alone. It runs on every Tab press,
+ * so the hooks skip telemetry and the completion tip for it entirely.
+ */
+export function isTabCompletionRun(commandPath) {
+    return commandPath === '__complete';
+}
 /**
  * True when the first-run completions tip must be deferred rather than shown.
  *
@@ -149,6 +156,12 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
+    // `__complete` runs on every Tab press, with stderr sent to /dev/null by the
+    // generated scripts. Tracking it would hold each press open for the request,
+    // and the first-run notice would be marked seen without anyone reading it.
+    if (isTabCompletionRun(getCommandPath(actionCommand))) {
+        return;
+    }
     // Show first-run telemetry notice (if not seen). It's written to stderr, so it
     // never pollutes stdout — but --json runs still defer it (see isJsonRun) so the
     // very first invocation stays free of any incidental output on either stream.
@@ -160,6 +173,11 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
 });
 // Shutdown telemetry after command completes
 program.hook('postAction', async (_thisCommand, actionCommand) => {
+    // Nothing to flush (preAction tracked nothing), and the tip is always
+    // deferred for completion runs, so skip loading either module.
+    if (isTabCompletionRun(getCommandPath(actionCommand))) {
+        return;
+    }
     // Show the first-run shell-completions tip (on stderr, so piped stdout stays
     // clean). postAction, not preAction: the tip trails the command's own output
     // instead of pushing an error message or `init`'s setup summary down the

package/dist/commands/completion.js

@@ -1,4 +1,3 @@
-import ora from 'ora';
 import { CompletionFactory } from '../core/completions/factory.js';
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { detectShell } from '../utils/shell-detection.js';
@@ -93,6 +92,9 @@ export class CompletionCommand {
     async installForShell(shell, verbose) {
         const generator = CompletionFactory.createGenerator(shell);
         const installer = CompletionFactory.createInstaller(shell);
+        // Loaded here, not at the top: `__complete` shares this module and runs on
+        // every Tab press, so it must not pay for the spinner.
+        const { default: ora } = await import('ora');
         const spinner = ora(`Installing ${shell} completion script...`).start();
         try {
             // Generate the completion script
@@ -187,6 +189,7 @@ export class CompletionCommand {
                 return;
             }
         }
+        const { default: ora } = await import('ora');
         const spinner = ora(`Uninstalling ${shell} completion script...`).start();
         try {
             const result = await installer.uninstall();

package/dist/core/archive.js

@@ -1078,13 +1078,22 @@ export class ArchiveCommand {
         const changesDir = root.changesDir;
         const archiveDir = root.archiveDir;
         const mainSpecsDir = root.specsDir;
-        for (const [allowedDirectory, managedDir] of [
-            [root.path, changesDir],
-            [changesDir, archiveDir],
-            [root.path, mainSpecsDir],
+        const openspecDir = path.dirname(changesDir);
+        // openspec/, changes/ and specs/ may be project-owned symlinks to another
+        // directory; archive/ may not leave the changes directory it lives in.
+        for (const [allowedDirectory, managedDir, allowLinkedLeaf] of [
+            [root.path, openspecDir, true],
+            [openspecDir, changesDir, true],
+            [changesDir, archiveDir, false],
+            [openspecDir, mainSpecsDir, true],
         ]) {
             try {
-                FileSystemUtils.assertPathWithin(allowedDirectory, managedDir);
+                if (allowLinkedLeaf) {
+                    FileSystemUtils.assertPathWithinAllowingLinkedLeaf(allowedDirectory, managedDir);
+                }
+                else {
+                    FileSystemUtils.assertPathWithin(allowedDirectory, managedDir);
+                }
             }
             catch {
                 throw new ArchiveBlockedError('archive_path_outside_root', `Refusing to archive through a path outside the OpenSpec root: ${managedDir}`);
@@ -1744,6 +1753,9 @@ export class ArchiveCommand {
                             if (hasRetirements) {
                                 await assertRetirementAuthorization(changeDir, retirementAuthorizationFingerprint);
                             }
+                            // update.source is canonical (symlinks resolved), so measure it from
+                            // the canonical change directory; changes/ may itself be a symlink.
+                            const canonicalChangeDir = FileSystemUtils.canonicalizeExistingPath(changeDir);
                             const verifyArchivedDeltas = async (stagedSource) => {
                                 if (hasRetirements) {
                                     await assertRetirementAuthorization(archivePath, retirementAuthorizationFingerprint, 
@@ -1757,13 +1769,13 @@ export class ArchiveCommand {
                                     }
                                 }
                                 for (const proposed of prepared) {
-                                    const archivedSource = path.join(archivePath, path.relative(changeDir, proposed.update.source));
+                                    const archivedSource = path.join(archivePath, path.relative(canonicalChangeDir, proposed.update.source));
                                     if ((await fingerprintPortableContent(archivedSource)) !==
                                         proposed.sourceContentFingerprint) {
                                         throw new Error(`The archived delta for '${proposed.update.id}' changed during the final move.`);
                                     }
                                     if (stagedSource) {
-                                        const stagedDelta = path.join(stagedSource, path.relative(changeDir, proposed.update.source));
+                                        const stagedDelta = path.join(stagedSource, path.relative(canonicalChangeDir, proposed.update.source));
                                         if ((await fingerprintPortableContent(stagedDelta)) !==
                                             proposed.sourceContentFingerprint) {
                                             throw new Error(`The active delta for '${proposed.update.id}' changed during the fallback copy.`);

package/dist/core/artifact-graph/outputs.js

@@ -4,6 +4,41 @@ import fg from 'fast-glob';
 import { FileSystemUtils } from '../../utils/file-system.js';
 const EXTGLOB_RE = /[!*+?@]\([^(]*\)/u;
 const BRACE_EXPANSION_SEPARATORS_RE = /,|\.\./u;
+// braces <=3.0.3 (fast-glob > micromatch) has no depth guard (GHSA-vfj7-8cjw-p6xm),
+// so reject nesting no real artifact pattern needs before it reaches the parser.
+const MAX_BRACE_NESTING = 16;
+function assertBraceNesting(pattern) {
+    // Mirror the braces parser: `[...]` and quoted runs are literal, `(` nests like
+    // `{`, and a closer only closes the innermost group of its own kind.
+    const open = [];
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === '[') {
+            for (let brackets = 1; brackets > 0 && index + 1 < pattern.length;) {
+                index += 1;
+                if (pattern[index] === '[')
+                    brackets += 1;
+                else if (pattern[index] === ']')
+                    brackets -= 1;
+            }
+        }
+        else if (char === '"' || char === "'" || char === '`') {
+            const end = pattern.indexOf(char, index + 1);
+            index = end === -1 ? pattern.length : end;
+        }
+        else if (char === '{' || char === '(') {
+            open.push(char);
+            if (open.length > MAX_BRACE_NESTING) {
+                // A pattern this deep can run to thousands of characters; quote only its start.
+                const shown = pattern.length > 80 ? `${pattern.slice(0, 80)}...` : pattern;
+                throw new Error(`Artifact output pattern nests braces more than ${MAX_BRACE_NESTING} levels deep: ${shown}`);
+            }
+        }
+        else if ((char === '}' && open.at(-1) === '{') || (char === ')' && open.at(-1) === '(')) {
+            open.pop();
+        }
+    }
+}
 function hasBraceExpansion(pattern) {
     const openings = [];
     for (let index = 0; index < pattern.length; index += 1) {
@@ -90,8 +125,11 @@ function assertGlobDirectoryTraversal(changeDir, currentDir, directorySegments,
  * Returns absolute file paths. Glob matches are sorted for deterministic output.
  */
 export function resolveArtifactOutputs(changeDir, generates) {
+    const isGlob = isGlobPattern(generates);
+    if (isGlob)
+        assertBraceNesting(FileSystemUtils.toPosixPath(generates));
     const outputPath = resolveArtifactOutputPath(changeDir, generates);
-    if (!isGlobPattern(generates)) {
+    if (!isGlob) {
         try {
             return fs.statSync(outputPath).isFile()
                 ? [FileSystemUtils.canonicalizeExistingPath(outputPath)]

package/dist/core/completions/completion-provider.js

@@ -1,5 +1,4 @@
 import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
-import { listSchemas } from '../artifact-graph/index.js';
 /**
  * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
  * Implements a 2-second cache to avoid excessive file system operations during
@@ -74,7 +73,10 @@ export class CompletionProvider {
         if (this.schemaCache && now - this.schemaCache.timestamp < this.cacheTTL) {
             return this.schemaCache.data;
         }
-        // Fetch fresh data
+        // Fetch fresh data. The resolver (and the yaml and zod it parses schemas
+        // with) loads only here: completing changes or specs never needs it, and
+        // the artifact-graph barrel would also pull in fast-glob.
+        const { listSchemas } = await import('../artifact-graph/resolver.js');
         const schemaNames = listSchemas(this.projectRoot);
         // Update cache
         this.schemaCache = {

package/dist/core/parsers/requirement-blocks.d.ts

@@ -70,6 +70,15 @@ export interface OrphanedRequirement {
     section: string | null;
     line: number;
 }
+/**
+ * Authored text archive does not carry into the main spec: a non-delta `## `
+ * section, text above the first `## `, or prose before the first requirement
+ * in ADDED/MODIFIED. `section` is null for text above the first `## `.
+ */
+export interface UnappliedContent {
+    section: string | null;
+    line: number;
+}
 export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
@@ -83,6 +92,7 @@ export interface DeltaPlan {
     unpairedRenames: UnpairedRename[];
     /** Canonical requirement blocks written outside every delta section. */
     orphanedRequirements: OrphanedRequirement[];
+    unappliedContent: UnappliedContent[];
     skippedHeaders: SkippedHeader[];
     sectionPresence: {
         added: boolean;
@@ -95,6 +105,7 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+export declare function describeUnappliedContent(content: UnappliedContent, sentenceStart?: boolean): string;
 /** Both directions of the scenario-name comparison, plus the two totals. */
 export interface ScenarioNameDiff {
     /** Names the current block has that the incoming block does not cover. */

package/dist/core/parsers/requirement-blocks.js

@@ -136,6 +136,7 @@ export function parseDeltaSpec(content) {
         renamed: renamedPairs,
         unpairedRenames,
         orphanedRequirements: findOrphanedRequirements(lines, fenceMask),
+        unappliedContent: findUnappliedContent(lines, fenceMask),
         skippedHeaders,
         sectionPresence: {
             added: addedLookup.found,
@@ -187,6 +188,62 @@ function findOrphanedRequirements(lines, fenceMask) {
     }
     return orphans;
 }
+export function describeUnappliedContent(content, sentenceStart = false) {
+    const text = content.section === null
+        ? 'text above the first "## " section'
+        : DELTA_SECTION_TITLES.has(content.section.toLowerCase())
+            ? `text before the first requirement in "## ${content.section}"`
+            : `section "## ${content.section}"`;
+    return sentenceStart ? text.charAt(0).toUpperCase() + text.slice(1) : text;
+}
+/**
+ * Where text the merge never reads begins. HTML comments, `# ` titles, Purpose
+ * (warned about separately), REMOVED/RENAMED bodies, and stray `###` headers
+ * before the first requirement (INFO since #498) are not reported.
+ */
+function findUnappliedContent(lines, fenceMask) {
+    // Blank out comments outside fences, keeping line count; an unterminated one
+    // runs to EOF. Comments only decide whether a line holds text: sections come
+    // from the same split the merge reads, where a `## ` line inside a comment is
+    // still a boundary. Fenced lines keep their text, so a `<!--` in a code sample
+    // never hides what follows the fence.
+    const comments = lines
+        .map((line, i) => (fenceMask[i] ? '' : line))
+        .join('\n')
+        .replace(/<!--[\s\S]*?(?:--!?>|$)/g, (m) => m.replace(/[^\n]/g, ' '))
+        .split('\n');
+    const masked = lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+    const sections = splitTopLevelSections(lines, fenceMask);
+    const firstText = (from, to, skip) => {
+        for (let i = from; i < to; i++)
+            if (masked[i].trim() && !skip?.test(masked[i]))
+                return i;
+        return -1;
+    };
+    const found = [];
+    const preamble = firstText(0, sections.length ? sections[0].body.bodyStartLine - 2 : lines.length, /^#\s/);
+    if (preamble !== -1)
+        found.push({ section: null, line: preamble + 1 });
+    for (const { title, body } of sections) {
+        const folded = title.toLowerCase();
+        const start = body.bodyStartLine - 1;
+        if (folded === 'added requirements' || folded === 'modified requirements') {
+            const block = body.lines.findIndex((l, i) => !body.fenceMask[i] && REQUIREMENT_HEADER_REGEX.test(l));
+            const first = firstText(start, start + (block === -1 ? body.lines.length : block), /^###\s/);
+            if (first !== -1)
+                found.push({ section: title, line: first + 1 });
+        }
+        else if (!DELTA_SECTION_TITLES.has(folded)) {
+            // The Purpose carry-over reads past commented-out headers, so only a
+            // `## Purpose` outside a comment is the one archive handles.
+            if (folded === 'purpose' && masked[start - 1].trim())
+                continue;
+            if (firstText(start, start + body.lines.length) !== -1)
+                found.push({ section: title, line: start });
+        }
+    }
+    return found;
+}
 /**
  * Every `## ` section, as a LIST rather than a title-keyed record.
  *

package/dist/core/specs-apply.js

@@ -8,7 +8,7 @@ import { promises as fs } from 'fs';
 import { randomUUID } from 'crypto';
 import path from 'path';
 import chalk from 'chalk';
-import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
@@ -145,6 +145,10 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             `which is not a delta section, so it was not applied. ` +
             `Move it under ADDED/MODIFIED/REMOVED/RENAMED Requirements.`);
     }
+    // Archive carries requirement blocks only; name any other text it leaves behind.
+    for (const lost of plan.unappliedContent) {
+        warn(`${specName} - ${describeUnappliedContent(lost)} (line ${lost.line}) is not carried into the main spec.`);
+    }
     // Pre-validate duplicates within sections
     const addedNames = new Set();
     for (const add of plan.added) {

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

@@ -178,6 +178,8 @@ If the user mentions a change or you detect one is relevant:
 
    \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
 
+   The files below are the default spec-driven schema's. With another schema, capture each insight in whichever artifact from \`artifactPaths\` fits it, and name that artifact in your offer; never create an artifact the schema does not define.
+
     | Insight Type               | Where to Capture                    |
     |----------------------------|-------------------------------------|
     | New requirement discovered | \`specs/<capability-path>/spec.md\` |
@@ -187,7 +189,7 @@ If the user mentions a change or you detect one is relevant:
     | New work identified        | \`tasks.md\`                        |
     | Assumption invalidated     | Relevant artifact                   |
 
-   Example offers:
+   Example offers (default schema):
    - "That's a design decision. Capture it in design.md?"
    - "This is a new requirement. Add it to specs?"
    - "This changes scope. Update the proposal?"
@@ -316,7 +318,7 @@ You: That changes everything.
 There's no required ending. Discovery might:
 
 - **Flow into a proposal**: "${DISCOVERY_END_HANDOFF}"
-- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Result in artifact updates**: "Updated the design with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
 
@@ -511,6 +513,8 @@ If the user mentions a change or you detect one is relevant:
 
    \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
 
+   The files below are the default spec-driven schema's. With another schema, capture each insight in whichever artifact from \`artifactPaths\` fits it, and name that artifact in your offer; never create an artifact the schema does not define.
+
     | Insight Type               | Where to Capture                    |
     |----------------------------|-------------------------------------|
     | New requirement discovered | \`specs/<capability-path>/spec.md\` |
@@ -520,7 +524,7 @@ If the user mentions a change or you detect one is relevant:
     | New work identified        | \`tasks.md\`                        |
     | Assumption invalidated     | Relevant artifact                   |
 
-   Example offers:
+   Example offers (default schema):
    - "That's a design decision. Capture it in design.md?"
    - "This is a new requirement. Add it to specs?"
    - "This changes scope. Update the proposal?"
@@ -545,7 +549,7 @@ If the user mentions a change or you detect one is relevant:
 There's no required ending. Discovery might:
 
 - **Flow into a proposal**: "${DISCOVERY_END_HANDOFF}"
-- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Result in artifact updates**: "Updated the design with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
 

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

@@ -64,7 +64,7 @@ ${CONTINUE_SCOPE_NOTE}
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
 
-   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`), plus any confirmed concrete path allowed under a partly populated glob artifact (step 4). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
 
 3. **Understand the request**
    - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
@@ -108,7 +108,7 @@ After each invocation, show:
 **Guardrails**
 - Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, ${APPLY_GUARDRAIL}.
 - Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
-- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
+- Edit only the concrete files in \`existingOutputPaths\`, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: if an artifact has empty \`existingOutputPaths\` and status \`ready\` or \`blocked\`, ${CONTINUE_FRONTIER}. Leave \`skipped\` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose \`existingOutputPaths\` is non-empty.
 - Confirm every edit with the user before writing.
 - If the request changes the change's *intent* rather than refining it, ${INTENT_CHANGE_GUARDRAIL}.`,
@@ -163,7 +163,7 @@ ${CONTINUE_SCOPE_NOTE}
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
 
-   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`), plus any confirmed concrete path allowed under a partly populated glob artifact (step 4). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
 
 3. **Understand the request**
    - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
@@ -207,7 +207,7 @@ After each invocation, show:
 **Guardrails**
 - Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, ${APPLY_GUARDRAIL}.
 - Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
-- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
+- Edit only the concrete files in \`existingOutputPaths\`, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: if an artifact has empty \`existingOutputPaths\` and status \`ready\` or \`blocked\`, ${CONTINUE_FRONTIER}. Leave \`skipped\` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose \`existingOutputPaths\` is non-empty.
 - Confirm every edit with the user before writing.
 - If the request changes the change's *intent* rather than refining it, ${INTENT_CHANGE_GUARDRAIL}.`

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

@@ -87,8 +87,11 @@ ${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:
-       - Search codebase for the removed 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. Never report a REMOVED requirement as "Requirement not found" or recommend implementing it.
+       - 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 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.
        - If the behavior is still present:
          - Add CRITICAL issue: "Removed requirement still implemented: <requirement name>"
          - Recommendation: "Remove the remaining implementation at <file>:<lines>, following the requirement's Migration note if it has one"
@@ -104,7 +107,7 @@ ${PROJECT_ROOT_GUARD}
 
 6. **Verify Correctness**
 
-   If the delta specs are readable and contain at least one REMOVED or RENAMED requirement but no ADDED or MODIFIED requirements (the change only removes or renames requirements), report **Requirement Implementation Mapping** and **Scenario Coverage** as **Not applicable**. The REMOVED and RENAMED checks under Spec Coverage are the evidence for such a change (each RENAMED entry is checked there against its baseline behavior), so do not mark these two checks as not verified. A delta spec with no parseable requirements at all is unusable evidence, not a removal-only change: mark these checks as not verified.
+   If the delta specs are readable and contain at least one REMOVED or RENAMED requirement but no ADDED or MODIFIED requirements (the change only removes or renames requirements), report **Requirement Implementation Mapping** and **Scenario Coverage** as **Not applicable**. The REMOVED and RENAMED checks under Spec Coverage are the evidence for such a change (each REMOVED and RENAMED entry with a usable baseline is checked there against its baseline behavior, and an entry already marked not verified there stays not verified), so do not mark these two checks as not verified. A delta spec with no parseable requirements at all is unusable evidence, not a removal-only change: mark these checks as not verified.
 
    **Requirement Implementation Mapping**:
    - For each ADDED or MODIFIED requirement from delta specs (REMOVED entries, and RENAMED entries without a MODIFIED block, were settled under Spec Coverage):
@@ -158,7 +161,7 @@ ${PROJECT_ROOT_GUARD}
    | Coherence    | Followed/Issues  |
    \`\`\`
 
-   In each Status cell, report the results of checks that ran and \`Not verified (<reason>)\` for every skipped check. If all checks in a dimension were skipped, start the cell with \`Not verified\`. Never score a skipped check as passing. Treat every not verified or partially verified check as skipped in the final assessment. Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately (for example, "1 removal confirmed, 1 rename verified"). For a change that only removes or renames requirements, the Correctness cell reads \`Not applicable (no ADDED or MODIFIED requirements)\`.
+   In each Status cell, report the results of checks that ran and \`Not verified (<reason>)\` for every skipped check. If all checks in a dimension were skipped, start the cell with \`Not verified\`. Never score a skipped check as passing. Treat every not verified or partially verified check as skipped in the final assessment. Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately (for example, "1 removal confirmed, 1 rename verified", or "1 removal not verified (baseline unavailable)"). For a change that only removes or renames requirements, the Correctness cell reads \`Not applicable (no ADDED or MODIFIED requirements)\`.
 
    **Issues by Priority**:
 
@@ -296,8 +299,11 @@ ${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:
-       - Search codebase for the removed 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. Never report a REMOVED requirement as "Requirement not found" or recommend implementing it.
+       - 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 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.
        - If the behavior is still present:
          - Add CRITICAL issue: "Removed requirement still implemented: <requirement name>"
          - Recommendation: "Remove the remaining implementation at <file>:<lines>, following the requirement's Migration note if it has one"
@@ -313,7 +319,7 @@ ${PROJECT_ROOT_GUARD}
 
 6. **Verify Correctness**
 
-   If the delta specs are readable and contain at least one REMOVED or RENAMED requirement but no ADDED or MODIFIED requirements (the change only removes or renames requirements), report **Requirement Implementation Mapping** and **Scenario Coverage** as **Not applicable**. The REMOVED and RENAMED checks under Spec Coverage are the evidence for such a change (each RENAMED entry is checked there against its baseline behavior), so do not mark these two checks as not verified. A delta spec with no parseable requirements at all is unusable evidence, not a removal-only change: mark these checks as not verified.
+   If the delta specs are readable and contain at least one REMOVED or RENAMED requirement but no ADDED or MODIFIED requirements (the change only removes or renames requirements), report **Requirement Implementation Mapping** and **Scenario Coverage** as **Not applicable**. The REMOVED and RENAMED checks under Spec Coverage are the evidence for such a change (each REMOVED and RENAMED entry with a usable baseline is checked there against its baseline behavior, and an entry already marked not verified there stays not verified), so do not mark these two checks as not verified. A delta spec with no parseable requirements at all is unusable evidence, not a removal-only change: mark these checks as not verified.
 
    **Requirement Implementation Mapping**:
    - For each ADDED or MODIFIED requirement from delta specs (REMOVED entries, and RENAMED entries without a MODIFIED block, were settled under Spec Coverage):
@@ -367,7 +373,7 @@ ${PROJECT_ROOT_GUARD}
    | Coherence    | Followed/Issues  |
    \`\`\`
 
-   In each Status cell, report the results of checks that ran and \`Not verified (<reason>)\` for every skipped check. If all checks in a dimension were skipped, start the cell with \`Not verified\`. Never score a skipped check as passing. Treat every not verified or partially verified check as skipped in the final assessment. Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately (for example, "1 removal confirmed, 1 rename verified"). For a change that only removes or renames requirements, the Correctness cell reads \`Not applicable (no ADDED or MODIFIED requirements)\`.
+   In each Status cell, report the results of checks that ran and \`Not verified (<reason>)\` for every skipped check. If all checks in a dimension were skipped, start the cell with \`Not verified\`. Never score a skipped check as passing. Treat every not verified or partially verified check as skipped in the final assessment. Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately (for example, "1 removal confirmed, 1 rename verified", or "1 removal not verified (baseline unavailable)"). For a change that only removes or renames requirements, the Correctness cell reads \`Not applicable (no ADDED or MODIFIED requirements)\`.
 
    **Issues by Priority**:
 

package/dist/core/validation/validator.js

@@ -5,7 +5,7 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
@@ -203,6 +203,16 @@ export class Validator {
                         message: `Requirement "${orphan.name}" is ${where}, which is not a delta section, so it is ignored. Move it under "## ADDED Requirements", "## MODIFIED Requirements", "## REMOVED Requirements", or "## RENAMED Requirements".`,
                     });
                 }
+                // Archive carries requirement blocks only, by design. Warn so text
+                // written elsewhere is moved rather than lost without notice.
+                for (const lost of plan.unappliedContent) {
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: lost.line,
+                        message: `${describeUnappliedContent(lost, true)} is not carried into the main spec by archive. Move it into a requirement, or into proposal.md or design.md.`,
+                    });
+                }
                 const sectionNames = [];
                 if (plan.sectionPresence.added)
                     sectionNames.push('## ADDED Requirements');

package/dist/utils/change-metadata.d.ts

@@ -2,10 +2,22 @@ import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-
 import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
 export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.openspec.yaml` alongside OpenSpec (a tracker id, an
+ * owner). OpenSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export declare const EXTENSION_KEY_PATTERN: RegExp;
+export declare function isExtensionMetadataKey(key: string): boolean;
 /**
  * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
  * stripped by ChangeMetadataSchema rather than rejected, so callers that want
  * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
  */
 export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
 /**
@@ -40,6 +52,11 @@ export declare function validateSchemaName(schemaName: string, projectRoot?: str
 /**
  * Writes change metadata to .openspec.yaml in the change directory.
  *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
  * @param changeDir - The path to the change directory
  * @param metadata - The metadata to write
  * @param projectRoot - Optional project root for project-local schema resolution

package/dist/utils/change-metadata.js

@@ -7,10 +7,24 @@ import { readProjectConfig } from '../core/project-config.js';
 import { sanitizeInline } from '../core/references.js';
 export const METADATA_FILENAME = '.openspec.yaml';
 export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.openspec.yaml` alongside OpenSpec (a tracker id, an
+ * owner). OpenSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export const EXTENSION_KEY_PATTERN = /^x-\S+$/;
+export function isExtensionMetadataKey(key) {
+    return EXTENSION_KEY_PATTERN.test(key);
+}
 /**
  * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
  * stripped by ChangeMetadataSchema rather than rejected, so callers that want
  * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
  */
 export function listUnknownChangeMetadataKeys(parsed) {
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -18,7 +32,7 @@ export function listUnknownChangeMetadataKeys(parsed) {
     }
     const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
     return Object.keys(parsed)
-        .filter((key) => !known.has(key))
+        .filter((key) => !known.has(key) && !isExtensionMetadataKey(key))
         .sort();
 }
 /**
@@ -32,7 +46,13 @@ export function formatUnknownChangeMetadataKeysMessage(keys) {
     const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
     const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
     let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
-        `Known keys: ${known}. Unknown keys are ignored and have no effect.`;
+        `Known keys: ${known}. Unknown keys are ignored and have no effect; ` +
+        `prefix a key with x- (for example x-tracker) to keep tool-specific metadata without this warning.`;
+    if (keys.some((key) => /^x-/i.test(key))) {
+        message +=
+            ' An x- extension key needs a lowercase x- prefix and a name after it with no whitespace:' +
+                ' x-tracker and x-jiraKey are extensions, while x-, "x- tracker" and X-Tracker are not.';
+    }
     if (keys.includes('skip_design')) {
         message +=
             ' skip_design is not a supported key; only skip_specs exists, and it only skips artifacts whose generates path lives under specs/.';
@@ -92,6 +112,11 @@ export function validateSchemaName(schemaName, projectRoot) {
 /**
  * Writes change metadata to .openspec.yaml in the change directory.
  *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
  * @param changeDir - The path to the change directory
  * @param metadata - The metadata to write
  * @param projectRoot - Optional project root for project-local schema resolution

package/dist/utils/file-system.d.ts

@@ -15,6 +15,13 @@ export declare class FileSystemUtils {
      * Missing suffixes are resolved from their nearest existing ancestor.
      */
     static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    /**
+     * Like assertPathWithin, but a targetPath that is itself a symlink may
+     * resolve outside allowedDirectory, so a project can keep a managed
+     * directory (for example openspec/changes) in another repository. Its parent
+     * must still be confined and the link must resolve to an existing path.
+     */
+    static assertPathWithinAllowingLinkedLeaf(allowedDirectory: string, targetPath: string): void;
     static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
     static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
     private static isPathWithin;

package/dist/utils/file-system.js

@@ -105,6 +105,31 @@ export class FileSystemUtils {
             throw new Error(`Path is outside the allowed directory: ${targetPath}`);
         }
     }
+    /**
+     * Like assertPathWithin, but a targetPath that is itself a symlink may
+     * resolve outside allowedDirectory, so a project can keep a managed
+     * directory (for example openspec/changes) in another repository. Its parent
+     * must still be confined and the link must resolve to an existing path.
+     */
+    static assertPathWithinAllowingLinkedLeaf(allowedDirectory, targetPath) {
+        const resolvedTarget = path.resolve(targetPath);
+        let isLink = false;
+        try {
+            isLink = nodeFs.lstatSync(resolvedTarget).isSymbolicLink();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        if (!isLink) {
+            this.assertPathWithin(allowedDirectory, resolvedTarget);
+            return;
+        }
+        this.assertPathWithin(allowedDirectory, path.dirname(resolvedTarget));
+        // Throws for a dangling link, which cannot be proven to be a directory.
+        nodeFs.realpathSync.native(resolvedTarget);
+    }
     static resolveProjectArtifactPath(projectPath, artifactPath) {
         if (path.isAbsolute(artifactPath)) {
             throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",