session-orchestrator 3.21.0 → 3.22.0

package/skills/session-start/soul.md

@@ -64,6 +64,116 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: explain the WHY behind each recommendation, name the alternatives you rejected and why, spell out unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say. This sets *how*. It binds at every
+level and is not itself a budget: applying it changes word order and word
+choice, not line count. It is the canonical statement for this repo — the
+other three souls (`plan`, `brainstorm`, `grill`) point here rather than
+copying it.
+
+**Write for someone who knows this project but has not seen what you just saw.**
+What he needs to decide stands in the text, not in the file it points at — in
+the AUQ payload and in every finding you post.
+
+This is not "explain it like he is five". The operator owns this repo. He is
+not missing knowledge, he is missing **observation** — he did not watch the
+command you just ran or read the file you just opened. A knowledge framing
+would be factually wrong and condescending at the same time. Write across, not
+down: same expertise as yours, minus your last ten minutes.
+
+#### Plain words, real things
+
+> **Say more simply what actually happens — and introduce nothing that does not exist.**
+>
+> **The test:** delete every noun the system does not contain. If the sentence
+> is still true and complete, it was no analogy. If it collapses, the analogy
+> was load-bearing — replace it with a description of what actually happens.
+
+Five worked cases, in rising difficulty:
+
+1. "Waiting means the other session finishes first." — **allowed.** Sessions
+   and waiting both exist; nothing foreign was introduced.
+2. "Think of the session as a level crossing." — **forbidden.** Delete "level
+   crossing" and nothing is left. Say what happens instead: one session holds
+   `.orchestrator/session.lock`, the other waits for it.
+3. "The token budget is used up." — **allowed.** `TOKEN_BUDGET_EXCEEDED` is a
+   real identifier and "budget" is the system's own word. Adding "…like a tank
+   of fuel" would be forbidden — the tank does not exist.
+4. "Think of the kill-switches as a fuse box." — **forbidden, and wrong on the
+   facts.** Fuses trip on overload; the kill-switches also test elapsed time and
+   confidence. The image sounds helpful and is not. A wrong picture costs more
+   than no picture, because the operator reasons from it.
+5. **Dead metaphors.** A proper name may itself be a metaphor —
+   `pre-bash-destructive-guard` is called a guard — and you use the name as
+   given. Reviving the image is the violation: "the guard will not let it
+   through" invites the operator to picture a guard and then reason from the
+   picture instead of from the hook. Name the identifier, then say what it
+   does: the hook denies the Bash call.
+
+#### Precedence over § "Never traded for brevity"
+
+There is a real collision above: "say it more simply" can water down a precise
+error message. Resolve it in three steps.
+
+1. **Simplifying removes words, never facts.** If a path, a number, an error
+   code, an identifier, or an instruction to act disappears, that is data loss,
+   not simplification — and § "Never traded for brevity" already forbids it.
+2. **When both will not fit in one sentence: precision in the sentence,
+   plainness in the one beside it.** The exact term is never replaced, only
+   accompanied. It is what the operator greps, quotes, and pastes into an issue.
+3. **The mechanical tie-breaker:** could the token you are about to cut ever
+   appear in a `grep`? Then it stays.
+
+Measured 2026-08-22 at `a4f93cf`: of 191 option descriptions in this repo, the
+20 that match the safety lexicon (`SAFETY_PATTERN` in
+`scripts/lib/auq/schema.mjs`) run 26–108 codepoints — all of them under both K6
+length thresholds (`descriptionCharsWarn` 120, `descriptionCharsFail` 150). The
+collision therefore does not occur today. This precedence rule is a precaution,
+not a repair.
+
+#### Worked example — an operator-visible message
+
+`formatBlockReason()` in `scripts/lib/issue-budget.mjs` is what the operator
+sees when the issue cap blocks a creation. Rendered with the collector-issue
+sink, before:
+
+```
+issue-budget: session cap reached — 12/12 issues already created.
+This request was NOT created. It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 will fold all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`. Nothing is lost.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config;
+`mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+After:
+
+```
+Nothing is lost — the issue is parked, and nothing needs doing right now.
+issue-budget: session cap reached — 12/12 issues already created, so this one was NOT created.
+It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 folds all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config; `mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+Three changes, and only these three: the operator's own question — *must I do
+something?* — moved to line 1, carrying "Nothing is lost" up from line 4 where
+he used to reach it last; `will fold` became the active `folds`; and the first
+two lines merged on a causal `so`, which is why "This request" is now "this
+one" — the same subject, already named in the sentence.
+
+The whole word-level diff is four dropped tokens: `This`, `request`, `will`,
+`fold`. Not one of them is a path, a count, a label, a config key, or a mode
+value; every one of those survives character for character. Eight lines before,
+eight lines after — **this register is not a diet.** It is the same facts, in
+the order the reader needs them.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/test-runner/SKILL.md

@@ -216,11 +216,11 @@ Group `medium` and `low` findings and present via a single `AskUserQuestion` cal
 AskUserQuestion({
   questions: [{
     question: `<N> medium/low findings to triage. How to handle?`,
-    header: "Test-runner triage",
+    header: "Triage",
     options: [
       {
         label: "Create all (Recommended)",
-        description: "File <N> new issues, all with label from:test-runner"
+        description: "Files <N> new issues at once, all with label from:test-runner — fastest, and you can still close any of them afterwards."
       },
       {
         label: "Review each",

package/skills/using-orchestrator/SKILL.md

@@ -67,7 +67,7 @@ When two or more candidates score ≥ 0.85 with delta < 0.15, call `AskUserQuest
 AskUserQuestion({
   questions: [{
     question: "Your message matches multiple workflows. Which one did you mean?",
-    header: "Skill Dispatch",
+    header: "Dispatch",
     multiSelect: false,
     options: [
       { label: "<top-skill display name> (Recommended)", description: "<one-line description of what it does>" },

package/skills/wave-executor/wave-loop.md

@@ -1114,20 +1114,40 @@ Before each wave dispatch:
    ```
    The `gates` field (optional) mirrors `enforcement-gates` from Session Config (#77). When present, hooks check each gate individually via `gate_enabled()`. Missing gate entries default to enabled, preserving default behavior.
 2. Validate by piping through `node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs"` (where `$PLUGIN_ROOT` is `$CLAUDE_PLUGIN_ROOT`, `$CODEX_PLUGIN_ROOT`, or `$CURSOR_RULES_DIR` per platform — see `skills/_shared/config-reading.md`). If validation fails (exit 1), fix the JSON based on stderr errors and retry.
-3. **`allowedPaths` is COMPUTED from per-agent scope files — never hand-transcribed (#1020).** Transcribing the union by hand produced 5 scope divergences in ONE session. Three steps, in this order; none of them is a judgement call. Globs stay verbatim (`scripts/*.sh`) — the enforcement hook resolves them at check time.
+3. **`allowedPaths` is COMPUTED from one canonical declaration array — never hand-transcribed (#1020/#1083).** Transcribing either declaration shape or the union by hand produced scope divergences. Globs stay verbatim (`scripts/*.sh`) — the enforcement hook resolves them at check time.
 
-   **3.1 — one file per agent.** Write each agent's "Files:" scope from the session plan, verbatim, as a JSON array of strings to `<state-dir>/filescopes/wave-<N>/<agent-id>.json`. That path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and the File-Scope Injection (#1020) already consume. Do not write a second copy anywhere, and **never to a `$TMPDIR` temp path**: the injector and `hooks/pre-task-scope-disjoint.mjs` need an addressable, wave-keyed location that a temp file cannot be. Reading `$AGENT_FILESCOPE_JSON` as "some temp file" is the one failure that costs no error — the injector finds nothing, no `FILE-SCOPE` block reaches the prompt, `extractScopeFromPrompt` returns `[]`, and the dispatch is ALLOWed exactly as it was before #1020, signal-free. The coordinator's OWN planned direct edits go into `<state-dir>/filescopes/wave-<N>/coordinator.json` in the identical form and take part in both steps below: 2 of those 5 divergences were coordinator-direct edits, for which no agent scope file exists by construction, and the commit guard caught them only at the commit boundary.
+   **3.1 — materialize both declaration shapes once.** Build one JSON array from the session plan, one `{id, files}` record for every agent plus exactly one `coordinator` record for the coordinator's planned direct edits. `files` arrays, their entries and their order are the plan's verbatim declarations. Materialize it ONCE and capture the aggregate-sidecar path:
 
-   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs BEFORE the union of 3.3 exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.
+   ```bash
+   WAVE_SCOPE_RECORDS='[{"id":"W3-I1","files":["scripts/example.mjs"]},{"id":"coordinator","files":["skills/wave-executor/wave-loop.md"]}]'
+   WAVE_SCOPES_SIDECAR="$(
+     printf '%s' "$WAVE_SCOPE_RECORDS" | node "$PLUGIN_ROOT/scripts/materialize-wave-scope.mjs" \
+       --state-dir "$STATE_DIR" --wave "$WAVE"
+   )"
+   [ -n "$WAVE_SCOPES_SIDECAR" ] || { echo "materialize-wave-scope produced no sidecar path" >&2; exit 1; }
+   ```
+
+   The non-empty check is not decoration. The materializer sends every diagnostic
+   to stderr, so a failure leaves `$WAVE_SCOPES_SIDECAR` empty, and an empty path
+   is what step 3.2 would then pass to `--assert-disjoint`. That combination used
+   to exit 0 with the collision gate never run — the same signal-free-ALLOW shape
+   #1083 exists to close. `validate-wave-scope.mjs` now refuses an empty flag
+   value as well, so this guard and that refusal are belt and braces.
+
+   `materialize-wave-scope.mjs` validates the COMPLETE input before writing; it writes `<state-dir>/filescopes/wave-<N>/<agent-id>.json` as each bare `files` array first, then writes `<state-dir>/filescopes/wave-<N>.scopes.json` as the unchanged aggregate record array last. Its human stdout is only that final sidecar path, so the command substitution above is the canonical `$WAVE_SCOPES_SIDECAR`. On error, do not continue with a partial declaration set; correct the plan and run the one command again.
 
-   **3.2 — assert disjointness BEFORE computing the union.** Build the sidecar — an ARRAY of `{id, files}` records (never an object map: a duplicated agent id must stay visible), one record per file written in 3.1, `coordinator.json` included — and run:
+   The per-agent path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and File-Scope Injection (#1020) consume. Never write a `$TMPDIR` copy: it degrades to a signal-free allow when an injector cannot find the addressable wave-keyed file. The coordinator's record is materialized as `coordinator.json` and included in the aggregate, so its direct edits are covered by the two checks below.
+
+   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.
+
+   **3.2 — assert disjointness BEFORE computing the union.** The materialized aggregate is an ARRAY of `{id, files}` records (never an object map: a duplicated agent id must stay visible), including `coordinator.json`. Run:
 
    ```bash
    node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
      --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
    ```
 
-   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, rewrite the affected 3.1 files, re-assert. Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
+   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, re-materialize, re-assert. Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
 
    **3.3 — compute the union.** `--union` is a QUERY MODE that still requires a schema-valid manifest on stdin, so write the skeleton first with `"allowedPaths": []`, then:
 
@@ -1138,6 +1158,8 @@ Before each wave dispatch:
 
    It prints the computed `allowedPaths` array as JSON on stdout **instead of** the manifest echo — one JSON document per run, the flag decides which. Insert that array as `allowedPaths`, then write the final `wave-scope.json`. It already applies the Test-Sibling Expansion below (`expandTestSiblings(unionFileScopes(scopes), { role })`, role read from the manifest), so do not also run the helper by hand.
 
+   **Artifact production, disjointness and union computation are mechanized. Native prompt injection is a separate follow-up.** The materializer creates the durable declarations; the validator proves disjointness and computes the union. It does not install or prove the platform's prompt-injection transport, which remains independently responsible for reading `$AGENT_FILESCOPE_JSON` before dispatch.
+
    **The `--assert-subset` assertion (#796, below) stays unchanged and keeps running.** It checks a DIFFERENT property — each agent's scope ⊆ the union — and a double assignment is structurally invisible to it: a file claimed twice is a subset twice over. `--assert-disjoint` is an addition, never a replacement.
 
    **Test-Sibling Expansion (#970):** an `allowedPaths` entry that names a production file but NOT its test sibling makes the wave's own regression test unwritable — the scope guard then mechanically enforces exactly the inconsistency the quality gate exists to catch. Cross-repo evidence, three occurrences in ONE session: a migrations glob without the SQL-test directory (the regression test could not be written); a lone `.actions.ts` file (the wave's cross-tenant security test stayed red); a dead-export deletion whose importing test lay outside every scope (the suite ended red). Do NOT hand-derive the sibling paths — step 3.3's `--union` runs `expandTestSiblings(…, { role })` for you, so the hook, the validator and this prose state one rule.

package/skills/write-executable-plan/SKILL.md

@@ -163,11 +163,11 @@ Any hit → surface to user via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "The placeholder linter found forbidden strings in the draft plan:\n\n[list each hit with Task number, Step number, and matched text]\n\nHow do you want to proceed?",
-    header: "Placeholder Linter",
+    question: "The draft plan still contains forbidden placeholder strings. How do you want to proceed?",
+    header: "Platzhalter",
     options: [
-      { label: "Fix automatically (Recommended)", description: "I will resolve each hit by filling in the missing specifics before writing the plan." },
-      { label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail." }
+      { label: "Fix automatically (Recommended)", description: "I fill in the missing specifics myself, then write the plan — fastest, and you review the result at hand-off.", preview: "[each hit: Task number, Step number, matched text]" },
+      { label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail.", preview: "[the same hits, one at a time, starting with the first]" }
     ],
     multiSelect: false
   }]
@@ -202,8 +202,8 @@ Present the plan path and task count to the user via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "Executable plan written to docs/plans/YYYY-MM-DD-<slug>.md ([N] tasks, ~[total] min estimated).\n\nHow do you want to execute it?",
-    header: "Plan Hand-off",
+    question: "Plan written to docs/plans/YYYY-MM-DD-<slug>.md — [N] tasks, ~[total] min. How to execute?",
+    header: "Plan fertig",
     options: [
       { label: "Dispatch via wave-executor (Recommended)", description: "Parallel agents execute all tasks simultaneously. Fastest for file-disjoint tasks." },
       { label: "Execute coordinator-direct", description: "One task at a time in this session. Safer for tasks with shared state." },

package/scripts/tests/fixtures/fetch-baseline/sample-rule.md

@@ -1,8 +0,0 @@
-# Sample Baseline Rule (test fixture)
-
-This file is used by scripts/tests/fetch-baseline.bats as the mocked response body
-for the GitLab API raw-file endpoint. It has no real content — presence is enough
-to verify the fetch + cache path.
-
-- Rule ID: TEST-001
-- Purpose: end-to-end fetch verification

package/skills/vault-sync/tests/fixtures/archive-test-vault/90-archive/bad-archived.md

@@ -1,8 +0,0 @@
----
-id: bad-archived
-type: memo
-created: not-a-date
-updated: not-a-date
----
-
-Bad frontmatter — but inside 90-archive, so must be ignored.

package/skills/vault-sync/tests/fixtures/archive-test-vault/live-note.md

@@ -1,8 +0,0 @@
----
-id: live-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Lives outside archive — must be validated.

package/skills/vault-sync/tests/fixtures/broken-frontmatter-vault/bad-type.md

@@ -1,8 +0,0 @@
----
-id: bad-type
-type: memo
-created: 2026-04-13
-updated: 2026-04-13
----
-
-`type: memo` is not in the enum.

package/skills/vault-sync/tests/fixtures/broken-frontmatter-vault/good-note.md

@@ -1,8 +0,0 @@
----
-id: good-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-OK.

package/skills/vault-sync/tests/fixtures/clean-vault/.obsidian/config.md

@@ -1,8 +0,0 @@
----
-id: bogus
-type: memo
-created: not-a-date
-updated: not-a-date
----
-
-If the validator crawls .obsidian/, this file would FAIL. It must be excluded.

package/skills/vault-sync/tests/fixtures/clean-vault/01-projects/foo/projects-baseline.md

@@ -1,10 +0,0 @@
----
-id: projects-baseline
-type: project
-created: 2026-04-01
-updated: 2026-04-13
-status: active
-tags: [meta, infra]
----
-
-Project overview.

package/skills/vault-sync/tests/fixtures/clean-vault/03-daily/daily-2026-04-13.md

@@ -1,8 +0,0 @@
----
-id: daily-2026-04-13
-type: daily
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Today: wrote vault-sync validator.

package/skills/vault-sync/tests/fixtures/clean-vault/README.md

@@ -1,3 +0,0 @@
-# Clean Vault
-
-No frontmatter here — README-style files must be skipped, not errored.

package/skills/vault-sync/tests/fixtures/clean-vault/hello-world.md

@@ -1,11 +0,0 @@
----
-id: hello-world
-type: note
-created: 2026-04-13
-updated: 2026-04-13
-title: Hello World
-tags: [meta, intro]
-status: active
----
-
-A minimal valid note that links to [[daily-2026-04-13]] and [[projects-baseline]].

package/skills/vault-sync/tests/fixtures/dangling-link-vault/has-dangling.md

@@ -1,9 +0,0 @@
----
-id: has-dangling
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-This note links to [[non-existent-target]] which should be flagged as a warning.
-It also links to [[real-target]] which exists.

package/skills/vault-sync/tests/fixtures/dangling-link-vault/real-target.md

@@ -1,8 +0,0 @@
----
-id: real-target
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Real.

package/skills/vault-sync/tests/fixtures/missing-field-vault/missing-id.md

@@ -1,7 +0,0 @@
----
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Missing `id`.

package/skills/vault-sync/tests/fixtures/nested-tag-vault/03-daily/daily-2026-04-13.md

@@ -1,9 +0,0 @@
----
-id: daily-2026-04-13
-type: daily
-created: 2026-04-13
-updated: 2026-04-13
-tags: [area/infrastructure/cleanup, meta/session-log]
----
-
-Daily note using deep-nested Obsidian tags.

package/skills/vault-sync/tests/fixtures/nested-tag-vault/nested-tags-note.md

@@ -1,11 +0,0 @@
----
-id: nested-tags-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
-title: Nested Tags Note
-tags: [meta/schema, status/in-progress, area/infrastructure, session/2026-04-13]
-status: active
----
-
-A note that uses Obsidian nested-tag conventions (slash-separated hierarchy).

package/skills/vault-sync/tests/fixtures/no-frontmatter-vault/README.md

@@ -1,3 +0,0 @@
-# README only
-
-No frontmatter. Must be counted as `files_skipped_no_frontmatter` and not error.

package/skills/vault-sync/tests/fixtures/no-frontmatter-vault/_MOC.md

@@ -1,3 +0,0 @@
-# Map of Content
-
-No frontmatter — this is a plain index.

package/skills/vault-sync/tests/fixtures/with-moc-vault/_MOC.md

@@ -1,11 +0,0 @@
----
-title: Map of Content
----
-
-# Map of Content
-
-This is an index file that intentionally lacks the full note frontmatter
-(no `id`, `type`, `created`, or `updated`). Validator should report errors
-unless this file is excluded via `--exclude "**/_MOC.md"`.
-
-- [[hello-world]]

package/skills/vault-sync/tests/fixtures/with-moc-vault/hello-world.md

@@ -1,11 +0,0 @@
----
-id: hello-world
-type: note
-created: 2026-04-13
-updated: 2026-04-13
-title: Hello World
-tags: [meta, intro]
-status: active
----
-
-A valid note that coexists with a broken `_MOC.md` index file.

package/skills/vault-sync/tests/schema-drift.test.mjs

@@ -1,133 +0,0 @@
-/**
- * schema-drift.test.mjs — Integration tests for sync-vault-schema.mjs
- *
- * Verifies that the vendored schema block in validator.mjs stays in lockstep
- * with the canonical TypeScript source. Tests run the actual script against
- * actual files — no mocks.
- *
- * Run from session-orchestrator root:
- *   pnpm exec vitest run skills/vault-sync/tests/schema-drift.test.mjs
- */
-
-import { describe, it, expect } from 'vitest';
-import { execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { tmpdir } from 'node:os';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Paths relative to this test file
-const SYNC_SCRIPT = join(__dirname, '../../../scripts/sync-vault-schema.mjs');
-const VALIDATOR_MJS = join(__dirname, '../validator.mjs');
-const CANONICAL = join(
-  __dirname,
-  '../../../../projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts',
-);
-// Tests below shell out to sync-vault-schema.mjs, which by default reads
-// the canonical schema from a sibling projects-baseline checkout. In CI
-// (and on any contributor machine without that checkout) the canonical
-// file is absent, so we skip these integration tests. The schema-drift
-// CI stage runs the script directly against a freshly cloned canonical.
-const HAS_CANONICAL = existsSync(CANONICAL);
-
-const SENTINEL_BEGIN = 'BEGIN GENERATED SCHEMA';
-const SENTINEL_END = 'END GENERATED SCHEMA';
-
-/**
- * Run sync-vault-schema.mjs with given args.
- * Returns { status, stdout, stderr }.
- * Never throws — captures non-zero exits via try/catch.
- */
-function runScript(args = []) {
-  try {
-    const stdout = execFileSync(process.execPath, [SYNC_SCRIPT, ...args], {
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return { status: 0, stdout, stderr: '' };
-  } catch (err) {
-    return {
-      status: err.status ?? 1,
-      stdout: err.stdout ?? '',
-      stderr: err.stderr ?? '',
-    };
-  }
-}
-
-describe.skipIf(!HAS_CANONICAL)('sync-vault-schema.mjs', () => {
-  it('idempotency — running --write twice produces no diff between runs', () => {
-    // Read validator.mjs before any writes
-    const before = readFileSync(VALIDATOR_MJS, 'utf-8');
-
-    // First --write
-    const first = runScript(['--write']);
-    expect(first.status, `first --write failed: ${first.stderr}`).toBe(0);
-
-    // Read after first write
-    const afterFirst = readFileSync(VALIDATOR_MJS, 'utf-8');
-    expect(afterFirst).toBe(before);
-
-    // Second --write
-    const second = runScript(['--write']);
-    expect(second.status, `second --write failed: ${second.stderr}`).toBe(0);
-
-    // Read after second write
-    const afterSecond = readFileSync(VALIDATOR_MJS, 'utf-8');
-    expect(afterSecond).toBe(before);
-  });
-
-  it('check-mode-clean — --check exits 0 when canonical and vendored are in sync', () => {
-    const result = runScript(['--check']);
-    expect(result.status, `--check failed unexpectedly: ${result.stderr}`).toBe(0);
-    expect(result.stdout).toContain('no drift');
-  });
-
-  it('check-mode-detects-drift — --check exits 1 with diff when canonical differs', () => {
-    // Build a temporary fake canonical with a different max for the id field
-    const rand = Math.random().toString(36).slice(2);
-    const tmpDir = join(tmpdir(), `sync-vault-schema-test-${rand}`);
-    mkdirSync(tmpDir, { recursive: true });
-    const fakeCanonical = join(tmpDir, 'vault-frontmatter.ts');
-
-    // Read the real canonical and alter it: change .max(128) to .max(256) for id
-    const realCanonical = readFileSync(CANONICAL, 'utf-8');
-    const altered = realCanonical.replace('.max(128)', '.max(256)');
-    writeFileSync(fakeCanonical, altered, 'utf-8');
-
-    try {
-      const result = runScript(['--check', '--canonical', fakeCanonical]);
-      expect(result.status, 'expected exit 1 for drift').toBe(1);
-      // Diff should mention the changed value
-      expect(result.stderr).toMatch(/256|drift/);
-    } finally {
-      rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  it('failure-mode-missing-canonical — exits 2 with clear message when canonical not found', () => {
-    const rand = Math.random().toString(36).slice(2);
-    const fakePath = join(tmpdir(), `does-not-exist-${rand}.ts`);
-
-    const result = runScript(['--check', '--canonical', fakePath]);
-    expect(result.status, 'expected exit 2 for missing file').toBe(2);
-    expect(result.stderr).toContain(fakePath);
-  });
-
-  it('sentinel-presence — validator.mjs contains both sentinel markers exactly once in correct order', () => {
-    const content = readFileSync(VALIDATOR_MJS, 'utf-8');
-
-    // Count occurrences
-    const beginCount = (content.match(/BEGIN GENERATED SCHEMA/g) ?? []).length;
-    const endCount = (content.match(/END GENERATED SCHEMA/g) ?? []).length;
-
-    expect(beginCount, 'BEGIN GENERATED SCHEMA must appear exactly once').toBe(1);
-    expect(endCount, 'END GENERATED SCHEMA must appear exactly once').toBe(1);
-
-    // BEGIN must appear before END
-    const beginPos = content.indexOf(SENTINEL_BEGIN);
-    const endPos = content.indexOf(SENTINEL_END);
-    expect(beginPos, 'BEGIN sentinel must appear before END sentinel').toBeLessThan(endPos);
-  });
-});