session-orchestrator 4.1.0 → 5.0.0

package/docs/owner-config-schema.md

@@ -5,13 +5,19 @@
 >
 > Issue [#174](../../../-/issues/174) — D1 of Sub-Epic [#161](../../../-/issues/161) (Owner Persona Layer).
 > Parent epic: [#157](../../../-/issues/157) (v3.1.0 Environment-Aware Sessions).
+>
+> **SSOT is code, not this file:** `scripts/lib/owner-yaml.mjs` (schema,
+> validator, loader, writer) + `scripts/lib/config/private-config-dir.mjs`
+> (path resolution). This page describes that module; when the two disagree,
+> the module wins.
 
 ## Path Resolution
 
-The loader (`scripts/lib/owner-config-loader.mjs`) resolves the canonical path as:
+The loader (`scripts/lib/owner-yaml.mjs`, via `resolvePrivateConfigDir()` in
+`scripts/lib/config/private-config-dir.mjs`) resolves the canonical path as:
 
 ```
-${XDG_CONFIG_HOME ?? <homedir>/.config}/session-orchestrator/owner.yaml
+${SO_CONFIG_HOME ?? XDG_CONFIG_HOME ?? <homedir>/.config}/session-orchestrator/owner.yaml
 ```
 
 | Platform   | Default path                                            |
@@ -21,37 +27,40 @@ ${XDG_CONFIG_HOME ?? <homedir>/.config}/session-orchestrator/owner.yaml
 | Windows    | `%USERPROFILE%\.config\session-orchestrator\owner.yaml` |
 
 A missing file is **not an error** — it signals the user has not opted in.
-The loader returns `{ok: false, source: 'missing'}` in that case and consumers
-fall back to plugin defaults.
-
-## Schema (`schema-version: 1`)
-
-| Section / Field                          | Type                          | Required | Default       | Notes                                              |
-|------------------------------------------|-------------------------------|----------|---------------|----------------------------------------------------|
-| `schema-version`                         | integer                       | yes      | —             | Must equal `1`.                                    |
-| `owner.name`                             | string (1-100)                | yes      | —             | Display name.                                      |
-| `owner.email-hash`                       | hex (64 chars) or `null`      | no       | `null`        | SHA256 of email; cross-host identity correlation.  |
-| `owner.language`                         | ISO-639-1 (`de`, `en`, ...)   | yes      | —             | Drives soul.md default language.                   |
-| `tone.style`                             | `direct\|neutral\|friendly`   | no       | `neutral`     |                                                    |
-| `tone.tonality`                          | string (≤200) or `null`       | no       | `null`        | Free-form descriptor.                              |
-| `efficiency.output-level`                | `lite\|full\|ultra`           | no       | `full`        | Caveman-inspired token dial.                       |
-| `efficiency.preamble`                    | `minimal\|verbose`            | no       | `minimal`     | Pre-tool-call narration.                           |
-| `efficiency.comments-in-code`            | `minimal\|full`               | no       | `minimal`     | Inline code comments.                              |
-| `hardware-sharing.enabled`               | boolean                       | no       | `false`       | Consent gate for hardware-pattern export.          |
-| `hardware-sharing.hash-salt`             | hex (64 chars) or `null`      | no       | `null`        | Per-host random salt. Required when `enabled=true`.|
-| `defaults.preferred-test-command`        | string (≤200) or `null`       | no       | `null`        | Override CLAUDE.md `test-command`.                 |
-| `defaults.preferred-editor`              | string (≤50) or `null`        | no       | `null`        |                                                    |
-| `metadata.created_at`                    | ISO 8601 string or `null`     | no       | `null`        | Auto-set on first write.                           |
-| `metadata.updated_at`                    | ISO 8601 string or `null`     | no       | `null`        | Auto-bumped on every save.                         |
+`loadOwnerConfig()` then returns `getDefaults()` with `source: 'defaults'`.
+
+## Schema
+
+Four **required** sections (`owner`, `tone`, `efficiency`, `hardware-sharing`)
+and the optional sections below. An invalid required section discards the whole
+file (defaults are returned, errors reported); an invalid optional object
+section is replaced by its default and reported via `droppedSections`
+(`source: 'partial'`).
+
+| Section / Field                     | Type / enum                          | Required | Default   | Notes                                              |
+|-------------------------------------|--------------------------------------|----------|-----------|----------------------------------------------------|
+| `owner.name`                        | non-empty string                     | yes      | `''`      | Display name.                                      |
+| `owner.language`                    | `de` \| `en`                         | yes      | `en`      | Drives soul.md default language.                   |
+| `tone.style`                        | `direct` \| `neutral` \| `friendly`  | yes      | `neutral` |                                                    |
+| `tone.tonality`                     | string or absent                     | no       | `''`      | Free-form descriptor.                              |
+| `efficiency.output-level`           | `lite` \| `full` \| `ultra`          | yes      | `full`    | Token dial.                                        |
+| `efficiency.preamble`               | `minimal` \| `verbose`               | yes      | `minimal` | Pre-tool-call narration.                           |
+| `hardware-sharing.enabled`          | boolean                              | yes      | `false`   | Consent gate for hardware-pattern export.          |
+| `hardware-sharing.hash-salt`        | string                               | no       | `''`      | Required (non-empty) when `enabled = true`.        |
+| `paths.vault-dir`                   | string                               | no       | `''`      | `''` = no override; beats the committed `vault-integration.vault-dir`. |
+| `paths.baseline-path`               | string                               | no       | `''`      | Host-local `plan-baseline-path` override (#653).   |
+| `paths.namespace-map-path`          | string                               | no       | `''`      | Host-local repo-pseudonym JSON map (#725 D5).      |
+| `paths.confidential-names-file`     | string                               | no       | `''`      | Host-local JSON array of names for the CP11 leakage rule (#728a). Names live in that file only, never inline here. |
+| `dispatcher.autonomy`               | `off` \| `advisory` \| `autonomous-gated` \| `''` | no | `''` | `''` = no override (#679).                         |
+| `vaults`, `baselines`               | lists                                | no       | absent    | Passed through untouched; parsed leniently at point of use. |
 
 ### Privacy Contract
 
-- `hardware-sharing.enabled = true` **requires** `hardware-sharing.hash-salt`
-  to be a valid 64-char hex string. The validator rejects `enabled=true` with
-  `hash-salt=null` so consent is never recorded without the means to
-  anonymise per-host learnings.
-- `owner.email-hash` is the only field carrying potential cross-host identity;
-  it is hashed (never plaintext email) and remains optional.
+- `hardware-sharing.enabled = true` **requires** a non-empty
+  `hardware-sharing.hash-salt`. The validator rejects consent without the means
+  to anonymise per-host learnings.
+- Only PATHS live in `owner.yaml`; the host-local data they point at
+  (confidential names, namespace map) is never inlined and never committed.
 
 ## Example
 
@@ -60,95 +69,70 @@ for an annotated, copyable example.
 
 ## API Surface
 
-`scripts/lib/owner-config.mjs` (pure, no I/O):
+`scripts/lib/owner-yaml.mjs` — the live SSOT. **Synchronous**; every call site
+consumes it without `await`. `js-yaml` is imported lazily, so the module is
+safe on the hook import graph.
 
 ```js
-import { validate, coerce, defaults, merge } from './scripts/lib/owner-config.mjs';
-
-// Defensive, never throws. Use this in skill code paths.
-const result = validate(rawObj);
-//   → { ok: true, value: <normalized>, errors: [] }
-//   → { ok: false, value: null, errors: ["owner.name must be ..."] }
-
-// Strict mode: throws OwnerConfigError on failure. Use in tests / CLI.
-const value = coerce(rawObj);
-
-// Default-filled config. owner.name and owner.language remain blank
-// (the bootstrap interview in D2 fills them in).
-const def = defaults();
+import { loadOwnerConfig, resolveOwnerYamlPath, validateOwnerConfig, getDefaults }
+  from './scripts/lib/owner-yaml.mjs';
 
-// Deep-merge two configs. `override` wins on every defined leaf.
-const merged = merge(baseFromOwnerYaml, perSessionOverrides);
-```
-
-`scripts/lib/owner-config-loader.mjs` (filesystem I/O):
-
-```js
-import { loadOwnerConfig, resolveOwnerConfigPath } from './scripts/lib/owner-config-loader.mjs';
-
-const result = await loadOwnerConfig();
+const result = loadOwnerConfig();
 // {
-//   ok: true|false,
-//   value: <normalized> | null,
-//   errors: string[],
-//   source: 'file' | 'missing' | 'parse-error' | 'validation-error',
+//   config: <merged with getDefaults()>,
+//   source: 'file' | 'partial' | 'defaults' | ...,
 //   path: '<absolute path>',
+//   errors: string[], warnings: string[], droppedSections: string[],
 // }
 
 // Test override
-const result2 = await loadOwnerConfig({ path: '/tmp/test-owner.yaml' });
+const result2 = loadOwnerConfig({ path: '/tmp/test-owner.yaml' });
+
+// Pure validation, no I/O, never throws.
+const { valid, errors } = validateOwnerConfig(rawObj);
 ```
 
+Also exported: `validateOwnerSections()` (per-section buckets),
+`writeOwnerConfig()`, `OPTIONAL_OBJECT_SECTIONS`, `resolvePrivateConfigDir`.
+
 ## Where this gets read
 
-D1 only ships the schema + validator + loader. The downstream tasks consume
-these primitives:
-
-- **[#175 D2](../../../-/issues/175) — bootstrap interview**: writes the file via
-  `coerce()` then a YAML serializer, stamping `metadata.created_at` /
-  `metadata.updated_at`.
-- **[#176 D3](../../../-/issues/176) — `soul.md` runtime-merge**: calls
-  `loadOwnerConfig()` from the session-start hook, then `merge()` with any
-  per-session overrides, then resolves `{{tone.style}}` /
-  `{{efficiency.output-level}}` / `{{owner.language}}` template slots.
-- **#177 D4 — projects-baseline propagation**: stamps a
-  reference to the canonical path into every consumer repo's CLAUDE.md
-  frontmatter (path reference only — never the content).
-- **[#168 C4](../../../-/issues/168) — hardware-sharing consent prompt**: writes
-  `hardware-sharing.enabled = true` + a freshly-generated `hash-salt` after
-  the user accepts the consent dialogue.
+`loadOwnerConfig()` has 10 live consumers outside its own module
+(`rg -ln "loadOwnerConfig" scripts hooks`, 2026-09-09) — two hooks
+(`hooks/on-session-start.mjs`, `hooks/skill-invocation-telemetry.mjs`), the
+session-start owner-config banner (`scripts/lib/owner-config-banner.mjs`), the
+host-path + dispatcher-autonomy resolvers (`scripts/lib/config/host-paths.mjs`,
+`scripts/lib/config/dispatcher-autonomy.mjs`), the named-vault resolver, the
+owner-leakage scanner, telemetry, and vault-mirror. For the behavioural
+contract of the persona layer itself see
+[`.claude/rules/owner-persona.md`](../.claude/rules/owner-persona.md).
 
 ## Validation Rules (rejection examples)
 
 ```yaml
-# REJECTED — schema-version missing
-owner: { name: x, language: en }
-
-# REJECTED — schema-version mismatch (refuses to load future versions)
-schema-version: 2
-owner: { name: x, language: en }
-
-# REJECTED — name empty
-schema-version: 1
+# REJECTED — owner.name empty
 owner: { name: "", language: en }
 
-# REJECTED — language not ISO-639-1
-schema-version: 1
+# REJECTED — language outside the de|en enum
 owner: { name: x, language: "english" }
 
 # REJECTED — enum violation
-schema-version: 1
 owner: { name: x, language: en }
 tone: { style: "snarky" }
 
 # REJECTED — privacy contract: enabled=true without hash-salt
-schema-version: 1
 owner: { name: x, language: en }
 hardware-sharing: { enabled: true }
 
-# ACCEPTED — minimal valid config
-schema-version: 1
+# ACCEPTED — all four required sections present and valid
 owner:
   name: Bernhard
   language: de
+tone:
+  style: direct
+efficiency:
+  output-level: full
+  preamble: minimal
+hardware-sharing:
+  enabled: false
 ```

package/docs/persona-panel.md

@@ -70,8 +70,8 @@ written to `.orchestrator/persona-panel/`.
 **Scenario:** A climate-research brief (`wfk-2.1.5.md`) needs sign-off from a domain physicist
 and an AI/ML expert before it is submitted. Both must agree.
 
-**Catalog files:** `.claude/personas/klima-physicist.md`,
-`.claude/personas/klima-ai-expert.md`
+**Catalog files:** `.claude/personas/klima-physicist.md`, <!-- path-check: example -->
+`.claude/personas/klima-ai-expert.md` <!-- path-check: example -->
 
 ```bash
 /persona-panel docs/research/wfk-2.1.5.md \
@@ -182,8 +182,8 @@ The command exits with code 1. CI pipelines and wave-executor hooks can gate on
 **Scenario:** An AI accountant (Sophie) produces invoice analysis JSON. A tax-advisor persona
 and a DSGVO-compliance persona must both approve before the output is delivered to the client.
 
-**Catalog files:** `.claude/personas/accounting-tax-advisor.md`,
-`.claude/personas/accounting-compliance.md`
+**Catalog files:** `.claude/personas/accounting-tax-advisor.md`, <!-- path-check: example -->
+`.claude/personas/accounting-compliance.md` <!-- path-check: example -->
 
 ```bash
 /persona-panel sophie-outputs/2026-05-19/invoice-12345.json \

package/docs/pi-setup.md

@@ -118,5 +118,6 @@ After reload, use the same commands:
 - **Prompts or skills not visible**: verify the project is trusted in Pi, then restart or reload.
 - **Package not loaded**: confirm `.pi/settings.json` or `~/.pi/agent/settings.json` contains the local checkout path under `packages`.
 - **Hooks not firing**: confirm `package.json` still has the `pi.extensions` entry and `hooks/hooks-pi.json` exists.
+- **No import-probe warning after an edit**: Pi wires the probe through `tool_result`; file eligibility, ESLint resolution, and `no-undef` configuration still apply. See [import-probe coverage and ESLint troubleshooting](USER-GUIDE.md#import-probe-warnings-and-missing-eslint).
 - **Config ignored**: ensure the file has a `## Session Config` header in `AGENTS.md` or `CLAUDE.md`.
 - **Runtime error from hooks**: run `npm install` in the Session Orchestrator checkout so hook dependencies are present.

package/docs/rule-authoring.md

@@ -285,12 +285,19 @@ them silently loses a learning or regenerates it:
    TTL past what its type registry granted it.) State the rule in the file
    itself, so the next editor does not "fix" it upward.
 
-3. **Keep `globs:` only, and take the UNION.** The merged file loads for any
-   path any of its parts covered, so its `globs:` is the union of theirs.
-   `rule-loader.mjs` resolves `globs:` and `paths:` with `globs:` winning
-   SILENTLY when both are present (issue #795, `parseGlobsFrontmatter`) — so a
-   file carrying both duplicate keys ships the `paths:` block as dead bytes.
-   Write `globs:` alone.
+3. **Keep BOTH `globs:` and `paths:`, as byte-identical mirrors, each the
+   UNION of the parts.** The merged file loads for any path any of its parts
+   covered, so both lists are the union of theirs — never `globs:` alone.
+   `rule-loader.mjs` resolves `globs:` for wave-time injection, while Claude
+   Code's OWN native rule loader reads ONLY `paths:` and treats a rule
+   lacking it as unconditional, always-on (`check-rules.mjs` check #1108,
+   measured this session) — a `globs:`-only merged file is scoped everywhere
+   it is inspected and loads everywhere it is used, exactly the
+   instruction-budget failure consolidation exists to prevent. `rule-loader.mjs`
+   still resolves `globs:` and `paths:` with `globs:` winning SILENTLY when
+   both are present (issue #795, `parseGlobsFrontmatter`), but keeping the two
+   lists identical makes that precedence moot — there is no divergent value
+   left for it to pick between.
 
 4. **Substance in, boilerplate out.** Each absorbed learning becomes an `###`
    heading carrying its original rule sentence, plus its evidence line. What is

package/docs/scope-collision-guard.md

@@ -25,6 +25,8 @@ Two things follow, and both are the point of #1020:
 
 `<state-dir>` is the first of `.pi` / `.cursor` / `.codex` / `.claude` that carries a `wave-scope.json` — the same precedence `findScopeFile()` and the hook's `waveKeyOf()` use.
 
+Step 1 also offers an opt-in path diagnostic: run `materialize-wave-scope.mjs` from the project root with `--warn-missing` to name absent concrete paths and their agents on stderr (#1235). Relative paths resolve from the working directory, not `<state-dir>`. A warning does not fail the command or change its stdout or either declaration shape. For a file the wave deliberately creates, repeat `--new-file PATH` as needed; every exception must exactly match a declared path and pass scope validation before any writes begin. Grants containing `*` or ending in `/` are skipped under the existing glob/prefix grammar; `?` and braces are literal. The canonical invocation and handling steps are in `skills/wave-executor/references/wave-loop-scope-manifest.md` § 3.1.
+
 ### 2.1 Why `--union` runs last
 
 A union computed over colliding scopes **launders the defect into the artefact meant to prevent it**: `allowedPaths` then grants the contested file, and every later gate — `--assert-subset`, `enforce-scope` Gate 7, the commit guard — sees a perfectly legal write. `validate()` in `validate-wave-scope.mjs` enforces the order in code: `--assert-subset` → `--assert-disjoint` → `--union`, and `--union` returns early because it is a QUERY MODE that replaces the manifest echo on stdout.
@@ -62,6 +64,14 @@ Five properties are choices, not omissions — and every one of them points the
 
 The event is what keeps the skip countable rather than silent: `orchestrator.scope.foreign_session_ignored` carries `hook`, `manifest`, `manifest_session`, `own_session`, `wave` and `file_path`. It is deliberately an event and not an `emitWarn` — the branch is hit on *every* Edit of the non-owning session, so a stderr line per write would be noise the operator learns to ignore.
 
+### 2.4 The one out-of-repo territory: harness auto-memory (#1295)
+
+`hooks/enforce-scope.mjs` Gate 5c allows writes under **this repo's** Claude Code auto-memory directory, `~/.claude/projects/<encoded-repo-path>/memory/` (`<encoded-repo-path>` = the repo root with every `/` and `.` replaced by `-`, via the one repo encoder `encodeProjectDir()` in `scripts/lib/wave-transcript-tail.mjs`). The harness writes `MEMORY.md` and the per-fact files there, outside the working copy, so those paths can never collide with any wave file scope — yet Gate 6 denied every one of them while a manifest existed, and six sessions in a consumer repo re-documented the same tear-down-the-manifest workaround (bewerbungs-assistent#307). One `orchestrator.scope.memory_dir_allowed` event per allow makes it countable.
+
+The grant is exactly one directory: containment is exact-prefix on the realpath-resolved candidate (both the raw and the canonical project root are encoded, since Claude Code names the directory after the path it was launched with), so a SIBLING repo's memory dir, an adjacent-prefix sibling directory (`<memory>-evil/`), a `..` traversal out of it, and every other out-of-repo path stay denied. One honest caveat: the harness name is not unique — `encodeProjectDir()` maps both `/` and `.` to `-`, so two repo roots differing only in `.` vs `-` (`/x/a.b` and `/x/a-b`) share ONE memory dir. That collision is the harness's, inherited here and not narrowable by this gate — and in-repo enforcement, including Discovery's `allowedPaths: []` deny-all, is untouched. The encoder is bound lazily and a load failure falls through to the deny (fail-closed). **Who the grant is for (#1352): the COORDINATOR only.** The carve-out opens a directory whose content is auto-injected as trusted project context into every later session, outside `git diff`, CI review, owner-leakage and gitleaks — so a dispatched wave agent must not reach it. The discriminator is the payload's **`agent_id`**, and it is measured, not assumed (Claude Code 2.1.270, `strings` over the shipped binary, 2026-09-13): the base hook-input builder every event shares is `{session_id, transcript_path: yf(session.id), cwd, …, agent_id: toolUseContext?.agentId, agent_type}`, which PreToolUse spreads verbatim, and the harness's own schema says of `agent_id` — *"Present only when the hook fires from within a subagent… Absent for the main thread, even in `--agent` sessions. Use this field (not `agent_type`) to distinguish subagent calls from main-thread calls."* The issue's original candidate is refuted by the same source: `transcript_path` is derived from the SESSION id, so coordinator and subagent carry the identical value; so is `CLAUDE_CODE_SESSION_ID`, and `CLAUDE_CODE_CHILD_SESSION=1` was measured in a main-thread `env` dump (`isSidechain:false`).
+
+`classifyCaller()` therefore returns `subagent` (non-empty `agent_id` → **no carve-out**; the write falls through to the normal gates, which is a DENY under Discovery's `allowedPaths: []`), `coordinator` (no `agent_id` but a non-empty `agent_type` — per the schema that combination is the main thread of an `--agent` session), or `absent` (neither field). **`absent` keeps the pre-#1352 ALLOW, deliberately fail-OPEN:** fail-closed on ambiguity would deny the coordinator's own memory writes and break `/close`, and a harness that sends no marker is indistinguishable from a main thread. The outcome rides on the existing `orchestrator.scope.memory_dir_allowed` event as `discriminator`, so the fail-open case is countable rather than silent (HR-105) — revisit if `absent` ever dominates the records on a harness that does dispatch subagents.
+
 ## 3. The collision algorithm
 
 `findScopeCollisions(agentScopes, { knownFiles })` compares every cross-agent entry pair through `classifyEntryCollision()`, in three binding stages:
@@ -141,6 +151,12 @@ Why it exists: the in-ledger `scopeSignals` counter (§ 4.1, rows 5/6) is a **wa
 
 **Payload discipline.** Counts and closed enums only, plus `agent_id` (the coordinator's own dispatch description, clamped) and the optional session attribution: no prompt body, no declared path, no glob. Issue #1092's acceptance criterion 3 is the rule, and the reason is concrete — this record also travels over the optional Clank Event-Bus webhook with no redaction, and paths under `01-projects/` carry private project slugs.
 
+**The receive side now has a SOFT self-report signal (#1092).** Beside the fenced `FILE-SCOPE` block the coordinator injects one line naming the `scopeDigest` of that agent's own scope file (`scripts/lib/scope-echo.mjs --instruction`); post-wave, `checkScopeEcho` compares the digest the agent echoed in its report and emits one `orchestrator.wave_dispatch.scope_echo_checked` record per agent (`skills/wave-executor/references/wave-loop-review.md` step 3d-bis). It is informational — a missing or mismatched echo blocks nothing.
+
+**Its ceiling, named (BV-004).** The digest is *handed to the agent in the prompt*, so an agent that never read a single path can still copy the line. The signal therefore proves only that the injected line survived the round trip into the agent's context and back — strictly more than the zero receive-side signal that preceded it, and strictly less than obedience, which stays measured at write time (`enforce-scope.mjs`) and by the W5 pass. Revisit when the platform exposes a prompt-assembly boundary, at which point the digest can be computed against the assembled prompt rather than echoed by its reader.
+
+A cryptographic proof still needs that platform boundary: no mechanism inside this repo can distinguish a copied digest from a read one.
+
 **Revisit-Trigger** (verbatim from issue #1092, for the transport half this section deliberately does NOT close):
 
 > Implement when the platform exposes a stable prompt-assembly hook or when a coordinator-owned digest event can be proven against the real dispatched transcript.

package/docs/session-config-reference.md

@@ -76,12 +76,33 @@ Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. The override key set is OPEN — `_coerceInteger` (`scripts/lib/config/coercers.mjs`) parses whatever keys the parentheses contain, so `6 (deep: 18, ultradeep: 18)` outputs `{"default": 6, "deep": 18, "ultradeep": 18}` with no code change (see § Session Profile below). Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). |
+| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. The override key set is OPEN — `_coerceInteger` (`scripts/lib/config/coercers.mjs`) parses whatever keys the parentheses contain, so `6 (deep: 18, ultradeep: 18)` outputs `{"default": 6, "deep": 18, "ultradeep": 18}` with no code change (see § Session Profile below). Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). **Resolution for wave shaping** is `resolveAgentCap(cap, sessionType)` in `scripts/lib/session-shape.mjs` — the one EXPORTED resolver. `wave-resource-gate.mjs` and `resource-probe/evaluate.mjs` both import and call this same function for their resource-ceiling checks, but each does so through a local `MODE_BLIND_SESSION_TYPE` constant (`undefined`) instead of the session's real type — two mode-blind CALL SITES, not separate resolvers — so `resolveAgentCap` sees no type and takes the `.default` fallback unconditionally; a difference between their answer and the wave-shape answer is expected, not a bug. Ultradeep looks up `ultradeep` → `deep` → `default`, in that order (`resolveUltradeepCap()`), so a repo that only configured `6 (deep: 18)` still gets 18 under the profile. See § Session Shapes below. |
 | `agent-mapping` | object | null | Optional mapping of role keys to agent names for explicit agent binding. Keys: `impl`, `test`, `db`, `ui`, `security`, `compliance`, `docs`, `perf`. Example: `{ impl: code-editor, test: test-specialist }`. Overrides auto-discovery when present. Values may carry a channel prefix — see § `agent-mapping` values below. |
-| `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
+| `waves` | integer | `5` | Base wave count, read by `resolveSessionShape()` (`scripts/lib/session-shape.mjs`) as the value it reports back in `wavesConfigHonored` / `wavesConfigIgnoredValue` — it is **not** a free dial per session type. `feature` and `deep` (no profile) each have exactly one natural wave count and IGNORE a `waves` value that disagrees with it (recorded in the shape's `notes`, never used to re-combine roles — the former 3/4/6+ role-combination tables are RETIRED as of 2026-09-09). The `ultradeep` profile ignores `waves` outright regardless of its value (`wavesConfigHonored: false`) — PRD `2026-09-06-ultradeep-session-profile.md` AC-9 ("`waves < 7` is an error") was dropped in favour of this explicit ignore-and-report. See § Session Shapes below for the authoritative per-shape wave counts. |
 | `recent-commits` | integer | `20` | Number of recent commits to display during session start git analysis. |
 | `special` | string | none | Repo-specific instructions. Freeform text that the orchestrator reads and follows during sessions. |
 
+### Session Shapes
+
+`scripts/lib/session-shape.mjs` is the one place a `/session` mode + optional `--profile` becomes an execution shape (wave count, roles, agent caps, Discovery on/off, per-wave `max-turns`), driven via the CLI wrapper `scripts/session-shape.mjs`:
+
+```
+node scripts/session-shape.mjs --repo-root <path> --session-type <housekeeping|feature|deep> \
+     [--profile ultradeep] [--known-scope true|false] [--task-count <n>] [--no-event]
+```
+
+It prints one JSON line (`resolveSessionShape()`'s return value) and, unless `--no-event`, records `orchestrator.session.shape_resolved` to `.orchestrator/metrics/events.jsonl`. Four shapes, resolved 2026-09-09 (decided by the operator, superseding the prose it replaces — see the module's own header for the full rationale):
+
+| Shape | Waves | Roles (agent cap) | Discovery | Coordinator-direct |
+|---|---|---|---|---|
+| `housekeeping` | **1** | Housekeeping (0 — coordinator runs the maintenance loop directly: drift-check, sweep, evolve, reconcile, dialectic, memory-cleanup) | n/a | yes, the whole wave |
+| `feature` | **3** | Impl-Core (4) → Impl-Polish+Quality (4) → Finalization (2) | no | no |
+| `deep` (unknown scope) | **5** | Discovery (8) → Impl-Core (10) → Impl-Polish (8) → Quality (6) → Finalization (4) | yes | no |
+| `deep` (`--known-scope true`) | **4** | Impl-Core (10) → Impl-Polish (8) → Quality (6) → Finalization (4) | no (dropped, rest renumbered) | no |
+| `deep` + `--profile ultradeep` | **7**, fixed — ignores `waves` | Research+Code-Discovery (18) → **Synthesis-Gate (0, coordinator-direct, blocking AskUserQuestion)** → Impl-Core (8) → Impl-Polish (8) → Review-Panel (3, read-only) → Quality (6) → Release/Finalization (4) | yes (wave 1) | wave 2 only |
+
+Raw caps are the `agents-per-wave` value BEFORE the session-type override resolves (`agentCapRaw` in the JSON); `agentCap` is the resolved number. `max-turns` (`auto`) expands per shape — see the `max-turns` row below. This table is descriptive of the module's committed defaults; the module itself, not this table, is the SSOT — re-run the CLI with `--no-event` to confirm before citing a number from here in an automated check.
+
 ### Session Profile — `session-profile` (NOT a Session Config key)
 
 `session-profile` names a WAVE-SHAPE variant on top of an unchanged `session-type`. It is listed here because it is easy to look for in the wrong place: **it is not a Session Config key and `parseSessionConfig()` does not emit one.** Writing `session-profile:` into a repo's `## Session Config` block is inert prose, exactly like `session-type:` (see the `agents-per-wave` row above).
@@ -270,15 +291,19 @@ issue-budget:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `issue-budget.max-per-session` | integer | `12` | Non-exempt issues one session may create before the cap bites. `0` is valid (blocks everything non-exempt). Malformed or negative values fall back to `12`. |
+| `issue-budget.max-per-session` | integer or integer with overrides | `12` | Non-exempt issues one session may create before the cap bites. `0` is valid (blocks everything non-exempt). Malformed or negative values fall back to `12`. **Accepts the same session-type override syntax `agents-per-wave` uses**: `12 (feature: 6)` parses via `_coerceInteger` into `{default: 12, feature: 6}`. The override key set is OPEN — any session-type label the operator writes, because the vocabulary lives in session-start, not in this parser. |
 | `issue-budget.mode` | string | `strict` | `strict` blocks over-cap creations (exit 2 from the hook) and parks them as overflow; `warn` allows them with a stderr notice; `off` disables the gate entirely (no counter is written). |
 | `issue-budget.overflow` | string | `collect-issue` | Where session-end drains parked creations. `collect-issue` files exactly ONE `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte` issue (`type::backlog`, `priority::low`) whose body is a checklist of the parked items; `vault-note` writes a single Markdown file under `vault/00-inbox/` instead. |
 
+**Override resolution (#1163-adjacent, load-bearing split).** `_parseIssueBudget()` (`scripts/lib/config/issue-budget.mjs`) returns TWO keys: `"max-per-session"` (always a plain number — the resolved `.default`, so the three existing consumers that treat it as a number never see `[object Object]`) and `"max-per-session-raw"` (the full parsed value, number or override object). `loadIssueBudgetConfig()` (`scripts/lib/issue-budget.mjs`) resolves the effective cap for the CURRENT session by reading `session-type:` off the active STATE.md frontmatter (`readSessionTypeFromStateMd()`, never throws — a missing/unparseable STATE.md yields `null`, read as "use the default") and calling `resolveMaxPerSession(cfg, sessionType)`, whose precedence is `raw[sessionType] ?? raw.default ?? cfg['max-per-session']`. The resolved session type is also returned as `"session-type-resolved"` (`null` when STATE.md carries none) so a caller can tell the resolution actually happened rather than fallen through.
+
 **Exemptions (load-bearing).** `priority::critical`, the carryover class (`[Carryover]`, `[SPIRAL]`/`[FAILED]`, `type::carryover`, a bare `carryover` label) and `broken-window` closure issues bypass the cap unconditionally. Without those exemptions the cap would break the standing session-end promises in `skills/session-end/SKILL.md` (Phase 1.8 "non-deselectable" SPIRAL/FAILED carryover, and the Critical Rule "ALWAYS create issues for unfinished PLANNED work"). Exempt creations are counted in the state file's `exempt` field for observability but never blocked.
 
 **Counter file:** `.orchestrator/runtime/issue-budget/<sha256(sessionId)[0..16]>.json` — `{ sessionId, count, exempt, overflow: [...] }`, ONE file per session (#1141: the former single `issue-budget.json` slot was reset by whichever session wrote last, so two sessions in one working copy silently disabled each other's cap). Identity-less callers still use the legacy flat path; `budgetStatePath(repoRoot, sessionId)` in `scripts/lib/issue-budget.mjs` is the resolver.
 
-**Used by:** `hooks/pre-bash-issue-budget.mjs` (shell path, PreToolUse/Bash), `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), `scripts/lib/issue-budget.mjs` (shared decision core), `skills/session-end/SKILL.md` Phase 5 Step 3b (overflow drain). Parser: `scripts/lib/config/issue-budget.mjs`.
+**Close-time reconcile (#1163).** The cap is enforced by a PreToolUse hook, which only sees the shell routes it pattern-matches — every unmatched creation route (a GUI-created issue, an unmatched CLI form) is a silent zero: no ledger line, no error, indistinguishable from "created nothing". `scripts/lib/issue-budget-reconcile.mjs` closes that gap at session-end by comparing two independently-produced numbers: `recorded` (`record.issues_created.length` from the session record) against `charged + exempt` (summed over BOTH the semantic-id and raw-id ledger keys — which key a given session's counter file used depends on a condition, `resolveIssueBudgetSessionId`, that can change mid-session). It emits `orchestrator.issue_budget.reconciled` with a `verdict`: `match` (recorded ≤ charged + exempt), `escaped` (`recorded > charged + exempt` — some creations bypassed the hook), `no-ledger` (`recorded > 0` and no counter file existed under either key — the hook never ran once), or `stale-record` (a ledger exists but the record shows 0 recorded with a positive charge). Fail-open by contract: nothing in this module throws, and a close-time cross-check that could abort the close would be strictly worse than one that reports `no-ledger`.
+
+**Used by:** `hooks/pre-bash-issue-budget.mjs` (shell path, PreToolUse/Bash, now charges **per statement** rather than per whole command — see `hooks/_lib/vcs-create-matcher.mjs`, which also matches `gh|glab api … POST …/issues`), `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), `scripts/lib/issue-budget.mjs` (shared decision core + `resolveMaxPerSession`/`readSessionTypeFromStateMd`), `scripts/lib/issue-budget-reconcile.mjs` (close-time cross-check), `skills/session-end/SKILL.md` Phase 5 Step 3b (overflow drain). Parser: `scripts/lib/config/issue-budget.mjs`.
 
 ## Slopcheck (Package Legitimacy Gate) (#520)
 
@@ -306,6 +331,8 @@ slopcheck:
 | `persistence` | boolean | `true` | Enable session resumption via STATE.md and session memory files. |
 | `memory-cleanup-threshold` | integer | `5` | Recommend `/memory-cleanup` after N accumulated session memory files. |
 | `memory-cleanup-soft-limit` | integer | `180` | Hard ceiling on accumulated memory files before the cleanup nudge escalates from a soft suggestion to a strong recommendation. PRD F2.2 / issue #502. Used by `scripts/lib/auto-dream.mjs`. |
+
+**Nudge retirement (2026-09-09, #1246-adjacent).** The two session-end nudges that used to read these thresholds — Phase 3.6.5 Auto-Dream and Phase 3.6.7 Auto-Dialectic — are RETIRED as standalone close-time prompts: measured across consumer repos, the auto-dialectic nudge recorded `decided: true` while nobody ever ran it, and memory-cleanup had run in only 1 of 3 repos, because both fired at the moment the operator is closing down, not the moment they can act. `shouldDispatchAutoDream()` and `shouldDispatchAutoDialectic()` are unchanged as pure signal functions and still consult these two keys — but they are now called from the session-START `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`, see § Reconcile below), which reads them as two of its six signals and reports a single `⚠ maintenance due: N of 6 …` banner at the one moment the operator can actually run `/session housekeeping`.
 | `learning-expiry-days` | integer | `30` | Legacy/default expiry window used by review/extend flows. New analyzer learnings preserve a candidate-supplied `expires_at` or derive expiry from `LEARNING_TTL_DAYS[type]` (for example, `autonomy-verdict` is 90 days). |
 | `learnings-surface-top-n` | integer | `15` | Cap on how many learnings the session-start Phase 5.6 and session-plan Step 0.5 sections surface, ranked by confidence descending. `0` = do not surface any learnings. Applies to Project Intelligence output. |
 | `learning-decay-rate` | float (0.0 ≤ x < 1.0) | `0.05` | Confidence decay applied to every untouched learning at session-end (after touched-set update, before prune). `0.0` = disable decay. A learning starting at `0.5` confidence survives ~10 untouched sessions with default decay. |
@@ -315,8 +342,8 @@ slopcheck:
 | `reasoning-output` | boolean | `false` | Enable STATE:/PLAN: structured reasoning markers in agent prompts. When true, agents emit short transparency lines before tool calls. Opt-in — adds prompt overhead. |
 | `grounding-check` | boolean | `true` | Enable file-level grounding verification in session-end Phase 1.1a (planned vs touched files). When true, session-end compares each agent's declared file scope against `git diff --name-only $SESSION_START_REF..HEAD` and reports scope creep + incomplete coverage. Informational — does not block session close. |
 | `grounding-injection-max-files` | integer | `3` | Max files with recent `edit-format-friction` stagnation history to inject as line-numbered GROUNDING blocks into each agent's prompt before dispatch (wave-executor pre-dispatch step). Per-agent scope; selects top N by recency. `0` disables the feature. Gated on `persistence: true`. (#85) |
-| `isolation` | string | `auto` | Agent isolation mode: `worktree`, `none`, or `auto`. `auto` resolves per-wave via the graduated default (#194): ≤2 agents → `none`, 3–4 agents on feature/deep → `worktree`, ≥5 agents → `worktree`, housekeeping 3–4 → `none`. Explicit `worktree` or `none` overrides the graduation. See [isolation graduation](#isolation-graduation) below. |
-| `max-turns` | integer or string | `auto` | Maximum agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
+| `isolation` | string | `auto` | Agent isolation mode: `worktree`, `none`, or `auto`. `auto` resolves per-wave via the graduated default (#194): ≤2 agents → `none`, 3–4 agents on feature/deep → `worktree`, ≥5 agents → `worktree`, housekeeping 3–4 → `none`. Explicit `worktree` or `none` overrides the graduation. The resolved value surfaces per wave as `waves[].isolation` in the session shape's JSON output (`scripts/session-shape.mjs`) — a coordinator-direct or read-only wave resolves `none` without consulting the graduation at all. See [isolation graduation](#isolation-graduation) below. |
+| `max-turns` | integer or string | `auto` | Maximum agent turns before PARTIAL. Auto expands PER SESSION TYPE inside the resolved shape (`scripts/lib/session-shape.mjs` `MAX_TURNS_DEFAULT`, § Session Shapes above): housekeeping=8, feature=15, deep=25 (`maxTurnsDefault` in the shape JSON, applied to every wave). The `ultradeep` profile does **not** use one flat number — it sets `max-turns` PER WAVE: 40 for the Research+Code-Discovery wave, 25 for Impl-Core/Impl-Polish/Quality, 15 for Release/Finalization (the Synthesis-Gate wave is coordinator-direct and carries no `max-turns` at all). |
 | `auto-commit-per-wave` | boolean | `false` | Automatically commit each wave's work after the Quality-Lite gate passes. Checkpoint commits per wave reduce the risk of data loss from `git stash` collisions in parallel sessions (V3.3 RESCUE incident — see GitLab #214). When `false`, all work is committed at session-end via `/close`. Requires `persistence: true`; the flag is silently ignored when `persistence: false`. Trade-off: each wave produces an additional commit; git log shows N+1 commits instead of 1. Use `/simplify` or `git rebase -i --autosquash` before final close to squash if a clean history is desired. **Implementation note:** the procedural commit sequence (`scripts/lib/auto-commit.mjs`) is deferred to V3.6. Until then, setting this flag to `true` triggers a session-start warning that auto-commits are not yet active — the flag is a no-op but is validated so projects can opt in early. <!-- path-check: historical --> |
 
 ### enforcement-gates: the five gate keys (#800/#915)
@@ -588,7 +615,7 @@ This guard converts the manual post-copy `git diff` check (used to rescue the 07
 
 ### Heavy-Repo Preflight (HR-003/HR-004, baseline #60)
 
-`templates/shared/.claude/rules/heavy-repo.md` documents two Session Config fields for repos large enough that default parallelism risks resource pressure (HR-001 indicators: checkout > 50 MB, DB surface > 100 tables, prior parallel agent count > 15, build time > 90s, generated artifacts > 200 MB). Both fields are now wired end-to-end (previously documented but silently dropped by the parser):
+The two Session Config fields below apply to repos large enough that default parallelism risks resource pressure (HR-001 indicators: checkout > 50 MB, DB surface > 100 tables, prior parallel agent count > 15, build time > 90s, generated artifacts > 200 MB). The parser accepts both fields; their runtime effects and remaining limits are listed below:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -636,7 +663,7 @@ Requires:
 
 If the fetch fails (network error, auth error, missing file), bootstrap continues without aborting — rules will arrive via the legacy Clank sync path. A warning is printed.
 
-See: session-orchestrator issue #110, projects-baseline `docs/REPO-STATUS.md`.
+See: session-orchestrator issue #110, projects-baseline `docs/REPO-STATUS.md`. <!-- path-check: example -->
 
 ### baseline-project-id
 
@@ -740,7 +767,7 @@ vault-integration:
 
 > **Host-local override (#653; extended #819).** `vault-dir` resolves host-locally with precedence: env-var (`SO_VAULT_DIR`) > `owner.yaml` `paths.vault-dir` > the committed default. `plan-baseline-path` resolves with an extra per-context tier in between: `SO_BASELINE_PATH` env > `owner.yaml` `baselines:` directory-prefix match against cwd > `owner.yaml` `paths.baseline-path` (legacy scalar) > the committed default. This keeps maintainer-specific absolute paths out of version control. Resolvers: `scripts/lib/config/host-paths.mjs` (both keys) and `scripts/lib/named-baseline-resolver.mjs` (the `baselines:` match tier).
 
-> **`SO_CONFIG_HOME` — the host-private config directory itself.** A sibling override, one layer below `owner.yaml`'s own contents rather than a key inside it: `scripts/lib/host-identity.mjs` `_privateDir()` resolves the directory holding `owner.yaml`, `host-private.json`, and the host-alias ledger (`SO_HOST_ALIASES_FILE`, see `host-identity.mjs`) with precedence env-var (`SO_CONFIG_HOME`, names the private dir ITSELF) > `XDG_CONFIG_HOME` (names its PARENT — `owner-config-loader.mjs` uses the same variable the same way) > the homedir default `~/.config/session-orchestrator`. Both env vars are read with `.trim() || fallback`, not a bare `||` (`.claude/rules/development.md` § Error Handling env-var-fallback-whitespace trap).
+> **`SO_CONFIG_HOME` — the host-private config directory itself.** A sibling override, one layer below `owner.yaml`'s own contents rather than a key inside it: `scripts/lib/config/private-config-dir.mjs` (`resolvePrivateConfigDir()`) is THE resolver (#1223) for the directory holding `owner.yaml`, `host-private.json`, and the host-alias ledger (`SO_HOST_ALIASES_FILE`) — `scripts/lib/host-identity.mjs`'s `_privateDir()` delegates to it — with precedence env-var (`SO_CONFIG_HOME`, names the private dir ITSELF) > `XDG_CONFIG_HOME` (names its PARENT) > the homedir default `~/.config/session-orchestrator`. Both env vars are read with `.trim() || fallback`, not a bare `||` (`.claude/rules/development.md` § Error Handling env-var-fallback-whitespace trap).
 
 > **Parser accepts three key-line renderings (#823).** The `vault-integration:` key line is recognized in plain form (`vault-integration:`), dash-bullet form (`- vault-integration:`), and bold-bullet form (`- **vault-integration:**`) — each paired with either the inline-object shape (`{ enabled: true, ... }` on the same line) or the indented block shape shown above. Parser: `scripts/lib/config/vault-integration.mjs` (`_parseVaultIntegration`).
 
@@ -968,7 +995,7 @@ broken-window-budget:
 
 ## Dialectic-Deriver (#506)
 
-Opt-in mode for `/evolve --dialectic` and session-end Phase 3.6.7 auto-trigger. When `cadence > 0`, session-end auto-dispatches `/evolve --dialectic --dry-run` after every N sessions to produce a proposed update to USER.md/AGENT.md peer cards (#503). The dry-run writes a sidecar at `.orchestrator/dialectic-pending.md`; the operator applies via `/evolve --dialectic --apply` in a subsequent session. Set `cadence: 0` as a kill-switch.
+Opt-in mode for `/evolve --dialectic`. When `cadence > 0`, the session-START `maintenance-due` probe reports a due dialectic after every N sessions, and the housekeeping loop runs `/evolve --dialectic --dry-run` to produce a proposed update to USER.md/AGENT.md peer cards (#503). The dry-run writes a sidecar at `.orchestrator/dialectic-pending.md`; the operator applies via `/evolve --dialectic --apply` in a subsequent session. Set `cadence: 0` as a kill-switch. <!-- path-check: example -->
 
 All fields live under a top-level `dialectic` object in your Session Config (CLAUDE.md or AGENTS.md):
 
@@ -981,15 +1008,15 @@ dialectic:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `dialectic.cadence` | integer | `5` | Number of sessions between auto-dialectic dispatches. Set to `0` to disable all dispatches (kill-switch). Non-integer and negative values silently fall back to default. |
+| `dialectic.cadence` | integer | `5` | Number of sessions between auto-dialectic dispatches. Set to `0` to disable all dispatches (kill-switch). Non-integer and negative values silently fall back to default. **The dispatch moment moved (2026-09-09):** `shouldDispatchAutoDialectic()` is still the decision function this key feeds, but session-end Phase 3.6.7's own auto-trigger nudge is gone — retired as a standalone close-time prompt, and its recording wrapper (with the `orchestrator.dialectic.nudge_decided` event) removed in #1288 — see § Persistence & Safety above "Nudge retirement". The session-start `maintenance-due` probe now calls it as one of six signals, so a due dialectic surfaces where the operator can act on it (session start), not where they are closing down. |
 | `dialectic.model` | string | `haiku` | Model tier for the critique call. Must be one of `haiku`, `sonnet`, `opus`. **Fail-fast**: unknown values cause parse-config.mjs to exit 1 at startup — NOT silently ignored. |
 | `dialectic.budget-tokens` | integer | `8000` | Input token budget per call. Output budget is fixed at 4000 (per #506). Non-integer and negative values fall back to default. |
 
-**Used by:** `skills/evolve/SKILL.md` Phase 6, `skills/session-end/SKILL.md` Phase 3.6.7, `scripts/dialectic-deriver.mjs`, `scripts/lib/auto-dialectic.mjs`.
+**Used by:** `skills/evolve/SKILL.md` Phase 6, `scripts/dialectic-deriver.mjs`, `scripts/lib/auto-dialectic.mjs`, and the session-start `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`). Session-end Phase 3.6.7 no longer reads it (retired 2026-09-09).
 
 **Cross-reference:** PRD F2.5 (#506) — Honcho's "reasoning at consolidation time" insight, adopted without SaaS/AGPL/per-message-LLM-cost.
 
-**Auto-trigger behavior:** When `cadence > 0` AND sessions-since-last-dialectic ≥ cadence AND (≥1 new session OR ≥1 new learning since last run), session-end Phase 3.6.7 dispatches the deriver in dry-run mode. The diff sidecar lands at `.orchestrator/dialectic-pending.md` (gitignored, vault-mirror-excluded). When `cadence: 0`, the auto-trigger is permanently skipped; manual `/evolve --dialectic` always works.
+**Trigger behavior:** When `cadence > 0` AND sessions-since-last-dialectic ≥ cadence AND (≥1 new session OR ≥1 new learning since last run), `shouldDispatchAutoDialectic()` returns `trigger: true` and the session-start `maintenance-due` probe reports it; the housekeeping session then runs the deriver in dry-run mode (session-end Phase 3.6.7 is retired — it dispatches nothing). The diff sidecar lands at `.orchestrator/dialectic-pending.md` (gitignored, vault-mirror-excluded). When `cadence: 0`, the signal never fires; manual `/evolve --dialectic` always works. <!-- path-check: example -->
 
 **Token cost:** With defaults (cadence: 5, budget-tokens: 8000, output 4000, model haiku), ~12k tokens every 5 sessions. At haiku pricing this is ~$0.02/run. Surfaced in Final Report.
 
@@ -997,7 +1024,9 @@ dialectic:
 
 ## Eval (#803)
 
-Opt-in configuration for the Standard v1 evaluation harness (aiat-llm-eval PRD, `docs/prd/2026-07-16-aiat-llm-eval.md` §S6) and the forthcoming `/eval` skill (Session-Prozess-Eval — lands in a later wave of Epic #803). This section documents the config surface only; the skill that reads it is not yet shipped as of this parser's introduction.
+Opt-in configuration for the Standard v1 evaluation harness and the `/eval` skill (Session-Prozess-Eval). The current workflow is documented in `skills/eval/SKILL.md`.
+
+The original config proposal is in the archived PRD `docs/prd/2026-07-16-aiat-llm-eval.md` §S6 (Epic #803). <!-- path-check: historical -->
 
 All fields live under a top-level `eval` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
@@ -1314,6 +1343,8 @@ Read by: `scripts/lib/config/evolve.mjs` (parser), `skills/evolve/SKILL.md` Step
 
 Opt-in configuration for the learning→conditional-rule reconciliation engine (Epic #693). When enabled, the reconciliation engine runs at session-end Phase 3.6.8 and proposes new `.claude/rules/` entries derived from accumulated learnings. The proposal is always operator-AUQ-gated — rules are **never** auto-applied. FA3 (#696) delivers proposals via `AskUserQuestion`; FA4 (#697) adds the guardrail config block documented here. When `enabled: false` (the default), Phase 3.6.8 is a silent no-op and the engine never runs.
 
+**The former `reconcile-nudge` session-start probe is SUBSUMED (2026-09-09), not replaced 1:1.** `reconcile-nudge-banner.mjs`'s `computeReconcileNudge()` function is unchanged and still the reconcile-specific signal — but it is no longer surfaced as its own standalone banner. `scripts/lib/maintenance-due-banner.mjs` now calls it wholesale as one of six ANDed maintenance signals (`reconcile: computeReconcileNudge().nudge === true`) behind the single session-start `maintenance-due` probe, alongside `evolve`, `sweep`, `dialectic`, `memory-cleanup` and `pending-sidecar`. The reconcile signal is therefore not lost — it is reported as `⚠ maintenance due: N of 6 (…) — run /session housekeeping.` rather than as its own line, with a 7-day cooldown after any housekeeping session (`HOUSEKEEPING_COOLDOWN_DAYS`) so a repo that just ran the loop stays silent instead of re-nagging.
+
 All fields live under a top-level `reconcile` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
 ```yaml
@@ -1447,7 +1478,7 @@ frontend-slop-hook:
 
 **Used by:** `hooks/post-tooluse-frontend-slop.mjs` (parser/loader: `scripts/lib/config/frontend-slop-hook.mjs`).
 
-**Cross-reference:** detector rule markers (`<!-- rule:<id> -->`) live in `.claude/rules/frontend.md` (Absolute Bans / Motion / Layout sections). Mirrors the opt-in / default-on contrast against `loop-guard`.
+**Cross-reference:** detector rule markers (`<!-- rule:<id> -->`) live in `rules/opt-in-stack/frontend.md` (Absolute Bans / Motion / Layout sections). Mirrors the opt-in / default-on contrast against `loop-guard`.
 
 ## Loop Guard (#619)
 
@@ -1593,7 +1624,9 @@ Both variables must be set for the fire-and-forget POST to fire. Setting only `C
 
 ## Express Path (#214)
 
-Codified coordinator-direct flow for housekeeping and simple single-issue sessions. When the express path activates, session-start Phase 8.5 skips the full 5-wave plan decomposition and runs all tasks directly as the coordinator — no subagents dispatched, no inter-wave checkpoints.
+Codified coordinator-direct flow for housekeeping and simple single-issue sessions. When the express path activates, session-start Phase 8.5 skips session-plan's full wave decomposition and runs all tasks directly as the coordinator — no subagents dispatched, no inter-wave checkpoints.
+
+**Relationship to § Session Shapes (2026-09-09).** The 1-wave `coordinator-direct` plan session-plan emits when the express path is active is the SAME shape `resolveSessionShape({sessionType: 'housekeeping'})` now resolves for EVERY housekeeping session, express-path gate or not — a single coordinator-direct "Housekeeping" wave running the maintenance loop (drift-check, sweep, evolve, reconcile, dialectic, memory-cleanup). Express path is the ACTIVATION GATE that decides whether the coordinator runs those tasks inline right now (its 3 conditions below); the housekeeping shape decides the wave STRUCTURE, and is unconditional for the type since the former 3/4/6+-wave role-combination mapping was retired 2026-09-09 for every session type. Housekeeping therefore has no "full 5-wave flow" left to fall back to — see the corrected condition-matrix note below.
 
 > **Historical context:** The 13 coordinator-direct sessions documented in the project `CLAUDE.md` (2026-04 series: vault-mirror GH#31, phased-rollout #307, v3.2.0 release, Architecture-DDD-Trio, etc.) were running this pattern implicitly without a codified path. Issue #214 codifies it so that future housekeeping sessions gain the express path automatically without needing to know to opt in manually.
 
@@ -1601,12 +1634,12 @@ All fields live under a top-level `express-path` object in your Session Config h
 
 ```yaml
 express-path:
-  enabled: true   # default true; set false to always use the full 5-wave flow
+  enabled: true   # default true; set false to always run session-plan's full decomposition flow
 ```
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `express-path.enabled` | boolean | `true` | When `true`, session-start Phase 8.5 evaluates the express-path activation conditions. When `false`, the evaluation is skipped and the full session-plan 5-wave flow always runs. |
+| `express-path.enabled` | boolean | `true` | When `true`, session-start Phase 8.5 evaluates the express-path activation conditions. When `false`, the evaluation is skipped and session-plan always runs its full decomposition flow — for a housekeeping session that flow still resolves to the same 1-wave shape (§ Session Shapes), since `express-path.enabled` only gates whether the coordinator runs it INLINE right now, not the wave count. |
 
 ### Activation conditions
 
@@ -1616,7 +1649,7 @@ All three conditions must be true simultaneously for the express path to activat
 2. Session type is `housekeeping` (confirmed in session-start Phase 8 Q&A)
 3. Agreed issue scope is ≤ 3 issues AND no parallel agents are required
 
-When any condition is false, the full 5-wave flow runs as before — the check is a transparent no-op.
+**When any condition is false, session-plan runs its full decomposition flow as before** — the express-path check is a transparent no-op on the PLAN, not on the wave shape. For `feature` and `deep` sessions this was always their own resolved shape (3 and 5 waves respectively, per § Session Shapes) and is unaffected by this gate. For a `housekeeping` session that fails the gate (≥4 issues, or parallel agents required), the older documentation here described a fallback to "the full 5-wave flow" — that fallback no longer exists: `resolveSessionShape({sessionType: 'housekeeping'})` returns the same 1-wave coordinator-direct maintenance-loop shape unconditionally, so the practical difference the gate still makes is whether the coordinator executes that one wave INLINE (gate passed) or session-plan emits it as a normal — still 1-wave, still coordinator-direct — plan for wave-executor to run (gate failed).
 
 ### What changes when express path is active
 
@@ -1629,9 +1662,9 @@ When any condition is false, the full 5-wave flow runs as before — the check i
 
 Set `express-path.enabled: false` when:
 
-- You want all housekeeping sessions to go through the standard quality-gate pipeline (Discovery + Quality waves).
+- You want session-plan to emit housekeeping's maintenance-loop wave as a normal wave-executor plan instead of running it inline as the coordinator — the wave STRUCTURE is unchanged either way (§ Session Shapes), only whether it runs inline or through the wave-executor dispatch/checkpoint machinery.
 - The session involves ≥ 4 issues (the scope check already prevents activation, but disabling makes the intent explicit).
-- You are running an automated `/autopilot` loop and want predictable wave counts across session types.
+- You are running an automated `/autopilot` loop and want a predictable inline-vs-dispatched execution path across session types.
 
 ### Condition matrix
 
@@ -1653,7 +1686,7 @@ Set `express-path.enabled: false` when:
 
 The `autopilot` block and its single field `autopilot.bg-isolation` are **gone**, not
 deprecated. Their only reader was `scripts/autopilot-multi.mjs`, retired together with <!-- path-check: historical -->
-`commands/autopilot-multi.md` by the 2026-09-06 360°-Audit (§ 5A: 0 telemetry, 0 fleet
+`commands/autopilot-multi.md` by the 2026-09-06 360°-Audit (§ 5A: 0 telemetry, 0 fleet <!-- path-check: historical -->
 invocations in 90 days, no runtime consumer).
 
 Verified 2026-09-06 at `e4674109`: