session-orchestrator 3.16.0

package/docs/ci-setup.md

@@ -0,0 +1,81 @@
+# CI Setup — session-orchestrator
+
+> **Maintainer-internal.** This document describes the maintainer's private CI mirror setup. It is not required for using the plugin.
+
+## schema-drift-check job
+
+The `schema-drift-check` job compares the vendored `vault-frontmatter` schema
+in this repo against the canonical source in
+`infrastructure/projects-baseline` (project ID 52, private).
+
+Because the target repo is on the same private GitLab instance but is a
+**different project**, `CI_JOB_TOKEN` is rejected with HTTP 403 unless
+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`.
+
+### Required CI variable
+
+| Variable | Type | Mask | Protect | Value |
+|---|---|---|---|---|
+| `SCHEMA_DRIFT_TOKEN` | Variable | Yes | Optional | deploy token or PAT (see below) |
+
+If `SCHEMA_DRIFT_TOKEN` is **not set**, the job prints a warning and exits 0
+(no pipeline failure). Set the variable to activate the real drift check.
+
+### 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 B — Personal Access Token (fallback)
+
+Use this if a deploy token is not available for the target project.
+
+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.
+
+### Verification path
+
+After setting the variable:
+
+1. Push to a feature branch or open an MR against `main`.
+2. Observe the `schema-drift-check` job in the pipeline — it should now clone
+   `infrastructure/projects-baseline` and run the sync check instead of
+   printing the skip warning.
+3. A passing job (exit 0) means the vendored schema matches the canonical
+   source. A failing job (exit 1) means drift was detected — run
+   `node scripts/sync-vault-schema.mjs --update` locally and commit the
+   refreshed copy.
+
+### Why not configure the CI Job Token allowlist in projects-baseline?
+
+That approach (Settings → CI/CD → Token Access in the foreign project) is
+equally valid and may be preferable if you manage `projects-baseline`.
+Documenting it here for completeness:
+
+- Go to `infrastructure/projects-baseline → Settings → CI/CD → Token Access`.
+- Under "Allow CI job tokens from the following projects", add
+  `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.

package/docs/codex-setup.md

