session-orchestrator 4.1.0 → 4.2.0

package/.agents/skills/session-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-plan
-description: Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into configurable waves (default 5) with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes.
+description: Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into waves resolved from the session mode by `scripts/session-shape.mjs`, with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes.
 metadata:
   user-invocable: "false"
   tags: orchestration, planning, waves, agents

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
-    "version": "4.1.0"
+    "version": "4.2.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.1.0+codex.20260908074427",
+  "version": "4.2.0+codex.20260909111615",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "keywords": [
     "session",

package/.codex-plugin/skills/session-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-plan
-description: Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into configurable waves (default 5) with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes.
+description: Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into waves resolved from the session mode by `scripts/session-shape.mjs`, with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes.
 metadata:
   user-invocable: 'false'
   tags: orchestration, planning, waves, agents

package/.cursor/skills/session-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-plan
-description: "Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into configurable waves (default 5) with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes."
+description: "Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into waves resolved from the session mode by `scripts/session-shape.mjs`, with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes."
 disable-model-invocation: true
 ---
 

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-09-09
+
+### Added
+
+- `scripts/session-shape.mjs` (+ `scripts/lib/session-shape.mjs`) — the one place a `/session` mode + optional `--profile` resolves into an execution shape (wave count, roles, per-wave agent caps, Discovery on/off, per-wave `max-turns`). Replaces prose that answered "how many waves does a `deep` session have" in 27 places and disagreed with itself in 8 of them (measured 2026-09-09). Emits `orchestrator.session.shape_resolved`. Housekeeping is now always 1 coordinator-direct maintenance-loop wave; feature is 3 waves; deep is 5 (4 with `--known-scope true`); the `ultradeep` profile is a fixed 7 waves and ignores `waves` outright (`wavesConfigHonored: false` — PRD AC-9's "`waves < 7` is an error" is dropped). Documented in `docs/session-config-reference.md` § Session Shapes and `docs/session-config-template.md`.
+- `scripts/lib/maintenance-due-banner.mjs` — one session-start probe (`maintenance-due`) replacing the standalone `reconcile-nudge` probe and the session-end Phase 3.6.5/3.6.7 auto-dream/auto-dialectic nudges. Six ANDed signals (evolve, sweep, reconcile, dialectic, memory-cleanup, pending-sidecar), a 7-day housekeeping cooldown, banner `⚠ maintenance due: N of 6 (…) — run /session housekeeping.`. Motivated by measurement: `orchestrator.evolve.completed` fired zero times across consumer repos while 628 learnings sat unprocessed, and the auto-dialectic nudge recorded `decided: true` while nobody ever ran it.
+- `scripts/lib/session-end/tail-runner.mjs` (`runTailPhases`) — the mechanical APPLY half of session-end Phase 3.6.4's Expired-Learnings Sweep, closing a gap where the dry-run decision ran every close but nothing ever applied it (census: 0 sweeps applied, 628 learnings resident, across three consumer repos). Emits `orchestrator.learnings.sweep_applied`.
+- `scripts/lib/issue-budget-reconcile.mjs` — a close-time cross-check between a session's recorded issue creations and what the issue-budget ledger actually charged, emitting `orchestrator.issue_budget.reconciled` with verdict `match` / `escaped` / `no-ledger` / `stale-record`. Motivated by a session record with 26 recorded issue creations and no ledger file under either accounting key.
+- `issue-budget.max-per-session` now accepts the same per-session-type override syntax as `agents-per-wave` (`12 (feature: 6)`), resolved against the current session's `session-type:` (read from STATE.md) via the new `resolveMaxPerSession()` / `readSessionTypeFromStateMd()` in `scripts/lib/issue-budget.mjs`. The parser (`scripts/lib/config/issue-budget.mjs`) now returns two keys — `max-per-session` (always numeric) and `max-per-session-raw` (the unresolved value) — plus `session-type-resolved` on the loaded config.
+- `scripts/lib/telemetry/pricing.mjs` — a per-model USD-per-million-token price table (`PRICING_TABLE_DATE: 2026-09-09`) covering uncached input, cache-read, cache-creation and output rates, used by `scripts/lib/session-token-rollup.mjs` to compute `total_cost_usd` per session (gated on `schema_version >= 2`; older records are reported as `legacy_v1_records` rather than silently summed in).
+
+### Security
+
+- **`js-yaml` `^4.3.1` → `^4.3.2`** (GHSA-2883-xcg3-v3hh, high) — pipeline #512 on `main` had failed in `npm-audit` on the old range; `npm audit --omit=dev --audit-level=high` now exits 0.
+- **`vitest` + `@vitest/coverage-v8` `^4.1.5` → `^4.1.11`** (GHSA: path traversal / arbitrary file read via `@vitest/mocker` redirect mock, moderate; dev-only) — `npm audit` now reports 0 vulnerabilities at any level; the two scaffolding templates (`templates/node-minimal`, `templates/nextjs-minimal`) move from `^3.1.0` to `^4.1.11` so Dependabot stops failing on them (`dependency_file_not_supported`, no lockfile in a template).
+
+### Changed
+
+- **CI (#1294)** — GitLab `test` job: 3 shards (was 2), inner vitest cap 840 s (was 600 s), job timeout 15 min (was 10), per-shard floor 2500 tests. Measured 2026-09-09: a degraded autoscaler VM ran every test file 3–4× slower and killed a green shard at the 600 s cap twice while its sibling shard finished in 206 s.
+- `hooks/subagent-telemetry.mjs` schema_version 2 (#1244) — `token_input` is redefined from raw `usage.input_tokens` to BILLABLE PROMPT VOLUME (uncached + cache_read + cache_creation). Under prompt caching the old value understated real prompt volume by up to ~65,646× on one measured agent (56 vs 3,676,179 tokens). New additive fields `token_input_uncached`, `token_cache_read`, `token_cache_creation`, `model`. This is a SERIES BREAK — v1 and v2 `token_input` values are not comparable, and `scripts/lib/session-token-rollup.mjs` sums only `schema_version >= 2` records.
+- `hooks/pre-bash-issue-budget.mjs` now charges per STATEMENT rather than per whole command; `hooks/_lib/vcs-create-matcher.mjs` additionally matches `gh|glab api … POST …/issues`.
+- `docs/USER-GUIDE.md` § 4 Session Types and § 6 The Wave Pattern rewritten around the four resolved shapes (housekeeping/feature/deep/ultradeep) and a pointer to `scripts/session-shape.mjs --help`; the retired 3/4/5/6+ role-combination mapping table and the stale `housekeeping=2/feature=6/deep=6-10` agent-count table are replaced with the shape's actual per-type ceilings.
+- `docs/components.md` — the Scripts exemplar list extended with `session-shape`, `maintenance-due-banner`, `tail-runner`, `issue-budget-reconcile`, `telemetry/pricing`.
+- **Dead-code sweep (`check-unwired-features.mjs`)** — deleted `scripts/lib/soul-resolve.mjs`, `scripts/lib/owner-config-loader.mjs`, `scripts/lib/owner-config.mjs` + `scripts/lib/owner-config/` (7 files), `scripts/lib/multi-provider-build/{templating,providers}.mjs`, and the `scripts/lib/vault-mirror/render.mjs` barrel, plus their 12 test files — unreachable-library-module findings 5 → 2 (the 2 remaining are #1293). `.claude/rules/owner-persona.md`, `docs/owner-config-schema.md`, and `scripts/lib/owner-config.example.yaml` now describe the live `owner-yaml.mjs` surface instead of the removed loader.
+- **#1288** — `decideAndRecordAutoDialectic` wrapper removed from `scripts/lib/auto-dialectic.mjs` (its only caller, session-end Phase 3.6.7, was already retired); `orchestrator.dialectic.nudge_decided` retired to a historical catalog row in `docs/events-schema.md`.
+- **#1290 (items 1+2)** — `resolveSessionShape` now rejects out-of-set `configIsolation`/`configEnforcement` up front instead of only where `buildWave` happens to reach the resolver (previously the housekeeping shape could swallow `configIsolation: 'worktre'` unnoticed); `maintenance-due-banner.mjs` tail-scans `events.jsonl` backwards in 256 KiB chunks instead of reading the whole file (probe 31→17 ms on a 7.9 MB ledger). Item 3 deferred.
+- **Rules** — 10 `/reconcile`-generated learnings absorbed into the 4 thematic files `toolchain-and-build.md`, `guard-design.md`, `identity-and-locks.md`, `review-and-adapter-contracts.md` per the merge contract (`docs/rule-authoring.md` § "Consolidated rules"); generated surface 128,999 → 120,906 B / 11 files (ceiling 124,000).
+- **Peer card** — `.orchestrator/peers/AGENT.md` frontmatter restored to the top of the file (a managed block had been hand-prepended above it in `1be450a0`); the 2026-09-07 dialectic sidecar merged (9 sections replaced, 1 added).
+- **Docs/citations** — `skills/wave-executor/SKILL.md` + `references/wave-loop-review.md` now cite `scripts/lib/workspace.mjs` for `restoreCoordinatorCwd()` (was `worktree.mjs`, which does not export it); `.claude/rules/security.md` dropped a citation to a heading that no longer exists; `.claude/rules/development.md` § Documentation gained a rule requiring an `rg` sweep for the old path whenever an exported symbol or module moves, in the SAME change (#1221 item 7).
+
+### Notes
+
+- **Housekeeping/VCS** — 21 stale `status:in-progress` labels cleared; #1213 closed (→ #1291); 4 merged `codex/*` branches + 2 sibling worktrees removed; 5 merged `feat/*` branches deleted on the GitHub mirror.
+
 ## [4.1.0] - 2026-09-08
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-4.2.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-vitest-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
@@ -84,7 +84,7 @@ Everything else is opt-in. Full template: [`docs/session-config-template.md`](do
 
 ```text
 /session feature    # research + Q&A — inspect git, issues, history, then agree on scope
-/go                 # execute in five typed waves (fixed roles), with a quality gate between each
+/go                 # execute in typed waves sized by session type (feature: 3, deep: 5) — quality gate between each
 /close              # verify every item, commit cleanly, file carryover issues for the rest
 ```
 
@@ -184,7 +184,7 @@ Counts measured on 2026-09-07 with the command in brackets:
 - **14 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …) (`ls agents/*.md | wc -l`)
 - **27 hook files across 10 event types**, enforcing scope, blocking destructive commands, gating templates-first, and capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged elsewhere ([Platform support](#platform-support)) (`ls hooks/*.mjs | wc -l`)
 - **26 rule files** and **18 ADRs** carrying the reasoning behind the mechanisms (`ls .claude/rules/*.md | wc -l`, `ls docs/adr/*.md | wc -l`)
-- **667 vitest test files** covered by the full quality gate and CI — 13,827 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`)
+- **664 vitest test files** covered by the full quality gate and CI — 13,789 static `it()`/`test()` definitions at that measurement, and the runtime total is higher because of parameterised blocks ([methodology](docs/telemetry/telemetry-claims.md)) (`find tests -name '*.test.mjs' | wc -l`); Full Gate 2026-09-09: 16847 passed / 11 skipped / 664 files
 
 **Portable across harnesses by construction.** `scripts/generate-agents-skills.mjs` generates root `AGENTS.md` byte-identical from `CLAUDE.md` and the `.agents/skills/<name>/SKILL.md` mirrors, with spec-legal frontmatter and pointers to canonical instructions. `scripts/generate-codex-skills.mjs` generates the Codex command entrypoints. Plugin validation checks both surfaces. Separate manifests under `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/` register each harness's components; see [Codex manifest compatibility](docs/codex-setup.md#manifest-compatibility).
 
@@ -202,13 +202,13 @@ Full component inventory: [`docs/components.md`](docs/components.md). Version hi
 
 How this compares to other orchestrators — with the parts that are measured and the parts that are not: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
 
-## Recent highlights (v4.1.0)
+## Recent highlights (v4.2.0)
 
-Highlights of the v4.1.0 line:
+Highlights of the v4.2.0 line:
 
-- **Privacy and session ownership.** The privacy scanner covers MDX and can include untracked files with `--include-untracked`. Native Codex task IDs now confirm session ownership; ambiguous inherited IDs remain unconfirmed.
-- **CI and release recovery.** Coverage verification now requires valid reports and measured thresholds. Audit detection checks executable workflow commands; GitHub release recovery retains the exact repository, tag and retry notes.
-- **Clearer onboarding.** README, English/German pages and the guide agree on installation and platform capabilities. Guide Copy buttons stay beside their command blocks, including on narrow screens.
+- **One place resolves a session into its shape.** `node scripts/session-shape.mjs` turns a mode (housekeeping/feature/deep, optional ultradeep profile) into waves, per-wave agent caps, isolation and enforcement, and records the result as an event. Housekeeping is now the maintenance loop (drift-check, sweep, evolve, reconcile, dialectic, memory-cleanup), driven by the session-start `maintenance-due` probe instead of close-time nudges.
+- **Honest cost numbers.** Subagent telemetry schema v2 counts cache-read and cache-creation tokens (previously under-reported ~65,000×); a per-model price table rolls up USD per session. The issue-budget ledger is reconciled against the session record at close.
+- **Leaner tree.** A dead-code sweep removed 13 unreachable library modules and their tests; `js-yaml` patched for GHSA-2883-xcg3-v3hh; ten reconciled learnings absorbed into the thematic rule files so the generated-rule surface stays under budget.
 
 If upgrading from before 4.0, read [the v4 migration guide](docs/migration-v4.md). Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 

package/agents/ux-evaluator.md

@@ -51,7 +51,7 @@ Log a warning to stdout (not a finding) if an expected artifact type is absent.
 
 **Step 6 — Apply Check 3: `console-errors`.** If `console.log` exists, read it. The file is NDJSON (one JSON object per line) with shape `{"ts":<epoch-ms>,"type":"error"|...,"text":"...","location":{...}}`. For each entry where `type === 'error'` OR `text` contains `UNCAUGHT`, `Unhandled`, `TypeError`, `ReferenceError`, or HTTP 4xx/5xx status strings surfaced to the UI, emit one finding. Filter lines where `text` matches developer-tooling noise patterns (e.g., Vue/React hydration hints, HMR messages, browser extension warnings). Severity HIGH for uncaught exceptions; MEDIUM for visible HTTP errors. Fingerprint inputs: `scope='console'`, `checkId='error-' + derived-msg-class`, `locator=<origin-url-or-file-line>`.
 
-**Step 7 — Apply Check 4: `liquid-glass-conformance`.** This check is conditional: only execute it when the project's `Package.swift` declares a platform target of iOS 26+ or macOS Tahoe (26+). Read `Package.swift` (or the nearest one if multiple exist in the repo). If the platform condition is not satisfied, skip this check and note "liquid-glass-conformance: skipped (platform target < 26)" in the stdout summary. If the condition is satisfied, read each Peekaboo screenshot under `screenshots/*.png` and the accompanying AX-path metadata. Flag frames where the AX annotation indicates a translucent/blurred background that does NOT use `.glassEffect()` (look for legacy `.background(.thinMaterial)` or `.blur(radius:)` annotations in the AX dump). Severity MEDIUM; LOW when project conventions explicitly permit the legacy modifier (check for a `docs/apple-hig-exceptions.md` or similar). Fingerprint inputs: `scope='liquid-glass'`, `checkId='missing-glassEffect'`, `locator=<screen-name>.<frame-id>`.
+**Step 7 — Apply Check 4: `liquid-glass-conformance`.** This check is conditional: only execute it when the project's `Package.swift` declares a platform target of iOS 26+ or macOS Tahoe (26+). Read `Package.swift` (or the nearest one if multiple exist in the repo). If the platform condition is not satisfied, skip this check and note "liquid-glass-conformance: skipped (platform target < 26)" in the stdout summary. If the condition is satisfied, read each Peekaboo screenshot under `screenshots/*.png` and the accompanying AX-path metadata. Flag frames where the AX annotation indicates a translucent/blurred background that does NOT use `.glassEffect()` (look for legacy `.background(.thinMaterial)` or `.blur(radius:)` annotations in the AX dump). Severity MEDIUM; LOW when project conventions explicitly permit the legacy modifier (check for a project-owned `docs/apple-hig-exceptions.md` or similar). Fingerprint inputs: `scope='liquid-glass'`, `checkId='missing-glassEffect'`, `locator=<screen-name>.<frame-id>`. <!-- path-check: example -->
 
 **Step 8 — Write `findings.jsonl`.** Collect all emitted findings. Sort by `severity` (CRITICAL → HIGH → MEDIUM → LOW), then by `check` alphabetically, then by `fingerprint`. Write the sorted list to `<run-dir>/findings.jsonl`, one JSON object per line (NDJSON). Include a header line (a JSON comment is not valid NDJSON — do NOT add a comment line; write a metadata record instead as the first line with `"_meta": true, "rubric_version": "v1", "run_id": "<run-id>", "evaluated_at": "<ISO timestamp>"`).
 

package/commands/close.md

@@ -10,9 +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`:** `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.)
+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. Parse STATE.md with `parseStateMd` and parse `.orchestrator/metrics/sessions.jsonl` as JSONL. Import `findRecordedSession` from the plugin's `scripts/lib/session-close-backfill.mjs` and call it with the parsed records and `{ sessionId: frontmatter['session-id'], semanticSessionId: frontmatter.session, startedAt: frontmatter.started_at }`. This is the shared backfill identity reader: native UUIDs take precedence, conflicting native IDs never match through a label, and legacy semantic records remain readable. Do not substitute a text grep or compare the semantic label only against `session_id`. A missing ledger means no record; an unreadable or malformed ledger is inconclusive — report the read/parse failure and stop before repeating close side effects.
+   - **A matching completed record exists (including a legacy authoritative record without a `status` field):** 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 matching completed record exists:** Warn the user: "STATE.md completed ohne passenden Abschluss im Ledger — session-end wird zur Vervollständigung ausgeführt (#429)." An abandoned backfill stub does not prove finalization. Do NOT stop — proceed to invoke the session-end skill exactly as in exit condition 3, so the missing completion gets written this time. (The SessionEnd hook's `backfillCompletedFromStateMd` 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/go.md

@@ -18,6 +18,8 @@ Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.
 
 If the banner is present (and the session-plan output emitted a 1-wave Express Path plan per `skills/session-plan/SKILL.md` § "Express Path Short-Circuit"):
 
+**The express 1-wave plan IS the housekeeping shape.** `node scripts/session-shape.mjs --repo-root "$PWD" --session-type housekeeping --no-event` resolves to a single wave with `coordinatorDirect: true` — the express path is not a bespoke shortcut but that shape executed. Consequently, when the session type is `housekeeping`, the coordinator-direct execution runs the **maintenance loop first** (drift-check, expired sweep, `/evolve analyze`, `/reconcile`, `/evolve dialectic`, `/memory-cleanup` — ordered scope, gates and proving artefacts in `skills/wave-executor/SKILL.md` § Housekeeping Sessions — the Maintenance Loop), and **then** the selected issues in dependency order.
+
 1. **Execute the agreed tasks directly** as coordinator actions, in dependency order. Do NOT dispatch subagents. Do NOT invoke the wave-executor skill.
 2. **Append the Express Path deviation to STATE.md** before invoking session-end. Use `appendDeviationOnDisk()` from `scripts/lib/state-md.mjs` — the on-disk wrapper takes the STATE.md lock automatically, serialising any concurrent writers. This step ensures the audit trail exists BEFORE session-end finalizes the file. Equivalent one-liner via Bash:
    ```bash

package/commands/memory-cleanup.md

@@ -13,12 +13,13 @@ The skill accepts two optional, mutually-exclusive flags (see PRD #502):
 
 | Flag | Behavior |
 |---|---|
-| `--dry-run` | Run Phases 1-3 read-only. Writes a complete-replacement MEMORY.md proposal (single fenced ` ```markdown ` block; topic-file changes carried as separate `### Topic-file change:` sections after it — never git-style diff hunks, see #717) to `.orchestrator/pending-dream.md` (atomic write). Prints `pending-dream written: <N> lines proposed` (or `no consolidation needed`). Exit 0. |
-| `--apply-pending` | Reads `.orchestrator/pending-dream.md`, refuses if older than 14 days or if MEMORY.md changed since the producing `--dry-run` (#788), applies the proposal, deletes the pending file. Prints `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0 on apply; exit 1 when pending file is missing (`no pending dream to apply`), stale (`pending dream is stale (>14d), re-run --dry-run`), index-drifted (`MEMORY.md changed since the producing --dry-run; re-run --dry-run.`), or unsupported-format (`auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.`). |
+| `--dry-run` | Run Phases 1-3 read-only. Writes a complete-replacement MEMORY.md proposal (single fenced ` ```markdown ` block; topic-file changes carried as separate `### Topic-file change:` sections after it — never git-style diff hunks, see #717) to `.orchestrator/pending-dream.md` (atomic write). Prints `pending-dream written: <N> lines proposed` (or `no consolidation needed`). Exit 0. <!-- path-check: example --> |
+| `--apply-pending` | Reads `.orchestrator/pending-dream.md`, refuses if older than 14 days or if MEMORY.md changed since the producing `--dry-run` (#788), applies the proposal, deletes the pending file. Prints `auto-dream applied: -<X> lines, +<Y> entries`. Exit 0 on apply; exit 1 when pending file is missing (`no pending dream to apply`), stale (`pending dream is stale (>14d), re-run --dry-run`), index-drifted (`MEMORY.md changed since the producing --dry-run; re-run --dry-run.`), or unsupported-format (`auto-dream NOT applied: pending-dream.md contains git-style diff hunks this applier cannot consume. MEMORY.md left untouched, sidecar preserved. Re-run /memory-cleanup --dry-run to regenerate a complete-body proposal.`). <!-- path-check: example --> |
 
 Passing both flags is an error. Absence of both = legacy interactive 4-phase mode.
 
-Session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock.
+Session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar.
+The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
 
 ## Default (no flag)
 

package/commands/persona-panel.md

@@ -111,7 +111,7 @@ Resolves catalog and target, prints the planned dispatch list (persona names, mo
 /persona-panel docs/design-doc.md --grounding re-derive
 ```
 
-Each dispatched persona is instructed to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section already present in `docs/design-doc.md`, and reports them as `derived_sources`. Advisory-only — `final_verdict` is unaffected.
+Each dispatched persona is instructed to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section already present in the input document (for example, `docs/design-doc.md`), and reports them as `derived_sources`. Advisory-only — `final_verdict` is unaffected. <!-- path-check: example -->
 
 ## Related
 

package/commands/session.md

@@ -9,7 +9,7 @@ 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. `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 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`. Once the type (and any profile) is settled, the resolved execution shape is recorded at plan time by `node scripts/session-shape.mjs` (event `orchestrator.session.shape_resolved`), so the ledger can answer "how many waves did this session actually run".
 
 ### Argument alias: `ultradeep` (PRD `docs/prd/2026-09-06-ultradeep-session-profile.md`)
 
@@ -23,7 +23,8 @@ 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.
+- **The profile OWNS its wave count.** `resolveSessionShape({ profile: 'ultradeep' })` returns 7 waves and reports `wavesConfigHonored: false` together with the ignored value; the `waves` key never applies to the profile (PRD AC-9 dropped 2026-09-09). Nothing to reconcile, nothing to ask the user about — read the count from `node scripts/session-shape.mjs --session-type deep --profile ultradeep`.
+- **Cost — why the alias stays the exception.** Measured 2026-09-09 over 6 ultradeep runs in three repos: 362–507 min wall-clock vs 131–164 min for deep, at similar output-token volume — use only with a named research question.
 - **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

@@ -2,8 +2,8 @@
 
 This directory holds three distinct classes of document. Knowing which class a
 file belongs to tells you whether to trust it as current, read it as history,
-or look for it in the (private) Meta-Vault instead. See `docs/prd/2026-07-08-docs-public-split.md`
-(Epic #774) for the sanitation project that established this split.
+or look for it in the (private) Meta-Vault instead. The archived, private PRD `docs/prd/2026-07-08-docs-public-split.md` <!-- path-check: historical -->
+(Epic #774) records the sanitation project that established this split; it is kept in the private Meta-Vault.
 
 ## The three classes
 
@@ -100,11 +100,11 @@ Two things worth knowing about this split:
 
 ### 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.
+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. <!-- path-check: historical -->
 
 ## See Also
 
-- `docs/prd/2026-07-08-docs-public-split.md` — the epic that established this split (S1–S8, issues #775–#782).
+- `docs/prd/2026-07-08-docs-public-split.md` — archived in the private Meta-Vault; the epic that established this split (S1–S8, issues #775–#782). <!-- path-check: historical -->
 - `docs/session-config-reference.md` — full Session Config field reference, including the two guards named above.
 - `docs/pm-skills-marketplace.md` — when to install `phuryn/pm-skills` alongside this plugin, and the overlap table against `/grill`, `/brainstorm`, `/plan`, `/discovery`.
 - `README.md` — top-level project overview; links into this router for anything docs-specific.