session-orchestrator 3.24.0 → 4.0.1

package/commands/session.md

@@ -1,6 +1,6 @@
 ---
-description: Start a development session (housekeeping, feature, deep)
-argument-hint: "[housekeeping|feature|deep]"
+description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 
 # Session Start
@@ -9,7 +9,22 @@ You are beginning a new development session. The user has invoked `/session` wit
 
 **Default rationale (measured, not assumed):** `deep` is the default because it is what operators actually run — 77.3 % of 489 recorded sessions across 5 repos, and 115 of 228 (50.4 %) in this repo's own `.orchestrator/metrics/sessions.jsonl`. The former `feature` default made the majority case the one that had to be typed out every time. A `deep` default costs a downgrade keystroke in the minority case; a `feature` default cost an upgrade keystroke in the majority case.
 
-**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then fall back to `deep`.
+**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. `ultradeep` is additionally accepted as an ARGUMENT ALIAS (see below); it is not a fourth type. If `$ARGUMENTS` is not empty and does not match any valid type or the alias, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep (alias: ultradeep)." Then fall back to `deep`.
+
+### Argument alias: `ultradeep` (PRD `docs/prd/2026-09-06-ultradeep-session-profile.md`)
+
+`/session ultradeep` is an alias, NOT a fourth `session_type`. Resolve it to TWO STATE.md frontmatter values and then continue exactly as a `deep` session would:
+
+```yaml
+session-type: deep          # what every downstream consumer sees
+session-profile: ultradeep  # the only place the alias survives
+```
+
+- **`session-type` NEVER becomes `ultradeep`.** The value is a closed set in `scripts/lib/session-schema/constants.mjs` (`VALID_SESSION_TYPES`) and in `scripts/lib/wave-sizing.mjs`; a fourth member would degrade silently in two places (`scripts/lib/telemetry/schema.mjs` maps an unknown type to `"other"`, `scripts/lib/session-close-backfill.mjs` labels it `housekeeping`). The alias exists so that no closed set has to change.
+- **`session-profile` is optional and absent by default.** A plain `/session deep` writes NO `session-profile` key. Absent means "no profile" — never write an empty string, `none`, or `null` to mean absence. Read/write helpers: `readSessionProfile` / `setSessionProfile` in `scripts/lib/state-md.mjs`.
+- **What the profile changes** is the WAVE SHAPE, not the session type: 7 waves with a coordinator-direct Synthesis-Gate at wave 2. See `skills/session-plan/SKILL.md` § Role-to-Wave Mapping and `skills/wave-executor/SKILL.md` § Ultradeep Profile.
+- **Precondition.** The profile needs 7 waves. If Session Config sets `waves` below 7, do NOT silently plan 5 waves under an ultradeep label — name the conflict to the user and let them raise `waves` or drop the alias.
+- **Budgets are deliberately not implemented yet** (PRD § 7): no `ultradeep.max-*` key is read anywhere. Do not invent one; the PRD defers thresholds until three runs have been measured.
 
 > **Not read from Session Config.** There is deliberately no `session-type:` (or equivalent) key in the `## Session Config` block — `scripts/lib/config.mjs` `parseSessionConfig()` does not emit one, so any such key in a repo's CLAUDE.md (or its Codex CLI equivalent AGENTS.md) is inert prose. The `session-type:` scalar that IS live lives in STATE.md frontmatter (read by `scripts/print-applicable-rules.mjs` for rule mode-gating) and is written per session, not configured per repo. Do not reintroduce a Session Config key here without wiring it into the parser first.
 

package/docs/README.md

@@ -98,6 +98,10 @@ Two things worth knowing about this split:
 | `docs/plans/` | Active work document | `/write-executable-plan` artifacts for in-progress work. May not exist when nothing is mid-plan. |
 | `docs/_private/`, `docs/specs/` | Local-only (gitignored) | Operator scratch space; never tracked, out of scope for this classification. |
 