@@ -0,0 +1,142 @@
+# Codex Setup Guide
+
+Guide for using Session Orchestrator with OpenAI Codex through Codex's public plugin lifecycle.
+
+## Prerequisites
+
+- Codex CLI 0.144.4 or newer
+- Node.js 24 or newer
+- Git and an initialized project repository
+- `plugins` and `hooks` reported as `stable true` by `codex features list`
+
+## Installation
+
+Clone the repository, install its runtime dependencies, and run the installer from the plugin root:
+
+```bash
+git clone https://github.com/Kanevry/session-orchestrator.git
+cd session-orchestrator
+npm install
+node scripts/codex-install.mjs
+```
+
+The installer validates the local Codex manifest and hook contract, then uses the same public commands an operator can run manually:
+
+```bash
+codex plugin marketplace add "$PWD"
+codex plugin add session-orchestrator@kanevry
+codex plugin list --available --json
+```
+
+It operates only through public Codex plugin commands; hook trust remains untouched.
+
+## Understand the Three States
+
+Codex reports three distinct states that must not be conflated:
+
+1. **Marketplace configured** — `kanevry` points at this clone, so the plugin is discoverable. This alone does not install or enable the plugin.
+2. **Plugin installed and enabled** — `codex plugin list --available --json` shows exactly one `session-orchestrator@kanevry` entry with `installed: true`, `enabled: true`, and the version from `.codex-plugin/plugin.json`.
+3. **Hooks trusted and executing** — after installation, start a fresh Codex task or fully restart Codex, run `/hooks`, review the Session Orchestrator hook bundle, and approve it if appropriate. Hook trust remains operator-controlled; the installer never writes or bypasses it.
+
+## Refresh and Explicit Cache Invalidation
+
+After pulling changes, rerun the installer:
+
+```bash
+git pull
+npm install
+node scripts/codex-install.mjs
+```
+
+Every installer run executes `codex plugin marketplace add` and `codex plugin add`, even when the marketplace is already configured. The repeated `plugin add` refreshes Codex's installed bundle from the current clone instead of treating installation as a one-time copy.
+
+The tracked Codex manifest uses a version such as `3.14.0+codex.20260717175716`. The base must match `package.json`; the `+codex.<YYYYMMDDHHmmss>` UTC suffix is the repository's explicit invalidation marker. When a shipped bundle needs a new cache identity, maintainers commit a new timestamp in `.codex-plugin/plugin.json`. The installer validates that committed value and never mutates the tracked manifest.
+
+## Configuration
+
+### Session Config in AGENTS.md
+
+Add a `## Session Config` section to your project's `AGENTS.md`. The format is identical to the Claude Code `CLAUDE.md` config:
+
+```markdown
+## Session Config
+
+test-command: npm test
+typecheck-command: npm run typecheck
+lint-command: npm run lint
+agents-per-wave: 6
+waves: 5
+persistence: true
+enforcement: warn
+vcs: github
+```
+
+See `docs/templates/AGENTS-session-config.md` for a complete template.
+
+### Agent Roles
+
+The plugin bundle includes the Codex role definitions under `.codex-plugin/agents/`. Project-level roles under the project's `.codex/agents/` may override or extend them when a repository needs more specialized prompts.
+
+## Hook Surface and Trust
+
+`hooks/hooks-codex.json` declares the curated six-event Codex project subset:
+
+- `SessionStart`
+- `PreToolUse`
+- `PostToolUse`
+- `SubagentStart`
+- `SubagentStop`
+- `Stop`
+
+The Codex hook command uses Codex's native `${PLUGIN_ROOT}` expansion. The wrapper also exports `CODEX_PLUGIN_ROOT="${PLUGIN_ROOT}"` for shared compatibility code and sets `SO_PLATFORM=codex` so Codex wins when multiple harness variables are present.
+
+Claude-only events (`SessionEnd`, `PostToolUseFailure`, `PostToolBatch`, and `CwdChanged`) are intentionally absent because Codex 0.144.4 does not expose them as supported project events. Claude Edit/Write payload handlers are also absent: Codex emits canonical `apply_patch` data, while those handlers currently expect Claude's Edit/Write payload shape. They will remain unwired until a real `apply_patch` adapter exists; pretending the payloads are compatible would create false enforcement.
+
+An empty `PreToolUse` or `SubagentStart` array means the event belongs to the validated Codex surface but currently has no payload-compatible handler. It does not mean installation or hook trust failed.
+
+## Usage
+
+After installation and hook review, start a fresh task. Session Orchestrator exposes the shared skill surface, including:
+
+- `/session [housekeeping|feature|deep]` — start a session
+- `/go` — execute the agreed plan
+- `/close` — end the session with verification
+- `/plan [new|feature|retro]` — plan a project or feature
+- `/discovery [scope]` — run quality probes
+- `/evolve [analyze|review|list]` — manage learnings
+
+## Key Differences from Claude Code
+
+| Aspect | Claude Code | Codex |
+|--------|-------------|-------|
+| Interactive choices | AskUserQuestion tool | Numbered Markdown lists |
+| Agent dispatch | Agent tool | Codex subagents / typed roles |
+| State directory | `.claude/` | `.codex/` |
+| 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 |
+
+Both platforms share session history and learnings through `.orchestrator/metrics/`.
+
+## 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.
+
+Hook enforcement is limited to the validated payload-compatible Codex subset described above. In particular, the absence of Claude-only events and Edit/Write handlers is deliberate rather than an installation workaround.
+
+## Troubleshooting
+
+Start every Codex plugin diagnosis with the public state view:
+
+```bash
+codex plugin list --available --json
+```
+
+- **Marketplace is configured but the plugin is only available:** run `codex plugin add session-orchestrator@kanevry`, then run the plugin list again.
+- **The target is missing, disabled, duplicated, or at the wrong version:** run `codex plugin marketplace list --json`, remove the exact target with `codex plugin remove session-orchestrator@kanevry` when present, and rerun `node scripts/codex-install.mjs` to reinstall and verify it.
+- **A `session-orchestrator@openai-curated` or `session-orchestrator@local` installation remains:** these are the only allowlisted legacy IDs. Remove the exact stale ID with `codex plugin remove session-orchestrator@openai-curated` or `codex plugin remove session-orchestrator@local`; unrelated plugins remain untouched.
+- **The `kanevry` marketplace points at another source:** confirm the conflict with `codex plugin marketplace list --json`, run `codex plugin marketplace remove kanevry`, then rerun the installer from the intended clone so it performs the public marketplace add and plugin add lifecycle.
+- **Plugin is installed and enabled but hooks do not fire:** start a fresh task or fully restart Codex, run `/hooks`, and review the trust state. Installation does not imply hook approval.
+- **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.

