session-orchestrator 3.21.0 → 3.23.0

package/commands/bootstrap.md

@@ -6,7 +6,7 @@ argument-hint: "[--upgrade <tier>]"
 
 # Bootstrap
 
-**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, and asks **a single confirmation question**. Bestätigen → fertig. Keine weiteren Schritte.
+**TL;DR — for first-time users:** Run `/bootstrap` with no flags. The skill auto-detects the right tier (fast/standard/deep) from your repo, recommends one with a one-line reason, then walks a **fixed questionnaire** — tier/stack (1–2 prompts), owner persona (5), dispatcher autonomy (1); **7–9 prompts** on a first-run full bootstrap. Bestätigen → fertig. Keine weiteren Schritte.
 
 The flags below cover special cases (re-adopting an existing repo, upgrading a tier, syncing rules). If you don't recognize the case in the description, you don't need the flag.
 
@@ -22,7 +22,7 @@ This is the path 95 % of users want.
 
 | Invocation | Behavior |
 |------------|----------|
-| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. At most ONE question in the normal case. Then scaffold files + commit. |
+| `/bootstrap` | Auto-detect tier (fast / standard / deep) from repo context. Present recommendation via `AskUserQuestion` with options to confirm or override. Tier/stack: 1–2 questions; first-run full bootstrap adds owner interview (5, `owner-interview.mjs`) + dispatcher-autonomy capture (1). Then scaffold files + commit. |
 
 What the user sees:
 

package/commands/close.md

@@ -10,7 +10,9 @@ The user wants to end the current session.
 **Pre-check before invoking session-end:** Determine `<state-dir>` from the current platform (`.claude/`, `.codex/`, `.cursor/`, or `.pi/`). Check if `<state-dir>/STATE.md` exists and read its `status` field. Three exit conditions:
 
 1. **STATE.md does not exist:** Read Session Config to check `persistence`. If `persistence: false`, inform the user: "Session completed (persistence is off — STATE.md was never created). Use `/session` to start a new session." If `persistence: true` (or Session Config unavailable), inform the user: "No active session found. Use `/session` to start a session first." Either way, stop.
-2. **STATE.md exists and `status: completed`:** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+2. **STATE.md exists and `status: completed`:** `status: completed` alone is NOT proof that session-end's Phase 3.7 writer ever ran (#429) — the field can be set by hand, or by any path that stops short of that write. Before treating the prior close as final, read STATE.md frontmatter's `session` field (the semantic session id, e.g. `main-2026-05-27-session-1`; see `skills/_shared/state-ownership.md`) and check whether `.orchestrator/metrics/sessions.jsonl` contains a record whose `session_id` equals it (`grep -c` for the literal id, or parse each line as JSON and compare `session_id`).
+   - **A matching record exists:** Inform the user: "Previous session was already finalized by session-end. Start a new session with `/session`, or inspect `<state-dir>/STATE.md` to review the prior close. (Note: if this is unexpected after an Express Path session, `commands/go.md` should have auto-invoked /close — check that STATE.md `## Deviations` contains an `Express path:` entry.)" and stop.
+   - **No `session` field is present in STATE.md frontmatter, OR no matching record exists:** Warn the user: "STATE.md completed ohne Ledger-Record — session-end wurde vorher nie ausgeführt (#429)." Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing record gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` — `scripts/lib/session-close-backfill.mjs` — independently self-heals this same gap on a later session's teardown; this Pre-Check branch covers the case where /close is re-run before that hook has had a chance to fire.)
 3. **STATE.md exists and `status: active` or `status: paused`:** Proceed to invoke the session-end skill.
 
 For any other `status` value (e.g., `idle`), warn the user: "Unexpected session status `<value>`. Inspect `<state-dir>/STATE.md` and use `/session` to reset if needed." and stop.

package/commands/eli5.md

@@ -0,0 +1,33 @@
+---
+description: Say the last answer again in plain words — same facts, in the order the operator needs them. Optional topic argument.
+argument-hint: "[topic]"
+---
+
+# eli5
+
+Invokes the `eli5` skill (`skills/eli5/SKILL.md`). Restates my last substantial output — or the named topic — for someone who knows this project but did not watch the last ten minutes of it.
+
+## Argument Validation
+
+The optional argument is a topic, in prose. If absent, the target is my own last substantial output in this conversation; if there is none yet, say so rather than picking a topic for him.
+
+Examples:
+- `/eli5` — restate what I just said
+- `/eli5 warum ist der Regel-Korpus voll?` — explain that, grounded in what this session measured
+
+## Behavior
+
+1. **Resolve the target** — last output, or `$ARGUMENTS`.
+2. **Ground it** — prefer what this session already measured over recall, and name where it came from. Never measured here → say so.
+3. **Restate** — consequence first (*must I act, and what if I don't?*), then the facts in the order he needs them.
+4. **Check before sending** — every greppable token from the original still present; every noun the system does not contain gone.
+
+## The limit that outranks the command
+
+**Simplifying removes words, never facts.** A dropped path, number, error code, identifier, or instruction to act is data loss, not simplification — `skills/session-start/soul.md` § "Never traded for brevity" outranks brevity here as everywhere. And no invented pictures: say what happens, never what it is "like".
+
+## Related
+
+- `skills/eli5/SKILL.md` — the skill, in full
+- `.claude/rules/ask-via-tool.md` § AUQ-006 — plain words, real things
+- `skills/session-start/soul.md` § Register — the canonical register statement

package/commands/go.md

@@ -10,7 +10,7 @@ The user has approved the session plan. Begin execution immediately.
 
 ## Express Path Detection
 
-Before invoking the wave-executor, check the conversation context for the Express Path activation banner emitted by session-plan or session-start Phase 8.5:
+Before invoking the wave-executor, check the conversation context for the Express Path activation banner — printed by `node scripts/express-path.mjs` in session-start Phase 8.5, and carried through session-plan's Short-Circuit (#1146):
 
 ```
 Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.