+### Superseded design notes
+
+Because `docs/specs/` is gitignored, a correction written INTO a spec can never be committed — so the correction lives here instead. `docs/specs/2026-05-26-parallel-aware-sessions-design.md` (parallel-aware sessions) specifies PID-based lock liveness (`stale-pid-dead`). That is **superseded**: liveness is heartbeat-age based since #1137 (`isLockLive`; `acquire()` knows only `stale-heartbeat`), and the recorded PID is consulted nowhere since #1151 — it was the PID of the short-lived subprocess that wrote the lock, dead within a second. Read the local spec only with that correction applied.
+
 ## See Also
 
 - `docs/prd/2026-07-08-docs-public-split.md` — the epic that established this split (S1–S8, issues #775–#782).

package/{agents/AGENTS.md → docs/agent-authoring.md}

@@ -1,37 +1,30 @@
----
-name: agents-authoring-spec
-description: NOT A DISPATCHABLE AGENT — never select this. It is the authoring specification that the agent definitions in this directory must follow, loaded as a nested instruction file. Claude Code's plugin loader registers every agents/*.md as an agent by directory convention, and the manifest's `agents` key is additive-only, so it cannot exclude a path. Without this frontmatter the file registered as an unnamed agent with FULL tool access; the minimal `tools` line below is what bounds that. If you need agent-authoring rules, read this file — do not dispatch it.
-tools: Read
----
+<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. -->
 
-# `agents/` — Sub-Agent Authoring Conventions
+# Sub-Agent Authoring Conventions (`agents/**`)
 
-> Nested instruction file for the `agents/` subtree. Claude Code / Cursor IDE
-> and Codex CLI both load this additively when working on files in this
-> directory (root `CLAUDE.md` for the big picture, this file for local
-> conventions). Resolution rule:
+> Authoring spec for the sub-agent definitions in `agents/`. Read it together
+> with the root `CLAUDE.md` (big picture) and, when working under `agents/`,
+> whatever nested instruction file that subtree carries. Resolution rule:
 > [`../skills/_shared/instruction-file-resolution.md`](../skills/_shared/instruction-file-resolution.md).
 >
-> This is **not** an agent definition — it is the authoring spec the agent
-> `*.md` definitions in this directory must follow. The plugin validator
-> (`scripts/lib/validate/check-agents.mjs`) excludes `AGENTS.md` / `CLAUDE.md`
-> from agent-frontmatter validation by name, and `measureDescriptionSurface`
-> excludes them from its walked corpus (#878).
->
-> **Claude Code's plugin loader makes no such exception.** It registers every
-> `agents/*.md` as a dispatchable agent by directory convention, and the
-> manifest's `agents` key is documented as *additive* ("in addition to those in
-> the `agents/` directory"), so it cannot exclude a path. With no frontmatter
-> this file therefore registered as an agent named `AGENTS` with **full tool
-> access**. The frontmatter above is the containment: it names the file for what
-> it is, states in the `description` that it must never be dispatched, and caps
-> `tools` at `Read`. Do not remove it — and if you add another non-agent doc to
-> this directory, give it the same treatment.
+> **This spec lives in `docs/`, not in `agents/`, on purpose.** Claude Code's
+> plugin loader registers every `agents/*.md` as a dispatchable agent by
+> directory convention, and the manifest's `agents` key is documented as
+> *additive* ("in addition to those in the `agents/` directory"), so it cannot
+> exclude a path. As `agents/AGENTS.md` this file was therefore a registered
+> agent — first an unnamed one with **full tool access**, later a contained one
+> whose pseudo-frontmatter capped `tools` at `Read`. Moving it out of the
+> directory removes the registration rather than bounding it. The same applies
+> to any future non-agent doc: put it under `docs/`, never in `agents/`.
+> (`scripts/lib/validate/check-agents.mjs` still excludes `AGENTS.md` /
+> `CLAUDE.md` by name, and `measureDescriptionSurface` still excludes them from
+> its walked corpus (#878) — both now vacuous for this file, and the safety net
+> for anyone who reintroduces one.)
 >
 > Sibling spec: for `.claude/rules/*.md` frontmatter (conditional loading via
 > globs/mode/host-class/expiry, plus the never-always-on invariant for
 > auto-generated rules), see the canonical authoring spec
-> [`docs/rule-authoring.md`](../docs/rule-authoring.md).
+> [`docs/rule-authoring.md`](./rule-authoring.md).
 
 ## Local Validation Commands
 

package/docs/baseline.md

@@ -0,0 +1,67 @@
+# The projects-baseline Relationship
+
+**One line:** `projects-baseline` is a **private, optional** companion repository that
+holds the operator's canonical rule and schema corpus. session-orchestrator reads
+from it when it is present and degrades to a documented fallback when it is not.
+Nothing in this plugin requires it, and no public consumer needs to obtain it.
+
+## What it is
+
+A separate git repository (not vendored, not a submodule, not on npm) carrying:
+
+- `packages/zod-schemas/src/vault-frontmatter.ts` — the canonical Zod schema for
+  Obsidian vault note frontmatter.
+- `templates/shared/.vault.yaml.template` — the canonical `.vault.yaml` template.
+- A `.claude/rules/` corpus. Measured: **26 rule files, all using `paths:`
+  frontmatter, 0 using `globs:`** (`scripts/lib/rule-loader.mjs` module doc;
+  restated in `scripts/lib/validate/check-rules.mjs`). That corpus is the reason
+  `paths:` exists as a same-shape alias for `globs:` at all (#795) — the fleet's
+  rules are read **from the baseline**, not from this plugin, so the plugin had to
+  learn the baseline's frontmatter convention rather than the other way round.
+
+## How the plugin finds it
+
+Never by a hardcoded path. Resolution is host-local, most specific first:
+
+1. `SO_BASELINE_PATH` environment variable
+2. `owner.yaml` `paths.baseline-path` (`~/.config/session-orchestrator/owner.yaml`,
+   host-local, never committed — see `docs/owner-config-schema.md`)
+3. a sibling checkout at `<repoRoot>/../projects-baseline`
+4. `~/Projects/projects-baseline` (legacy default)
+
+Tiers 1–2 go through `resolveHostPath('baseline-path', …)` in
+`scripts/lib/config/host-paths.mjs`. `scripts/lib/vault-backfill/template.mjs`
+additionally honours `PROJECTS_BASELINE_DIR` above all four, for back-compat.
+
+## The four hard-runtime touchpoints, and what each degrades to
+
+| Touchpoint | Reads / writes | Without a baseline |
+|---|---|---|
+| `scripts/lib/frontmatter-guard.mjs` | the canonical vault-frontmatter Zod schema | `readVaultSchema()` → `null`; `generateFrontmatterSnippet()` falls back to an in-module enum set mirroring `skills/vault-sync/validator.mjs` and warns ONCE on stderr; `computeSchemaHash()` → `null` (never the empty-string hash) |
+| `scripts/lib/vault-backfill/template.mjs` | `.vault.yaml.template` | `loadTemplate()` calls `dieFn(2, …)` with a message naming `owner.yaml paths.baseline-path`, `SO_BASELINE_PATH`, `PROJECTS_BASELINE_DIR`, and the sibling-checkout convention. Only `scripts/vault-backfill.mjs` is affected; nothing else aborts |
+| `scripts/sync-vault-schema.mjs` | `--check` drift guard against the canonical schema | exits 2 (missing file). It is a maintenance script, never on a session path |
+| `scripts/lib/reconcile/writer.mjs` + `scripts/lib/session-end/phase-skip.mjs` | writes rule proposals into the baseline (`reconcile.targets` containing `baseline`) | `baselineRoot` absent ⇒ the `baseline` target is a **no-op**; `repo-local` (the default target) is unaffected |
+
+`scripts/promote-vault-strict.mjs` also uses a baseline template and already ships
+an explicit `--no-baseline` opt-out.
+
+## The public fallback
+
+A repository bootstrapped without the baseline is a normal, supported outcome —
+`skills/bootstrap/public-fallback.md` owns that path. `bootstrap.lock` records
+which source produced the scaffold in its `source:` field:
+
+- `claude-init` — `claude init` ran successfully (Claude Code fast path)
+- `plugin-template` — the plugin's own template was copied (every other case)
+- `projects-baseline` — the private baseline was present and used
+
+The first two are the **public** values. A consumer repo that shows either is
+fully bootstrapped; the baseline adds the operator's private corpus on top, it
+does not gate the scaffold.
+
+## See also
+
+- `docs/owner-config-schema.md` — `owner.yaml` schema, including `paths.baseline-path`
+- `docs/rule-authoring.md` — `paths:` / `globs:` frontmatter
+- `skills/bootstrap/public-fallback.md` — the no-baseline bootstrap path
+- `skills/frontmatter-guard/SKILL.md` — the schema-source resolution table

package/docs/ci-setup.md

@@ -14,62 +14,78 @@ project-level Job Token allowlists are explicitly configured — an admin action
 in the foreign project that cannot be scripted from here. The fix is a deploy
 token or PAT stored as the masked CI variable `SCHEMA_DRIFT_TOKEN`.
 
-> **Current decision (2026-08-28, #1062): amber is the accepted normal state.**
-> `glab variable list` on this project returns zero CI variables — no
-> `SCHEMA_DRIFT_TOKEN` is set — so every pipeline runs the job to exit 3
-> (`NOT VERIFIED`) and `pipeline-gate` prints the amber line. This is a
-> deliberate operator choice, not a defect: the job is correctly fail-loud
-> (exit taxonomy below), the vendored schema is compared manually at each
-> baseline refresh (#1100), and no token is rotated for a check that runs
-> against a private project of our own. Session-start's CI banner keeps
-> reporting the soft failure on purpose (`allow_failure` jobs are invisible
-> at pipeline level, which is what that banner exists to surface). Revisit
-> trigger: the first time a vendored-schema drift ships unnoticed, or when
-> the baseline gains a public mirror — then set the token (Option A below)
-> and flip `SCHEMA_DRIFT_OPTIONAL` at both sites.
-
-### Activation status (measured 2026-09-02)
-
-**Update, same day:** the token below was **revoked** — an unused credential is a
-liability per SEC-005's secrets-lifecycle discipline, and leaving a live,
-never-set-as-a-CI-variable token sitting in `infrastructure/projects-baseline`
-served no purpose once the control run below had already answered the
-question it was minted for. Re-minting it (same `glab api --method POST … --input -`
-recipe as Option A step 1) is now **Step 0** of the re-activation sequence
-below, not an assumed-still-valid token.
-
-A Project Access Token was provisioned today, scoped exactly as Option A
-below recommends:
+> **Armed (2026-09-03, #1175): the hard gate is live.** #531 landed upstream
+> — `infrastructure/projects-baseline` commit `cb9ec97` adds `peer-card`,
+> `board`, and `source-repo` to the canonical schema (the issue's AC named
+> only `peer-card`; the close comment widened scope to all three values
+> already vendored ahead here). That closed the vendored-schema divergence
+> which had blocked activation since 2026-09-02; `skills/vault-sync/
+> validator.mjs` was regenerated and `node scripts/sync-vault-schema.mjs
+> --check` now exits 0. The Project Access Token was re-minted (id 53, see
+> § Activation status below), the masked `SCHEMA_DRIFT_TOKEN` CI variable is
+> set on this project, and `SCHEMA_DRIFT_OPTIONAL` is `"false"` at both
+> sites in `.gitlab-ci.yml` — a missing or expired token now hard-fails the
+> pipeline (exit 4) instead of printing the amber `NOT VERIFIED` line that
+> was the accepted state under the prior (2026-08-28, #1062) decision. Both
+> directions were proven before the flip — see below. Revisit trigger for
+> the token itself: expiry (2027-09-01) or a scope/rotation need — see
+> § Rotation / re-arm sequence.
+
+### Activation status (token re-minted 2026-09-03, id 53)
+
+The Project Access Token was revoked on 2026-09-02 once a control run had
+answered the question it was minted for — an unused credential is a
+liability per SEC-005's secrets-lifecycle discipline. That control run had
+also surfaced the real reason activation was still blocked:
+`skills/vault-sync/validator.mjs`'s `vaultNoteTypeSchema` enum carried
+`peer-card` and `board`, and `vaultFrontmatterSchema` carried
+`source-repo: z.string().optional()`, none of which the canonical
+`infrastructure/projects-baseline` source had yet — the documented
+vendor-ahead state (`scripts/sync-vault-schema.mjs` header, "Vendor-ahead
+state (2026-05-23, #503, I5)"), tracked as upstream-sync-debt in issue #531
+(#503 itself was already closed).
+
+**#531 landed upstream** as commit `cb9ec97`: `vaultNoteTypeSchema` gained
+`peer-card` and `board`; `vaultFrontmatterSchema` gained `source-repo:
+z.string().optional()`. With the canonical source caught up,
+`node scripts/sync-vault-schema.mjs --check` exits 0 — no drift.
+
+**Token, re-minted:**
 
 - **Name:** `session-orchestrator-ci-schema-drift`
 - **Project:** `infrastructure/projects-baseline` (id 52) — the TARGET repo,
   not this one
+- **Token id:** 53
 - **Scopes:** `read_repository`
 - **Access level:** Reporter (20)
 - **Expires:** 2027-09-01
 
-The masked `SCHEMA_DRIFT_TOKEN` CI variable on this project (id 74) was set
-with that token, then **removed again**. A control run with the token set
-confirmed the clone step authenticates correctly — but the drift check itself
-then failed for a real, already-known reason:
-`skills/vault-sync/validator.mjs`'s `vaultNoteTypeSchema` enum carries
-`peer-card` and `board`, and the canonical `infrastructure/projects-baseline`
-source does not have either yet. This is the documented vendor-ahead state
-(`scripts/sync-vault-schema.mjs` header, "Vendor-ahead state (2026-05-23,
-#503, I5)") and tracked as upstream-sync-debt in issue #531 (#503 itself is
-closed). With the variable set and `SCHEMA_DRIFT_OPTIONAL` still `"true"`,
-this exit-1 `DRIFT` is a **hard** failure — it is not in
-`allow_failure.exit_codes: [3]` — so leaving the variable set today would turn
-the next push red for a fact already tracked in #531, not for a new defect.
-The variable was removed rather than left set; activation stays blocked until
-the canonical enum gains both values.
-
-**Re-activation sequence once #531 lands upstream:**
-
-0. **Re-mint the token** — it was revoked (see § Activation status above). Run
-   the same `glab api --method POST … --input -` recipe as Option A step 1,
-   against the TARGET project (id 52), and copy the response's `token` field
-   immediately — it is shown exactly once.
+The masked `SCHEMA_DRIFT_TOKEN` CI variable is set on this project (id 74),
+**not** Protected — same reasoning as Option A step 3 below.
+
+**Proof pipelines, both directions, run before the flip:**
+
+- **GREEN** — pipeline 8358 @ `dc9522dd` (branch
+  `proof/1175-schema-drift-green`): job `schema-drift-check` #84625 ran with
+  the token, cloned the baseline, and printed `RESULT: IN-SYNC (exit 0)`;
+  `pipeline-gate` succeeded.
+- **RED** — pipelines 8355–8357 @ `bca78dae` (branch
+  `proof/1175-schema-drift-red`, a deliberately bogus enum value injected
+  into the vendored copy): `sync-vault-schema.mjs` reported drift, the job
+  failed with exit 1 — outside `allow_failure.exit_codes: [3]` — and
+  `pipeline-gate` never ran.
+
+With both proofs recorded, `SCHEMA_DRIFT_OPTIONAL` is `"false"` at both
+sites in `.gitlab-ci.yml` — `schema-drift-check` and `pipeline-gate`.
+`tests/ci/schema-drift-check.test.mjs` pins the committed value on both
+jobs, so a half-revert or a template refresh flipping one site back to
+`"true"` fails the suite locally, not silently in a pipeline.
+
+**Rotation / re-arm sequence** (token expiry or replacement):
+
+0. **Re-mint the token.** Run the same `glab api --method POST … --input -`
+   recipe as Option A step 1, against the TARGET project (id 52), and copy
+   the response's `token` field immediately — it is shown exactly once.
 1. `read -rs TOKEN` at the prompt (no echo), then pipe it into `glab variable
    set` rather than passing it as a `--value` argument — a value passed on the
    command line is visible to any other process on the host via `ps`, while
@@ -92,10 +108,12 @@ the canonical enum gains both values.
    `RESULT: IN-SYNC` — and confirm the job DURATION is well over 20 seconds
    (see the pipeline-6815 warning above). A fast "success" is the exit-3
    soft-skip in disguise, not a real run.
-3. Flip `SCHEMA_DRIFT_OPTIONAL` to `"false"` at **both** sites —
-   `schema-drift-check` and `pipeline-gate` — in one commit.
-   `tests/ci/schema-drift-check.test.mjs` already asserts the two values are
-   equal, so no test edit is needed to enforce the flip.
+3. `SCHEMA_DRIFT_OPTIONAL` stays `"false"` at **both** sites —
+   `schema-drift-check` and `pipeline-gate`. A rotation replaces only the
+   credential, never the flag; if the flag was ever reverted for an
+   emergency, flip it back to `"false"` at both sites in one commit —
+   `tests/ci/schema-drift-check.test.mjs` pins the committed value on both
+   jobs, so a half-flip fails the suite locally.
 4. Local counter-probe before trusting the pipeline: clone
    `infrastructure/projects-baseline` with the token, make a throwaway copy of
    `packages/zod-schemas/src/vault-frontmatter.ts` with one field
@@ -134,11 +152,12 @@ let alone diff a schema against it. Issue #933.
 
 ```yaml
 variables:
-  SCHEMA_DRIFT_OPTIONAL: "true"
+  SCHEMA_DRIFT_OPTIONAL: "false"
 ```
 
-It is the review-visible declaration that "no token" is *currently* an accepted
-state. The behaviour matrix:
+It is the review-visible declaration that "no token" is *no longer* an
+accepted state — armed 2026-09-03 (#1175, see § Activation status above).
+The behaviour matrix:
 
 | `SCHEMA_DRIFT_TOKEN` | `SCHEMA_DRIFT_OPTIONAL` | Exit | State | Pipeline effect |
 |---|---|---|---|---|
@@ -169,14 +188,41 @@ note, not a blocker: the sentinels are intact today, and the fix — if it is
 ever needed — is giving `sync-vault-schema.mjs`'s malformed-sentinel case a
 distinct exit code, not a change here.
 
-**After completing the token setup below, change `SCHEMA_DRIFT_OPTIONAL` to
-`"false"` in `.gitlab-ci.yml`** — in **both** places: the `schema-drift-check`
+**This is what the armed state looks like.** `SCHEMA_DRIFT_OPTIONAL` is
+`"false"` in `.gitlab-ci.yml` at **both** places: the `schema-drift-check`
 job and `pipeline-gate`. One flag, two enforcement points;
-`tests/ci/schema-drift-check.test.mjs` asserts the mirroring, so a half-flip
-fails the suite locally rather than silently leaving one point advisory. The
-flip is what converts a missing token from a tolerated warning into a hard red,
-and it is the whole point of the flag: the opt-out is a line in a reviewed file,
-not the accidental side effect of an unset CI variable.
+`tests/ci/schema-drift-check.test.mjs` asserts the mirroring AND pins the
+literal `"false"` value on both jobs, so a half-flip — or a full revert —
+fails the suite locally rather than silently leaving one point advisory. A
+missing or expired token now hard-fails the pipeline (exit 4) instead of the
+tolerated amber warning — that is the whole point of the flag: the opt-out is
+a line in a reviewed file, not the accidental side effect of an unset CI
+variable.
+
+**To switch it back to amber temporarily** (a token rotation window, or
+taking the check offline for an emergency): set `SCHEMA_DRIFT_OPTIONAL` to
+`"true"` at **both** sites, in one commit — the same mirrored-pair discipline
+applies in reverse, and the same test catches a half-revert. Re-arm by
+flipping both sites back to `"false"` once the reason for the amber window is
+resolved; see § Rotation / re-arm sequence above for the token side of that
+operation.
+
+**Fork / external-contributor MR caveat.** `.gate-rules` (`.gitlab-ci.yml:74`)
+includes `if: $CI_PIPELINE_SOURCE == "merge_request_event"`, so a merge
+request pipeline runs `schema-drift-check` regardless of who opened it — but
+GitLab does not pass the target project's masked CI/CD variables to a
+pipeline running a **forked** project's code, by design, so that an untrusted
+fork cannot exfiltrate a secret. A fork/contributor MR therefore cannot read
+`SCHEMA_DRIFT_TOKEN` even though the variable is set and unprotected on this
+project, and with `SCHEMA_DRIFT_OPTIONAL: "false"` that reads as a genuinely
+missing token: exit **4** (`MISCONFIGURED`), a hard pipeline failure — not the
+amber `SKIPPED` a same-project branch would get. The accepted mitigation is
+either of: a maintainer re-runs the pipeline from within this project (e.g.
+pushing the same commit to a branch here, where the variable IS available),
+or a maintainer temporarily sets `SCHEMA_DRIFT_OPTIONAL: "true"` on that one
+MR/branch for the duration of review. Do not weaken the committed default in
+`.gitlab-ci.yml` for this — it stays `"false"` at both sites per the armed
+state above.
 
 > **Before you flip it, run ONE pipeline with the token present while
 > `SCHEMA_DRIFT_OPTIONAL` is still `"true"`, and check the job's DURATION.**