session-orchestrator 3.23.0 → 4.0.0

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,25 +14,124 @@ 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.
+> **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 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
+   stdin is not:
+
+   ```bash
+   read -rs TOKEN
+   printf '%s' "$TOKEN" | glab variable set SCHEMA_DRIFT_TOKEN \
+     -R infrastructure/session-orchestrator --masked
+   ```
+
+   **Not** `--protected`: `.gate-rules` (`.gitlab-ci.yml:74`) runs the job
+   on every branch and every MR pipeline, and a protected-only variable would
+   silently reproduce the exit-5 `UNAVAILABLE` failure on every unprotected
+   branch. (`glab variable set --help` documents stdin piping directly —
+   `cat file.txt | glab variable set SERVER_TOKEN` — but no `-`/dash value
+   for `--value`; the flag only accepts a literal string, so omitting it
+   entirely and piping the value is the only way to keep the token off argv.)
+2. Push an ordinary commit and read the `schema-drift-check` job log for
+   `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. `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
+   deliberately edited, then run
+   `node scripts/sync-vault-schema.mjs --check --canonical <path-to-edited-copy>`
+   — expect exit 1 with a diff naming the edited field. That confirms the
+   check diffs real content rather than passing on a broken comparison.
+
+Per `.claude/rules/security.md` § SEC-005, this token's lifecycle belongs in
+`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present
+in this repo (measured 2026-09-02: no `.claude/docs/` directory tracked), so
+the inventory is not adopted here and this section remains the sole record.
 
 ### Required CI variable
 
 | Variable | Type | Mask | Protect | Value |
 |---|---|---|---|---|
-| `SCHEMA_DRIFT_TOKEN` | Variable | Yes | Optional | deploy token or PAT (see below) |
+| `SCHEMA_DRIFT_TOKEN` | Variable | Yes | No | Project Access Token or PAT — see Option A/B below |
 
 If `SCHEMA_DRIFT_TOKEN` is **not set**, the job prints a `NOT VERIFIED` notice
 and exits **3** — which `allow_failure.exit_codes` renders as an amber *warning*,
@@ -53,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 |
 |---|---|---|---|---|
@@ -76,14 +176,53 @@ a schema diff that does not exist. Only 3 is listed in
 outcome also prints its own `[schema-drift] RESULT: <STATE>` line, so the job log
 answers "what happened" without the reader having to know this table.
 
-**After completing the token setup below, change `SCHEMA_DRIFT_OPTIONAL` to
-`"false"` in `.gitlab-ci.yml`** — in **both** places: the `schema-drift-check`
+**Caveat — a second, narrower exit-3 collision (do not change the YAML for
+it).** `scripts/sync-vault-schema.mjs` has its own exit 3, for a different
+condition: malformed sentinel comments in `validator.mjs` (only one of
+`begin`/`end` present). If `--check` ever hit that branch, it would return
+exit 3 from the tool itself — and `allow_failure.exit_codes: [3]` reads the
+shell's final exit code, not which tool produced it, so a genuine tooling
+defect (broken sentinels) would render as the same amber "no token, declared
+optional" warning that the missing-token guard produces. This is a caveat to
+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.
+
+**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.**
@@ -98,35 +237,93 @@ not the accidental side effect of an unset CI variable.
 > exactly this failure — pipeline 6815 reported SUCCESS in 17 s having checked
 > nothing (issue #933).
 
-### Option A — Deploy Token (recommended, least-privilege)
-
-1. Open `infrastructure/projects-baseline` on your GitLab instance.
-2. Go to **Settings → Repository → Deploy tokens**.
-3. Click **Add token**:
-   - **Name:** `session-orchestrator-ci-schema-drift`
-   - **Expires at:** set a reminder (e.g. 1 year); rotate before expiry
-   - **Scopes:** check `read_repository` only
-4. Copy the generated token value (shown once).
-5. Open `session-orchestrator` on GitLab.
-6. Go to **Settings → CI/CD → Variables → Add variable**:
-   - **Key:** `SCHEMA_DRIFT_TOKEN`
-   - **Value:** paste the deploy token
-   - **Type:** Variable
-   - **Masked:** Yes
-   - **Protected:** Optional (enable if you only need it on protected branches)
-7. Save.
+### Option A — Project Access Token (recommended — works with the current clone URL)
+
+GitLab resolves a **deploy token** by its own fixed username
+(`gitlab+deploy-token-<n>`, or a custom username if one was set at creation).
+The job's clone step hardcodes the login as `oauth2:${SCHEMA_DRIFT_TOKEN}`
+(`.gitlab-ci.yml` ~:652) — `oauth2` is the username GitLab expects for a
+Personal or Project Access Token, not for a deploy token. A deploy token's
+value paired with that hardcoded username fails authentication at clone time
+and surfaces as exit 5 `UNAVAILABLE`, which reads as a network/credential
+problem rather than "wrong username" (see the demoted Deploy Token option
+below). Tokens with **PAT semantics** — GitLab accepts any username alongside
+the token value — authenticate correctly with this clone URL: a Personal
+Access Token, or, least-privilege, a **Project Access Token** scoped to the
+TARGET project (`infrastructure/projects-baseline`). A Project Access Token
+is preferred over a personal PAT for the same reason the deploy token used to
+be recommended: it belongs to the project, not a person, and survives staff
+changes.
+
+1. Create the token via API against the TARGET project (id 52) — GitLab has
+   no path to create a Project Access Token FOR a project from outside that
+   project's own Settings UI, so use `glab api`:
+
+   ```bash
+   glab api --hostname "$GITLAB_HOST" -X POST "projects/52/access_tokens" \
+     -H 'Content-Type: application/json' --input - <<'JSON'
+   {"name":"session-orchestrator-ci-schema-drift","scopes":["read_repository"],"access_level":20,"expires_at":"2027-09-01"}
+   JSON
+   ```
+
+   `--input -` plus the explicit `Content-Type: application/json` header is
+   required because the payload has a nested type (`scopes` is a JSON array),
+   which `glab api`'s `-f`/`-F` flag form cannot express. `access_level: 20`
+   is Reporter — the lowest access level that can read repository content.
+   `expires_at` is an operator choice, not a fixed value; the token created
+   for this document's own dry run (2026-09-02) was set 1 year out
+   (`2027-09-01`) — rotate before expiry.
+
+2. The response's `token` field holds the token value and is **shown exactly
+   once** — copy it immediately; GitLab will not display it again.
+
+3. Store it in `session-orchestrator` CI/CD variables as `SCHEMA_DRIFT_TOKEN`.
+   Prefer stdin over `--value` — a value passed as a command-line argument is
+   visible to other processes on the host (`ps`), while stdin is not:
+
+   ```bash
+   read -rs TOKEN
+   printf '%s' "$TOKEN" | glab variable set SCHEMA_DRIFT_TOKEN \
+     -R infrastructure/session-orchestrator --masked
+   ```
+
+   **Masked:** Yes. **Not** `--protected` — `.gate-rules` (`.gitlab-ci.yml:74`)
+   runs the job on every branch and every MR pipeline, so a protected-only
+   variable would silently be absent everywhere the job actually needs it.
 
 ### Option B — Personal Access Token (fallback)
 
-Use this if a deploy token is not available for the target project.
+The same PAT-semantics reasoning from Option A applies: a personal PAT
+authenticates under any username, so it works with the hardcoded `oauth2:`
+clone login. Use this only if you cannot create a Project Access Token on
+`infrastructure/projects-baseline` (e.g. you lack Owner/Maintainer there).
 
 1. Go to your GitLab profile → **Access Tokens**.
 2. Create a token with scope `read_repository` and a reasonable expiry.
 3. Store it in `session-orchestrator` CI/CD variables as `SCHEMA_DRIFT_TOKEN`
-   (Masked: Yes) — same steps 5–7 above.
-
-Note: a PAT is scoped to the creating user's access; prefer a deploy token so
-the CI credential survives staff changes.
+   (Masked: Yes, **not** Protected — see Option A step 3 above).
+
+A personal PAT is tied to the creating user's account and access; prefer the
+Project Access Token in Option A so the CI credential survives staff changes.
+
+### Deploy Token — does not work with the current clone URL
+
+This was the previously recommended option; it is demoted here because, as
+the job is written today, it does not authenticate. GitLab deploy tokens
+authenticate under their OWN username (`gitlab+deploy-token-<n>`, or a custom
+username set at creation) — never as `oauth2`. The job's clone step hardcodes
+`oauth2:${SCHEMA_DRIFT_TOKEN}` (`.gitlab-ci.yml` ~:652), so a deploy token's
+value paired with the wrong username fails authentication at clone time. This
+job reports that as exit 5 `UNAVAILABLE` — read as a network/credential-scope
+problem, when the actual cause is the username mismatch.
+
+To use a deploy token instead of Option A, `.gitlab-ci.yml`'s clone step would
+need to stop hardcoding `oauth2` — either read the deploy token's own username
+from a second CI variable and interpolate it into the clone URL, or create the
+deploy token with a custom username of `oauth2` if the GitLab instance allows
+choosing one. Neither change is made in this repo; that edit is out of this
+document's scope. Option A avoids needing it at all, by using a token whose
+username requirement (any username) already matches the hardcoded login.
 
 ### Verification path
 
@@ -162,8 +359,12 @@ Documenting it here for completeness:
   `infrastructure/session-orchestrator`.
 - Once the allowlist entry is saved, the job can use `CI_JOB_TOKEN` directly
   and `SCHEMA_DRIFT_TOKEN` is not needed.
-- Issue #279 chose the deploy-token path because it requires no admin action
-  in the foreign project and works immediately after variable creation.
+- Issue #279 chose the token-variable path over this allowlist because it
+  requires no admin action in the foreign project and works immediately after
+  variable creation. The original choice was a deploy token; as documented in
+  Option A above, a deploy token does not actually authenticate with this
+  job's hardcoded `oauth2:` clone login, so a Project Access Token (or PAT)
+  is the variant that delivers on that original reasoning.
 
 ## `pipeline-gate` — the fan-in job