package/commands/journey-audit.md

@@ -0,0 +1,43 @@
+---
+description: Outside-in product audit as a deep session — 7 read-only roles check what the site promises against what the code does, what a user experiences, what arrives by mail, and what the data says is used. Writes a dossier; needs a per-repo journey-manifest.
+argument-hint: "[manifest-path]"
+---
+
+# Journey Audit
+
+Invokes the `journey-audit` skill (`skills/journey-audit/SKILL.md`). Dispatches roles R1–R7 against
+the repo's journey manifest, re-verifies every P0 claim in the coordinator thread, and writes
+`docs/audits/YYYY-MM-DD-user-journey-audit.md`.
+
+Complements `/discovery` rather than replacing it: discovery checks code quality inside-out,
+journey-audit checks product truth outside-in.
+
+## Argument Validation
+
+The optional argument is a path to the manifest, overriding the default
+`.orchestrator/journey-manifest.md`. Use it for a second manifest (e.g. a staging variant) or when
+the repo keeps it elsewhere.
+
+- `/journey-audit` — uses `.orchestrator/journey-manifest.md`
+- `/journey-audit .orchestrator/journey-manifest.staging.md` — uses that file instead
+
+If the argument names a file that does not exist, say so and stop — do NOT silently fall back to
+the default path, because auditing the wrong manifest produces findings that look valid and are not.
+
+## Behavior
+
+1. **Gates** — bootstrap gate, then the manifest HARD-GATE: no manifest → refuse and point at
+   `templates/_shared/journey-manifest.md`; no filled `## SAFETY` block → run without R5 and say so.
+2. **Peer-session check** — announce the audit before dispatching (`.claude/rules/parallel-sessions.md`).
+3. **Wave** — R1–R7 in parallel, all read-only except R5, each fed from the manifest.
+4. **Coordinator re-verification** — every P0 re-checked with the coordinator's own command before
+   it enters the dossier. This step is not optional and not delegable.
+5. **Dossier + closing AUQ** — fixed section order, then fix-wave packages (multiSelect) and an
+   optional issue batch via `skills/gitlab-ops/SKILL.md` label taxonomy.
+
+## Related
+
+- `skills/journey-audit/SKILL.md` — the skill, in full
+- `templates/_shared/journey-manifest.md` — the per-repo manifest template (SAFETY block gates R5)
+- `docs/prd/2026-08-28-journey-audit-skill.md` — the PRD, incl. the first-run evidence
+- `commands/discovery.md` — the inside-out counterpart

