Version Packages (#2112)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.devcontainer/README.md

@@ -4,7 +4,7 @@ This directory contains the VS Code dev container configuration for OpenSpec dev
 
 ## What's Included
 
-- **Node.js 20 LTS** (>=20.19.0) - TypeScript/JavaScript runtime
+- **Node.js 22 LTS** - TypeScript/JavaScript runtime (OpenSpec itself supports Node 20.19.0 and newer)
 - **pnpm** - Fast, disk space efficient package manager
 - **Git + GitHub CLI** - Version control tools
 - **VS Code Extensions**:

.github/workflows/ci.yml

@@ -55,19 +55,34 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # Every OS runs the oldest supported Node (package.json engines).
+        # Linux also runs the current LTS lines users are likely to have.
         include:
           - os: ubuntu-latest
             shell: bash
             label: linux-bash
+            node: '20.19.0'
             vitest_workers: 4
           - os: macos-latest
             shell: bash
             label: macos-bash
+            node: '20.19.0'
             vitest_workers: 4
           - os: windows-latest
             shell: pwsh
             label: windows-pwsh
+            node: '20.19.0'
             vitest_workers: 2
+          - os: ubuntu-latest
+            shell: bash
+            label: linux-bash-node22
+            node: '22'
+            vitest_workers: 4
+          - os: ubuntu-latest
+            shell: bash
+            label: linux-bash-node24
+            node: '24'
+            vitest_workers: 4
 
     defaults:
       run:
@@ -86,7 +101,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20.19.0'
+          node-version: ${{ matrix.node }}
           cache: 'pnpm'
 
       - name: Print environment diagnostics
@@ -105,7 +120,7 @@ jobs:
         run: pnpm test
 
       - name: Upload test coverage
-        if: matrix.os == 'ubuntu-latest'
+        if: matrix.os == 'ubuntu-latest' && matrix.node == '20.19.0'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: coverage-report-${{ github.event_name }}

CHANGELOG.md

@@ -1,5 +1,63 @@
 # @fission-ai/openspec
 
+## 1.14.3
+
+### Patch Changes
+
+- [#2101](https://github.com/Fission-AI/OpenSpec/pull/2101) [`87a69a2`](https://github.com/Fission-AI/OpenSpec/commit/87a69a2bf8eb3315a8c042d001520eb7766ab580) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **A capability's `spec.md` may be a symlink to a file elsewhere in the project** — `list --specs`, `show`, `validate` and `archive` no longer refuse `openspec/specs/<capability>/spec.md` when it links to the file the project keeps somewhere else, such as beside the product documentation it belongs to. A link that resolves outside the project is still refused.
+
+- [#2103](https://github.com/Fission-AI/OpenSpec/pull/2103) [`e33245d`](https://github.com/Fission-AI/OpenSpec/commit/e33245d22ba6f994596a1747baf17130fe04515d) Thanks [@surlymochan](https://github.com/surlymochan)! - ### Bug Fixes
+  
+  - Installing OpenSpec no longer pulls in the unpatched `braces` package, so a consumer audit does not report GHSA-vfj7-8cjw-p6xm through this package. A `generates` brace pattern that nests deeply, or expands to more than 1024 paths, is now rejected with a clear message instead of crashing `openspec status` with a stack overflow or an out-of-memory error.
+
+- [#2104](https://github.com/Fission-AI/OpenSpec/pull/2104) [`276d015`](https://github.com/Fission-AI/OpenSpec/commit/276d015090965791d8be3d02daf6bfd71de884c3) Thanks [@CRYPTONIKAV](https://github.com/CRYPTONIKAV)! - Keep glob artifact paths inside the change directory in the propose, ff-change and continue-change workflows
+
+- [#2108](https://github.com/Fission-AI/OpenSpec/pull/2108) [`5251f2e`](https://github.com/Fission-AI/OpenSpec/commit/5251f2ef5e9e83eac68dd6950091928c4324b127) Thanks [@clay-good](https://github.com/clay-good)! - Stop `openspec validate --all` hanging on a zero-width TTY. Some hosts hand the
+  process a terminal that reports `columns === 0` — a pty inherited from a
+  pre-commit runner such as lefthook, or `script -qec`. ora computes how many
+  lines to erase as `ceil(width / columns)`, so zero columns makes that count
+  `Infinity` and the clear loop never ends: the command burned a core and wrote
+  hundreds of megabytes of cursor escapes without finishing. The spinner is now
+  skipped when nothing can be drawn, and validate falls back to its plain output.
+  `OPEN_SPEC_INTERACTIVE=0` and `CI` now disable the spinner too, the same way
+  `--no-interactive` already did.
+
+- [#2110](https://github.com/Fission-AI/OpenSpec/pull/2110) [`c9a8ade`](https://github.com/Fission-AI/OpenSpec/commit/c9a8adef5021e9793ed9e104f65834fce0fb16cb) Thanks [@clay-good](https://github.com/clay-good)! - Preview the built docs site with a first-party static server instead of `serve`.
+  `pnpm start` in `website/` now runs `scripts/preview.mjs`, a dependency-free
+  server that resolves routes in a Next static export (it does not apply
+  `out/_redirects`). This
+  drops the `serve` dev dependency whose transitive tree kept publishing
+  advisories (brace-expansion x3, fast-uri, compression) that had to be pinned by
+  hand even though none of that code ever reached the published site.
+
+## 1.14.2
+
+### Patch Changes
+
+- [#2052](https://github.com/Fission-AI/OpenSpec/pull/2052) [`90c95c2`](https://github.com/Fission-AI/OpenSpec/commit/90c95c2a235e0d4088006a879c19cd1febff2a9e) Thanks [@drakeo338](https://github.com/drakeo338)! - ### Bug Fixes
+  
+  - **Archive accepts `openspec/`, `openspec/changes` or `openspec/specs` as a symlink** — `openspec archive` no longer refuses a project-owned symlink that points to another directory, such as a shared docs repository. An `archive/` directory that resolves outside the changes directory is still refused.
+
+- [#2061](https://github.com/Fission-AI/OpenSpec/pull/2061) [`7acf282`](https://github.com/Fission-AI/OpenSpec/commit/7acf282050c0b2a27bd18f30c48fbcc0986bfc45) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **Guard against deeply nested brace patterns** — An artifact `generates` or `apply.tracks` pattern that nests braces or parentheses more than 16 levels deep is now rejected with a clear error before glob matching, so a schema cannot overflow the stack through the unpatched `braces` advisory GHSA-vfj7-8cjw-p6xm.
+
+- [#2086](https://github.com/Fission-AI/OpenSpec/pull/2086) [`9cb5ba8`](https://github.com/Fission-AI/OpenSpec/commit/9cb5ba8cec4bc47227dcac4974a74b4adf1819f6) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **Explore no longer offers to write default-schema files under a custom schema** — The explore workflow's "where to capture" table and example offers now say they describe the default spec-driven schema. With another schema, the agent captures each insight in an artifact that schema defines, names it in the offer, and never creates a file such as `design.md` that the schema does not have.
+
+- [#2064](https://github.com/Fission-AI/OpenSpec/pull/2064) [`76d49a1`](https://github.com/Fission-AI/OpenSpec/commit/76d49a1d8176ad2bdb3696e29c4ffe222402f2da) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Shell Tab completion is faster. `openspec __complete`, which the completion scripts run on every Tab press, now loads 48 modules instead of 344 when completing changes or specs, and no longer records usage, so a press never waits on the telemetry request and can't use up the first-run telemetry notice where nobody sees it. Completion output is unchanged.
+
+- [#2083](https://github.com/Fission-AI/OpenSpec/pull/2083) [`3fea2a9`](https://github.com/Fission-AI/OpenSpec/commit/3fea2a96b2e04e01097f4617573734c47a57589b) Thanks [@clay-good](https://github.com/clay-good)! - The update workflow now states the glob new-file exception at both places that state the scope rule (step 2 and the guardrails), not only where the rule is restated. It said to edit only the concrete files in `existingOutputPaths`, while the file step 4 creates to fill a gap under a partly written glob artifact is by definition not in that list, so an agent applying the blanket rule refused the operation the flow exists to perform.
+
+- [#2083](https://github.com/Fission-AI/OpenSpec/pull/2083) [`3fea2a9`](https://github.com/Fission-AI/OpenSpec/commit/3fea2a96b2e04e01097f4617573734c47a57589b) Thanks [@clay-good](https://github.com/clay-good)! - The verify workflow now reads a REMOVED requirement's baseline from the main spec before searching the codebase for it. A REMOVED delta block carries only the requirement name plus its Reason and Migration notes, so the search started from the heading alone - and because finding nothing is the passing result for a removal, an implementation written in different vocabulary read as a clean removal. When the baseline cannot be recovered from the main spec or that file's history - including a baseline that only restates its own title - Spec Coverage is now reported as not verified for that entry and the search is skipped, instead of passing.
+
+- [#2054](https://github.com/Fission-AI/OpenSpec/pull/2054) [`1bce87f`](https://github.com/Fission-AI/OpenSpec/commit/1bce87f858c2591b2cb58108597ae6f0a9bb5d7c) Thanks [@runsonmypc](https://github.com/runsonmypc)! - `openspec validate` and `openspec archive` now warn when a delta spec holds text archive does not carry into the main spec: a `## ` section other than Purpose and the four delta sections, text above the first `## ` header, or prose before the first requirement in ADDED or MODIFIED. That text was dropped without notice before. Like other validation warnings, these fail `openspec validate --strict`. What archive carries is unchanged.
+
+- [#2063](https://github.com/Fission-AI/OpenSpec/pull/2063) [`e0a2f00`](https://github.com/Fission-AI/OpenSpec/commit/e0a2f00f95731af7cf22a30c2c4a8b7ff910b509) Thanks [@gkinter](https://github.com/gkinter)! - Keys in a change's `.openspec.yaml` that start with a lowercase `x-` (for example `x-goal: G-12` or `x-jiraKey`) are now treated as your own extension metadata: OpenSpec no longer reports them as unknown, so `openspec validate --strict` passes on a change that carries them. Any other unrecognized key, including `X-Tracker` or a bare `x-`, is still reported.
+
 ## 1.14.1
 
 ### Patch Changes

CONTRIBUTING.md

@@ -41,7 +41,7 @@ Run `pnpm changeset` if your change affects users, and commit the file it genera
 
 Editors, agents and OpenSpec Desktop run the CLI many times, and each call pays for every module it loads before the command runs. Before this rule, `openspec --version` loaded 485 modules: about 0.5 s per call on a Windows machine. So a command loads only the command definitions and its own code:
 
-- **Definitions** (name, options, help text) go in `src/cli/index.ts` or `src/cli/commands/<name>.ts`. Import nothing heavy there: no zod, yaml, fast-glob, ora, and no other command's code.
+- **Definitions** (name, options, help text) go in `src/cli/index.ts` or `src/cli/commands/<name>.ts`. Import nothing heavy there: no zod, yaml, tinyglobby, ora, and no other command's code.
 - **The command's code** goes in `src/commands/<name>.ts` or `src/core/`, loaded inside the action with `await import()`.
 
 `test/cli-e2e/startup-modules.test.ts` checks which modules each command loads, and fails if a definition starts pulling in an implementation. When you add a command, add it to that test's list.

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
 

docs-lab/reference/configuration/change-metadata.md

@@ -42,6 +42,24 @@ Declares the change intentionally makes no spec deltas: a pure refactor, tooling
 
 Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call.
 
+### Extension keys
+
+A top-level key that starts with a lowercase `x-` is yours, for data another tool or your team keeps beside the change, such as a tracker id or an owner:
+
+```yaml
+schema: spec-driven
+x-tracker: SB-5497
+x-jiraKey: ABC-1
+x-owner:
+  team: payments
+```
+
+- **Name**: the lowercase `x-` prefix followed by at least one character, with no whitespace anywhere. Any case or spelling works after the prefix, so `x-jiraKey` and `x-trackerID` qualify. `X-Tracker`, a bare `x-`, and `x- tracker` do not, and are reported as unknown keys.
+- **Value**: any YAML value. OpenSpec does not read or validate it, and it changes no behavior.
+- **Scope**: top-level only. An `x-` key inside `initiative` is still rejected, like any other key there.
+- **Validation**: extension keys are never reported as unknown, so `openspec validate --strict` passes on a change that carries them.
+- **Archive**: the file moves with the change unchanged, extension keys included.
+
 ## Example
 
 A filled-in .openspec.yaml:
@@ -61,5 +79,5 @@ The file is validated whenever a command writes or reads it. A write that fails
 
 Unlike [config.yaml](config-yaml.md), bad values are never dropped with a warning. A metadata error stops the command.
 
-- **Unknown top-level keys**: OpenSpec ignores them. `status`, `instructions`, `validate`, and `archive` report that they have no effect. JSON output carries the warning in its structured result.
-- **Strict validation**: `openspec validate --strict` treats an unknown-key warning as a failure.
+- **Unknown top-level keys**: OpenSpec ignores them. `status`, `instructions`, `validate`, and `archive` report that they have no effect. JSON output carries the warning in its structured result. [Extension keys](#extension-keys) are not unknown and are never reported.
+- **Strict validation**: `openspec validate --strict` treats an unknown-key warning as a failure. A change whose only extra keys are extension keys passes.

docs-lab/reference/schemas/schema-yaml.md

@@ -84,7 +84,7 @@ OpenSpec recognizes these glob forms in `generates`:
 
 **Literal filenames**: a leading `!` alone does not make a glob. Use `generates: '!review.md'` to name that file. Plain parentheses such as `(proposal|design).md` and single-element braces such as `review-{api}.md` also remain literal.
 
-OpenSpec rejects absolute paths and paths containing a `..` segment.
+OpenSpec rejects absolute paths, paths containing a `..` segment, and globs that nest braces or parentheses more than 16 levels deep, such as `{a,{b,{c,...}}}`. Real patterns need one or two levels. It also rejects a glob whose braces expand to more than 1,024 patterns, such as `{a,b}` repeated eleven times or a range like `file-{1..5000}.md`. The error says `Artifact output pattern expands to more than 1024 patterns`. Real patterns expand to a handful.
 
 #### Completion
 
@@ -140,7 +140,7 @@ The path starts from the change folder. For a change named `add-auth`, `tracks:
 openspec/changes/add-auth/tasks.md
 ```
 
-A glob such as `tracks: "**/tasks.md"` reads every matching file, such as `backend/tasks.md` and `frontend/tasks.md`. OpenSpec combines their tasks and progress. Use the same value for an artifact's `generates` field so status and list track the same files.
+A glob such as `tracks: "**/tasks.md"` reads every matching file, such as `backend/tasks.md` and `frontend/tasks.md`. OpenSpec combines their tasks and progress. Use the same value for an artifact's `generates` field so status and list track the same files. The brace limits from `generates` (16 levels deep, 1,024 expanded patterns) apply here too.
 
 Apply stays blocked if no file matches or the matched files contain no checkbox with task text. OpenSpec counts these checkbox forms:
 

docs/README.md

@@ -1,5 +1,8 @@
 # OpenSpec Documentation
 
+> [!WARNING]
+> These pages are legacy and some are out of date. The current docs are at **[openspec.dev/docs](https://openspec.dev/docs)** (source: [`docs-lab/`](../docs-lab/)).
+
 Welcome. This is the home for everything OpenSpec.
 
 OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.

docs/cli.md

@@ -678,6 +678,23 @@ Then archive the change normally:
 openspec archive retire-legacy --yes
 ```
 
+**Keep your own metadata:** a top-level key starting with a lowercase `x-` is
+yours. OpenSpec never reads, writes or reports it, so `openspec validate
+--strict` stays green on a change that carries tool-specific data:
+
+```yaml
+# openspec/changes/add-dark-mode/.openspec.yaml
+schema: spec-driven
+x-tracker: SB-5497
+x-jiraKey: ABC-1
+```
+
+The name after the prefix is yours to choose, in any case or spelling, as long
+as it is not empty and has no whitespace in it. Two limits: the prefix itself is
+lowercase, so `X-Tracker` is still reported, and extensions are top-level only —
+a key inside `initiative:` is rejected whatever it is called. Any other
+unrecognized top-level key is still reported as having no effect.
+
 When the change removes the capability's last requirement, OpenSpec deletes its
 live `spec.md`. Other capability deltas in the same change still update their
 main specs. Without the marker, archive stops before changing any files and

docs/community.md

@@ -7,9 +7,16 @@ Listed projects are maintained independently. Inclusion does not imply official
 ## Projects and resources
 
 - **[OpenSpec Workbench](https://github.com/VeryComplexAndLongName/OpenSpec-UI)**: Running and supervising agents on OpenSpec changes.
-- **[MySpec](https://myspec.dev)**: Cloud beta (account required) that conducts guided spec interviews and exports four-file bundles or OpenSpec-compatible changes. The service sends submitted content to third-party AI providers and is not designed for sensitive data.
 - **[openspec-guard](https://github.com/guillaume-flambard/spec-guard)**: CLI and GitHub Action that reports which OpenSpec scenarios are covered by a Vitest or Jest test, without running the tests.
 
+## Hosted services
+
+Hosted products that add an OpenSpec capability the CLI does not provide. Each entry states its account, payment, and data-handling terms.
+
+- **[MySpec](https://myspec.dev)**: Cloud beta (account required; free tier, no credit card) that conducts guided spec interviews and exports four-file bundles or OpenSpec-compatible changes. Its MCP server (`@myspec/mcp-server`) and [Claude Code plugins](https://github.com/myspecs/claude-plugins) let coding agents read those specs, write OpenSpec changes, and implement them task by task. The service sends submitted content to third-party AI providers and is not designed for sensitive data.
+- **[Entalpa](https://entalpa.com/en/openspec)**: Imports a public GitHub repository's `openspec/specs/` (up to 300 requirements) into a browsable project, adds stakeholders, stories and open questions labeled as inferred, and exports the result as an `openspec/specs/` tree; it never writes to the repository. Importing and reading need no account; saving or editing needs one, and AI features use paid credits. Imported content is sent to third-party AI providers.
+- **[OpenSpec Review](https://skillgild.dev/skills/openspec-review) and [OpenSpec Compact](https://skillgild.dev/skills/openspec-compact)**: Hosted skills from SkillGild for Claude Code, Codex, Cursor, Gemini CLI or any MCP client. Review publishes a change as a link where anyone holding it can approve, request changes or comment per requirement without an account, shows the main spec as `openspec archive` would write it, and flags requirements that other open changes also touch. Compact finds lexically similar requirements and repeated scenarios across main specs and writes the cleanup as an OpenSpec change. Requires the SkillGild CLI and a free account (25 runs a month per skill). Both send spec content to SkillGild's servers, which run closed-source code and make no AI model call; Review also sends the proposal, design and tasks, and keeps the change for 30 days.
+
 ## Add your project
 
 Open a pull request adding one line to this file with your project's name, a direct link, and a short description of how it relates to OpenSpec.
@@ -17,5 +24,6 @@ Open a pull request adding one line to this file with your project's name, a dir
 - Keep entries focused on something built with OpenSpec or supporting its use, rather than general product advertising.
 - Describe what people can use. Avoid promotional claims, referral links, and tracking links.
 - Disclose paid features or required accounts in the entry, if any.
+- Hosted or paid services are listed under Hosted services only when they add an OpenSpec capability the CLI does not already provide and have a free way to try them. A service that repackages OpenSpec's own skills or commands is not listed.
 
 Corrections and updates to existing entries are welcome too.

docs/concepts.md

@@ -190,7 +190,7 @@ openspec/changes/add-dark-mode/
 ├── proposal.md           # Why and what
 ├── design.md             # How (technical approach)
 ├── tasks.md              # Implementation checklist
-├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs, retire_capabilities
+├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs, retire_capabilities, plus your own x-* keys
 └── specs/                # Delta specs
     └── ui/
         └── spec.md       # What's changing in ui/spec.md

docs/customization.md

@@ -423,6 +423,7 @@ Community schemas are not vendored into OpenSpec core — they live in their own
 | `nanopm` | @nmrtn | [nmrtn/nanopm](https://github.com/nmrtn/nanopm/tree/main/openspec-schema) | PM-first workflow. Runs [nanopm](https://github.com/nmrtn/nanopm)'s planning pipeline (audit → strategy → roadmap → PRD) upstream of implementation. Bridges product planning to OpenSpec's spec-driven engineering workflow. Artifacts read from `.nanopm/` if present — proposal sources the audit, design sources the strategy, and tasks source the PRD breakdown. |
 | `e2e-runbooks` | @Lukk17 | [Lukk17/openspec-schemas](https://github.com/Lukk17/openspec-schemas/tree/master/openspec/schemas/e2e-runbooks) | Capability-level end-to-end test runbooks. Each capability gets an immutable spec, an immutable tasks-template, and one timestamped run record per execution. Assertions are observable behaviour only (HTTP status, response body, persisted state — never log substrings); each run records start/end UTC, duration, and best-estimate LLM token consumption. |
 | `anvil` | @jikkujoyce | [jikkujoyce/openspec-schemas](https://github.com/jikkujoyce/openspec-schemas/tree/main/schemas/anvil) | Spec-driven workflow with TDD discipline and an adversarial review step. Flow: `proposal` → `specs` → `design` → `review` → `test-plan` → `tasks` → `apply` → `verify`. `review` is written by a fresh-context, read-only reviewer (a second model when one is available) and emits a `VERDICT:` line telling the agent to gate `test-plan`, `tasks`, and `apply`; OpenSpec only checks that artifacts exist, so enforce the gate with your own CI or hook. `test-plan` maps every spec scenario to a named test and doubles as a red/green ledger that `verify` audits. |
+| `ml-research` | @tsenst | [idealo/openspec-schemas](https://github.com/idealo/openspec-schemas/tree/main/openspec/schemas/ml-research) | Machine-learning experiment workflow. Flow: `proposal` → `design` → `evaluation` → `tasks` → `apply` → `specs`. `evaluation` fixes metrics, success criteria, and the falsification condition before the run; `apply` writes `results.md`; `specs` records only evidence-backed findings (refuted hypotheses included) as `Finding:` requirements with linked `Evidence:` blocks. |
 
 > Want to contribute a community schema? Open an issue with a link to your repository, or submit a PR adding a row to this table.
 

flake.nix

@@ -53,7 +53,7 @@
             inherit (finalAttrs) pname version src;
             pnpm = final.pnpm_10;
             fetcherVersion = 3;
-            hash = "sha256-NIMHf7t+FnBgsswDtB1k4E/zX1ks1r3708ggE2ps9E8=";
+            hash = "sha256-fKm4sBdTDeQfIiE0k301jtRbiuJrBE7YIEBu8RZxuXI=";
           };
 
           nativeBuildInputs = with final; [

openspec/changes/fix-validate-view-resolution-parity/design.md

@@ -49,7 +49,7 @@ The fix lands in the shared helper `getTaskProgressForChange`, correcting all fo
 
 Two corrections to an earlier draft, both load-bearing:
 
-- **`apply.tracks` is a filename that *selects* the artifact; it is not the glob.** `apply.tracks` is typed `string | null` and is consumed elsewhere as a literal path (`path.join(changeDir, tracks)` + `existsSync`), so `apply.tracks: "**/tasks.md"` cannot match nested files. The glob `status` actually uses is the tracked artifact's **`generates`**, resolved by `resolveArtifactOutputs(changeDir, artifact.generates)`. So the fix identifies the tracked-tasks artifact (the artifact whose `generates` equals `apply.tracks`, falling back to artifact id `tasks` when no `apply` block is present), then counts checkboxes across `resolveArtifactOutputs(changeDir, thatArtifact.generates)`. `resolveArtifactOutputs` roots `fast-glob` at the change directory (so a sibling `changes/archive/` or another change's `tasks.md` cannot match) and de-dups via a `Set` (so no double counting).
+- **`apply.tracks` is a filename that *selects* the artifact; it is not the glob.** `apply.tracks` is typed `string | null` and is consumed elsewhere as a literal path (`path.join(changeDir, tracks)` + `existsSync`), so `apply.tracks: "**/tasks.md"` cannot match nested files. The glob `status` actually uses is the tracked artifact's **`generates`**, resolved by `resolveArtifactOutputs(changeDir, artifact.generates)`. So the fix identifies the tracked-tasks artifact (the artifact whose `generates` equals `apply.tracks`, falling back to artifact id `tasks` when no `apply` block is present), then counts checkboxes across `resolveArtifactOutputs(changeDir, thatArtifact.generates)`. `resolveArtifactOutputs` roots its glob at the change directory (so a sibling `changes/archive/` or another change's `tasks.md` cannot match) and de-dups via a `Set` (so no double counting).
 - **`status` checks file *existence*, not checkbox completion.** Empirically `status` calls a 3/5 change `4/4 complete, isComplete:true`. So the parity established here is **resolution-mechanism parity** (`view`/`archive` resolve the same set of files `status` resolves), not count parity — `view`/`archive` additionally count checkboxes. Any "view/archive task counts equal status" claim is false and is removed from the spec.
 
 The signature gains `projectRoot` (needed to resolve project-local schemas via `resolveSchema`); all four call sites plus the two `change.ts` sites can derive it. `resolveSchema` **throws** on an unresolvable/misnamed schema, whereas the current helper never throws — so the helper MUST catch and fall back to single-file `tasks.md`, or `view`/`list`/`archive` would crash on a project whose config names a deleted schema. This fallback is specified and tested.

openspec/specs/artifact-graph/spec.md

@@ -119,6 +119,14 @@ The system SHALL preserve literal filenames with a bare leading `!`, plain paren
 - **AND** "content/linked" is a symbolic link to a directory outside the change directory
 - **THEN** output resolution rejects traversal through that link even when no matching files exist
 
+### Requirement: Glob Nesting Limit
+The system SHALL reject a glob `generates` or `apply.tracks` value that nests braces or parentheses more than 16 levels deep, counting them as the brace parser does, with an error naming the limit, before any glob matching runs.
+
+#### Scenario: Brace nesting beyond the limit
+- **WHEN** an artifact generates a pattern whose braces nest 17 levels deep
+- **THEN** resolving its outputs fails with an error naming the 16-level limit
+- **AND** no glob matching runs for that pattern
+
 ### Requirement: Ready Artifact Query
 The system SHALL identify which artifacts are ready to be created based on dependency completion.
 

openspec/specs/cli-archive/spec.md

@@ -224,12 +224,12 @@ The spec update confirmation SHALL provide clear visibility into changes before
   EXISTING specs to be updated:
     - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
   
-  Update 2 specs and archive 'add-archive-command'? [y/N]:
+  Proceed with spec updates? (Y/n)
   ```
 #### Scenario: Handling confirmation response
 
 - **WHEN** waiting for user confirmation
-- **THEN** default to "No" for safety (require explicit "y" or "yes")
+- **THEN** default to "Yes", so pressing Enter proceeds (declining requires an explicit "n" or "no")
 - **AND** skip confirmation when `--yes` or `-y` flag is provided
 
 #### Scenario: User declines confirmation

openspec/specs/opsx-verify-skill/spec.md

@@ -103,7 +103,11 @@ The agent SHALL verify that implementation matches the specifications.
 
 #### Scenario: Removed requirement
 - **WHEN** a requirement sits under `## REMOVED Requirements` in a delta spec
-- **THEN** the agent treats the absence of its implementation as the expected result
+- **THEN** the agent reads the baseline requirement (its body and scenarios in the main spec, matched by normalized name) before searching, rather than searching from the requirement name alone
+- **AND** recovers the baseline from the main spec file's history when that file no longer holds the requirement, for example because an earlier sync already applied the removal
+- **AND** treats a baseline that adds nothing to its own title as unusable, the same as a missing one
+- **AND** marks spec coverage as not verified for the entry, without searching, when no usable baseline can be found or read
+- **AND** treats the absence of an implementation of that baseline behavior as the expected result
 - **AND** does not report it as missing or suggest implementing it
 - **AND** reports it as CRITICAL only if the removed behavior is still present in the codebase
 - **AND** skips scenario coverage for it

openspec/specs/schema-resolution/spec.md

@@ -92,14 +92,14 @@ The `openspec schemas` command SHALL display the source of each schema.
 
 ### Requirement: Use config schema as default for new changes
 
-The system SHALL use the schema field from `openspec/config.yaml` as the default when creating new changes without explicit `--schema` flag and no planning-home default applies.
+The system SHALL use the schema field from `openspec/config.yaml` as the default when creating new changes without an explicit `--schema` flag, and SHALL fall back to the planning-home default when the config supplies no schema.
 
 #### Scenario: Create change without --schema flag and config exists
-- **WHEN** user runs `openspec new change foo`, no planning-home default applies, and config contains `schema: "tdd"`
-- **THEN** system creates change with schema "tdd"
+- **WHEN** user runs `openspec new change foo` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "tdd", even when a planning-home default applies
 
 #### Scenario: Create change without --schema flag and no config
-- **WHEN** user runs `openspec new change foo`, no planning-home default applies, and no config file exists
+- **WHEN** user runs `openspec new change foo`, no config file exists, and no planning-home default applies
 - **THEN** system creates change with default schema "spec-driven"
 
 #### Scenario: Create change with explicit --schema flag
@@ -108,7 +108,7 @@ The system SHALL use the schema field from `openspec/config.yaml` as the default
 
 ### Requirement: Resolve schema with updated precedence order
 
-The system SHALL resolve the schema for a change using the following precedence order: CLI flag, change metadata, planning-home default, project config, hardcoded default.
+The system SHALL resolve the schema for a change using the following precedence order: CLI flag, change metadata, project config, planning-home default, hardcoded default.
 
 #### Scenario: CLI flag is provided
 - **WHEN** user runs command with `--schema custom`
@@ -119,11 +119,11 @@ The system SHALL resolve the schema for a change using the following precedence
 - **THEN** system uses "bound" from change metadata
 
 #### Scenario: Only project config specifies schema
-- **WHEN** no CLI flag, change metadata, or planning-home default exists, but config has `schema: tdd`
-- **THEN** system uses "tdd" from project config
+- **WHEN** no CLI flag or change metadata exists, but config has `schema: tdd`
+- **THEN** system uses "tdd" from project config, even when a planning-home default applies
 
 #### Scenario: No schema specified anywhere
-- **WHEN** no CLI flag, change metadata, planning-home default, or project config
+- **WHEN** no CLI flag, change metadata, project config, or planning-home default
 - **THEN** system uses hardcoded default "spec-driven"
 
 ### Requirement: Support project-local schema names in config

openspec/specs/telemetry/spec.md

@@ -62,7 +62,7 @@ The system SHALL display a one-line telemetry disclosure notice on the first com
 #### Scenario: First command execution
 - **WHEN** a user runs their first openspec command
 - **AND** telemetry is enabled
-- **THEN** the system displays: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0"
+- **THEN** the system displays: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false"
 
 #### Scenario: Subsequent command execution
 - **WHEN** a user has already seen the notice (noticeSeen: true in config)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.14.1",
+  "version": "1.14.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -63,6 +63,7 @@
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
+    "@types/picomatch": "^4.0.3",
     "@vitest/ui": "^4.1.11",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
@@ -73,12 +74,14 @@
   "dependencies": {
     "@inquirer/core": "^12.0.0",
     "@inquirer/prompts": "^8.5.2",
+    "brace-expansion": "^5.0.12",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "cross-spawn": "7.0.6",
     "diff": "^9.0.0",
-    "fast-glob": "^3.3.3",
     "ora": "^9.4.1",
+    "picomatch": "^4.0.4",
+    "tinyglobby": "^0.2.17",
     "yaml": "^2.8.3",
     "zod": "^4.4.3"
   }

pnpm-workspace.yaml

@@ -10,7 +10,10 @@ allowBuilds:
 # plain-name entries in package.json when it bumps the same package, so a mirrored
 # copy there both drifts and silently takes precedence over these advisory pins.
 overrides:
-  brace-expansion@<=5.0.8: '>=5.0.9 <6'
+  # GHSA-6j4f-fj2g-mc7p, GHSA-qhr7-859c-m2p7, GHSA-q2hr-2g5m-vwhr — brace-expansion
+  # below 5.0.12. Direct dependency, and minimatch. Remove once every copy is
+  # >=5.0.12 (check: pnpm why brace-expansion).
+  brace-expansion@<5.0.12: '>=5.0.12 <6'
   postcss@<8.5.23: '>=8.5.23 <9'
   # GHSA-5p4m-2wfm-xmqj — js-yaml quadratic-CPU !!omap DoS. Dev-only (pulled by
   # @changesets: read-yaml-file for 3.x, @changesets/parse for 4.x); never in the
@@ -26,3 +29,8 @@ overrides:
   # Dev-only (transitive via @vitest/ui); never in the published CLI. Remove once
   # transitive fflate is >=0.8.3 (check: pnpm why fflate).
   fflate@<0.8.3: '>=0.8.3 <0.9'
+  # GHSA-pqg4-j6r4-53mv — shell-quote `quote()` command injection via a line
+  # terminator after a `{ comment }` token. Dev-only (transitive via
+  # @changesets/cli > launch-editor); never in the published CLI. Remove once
+  # transitive shell-quote is >=1.11.0 (check: pnpm why shell-quote).
+  shell-quote@>=1.8.4 <1.11.0: '>=1.11.0 <2'

skills/openspec-continue-change/SKILL.md

@@ -60,8 +60,8 @@ In both branches, never create the root as a side effect: do not run `openspec i
 
    **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
 
    ---
 
@@ -89,10 +89,13 @@ In both branches, never create the root as a side effect: do not run `openspec i
      - `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
 
@@ -120,7 +123,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

skills/openspec-explore/SKILL.md

@@ -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: `/openspec-propose` writes the remaining planning artifacts, and `/openspec-apply-change` implements the change once tasks exist. Capturing artifacts never starts implementing them.
@@ -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**: "Ready to start? Run `/openspec-propose` and this becomes a change."
-- **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"
 

skills/openspec-ff-change/SKILL.md

@@ -76,8 +76,9 @@ In both branches, never create the root as a side effect: do not run `openspec i
         - 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>"
 
@@ -111,7 +112,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

skills/openspec-propose/SKILL.md

@@ -121,8 +121,9 @@ In both branches, never create the root as a side effect: do not run `openspec i
         - 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>"
 
@@ -156,7 +157,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

skills/openspec-update-change/SKILL.md

@@ -58,7 +58,7 @@ This workflow revises artifacts that already exist; `/openspec-continue-change`
 
    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.
@@ -102,7 +102,7 @@ After each invocation, show:
 **Guardrails**
 - Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/openspec-apply-change`.
 - 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`, that is `/openspec-continue-change`'s job. 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, recommend starting fresh with `/openspec-new-change` (the "Update vs. Start Fresh" heuristic).

skills/openspec-verify-change/SKILL.md

@@ -101,8 +101,11 @@ In both branches, never create the root as a side effect: do not run `openspec i
        - 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"
@@ -118,7 +121,7 @@ In both branches, never create the root as a side effect: do not run `openspec i
 
 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):
@@ -172,7 +175,7 @@ In both branches, never create the root as a side effect: do not run `openspec i
    | 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**:
 

src/cli/index.ts

@@ -123,6 +123,14 @@ export function isCompletionRun(commandPath: string): boolean {
   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: string): boolean {
+  return commandPath === '__complete';
+}
+
 /**
  * True when the first-run completions tip must be deferred rather than shown.
  *
@@ -196,6 +204,13 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     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.
@@ -210,6 +225,12 @@ 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

src/commands/change.ts

@@ -15,6 +15,7 @@ import {
 } from '../utils/nested-change.js';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { assertDiscoveredSpecFile } from '../utils/spec-path-containment.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
 import {
   foldRequirementName,
@@ -217,7 +218,7 @@ export class ChangeCommand {
       const mainSpecPath = path.join(mainSpecsDir, ...capability.split('/'), 'spec.md');
       let mainContent: string | null = null;
       try {
-        FileSystemUtils.assertPathWithin(mainSpecsDir, mainSpecPath);
+        assertDiscoveredSpecFile(mainSpecsDir, mainSpecPath);
         mainContent = await fs.readFile(mainSpecPath, 'utf-8');
       } catch (error) {
         if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;

src/commands/completion.ts

@@ -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, SupportedShell } from '../utils/shell-detection.js';
@@ -125,6 +124,9 @@ export class CompletionCommand {
     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 {
@@ -234,6 +236,7 @@ export class CompletionCommand {
       }
     }
 
+    const { default: ora } = await import('ora');
     const spinner = ora(`Uninstalling ${shell} completion script...`).start();
 
     try {

src/commands/spec.ts

@@ -7,7 +7,7 @@ import type { RootOutput } from '../core/root-selection.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
-import { FileSystemUtils } from '../utils/file-system.js';
+import { assertDiscoveredSpecFile } from '../utils/spec-path-containment.js';
 
 const SPECS_DIR = 'openspec/specs';
 
@@ -21,14 +21,7 @@ function assertSpecPath(specsDir: string, specPath: string): void {
     throw new Error(`Path is outside the allowed directory: ${specPath}`);
   }
 
-  try {
-    // Preserve confined spec.md links, including links to a sibling capability.
-    FileSystemUtils.assertPathWithin(specsDir, specPath);
-  } catch {
-    // A capability directory may intentionally be a monorepo symlink. Treat it
-    // as the trust root while still rejecting a link outside that capability.
-    FileSystemUtils.assertPathWithin(path.dirname(specPath), specPath);
-  }
+  assertDiscoveredSpecFile(specsDir, specPath);
 }
 
 export interface ShowOptions {

src/commands/validate.ts

@@ -15,7 +15,7 @@ import {
   type ResolvedOpenSpecRoot,
   isStoreSelectedRoot,
 } from '../core/root-selection.js';
-import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
+import { canRenderSpinner, isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { getAvailableChanges } from './workflow/shared.js';
 import { nearestMatches } from '../utils/match.js';
@@ -441,7 +441,7 @@ export class ValidateCommand {
   }
 
   private async runBulkValidation(root: ResolvedOpenSpecRoot, scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string; noInteractive?: boolean; findingsScope?: BulkScope }): Promise<void> {
-    const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
+    const spinner = !opts.json && isInteractive(opts) && canRenderSpinner() ? ora('Validating...').start() : undefined;
     const [changeIds, specIds] = await Promise.all([
       scope.changes ? this.listChangeIds(root) : Promise.resolve<string[]>([]),
       scope.specs ? getSpecIds(root.path) : Promise.resolve<string[]>([]),
@@ -615,7 +615,7 @@ export class ValidateCommand {
     // List first (may throw on a real archive-read failure), then start the
     // spinner so a thrown error never leaves a spinner spinning.
     const ids = await this.listArchivedChangeIds(root);
-    const spinner = !opts.json && !opts.noInteractive ? ora('Validating archived changes...').start() : undefined;
+    const spinner = !opts.json && isInteractive(opts) && canRenderSpinner() ? ora('Validating archived changes...').start() : undefined;
 
     // The archive is append-only and can hold thousands of changes; a single
     // run resolves them all under one constant projectRoot (root.path), so

src/core/archive.ts

@@ -1358,13 +1358,22 @@ export class ArchiveCommand {
     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],
     ] as const) {
       try {
-        FileSystemUtils.assertPathWithin(allowedDirectory, managedDir);
+        if (allowLinkedLeaf) {
+          FileSystemUtils.assertPathWithinAllowingLinkedLeaf(allowedDirectory, managedDir);
+        } else {
+          FileSystemUtils.assertPathWithin(allowedDirectory, managedDir);
+        }
       } catch {
         throw new ArchiveBlockedError(
           'archive_path_outside_root',
@@ -2190,6 +2199,9 @@ export class ArchiveCommand {
                 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?: string
             ): Promise<void> => {
@@ -2213,7 +2225,7 @@ export class ArchiveCommand {
               for (const proposed of prepared) {
                 const archivedSource = path.join(
                   archivePath,
-                  path.relative(changeDir, proposed.update.source)
+                  path.relative(canonicalChangeDir, proposed.update.source)
                 );
                 if (
                   (await fingerprintPortableContent(archivedSource)) !==
@@ -2226,7 +2238,7 @@ export class ArchiveCommand {
                 if (stagedSource) {
                   const stagedDelta = path.join(
                     stagedSource,
-                    path.relative(changeDir, proposed.update.source)
+                    path.relative(canonicalChangeDir, proposed.update.source)
                   );
                   if (
                     (await fingerprintPortableContent(stagedDelta)) !==

src/core/artifact-graph/outputs.ts

@@ -1,10 +1,215 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import fg from 'fast-glob';
+import { expand } from 'brace-expansion';
+import picomatch from 'picomatch';
+import * as globby from 'tinyglobby';
 import { FileSystemUtils } from '../../utils/file-system.js';
 
 const EXTGLOB_RE = /[!*+?@]\([^(]*\)/u;
 const BRACE_EXPANSION_SEPARATORS_RE = /,|\.\./u;
+const DUPLICATE_SLASH_RE = /(?!^)\/{2,}/gu;
+// Deeply nested braces can overflow a recursive expander. Reject nesting no real
+// artifact pattern needs before brace-expansion or tinyglobby see the pattern.
+const MAX_BRACE_NESTING = 16;
+// Nesting depth alone does not bound the work: `{a,b}` repeated 20 times is
+// only one level deep and expands to 1,048,576 patterns, which exhausts the
+// heap. fast-glob never expanded that far because micromatch compiled the
+// braces to a regex. No real artifact pattern needs more than a few hundred.
+const MAX_BRACE_EXPANSIONS = 1024;
+
+const ARTIFACT_GLOB_OPTIONS = {
+  absolute: true,
+  // Braces are expanded first so `{draft}` left behind stays a literal name.
+  braceExpansion: false,
+  // fast-glob migration: directory patterns must not grow a trailing `/**`.
+  expandDirectories: false,
+  followSymbolicLinks: true,
+  onlyFiles: true,
+} as const;
+
+function assertBraceNesting(pattern: string): void {
+  // 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: string[] = [];
+  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 isDynamicSegment(segment: string): boolean {
+  return segment.includes('*') || segment.includes('?') || segment.includes('[')
+    || EXTGLOB_RE.test(segment);
+}
+
+/**
+ * Static directory prefix of an expanded pattern, equivalent to the `base`
+ * fast-glob's generateTasks used to reject `../` before walking.
+ */
+function globBase(pattern: string): string {
+  const segments = pattern.split('/');
+  if (segments.length <= 1) return '.';
+  const base: string[] = [];
+  for (const segment of segments.slice(0, -1)) {
+    if (segment === '') continue;
+    if (isDynamicSegment(segment)) break;
+    base.push(segment);
+  }
+  // An absolute pattern must stay absolute, or `path.resolve(changeDir, base)`
+  // rebases `/etc/*` inside the change directory and the containment check
+  // passes for a pattern that globs the filesystem root.
+  if (pattern.startsWith('/')) return `/${base.join('/')}`;
+  return base.length > 0 ? base.join('/') : '.';
+}
+
+// brace-expansion 5 leaves the rest of a pattern literal when a non-expanding
+// group such as `{draft}` comes before a range. Expand one real group at a time.
+// NUL-prefixed so no `generates` value can forge them: `resolveArtifactOutputPath`
+// runs `path.join` first, which rejects a NUL byte. A single-character sentinel
+// such as U+0001 is a legal filename character, and a pattern containing one
+// would come back out of the expander as a brace.
+const LITERAL_BRACE_OPEN = '\u0000<';
+const LITERAL_BRACE_CLOSE = '\u0000>';
+
+function hasTopLevelExpansion(body: string): boolean {
+  let depth = 0;
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+    if (char === '{') depth += 1;
+    else if (char === '}') depth = Math.max(0, depth - 1);
+    else if (depth === 0) {
+      if (char === ',') return true;
+      if (char === '.' && body[index + 1] === '.') return true;
+    }
+  }
+  return false;
+}
+
+function findTopLevelExpansion(pattern: string): { pre: string; body: string; post: string } | null {
+  const stack: number[] = [];
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === '{') {
+      stack.push(index);
+    } else if (char === '}' && stack.length > 0) {
+      const open = stack.pop();
+      if (open === undefined) continue;
+      // Only the outermost group that actually expands. brace-expansion expands
+      // its nested groups in one linear pass. Peeling the innermost `{a,b}` first
+      // turns `{a,{a,{a,b}}}` into a binary tree, so a 16-deep pattern does not
+      // finish before the test timeout.
+      if (stack.length > 0) continue;
+      const body = pattern.slice(open + 1, index);
+      if (!hasTopLevelExpansion(body)) {
+        // `{prefix{a,b}}` has no separator of its own, so the outer braces stay
+        // literal. Keep scanning inside them; a nested group may still expand.
+        const nested = findTopLevelExpansion(body);
+        if (!nested) continue;
+        return {
+          pre: `${pattern.slice(0, open + 1)}${nested.pre}`,
+          body: nested.body,
+          post: `${nested.post}${pattern.slice(index)}`,
+        };
+      }
+      return { pre: pattern.slice(0, open), body, post: pattern.slice(index + 1) };
+    }
+  }
+  return null;
+}
+
+function assertExpansionBudget(pattern: string, count: number): void {
+  if (count <= MAX_BRACE_EXPANSIONS) return;
+  // A pattern this wide 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 expands to more than ${MAX_BRACE_EXPANSIONS} patterns: ${shown}`
+  );
+}
+
+function expandArtifactBraces(pattern: string): string[] {
+  if (pattern.includes('\u0000')) {
+    throw new Error('Artifact output pattern contains a NUL byte');
+  }
+  const pending = [pattern];
+  const finished: string[] = [];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) break;
+    const group = findTopLevelExpansion(current);
+    if (!group) {
+      finished.push(current.replaceAll(LITERAL_BRACE_OPEN, '{').replaceAll(LITERAL_BRACE_CLOSE, '}'));
+      continue;
+    }
+    const wrapped = `{${group.body}}`;
+    // `max` makes this budget the binding one. Without it `{1..1000000000}`
+    // allocates brace-expansion's own 100,000-result default before the check
+    // below rejects it. `max` truncates silently, so ask for one result more
+    // than the budget allows: a result that long means the pattern is over
+    // budget rather than fully expanded. A truncated group never looks literal,
+    // because its first alternative is not the group itself.
+    const remaining = Math.max(MAX_BRACE_EXPANSIONS - (pending.length + finished.length), 0);
+    const alternatives = expand(wrapped, { max: remaining + 1 });
+    if (alternatives.length === 1 && alternatives[0] === wrapped) {
+      pending.push(`${group.pre}${LITERAL_BRACE_OPEN}${group.body}${LITERAL_BRACE_CLOSE}${group.post}`);
+      continue;
+    }
+    // Checked before the push so the budget bounds memory, not just the result.
+    assertExpansionBudget(pattern, pending.length + finished.length + alternatives.length);
+    for (const alternative of alternatives) {
+      pending.push(`${group.pre}${alternative}${group.post}`);
+    }
+  }
+  const normalized = finished
+    .map((value) => value.replace(DUPLICATE_SLASH_RE, '/'))
+    .filter((value) => value.length > 0);
+  return normalized.length > 0 ? normalized : [pattern];
+}
+
+/**
+ * One directory level. picomatch matches the segment; readdir keeps symlink
+ * entries tinyglobby would drop when followSymbolicLinks is false.
+ */
+function listDirectoryMatches(directory: string, segment: string): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const isMatch = picomatch(segment, {
+    dot: false,
+    nobrace: true,
+    noglobstar: true,
+    posix: true,
+  });
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (isMatch(entry.name)) names.push(entry.name);
+  }
+  return names;
+}
 
 function hasBraceExpansion(pattern: string): boolean {
   const openings: number[] = [];
@@ -79,12 +284,25 @@ function assertGlobDirectoryTraversal(
       );
     }
 
-    const matches = fg.sync(segment === '**' ? '*' : segment, {
-      cwd: canonicalDir,
-      onlyFiles: false,
-      followSymbolicLinks: false,
-      deep: 1,
-    });
+    // `.` and `..` are not directory entries. Resolve them directly so a
+    // `**/../` pattern is confined before any glob runs.
+    if (segment === '' || segment === '.' || segment === '..') {
+      const candidate = path.resolve(canonicalDir, segment === '' ? '.' : segment);
+      const canonicalCandidate = FileSystemUtils.canonicalizeExistingPath(candidate);
+      FileSystemUtils.assertPathWithin(canonicalChangeDir, canonicalCandidate);
+      assertGlobDirectoryTraversal(
+        changeDir,
+        canonicalCandidate,
+        directorySegments,
+        segmentIndex + 1,
+        visited,
+        canonicalChangeDir,
+        ancestors
+      );
+      return;
+    }
+
+    const matches = listDirectoryMatches(canonicalDir, segment === '**' ? '*' : segment);
     for (const match of matches) {
       const candidate = path.join(canonicalDir, match);
       try {
@@ -115,9 +333,11 @@ function assertGlobDirectoryTraversal(
  * Returns absolute file paths. Glob matches are sorted for deterministic output.
  */
 export function resolveArtifactOutputs(changeDir: string, generates: string): string[] {
+  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)]
@@ -127,31 +347,25 @@ export function resolveArtifactOutputs(changeDir: string, generates: string): st
     }
   }
 
-  const normalizedPattern = FileSystemUtils.toPosixPath(generates);
-  const globOptions = {
-    cwd: changeDir,
-    onlyFiles: true,
-    absolute: true,
-    // Preserve linked artifact directories; confine traversal and concrete matches.
-    followSymbolicLinks: true,
-  };
-  // Task generation expands braces without accessing the filesystem. Validate
-  // every task base before globbing, including paths introduced by expansion.
-  const tasks = fg.generateTasks(normalizedPattern, globOptions);
-  for (const task of tasks) {
-    FileSystemUtils.assertPathWithin(changeDir, path.resolve(changeDir, task.base));
+  const normalizedPattern = FileSystemUtils.toPosixPath(generates).replace(DUPLICATE_SLASH_RE, '/');
+  // Expand braces before any filesystem access. tinyglobby has no generateTasks,
+  // and a `../` alternative is invisible until the braces are expanded.
+  const patterns = expandArtifactBraces(normalizedPattern);
+  for (const pattern of patterns) {
+    FileSystemUtils.assertPathWithin(changeDir, path.resolve(changeDir, globBase(pattern)));
   }
-  for (const task of tasks) {
-    for (const positivePattern of task.positive) {
-      assertGlobDirectoryTraversal(
-        changeDir,
-        changeDir,
-        positivePattern.split('/').slice(0, -1)
-      );
-    }
+  for (const pattern of patterns) {
+    assertGlobDirectoryTraversal(
+      changeDir,
+      changeDir,
+      pattern.split('/').slice(0, -1)
+    );
   }
-  const matches = fg
-    .sync(normalizedPattern, globOptions)
+  const matches = globby
+    .globSync(patterns, {
+      cwd: changeDir,
+      ...ARTIFACT_GLOB_OPTIONS,
+    })
     .map((match) => {
       const normalizedMatch = path.normalize(match);
       FileSystemUtils.assertPathWithin(changeDir, normalizedMatch);

src/core/completions/completion-provider.ts

@@ -1,5 +1,4 @@
 import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
-import { listSchemas } from '../artifact-graph/index.js';
 
 /**
  * Cache entry for completion data
@@ -96,7 +95,10 @@ export class CompletionProvider {
       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 tinyglobby.
+    const { listSchemas } = await import('../artifact-graph/resolver.js');
     const schemaNames = listSchemas(this.projectRoot);
 
     // Update cache

src/core/parsers/requirement-blocks.ts

@@ -169,6 +169,16 @@ export interface OrphanedRequirement {
   line: number; // 1-based line number in the delta file
 }
 
+/**
+ * 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; // 1-based: the section header, or the first line of leading prose
+}
+
 export interface DeltaPlan {
   added: RequirementBlock[];
   modified: RequirementBlock[];
@@ -182,6 +192,7 @@ export interface DeltaPlan {
   unpairedRenames: UnpairedRename[];
   /** Canonical requirement blocks written outside every delta section. */
   orphanedRequirements: OrphanedRequirement[];
+  unappliedContent: UnappliedContent[];
   skippedHeaders: SkippedHeader[]; // non-canonical ### headers the reader skipped
   sectionPresence: {
     added: boolean;
@@ -256,6 +267,7 @@ export function parseDeltaSpec(content: string): DeltaPlan {
     renamed: renamedPairs,
     unpairedRenames,
     orphanedRequirements: findOrphanedRequirements(lines, fenceMask),
+    unappliedContent: findUnappliedContent(lines, fenceMask),
     skippedHeaders,
     sectionPresence: {
       added: addedLookup.found,
@@ -315,6 +327,57 @@ function findOrphanedRequirements(
   return orphans;
 }
 
+export function describeUnappliedContent(content: UnappliedContent, sentenceStart = false): string {
+  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: string[], fenceMask: boolean[]): UnappliedContent[] {
+  // 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: number, to: number, skip?: RegExp) => {
+    for (let i = from; i < to; i++) if (masked[i].trim() && !skip?.test(masked[i])) return i;
+    return -1;
+  };
+  const found: UnappliedContent[] = [];
+  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;
+}
+
 /** One `## ` section of a delta file, in the order it was written. */
 interface DeltaSection {
   title: string;

src/core/specs-apply.ts

@@ -13,6 +13,7 @@ import {
   extractRequirementsSection,
   diffScenarioNames,
   describeScenarioBalance,
+  describeUnappliedContent,
   foldRequirementName,
   parseDeltaSpec,
   normalizeRequirementName,
@@ -29,6 +30,7 @@ import {
 } 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';
 
 // -----------------------------------------------------------------------------
@@ -71,7 +73,7 @@ function resolveTrustedSpecPath(
 
   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,
@@ -96,7 +98,7 @@ function resolveTrustedSpecPath(
       );
     }
     const file = path.join(root, path.basename(specPath));
-    FileSystemUtils.assertPathWithin(root, file);
+    assertSpecFileWithin(root, file);
     return { root, file };
   }
 }
@@ -105,7 +107,7 @@ function assertTrustedSpecPath(root: string, specPath: string): void {
   if (FileSystemUtils.canonicalizeExistingPath(root) !== path.resolve(root)) {
     throw new Error(`Path is outside the allowed directory: ${specPath}`);
   }
-  FileSystemUtils.assertPathWithin(root, specPath);
+  assertSpecFileWithin(root, specPath);
 }
 
 // -----------------------------------------------------------------------------
@@ -251,6 +253,11 @@ export async function buildUpdatedSpec(
     );
   }
 
+  // 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<string>();
   for (const add of plan.added) {
@@ -1241,6 +1248,14 @@ export async function writeUpdatedSpec(
   } = {}
 ): Promise<void> {
   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);
@@ -1252,17 +1267,28 @@ export async function writeUpdatedSpec(
   // 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 as NodeJS.ErrnoException).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;

src/core/templates/workflows/continue-change.ts

@@ -31,8 +31,8 @@ const PLANNING_COMPLETE_HANDOFF = optionalWorkflow(
  */
 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(): SkillTemplate {
   return {
@@ -106,10 +106,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
 
@@ -137,7 +140,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
@@ -229,10 +232,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
 
@@ -260,7 +266,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

src/core/templates/workflows/explore.ts

@@ -195,7 +195,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.
@@ -217,6 +217,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\` |
@@ -226,7 +228,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?"
@@ -355,7 +357,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"
 
@@ -529,7 +531,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.
@@ -551,6 +553,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\` |
@@ -560,7 +564,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?"
@@ -585,7 +589,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"
 

src/core/templates/workflows/ff-change.ts

@@ -91,8 +91,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>"
 
@@ -126,7 +127,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
@@ -210,8 +211,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>"
 
@@ -245,7 +247,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

src/core/templates/workflows/propose.ts

@@ -137,8 +137,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>"
 
@@ -172,7 +173,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
@@ -302,8 +303,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>"
 
@@ -337,7 +339,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

src/core/templates/workflows/update-change.ts

@@ -117,7 +117,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.
@@ -161,7 +161,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}.`,
@@ -217,7 +217,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.
@@ -261,7 +261,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}.`

src/core/templates/workflows/verify-change.ts

@@ -95,8 +95,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"
@@ -112,7 +115,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):
@@ -166,7 +169,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**:
 
@@ -305,8 +308,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"
@@ -322,7 +328,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):
@@ -376,7 +382,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**:
 

src/core/validation/validator.ts

@@ -18,6 +18,7 @@ import {
   extractRequirementsSection,
   diffScenarioNames,
   describeScenarioBalance,
+  describeUnappliedContent,
   type RequirementBlock,
 } from '../parsers/requirement-blocks.js';
 import {
@@ -28,6 +29,7 @@ import {
 } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { assertDiscoveredSpecFile } from '../../utils/spec-path-containment.js';
 import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
 import {
   METADATA_FILENAME,
@@ -257,6 +259,17 @@ export class Validator {
           });
         }
 
+        // 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: string[] = [];
         if (plan.sectionPresence.added) sectionNames.push('## ADDED Requirements');
         if (plan.sectionPresence.modified) sectionNames.push('## MODIFIED Requirements');
@@ -364,14 +377,13 @@ export class Validator {
             ...specId.split('/'),
             'spec.md'
           );
-          FileSystemUtils.assertPathWithin(path.dirname(mainSpecFile), mainSpecFile);
           issues.push(
             ...(await this.findScenarioLossIssues(
               plan.modified,
               plan.renamed,
               mainSpecFile,
               entryPath,
-              path.dirname(mainSpecFile)
+              options.mainSpecsDir
             ))
           );
         }
@@ -698,7 +710,7 @@ export class Validator {
     mainSpecRoot: string
   ): Promise<ValidationIssue[]> {
     let mainContent: string;
-    FileSystemUtils.assertPathWithin(mainSpecRoot, mainSpecFile);
+    assertDiscoveredSpecFile(mainSpecRoot, mainSpecFile);
     try {
       mainContent = await fs.readFile(mainSpecFile, 'utf-8');
     } catch (error) {

src/utils/change-metadata.ts

@@ -14,10 +14,26 @@ 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: string): boolean {
+  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: unknown): string[] {
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -25,7 +41,7 @@ export function listUnknownChangeMetadataKeys(parsed: unknown): string[] {
   }
   const known = new Set<string>(CHANGE_METADATA_KNOWN_KEYS);
   return Object.keys(parsed as Record<string, unknown>)
-    .filter((key) => !known.has(key))
+    .filter((key) => !known.has(key) && !isExtensionMetadataKey(key))
     .sort();
 }
 
@@ -41,7 +57,13 @@ export function formatUnknownChangeMetadataKeysMessage(keys: string[]): string {
   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/.';
@@ -110,6 +132,11 @@ export function validateSchemaName(
 /**
  * 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

src/utils/file-system.ts

@@ -82,7 +82,7 @@ function findMarkerIndex(
 export class FileSystemUtils {
   /**
    * Converts a path to use forward slashes (POSIX style).
-   * Essential for cross-platform compatibility with glob libraries like fast-glob.
+   * Essential for cross-platform compatibility with glob libraries like tinyglobby.
    */
   static toPosixPath(p: string): string {
     return p.replace(/\\/g, '/');
@@ -125,6 +125,33 @@ export class FileSystemUtils {
     }
   }
 
+  /**
+   * 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 {
+    const resolvedTarget = path.resolve(targetPath);
+    let isLink = false;
+    try {
+      isLink = nodeFs.lstatSync(resolvedTarget).isSymbolicLink();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).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: string, artifactPath: string): string {
     if (path.isAbsolute(artifactPath)) {
       throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);

src/utils/interactive.ts

@@ -176,3 +176,22 @@ function readYesNo(
   });
 }
 
+/**
+ * Whether a spinner can safely render to `stream`.
+ *
+ * ora decides how many lines to erase with `ceil(width / stream.columns)`, so a
+ * TTY that reports zero columns makes that count `Infinity` and `clear()` never
+ * ends: the spinner emits cursor-up/clear-line escapes as fast as it can and the
+ * command never finishes (#2106). Zero-width TTYs are real — a pty inherited
+ * from a pre-commit runner such as lefthook, or `script -qec` — and nothing can
+ * be drawn in zero columns anyway, so refuse the spinner and let the caller fall
+ * back to its plain output.
+ */
+export function canRenderSpinner(
+  stream: { isTTY?: boolean; columns?: number } = process.stderr
+): boolean {
+  // A non-TTY stream never enters the clear loop: ora disables itself and
+  // prints one plain line instead.
+  if (!stream.isTTY) return true;
+  return (stream.columns ?? 0) > 0;
+}

src/utils/spec-discovery.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { FileSystemUtils } from './file-system.js';
+import { assertDiscoveredSpecFile } from './spec-path-containment.js';
 import { parseDeltaSpec } from '../core/parsers/requirement-blocks.js';
 
 export interface DiscoveredSpec {
@@ -10,26 +10,16 @@ export interface DiscoveredSpec {
   specFile: string;
 }
 
-function assertDiscoveredSpecPath(specsRoot: string, capabilityDir: string, specFile: string): void {
-  try {
-    FileSystemUtils.assertPathWithin(specsRoot, specFile);
-  } catch {
-    // Direct capability directories may intentionally be external monorepo
-    // links. In that case, confine the file to the capability itself.
-    FileSystemUtils.assertPathWithin(capabilityDir, specFile);
-  }
-}
-
 /**
  * Recursively discover every `spec.md` under a specs root, so both the flat
  * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
  * are found (#1353). A `spec.md` sitting directly in the root is ignored,
  * matching the historical requirement that specs live in a capability folder.
  * Dot-directories are skipped and symlinked directories are not followed.
- * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
- * artifact graph's globs both count it as content, so dropping it here would
- * silently lose the delta on archive. A link outside its capability is
- * rejected and a dangling link is skipped. Results are sorted by id.
+ * A symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the artifact
+ * graph's globs both count it as content, so dropping it here would silently
+ * lose the delta on archive. `assertSpecFilePathAllowed` decides how far such
+ * a link may point; a dangling link is skipped. Results are sorted by id.
  *
  * A missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
@@ -53,12 +43,12 @@ export async function discoverSpecFiles(specsRoot: string): Promise<DiscoveredSp
       } else if (entry.name === 'spec.md' && segments.length > 0) {
         const specFile = path.join(dir, entry.name);
         if (entry.isFile()) {
-          assertDiscoveredSpecPath(specsRoot, dir, specFile);
+          assertDiscoveredSpecFile(specsRoot, specFile);
           results.push({ id: segments.join('/'), specFile });
         } else if (entry.isSymbolicLink()) {
           try {
             if ((await fs.stat(specFile)).isFile()) {
-              assertDiscoveredSpecPath(specsRoot, dir, specFile);
+              assertDiscoveredSpecFile(specsRoot, specFile);
               results.push({ id: segments.join('/'), specFile });
             }
           } catch (err: any) {

src/utils/spec-path-containment.ts

@@ -0,0 +1,132 @@
+import * as nodeFs from 'fs';
+import path from 'path';
+import { OPENSPEC_DIR_NAME } from '../core/config.js';
+import { FileSystemUtils } from './file-system.js';
+
+/**
+ * The project a specs root belongs to, or null when it cannot be named.
+ *
+ * Every specs root OpenSpec reads is addressed through the project's
+ * `openspec` directory - `<project>/openspec/specs` for main specs and
+ * `<project>/openspec/changes/<change>/specs` (or `.../changes/archive/...`)
+ * for a change's deltas - so the project is the parent of that `openspec`
+ * directory.
+ *
+ * The directory below the match has to be `specs` or `changes`, which is what
+ * makes this a planning root rather than a directory that merely shares the
+ * name: a store kept at `~/openspec/my-store` would otherwise hand out `~` as
+ * its boundary. A specs root reached some other way (a store given by path)
+ * has no project to name, and containment stays at the specs root.
+ */
+function findProjectRoot(specsRoot: string): string | null {
+  let current = path.resolve(specsRoot);
+  let below: string | null = null;
+  while (true) {
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    if (
+      path.basename(current) === OPENSPEC_DIR_NAME &&
+      (below === 'specs' || below === 'changes')
+    ) {
+      return parent;
+    }
+    below = path.basename(current);
+    current = parent;
+  }
+}
+
+/** Path-segment containment on the paths as written, without resolving links. */
+function isLexicallyWithin(allowedDirectory: string, targetPath: string): boolean {
+  const relative = path.relative(path.resolve(allowedDirectory), path.resolve(targetPath));
+  return (
+    relative === '' ||
+    (relative !== '..' &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * A project may keep a capability's spec file elsewhere - beside the product
+ * documentation it belongs to - and leave a relative symlink at
+ * `openspec/specs/<capability>/spec.md`, so OpenSpec and the docs read and
+ * write the same bytes. Accept such a link, and refuse one that leaves the
+ * project, so a link swapped underneath a repo cannot turn a spec read or an
+ * archive write into an arbitrary file access.
+ *
+ * `outsideError` is rethrown when the file is not a link at all, so a path
+ * that simply escapes its root keeps reporting that.
+ */
+function assertLinkedSpecFileInProject(
+  root: string,
+  specFile: string,
+  outsideError: unknown
+): void {
+  const projectRoot = findProjectRoot(root);
+  if (projectRoot === null) {
+    throw outsideError;
+  }
+
+  const resolvedFile = path.resolve(specFile);
+  let isLink = false;
+  try {
+    isLink = nodeFs.lstatSync(resolvedFile).isSymbolicLink();
+  } catch {
+    isLink = false;
+  }
+  if (!isLink) {
+    throw outsideError;
+  }
+
+  // Only where the link points is the project's choice. The directory holding
+  // it must still be reached from inside the root.
+  FileSystemUtils.assertPathWithin(root, path.dirname(resolvedFile));
+  // Canonicalizes through the link, so a target outside the project is refused
+  // and a dangling link - which cannot be proven contained - fails loudly.
+  FileSystemUtils.assertPathWithin(projectRoot, resolvedFile);
+}
+
+/**
+ * Containment for a `spec.md` under a trust root already established for it:
+ * inside the root, or a link out of the root that stays inside the project.
+ *
+ * Deliberately does not re-derive a trust root from the file's own capability
+ * directory. Callers use this to recheck a path immediately before reading or
+ * writing it, and a capability directory swapped for a link since the path was
+ * resolved has to be refused rather than trusted afresh.
+ */
+export function assertSpecFileWithin(root: string, specFile: string): void {
+  try {
+    FileSystemUtils.assertPathWithin(root, specFile);
+  } catch (error) {
+    assertLinkedSpecFileInProject(root, specFile, error);
+  }
+}
+
+/**
+ * Containment for a `spec.md` as it is discovered, where the capability
+ * directory itself may deliberately be a link into another repository and is
+ * then the file's own trust root.
+ */
+export function assertDiscoveredSpecFile(specsRoot: string, specFile: string): void {
+  const capabilityDir = path.dirname(path.resolve(specFile));
+  try {
+    FileSystemUtils.assertPathWithin(specsRoot, specFile);
+    return;
+  } catch (error) {
+    // The capability directory is the file's own trust root only while it is
+    // addressed from inside the specs root: the link it may be is deliberate,
+    // a `..` out of the root is not.
+    if (isLexicallyWithin(specsRoot, capabilityDir)) {
+      try {
+        FileSystemUtils.assertPathWithin(capabilityDir, specFile);
+        return;
+      } catch {
+        // Not a file of its own capability either; the link rule decides.
+      }
+    }
+    assertLinkedSpecFileInProject(specsRoot, specFile, error);
+  }
+}

test/cli-e2e/spec-symlink-into-project.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { tmpdir } from 'os';
+import { runCLI } from '../helpers/run-cli.js';
+
+/**
+ * The layout reported in #2100: a project keeps its main specs beside the
+ * product documentation they belong to and links
+ * `openspec/specs/<capability>/spec.md` to them, so OpenSpec and the docs read
+ * and write the same bytes.
+ *
+ * Driven through the real CLI on purpose. The regression this guards against
+ * was introduced by a containment check several layers down, and the unit
+ * tests of the day could not see it because their fixtures placed "outside the
+ * specs root" and "outside the project" at the same path. Exercising the
+ * commands a user actually runs does not care which layer the boundary moves
+ * in: it fails if any of them stops accepting the link, or starts accepting a
+ * link that leaves the project.
+ */
+const describeWithSymlinks = describe.skipIf(process.platform === 'win32');
+
+describeWithSymlinks('a main spec that is a symlink into the project (#2100)', () => {
+  let base: string;
+  let projectDir: string;
+  let docsSpec: string;
+  let linkedSpec: string;
+
+  const MAIN_SPEC = [
+    '# login Specification',
+    '',
+    '## Purpose',
+    'Users sign in with their credentials to reach their account.',
+    '',
+    '## Requirements',
+    '',
+    '### Requirement: Sign in',
+    'The system SHALL let a user sign in with valid credentials.',
+    '',
+    '#### Scenario: Valid credentials',
+    '- **WHEN** the user submits valid credentials',
+    '- **THEN** the user is signed in',
+    '',
+  ].join('\n');
+
+  const DELTA = [
+    '## ADDED Requirements',
+    '',
+    '### Requirement: Second factor',
+    'The system SHALL require a second factor.',
+    '',
+    '#### Scenario: Prompted',
+    '- **WHEN** a user signs in',
+    '- **THEN** a second factor is requested',
+    '',
+  ].join('\n');
+
+  const write = async (relative: string, content: string) => {
+    const file = path.join(projectDir, relative);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, content);
+  };
+
+  beforeEach(async () => {
+    // The project sits one level below the temp root, so a link written to the
+    // temp root genuinely leaves the project.
+    base = await fs.mkdtemp(path.join(tmpdir(), 'openspec-spec-symlink-e2e-'));
+    projectDir = path.join(base, 'repo');
+    docsSpec = path.join(projectDir, 'docs', 'auth', 'specs', 'login.md');
+    linkedSpec = path.join(projectDir, 'openspec', 'specs', 'login', 'spec.md');
+
+    await write(path.join('docs', 'auth', 'specs', 'login.md'), MAIN_SPEC);
+    await write(path.join('openspec', 'changes', 'add-mfa', 'proposal.md'),
+      '# Add MFA\n\n## Why\nAccounts need a second factor.\n\n## What Changes\n- Require a second factor\n');
+    await write(path.join('openspec', 'changes', 'add-mfa', 'tasks.md'), '## 1. Work\n- [x] 1.1 Ship it\n');
+    await write(path.join('openspec', 'changes', 'add-mfa', 'specs', 'login', 'spec.md'), DELTA);
+    await fs.mkdir(path.dirname(linkedSpec), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(base, { recursive: true, force: true });
+  });
+
+  const linkInto = (target: string) =>
+    fs.symlink(path.relative(path.dirname(linkedSpec), target), linkedSpec);
+
+  describe('when the link stays inside the project', () => {
+    beforeEach(async () => {
+      await linkInto(docsSpec);
+    });
+
+    it('lists the capability', async () => {
+      const result = await runCLI(['list', '--specs'], { cwd: projectDir });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('login');
+    });
+
+    it('shows the linked file as the spec', async () => {
+      const result = await runCLI(['show', 'login', '--type', 'spec'], { cwd: projectDir });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Users sign in with their credentials');
+    });
+
+    it('validates the capability, by id and as part of --specs', async () => {
+      const byId = await runCLI(['validate', 'login', '--type', 'spec'], { cwd: projectDir });
+      expect(byId.exitCode).toBe(0);
+
+      const all = await runCLI(['validate', '--specs'], { cwd: projectDir });
+      expect(all.exitCode).toBe(0);
+      expect(`${all.stdout}${all.stderr}`).not.toContain('outside the allowed directory');
+    });
+
+    it('archives through the link, leaving the link and the docs file in place', async () => {
+      const result = await runCLI(['archive', 'add-mfa', '--yes'], { cwd: projectDir });
+      expect(result.exitCode).toBe(0);
+
+      // The merge landed in the file the docs own, and kept what was there.
+      const merged = await fs.readFile(docsSpec, 'utf-8');
+      expect(merged).toContain('Second factor');
+      expect(merged).toContain('Sign in');
+      // ...by writing through the link rather than replacing it.
+      expect((await fs.lstat(linkedSpec)).isSymbolicLink()).toBe(true);
+    });
+  });
+
+  describe('when the link leaves the project', () => {
+    let outside: string;
+
+    beforeEach(async () => {
+      outside = path.join(base, 'outside.md');
+      await fs.writeFile(outside, MAIN_SPEC);
+      await linkInto(outside);
+    });
+
+    it.each([
+      ['list', ['list', '--specs']],
+      ['show', ['show', 'login', '--type', 'spec']],
+      ['validate by id', ['validate', 'login', '--type', 'spec']],
+      ['validate --specs', ['validate', '--specs']],
+    ])('refuses it in %s', async (_label, args) => {
+      const result = await runCLI(args, { cwd: projectDir });
+      expect(result.exitCode).not.toBe(0);
+      expect(`${result.stdout}${result.stderr}`).toContain('outside the allowed directory');
+    });
+
+    it('refuses to archive, and writes nothing', async () => {
+      const result = await runCLI(['archive', 'add-mfa', '--yes'], { cwd: projectDir });
+      expect(result.exitCode).not.toBe(0);
+      expect(`${result.stdout}${result.stderr}`).toContain('outside the allowed directory');
+      await expect(fs.readFile(outside, 'utf-8')).resolves.toBe(MAIN_SPEC);
+      // The change is still there to retry once the link is corrected.
+      await expect(
+        fs.access(path.join(projectDir, 'openspec', 'changes', 'add-mfa'))
+      ).resolves.toBeUndefined();
+    });
+  });
+});

test/cli-e2e/startup-modules.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, describe, expect, it } from 'vitest';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -118,6 +118,103 @@ describe('CLI startup loads only what the command needs', () => {
     }
   );
 
+  // Shell completion scripts run `__complete` on every Tab press. It needs no
+  // package beyond commander, and never telemetry: tracking would hold each
+  // press open for the request.
+  it.each(['changes', 'specs'])(
+    '`openspec __complete %s` loads only commander and no telemetry',
+    async (type) => {
+      await ensureCliBuilt();
+      const { own, packages, status } = loadedModules(['__complete', type]);
+
+      expect(status).toBe(0);
+      expect([...packages]).toEqual(['commander']);
+      expect(implementationsLoaded(own)).toEqual(['completion']);
+      expect(own).not.toContain('telemetry/index.js');
+    }
+  );
+
+  it('`openspec __complete schemas` loads the schema reader but not tinyglobby or ora', async () => {
+    await ensureCliBuilt();
+    const { own, packages, status } = loadedModules(['__complete', 'schemas']);
+
+    expect(status).toBe(0);
+    expect([...packages]).not.toContain('fast-glob');
+    expect([...packages]).not.toContain('tinyglobby');
+    expect([...packages]).not.toContain('brace-expansion');
+    expect([...packages]).not.toContain('ora');
+    expect(own).not.toContain('telemetry/index.js');
+    // The name promises a schema reader, so pin it: the resolver directly, not
+    // the artifact-graph barrel, which re-exports it but also pulls outputs.js
+    // and with it tinyglobby.
+    expect(own).toContain('core/artifact-graph/resolver.js');
+    expect(own).not.toContain('core/artifact-graph/index.js');
+  });
+
+  // Negative control for the two cases above. `isTabCompletionRun` matches the
+  // command path exactly, unlike the adjacent `isCompletionRun`, which
+  // prefix-matches `completion:*`. Widening one into the other would silently
+  // stop tracking every user-facing command in that group, and every assertion
+  // above would still pass.
+  it.each([['list --json'], ['completion generate zsh']])(
+    '`openspec %s` still reaches the telemetry hooks',
+    async (invocation) => {
+      await ensureCliBuilt();
+      const { own } = loadedModules(invocation.split(' '));
+
+      expect(own).toContain('telemetry/index.js');
+      expect(own).toContain('core/completion-tip.js');
+    }
+  );
+
+  // The module-count assertions above pin that telemetry is not LOADED. They do
+  // not pin the user-visible consequence, which is the reason the skip exists:
+  // the first-run disclosure goes to stderr, every generated completion script
+  // sends `__complete` stderr to /dev/null, and `maybeShowTelemetryNotice` marks
+  // `noticeSeen` before `trackCommand` re-reads it. So before this change a
+  // user's first-ever interaction being a Tab press burned the disclosure where
+  // nobody could read it and began collecting on that same press.
+  //
+  // Telemetry is deliberately left ENABLED here: the point is that an enabled
+  // run still records nothing. HOME must be isolated as well as XDG_CONFIG_HOME,
+  // or `migrateLegacyTelemetryConfig` imports the developer's real config from
+  // ~/.config/openspec/config.json and the test passes vacuously.
+  it('`openspec __complete` leaves the first-run telemetry notice unconsumed', async () => {
+    await ensureCliBuilt();
+    const home = mkdtempSync(path.join(os.tmpdir(), 'openspec-notice-'));
+    workDirs.push(home);
+    const configHome = path.join(home, 'config');
+
+    // These have to be DELETED, not blanked. Both opt-outs read as "set to
+    // anything that is not an explicit on-value", so `OPENSPEC_TELEMETRY: ''`
+    // and `DO_NOT_TRACK: ''` would switch telemetry OFF and the assertions
+    // below would hold on any build, passing vacuously.
+    const env = {
+      ...process.env,
+      HOME: home,
+      USERPROFILE: home,
+      XDG_CONFIG_HOME: configHome,
+      XDG_DATA_HOME: path.join(home, 'data'),
+    };
+    delete env.OPENSPEC_TELEMETRY;
+    delete env.DO_NOT_TRACK;
+    delete env.CI;
+
+    const result = spawnSync(process.execPath, [binPath, '__complete', 'changes'], {
+      cwd: home,
+      env,
+      encoding: 'utf-8',
+      timeout: 30_000,
+      windowsHide: true,
+    });
+
+    expect(result.status).toBe(0);
+    // No disclosure written to a stream the completion scripts discard.
+    expect(result.stderr).toBe('');
+    // And no config file, so neither noticeSeen nor an anonymousId was minted.
+    expect(existsSync(path.join(configHome, 'openspec', 'config.json'))).toBe(false);
+  });
+
   it.each([
     ['config list --json', 'config'],
     ['config path', 'config'],

test/core/archive.test.ts

@@ -6,7 +6,7 @@ import { MarkdownParser } from '../../src/core/parsers/markdown-parser.js';
 import { findMainSpecStructureIssues } from '../../src/core/parsers/spec-structure.js';
 import { VALIDATION_MESSAGES } from '../../src/core/validation/constants.js';
 import { formatLocalDate } from '../../src/utils/date.js';
-import { promises as fs, realpathSync } from 'fs';
+import { constants as fsConstants, promises as fs, realpathSync } from 'fs';
 import path from 'path';
 import os from 'os';
 
@@ -153,6 +153,31 @@ describe('ArchiveCommand', () => {
       );
     });
 
+    it('archives x- extension keys without a warning and keeps them byte-for-byte', async () => {
+      const changeName = 'extension-metadata';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), '- [x] Task 1\n');
+      const metadata =
+        'schema: spec-driven\nx-goal: G-12\nx-tracker:\n  system: linear\n  id: SB-5497\n';
+      await fs.writeFile(path.join(changeDir, '.openspec.yaml'), metadata);
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true, json: true });
+
+      const logCalls = (console.log as unknown as { mock: { calls: unknown[][] } }).mock.calls
+        .flat()
+        .map(String);
+      const jsonLine = logCalls.find((entry) => entry.trimStart().startsWith('{'));
+      expect(jsonLine).toBeDefined();
+      expect(JSON.parse(jsonLine!).archive.warnings).toBeUndefined();
+
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const [archived] = await fs.readdir(archiveDir);
+      expect(
+        await fs.readFile(path.join(archiveDir, archived, '.openspec.yaml'), 'utf-8')
+      ).toBe(metadata);
+    });
+
     describe('a namespace folder holding nested changes (#1846)', () => {
       async function seedNamespaceFolder(): Promise<string> {
         const nested = path.join(tempDir, 'openspec', 'changes', 'mobile', 'refresh-token');
@@ -619,6 +644,180 @@ describe('ArchiveCommand', () => {
       await expect(fs.readdir(outsideDir)).resolves.toEqual([]);
     });
 
+    it('archives when openspec/changes is a project-owned symlink to another directory', async () => {
+      const changeName = 'linked-change';
+      const docsRepo = realpathSync.native(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-docs-repo-'))
+      );
+      onTestFinished(() => fs.rm(docsRepo, { recursive: true, force: true }));
+      const sharedChanges = path.join(docsRepo, 'changes');
+      const changesLink = path.join(tempDir, 'openspec', 'changes');
+      await fs.rm(changesLink, { recursive: true, force: true });
+      await fs.mkdir(path.join(sharedChanges, changeName), { recursive: true });
+      await fs.writeFile(path.join(sharedChanges, changeName, 'tasks.md'), '- [x] Task 1\n');
+      await fs.symlink(sharedChanges, changesLink, process.platform === 'win32' ? 'junction' : 'dir');
+
+      await archiveCommand.execute(changeName, {
+        yes: true,
+        noValidate: true,
+        skipSpecs: true,
+      });
+
+      await expect(fs.access(path.join(sharedChanges, changeName))).rejects.toThrow();
+      const archived = await fs.readdir(path.join(sharedChanges, 'archive'));
+      expect(archived.some((name) => name.endsWith(`-${changeName}`))).toBe(true);
+    });
+
+    it.each([
+      { linkChanges: true, linkSpecs: false },
+      { linkChanges: false, linkSpecs: true },
+      { linkChanges: true, linkSpecs: true },
+    ])(
+      'applies a spec delta and archives with symlinked changes=$linkChanges specs=$linkSpecs',
+      async ({ linkChanges, linkSpecs }) => {
+        const changeName = 'linked-delta';
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+        const docsRepo = realpathSync.native(
+          await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-docs-repo-'))
+        );
+        onTestFinished(() => fs.rm(docsRepo, { recursive: true, force: true }));
+        const openspecDir = path.join(tempDir, 'openspec');
+        const changesDir = linkChanges ? path.join(docsRepo, 'changes') : path.join(openspecDir, 'changes');
+        const specsDir = linkSpecs ? path.join(docsRepo, 'specs') : path.join(openspecDir, 'specs');
+        if (linkChanges) {
+          await fs.rm(path.join(openspecDir, 'changes'), { recursive: true, force: true });
+          await fs.mkdir(changesDir, { recursive: true });
+          await fs.symlink(changesDir, path.join(openspecDir, 'changes'), linkType);
+        }
+        if (linkSpecs) {
+          await fs.rm(path.join(openspecDir, 'specs'), { recursive: true, force: true });
+          await fs.mkdir(specsDir, { recursive: true });
+          await fs.symlink(specsDir, path.join(openspecDir, 'specs'), linkType);
+        }
+        const deltaDir = path.join(changesDir, changeName, 'specs', 'linked-capability');
+        await fs.mkdir(deltaDir, { recursive: true });
+        await fs.writeFile(
+          path.join(deltaDir, 'spec.md'),
+          `# Linked Capability - Changes
+
+## ADDED Requirements
+
+### Requirement: The system SHALL archive through linked directories
+
+#### Scenario: Linked directories
+- **WHEN** the change is archived
+- **THEN** the delta is applied and the change is archived
+`
+        );
+
+        await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+
+        const mainSpec = await fs.readFile(
+          path.join(specsDir, 'linked-capability', 'spec.md'),
+          'utf-8'
+        );
+        expect(mainSpec).toContain('### Requirement: The system SHALL archive through linked directories');
+        await expect(fs.access(path.join(changesDir, changeName))).rejects.toThrow();
+        const archived = await fs.readdir(path.join(changesDir, 'archive'));
+        const archivedName = archived.find((name) => name.endsWith(`-${changeName}`));
+        expect(archivedName).toBeDefined();
+        await expect(
+          fs.access(path.join(changesDir, 'archive', archivedName!, 'specs', 'linked-capability', 'spec.md'))
+        ).resolves.not.toThrow();
+      }
+    );
+
+    it('archives when the whole openspec directory is a project-owned symlink', async () => {
+      const changeName = 'linked-openspec';
+      const docsRepo = realpathSync.native(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-docs-repo-'))
+      );
+      onTestFinished(() => fs.rm(docsRepo, { recursive: true, force: true }));
+      const sharedOpenspec = path.join(docsRepo, 'openspec');
+      await fs.rm(path.join(tempDir, 'openspec'), { recursive: true, force: true });
+      await fs.mkdir(path.join(sharedOpenspec, 'changes', changeName), { recursive: true });
+      await fs.mkdir(path.join(sharedOpenspec, 'specs'), { recursive: true });
+      await fs.writeFile(
+        path.join(sharedOpenspec, 'changes', changeName, 'tasks.md'),
+        '- [x] Task 1\n'
+      );
+      await fs.symlink(
+        sharedOpenspec,
+        path.join(tempDir, 'openspec'),
+        process.platform === 'win32' ? 'junction' : 'dir'
+      );
+
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true, skipSpecs: true });
+
+      const archived = await fs.readdir(path.join(sharedOpenspec, 'changes', 'archive'));
+      expect(archived.some((name) => name.endsWith(`-${changeName}`))).toBe(true);
+    });
+
+    it('rejects an archive directory that escapes a symlinked changes directory', async () => {
+      const changeName = 'linked-escape';
+      const docsRepo = realpathSync.native(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-docs-repo-'))
+      );
+      onTestFinished(() => fs.rm(docsRepo, { recursive: true, force: true }));
+      const sharedChanges = path.join(docsRepo, 'changes');
+      const outsideDir = path.join(docsRepo, 'outside');
+      const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+      await fs.rm(path.join(tempDir, 'openspec', 'changes'), { recursive: true, force: true });
+      await fs.mkdir(path.join(sharedChanges, changeName), { recursive: true });
+      await fs.mkdir(outsideDir);
+      await fs.writeFile(path.join(sharedChanges, changeName, 'tasks.md'), '- [x] Task 1\n');
+      await fs.symlink(sharedChanges, path.join(tempDir, 'openspec', 'changes'), linkType);
+      await fs.symlink(outsideDir, path.join(sharedChanges, 'archive'), linkType);
+
+      await expect(
+        archiveCommand.execute(changeName, { yes: true, noValidate: true, skipSpecs: true })
+      ).rejects.toThrow(/outside the OpenSpec root/u);
+      await expect(fs.access(path.join(sharedChanges, changeName))).resolves.not.toThrow();
+      await expect(fs.readdir(outsideDir)).resolves.toEqual([]);
+    });
+
+    it('verifies deltas through a symlinked changes directory on the cross-device fallback', async () => {
+      const changeName = 'linked-exdev';
+      const docsRepo = realpathSync.native(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-docs-repo-'))
+      );
+      onTestFinished(() => fs.rm(docsRepo, { recursive: true, force: true }));
+      const sharedChanges = path.join(docsRepo, 'changes');
+      const deltaDir = path.join(sharedChanges, changeName, 'specs', 'linked-capability');
+      await fs.rm(path.join(tempDir, 'openspec', 'changes'), { recursive: true, force: true });
+      await fs.mkdir(deltaDir, { recursive: true });
+      await fs.writeFile(
+        path.join(deltaDir, 'spec.md'),
+        `## ADDED Requirements
+
+### Requirement: The system SHALL survive EXDEV
+The system SHALL archive.
+
+#### Scenario: Cross device
+- **WHEN** rename fails with EXDEV
+- **THEN** the copy fallback archives the change
+`
+      );
+      await fs.symlink(
+        sharedChanges,
+        path.join(tempDir, 'openspec', 'changes'),
+        process.platform === 'win32' ? 'junction' : 'dir'
+      );
+
+      const rename = vi.spyOn(fs, 'rename').mockRejectedValueOnce(
+        Object.assign(new Error('cross-device move'), { code: 'EXDEV' })
+      );
+      try {
+        await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      } finally {
+        rename.mockRestore();
+      }
+
+      await expect(fs.access(path.join(sharedChanges, changeName))).rejects.toThrow();
+      const archived = await fs.readdir(path.join(sharedChanges, 'archive'));
+      expect(archived.some((name) => name.endsWith(`-${changeName}`))).toBe(true);
+    });
+
     it('archives normally when the project root is reached through a symlink alias', async () => {
       if (process.platform === 'win32') return;
 
@@ -7664,12 +7863,15 @@ The system SHALL provide a new behavior.
         });
 
         await expect(archiveCommand.execute(changeName, { yes: true })).rejects.toThrow(
-          /Path is outside the allowed directory/
+          /changed while archive was securing it for retirement/
         );
 
         expect((await fs.lstat(linkedSpec)).isSymbolicLink()).toBe(true);
         expect(await fs.readlink(linkedSpec)).toBe(shared);
-        await expect(fs.readFile(shared, 'utf-8')).resolves.toBe(mainSpec('a-layer'));
+        // The link is back, and the update that landed on its target while the
+        // retirement was in flight is still there - restoring the link must not
+        // write through it.
+        await expect(fs.readFile(shared, 'utf-8')).resolves.toBe('concurrent update\n');
         await expect(fs.access(changeDir)).resolves.not.toThrow();
       }
     );
@@ -7713,11 +7915,31 @@ The system SHALL provide a new behavior.
         });
 
         await expect(archiveCommand.execute(changeName, { yes: true })).rejects.toThrow(
-          /Path is outside the allowed directory/
+          /A concurrent file appeared at/
         );
 
-        expect((await fs.lstat(linkedSpec)).isSymbolicLink()).toBe(true);
-        expect(await fs.readlink(linkedSpec)).toBe(shared);
+        // The occupant that appeared at the link's path is left exactly as it
+        // was found; the displaced link is retained beside it instead.
+        // O_NOFOLLOW makes the open itself fail if the path is a link again, so
+        // one handle both proves the occupant is a regular file and carries its
+        // bytes - no second lookup that could land on a different file.
+        const occupant = await fs.open(
+          linkedSpec,
+          fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW
+        );
+        try {
+          expect((await occupant.stat()).isFile()).toBe(true);
+          await expect(occupant.readFile('utf-8')).resolves.toBe('concurrent occupant\n');
+        } finally {
+          await occupant.close();
+        }
+        const retained = (await fs.readdir(path.dirname(linkedSpec))).find((name) =>
+          name.includes('.openspec-retire-')
+        );
+        expect(retained).toBeDefined();
+        expect(
+          (await fs.lstat(path.join(path.dirname(linkedSpec), retained!))).isSymbolicLink()
+        ).toBe(true);
         await expect(fs.readFile(shared, 'utf-8')).resolves.toBe(mainSpec('a-layer'));
         await expect(fs.access(changeDir)).resolves.not.toThrow();
       }
@@ -7774,7 +7996,7 @@ The system SHALL provide a new behavior.
         });
 
         await expect(archiveCommand.execute(changeName, { yes: true })).rejects.toThrow(
-          /Path is outside the allowed directory/
+          /permission denied/
         );
 
         await expect(fs.readFile(shared, 'utf-8')).resolves.toBe(original);
@@ -8173,10 +8395,12 @@ The system SHALL provide a new behavior.
         await archiveCommand.execute(changeName, { yes: true, json: true });
 
         const payload = JSON.parse(lastJsonPayload());
-        expect(payload.archive).toBeNull();
-        expect(payload.status[0].message).toContain('Path is outside the allowed directory');
-        expect((await fs.lstat(path.join(mainSpecDir, 'spec.md'))).isSymbolicLink()).toBe(true);
-        // The shared file really is still there.
+        expect(payload.archive.specsUpdated).toBe(true);
+        const notes = payload.archive.warnings.join('\n');
+        expect(notes).toContain('openspec/specs/legacy-layer/spec.md');
+        expect(notes).not.toContain('shared-legacy.md');
+        // The link is gone, and the shared file it pointed at really is still there.
+        await expect(fs.lstat(path.join(mainSpecDir, 'spec.md'))).rejects.toThrow();
         await expect(fs.readFile(shared, 'utf-8')).resolves.toContain('### Requirement:');
       }
     );

test/core/artifact-graph/outputs.test.ts

@@ -1,5 +1,13 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import fg from 'fast-glob';
+import * as globby from 'tinyglobby';
+
+vi.mock('tinyglobby', async () => {
+  const actual = await vi.importActual<typeof import('tinyglobby')>('tinyglobby');
+  return {
+    ...actual,
+    globSync: vi.fn((...args: Parameters<typeof actual.globSync>) => actual.globSync(...args)),
+  };
+});
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -18,6 +26,7 @@ describe('artifact-graph/outputs', () => {
 
   beforeEach(() => {
     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-outputs-test-'));
+    vi.mocked(globby.globSync).mockClear();
   });
 
   afterEach(() => {
@@ -138,7 +147,7 @@ describe('artifact-graph/outputs', () => {
     const outsideDir = fs.mkdtempSync(path.join(path.dirname(tempDir), 'openspec-outside-'));
     const pattern = `{safe,../${path.basename(outsideDir)}}/review.md`;
     if (exists) fs.writeFileSync(path.join(outsideDir, 'review.md'), 'private');
-    const glob = vi.spyOn(fg, 'sync');
+    const glob = vi.mocked(globby.globSync);
     try {
       expect(() => resolveArtifactOutputs(tempDir, pattern)).toThrow(
         /outside the allowed directory/u
@@ -160,6 +169,39 @@ describe('artifact-graph/outputs', () => {
     expect(resolveArtifactOutputs(tempDir, pattern)).toEqual([canonical(filePath)]);
   });
 
+  it.each([
+    ['{prefix{a,b}}.md', ['{prefixa}.md', '{prefixb}.md']],
+    ['{prefix{1..2}}.md', ['{prefix1}.md', '{prefix2}.md']],
+    ['{pre{a,b}post}.md', ['{preapost}.md', '{prebpost}.md']],
+    ['{{a,b}}.md', ['{a}.md', '{b}.md']],
+    ['{draft{nope}{a,b}}.md', ['{draft{nope}a}.md', '{draft{nope}b}.md']],
+  ])('expands a nested group inside non-expanding braces in %s', (pattern, filenames) => {
+    for (const filename of filenames) {
+      fs.writeFileSync(path.join(tempDir, filename), 'content');
+    }
+    fs.writeFileSync(path.join(tempDir, pattern), 'unexpanded');
+
+    expect(resolveArtifactOutputs(tempDir, pattern)).toEqual(
+      filenames.map((filename) => canonical(path.join(tempDir, filename)))
+    );
+  });
+
+  it('keeps a brace group literal when neither it nor its nested groups expand', () => {
+    const literalPath = path.join(tempDir, 'notes-{prefix{draft}}-a.md');
+    fs.writeFileSync(literalPath, 'content');
+    fs.writeFileSync(path.join(tempDir, 'notes-{prefix{draft}}-b.md'), 'content');
+    fs.writeFileSync(path.join(tempDir, 'notes-{prefixdraft}-a.md'), 'stripped');
+    fs.writeFileSync(path.join(tempDir, '{prefix{draft}}.md'), 'content');
+
+    expect(resolveArtifactOutputs(tempDir, 'notes-{prefix{draft}}-{a,b}.md')).toEqual([
+      canonical(literalPath),
+      canonical(path.join(tempDir, 'notes-{prefix{draft}}-b.md')),
+    ]);
+    expect(resolveArtifactOutputs(tempDir, '{prefix{draft}}.md')).toEqual([
+      canonical(path.join(tempDir, '{prefix{draft}}.md')),
+    ]);
+  });
+
   it('resolves a brace range after a literal brace group', () => {
     const filenames = [1, 2, 3, 4].map((index) => `report-{draft}-${index}.md`);
     for (const filename of filenames) {
@@ -272,6 +314,119 @@ describe('artifact-graph/outputs', () => {
     expect(artifactOutputExists(tempDir, 'file-{1..3}.md')).toBe(true);
   });
 
+  it('rejects brace nesting deeper than any artifact pattern needs before it can overflow', () => {
+    const fileA = path.join(tempDir, 'a.md');
+    fs.writeFileSync(fileA, 'content');
+    const nested = (depth: number) => `${'{a,'.repeat(depth)}b${'}'.repeat(depth)}.md`;
+    const globSpy = vi.mocked(globby.globSync);
+
+    expect(resolveArtifactOutputs(tempDir, nested(16))).toEqual([canonical(fileA)]);
+    globSpy.mockClear();
+    expect(() => resolveArtifactOutputs(tempDir, nested(17))).toThrow(
+      'Artifact output pattern nests braces more than 16 levels deep'
+    );
+    // A pattern deep enough to crash braces is also too long for the filesystem;
+    // the guard must still be the error the user sees.
+    expect(() => resolveArtifactOutputs(tempDir, nested(4000))).toThrow(
+      'Artifact output pattern nests braces more than 16 levels deep'
+    );
+    // The error quotes only the start of a pattern that long.
+    expect(() => resolveArtifactOutputs(tempDir, nested(4000))).toThrow(
+      `16 levels deep: ${nested(4000).slice(0, 80)}...`
+    );
+    expect(() => resolveArtifactOutputs(tempDir, nested(4000))).not.toThrow(nested(4000));
+    expect(() => resolveArtifactOutputs(tempDir, nested(4000))).not.toThrow(
+      /Maximum call stack size exceeded/u
+    );
+    expect(globSpy).not.toHaveBeenCalled();
+    globSpy.mockRestore();
+  });
+
+  it('rejects a brace pattern that is wide rather than deep before it exhausts the heap', () => {
+    // Nesting depth is 1 here, so the depth guard never fires. `{a,b}` repeated
+    // 20 times is 1,048,576 patterns and crashed the expander with
+    // "JavaScript heap out of memory"; fast-glob compiled it to a regex instead.
+    const wide = (groups: number) => `${'{a,b}'.repeat(groups)}.md`;
+    const globSpy = vi.mocked(globby.globSync);
+
+    expect(() => resolveArtifactOutputs(tempDir, wide(20))).toThrow(
+      'Artifact output pattern expands to more than 1024 patterns'
+    );
+    // The error quotes only the start of a pattern that long.
+    expect(() => resolveArtifactOutputs(tempDir, wide(20))).toThrow(
+      `1024 patterns: ${wide(20).slice(0, 80)}...`
+    );
+    // A range is bounded by the same budget. brace-expansion caps itself at
+    // 100,000 results, so the budget is passed down as its `max` and the
+    // allocation stops just past 1024 instead.
+    expect(() => resolveArtifactOutputs(tempDir, 'file-{1..200000}.md')).toThrow(
+      'Artifact output pattern expands to more than 1024 patterns'
+    );
+    // Far past brace-expansion's own cap, so only our `max` can stop it early.
+    expect(() => resolveArtifactOutputs(tempDir, 'file-{1..1000000000}.md')).toThrow(
+      'Artifact output pattern expands to more than 1024 patterns'
+    );
+    expect(globSpy).not.toHaveBeenCalled();
+    globSpy.mockRestore();
+  });
+
+  it('still resolves the widest pattern inside the expansion budget', () => {
+    // 2^10 = 1024 alternatives: at the budget, not over it.
+    const file = path.join(tempDir, `${'a'.repeat(10)}.md`);
+    fs.writeFileSync(file, 'content');
+
+    expect(resolveArtifactOutputs(tempDir, `${'{a,b}'.repeat(10)}.md`)).toEqual([canonical(file)]);
+  });
+
+  it('rejects an absolute pattern before globbing, however little it matches', () => {
+    // fast-glob's generateTasks reported `/etc` as the task base, so the
+    // containment check rejected the pattern. A base that silently drops the
+    // leading slash resolves inside the change directory and lets the glob read
+    // a directory the change does not own.
+    const globSpy = vi.mocked(globby.globSync);
+
+    expect(() => resolveArtifactOutputs(tempDir, '/etc/openspec-nope-*.md')).toThrow(
+      /outside the allowed directory/u
+    );
+    expect(() => resolveArtifactOutputs(tempDir, '/openspec-nope-*.md')).toThrow(
+      /outside the allowed directory/u
+    );
+    expect(globSpy).not.toHaveBeenCalled();
+    globSpy.mockRestore();
+  });
+
+  it('keeps a control character in a filename literal instead of reading it as a brace', () => {
+    // The expander parks a non-expanding brace group on a sentinel. A
+    // single-character sentinel is a legal filename character on POSIX, so a
+    // pattern containing one came back out as `{` or `}` and matched the wrong
+    // file. The decoy is what the bug returned, and it must never match on any
+    // platform; Windows forbids U+0001 in a filename, so there the real file
+    // cannot exist and the pattern has to come back empty.
+    fs.writeFileSync(path.join(tempDir, 'x}y.md'), 'wrong');
+    const literal = path.join(tempDir, 'x\u0001y.md');
+    const literalIsCreatable = process.platform !== 'win32';
+    if (literalIsCreatable) fs.writeFileSync(literal, 'content');
+
+    expect(resolveArtifactOutputs(tempDir, 'x\u0001y*.md')).toEqual(
+      literalIsCreatable ? [canonical(literal)] : []
+    );
+  });
+
+  it.each([
+    ['a bracket', (depth: number) => `*${'{a,[}]'.repeat(depth)}${'}'.repeat(depth)}`],
+    ['a quote', (depth: number) => `*${'{a,"}"'.repeat(depth)}${'}'.repeat(depth)}`],
+    ['an open parenthesis', (depth: number) => `*${'{a,(}'.repeat(depth)}${')}'.repeat(depth)}`],
+    ['parentheses alone', (depth: number) => `*{a,b}${'('.repeat(depth)}${')'.repeat(depth)}`],
+  ])('counts nesting the braces parser sees past %s', (_label, nested) => {
+    const globSpy = vi.mocked(globby.globSync);
+
+    expect(() => resolveArtifactOutputs(tempDir, nested(17))).toThrow(
+      'Artifact output pattern nests braces more than 16 levels deep'
+    );
+    expect(globSpy).not.toHaveBeenCalled();
+    globSpy.mockRestore();
+  });
+
   it.each(['@(proposal|design).md', '+(proposal|design).md'])('supports extglob %s', (pattern) => {
     const proposalPath = path.join(tempDir, 'proposal.md');
     fs.writeFileSync(proposalPath, 'content');

test/core/cli-is-json-run.test.ts

@@ -1,7 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import { Command, Option } from 'commander';
 
-import { isJsonRun, isCompletionRun, shouldDeferCompletionTip } from '../../src/cli/index.js';
+import {
+  isJsonRun,
+  isCompletionRun,
+  isTabCompletionRun,
+  shouldDeferCompletionTip,
+} from '../../src/cli/index.js';
 
 /**
  * Reproduce the three ways `--json` reaches a command in the real CLI, so a
@@ -106,6 +111,23 @@ describe('isCompletionRun', () => {
   );
 });
 
+describe('isTabCompletionRun', () => {
+  /**
+   * Only the hidden resolver skips telemetry. The user-facing `completion`
+   * commands are run by a person and are tracked like any other command.
+   */
+  it('matches the hidden resolver', () => {
+    expect(isTabCompletionRun('__complete')).toBe(true);
+  });
+
+  it.each(['completion', 'completion:install', 'completion:generate', 'list'])(
+    'does not match "%s"',
+    (commandPath) => {
+      expect(isTabCompletionRun(commandPath)).toBe(false);
+    }
+  );
+});
+
 describe('shouldDeferCompletionTip', () => {
   /**
    * The tip must survive every run that cannot display it. Deferring (rather

test/core/commands/spec-command.security.test.ts

@@ -6,13 +6,17 @@ import { SpecCommand } from '../../../src/commands/spec.js';
 
 describe('SpecCommand path boundaries', () => {
   let tempDir: string;
+  let projectDir: string;
   let originalCwd: string;
 
   beforeEach(async () => {
     originalCwd = process.cwd();
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-spec-command-security-'));
-    await fs.mkdir(path.join(tempDir, 'openspec', 'specs'), { recursive: true });
-    process.chdir(tempDir);
+    // A spec file may link to another file in the same project, so the escape
+    // these cases guard against is one that leaves the project entirely.
+    projectDir = path.join(tempDir, 'repo');
+    await fs.mkdir(path.join(projectDir, 'openspec', 'specs'), { recursive: true });
+    process.chdir(projectDir);
   });
 
   afterEach(async () => {
@@ -31,10 +35,10 @@ describe('SpecCommand path boundaries', () => {
   });
 
   it.skipIf(process.platform === 'win32')(
-    'rejects a spec file symlink that leaves the specs root',
+    'rejects a spec file symlink that leaves the project',
     async () => {
       const outsideSpec = path.join(tempDir, 'outside.md');
-      const linkedSpec = path.join(tempDir, 'openspec', 'specs', 'linked', 'spec.md');
+      const linkedSpec = path.join(projectDir, 'openspec', 'specs', 'linked', 'spec.md');
       await fs.writeFile(outsideSpec, '# Outside sentinel');
       await fs.mkdir(path.dirname(linkedSpec), { recursive: true });
       await fs.symlink(outsideSpec, linkedSpec);
@@ -45,6 +49,28 @@ describe('SpecCommand path boundaries', () => {
     }
   );
 
+  it.skipIf(process.platform === 'win32')(
+    'shows a spec.md linked to a file elsewhere in the project',
+    async () => {
+      // The reported layout (#2100): the spec lives beside the product docs it
+      // belongs to and openspec/specs/<capability>/spec.md links to it.
+      const docsSpec = path.join(projectDir, 'docs', 'auth', 'specs', 'login.md');
+      await fs.mkdir(path.dirname(docsSpec), { recursive: true });
+      await fs.writeFile(
+        docsSpec,
+        '# login\n\n## Purpose\n\nUsers sign in.\n\n## Requirements\n'
+      );
+      const linkedSpec = path.join(projectDir, 'openspec', 'specs', 'login', 'spec.md');
+      await fs.mkdir(path.dirname(linkedSpec), { recursive: true });
+      await fs.symlink(
+        path.relative(path.dirname(linkedSpec), docsSpec),
+        linkedSpec
+      );
+
+      await expect(new SpecCommand().show('login')).resolves.toBeUndefined();
+    }
+  );
+
   it.skipIf(process.platform === 'win32')(
     'allows a linked capability directory as its own trust root',
     async () => {
@@ -56,7 +82,7 @@ describe('SpecCommand path boundaries', () => {
       );
       await fs.symlink(
         sharedCapability,
-        path.join(tempDir, 'openspec', 'specs', 'shared')
+        path.join(projectDir, 'openspec', 'specs', 'shared')
       );
 
       await expect(new SpecCommand().show('shared')).resolves.toBeUndefined();
@@ -66,7 +92,7 @@ describe('SpecCommand path boundaries', () => {
   it.skipIf(process.platform === 'win32')(
     'allows a spec file symlink elsewhere in the specs root',
     async () => {
-      const specsDir = path.join(tempDir, 'openspec', 'specs');
+      const specsDir = path.join(projectDir, 'openspec', 'specs');
       const sharedSpec = path.join(specsDir, 'shared.md');
       const linkedSpec = path.join(specsDir, 'linked', 'spec.md');
       await fs.writeFile(

test/core/completions/generators/zsh-generator.test.ts

@@ -421,5 +421,35 @@ describe('ZshGenerator', () => {
       expect(script).toContain('_openspec_view() {');
       expect(script).toContain('_arguments');
     });
+
+    // The bash, fish and powershell generator tests each pin this redirect;
+    // zsh was the one that did not, and it has the most `__complete` call
+    // sites and is the default shell on macOS. The redirect is what keeps a
+    // Tab press silent, so anything `__complete` ever writes to stderr - a
+    // deprecation notice, a Node experimental warning - would otherwise print
+    // into the middle of the user's prompt with no test objecting.
+    it('sends every __complete call stderr to /dev/null', () => {
+      const commands: CommandDefinition[] = [
+        { name: 'archive', description: 'Archive a change', flags: [] },
+        { name: 'show', description: 'Show an item', flags: [] },
+        { name: 'new', description: 'Create a change', flags: [] },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('openspec __complete changes 2>/dev/null');
+      expect(script).toContain('openspec __complete specs 2>/dev/null');
+      expect(script).toContain('openspec __complete schemas 2>/dev/null');
+      // No invocation may survive a template edit that drops a redirect. Only
+      // real call sites count: the script also explains itself in comments
+      // that name the command without running it.
+      const invocations = script
+        .split('\n')
+        .filter((line) => line.includes('openspec __complete') && !line.trim().startsWith('#'));
+      expect(invocations.length).toBeGreaterThan(0);
+      for (const line of invocations) {
+        expect(line, `unredirected __complete call: ${line.trim()}`).toContain('2>/dev/null');
+      }
+    });
   });
 });

test/core/parsers/unapplied-content.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { parseDeltaSpec } from '../../../src/core/parsers/requirement-blocks.js';
+import { buildUpdatedSpec, findSpecUpdates } from '../../../src/core/specs-apply.js';
+import { Validator } from '../../../src/core/validation/validator.js';
+
+// Archive carries requirement blocks only. Text written anywhere else in a delta
+// used to vanish with no warning while `validate --strict` passed.
+const DELTA = [
+  '# billing delta', // 1 - a title is not reported
+  'Context above the first section.', // 2
+  '## ADDED Requirements', // 3
+  'Intro prose.', // 4
+  '### Requirement: Invoices', // 5
+  'The system SHALL generate invoices.', // 6
+  '', // 7
+  '#### Scenario: Period closes', // 8
+  '- **WHEN** a', // 9
+  '- **THEN** b', // 10
+  'Trailing note, carried with the block.', // 11
+  '## Acceptance Criteria', // 12
+  '- Invoices reconcile.', // 13
+].join('\n');
+
+describe('parseDeltaSpec unappliedContent', () => {
+  it('reports text above the first section, leading prose, and non-delta sections', () => {
+    expect(parseDeltaSpec(DELTA).unappliedContent).toEqual([
+      { section: null, line: 2 },
+      { section: 'ADDED Requirements', line: 4 },
+      { section: 'Acceptance Criteria', line: 12 },
+    ]);
+  });
+
+  it('does not exempt a commented-out Purpose, and honours the --!> terminator', () => {
+    const plan = parseDeltaSpec(
+      ['<!--', '## Purpose', '--!>', 'Real prose.', '## ADDED Requirements', '### Requirement: A', 'a', '## Notes', 'n'].join(
+        '\n'
+      )
+    );
+    expect(plan.unappliedContent).toEqual([
+      { section: 'Purpose', line: 2 },
+      { section: 'Notes', line: 8 },
+    ]);
+  });
+
+  // The merge splits sections on every `## ` line outside a fence, comment or not.
+  // Reading boundaries from comment-masked lines disagreed with it both ways.
+  it('reads section boundaries exactly as the merge does', () => {
+    // `<!--` in inline code and a later `-->` are not a comment to the merge;
+    // masking across them hid `## ADDED Requirements` and blamed a carried requirement.
+    const inlineOpener = parseDeltaSpec(
+      ['# Delta: strip `<!--` openers', '## ADDED Requirements', '### Requirement: A', 'Flow: ingest --> render', 'The system SHALL a.'].join('\n')
+    );
+    expect(inlineOpener.added.map((b) => b.name)).toEqual(['A']);
+    expect(inlineOpener.unappliedContent).toEqual([]);
+
+    // A header inside a comment is still a section to the merge, so the
+    // requirement after the comment is carried, not text above the first section.
+    const commentedHeader = parseDeltaSpec(
+      ['<!-- add requirements below', '## ADDED Requirements', '-->', '### Requirement: A', 'The system SHALL a.'].join('\n')
+    );
+    expect(commentedHeader.added.map((b) => b.name)).toEqual(['A']);
+    expect(commentedHeader.unappliedContent).toEqual([]);
+
+    // ...and text after a commented-out `## Notes` is dropped by the merge.
+    const commentedNotes = parseDeltaSpec(
+      ['## ADDED Requirements', '### Requirement: A', 'a', '<!--', '## Notes', '-->', 'Dropped.'].join('\n')
+    );
+    expect(commentedNotes.added[0].raw).not.toContain('Dropped.');
+    expect(commentedNotes.unappliedContent).toEqual([{ section: 'Notes', line: 5 }]);
+  });
+
+  it('does not let a `<!--` inside a code fence hide later sections', () => {
+    const plan = parseDeltaSpec(
+      ['## ADDED Requirements', '### Requirement: A', 'a', '```html', '<!-- unterminated sample', '```', '## Notes', 'Dropped.'].join('\n')
+    );
+    expect(plan.unappliedContent).toEqual([{ section: 'Notes', line: 7 }]);
+  });
+
+  it('ignores Purpose, REMOVED/RENAMED bodies, HTML comments, fences, and stray ### headers', () => {
+    const plan = parseDeltaSpec(
+      [
+        '<!--',
+        'Multi-line instructions.',
+        '-->',
+        '## Purpose',
+        'A new capability.',
+        '## ADDED Requirements',
+        '<!-- add requirements below -->',
+        '### Documentation Requirements',
+        '### Requirement: A',
+        'a',
+        '```markdown',
+        '## Notes',
+        '```',
+        '## REMOVED Requirements',
+        '### Requirement: B',
+        '**Reason**: obsolete',
+        '## RENAMED Requirements',
+        '- FROM: `### Requirement: C`',
+        '- TO: `### Requirement: D`',
+      ].join('\n')
+    );
+    expect(plan.unappliedContent).toEqual([]);
+  });
+});
+
+describe('archive and validate report unapplied content', () => {
+  let tempDir: string;
+  let changeDir: string;
+  let specsRoot: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-unapplied-'));
+    specsRoot = path.join(tempDir, 'openspec', 'specs');
+    changeDir = path.join(tempDir, 'openspec', 'changes', 'c');
+    await fs.mkdir(path.join(changeDir, 'specs', 'billing'), { recursive: true });
+    await fs.mkdir(specsRoot, { recursive: true });
+    await fs.writeFile(path.join(changeDir, 'specs', 'billing', 'spec.md'), DELTA);
+  });
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('archive warns and still carries only the requirement', async () => {
+    const [update] = await findSpecUpdates(changeDir, specsRoot);
+    const built = await buildUpdatedSpec(update, 'c', { silent: true });
+
+    expect(built.warnings).toContain(
+      'billing - section "## Acceptance Criteria" (line 12) is not carried into the main spec.'
+    );
+    expect(built.rebuilt).toContain('### Requirement: Invoices');
+    expect(built.rebuilt).not.toContain('Acceptance Criteria');
+  });
+
+  it('validate warns, which fails --strict', async () => {
+    const report = await new Validator(true).validateChangeDeltaSpecs(changeDir);
+    const lost = report.issues.filter((issue) => /not carried into the main spec/.test(issue.message));
+
+    expect(lost.map((issue) => [issue.level, issue.line])).toEqual([
+      ['WARNING', 2],
+      ['WARNING', 4],
+      ['WARNING', 12],
+    ]);
+    expect(report.valid).toBe(false);
+  });
+});

test/core/specs-apply.project-linked-spec.test.ts

@@ -0,0 +1,232 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  buildUpdatedSpec,
+  findSpecUpdates,
+  writeUpdatedSpec,
+} from '../../src/core/specs-apply.js';
+
+const itWithSymlinks = it.skipIf(process.platform === 'win32');
+
+/**
+ * A project may keep its main specs beside the product documentation they
+ * belong to and link `openspec/specs/<capability>/spec.md` to them, so the
+ * docs and OpenSpec read and write the same bytes (#2100). The merge has to
+ * write through such a link, and still refuse one that leaves the project.
+ */
+describe('a spec.md linked to a file elsewhere in the project', () => {
+  let tempDir: string;
+  let projectDir: string;
+  let changeDir: string;
+  let mainSpecsDir: string;
+  let docsSpec: string;
+  let linkedSpec: string;
+
+  const DELTA = [
+    '## ADDED Requirements',
+    '',
+    '### Requirement: Second factor',
+    'The system SHALL require a second factor.',
+    '',
+    '#### Scenario: Prompted',
+    '- **WHEN** a user signs in',
+    '- **THEN** a second factor is requested',
+    '',
+  ].join('\n');
+
+  const MAIN_SPEC = [
+    '# login Specification',
+    '',
+    '## Purpose',
+    'Users sign in with their credentials to reach their account.',
+    '',
+    '## Requirements',
+    '',
+    '### Requirement: Sign in',
+    'The system SHALL let a user sign in with valid credentials.',
+    '',
+    '#### Scenario: Valid credentials',
+    '- **WHEN** the user submits valid credentials',
+    '- **THEN** the user is signed in',
+    '',
+  ].join('\n');
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-project-linked-spec-'));
+    projectDir = path.join(tempDir, 'repo');
+    changeDir = path.join(projectDir, 'openspec', 'changes', 'add-mfa');
+    mainSpecsDir = path.join(projectDir, 'openspec', 'specs');
+    docsSpec = path.join(projectDir, 'docs', 'auth', 'specs', 'login.md');
+    linkedSpec = path.join(mainSpecsDir, 'login', 'spec.md');
+
+    await fs.mkdir(path.join(changeDir, 'specs', 'login'), { recursive: true });
+    await fs.writeFile(path.join(changeDir, 'specs', 'login', 'spec.md'), DELTA);
+    await fs.mkdir(path.dirname(docsSpec), { recursive: true });
+    await fs.writeFile(docsSpec, MAIN_SPEC);
+    await fs.mkdir(path.dirname(linkedSpec), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  itWithSymlinks('merges through the link and leaves the link in place', async () => {
+    await fs.symlink(path.relative(path.dirname(linkedSpec), docsSpec), linkedSpec);
+
+    const warnings: string[] = [];
+    const onWarning = (warning: Error) => warnings.push(warning.message);
+    process.on('warning', onWarning);
+    let updates;
+    try {
+      updates = await findSpecUpdates(changeDir, mainSpecsDir);
+      // process.emitWarning dispatches on the next tick.
+      await new Promise((resolve) => setImmediate(resolve));
+    } finally {
+      process.off('warning', onWarning);
+    }
+
+    expect(updates).toHaveLength(1);
+    const [update] = updates;
+    // The link path is what the CLI reports, and the write goes through it.
+    // Rebased onto the canonical specs root, so /var and /private/var agree.
+    const canonicalLinkedSpec = path.join(
+      await fs.realpath(path.dirname(linkedSpec)),
+      'spec.md'
+    );
+    expect(update.target).toBe(canonicalLinkedSpec);
+    expect(update.exists).toBe(true);
+    // Nothing leaves the project, so there is nothing to announce.
+    expect(warnings).toEqual([]);
+
+    const built = await buildUpdatedSpec(update, 'add-mfa', { silent: true });
+    await writeUpdatedSpec(update, built.rebuilt, built.counts, { silent: true });
+
+    // The file the docs own received the merge, and kept what it already had.
+    const merged = await fs.readFile(docsSpec, 'utf-8');
+    expect(merged).toContain('Second factor');
+    expect(merged).toContain('Sign in');
+    expect((await fs.lstat(linkedSpec)).isSymbolicLink()).toBe(true);
+  });
+
+  itWithSymlinks('refuses a link that leaves the project', async () => {
+    const outsideSpec = path.join(tempDir, 'outside.md');
+    await fs.writeFile(outsideSpec, MAIN_SPEC);
+    await fs.symlink(outsideSpec, linkedSpec);
+
+    await expect(findSpecUpdates(changeDir, mainSpecsDir)).rejects.toThrow(
+      'Path is outside the allowed directory'
+    );
+    await expect(fs.readFile(outsideSpec, 'utf-8')).resolves.toBe(MAIN_SPEC);
+  });
+
+  itWithSymlinks(
+    'refuses a link repointed out of the project between resolve and write',
+    async () => {
+      await fs.symlink(path.relative(path.dirname(linkedSpec), docsSpec), linkedSpec);
+      const [update] = await findSpecUpdates(changeDir, mainSpecsDir);
+      const built = await buildUpdatedSpec(update, 'add-mfa', { silent: true });
+
+      // The link now points out of the project, after the path was resolved and
+      // the merge was built. The recheck before the write has to catch it.
+      const outsideSpec = path.join(tempDir, 'outside.md');
+      await fs.writeFile(outsideSpec, 'outside sentinel');
+      await fs.rm(linkedSpec);
+      await fs.symlink(outsideSpec, linkedSpec);
+
+      await expect(
+        writeUpdatedSpec(update, built.rebuilt, built.counts, { silent: true })
+      ).rejects.toThrow('Path is outside the allowed directory');
+      await expect(fs.readFile(outsideSpec, 'utf-8')).resolves.toBe('outside sentinel');
+    }
+  );
+
+  itWithSymlinks(
+    'refuses a link repointed out of the project between resolve and read',
+    async () => {
+      await fs.symlink(path.relative(path.dirname(linkedSpec), docsSpec), linkedSpec);
+      const [update] = await findSpecUpdates(changeDir, mainSpecsDir);
+
+      const outsideSpec = path.join(tempDir, 'outside.md');
+      await fs.writeFile(outsideSpec, 'outside sentinel');
+      await fs.rm(linkedSpec);
+      await fs.symlink(outsideSpec, linkedSpec);
+
+      await expect(buildUpdatedSpec(update, 'add-mfa', { silent: true })).rejects.toThrow(
+        'Path is outside the allowed directory'
+      );
+    }
+  );
+
+  itWithSymlinks(
+    'cannot be redirected by a link repointed while the write is in flight',
+    async () => {
+      await fs.symlink(path.relative(path.dirname(linkedSpec), docsSpec), linkedSpec);
+      const [update] = await findSpecUpdates(changeDir, mainSpecsDir);
+      const built = await buildUpdatedSpec(update, 'add-mfa', { silent: true });
+
+      const outsideSpec = path.join(tempDir, 'outside.md');
+      await fs.writeFile(outsideSpec, 'outside sentinel');
+
+      // `beforeMutate` runs after the containment check, so it is the one
+      // window a swap could still use.
+      await expect(
+        writeUpdatedSpec(update, built.rebuilt, built.counts, {
+          silent: true,
+          beforeMutate: async () => {
+            await fs.rm(linkedSpec);
+            await fs.symlink(outsideSpec, linkedSpec);
+          },
+        })
+      ).rejects.toThrow();
+
+      // Nothing was written: not to where the link now points, and not to the
+      // file that was verified either, since the target is no longer it.
+      await expect(fs.readFile(outsideSpec, 'utf-8')).resolves.toBe('outside sentinel');
+      await expect(fs.readFile(docsSpec, 'utf-8')).resolves.not.toContain('Second factor');
+    }
+  );
+
+  itWithSymlinks(
+    'refuses an ordinary target replaced by a link while the write is in flight',
+    async () => {
+      // Not specific to the linked layout: the canonical file at the end of the
+      // chain can be swapped for a link too, so the re-check has to catch that
+      // for a plain `openspec/specs/<capability>/spec.md` as well.
+      await fs.writeFile(linkedSpec, MAIN_SPEC);
+      const [update] = await findSpecUpdates(changeDir, mainSpecsDir);
+      const built = await buildUpdatedSpec(update, 'add-mfa', { silent: true });
+      const outsideSpec = path.join(tempDir, 'outside.md');
+      await fs.writeFile(outsideSpec, 'outside sentinel');
+
+      await expect(
+        writeUpdatedSpec(update, built.rebuilt, built.counts, {
+          silent: true,
+          beforeMutate: async () => {
+            await fs.rm(linkedSpec);
+            await fs.symlink(outsideSpec, linkedSpec);
+          },
+        })
+      ).rejects.toThrow();
+
+      await expect(fs.readFile(outsideSpec, 'utf-8')).resolves.toBe('outside sentinel');
+    }
+  );
+
+  itWithSymlinks('merges through a linked delta spec inside the project', async () => {
+    await fs.symlink(path.relative(path.dirname(linkedSpec), docsSpec), linkedSpec);
+    const sharedDelta = path.join(projectDir, 'docs', 'auth', 'deltas', 'login.md');
+    await fs.mkdir(path.dirname(sharedDelta), { recursive: true });
+    await fs.writeFile(sharedDelta, DELTA);
+    const deltaPath = path.join(changeDir, 'specs', 'login', 'spec.md');
+    await fs.rm(deltaPath);
+    await fs.symlink(path.relative(path.dirname(deltaPath), sharedDelta), deltaPath);
+
+    const [update] = await findSpecUpdates(changeDir, mainSpecsDir);
+    const built = await buildUpdatedSpec(update, 'add-mfa', { silent: true });
+
+    expect(built.rebuilt).toContain('Second factor');
+  });
+});

test/core/specs-apply.security.test.ts

@@ -12,6 +12,7 @@ const itWithSymlinks = it.skipIf(process.platform === 'win32');
 
 describe('spec apply path boundaries', () => {
   let tempDir: string;
+  let projectDir: string;
   let changeDir: string;
   let changeSpecsDir: string;
   let mainSpecsDir: string;
@@ -19,9 +20,12 @@ describe('spec apply path boundaries', () => {
 
   beforeEach(async () => {
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-spec-apply-security-'));
-    changeDir = path.join(tempDir, 'openspec', 'changes', 'test-change');
+    // A spec file may link to another file in the same project, so the escape
+    // these cases guard against is one that leaves the project entirely.
+    projectDir = path.join(tempDir, 'repo');
+    changeDir = path.join(projectDir, 'openspec', 'changes', 'test-change');
     changeSpecsDir = path.join(changeDir, 'specs');
-    mainSpecsDir = path.join(tempDir, 'openspec', 'specs');
+    mainSpecsDir = path.join(projectDir, 'openspec', 'specs');
     outsideDir = path.join(tempDir, 'outside');
     await fs.mkdir(changeSpecsDir, { recursive: true });
     await fs.mkdir(mainSpecsDir, { recursive: true });
@@ -52,7 +56,7 @@ describe('spec apply path boundaries', () => {
     return deltaPath;
   }
 
-  itWithSymlinks('rejects a delta spec symlink that leaves the change specs root', async () => {
+  itWithSymlinks('rejects a delta spec symlink that leaves the project', async () => {
     const outsideSpec = path.join(outsideDir, 'spec.md');
     await fs.writeFile(outsideSpec, 'outside sentinel');
     const linkedSpec = path.join(changeSpecsDir, 'widgets', 'spec.md');

test/core/task-checkboxes.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import fg from 'fast-glob';
+import { globSync } from 'tinyglobby';
 import { findMissingTaskCheckboxIssues } from '../../src/core/validation/task-checkboxes.js';
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -189,9 +189,10 @@ describe('findMissingTaskCheckboxIssues', () => {
   it('accepts every packaged tasks template', async () => {
     // An agent writing a task file follows these. If one ever loses its
     // checkboxes, every change built from it starts life counting zero tasks.
-    const templates = await fg('schemas/*/templates/tasks.md', {
+    const templates = globSync('schemas/*/templates/tasks.md', {
       cwd: repoRoot,
       absolute: true,
+      expandDirectories: false,
     });
     expect(templates.length).toBeGreaterThan(0);
 

test/core/templates/glob-path-bounding.test.ts

@@ -0,0 +1,213 @@
+// Every workflow that turns a glob output into a concrete write path must keep
+// that path inside `changeRoot` (#2099). update-change always did; propose,
+// ff-change and continue-change chose a path with no containment rule, so a
+// capability path such as `../../x`, or a symlinked directory under `specs/`,
+// would be written outside the change.
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getContinueChangeSkillTemplate,
+  getExploreSkillTemplate,
+  getFfChangeSkillTemplate,
+  getOpsxContinueCommandTemplate,
+  getOpsxExploreCommandTemplate,
+  getOpsxFfCommandTemplate,
+  getOpsxProposeCommandTemplate,
+  getOpsxProposeSkillTemplate,
+  getOpsxUpdateCommandTemplate,
+  getUpdateChangeSkillTemplate,
+} from '../../../src/core/templates/skill-templates.js';
+import { resolveOptionalWorkflows } from '../../../src/core/templates/optional-workflow.js';
+import { ALL_WORKFLOWS } from '../../../src/core/profiles.js';
+
+const withAllWorkflows = (body: string) =>
+  resolveOptionalWorkflows(body, new Set<string>(ALL_WORKFLOWS));
+
+/** Lines that tell the agent to pick a concrete path for a glob output. */
+const PATH_CHOICE = /choose a concrete path/i;
+
+/**
+ * The containment rule for a write that may land on an existing file. A
+ * destination that is itself a symlink to a file outside `changeRoot` passes a
+ * parent-only check, so the file is resolved too.
+ */
+const BOUND =
+  'remains inside `changeRoot` after resolving symlinks, both in its parent directories and in the file itself if it already exists';
+
+/**
+ * update-change creates its file with an operation that fails if the target
+ * exists - a symlink included - so resolving the parents is enough there.
+ */
+const CREATE_ONLY_BOUND =
+  'remains inside `changeRoot` after resolving any symlinked parent directories';
+
+const boundFor = (label: string) => (label.startsWith('update-change') ? CREATE_ONLY_BOUND : BOUND);
+
+/** Every surface that writes glob artifacts, skill and slash-command alike. */
+const SURFACES: Array<[label: string, body: string]> = [
+  ['propose skill', withAllWorkflows(getOpsxProposeSkillTemplate().instructions)],
+  ['propose command', withAllWorkflows(getOpsxProposeCommandTemplate().content)],
+  ['ff-change skill', withAllWorkflows(getFfChangeSkillTemplate().instructions)],
+  ['ff-change command', withAllWorkflows(getOpsxFfCommandTemplate().content)],
+  ['continue-change skill', withAllWorkflows(getContinueChangeSkillTemplate().instructions)],
+  ['continue-change command', withAllWorkflows(getOpsxContinueCommandTemplate().content)],
+  ['update-change skill', withAllWorkflows(getUpdateChangeSkillTemplate().instructions)],
+  ['update-change command', withAllWorkflows(getOpsxUpdateCommandTemplate().content)],
+  ['explore skill', withAllWorkflows(getExploreSkillTemplate().instructions)],
+  ['explore command', withAllWorkflows(getOpsxExploreCommandTemplate().content)],
+];
+
+/** Where a line tells the agent to write. The bound must come before it. */
+const WRITE = /\b(?:write|Write)\b(?! anything)(?! an expected path)(?! only the missing)/;
+
+/**
+ * The bound has to be checked before the write, or an escaping path is already
+ * written by the time it is verified. A line with no write (update-change
+ * writes in a later step) only needs the bound.
+ */
+function expectBoundBeforeWrite(label: string, line: string): void {
+  const boundAt = line.indexOf(boundFor(label));
+  expect(boundAt, label).toBeGreaterThanOrEqual(0);
+  const writeAt = line.search(WRITE);
+  if (writeAt !== -1) {
+    expect(writeAt, `${label}: writes before checking the bound`).toBeGreaterThan(boundAt);
+    expect(line, `${label}: no instruction to refuse an escaping path`).toContain(
+      'stop and tell the user'
+    );
+  }
+}
+
+/** Every place a body hands artifact creation to another skill or command. */
+const DELEGATION = /delegates creation/g;
+
+/**
+ * A delegated writer is a write too. It may run only after the path it writes
+ * to has been chosen and checked, and only if it can write exactly there.
+ * Returns each delegation as [offset, the sentence that states it].
+ */
+function delegations(body: string): Array<[number, string]> {
+  return [...body.matchAll(DELEGATION)].map((match) => {
+    const start = match.index ?? 0;
+    const end = body.slice(start).search(/[.\n]/);
+    return [start, body.slice(start, end === -1 ? undefined : start + end)];
+  });
+}
+
+describe('glob output paths stay inside changeRoot (#2099)', () => {
+  it.each(SURFACES)('%s bounds every concrete-path choice', (label, body) => {
+    const choices = body.split('\n').filter((line) => PATH_CHOICE.test(line));
+
+    expect(choices, `${label}: no concrete-path line found`).toHaveLength(1);
+    expectBoundBeforeWrite(label, choices[0]);
+  });
+
+  it.each(SURFACES)('%s chooses and checks the path before any delegated writer runs', (label, body) => {
+    const choiceAt = body.search(PATH_CHOICE);
+    const found = delegations(body);
+    expect(found.length, `${label}: no delegated-creation rule found`).toBeGreaterThan(0);
+
+    for (const [at, sentence] of found) {
+      // Bound to one path, and refuses rather than letting it write elsewhere.
+      expect(sentence, label).toMatch(/only if it can/);
+      expect(sentence, label).toMatch(/stop/);
+      // The creation step's delegation comes after the choice it depends on.
+      // The only one allowed earlier is continue-change's backfill, which
+      // names the path its own preceding bullet checked.
+      if (at < choiceAt) {
+        expect(sentence, `${label}: delegates before choosing the path`).toContain(
+          'its checked path'
+        );
+      }
+    }
+    expect(
+      found.some(([at]) => at > choiceAt),
+      `${label}: the creation step does not bound its delegated writer`
+    ).toBe(true);
+  });
+
+  // A delegated writer has already created the artifact; writing the template
+  // over it afterwards would replace what it made.
+  it.each(SURFACES.filter(([label]) => !label.startsWith('update-change')))(
+    '%s writes the template only when creation was not delegated',
+    (label, body) => {
+      const templateWrite = /\b[Ww]rite (?:it|the file|the artifact) to that output path/u;
+      const lines = body.split('\n');
+      let writes = 0;
+
+      lines.forEach((line, index) => {
+        // Judged sentence by sentence: explore states both branches in one
+        // paragraph, and the delegation sentence names the same path for the
+        // delegated writer.
+        for (const sentence of line.split(/(?<=\.)\s+(?=[A-Z])/u)) {
+          if (!templateWrite.test(sentence) || sentence.includes('delegates creation')) continue;
+          writes++;
+          if (/otherwise/iu.test(sentence.slice(0, sentence.search(templateWrite)))) continue;
+          // Otherwise nested under a bullet that opens the Otherwise branch.
+          const indent = line.search(/\S/u);
+          const parent = lines
+            .slice(0, index)
+            .reverse()
+            .find((candidate) => candidate.trim() !== '' && candidate.search(/\S/u) < indent);
+          expect(parent, `${label}: template write outside the Otherwise branch`).toMatch(
+            /^\s*- Otherwise/u
+          );
+        }
+      });
+      expect(writes, `${label}: no template write found`).toBeGreaterThan(0);
+    }
+  );
+
+  it.each([
+    ['continue-change skill', withAllWorkflows(getContinueChangeSkillTemplate().instructions)],
+    ['continue-change command', withAllWorkflows(getOpsxContinueCommandTemplate().content)],
+  ])('%s verifies the output after either creation branch', (label, body) => {
+    const lines = body.split('\n');
+    const delegation = lines.findIndex((line) => line.includes('delegates creation to a specific skill'));
+    const verify = lines.findIndex((line) =>
+      line.includes('Either way, verify the artifact file exists at that output path')
+    );
+    expect(verify, label).toBeGreaterThan(delegation);
+    // Same depth as the two branches, so it runs after whichever was taken.
+    expect(lines[verify].search(/\S/u), label).toBe(lines[delegation].search(/\S/u));
+  });
+
+  it.each(SURFACES)('%s never targets the glob itself', (label, body) => {
+    // A glob is a pattern, not a file: nothing may be written to, or verified
+    // at, `resolvedOutputPath` unless it is a concrete path.
+    expect(body, label).not.toContain('exists at `resolvedOutputPath`');
+    expect(body, label).not.toContain('write it to `resolvedOutputPath`');
+  });
+
+  it.each(SURFACES)('%s restates delegation only with the same bound', (label, body) => {
+    // The artifact-creation guidelines repeat the delegation rule where agents
+    // skim; a bare "invoke it instead" there would undo the ordering above.
+    for (const line of body
+      .split('\n')
+      .filter((candidate) => candidate.includes('directs you to use a specific skill or command'))) {
+      expect(line, label).toContain('only once you have chosen and checked the output path');
+    }
+  });
+
+  // continue-change alone backfills a half-written glob artifact: it compares
+  // expected paths against what exists instead of choosing a new one, so the
+  // bound has to sit on that bullet too.
+  it.each([
+    ['continue-change skill', withAllWorkflows(getContinueChangeSkillTemplate().instructions)],
+    ['continue-change command', withAllWorkflows(getOpsxContinueCommandTemplate().content)],
+  ])('%s bounds the partly-written-artifact check', (label, body) => {
+    const bullets = body
+      .split('\n')
+      .filter((line) => line.includes('resolve each expected path against `changeRoot`'));
+
+    expect(bullets, `${label}: partial-artifact bullet missing`).toHaveLength(1);
+    expect(bullets[0], label).toContain(BOUND);
+    // The write is the next bullet, so the refusal has to sit there.
+    const lines = body.split('\n');
+    const next = lines[lines.indexOf(bullets[0]) + 1];
+    expect(next, label).toContain('Never write an expected path that fails that check');
+    expect(next.indexOf('Never write'), label).toBeLessThan(next.indexOf('write only the missing'));
+    // A delegated writer filling the gap is held to the same checked paths.
+    expect(next, label).toContain('invoke it only if it can write each file to its checked path');
+  });
+});

test/core/templates/propose.test.ts

@@ -678,7 +678,7 @@ describe('artifact loop guards (propose and ff)', () => {
   it('tells the agent how to resolve a glob output path', () => {
     for (const [label, body] of loopBodies) {
       expect(body, label).toContain(
-        'is a glob, follow `instruction` to choose the concrete file path'
+        'is a glob, follow `instruction` to choose a concrete path'
       );
     }
   });

test/core/templates/skill-templates-parity.test.ts

@@ -76,46 +76,46 @@ function specDrivenTitles(): Record<string, string> {
 }
 
 const EXPECTED_FUNCTION_HASHES: Record<string, string> = {
-  getExploreSkillTemplate: 'c1fddb294758004936add586f5826694cb06175cff935b75fd3a8d92332332e6',
+  getExploreSkillTemplate: '80246765b685ec1e5530e8348bde84ed2ba0a6c418c9fbcd7e9e79a638d289dd',
   getNewChangeSkillTemplate: '0e5035b7b42198afc430206a1dbc9579096650ef0813d85e837d5a6cd0b98a85',
-  getContinueChangeSkillTemplate: '32ec5965a2e90c033c9285f57a73cd6f39a31b58029d7546dba3cb6ba4c091f7',
+  getContinueChangeSkillTemplate: '2da5a24eb949f0717ffdb23c28c021ab6f73dc4beeb92ab709b8dbdac9db7355',
   getApplyChangeSkillTemplate: 'c4f02c29137e19b34bf1dc59146941b8c920214aa2cf3ce80ae7f1b982e976fc',
-  getFfChangeSkillTemplate: 'd091600476a815ba99f69b446bcd46af5bf73d1c2810215a0c6196937d019cf6',
+  getFfChangeSkillTemplate: '0eb8ddc6da710bc9ed6cd142a2eec1bec883f730125d76dc38e532bd5395bdf2',
   getSyncSpecsSkillTemplate: 'bc80fe9b07eaa289e5eb8a3ce65eb7df722a16d864e37283c678220712e4f230',
   getOnboardSkillTemplate: '84258a06c0ca88de708a23dd74e9a17efe11eff63a071b3864c781dcd5a0a4b7',
-  getOpsxExploreCommandTemplate: '5d11f8ecb4c457140a3e874a8bf7aa72674e922e698c208832b1f34d3c617719',
+  getOpsxExploreCommandTemplate: 'c0af210bc070b7ac5168523b381cb9e213e4e102205bfc26bdae15677d954ae1',
   getOpsxNewCommandTemplate: '6d504fef1e0d4ced7c423f4cc9d9d2cee11b1a6224edf685e06a3f0757e0ebff',
-  getOpsxContinueCommandTemplate: '659596cef4859162707d8acbd411afb863110f34a7b90ad037bae5eb84dd858d',
+  getOpsxContinueCommandTemplate: '9e36b758c2760fcab4dcef4677ee678eb29eac00f31de8cbc99f812a440afaaf',
   getOpsxApplyCommandTemplate: '9b733946aa7216b45d084bb5affd7071086db6f91282c3666731a17543825ff1',
-  getOpsxFfCommandTemplate: '743a7304c7efc84aa87f556154c034e1e0e561c276c51870a30ada58f33eb9af',
+  getOpsxFfCommandTemplate: '625d6a4a52adeaa16dbceff378f1d7cb07556e79b19d9af63feca5125aa4da13',
   getArchiveChangeSkillTemplate: '04a029782fc4137971fad6f54cfda3685d7e0b835b06565f9a509b4878093099',
   getBulkArchiveChangeSkillTemplate: '44dbd3c7a347e5f8339b2141393f2ac36017527cce251483fe70f2059c1e286e',
   getOpsxSyncCommandTemplate: '60550b7bb9829421656d6324a9e4c951bc912f48f88882d1a07ce7f78397a5e7',
-  getVerifyChangeSkillTemplate: '9522cdf3fd638baee6098d480445c615b908b2f35d776b2a1eebeb6e2b208480',
+  getVerifyChangeSkillTemplate: '5c188c8e94fa0d4717cc3475813017d9e0bea9c53ad1df7303d18533cc26ee7f',
   getOpsxArchiveCommandTemplate: '5d153490bf1ca24207f49856826720f793c8884a6ec15059104107b0e34ee345',
   getOpsxOnboardCommandTemplate: '0cf66e164c0e14c916c6d1ebb5d80ded07d7fb8e55d4eb34eba43e8ca9c28558',
   getOpsxBulkArchiveCommandTemplate: 'cb1d55d6ce53686bfe94be5e081c7a4d06a8e4d10b63019132df5bb3db7144cb',
-  getOpsxVerifyCommandTemplate: '62ba027d789186416620f963341129bf8f7acf956c8f5b806f78945e1109d7ab',
-  getOpsxProposeSkillTemplate: '1aa2f2eb9c8cbc4dcab9d777bf8832b92ca04f9ef91d0494f1224a566aefdfe8',
-  getOpsxProposeCommandTemplate: '3b7090ce5e79e879ab9b5bdaf4ff2b52e3c02211f71188838772d36ac337f96c',
+  getOpsxVerifyCommandTemplate: '9f3b4551a3cce3f1d1aa6c14fc595424ba22cd049326412460b30bd32e4cb0fc',
+  getOpsxProposeSkillTemplate: 'd5e0e2d675cedaffbd771892f15edd8f7f55b464ee42362b1572aa59c4c1d492',
+  getOpsxProposeCommandTemplate: 'f30af4ce5b7677bd664da71dd6d616a93278335e8828a7c3442fab59c339a11b',
   getFeedbackSkillTemplate: 'dabeb5e825b9349abc8156c3e7b8608f27987912a6d9bf47ef29addde6138133',
-  getUpdateChangeSkillTemplate: '8380139769cf9b247cb64089c07628e73923405fca4704052d52a67f35526fe8',
-  getOpsxUpdateCommandTemplate: 'ec6c8b7f3f366d65a216c4ba423bc41b8dbd18974a432186ad44e60c1891340b',
+  getUpdateChangeSkillTemplate: '14c209b8a18d1b100d372b0ef96707b70a7c64117a16309ee463f66d39180b3e',
+  getOpsxUpdateCommandTemplate: '33528a80c9436c9dad74084a37d2fce5e78e34abfb71185fa21495a4f2a8b4d3',
 };
 
 const EXPECTED_GENERATED_SKILL_CONTENT_HASHES: Record<string, string> = {
-  'openspec-explore': '7d80caf9cd25a2565ba190b1297f1631c7f2c2db5e614597b4284abc0118ea70',
+  'openspec-explore': '90a87227a7d3dca576448bb16936cede31b4e4666d35a6f0744e0b9bc628f1ac',
   'openspec-new-change': '27e09d43785953827efc9a98bb9d6cf06db48fe6abe7e1c049409fe5b5061323',
-  'openspec-continue-change': '4edf6d8b220f09146029e7671f140b7ef94a666d8e29fe7ad78ce40bc7ec9017',
+  'openspec-continue-change': 'd8859091316ad43a58cd015091454a95bf49378ec9d9117b24ab9b2396dc8303',
   'openspec-apply-change': '991a1d4687f1c8c7147d8c3b68cf14e9c515c6c53bb026356dac3b80e909b827',
-  'openspec-ff-change': 'a7ab656d46f04d45dff0c8888df4a126a2e62288b7336f7445bce4d1715055f5',
+  'openspec-ff-change': '224ff2ed2315eb23876fc4b83d796b60cf3cd05d853f2612e5b056ee7a6e93d2',
   'openspec-sync-specs': '3909936a236a21a9a6d5bf495f90b396b3b68fc9220d7b2c1894668653beb2e4',
   'openspec-archive-change': '5f0d131a885dcdcd9ba2172ea9a42bc6748125e24b8c4eecb7c86f1a4aea83af',
   'openspec-bulk-archive-change': 'd2a258055ab2f0d8086c4348d37212ebc95a5adef2d5f524db959fb93490d5c8',
-  'openspec-verify-change': 'ed7c3f0287ef246fc1c19665fd64c275259712950bfe95fb94971ddcc8fb64ac',
+  'openspec-verify-change': '9422e0afeec1dbd27c425258e67d52d73686c07765a54edeba62043c9640c8b5',
   'openspec-onboard': '6993eff867d97d485e080078f9dfb80e968e242f3b17a924eeb077715fd548fa',
-  'openspec-propose': '66e3395adf9f2d93a09e8ef1d20e4efb010e5e8d4811f2d42a9316e4d1ca5a8b',
-  'openspec-update-change': '5f4ea19aa732b33d87a2120ec393ee34578e70678d97e8c3bb10f988c00cb4d3',
+  'openspec-propose': '2bbfc169f483cbacc481bf5160aece61d5237e1bca80955f48f7e2a4814e6143',
+  'openspec-update-change': 'a6fc9d6972bfb024b91f0a01e14d8a7666ae641bcad83cfae937e41dcccc545a',
 };
 
 // Intentionally excludes getFeedbackSkillTemplate: this list only models templates
@@ -1212,15 +1212,19 @@ describe('skill templates split parity', () => {
       expect(content, variant).toContain('the authoritative guidance');
       expect(content, variant).not.toContain('Common artifact patterns');
 
-      // Delegated creation is honored at the creation step itself, and the
-      // delegated skill's output is verified rather than assumed.
+      // Delegated creation is honored at the creation step itself, held to the
+      // output path already chosen and checked (#2099), and the delegated
+      // skill's output is verified rather than assumed.
       expect(content, variant).toContain(
-        '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`'
+        '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'
+      );
+      expect(content, variant).toMatch(
+        /(?:Then|Either way,) verify the artifact file exists at that output path/u
       );
 
       // ...and restated in the artifact-creation guidelines.
       expect(content, variant).toContain(
-        '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'
       );
     }
   });
@@ -1253,6 +1257,20 @@ describe('skill templates split parity', () => {
       expect(text, variant).not.toContain('Loose prose left under `## Requirements` does NOT block');
     }
   });
+
+  // The explore capture table names spec-driven files; without this caveat an
+  // agent on a custom schema offers to write artifacts it never defines (#2084).
+  it('scopes the explore capture table to the default schema', () => {
+    const variants = [
+      ['explore skill', getExploreSkillTemplate().instructions],
+      ['explore command', getOpsxExploreCommandTemplate().content],
+    ] as const;
+    for (const [variant, text] of variants) {
+      expect(text, variant).toContain(
+        "The files below are the default spec-driven schema's. With another schema, capture each insight in whichever artifact from `artifactPaths` fits it"
+      );
+    }
+  });
 });
 
 describe('apply skill/command shared instruction core', () => {

test/core/templates/update-change.test.ts

@@ -55,7 +55,7 @@ const SANCTIONED_OUTSIDE_STEP_FIVE = [
   STEP_FOUR_DRAFT_RULE,
   'that is the starting edit.',
   'Do NOT write to `resolvedOutputPath`',
-  '- 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`.',
   'Confirm every edit with the user before writing.',
   '`/opsx:apply`',
   '(tasks checked off / already applied)',
@@ -292,6 +292,49 @@ describe('update-change templates', () => {
     }
   });
 
+  // #2068: the first guardrail read "Edit only the concrete files in
+  // existingOutputPaths", and a file step 4 creates is by definition not in
+  // that list. The exception sat two bullets below, so an agent applying the
+  // blanket rule refused the very operation the glob-gap flow exists to
+  // perform. Every place that states the scope rule has to carry the
+  // exception - a slice of the Guardrails section alone would miss step 2,
+  // which states the same rule two steps before the exception appears.
+  it('carries the glob new-file exception wherever the scope rule is stated (#2068)', () => {
+    for (const [label, body] of bodies) {
+      const scopeLines = body
+        .split('\n')
+        .filter((line) =>
+          /- Edit only the concrete files in `existingOutputPaths`|The files to edit are `artifactPaths/.test(line)
+        );
+      // Both sites: step 2's prose and the Guardrails bullet.
+      expect(scopeLines.length, `${label}: expected both scope-rule sites`).toBe(2);
+
+      for (const line of scopeLines) {
+        expect(line, `${label}: unqualified scope rule: ${line}`).toContain(
+          'any confirmed concrete path allowed under a partly populated glob artifact (step 4)'
+        );
+      }
+
+      // A reword must not be able to restore the unqualified prohibition.
+      expect(body, label).not.toMatch(/existingOutputPaths`;\s*never write to a glob/);
+      expect(body, label).not.toMatch(/existingOutputPaths` - the concrete files that exist on disk[^.]*\.\s*Do NOT write/);
+
+      // The prohibition itself and the frontier rule must survive the fix.
+      const guardrails = body.slice(body.indexOf('**Guardrails**'));
+      expect(guardrails, label).toContain('never write to a glob `resolvedOutputPath`');
+      expect(guardrails, label).toContain(
+        'The only new-file scope is a confirmed concrete path under a glob artifact whose `existingOutputPaths` is non-empty.'
+      );
+
+      // "(step 4)" is a cross-reference; pin that step 4 is still the step
+      // that owns the confirmation and the path checks, so renumbering or
+      // moving the flow cannot leave a dangling pointer.
+      const stepFour = section(body, '4. **Read and reconcile**', '5. **Confirm and apply', `${label} step 4`);
+      expect(stepFour, label).toContain('whose `existingOutputPaths` is non-empty');
+      expect(stepFour, label).toContain('create it only after the user confirms');
+    }
+  });
+
   it('writes to existingOutputPaths, never to a glob resolvedOutputPath (3.4)', () => {
     for (const [label, body] of bodies) {
       expect(body, label).toContain('artifactPaths.<id>.existingOutputPaths');

test/core/templates/verify-change-delta-operations.test.ts

@@ -55,7 +55,7 @@ describe('verify checks each requirement by its delta operation', () => {
     const coverage = section(body, '**Spec Coverage**', '6. **Verify Correctness**', label);
     const removed = section(coverage, '- For each REMOVED requirement', '- For each RENAMED entry', label);
 
-    expect(removed, label).toContain('Finding no implementation is the expected result.');
+    expect(removed, label).toContain('Finding no implementation is the expected result, but only once the baseline behavior was the thing you searched for.');
     expect(removed, label).toContain('Never report a REMOVED requirement as "Requirement not found"');
     expect(removed, label).toContain('Add CRITICAL issue: "Removed requirement still implemented: <requirement name>"');
     expect(removed, label).not.toContain('Recommendation: "Implement');
@@ -89,7 +89,7 @@ describe('verify checks each requirement by its delta operation', () => {
 
     expect(renamed, label).toContain('If the baseline requirement cannot be found or read, mark **Spec Coverage** as not verified for that entry');
     expect(renamed, label).toContain('Never count an unchecked rename as passing.');
-    expect(body, label).toContain('(each RENAMED entry is checked there against its baseline behavior)');
+    expect(body, label).toContain('each REMOVED and RENAMED entry with a usable baseline is checked there against its baseline behavior');
   });
 
   it.each(bodies)('%s: maps implementation and scenarios only for ADDED or MODIFIED requirements', (label, body) => {
@@ -122,6 +122,97 @@ describe('verify checks each requirement by its delta operation', () => {
     expect(removed, label).toContain('Report any code path that still delivers the removed behavior, including one shared with an ADDED requirement.');
   });
 
+  // #2067: the REMOVED branch said only "search codebase for the removed
+  // behavior". A REMOVED block carries just the requirement name plus Reason
+  // and Migration notes, so the search started from the heading alone - and
+  // because an absent match is the passing result here, an implementation
+  // written in different vocabulary read as a clean removal. The RENAMED
+  // branch beside it already loaded the baseline from the main spec first.
+  it.each(bodies)('%s: reads the removed requirement baseline before searching', (label, body) => {
+    const removed = section(body, '- For each REMOVED requirement', '- For each RENAMED entry', label);
+
+    expect(removed, label).toContain('A REMOVED block carries only the requirement name and any `**Reason**`/`**Migration**` notes');
+    expect(removed, label).toContain('`<planningHome.root>/openspec/specs/<capability-path>/spec.md`');
+    expect(removed, label).toContain('Its body and scenarios are the evidence for the behavior that must be gone');
+    expect(removed, label).toContain('never search from the requirement name alone');
+    // A literal title lookup misses a differently-worded baseline and gets
+    // misread as "the sync already removed it".
+    expect(removed, label).toContain('Match it by normalized name');
+  });
+
+  // The baseline read, the history fallback and the search have to stay in
+  // that order. Each index is checked present first: an unguarded indexOf
+  // returns -1, and -1 is less than everything, so a reworded sentence would
+  // satisfy a bare ordering comparison and silently retire this guard.
+  it.each(bodies)('%s: orders the baseline read, then the fallback, then the search', (label, body) => {
+    const removed = section(body, '- For each REMOVED requirement', '- For each RENAMED entry', label);
+
+    const baselineAt = removed.indexOf('Before searching, read the baseline requirement');
+    const fallbackAt = removed.indexOf("recover the baseline from the same file's history");
+    const bailOutAt = removed.indexOf('mark **Spec Coverage** as not verified for that entry');
+    const searchAt = removed.indexOf('Search codebase for that behavior.');
+
+    expect(baselineAt, `${label}: baseline-read sentence missing`).toBeGreaterThanOrEqual(0);
+    expect(fallbackAt, `${label}: history fallback missing`).toBeGreaterThanOrEqual(0);
+    expect(bailOutAt, `${label}: not-verified bail-out missing`).toBeGreaterThanOrEqual(0);
+    expect(searchAt, `${label}: search step missing`).toBeGreaterThanOrEqual(0);
+
+    // The main spec is the primary source; history is only its fallback.
+    expect(baselineAt, `${label}: fallback must follow the primary read`).toBeLessThan(fallbackAt);
+    // Bailing out must be reachable before the search, not two bullets after
+    // the rule that says finding nothing is expected.
+    expect(bailOutAt, `${label}: bail-out must precede the search`).toBeLessThan(searchAt);
+  });
+
+  // The git example is the one piece of the fallback an agent runs verbatim.
+  // `git log` treats an unmatched pathspec as success and prints nothing, so a
+  // path missing the `openspec/specs/` prefix reads as "no baseline in
+  // history" and sends every post-sync removal to the not-verified branch.
+  it.each(bodies)('%s: gives a runnable, store-aware history command', (label, body) => {
+    const removed = section(body, '- For each REMOVED requirement', '- For each RENAMED entry', label);
+
+    expect(removed, label).toContain('git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md');
+    // `rev:path` resolves from the repository root, not from `-C`; the `./`
+    // keeps it relative to a planning root that is a subdirectory (monorepo).
+    expect(removed, label).toContain('git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md');
+    expect(removed, label).not.toMatch(/show <commit>\^:openspec\//);
+    // An unquoted planning root splits on spaces and runs git in the wrong place.
+    expect(removed, label).not.toMatch(/git -C <planningHome\.root>/);
+    expect(removed, label).toContain('Empty output means the pathspec matched nothing');
+    // A bare `<capability-path>/spec.md` pathspec matches nothing: the
+    // placeholder is defined relative to `specs/`.
+    expect(removed, label).not.toMatch(/git[^`\n]*log[^`\n]*--\s+<capability-path>/);
+    // History must be read from the planning home, which may be a store repo
+    // rather than the current checkout (#1702).
+    expect(removed, label).not.toMatch(/\bgit log -p -- openspec/);
+  });
+
+  it.each(bodies)('%s: never counts an unsearched removal as passing', (label, body) => {
+    const removed = section(body, '- For each REMOVED requirement', '- For each RENAMED entry', label);
+
+    expect(removed, label).toContain('mark **Spec Coverage** as not verified for that entry with the reason and stop there');
+    expect(removed, label).toContain('do not search, and never count an unsearched removal as passing');
+    // A baseline that only restates its title gives no more vocabulary than
+    // the heading did, which is the #2067 failure mode in miniature.
+    expect(removed, label).toContain('A baseline that adds nothing to its own title');
+    expect(removed, label).toContain('is unusable evidence, the same as a missing one');
+    // Reworded re-introductions must fail too, not just the exact old
+    // sentence: the bug was searching from the name, however it is phrased.
+    expect(removed, label).not.toMatch(/Search\b[^.\n]*\bfor the removed behavior/i);
+    expect(removed, label).not.toMatch(/Finding no implementation is the expected result[.;]/);
+  });
+
+  // Step 6 asserts that Spec Coverage carries the evidence for a removal-only
+  // change. That claim has to leave room for the entry the branch above marks
+  // not verified, or it reads as licence to drop the mark.
+  it.each(bodies)('%s: does not claim a baseline check that may not have happened', (label, body) => {
+    expect(body, label).toContain('each REMOVED and RENAMED entry with a usable baseline is checked there against its baseline behavior');
+    expect(body, label).toContain('an entry already marked not verified there stays not verified');
+    // The scorecard must model the not-verified wording, not only the
+    // confirming kind.
+    expect(body, label).toContain('"1 removal not verified (baseline unavailable)"');
+  });
+
   it.each(bodies)('%s: counts removals separately from covered requirements', (label, body) => {
     expect(body, label).toContain('Count only ADDED and MODIFIED requirements in N, and report REMOVED and RENAMED requirements separately');
     expect(body, label).toContain('the Correctness cell reads `Not applicable (no ADDED or MODIFIED requirements)`');

test/core/validation.archive-preflight.test.ts

@@ -59,8 +59,10 @@ describe('validate: deltas archive would refuse (#1112)', () => {
 
   beforeEach(async () => {
     testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-preflight-'));
-    changesDir = path.join(testDir, 'openspec', 'changes');
-    mainSpecsDir = path.join(testDir, 'openspec', 'specs');
+    // The project sits one level down, so a link written to testDir leaves it:
+    // a spec link that stays inside the project is allowed, one that leaves is not.
+    changesDir = path.join(testDir, 'repo', 'openspec', 'changes');
+    mainSpecsDir = path.join(testDir, 'repo', 'openspec', 'specs');
     await fs.mkdir(changesDir, { recursive: true });
     await fs.mkdir(mainSpecsDir, { recursive: true });
   });

test/core/validation.unknown-metadata-keys.test.ts

@@ -82,6 +82,34 @@ describe('unrecognized keys in .openspec.yaml', () => {
     expect(report.valid).toBe(true);
   });
 
+  it('passes --strict when the only extra keys are x- extension keys, whatever their values', async () => {
+    await writeMetadata(
+      'schema: spec-driven\nskip_specs: true\nx-goal: G-12\nx-jiraKey: ABC-1\n' +
+        'x-owner:\n  team: payments\nx-list: [1, 2]\nx-empty:\n'
+    );
+
+    const report = await new Validator(true).validateChangeDeltaSpecs(testDir);
+
+    expect(report.issues.filter((issue) => issue.path === METADATA_FILENAME)).toHaveLength(0);
+    expect(report.valid).toBe(true);
+  });
+
+  it('still fails --strict on near-miss extension keys beside a valid one', async () => {
+    await writeMetadata(
+      'schema: spec-driven\nskip_specs: true\nx-goal: G-12\nX-Tracker: 1\n"x-": 1\n"x- tracker": 1\n'
+    );
+
+    const report = await new Validator(true).validateChangeDeltaSpecs(testDir);
+
+    const warning = report.issues.find(
+      (issue) => issue.level === 'WARNING' && issue.path === METADATA_FILENAME
+    );
+    expect(report.valid).toBe(false);
+    expect(warning?.message).toContain('X-Tracker');
+    expect(warning?.message).toContain('x- tracker');
+    expect(warning?.message).not.toContain('x-goal');
+  });
+
   it('still accepts skip_specs when an unknown key sits beside it', async () => {
     await writeMetadata('schema: spec-driven\nskip_specs: true\nskip_design: true\n');
 
@@ -118,4 +146,17 @@ describe('status/instructions report unrecognized change metadata keys', () => {
     expect(context.metadata?.skip_specs).toBe(true);
     expect(context.warnings).toEqual([expect.stringContaining('skip_design')]);
   });
+
+  it('returns no warning when the only extra keys are x- extension keys', async () => {
+    await fs.writeFile(
+      path.join(changeDir, METADATA_FILENAME),
+      'schema: spec-driven\nskip_specs: true\nx-goal: G-12\nx-owner:\n  team: payments\n',
+      'utf-8'
+    );
+
+    const context = loadChangeContext(tempDir, 'probe');
+
+    expect(context.metadata?.skip_specs).toBe(true);
+    expect(context.warnings).toBeUndefined();
+  });
 });

test/explore-docs-claims.test.ts

@@ -22,8 +22,8 @@ import { fileURLToPath } from 'node:url';
 // unless you ask" is the wording this very test recommends.
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-// The pages that pitch explore to a user. Both trees ship: `docs/` is what
-// README links today, `docs-lab/` is what the documentation site publishes
+// The pages that pitch explore to a user. Both trees ship: `docs/` is the
+// legacy tree still readable on GitHub, `docs-lab/` is what the documentation site publishes
 // (`website/content/docs` is generated from it and is not committed).
 const PAGES = [
   'README.md',

test/pnpm-workspace-config.test.ts

@@ -54,6 +54,24 @@ describe('pnpm workspace configuration', () => {
     expect(workspace.overrides).toEqual(lockfile.overrides);
   });
 
+  it('previews the built site without a server dependency', () => {
+    const packageJson = readJson('website/package.json');
+    const lockfile = readYaml('website/pnpm-lock.yaml');
+
+    // `pnpm start` ran `serve`, whose dev-only tree kept publishing advisories
+    // into the site's graph — four of them (brace-expansion x3, fast-uri) turned
+    // the Security workflow red on `main` and had to be pinned by hand, for code
+    // that never reached the published site. A first-party preview script has no
+    // tree to audit. Re-adding a server dependency means taking that back on
+    // purpose, so it should update this test too.
+    expect(packageJson.scripts.start).toBe('node scripts/preview.mjs');
+    expect(fs.existsSync(path.join(projectRoot, 'website/scripts/preview.mjs'))).toBe(true);
+    const serverPackages = Object.keys(lockfile.packages).filter((key) =>
+      /^(serve|serve-handler)@/.test(key)
+    );
+    expect(serverPackages).toEqual([]);
+  });
+
   it('includes install policy changes in Nix and security validation', () => {
     const flake = fs.readFileSync(path.join(projectRoot, 'flake.nix'), 'utf8');
     const ci = fs.readFileSync(path.join(projectRoot, '.github/workflows/ci.yml'), 'utf8');

test/utils/change-metadata.test.ts

@@ -10,6 +10,7 @@ import {
   ChangeMetadataError,
   readRetireCapabilitiesMarker,
   listUnknownChangeMetadataKeys,
+  isExtensionMetadataKey,
   formatUnknownChangeMetadataKeysMessage,
 } from '../../src/utils/change-metadata.js';
 import { ChangeMetadataSchema } from '../../src/core/change-metadata/index.js';
@@ -175,6 +176,23 @@ describe('listUnknownChangeMetadataKeys', () => {
     ).toEqual([]);
   });
 
+  it('does not report x- extension keys, and still reports everything else', () => {
+    expect(
+      listUnknownChangeMetadataKeys({
+        schema: 'spec-driven',
+        'x-goal': 'G-12',
+        'x-tracker': { system: 'linear', id: 'SB-5497' },
+        'x-': 'not an extension key',
+        'X-Upper': 1,
+        bogus_key: 1,
+      })
+    ).toEqual(['X-Upper', 'bogus_key', 'x-']);
+  });
+
+  it('tells the author how to keep tool metadata without the warning', () => {
+    expect(formatUnknownChangeMetadataKeysMessage(['bogus_key'])).toContain('x-');
+  });
+
   it('explains that skip_design is not skip_specs', () => {
     const message = formatUnknownChangeMetadataKeysMessage(['skip_design']);
     expect(message).toContain('skip_design');
@@ -488,3 +506,93 @@ describe('boolean marker reasons', () => {
     expect(marker.invalidReason).not.toMatch(/[\u0000-\u001f\u007f]/);
   });
 });
+
+describe('isExtensionMetadataKey', () => {
+  it('accepts x- followed by a name', () => {
+    expect(isExtensionMetadataKey('x-goal')).toBe(true);
+    expect(isExtensionMetadataKey('x-kf_part-2')).toBe(true);
+    expect(isExtensionMetadataKey('x-')).toBe(false);
+    expect(isExtensionMetadataKey('X-goal')).toBe(false);
+    expect(isExtensionMetadataKey('goal')).toBe(false);
+  });
+
+  // The name after the prefix is the owner's business, in any case or spelling.
+  it('accepts the spellings a tracker id is actually written in', () => {
+    expect(isExtensionMetadataKey('x-jiraKey')).toBe(true);
+    expect(isExtensionMetadataKey('x-trackerID')).toBe(true);
+    expect(isExtensionMetadataKey('x-Owner')).toBe(true);
+    expect(isExtensionMetadataKey('x-foo.bar')).toBe(true);
+    expect(isExtensionMetadataKey('x--foo')).toBe(true);
+  });
+
+  it('rejects a prefix that names nothing, or a name carrying whitespace', () => {
+    expect(isExtensionMetadataKey('x-')).toBe(false);
+    expect(isExtensionMetadataKey('x- ')).toBe(false);
+    expect(isExtensionMetadataKey('x- tracker')).toBe(false);
+    expect(isExtensionMetadataKey(' x-foo')).toBe(false);
+    expect(isExtensionMetadataKey('x-foo ')).toBe(false);
+    expect(isExtensionMetadataKey('x-a\nb')).toBe(false);
+  });
+
+  it('rejects a near-miss prefix, including the wrong case', () => {
+    expect(isExtensionMetadataKey('x_foo')).toBe(false);
+    expect(isExtensionMetadataKey('xfoo')).toBe(false);
+    expect(isExtensionMetadataKey('x')).toBe(false);
+    expect(isExtensionMetadataKey('-x-foo')).toBe(false);
+    expect(isExtensionMetadataKey('X-Foo')).toBe(false);
+  });
+});
+
+describe('extension keys alongside the unknown-key warning', () => {
+  it('keeps reporting a misspelled real key beside a valid extension', () => {
+    expect(
+      listUnknownChangeMetadataKeys({
+        schema: 'spec-driven',
+        'x-goal': 'G-12',
+        skip_spec: true,
+        taskss: true,
+      })
+    ).toEqual(['skip_spec', 'taskss']);
+  });
+
+  // An x- key inside a recognized object is not a top-level extension; the
+  // object's own strict schema rejects it, so it must not be silently accepted.
+  it('does not treat an x- key inside a recognized object as an extension', () => {
+    expect(
+      listUnknownChangeMetadataKeys({
+        schema: 'spec-driven',
+        initiative: { store: 'a', id: 'b', 'x-extra': 1 },
+      })
+    ).toEqual([]);
+    expect(
+      ChangeMetadataSchema.safeParse({
+        schema: 'spec-driven',
+        initiative: { store: 'a', id: 'b', 'x-extra': 1 },
+      }).success
+    ).toBe(false);
+  });
+
+  // The message must not tell someone who already wrote x-jiraKey to "prefix a
+  // key with x-". It now names the two conditions the prefix does not cover.
+  it('explains the near-miss to a user who did use the prefix', () => {
+    const message = formatUnknownChangeMetadataKeysMessage(['X-Tracker', 'x-']);
+    expect(message).toContain('lowercase x- prefix');
+    expect(message).toContain('no whitespace');
+    expect(message).toContain('x-jiraKey are extensions');
+  });
+
+  it('leaves the message alone when no key used the prefix', () => {
+    expect(formatUnknownChangeMetadataKeysMessage(['taskss'])).not.toContain(
+      'lowercase x- prefix'
+    );
+  });
+
+  // ChangeMetadataSchema strips unknown keys, so writeChangeMetadata is only
+  // safe on a new file. If a future caller rewrites an existing one without
+  // merging the raw YAML back, every x- key in it is silently deleted.
+  it('strips extension keys, so the writer must never rewrite an existing file', () => {
+    expect(
+      ChangeMetadataSchema.safeParse({ schema: 'spec-driven', 'x-goal': 'G-12' }).data
+    ).toEqual({ schema: 'spec-driven' });
+  });
+});

test/utils/interactive.test.ts

@@ -5,6 +5,7 @@ import {
   isInteractive,
   isNonInteractivePromptError,
   resolveNoInteractive,
+  canRenderSpinner,
   InteractiveOptions,
 } from '../../src/utils/interactive.js';
 
@@ -382,4 +383,49 @@ describe('interactive utilities', () => {
       ).rejects.toThrow('stdin exploded');
     });
   });
+
+  describe('canRenderSpinner', () => {
+    it('refuses a TTY that reports zero columns', () => {
+      expect(canRenderSpinner({ isTTY: true, columns: 0 })).toBe(false);
+    });
+
+    it('refuses a TTY that reports no width at all', () => {
+      expect(canRenderSpinner({ isTTY: true })).toBe(false);
+    });
+
+    it('allows a TTY with a real width', () => {
+      expect(canRenderSpinner({ isTTY: true, columns: 80 })).toBe(true);
+    });
+
+    it('allows a non-TTY stream, which ora prints as one plain line', () => {
+      expect(canRenderSpinner({ isTTY: false })).toBe(true);
+    });
+
+    it('covers the case where ora clears without bound (#2106)', async () => {
+      // The reason the guard exists: with zero columns ora's line count is
+      // Infinity, so clear() keeps moving the cursor up forever. The fake stream
+      // is capped so the unbounded loop fails fast instead of hanging the suite.
+      // If a future ora bounds that loop this test goes red, and the guard can
+      // be revisited.
+      const ora = (await import('ora')).default;
+      let moves = 0;
+      const stream = {
+        isTTY: true,
+        columns: 0,
+        rows: 0,
+        write: () => true,
+        cursorTo: () => {},
+        clearLine: () => {},
+        moveCursor: () => {
+          if (++moves > 1000) throw new Error('unbounded clear');
+        },
+        once: () => {},
+      } as unknown as NodeJS.WriteStream;
+
+      const spinner = ora({ text: 'Validating...', stream, isEnabled: true });
+      spinner.render();
+      expect(() => spinner.render()).toThrow('unbounded clear');
+      expect(canRenderSpinner(stream)).toBe(false);
+    });
+  });
 });

test/utils/spec-discovery.test.ts

@@ -149,6 +149,44 @@ describe('discoverSpecFiles', () => {
     });
   });
 
+  it.skipIf(process.platform === 'win32')(
+    'discovers a spec.md linked to a file elsewhere in the project (#2100)',
+    async () => {
+      await withTempDir(async (dir) => {
+        // The project keeps its specs beside the product documentation and
+        // links openspec/specs/<capability>/spec.md to them.
+        const specsRoot = path.join(dir, 'repo', 'openspec', 'specs');
+        const docsSpec = path.join(dir, 'repo', 'docs', 'auth', 'specs', 'login.md');
+        await fs.mkdir(path.join(specsRoot, 'login'), { recursive: true });
+        await fs.mkdir(path.dirname(docsSpec), { recursive: true });
+        await fs.writeFile(docsSpec, '# login\n', 'utf8');
+        const link = path.join(specsRoot, 'login', 'spec.md');
+        await fs.symlink(path.relative(path.dirname(link), docsSpec), link, 'file');
+
+        const found = await discoverSpecFiles(specsRoot);
+        expect(found.map((s) => s.id)).toEqual(['login']);
+        expect(found[0].specFile).toBe(link);
+      });
+    }
+  );
+
+  it.skipIf(process.platform === 'win32')(
+    'rejects a spec.md symlink that leaves the project (#2100)',
+    async () => {
+      await withTempDir(async (dir) => {
+        const specsRoot = path.join(dir, 'repo', 'openspec', 'specs');
+        const outside = path.join(dir, 'outside.md');
+        await fs.mkdir(path.join(specsRoot, 'login'), { recursive: true });
+        await fs.writeFile(outside, '# Outside\n', 'utf8');
+        await fs.symlink(outside, path.join(specsRoot, 'login', 'spec.md'), 'file');
+
+        await expect(discoverSpecFiles(specsRoot)).rejects.toThrow(
+          'Path is outside the allowed directory'
+        );
+      });
+    }
+  );
+
   it.skipIf(process.platform === 'win32')('skips a dangling spec.md symlink', async () => {
     await withTempDir(async (dir) => {
       await writeSpec(dir, 'real');

test/utils/spec-path-containment.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  assertDiscoveredSpecFile,
+  assertSpecFileWithin,
+} from '../../src/utils/spec-path-containment.js';
+
+const itWithSymlinks = it.skipIf(process.platform === 'win32');
+
+/**
+ * Coverage for the containment rule itself rather than for a copy of it in a
+ * command. The cases run against real directories because the rule
+ * canonicalizes before deciding, so a purely notional path would not exercise
+ * it.
+ */
+describe('spec.md containment', () => {
+  let tempDir: string;
+  let projectDir: string;
+  let specsRoot: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-spec-containment-'));
+    projectDir = path.join(tempDir, 'repo');
+    specsRoot = path.join(projectDir, 'openspec', 'specs');
+    await fs.mkdir(path.join(specsRoot, 'login'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  async function link(target: string): Promise<string> {
+    const linkPath = path.join(specsRoot, 'login', 'spec.md');
+    await fs.symlink(target, linkPath);
+    return linkPath;
+  }
+
+  for (const [name, assert] of [
+    ['assertDiscoveredSpecFile', assertDiscoveredSpecFile],
+    ['assertSpecFileWithin', assertSpecFileWithin],
+  ] as const) {
+    describe(name, () => {
+      it('accepts an ordinary spec file', async () => {
+        const specFile = path.join(specsRoot, 'login', 'spec.md');
+        await fs.writeFile(specFile, '# login\n');
+        expect(() => assert(specsRoot, specFile)).not.toThrow();
+      });
+
+      it('rejects a path that traverses out of the specs root', () => {
+        expect(() =>
+          assert(specsRoot, path.join(specsRoot, '..', '..', '..', 'outside.md'))
+        ).toThrow('Path is outside the allowed directory');
+      });
+
+      itWithSymlinks('accepts a link to a file elsewhere in the project', async () => {
+        const docsSpec = path.join(projectDir, 'docs', 'auth', 'specs', 'login.md');
+        await fs.mkdir(path.dirname(docsSpec), { recursive: true });
+        await fs.writeFile(docsSpec, '# login\n');
+        const linkPath = await link(path.relative(path.join(specsRoot, 'login'), docsSpec));
+
+        expect(() => assert(specsRoot, linkPath)).not.toThrow();
+      });
+
+      itWithSymlinks('rejects a link that leaves the project', async () => {
+        const outside = path.join(tempDir, 'outside.md');
+        await fs.writeFile(outside, '# outside\n');
+        const linkPath = await link(outside);
+
+        expect(() => assert(specsRoot, linkPath)).toThrow(
+          'Path is outside the allowed directory'
+        );
+      });
+
+      itWithSymlinks('rejects a dangling link rather than assuming it is contained', async () => {
+        const linkPath = await link(path.join(projectDir, 'docs', 'missing.md'));
+
+        expect(() => assert(specsRoot, linkPath)).toThrow();
+      });
+
+      itWithSymlinks(
+        'keeps a specs root with no project to name confined to itself',
+        async () => {
+          // A specs root reached outside an `openspec` directory (a store given
+          // by path) has no project boundary to widen to.
+          const bareRoot = path.join(tempDir, 'bare-specs');
+          await fs.mkdir(path.join(bareRoot, 'login'), { recursive: true });
+          const outside = path.join(tempDir, 'bare-outside.md');
+          await fs.writeFile(outside, '# outside\n');
+          const linkPath = path.join(bareRoot, 'login', 'spec.md');
+          await fs.symlink(outside, linkPath);
+
+          expect(() => assert(bareRoot, linkPath)).toThrow(
+            'Path is outside the allowed directory'
+          );
+        }
+      );
+    });
+  }
+
+  describe('the project boundary a specs root resolves to', () => {
+    async function linkedSpecUnder(
+      specsRoot: string,
+      target: string
+    ): Promise<string> {
+      await fs.mkdir(path.join(specsRoot, 'login'), { recursive: true });
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, '# login\n');
+      const linkPath = path.join(specsRoot, 'login', 'spec.md');
+      await fs.symlink(path.relative(path.join(specsRoot, 'login'), target), linkPath);
+      return linkPath;
+    }
+
+    itWithSymlinks('reaches the project from a change\'s delta specs', async () => {
+      const deltaSpecs = path.join(projectDir, 'openspec', 'changes', 'c1', 'specs');
+      const linkPath = await linkedSpecUnder(
+        deltaSpecs,
+        path.join(projectDir, 'docs', 'shared-delta.md')
+      );
+
+      expect(() => assertDiscoveredSpecFile(deltaSpecs, linkPath)).not.toThrow();
+    });
+
+    itWithSymlinks('reaches the project from an archived change\'s delta specs', async () => {
+      const deltaSpecs = path.join(
+        projectDir,
+        'openspec',
+        'changes',
+        'archive',
+        '2026-01-01-c1',
+        'specs'
+      );
+      const linkPath = await linkedSpecUnder(
+        deltaSpecs,
+        path.join(projectDir, 'docs', 'shared-delta.md')
+      );
+
+      expect(() => assertDiscoveredSpecFile(deltaSpecs, linkPath)).not.toThrow();
+    });
+
+    itWithSymlinks(
+      'does not widen for a directory that merely shares the name `openspec`',
+      async () => {
+        // A store kept at `<somewhere>/openspec/my-store` must not hand out
+        // `<somewhere>` as its boundary: only `openspec/specs` and
+        // `openspec/changes` are planning roots.
+        const storeSpecs = path.join(tempDir, 'openspec', 'my-store', 'specs');
+        const linkPath = await linkedSpecUnder(
+          storeSpecs,
+          path.join(tempDir, 'elsewhere', 'login.md')
+        );
+
+        expect(() => assertDiscoveredSpecFile(storeSpecs, linkPath)).toThrow(
+          'Path is outside the allowed directory'
+        );
+      }
+    );
+  });
+
+  itWithSymlinks(
+    'assertDiscoveredSpecFile treats a linked capability directory as its own trust root',
+    async () => {
+      const external = path.join(tempDir, 'other-repo', 'login');
+      await fs.mkdir(external, { recursive: true });
+      await fs.writeFile(path.join(external, 'spec.md'), '# login\n');
+      const capabilityLink = path.join(specsRoot, 'shared');
+      await fs.symlink(external, capabilityLink);
+
+      expect(() =>
+        assertDiscoveredSpecFile(specsRoot, path.join(capabilityLink, 'spec.md'))
+      ).not.toThrow();
+    }
+  );
+
+  itWithSymlinks(
+    'assertSpecFileWithin refuses a capability directory swapped for a link',
+    async () => {
+      // The recheck before a read or a write must not trust a directory that
+      // became a link after the path was resolved.
+      const external = path.join(tempDir, 'other-repo', 'login');
+      await fs.mkdir(external, { recursive: true });
+      await fs.writeFile(path.join(external, 'spec.md'), '# login\n');
+      await fs.rm(path.join(specsRoot, 'login'), { recursive: true });
+      await fs.symlink(external, path.join(specsRoot, 'login'));
+
+      expect(() =>
+        assertSpecFileWithin(specsRoot, path.join(specsRoot, 'login', 'spec.md'))
+      ).toThrow('Path is outside the allowed directory');
+    }
+  );
+});

test/website-preview.test.ts

@@ -0,0 +1,207 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { AddressInfo } from 'net';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+type PreviewModule = {
+  resolveStaticFile(root: string, requestPath: string): string | null;
+  contentTypeFor(filePath: string): string;
+  createPreviewServer(root: string): import('http').Server;
+};
+
+// A literal relative specifier, so the runner resolves it the same way it
+// resolves every other import in this suite. Building the path at runtime
+// instead handed it a Windows absolute path, which is not a module specifier:
+// the suite failed to load on windows-pwsh with `SyntaxError: Invalid or
+// unexpected token`, and a `file://` URL did not fix it either.
+// `test/pnpm-workspace-config.test.ts` pins the script's location.
+const preview = (await import(
+  '../website/scripts/preview.mjs'
+)) as unknown as PreviewModule;
+
+/**
+ * Mirrors a Next static export: a route is written as `docs/cli.html`, and a
+ * directory of the same name holds its data files but no index.html.
+ */
+function buildFixture(): string {
+  // The export sits one level down, so files placed "outside" it still live
+  // inside this run's own temporary directory.
+  const parent = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-preview-'));
+  const root = path.join(parent, 'out');
+  fs.mkdirSync(root);
+  fs.writeFileSync(path.join(root, 'index.html'), '<html>home</html>');
+  fs.writeFileSync(path.join(root, '404.html'), '<html>missing</html>');
+  fs.writeFileSync(path.join(root, 'robots.txt'), 'User-agent: *\n');
+  fs.mkdirSync(path.join(root, 'docs', 'cli'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'docs', 'cli.html'), '<html>cli</html>');
+  fs.writeFileSync(path.join(root, 'docs', 'cli', 'data.txt'), 'data');
+  fs.mkdirSync(path.join(root, 'guide'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'guide', 'index.html'), '<html>guide</html>');
+  return root;
+}
+
+/** A file symlink, or false where the OS refuses one (Windows without the privilege). */
+function linkFile(target: string, linkPath: string): boolean {
+  try {
+    fs.symlinkSync(target, linkPath, 'file');
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EPERM') return false;
+    throw error;
+  }
+}
+
+describe('website preview server', () => {
+  let root: string;
+
+  beforeAll(() => {
+    root = buildFixture();
+  });
+
+  afterAll(() => {
+    fs.rmSync(path.dirname(root), { recursive: true, force: true });
+  });
+
+  describe('resolveStaticFile', () => {
+    it('serves the root index', () => {
+      expect(preview.resolveStaticFile(root, '/')).toBe(path.join(root, 'index.html'));
+    });
+
+    it('falls back to the exported .html file for a route', () => {
+      expect(preview.resolveStaticFile(root, '/docs/cli')).toBe(
+        path.join(root, 'docs', 'cli.html')
+      );
+    });
+
+    it('resolves a route the same way with a trailing slash', () => {
+      expect(preview.resolveStaticFile(root, '/docs/cli/')).toBe(
+        path.join(root, 'docs', 'cli.html')
+      );
+    });
+
+    it('prefers a directory index when one exists', () => {
+      expect(preview.resolveStaticFile(root, '/guide')).toBe(
+        path.join(root, 'guide', 'index.html')
+      );
+    });
+
+    it('serves a file by its exact path', () => {
+      expect(preview.resolveStaticFile(root, '/robots.txt')).toBe(path.join(root, 'robots.txt'));
+    });
+
+    it('returns null for a path with no match', () => {
+      expect(preview.resolveStaticFile(root, '/nope')).toBeNull();
+    });
+
+    it('refuses to escape the export directory', () => {
+      const outside = path.join(root, '..', 'escaped.txt');
+      fs.writeFileSync(outside, 'secret');
+      try {
+        expect(preview.resolveStaticFile(root, '/../escaped.txt')).toBeNull();
+        expect(preview.resolveStaticFile(root, '/%2e%2e/escaped.txt')).toBeNull();
+        expect(preview.resolveStaticFile(root, '/docs/../../escaped.txt')).toBeNull();
+      } finally {
+        fs.rmSync(outside, { force: true });
+      }
+    });
+
+    it('refuses a symlink under the export that points outside it', () => {
+      const outsideDir = path.join(path.dirname(root), 'private');
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.writeFileSync(path.join(outsideDir, 'secret.txt'), 'secret');
+      // A junction needs no privilege on Windows and is a link to Node.
+      fs.symlinkSync(outsideDir, path.join(root, 'linked'), 'junction');
+      const fileLinked = linkFile(path.join(outsideDir, 'secret.txt'), path.join(root, 'secret.txt'));
+      try {
+        expect(preview.resolveStaticFile(root, '/linked/secret.txt')).toBeNull();
+        if (fileLinked) expect(preview.resolveStaticFile(root, '/secret.txt')).toBeNull();
+      } finally {
+        fs.rmSync(path.join(root, 'linked'), { force: true, recursive: true });
+        fs.rmSync(path.join(root, 'secret.txt'), { force: true });
+        fs.rmSync(outsideDir, { recursive: true, force: true });
+      }
+    });
+
+    it('follows a symlink that stays inside the export', (ctx) => {
+      if (!linkFile(path.join(root, 'robots.txt'), path.join(root, 'robots-link.txt'))) {
+        ctx.skip();
+      }
+      try {
+        expect(preview.resolveStaticFile(root, '/robots-link.txt')).toBe(
+          path.join(root, 'robots-link.txt')
+        );
+      } finally {
+        fs.rmSync(path.join(root, 'robots-link.txt'), { force: true });
+      }
+    });
+
+    it('rejects malformed encoding and null bytes', () => {
+      expect(preview.resolveStaticFile(root, '/%E0%A4%A')).toBeNull();
+      expect(preview.resolveStaticFile(root, '/index.html%00.txt')).toBeNull();
+    });
+  });
+
+  describe('contentTypeFor', () => {
+    it('names the common static types', () => {
+      expect(preview.contentTypeFor('a/b.html')).toBe('text/html; charset=utf-8');
+      expect(preview.contentTypeFor('a/b.css')).toBe('text/css; charset=utf-8');
+      expect(preview.contentTypeFor('a/b.svg')).toBe('image/svg+xml');
+      expect(preview.contentTypeFor('a/b.woff2')).toBe('font/woff2');
+    });
+
+    it('falls back to a byte stream for anything else', () => {
+      expect(preview.contentTypeFor('a/b.unknown')).toBe('application/octet-stream');
+    });
+  });
+
+  describe('over HTTP', () => {
+    it('serves pages and answers a miss with the 404 page', async () => {
+      const server = preview.createPreviewServer(root);
+      await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const { port } = server.address() as AddressInfo;
+
+      try {
+        const page = await fetch(`http://127.0.0.1:${port}/docs/cli`);
+        expect(page.status).toBe(200);
+        expect(page.headers.get('content-type')).toBe('text/html; charset=utf-8');
+        expect(await page.text()).toBe('<html>cli</html>');
+
+        const missing = await fetch(`http://127.0.0.1:${port}/nope`);
+        expect(missing.status).toBe(404);
+        expect(await missing.text()).toBe('<html>missing</html>');
+      } finally {
+        await new Promise<void>((resolve, reject) =>
+          server.close((error) => (error ? reject(error) : resolve()))
+        );
+      }
+    });
+
+    it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)(
+      'answers an unreadable file with an error instead of crashing',
+      async () => {
+        const locked = path.join(root, 'locked.txt');
+        fs.writeFileSync(locked, 'locked');
+        fs.chmodSync(locked, 0o000);
+        const server = preview.createPreviewServer(root);
+        await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const { port } = server.address() as AddressInfo;
+
+        try {
+          const failed = await fetch(`http://127.0.0.1:${port}/locked.txt`);
+          expect(failed.status).toBe(500);
+          // Still serving afterwards.
+          const page = await fetch(`http://127.0.0.1:${port}/docs/cli`);
+          expect(page.status).toBe(200);
+        } finally {
+          fs.chmodSync(locked, 0o644);
+          fs.rmSync(locked, { force: true });
+          server.closeAllConnections();
+          await new Promise<void>((resolve, reject) =>
+            server.close((error) => (error ? reject(error) : resolve()))
+          );
+        }
+      }
+    );
+  });
+});

website/package.json

@@ -8,28 +8,27 @@
     "sync:docs:watch": "node --watch-path=../docs --watch-path=../docs-lab --watch-path=docs.sync.config.mjs --watch-preserve-output scripts/sync-docs.mjs",
     "build": "pnpm run sync:docs && fumadocs-mdx && next build",
     "dev": "pnpm run sync:docs && (pnpm run sync:docs:watch & next dev)",
-    "start": "serve out",
+    "start": "node scripts/preview.mjs",
     "types:check": "pnpm run sync:docs && fumadocs-mdx && next typegen && tsc --noEmit"
   },
   "dependencies": {
     "beautiful-mermaid": "^1.1.3",
-    "fumadocs-core": "^16.15.17",
-    "fumadocs-mdx": "^15.3.1",
-    "fumadocs-ui": "^16.15.17",
-    "lucide-react": "^1.34.0",
+    "fumadocs-core": "^16.16.1",
+    "fumadocs-mdx": "^15.4.6",
+    "fumadocs-ui": "^16.16.1",
+    "lucide-react": "^1.52.0",
     "next": "16.3.8",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "zod": "^4.4.3"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.1",
     "@types/mdx": "^2.0.14",
-    "@types/node": "^26.3.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
-    "postcss": "^8.5.28",
-    "serve": "^14.2.6",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "postcss": "^8.5.29",
     "tailwindcss": "^4.3.1",
     "typescript": "^6.0.3"
   }

website/pnpm-workspace.yaml

@@ -12,12 +12,6 @@ allowBuilds:
 overrides:
   postcss: ^8.5.28
   sharp: ^0.35.3
-  # GHSA-6j4f-fj2g-mc7p, GHSA-qhr7-859c-m2p7, GHSA-q2hr-2g5m-vwhr — brace-expansion
-  # DoS via nested or comma-heavy brace groups. Dev-only (serve > serve-handler >
-  # minimatch); never in the static site.
-  brace-expansion@<5.0.12: '>=5.0.12 <6'
-  # GHSA-hrr3-gc8f-f4qj — fast-uri. Dev-only (serve > ajv).
-  fast-uri@<3.1.8: ^3.1.8
   # GHSA-2v37-7h3g-55p8 / CVE-2026-67213 — nanoid infinite loop on size=0. Build-time
   # only (transitive via postcss); this is a statically exported site with no server
   # runtime. Remove once transitive nanoid is >=3.3.17 (check: pnpm why nanoid).

website/scripts/preview.mjs

@@ -0,0 +1,169 @@
+// Serve the built static site in `out/` for a local look at what Cloudflare
+// Pages will publish. Backs `pnpm start`.
+//
+// Deliberately dependency-free. This replaced `serve`, whose transitive tree
+// kept publishing advisories into a dev-only tool: four of them (brace-expansion
+// x3, fast-uri) turned the Security workflow red on `main` and had to be pinned
+// by hand, and none of that code ever reached the published site. A preview
+// server for a static export is small enough to own outright.
+//
+// Routing approximates Cloudflare Pages for a Next static export:
+//   /             -> out/index.html
+//   /docs/cli     -> out/docs/cli.html (or out/docs/cli/index.html)
+//   /docs/cli/    -> the same, so links work with or without a trailing slash
+//   anything else -> out/404.html with status 404
+//
+// `out/_redirects` is a Cloudflare feature and is not applied here, same as
+// before: the preview serves the exported files as they are.
+
+import { createServer } from 'node:http';
+import { createReadStream, existsSync, realpathSync, statSync } from 'node:fs';
+import { dirname, extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const websiteRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = join(websiteRoot, 'out');
+
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+export function contentTypeFor(filePath) {
+  return CONTENT_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/**
+ * Resolves a request path to a file inside `root`, or null when nothing matches.
+ *
+ * Escaping `root` is never a match: the decoded path is normalized and the
+ * result is checked to still sit under `root`, so `..` segments and an
+ * encoded `%2e%2e` both fall through to the 404 page. A candidate is then
+ * checked again after resolving symlinks, so a link under `root` that points
+ * outside it is not served either.
+ */
+export function resolveStaticFile(root, requestPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(requestPath);
+  } catch {
+    return null; // Malformed percent-encoding.
+  }
+  if (decoded.includes('\0')) return null;
+
+  // Normalize in POSIX terms first: a request path is URL-shaped, so its
+  // separator is `/` on every platform.
+  // Trailing separators are dropped so a directory request and the `.html`
+  // fallback for it build the same base path.
+  const relativePath = normalize(decoded.replace(/^\/+/, '').split('/').join(sep)).replace(
+    new RegExp(`\\${sep}+$`),
+    ''
+  );
+  const base = relativePath === '' || relativePath === '.' ? root : join(root, relativePath);
+  if (base !== root && !base.startsWith(root + sep)) return null;
+
+  // Next's export writes a route as `docs/cli.html`, not `docs/cli/index.html`,
+  // so both spellings have to resolve either way the link was written.
+  const candidates = decoded.endsWith('/')
+    ? [join(base, 'index.html'), `${base}.html`]
+    : [base, join(base, 'index.html'), `${base}.html`];
+
+  let realRoot;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    return null;
+  }
+  for (const candidate of candidates) {
+    if (candidate !== root && !candidate.startsWith(root + sep)) continue;
+    try {
+      // The lexical check above does not see symlinks; the real path does.
+      const real = realpathSync(candidate);
+      if (real !== realRoot && !real.startsWith(realRoot + sep)) continue;
+      if (statSync(real).isFile()) return candidate;
+    } catch {
+      // Missing, or removed since the request arrived: not a match.
+    }
+  }
+  return null;
+}
+
+/**
+ * Streams a file, sending headers only once it is open. A file that is gone or
+ * unreadable by then gets a plain error response instead of crashing the
+ * server with an unhandled stream error.
+ */
+function sendFile(response, status, filePath) {
+  const stream = createReadStream(filePath);
+  stream.once('open', () => {
+    response.writeHead(status, { 'content-type': contentTypeFor(filePath) });
+    stream.pipe(response);
+  });
+  stream.once('error', () => {
+    if (response.headersSent) {
+      response.destroy();
+      return;
+    }
+    const failed = status === 404 ? [404, 'Not found\n'] : [500, 'Could not read file\n'];
+    response.writeHead(failed[0], { 'content-type': 'text/plain; charset=utf-8' });
+    response.end(failed[1]);
+  });
+}
+
+/** The preview server for a built export directory. Exported for tests. */
+export function createPreviewServer(root) {
+  return createServer((request, response) => {
+    const requestPath = new URL(request.url ?? '/', 'http://localhost').pathname;
+    const filePath = resolveStaticFile(root, requestPath);
+
+    if (!filePath) {
+      const notFound = resolveStaticFile(root, '/404.html');
+      if (notFound) {
+        sendFile(response, 404, notFound);
+        return;
+      }
+      response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+      response.end('Not found\n');
+      return;
+    }
+
+    sendFile(response, 200, filePath);
+  });
+}
+
+function main() {
+  if (!existsSync(outDir)) {
+    console.error(`No build found at ${outDir}. Run "pnpm build" first.`);
+    process.exit(1);
+  }
+
+  const port = Number(process.env.PORT ?? 3000);
+  const host = process.env.HOST ?? 'localhost';
+
+  createPreviewServer(outDir).listen(port, host, () => {
+    console.log(`Serving ${outDir} at http://${host}:${port}`);
+  });
+}
+
+// Importing this file for its helpers must not start a server.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}