package/docs/components.md

@@ -0,0 +1,74 @@
+# Components & Reference
+
+Detailed component inventory and architecture reference for Session Orchestrator. The [README](../README.md) keeps the landing page lean; the full inventory lives here.
+
+## Repository anatomy
+
+```mermaid
+flowchart LR
+    USER([Operator]) -->|invokes /session| COORD[Coordinator]
+    COORD -->|reads| SK[Skills<br/>44 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>24 slash-cmds]
+    COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
+    AG -.->|parallel waves| W1[code-implementer]
+    AG -.-> W2[test-writer]
+    AG -.-> W3[security-reviewer]
+    AG -.-> W4[session-reviewer]
+    HOOK[Hooks<br/>10 event types] -.->|enforce scope + commands| COORD
+    COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
+```
+
+## Skills (44 user-facing)
+
+- **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
+- **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`
+- **Planning & discovery:** `plan`, `discovery`, `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`
+- **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
+- **Content review:** `persona-panel`
+- **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
+
+## Commands (24)
+
+`/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`.
+
+## Agents (15 typed sub-agents)
+
+`code-implementer`, `test-writer`, `ui-developer`, `db-specialist`, `security-reviewer`, `session-reviewer`, `docs-writer`, `architect-reviewer`, `qa-strategist`, `analyst`, `ux-evaluator`, `dialectic-deriver`, `memory-proposal-collector`, `skill-applied-judge`, `eval-judge`.
+
+Custom agents live in `agents/` (plugin) or `.claude/agents/` (project) as Markdown with YAML frontmatter. The authoring spec — required fields, body conventions, validation commands — is in [`agents/AGENTS.md`](../agents/AGENTS.md), following the canonical [code.claude.com/sub-agents](https://code.claude.com/docs/en/sub-agents) contract.
+
+## Hook event types (10)
+
+The full Claude wiring uses: `SessionStart` (banner + init), `SessionEnd` (close events), `PreToolUse/Edit|Write` (scope enforcement), `PreToolUse/Bash` (destructive-command guard + enforce-commands + templates-first + staging-fence + memory-propose audit), `PostToolUse` (edit validation + opt-in frontend-slop detection + loop-guard), `Stop` (session events), `SubagentStop` (telemetry), `PostToolUseFailure` (corrective context), `PostToolBatch` (wave signal + operator-steer), `SubagentStart` (telemetry), `CwdChanged` (cwd-change record).
+
+Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `PostToolUse`, `SubagentStart`, `SubagentStop`, and `Stop`. Claude-only events are not exposed there, and Claude Edit/Write handlers remain unwired until a real adapter translates Codex's canonical `apply_patch` payload. The manifest uses native `${PLUGIN_ROOT}` while exporting `CODEX_PLUGIN_ROOT` plus `SO_PLATFORM=codex` for shared compatibility code.
+
+## Other surfaces
+
+- **Output Styles (3):** `session-report`, `wave-summary`, `finding-report`.
+- **Policy & rules:** `.orchestrator/policy/blocked-commands.json` (destructive-command rules); `.claude/rules/parallel-sessions.md` (PSA-001..PSA-004).
+- **Codex:** `.codex-plugin/plugin.json` (tracked `+codex.<UTC timestamp>` version), compatibility config, agent role definitions, and the public marketplace/add/list lifecycle implemented by `scripts/codex-install.mjs`. Every run refreshes via `plugin add`; hook trust remains an operator decision in a fresh task through `/hooks`.
+- **Pi:** `package.json` `pi` manifest, `pi/extensions/session-orchestrator.ts` bridge, `hooks/hooks-pi.json`, `scripts/pi-install.mjs`.
+- **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot) plus shared lib under `scripts/lib/*.mjs`, all covered by the vitest suite.
+
+## `/harness-audit` — Anthropic large-codebase rubric
+
+`scripts/harness-audit.mjs` runs **9 deterministic categories / 38 checks** over a repo and emits `.orchestrator/metrics/audit.jsonl`. Category 8 ("Large-Codebase Readiness") operationalises Anthropic's [Claude Code large-codebase best-practices](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) checklist — layered `CLAUDE.md` (or `AGENTS.md`), codebase-map presence, LSP/code-intelligence wiring, scoped test/lint commands, `permissions.deny`, and root-file leanness — as scored signals you can run on yourself and on consumer repos. Category 9 ("Skill-Health Surfacing") surfaces the #648 per-skill health pipeline — telemetry hygiene, scorer wiring, and an advisory-only verdict tally that never affects points; non-adoption always scores full points. These checks are intentionally orthogonal to repo-audit's baseline-compliance pass/fail; both surfaces ship.
+
+## Comparison vs. maestro-orchestrate
+
+Both [`maestro-orchestrate`](https://github.com/josstei/maestro-orchestrate) and session-orchestrator coordinate multi-agent work in long-running AI coding sessions. They differ in scope and execution model:
+
+| Axis | session-orchestrator | maestro-orchestrate |
+|---|---|---|
+| Execution model | 5 typed waves (Discovery → Impl-Core → Impl-Polish → Quality → Finalization) with inter-wave quality gates and confidence-scored session-reviewer | 4-phase sequential model with parallel subagents |
+| Runtime coverage | Claude Code + Codex CLI + Cursor IDE + Pi (4) | Gemini CLI + Claude Code + Codex + Qwen Code (4) |
+| VCS integration | GitLab + GitHub (auto-detected); hook events + commands wire to both | Runtime-agnostic; VCS work delegated to user |
+| Cross-session learning | Confidence-scored entries surfaced at session-start; opt-in `/evolve` review | Session archival without explicit learning extraction |
+| Specialist agents | 15 typed agents | 39 specialist agents across design/impl/review/debugging/security/compliance |
+
+The two plugins are complementary rather than competing: session-orchestrator focuses on a single wave-based lifecycle with VCS + learning integration, while maestro-orchestrate optimises for multi-runtime parallel specialist delivery.

package/docs/cursor-setup.md

@@ -0,0 +1,104 @@
+# Cursor IDE Setup Guide
+
+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`)
+- 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
+```
+
+### Option 2: Manual copy
+```bash
+# Copy .cursor/rules/ into your project
+cp -r path/to/session-orchestrator/.cursor/rules/ .cursor/rules/
+```
+
+## Configuration
+
+### Session Config in CLAUDE.md
+
+Cursor reads CLAUDE.md natively — no separate config file needed! Add a `## Session Config` section to your project's `CLAUDE.md`:
+
+```markdown
+## Session Config
+
+test-command: npm test
+typecheck-command: npm run typecheck
+lint-command: npm run lint
+agents-per-wave: 6
+waves: 5
+persistence: true
+enforcement: warn
+vcs: github
+```
+
+Note: `agents-per-wave` is ignored on Cursor since tasks execute sequentially (no parallel Agent dispatch).
+
+### Hooks (Optional)
+
+Cursor supports hooks via Settings > Hooks. Configure:
+
+- **afterFileEdit**: Run `hooks/enforce-scope.sh` for scope enforcement (post-hoc warning)
+- **beforeShellExecution**: Run `hooks/enforce-commands.sh` to block dangerous commands
+
+See `hooks/hooks-cursor.json` for the hook mapping reference.
+
+## 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
+- `/plan [new|feature|retro]` — Plan a project/feature
+- `/discovery [scope]` — Run quality probes
+- `/evolve [analyze|review|list]` — Manage learnings
+
+## Key Differences from Claude Code
+
+| Aspect | Claude Code | Cursor IDE |
+|--------|------------|------------|
+| Interactive choices | AskUserQuestion tool | Numbered Markdown lists |
+| Agent dispatch | Agent() tool (parallel) | Sequential execution (no subagents) |
+| State directory | .claude/ | .cursor/ |
+| Config file | CLAUDE.md | CLAUDE.md (same!) |
+| Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
+| Pre-edit enforcement | PreToolUse hook (blocks) | afterFileEdit hook (warns after) |
+| Command enforcement | PreToolUse hook (blocks) | beforeShellExecution hook (blocks) |
+| 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. **Post-hoc scope enforcement** — Cursor's `afterFileEdit` fires after the edit, not before. It can warn but not prevent out-of-scope edits.
+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.
+
+## Shared Knowledge
+
+All platforms share knowledge via `.orchestrator/metrics/`:
+- `sessions.jsonl` — Session history (all platforms write here with a `platform` field)
+- `learnings.jsonl` — Cross-session intelligence
+
+Switch freely between Claude Code, Codex, and Cursor on the same project — all benefit from accumulated learnings.
+
+## 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

package/docs/events-schema.md

@@ -0,0 +1,81 @@
+# Events Schema & Naming Convention
+
+The orchestrator emits **one** structured telemetry stream:
+`.orchestrator/metrics/events.jsonl` (append-only NDJSON). There is no second
+stream — `actions.jsonl` does not exist. Size-based rotation is handled once per
+session at SessionStart (`events-rotation.mjs`).
+
+## Canonical record shape
+
+Every record is a single JSON line of the form:
+
+```json
+{ "timestamp": "2026-05-28T14:35:13.123Z", "event": "orchestrator.session.ended", "...": "payload" }
+```
+
+- `timestamp` — ISO-8601 UTC string (trailing `Z`). Generated by `emitEvent()`.
+- `event` — the event name (see convention below).
+- remaining keys — event-specific payload, shallow-merged.
+
+## Single emission path
+
+**All orchestrator events MUST be emitted via `emitEvent(type, payload)` from
+`scripts/lib/events.mjs`** — never by hand-writing JSONL with `appendFile`/`jq`.
+`emitEvent()` writes the canonical record AND fires the optional Clank Event Bus
+webhook (when `CLANK_EVENT_SECRET` + `CLANK_EVENT_URL` are set) with the **same**
+event name on both sides. Hand-rolled appenders drift: the JSONL and the webhook
+end up with different names (the `stop` vs `orchestrator.session.stopped`
+divergence that issue #609 fixed).
+
+Shell and other non-Node emitters MUST route through the **`scripts/emit-event.mjs`**
+CLI (`--type <name> --payload <json>` + optional `--file <path>`, plus `--json`/`--help`),
+which wraps `emitEvent()` so they inherit the same canonical record + webhook fan-out
+instead of `jq >> events.jsonl`. For callers that manage their own stream path,
+`emitEvent(type, payload, { filePath })` accepts an additive optional path override
+(default = the resolved `eventsFilePath()`); existing two-argument callers are unchanged.
+
+## Naming convention
+
+Orchestrator-owned events use a dotted namespace:
+
+```
+orchestrator.<domain>.<verb>[.<sub>]
+```
+
+- lowercase alphanumeric segments; `_` allowed *within* a segment (`quality_gate`, `propose_invoked`);
+- at least three segments (`orchestrator` + domain + verb).
+
+Third-party / IDE events (e.g. `tmux-layout.*`) and not-yet-migrated legacy names
+are accepted as-is — the convention is enforced only on the `orchestrator.`
+namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
+(`validateEventRecord`, `ORCHESTRATOR_EVENT_RE`), covered by
+`tests/lib/events-schema.test.mjs`.
+
+## Event catalog
+
+| Event | Emitter | Hook / trigger |
+|---|---|---|
+| `orchestrator.session.started` | `hooks/on-session-start.mjs` | SessionStart |
+| `orchestrator.session.ended` | `hooks/on-session-end.mjs` | SessionEnd |
+| `orchestrator.session.stopped` | `hooks/on-stop.mjs` | Stop |
+| `orchestrator.session.lock.acquired` | `hooks/_lib/lock-bootstrap.mjs` | SessionStart |
+| `orchestrator.agent.stopped` | `hooks/on-stop.mjs` | SubagentStop |
+| `orchestrator.memory.propose_invoked` | `hooks/pre-bash-memory-propose-audit.mjs` | PreToolUse(Bash) |
+| `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence |
+| `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` | per gate-CLI run (live) |
+| `orchestrator.grounding.injected` | `scripts/compute-grounding-injection.sh` (via `scripts/emit-event.mjs`) | grounding injection, when `PERSISTENCE=true` |
+| `orchestrator.handover.gated` | `skills/session-end/SKILL.md` Phase 1.65 (skill-prose, via `scripts/emit-event.mjs`) | Handover-Alignment-Gate outcome (#773). Payload: `candidates_total`, `auto_carry`, `asked`, `dropped`, `questions_asked`, `questions_answered`, `questions_deferred`, `path` (`fast_path`\|`triage`\|`weiterarbeiten`\|`fail_open`). Emitted exactly once per close — including the fail-open skip and the "Weiterarbeiten" abort — so never-measured paths become observable |
+
+Non-orchestrator names still present in the stream: `tmux-layout.{invoked,completed,degraded}`
+(tmux-layout skill) and `stagnation_detected`. (`grounding_injected` was migrated to
+the dotted `orchestrator.grounding.injected` in #611 — see the catalog above.)
+
+## Consumers
+
+- `scripts/lib/convergence-monitor.mjs` — tails events.jsonl; reads `event_type ?? event`.
+- `scripts/lib/tmux-layout/telemetry-stats.mjs` — filters `event.startsWith('tmux-layout.')`.
+- `scripts/lib/events-rotation.mjs` — size-based archival.
+- `skills/session-end/metrics-collection.md` — jq roll-ups (incl. `orchestrator.grounding.injected`).
+
+Renaming an existing event name is a breaking change to the stream + these
+consumers — verify with `grep` (PSA-006) and update consumers in lockstep.

package/docs/migration-v3.md

@@ -0,0 +1,148 @@
+# Migrating to Session Orchestrator v3.0.0
+
+v3.0.0 swaps the Bash/zx runtime for Node.js 24+ and adds native Windows support without WSL. This guide walks through the upgrade step-by-step for each supported platform (Claude Code, Codex, Cursor IDE) and each OS (macOS, Linux, Windows).
+
+Epic reference: [#124](https://github.com/Kanevry/session-orchestrator/issues/124). Full change list: [CHANGELOG.md](../CHANGELOG.md).
+
+## 1. What Changes
+
+| Area | v2.x | v3.0.0 |
+|------|------|--------|
+| Runtime | Bash + `jq` + zx via Bash | Node.js 24+ + zx (native `import`) |
+| Hooks | `.sh` files in `hooks/` | `.mjs` files (ES modules) |
+| Install step | `git clone` only | `git clone` **then** `npm install` |
+| Windows support | Implicit via WSL / Git-Bash | Native (no wrapper shell) |
+| CI | Ubuntu-only | Ubuntu + macOS matrix |
+| Test framework | `bats` shell harness | `vitest` |
+| Dependencies | `jq`, `bash`, `git` hard deps | Node 24+, `git`; `jq` optional |
+
+Nothing about skills, commands, or session flow changes. `/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, and 17 more (see [`docs/components.md`](./components.md#commands-24)) work the same.
+
+## 2. Prerequisites
+
+- **Node.js 24 or later.** Check with `node --version`. Install from [nodejs.org](https://nodejs.org/) or via your package manager (`brew install node`, `winget install OpenJS.NodeJS`, `apt install nodejs`).
+- **Git.** Any recent version.
+- **`jq` (optional, recommended).** The scope and command enforcement policies are edited as JSON — `jq` makes that easier. No hook invokes `jq` at runtime in v3.
+
+Optional but recommended:
+- **`glab`** (GitLab CLI) or **`gh`** (GitHub CLI) for VCS operations — same as v2.
+
+## 3. Upgrade Steps
+
+### 3a. Claude Code
+
+```bash
+# 1. Pull the latest plugin
+cd "$(claude plugin dir session-orchestrator 2>/dev/null || echo ~/.claude/plugins/session-orchestrator)"
+git pull
+
+# 2. Install Node dependencies
+npm install
+
+# 3. Restart Claude Code so hooks.json is re-read
+```
+
+If you installed via `/plugin marketplace add Kanevry/session-orchestrator`, the plugin lives under `~/.claude/plugins/session-orchestrator`. If you installed from a local clone, use the clone path.
+
+### 3b. Codex
+
+```bash
+cd ~/Projects/session-orchestrator
+git pull
+npm install
+node scripts/codex-install.mjs
+codex plugin list --available --json
+```
+
+The installer now uses Codex's public marketplace/add/list lifecycle; it does not rewrite private catalogs, configuration, caches, or hook state. It repeats `codex plugin add` on every run to refresh the installed bundle. Explicit invalidation comes from the committed `.codex-plugin/plugin.json` version suffix `+codex.<YYYYMMDDHHmmss>`, which the installer validates but never mutates.
+
+After the list shows `session-orchestrator@kanevry` installed and enabled, start a fresh task or restart Codex, run `/hooks`, and review the bundle. Marketplace configuration, plugin installation, and hook trust remain separate states.
+
+### 3c. Cursor IDE
+
+```bash
+cd ~/Projects/session-orchestrator
+git pull
+npm install
+node scripts/cursor-install.mjs /path/to/your/project    # re-syncs rules
+# Restart Cursor
+```
+
+### 3d. Verify
+
+After restart, run `/session housekeeping` in any configured repo. On session start you should see the host + resource health banner (new in v3). If the banner is missing or hooks report errors, see [Known Issues](#5-known-issues--workarounds) below.
+
+## 4. What Stays the Same
+
+None of the following change in v3. Existing data migrates transparently.
+
+- **`.orchestrator/metrics/*.jsonl`** — learnings, sessions, events files are read-write compatible.
+- **`<state-dir>/STATE.md`** — schema v1 frontmatter unchanged.
+- **Session memory** (`~/.claude/projects/<project>/memory/`) — untouched.
+- **Session Config** in `CLAUDE.md` / `AGENTS.md` / Cursor rules — same field names and defaults. New optional fields (`resource-awareness`, `resource-thresholds`, `allow-destructive-ops`, `worktree-exclude`) default to safe values.
+- **All 24 slash commands** — same arguments, same flow. See [`docs/components.md`](./components.md#commands-24) for the full list.
+- **Skill Markdown** — skills are still pure Markdown with YAML frontmatter; no build step.
+- **VCS integration** — `glab` / `gh` commands, label taxonomy, issue templates.
+
+## 5. Known Issues & Workarounds
+
+### `npm install` fails with `ERESOLVE` or peer-dep warnings
+
+Use Node.js 24 or later, matching `package.json` (`engines.node: ">=24.0.0"`). Confirm `node --version` reports a supported runtime before retrying. If the error persists:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+### Windows: hooks silently no-op after install
+
+Make sure `node` is on your `PATH` inside the editor process (not just in your terminal). On Windows, Claude Code inherits PATH from the launching shell — if you installed Node via nvm-windows or fnm, relaunch the editor from a shell that has the runtime on PATH.
+
+Verify from inside Claude Code: `!node --version` should print `v24.x` or later.
+
+### EOL issues on Windows (autocrlf)
+
+v3 ships `.gitattributes` with explicit LF rules for `.sh`, `.mjs`, `.md`, `.json`, and `.yaml`. If you cloned before v3, run:
+
+```bash
+git config core.autocrlf false
+git rm --cached -r .
+git reset --hard
+```
+
+This re-checks out every file with the correct line endings. Back up any uncommitted work first.
+
+### Permission errors on hook scripts (macOS / Linux)
+
+Pre-v3, hook `.sh` files needed `+x`. v3 `.mjs` files are invoked via `node <path>`, so the executable bit is not required. If your editor reports `Permission denied` on a hook, it is pointing at a stale `.sh` path — re-run the install script for your platform (`scripts/codex-install.mjs`, `scripts/cursor-install.mjs`) or re-add the plugin in Claude Code.
+
+### `zx` not found
+
+Run `npm install` from the plugin root. The `zx` package is listed under `dependencies` (not `devDependencies`), so it installs in production trees too. If you run `npm install --production` explicitly, zx is still installed — it is only missing if you ran `npm ci --only=dev` or manually pruned runtime deps.
+
+### Hooks report `SyntaxError: Cannot use import statement outside a module`
+
+Your Node version is below 24 or your `package.json` is missing `"type": "module"`. Verify that `node --version` satisfies `engines.node >=24` and that `jq '.type' package.json` returns `"module"`.
+
+## 6. Rollback
+
+If v3 causes blocking problems and you need to revert to v2.x:
+
+```bash
+cd /path/to/session-orchestrator
+git fetch --tags
+git checkout v2.0.0
+rm -rf node_modules package-lock.json   # v2 does not use these
+# Restart your editor
+```
+
+v2.x state files (`STATE.md`, `sessions.jsonl`, `learnings.jsonl`) remain readable on rollback — the formats are stable across the 2.x → 3.0 transition.
+
+Please open an issue (link below) describing the blocker so we can address it in a v3.0.x patch.
+
+## 7. Support
+
+- **GitHub:** [Kanevry/session-orchestrator/issues](https://github.com/Kanevry/session-orchestrator/issues) — preferred for bugs and feature requests.
+- **Homepage:** [session-orchestrator.example.com](https://session-orchestrator.example.com)
+
+Please include `node --version`, your OS + arch, the editor (Claude Code / Codex / Cursor), and a minimal reproduction when filing a bug. For hook failures, attach the relevant entries from `.orchestrator/metrics/events.jsonl`.