package/commands/release.md

@@ -32,13 +32,13 @@ The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.
 4. **Preflight.** `node scripts/release.mjs --check --json` — every row green. This runs *after* step 2, never before: `--check` derives its target from `package.json`, so on the pre-bump version the registry- and tag-collision rows are red by construction.
 5. **Gate, commit, push.** Full quality gate, then commit and push to **both** remotes.
 6. **CI green — on the commit that will be published.** Not on its predecessor. A green pipeline from before step 5's commit is evidence about a different tree.
-7. **Publish.** `node scripts/release.mjs --publish` — publishes, verifies the registry, tags **after** the verified publish, pushes `main` + tag to both remotes, then polls the live site. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
+7. **Publish.** `node scripts/release.mjs --publish` — the target-confirmed npm receipt is the irreversible boundary. Before that receipt, any failure aborts normally. After it, never rerun `--publish`: registry propagation timeout/query/wait failures are reconciliation while the script still tags, pushes `main` + tag to both remotes, handles the GitHub release, and polls the live site. If tag/push fails after the receipt, the dependent GitHub-release and site steps are skipped and the script returns structured reconciliation guidance instead. Add the GitHub release for the new tag (`gh release create`) as part of this step, not "later" — "later" is what produced the three-second backfill above.
 
 Steps 2–7 are one continuous act. A release left parked between step 5 and step 7 is exactly the `3.18.0` state: every surface says released, the registry disagrees.
 
 ## Abort criteria
 
-Stop and report. Do not work around, do not "fix it after the publish" — an npm publish is not revocable.
+**Before a target-confirmed npm publish receipt:** stop and report. Do not work around, do not "fix it after the publish" — an npm publish is not revocable.
 
 | Signal | Why it stops the release |
 |---|---|
@@ -51,7 +51,9 @@ Stop and report. Do not work around, do not "fix it after the publish" — an np
 
 ## After
 
-`--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
+`--publish` reports either **Release complete** or **Post-publish reconciliation required**. The latter means npm accepted the target release but registry propagation, tag/push, GitHub-release handling, or the live-site check still needs repair; a tag/push failure explicitly skips its dependent GitHub-release and site steps. **Do not rerun `--publish`**: reconcile the listed state directly, because a second publish cannot replace the immutable version. Exit `1` means a preflight/check failure or post-publish reconciliation is required; exit `2` remains a system/usage failure before the receipt.
+
+After a complete release, `--publish` prints the remaining manual items (token rotation, async gallery indexing). Rotate the npm token — write tokens are short-lived by policy, and a token that transited a log or a chat is burned.
 
 ## See Also
 

package/commands/test.md

@@ -59,9 +59,9 @@ Present the user with a structured choice via `AskUserQuestion`:
 AskUserQuestion({
   questions: [{
     question: "Which test profile should be run?",
-    header: "Test Command: profile selection",
+    header: "Profil",
     options: [
-      { label: "smoke (Recommended)", description: "Quick sanity pass — key flows, axe critical/serious, console errors." },
+      { label: "smoke (Recommended)", description: "Quick sanity pass — key flows, axe critical/serious, console errors. The fastest of the four; run it first." },
       { label: "full", description: "All checks at full depth — slower, used before release." },
       { label: "a11y", description: "Accessibility-focused pass — axe-core exhaustive scan." },
       { label: "onboarding", description: "Onboarding step-count + Liquid Glass conformance checks." }

package/docs/USER-GUIDE.md

@@ -36,7 +36,7 @@ Session Orchestrator is a Claude Code and Codex plugin that brings structured, w
 
 #### Claude Code
 
-Claude Code installs plugins through slash commands inside a running session. There is no `claude plugin` shell CLI — run these commands in the Claude Code prompt:
+Claude Code also has a `claude plugin` shell CLI (`claude plugin --help` lists subcommands). For end-user installation, use the slash commands inside a running session — run these in the Claude Code prompt:
 
 **From GitHub (recommended for end users):**
 
@@ -992,7 +992,7 @@ Enforcement levels (configured via `enforcement`):
 
 ### Prerequisites
 
-Scope and command enforcement hooks require `jq` to be installed. If `jq` is not available, hooks degrade gracefully — all operations are allowed with a warning to stderr. Install `jq` for enforcement to be active:
+The enforcement hooks (`hooks/enforce-scope.mjs`, `hooks/enforce-commands.mjs`) do not call `requireJq()` — they run without `jq`. `jq` is required by `scripts/validate-plugin.mjs` and by the wave-scope shell snippets in `skills/wave-executor/` (e.g. deriving `blockedCommands` and reading Session Config). Install `jq` when you run those tools or snippets:
 
 - **macOS**: `brew install jq`
 - **Ubuntu/Debian**: `sudo apt-get install jq`

package/docs/ci-setup.md

@@ -14,6 +14,20 @@ 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.
+
 ### Required CI variable
 
 | Variable | Type | Mask | Protect | Value |

package/docs/codex-setup.md

@@ -30,6 +30,42 @@ codex plugin list --available --json
 
 It operates only through public Codex plugin commands; hook trust remains untouched.
 
+### Short-Form Marketplace Add (Verified 2026-08-28, codex-cli 0.141.0)
+
+`codex plugin marketplace add --help` documents a short remote form:
+
+```
+codex plugin marketplace add owner/repo --ref main
+```
+
+Tested against this repo in a scoped throwaway `CODEX_HOME` (2026-08-28, codex-cli 0.141.0):
+
+```
+$ codex plugin marketplace add Kanevry/session-orchestrator --json
+{
+  "marketplaceName": "kanevry",
+  "installedRoot": ".../.tmp/marketplaces/kanevry",
+  "alreadyAdded": false
+}
+$ echo $?
+0
+```
+
+This succeeds and clones the repo via git — no `--ref`/`owner/repo` string is needed beyond the short form; the resulting marketplace name (`kanevry`) is read from `.claude-plugin/marketplace.json`'s `name` field, not from the `owner/repo` argument.
+
+**However**, the subsequent install step fails identically for both this short remote form *and* the long-form local install documented above (`codex plugin marketplace add "$PWD"`, same as `scripts/codex-install.mjs` runs):
+
+```
+$ codex plugin add session-orchestrator@kanevry --json
+Error: plugin `session-orchestrator` was not found in marketplace `kanevry`
+$ echo $?
+1
+```
+
+`codex plugin list --available --json --marketplace kanevry` returns `{"installed": [], "available": []}` for both forms — the marketplace is configured, but no plugin is discoverable inside it, contradicting item 1 under "Understand the Three States" below. A synthetic marketplace root mirroring this repo's exact layout (`.codex-plugin/plugin.json` directly at root, no `.claude-plugin/marketplace.json`) reproduces the same empty discovery; by contrast, a directory scanned via a `<root>/plugins/<name>/.codex-plugin/plugin.json` layout (the shape `codex plugin marketplace add --help`'s `--sparse plugins/foo` example implies, and the shape this host's own pre-existing `local` marketplace uses via `~/plugins/session-orchestrator`) resolves correctly. This suggests codex's own plugin-discovery convention expects a `plugins/<name>/` marketplace layout that this repo's flat root does not provide, though `.claude-plugin/marketplace.json` (Claude Code's schema) is independently accepted as "a supported manifest" at the `marketplace add` step, without resolving to a discoverable Codex plugin at `list` time.
+
+**Caveat that limits this finding:** this host's installed codex-cli is **0.141.0**, older than the "0.144.4 or newer" prerequisite this guide states above. This failure was not re-verified against 0.144.4+, so it may be specific to running below the documented minimum rather than a defect in this repo's layout on a supported version. Until re-verified on 0.144.4+, treat both the short remote form and the long-form local install (`node scripts/codex-install.mjs`) as **unconfirmed end-to-end on this host** — the `marketplace add` step succeeds either way, but `plugin add` does not, on 0.141.0. Do not elevate either form to a README-level recommended command until a `plugin add` success is measured and dated.
+
 ## Understand the Three States
 
 Codex reports three distinct states that must not be conflated:
@@ -115,9 +151,12 @@ After installation and hook review, start a fresh task. Session Orchestrator exp
 | Config file | `CLAUDE.md` | `AGENTS.md` |
 | Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
 | Hook root | `$CLAUDE_PLUGIN_ROOT` | native `${PLUGIN_ROOT}` plus `CODEX_PLUGIN_ROOT` compatibility export |
+| MCP server root | `$CLAUDE_PLUGIN_ROOT`, injected into the server process | resolved by `.mcp.json` itself — Codex expands no root variable inside `mcpServers.args` and injects none into the MCP child's environment |
 
 Both platforms share session history and learnings through `.orchestrator/metrics/`.
 
+`CODEX_PLUGIN_ROOT` is **session-orchestrator's own compatibility export, not a variable Codex provides.** The hook wrapper in `hooks/hooks-codex.json` assigns it from Codex's native `${PLUGIN_ROOT}` so that shared code (`scripts/lib/plugin-root.mjs`) can read one name on every harness. Nothing outside a hook command string sets it — in particular an MCP server started by Codex inherits neither `CODEX_PLUGIN_ROOT` nor `PLUGIN_ROOT`. That is why `.mcp.json` resolves the plugin root on its own instead of relying on a harness-provided variable: it tries `CLAUDE_PLUGIN_ROOT`, `CODEX_PLUGIN_ROOT`, `PLUGIN_ROOT`, then `git rev-parse --show-toplevel`, then asks Node to resolve the installed `session-orchestrator` package (which reaches `resolvePluginRoot()` and with it the `CURSOR_RULES_DIR` / `PI_PLUGIN_ROOT` roots too), and as the last tier scans the client plugin caches (`${CODEX_HOME:-$HOME/.codex}` and `$HOME/.claude` under `plugins/cache/*/session-orchestrator/*`, accepted only when the copy's `package.json` names `session-orchestrator`; newest by mtime wins). The tier order is documented once, in `scripts/lib/plugin-root.mjs` § TIER ORDER, and `.mcp.json` mirrors it. Each candidate must actually contain `scripts/mcp-server.sh` before it is used.
+
 ## Platform Limitations
 
 Claude Code dispatches role-specialized agents with dedicated definitions. Codex maps implementation work through its configured roles, so task prompts carry specialization that is not represented by a dedicated role. A project can add more specific TOML definitions under `.codex/agents/` when needed.
@@ -140,3 +179,28 @@ codex plugin list --available --json
 - **Other pre-public plugin/config/cache/hook-state residue is suspected:** this state is unsupported. Do not modify private Codex files. File an issue with `codex --version`, `codex plugin list --available --json`, and `codex plugin marketplace list --json` output so the public recovery path can be diagnosed.
 - **Agent dispatch fails:** verify Codex multi-agent support and inspect the bundled or project-level role TOMLs.
 - **Hooks report that Node is unavailable:** expose Node 24+ on the Codex hook PATH or set `SO_NODE_BIN` to the absolute Node executable.
+- **`MCP startup failed: handshaking with MCP server failed: connection closed: initialize response`:** the MCP entrypoint could not locate the plugin, or could not run. Read the server's **stderr** — since GH#64 it names itself. Two diagnostics exist:
+  - `session-orchestrator: cannot locate the plugin root` — no plugin-root variable was set, the working directory was outside any git checkout, no cached copy of the plugin was found, and Node could not resolve an installed `session-orchestrator` package. Fix: reinstall the plugin so a cached copy exists (see *Where the plugin actually lives* below), or add `CODEX_PLUGIN_ROOT` (or `CLAUDE_PLUGIN_ROOT`) pointing at the plugin directory to that server's `env` block. Do not expect Codex to supply the variable — see the note under *Key Differences* above.
+  - `session-orchestrator: 'jq' not found in PATH` — the plugin was found but `jq` is missing. Fix: install `jq` and restart Codex. (Before GH#64 this case wrote a JSON-RPC error to *stdout* with `id: null`, which is not a valid `initialize` response either, so a missing `jq` and a missing plugin were indistinguishable from the client side.)
+- **The MCP tools answer `Error: not inside a git repository`:** expected, not a failure. The handshake succeeded; `session_config` and `session_metrics` read the *project* you are working in, so they need Codex's working directory to be inside a git repository. Start Codex from the project, or `cd` into it.
+- **"another session holds the lock" right after `resume`/`compact` in Codex:** the session lock appears to be self-collision across a resume/compact boundary rather than a real second session. Cause: before v3.23.0 (unreleased at time of writing), `parseSessionId()`'s UUID matcher was pinned to version nibble `4` (Claude Code's format), so every native session id Codex CLI mints — UUIDv7 — failed to parse; `hooks/on-session-start.mjs` fell through to a freshly generated `randomUUID()` on each `SessionStart`, and the new mint then collided with the lock the previous mint still held (Kanevry#66 / #1091). Fixed in v3.23.0 by widening `UUID_RE` in `scripts/lib/session-id.mjs` to accept any RFC 9562 UUID version 1–8, not only `4`. Check: `node -e "import('./scripts/lib/session-id.mjs').then(m=>console.log(m.parseSessionId('017f22e2-79b0-7cc3-98c4-dc0c0c07398f')))"` must print `format: 'uuid'` and `version: 7` (verified 2026-08-28 @ 30940cb — it does).
+
+### Where the plugin actually lives (measured 2026-08-28, codex-cli 0.141.0)
+
+Three facts explain why launching Codex from `$HOME` used to kill the MCP server before `initialize` (GH Kanevry/session-orchestrator#64), and none of them is guessable from the docs:
+
+1. **Codex copies the plugin; it does not run it from your clone.** A marketplace install lands at `<CODEX_HOME>/plugins/cache/<marketplace>/<plugin>/<version>/` — measured here as `~/.codex/plugins/cache/local/session-orchestrator/3.22.0+codex.20260822193811/`, a full self-contained tree with its own `.mcp.json`, `package.json` and `scripts/mcp-server.sh`. Claude Code uses the same shape under `~/.claude/plugins/cache/`.
+2. **The MCP child gets no plugin-root variable and no working directory of its own.** Probing a registered MCP server launched from `/tmp` showed `PWD=/private/tmp` (the launch directory, verbatim) and `CLAUDE_PLUGIN_ROOT`, `CODEX_PLUGIN_ROOT`, `PLUGIN_ROOT` and `CODEX_HOME` **all unset**; `codex mcp list` prints `Env: -` and `Cwd: -` for the entry. `HOME` *is* set. So from `$HOME` — not a git repository — every locator the entrypoint had was blind, and `$(git rev-parse --show-toplevel)` collapsed the path to `/scripts/mcp-server.sh`.
+3. **Codex does not expand `${...}` in the registered command, and the registration is a snapshot.** `codex mcp list` shows the launch string verbatim, `${CLAUDE_PLUGIN_ROOT:-…}` and all — bash expands it, not Codex. It comes from the *cached* `.mcp.json`, taken at install time: a fix committed to this repo reaches an existing install only after a reinstall.
+
+The entrypoint therefore scans those cache roots itself, matching on `package.json` `"name": "session-orchestrator"` rather than on the directory name, and preferring the most recently installed copy. A directory that merely *sits* under a `session-orchestrator/` marketplace folder is rejected.
+
+**If your install predates this fix, reinstall — the fix cannot reach a cached copy on its own:**
+
+```bash
+codex plugin marketplace add Kanevry/session-orchestrator
+codex mcp list | grep session-orchestrator   # the launch string should mention plugins/cache
+```
+
+The 0.144.4 minimum-version caveat above still stands: everything in this section was measured on **0.141.0**, below the documented minimum, and has not been re-verified on 0.144.4+ or on the reporter's 0.149.0-alpha.4.3.
+

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>46 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>25 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>48 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>28 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,22 +18,23 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (46 user-facing)
+## Skills (48 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`, `contract-version-bump`
-- **Planning & discovery:** `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
+- **Planning & discovery:** `plan`, `discovery`, `journey-audit`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
 - **Architecture:** `architecture`, `domain-model`, `ubiquitous-language`
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`
 - **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`, `npm-publish`
 - **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
 - **Content review:** `persona-panel`
+- **Operator ergonomics:** `eli5` (plain-language restatement of the last answer)
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (25)
+## Commands (28)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/contract-version-bump`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/contract-version-bump`, `/eli5`, `/journey-audit`.
 
 ## Agents (15 typed sub-agents)
 

package/docs/cursor-setup.md

@@ -5,32 +5,31 @@ Guide for using Session Orchestrator with Cursor IDE.
 ## Prerequisites
 
 - [Cursor IDE](https://cursor.com) installed (version 1.7+ recommended for hooks support)
-- jq installed (`brew install jq` / `apt install jq`)
+- Node.js 24+
 - A project repository with git initialized
 
 ## Installation
 
-### Option 1: Clone and symlink (recommended)
 ```bash
-# 1. Clone the session-orchestrator repo and install its dependencies
 git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator
 cd ~/Projects/session-orchestrator && npm install
-
-# 2. Symlink Cursor rules into your project
-node ~/Projects/session-orchestrator/scripts/cursor-install.mjs /path/to/your/project
+node ~/Projects/session-orchestrator/scripts/cursor-install.mjs /path/to/your-project
 ```
 
-### Option 2: Manual copy
-```bash
-# Copy .cursor/rules/ into your project
-cp -r path/to/session-orchestrator/.cursor/rules/ .cursor/rules/
-```
+The installer links four Cursor-native surfaces into the target project:
 
-## Configuration
+| Surface | Path | What Cursor does with it |
+|---|---|---|
+| Rules | `.cursor/rules/*.mdc` | Always-on + intelligent-apply guidance |
+| Commands | `.cursor/commands/*.md` | Slash commands (`/session`, `/go`, `/close`, …) |
+| Skills | `.cursor/skills/<name>/SKILL.md` | Skill discovery; wrappers point at canonical `skills/` |
+| Hooks | `.cursor/hooks.json` | Native hooks via `scripts/lib/cursor-hook-bridge.mjs` |
+
+Working **in this repo** does not need the installer — those paths are committed. Reload Cursor (or start a new agent chat) after a pull so `/session` appears.
 
-### Session Config in CLAUDE.md
+## Configuration
 
-Cursor reads CLAUDE.md natively — no separate config file needed! Add a `## Session Config` section to your project's `CLAUDE.md`:
+Cursor reads CLAUDE.md natively. Add a `## Session Config` section:
 
 ```markdown
 ## Session Config
@@ -45,33 +44,10 @@ enforcement: warn
 vcs: github
 ```
 
-Note: `agents-per-wave` is ignored on Cursor since tasks execute sequentially (no parallel Agent dispatch).
-
-### Hooks (Optional — not yet enforcing)
-
-> **The hook handlers do not currently fire on Cursor (#919).** Both are written
-> against Claude Code's `PreToolUse` payload — they require `tool_name === "Bash"`
-> plus `tool_input.command`, and they signal a decision with a Claude Code
-> `hookSpecificOutput` envelope. Fed a Cursor `beforeShellExecution` payload,
-> `hooks/enforce-commands.mjs` short-circuits at its first gate and writes **0
-> bytes to stdout and 0 bytes to stderr, exit 0** — so the harness sees no
-> decision and **the command runs**. It is a silent no-op, not a block and not
-> even a warning. Making this real needs a Cursor input/output adapter, the way
-> Pi has `scripts/lib/pi-hook-bridge.mjs`; no such adapter exists yet.
->
-> Until then, treat `hooks/hooks-cursor.json` as the *intended* mapping and do
-> not rely on it for command or scope enforcement on Cursor.
-
-Cursor supports hooks via Settings > Hooks. The intended mapping is:
-
-- **afterFileEdit**: `hooks/enforce-scope.mjs` for scope enforcement (post-hoc warning)
-- **beforeShellExecution**: `hooks/enforce-commands.mjs` for dangerous-command enforcement
-
-See `hooks/hooks-cursor.json` for the hook mapping reference.
+`agents-per-wave` is ignored on Cursor — tasks execute sequentially (no parallel Agent dispatch).
 
 ## Usage
 
-Commands work the same as in Claude Code:
 - `/session [housekeeping|feature|deep]` — Start a session
 - `/go` — Execute the agreed plan
 - `/close` — End session with verification
@@ -79,6 +55,8 @@ Commands work the same as in Claude Code:
 - `/discovery [scope]` — Run quality probes
 - `/evolve [analyze|review|list]` — Manage learnings
 
+Cursor has no Skill tool. Commands tell the agent to **Read** `skills/<name>/SKILL.md` and follow it.
+
 ## Key Differences from Claude Code
 
 | Aspect | Claude Code | Cursor IDE |
@@ -88,17 +66,18 @@ Commands work the same as in Claude Code:
 | State directory | .claude/ | .cursor/ |
 | Config file | CLAUDE.md | CLAUDE.md (same!) |
 | Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
-| Pre-edit enforcement | PreToolUse hook (blocks) | None today — `afterFileEdit` handler is a no-op (#919) |
-| Command enforcement | PreToolUse hook (blocks) | None today — `beforeShellExecution` handler is a no-op (#919) |
+| Pre-edit enforcement | PreToolUse hook (blocks) | `preToolUse` via cursor-hook-bridge (blocks) |
+| Command enforcement | PreToolUse hook (blocks) | `beforeShellExecution` via cursor-hook-bridge (blocks) |
+| Post-edit | PostToolUse | `afterFileEdit` is post-hoc (cannot unwrite) |
 | Model | Claude via API | Model selected in Cursor settings |
 | Plan mode | EnterPlanMode tool | Instruction-based |
 
 ## Limitations
 
 1. **No parallel agents** — All wave tasks execute sequentially. Sessions take longer than in Claude Code.
-2. **No hook enforcement yet (#919)** — the handlers in `hooks/hooks-cursor.json` are Claude Code `PreToolUse` handlers. On a Cursor payload both `enforce-commands.mjs` and `enforce-scope.mjs` short-circuit at their first gate and produce **0 bytes on stdout and stderr with exit 0** — a silent no-op, so nothing is blocked and nothing is warned. Two independent adapters are missing: Cursor's payload field names differ from `tool_name` / `tool_input.*`, and Cursor does not read Claude Code's `hookSpecificOutput` decision envelope. Even once adapted, Cursor's `afterFileEdit` fires *after* the edit, so scope enforcement could at best warn, never prevent.
+2. **afterFileEdit cannot prevent an edit** — it fires after the write. Scope blocking belongs on `preToolUse`.
 3. **Model preference advisory** — The `model-preference-cursor` frontmatter in skills is advisory only. Select your model in Cursor settings.
-4. **No native plugin loader** — Skills are delivered as `.cursor/rules/*.mdc` files, not loaded from a plugin directory.
+4. **No Agent/Skill tools** — `pre-task-scope-disjoint` and `skill-invocation-telemetry` are not wired; commands Read skill files directly.
 
 ## Shared Knowledge
 
@@ -110,8 +89,8 @@ Switch freely between Claude Code, Codex, and Cursor on the same project — all
 
 ## Troubleshooting
 
-- **Rules not loading**: Ensure `.cursor/rules/` exists in your project root with `.mdc` files
-- **Commands not recognized**: Check that `000-session-orchestrator.mdc` has `alwaysApply: true`
-- **Hooks not firing**: Verify hooks are configured in Cursor Settings > Hooks
-- **jq not found**: Install jq for scope enforcement hooks
-- **State files not created**: Check `.cursor/` directory exists and is writable
+- **`/session` missing**: Confirm `.cursor/commands/session.md` exists. Reload Cursor. If this is another project, re-run `node scripts/cursor-install.mjs .`
+- **Rules not loading**: Ensure `.cursor/rules/` exists with `.mdc` files; `000-session-orchestrator.mdc` has `alwaysApply: true`
+- **Hooks not firing**: Confirm `.cursor/hooks.json` exists. Open Cursor Settings → Hooks. Restart Cursor if it was open during install.
+- **`'node' not found` in hook PATH**: See README troubleshooting. `hooks/run-node.sh` resolves Homebrew/nvm Node.
+- **State files not created**: Check `.cursor/` is writable