session-orchestrator 4.1.0 → 5.0.0

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.

package/docs/USER-GUIDE.md

@@ -96,7 +96,7 @@ enforcement: warn
 vcs: github
 ```
 
-If you skip this step, the plugin uses sensible defaults: `feature` type, 6 agents per wave, 5 waves, and auto-detected VCS. See [`docs/session-config-template.md`](session-config-template.md) for the full field walkthrough.
+If you skip this step, the plugin uses sensible defaults: `feature` type (a fixed 3-wave shape — see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes for the full per-type wave/agent-cap table), 6 agents per wave, and auto-detected VCS. See [`docs/session-config-template.md`](session-config-template.md) for the full field walkthrough.
 
 ### Run your first session
 
@@ -198,6 +198,22 @@ You can also run the bootstrap flow explicitly, outside of any session:
 
 `--retroactive` is the recommended path for existing repos that predate the Bootstrap Gate — it adds the missing `CLAUDE.md` structure and lock file without touching your existing code or configuration.
 
+### Use a configured baseline
+
+Standard and Deep bootstrap can read the validated archetype contract from your
+configured local baseline. Existing project markers select a matching archetype;
+an empty or unrecognized project presents the baseline's available choices.
+The selected contract supplies templates, runtime and package-manager versions,
+commands, CI expectations, and required rules. Existing project files are
+preserved and reported for review.
+
+Configuration resolves from `SO_BASELINE_PATH`, a matching named baseline,
+`owner.yaml` paths, then the project's `plan-baseline-path`. Lookup is offline
+and does not install packages. An absent baseline uses the bundled public
+templates; an invalid configured contract stops before writing files. Missing
+quality gates are reported as unavailable. See [Baseline integration](baseline.md)
+for the contract and configuration details.
+
 ### Anti-bureaucracy promise
 
 - **Normal flow:** exactly 1 question (tier confirmation)
@@ -285,29 +301,47 @@ Structured requirement gathering, PRD generation, and issue creation. Accepts on
 
 **Optional:** `plan-baseline-path` in Session Config (for `/plan new` repo scaffolding from your own baseline). When absent, `/bootstrap` falls back to plugin-bundled minimal templates. Not required for `/plan feature` or `/plan retro`.
 
+**Optional private capability context:** For new-project or session planning, you can
+supply a small catalog excerpt or authorize a particular offline, read-only local
+catalog lookup and state that its planning destination is private/internal. The
+planner uses at most five matches to explain reuse alternatives and remaining
+contract checks. Existing authorization carries forward. Missing or unsuitable
+context leaves ordinary planning available; a match does not authorize adoption.
+Private findings stay out of public output and generated repositories. This needs
+no new Session Config key; see the [shared procedure](../skills/_shared/private-capability-context.md).
+
 ---
 
 ## 4. Session Types
 
-### Housekeeping
+Wave count, roles, and per-wave agent caps are resolved by one module — `scripts/lib/session-shape.mjs` — not derived by hand from `waves`/`agents-per-wave`. Run the CLI yourself to see exactly what a given mode resolves to before starting a session:
+
+```
+node scripts/session-shape.mjs --repo-root "$PWD" --session-type <housekeeping|feature|deep> \
+  [--profile ultradeep] [--known-scope true|false] --no-event
+```
+
+It prints one JSON line (`totalWaves`, `waves[]` with each wave's `role`/`agentCap`/`maxTurns`/`verification`, `discovery`, `wavesConfigHonored`, `notes`) and, without `--no-event`, records `orchestrator.session.shape_resolved` to `.orchestrator/metrics/events.jsonl`.
+
+### Housekeeping — the maintenance loop
 
 Best for: git cleanup, SSOT refresh, CI fixes, branch merges, documentation updates.
 
-- **Execution model:** Serial (no wave structure)
-- **Agents:** 1-2 per task
+- **Execution model:** **1 coordinator-direct wave.** Housekeeping *is* the maintenance loop: drift-check → expired-learnings sweep → `/evolve analyze` → `/reconcile` → `/evolve dialectic` → `/memory-cleanup`, then any operator-selected housekeeping issues appended in the order picked. No wave-executor dispatch for the loop itself — most of those steps are `AskUserQuestion`-gated, and AUQ does not exist inside a dispatched subagent.
+- **Agents:** 0 dispatched for the loop (the coordinator runs it directly); the dialectic step dispatches the read-only `dialectic-deriver` subagent.
 - **Typical duration:** Short
-- **Use when:** Your repo needs maintenance, not new features
+- **Use when:** Your repo needs maintenance, not new features — or when the session-start `maintenance-due` banner tells you it's overdue.
 
 ```
 /session housekeeping
 ```
 
-### Feature
+### Feature — 3 waves
 
 Best for: frontend/backend feature work, implementing issues, standard development.
 
-- **Execution model:** 5 waves with parallel agents
-- **Agents:** 4-6 per wave (configurable)
+- **Execution model:** 3 waves — Impl-Core → Impl-Polish+Quality → Finalization.
+- **Agents:** capped at 4 / 4 / 2 respectively (subject to `agents-per-wave`).
 - **Typical duration:** Medium
 - **Use when:** You have feature issues to implement
 
@@ -315,12 +349,12 @@ Best for: frontend/backend feature work, implementing issues, standard developme
 /session feature
 ```
 
-### Deep
+### Deep — 5 waves (4 when scope is already known)
 
 Best for: complex backend work, security audits, database refactoring, architecture changes.
 
-- **Execution model:** 5 waves with parallel agents
-- **Agents:** Up to 10-18 per wave (configurable)
+- **Execution model:** 5 waves — Discovery → Impl-Core → Impl-Polish → Quality → Finalization. When the agreed scope is already fully known (`--known-scope true`), Discovery is dropped and the rest renumbered to 4 waves.
+- **Agents:** capped at 8 / 10 / 8 / 6 / 4 per wave respectively (subject to `agents-per-wave`).
 - **Typical duration:** Longer
 - **Use when:** The work requires extensive discovery, testing, or touches critical systems
 
@@ -328,6 +362,19 @@ Best for: complex backend work, security audits, database refactoring, architect
 /session deep
 ```
 
+### Ultradeep — 7 fixed waves (a profile over `deep`)
+
+Best for: sessions that outgrow 5 waves — large audits, work needing web research before implementation, or a release that benefits from an independent review panel.
+
+- **Execution model:** a **fixed 7-wave shape** — Research+Code-Discovery → Synthesis-Gate (coordinator-direct, 0 agents, blocking `AskUserQuestion`) → Impl-Core → Impl-Polish → Review-Panel (read-only) → Quality → Release/Finalization. It IGNORES the `waves` Session Config value outright (`wavesConfigHonored: false`) — there is no "waves < 7 is an error" check; the profile just reports that it ignored the configured number.
+- **Agents:** capped at 18 / 0 / 8 / 8 / 3 / 6 / 4 per wave respectively; `max-turns` is set PER WAVE (40 / — / 25 / 25 / 25 / 25 / 15), not one flat number.
+- **Typical duration:** Longest
+- **Use when:** `/session deep` would work but the scope needs research first, or you want a dedicated review panel before Quality.
+
+```
+/session deep --profile ultradeep    # or the /session ultradeep alias, per commands/session.md
+```
+
 ---
 
 ## 5. Session Config Reference
@@ -372,8 +419,8 @@ Add a `## Session Config` section to your project's Session Config host file to
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agents-per-wave` | integer | `6` | Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources. |
-| `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
+| `agents-per-wave` | integer | `6` | Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources. Supports the per-type override syntax `6 (deep: 18)` — see [§ 4 Session Types](#4-session-types). |
+| `waves` | integer | `5` | Base wave count. The wave count actually used is resolved per session type by `scripts/session-shape.mjs` (see [§ 4 Session Types](#4-session-types)) — `feature` and `deep` each have one natural shape and ignore a disagreeing `waves` value; the `ultradeep` profile ignores it outright. |
 | `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
 | `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
 | `ssot-files` | list | none | Single Source of Truth files to track for freshness (e.g., `STATUS.md`, `STATE.md`). Flagged if older than 5 days. |
@@ -392,7 +439,7 @@ Add a `## Session Config` section to your project's Session Config host file to
 | `issue-limit` | integer | `50` | Maximum issues to fetch when querying VCS during session start. |
 | `stale-branch-days` | integer | `7` | Days of inactivity before a branch is flagged as stale. |
 | `stale-issue-days` | integer | `30` | Days without progress before an issue is flagged for triage. |
-| `discovery-on-close` | boolean | `false` | Run discovery probes automatically during `/close`. |
+| `discovery-on-close` | boolean | `true` | Run discovery probes automatically during `/close`. `auto` or an absent key means `true`; set `false` explicitly for a faster close. |
 | `discovery-probes` | list | `[all]` | Probe categories to run: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature`. |
 | `discovery-exclude-paths` | list | `[]` | Glob patterns to exclude from discovery scanning (e.g., `vendor/**`, `dist/**`). |
 | `discovery-severity-threshold` | string | `low` | Minimum severity for reported findings: `critical`, `high`, `medium`, `low`. |
@@ -414,7 +461,7 @@ Add a `## Session Config` section to your project's Session Config host file to
 | `cold-start.silence-after-sessions` | integer | `1` | Consecutive silent sessions (no commits, no learnings) before the cold-start detector fires a nudge. PRD F1.3 / issue #500. |
 | `enforcement` | string | `warn` | Hook enforcement level for scope and command restrictions: `strict`, `warn`, or `off`. |
 | `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`. See Section 15 "Isolation Graduation" below. |
-| `max-turns` | integer or string | `auto` | Max agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
+| `max-turns` | integer or string | `auto` | Max agent turns before PARTIAL. Auto-resolves per session shape (`scripts/lib/session-shape.mjs`): 8 for housekeeping, 15 for feature, 25 for deep — applied to every wave. The `ultradeep` profile sets it PER WAVE instead (40 for Research+Code-Discovery, 25 for Impl-Core/Impl-Polish/Quality, 15 for Release/Finalization). See [§ 4 Session Types](#4-session-types). |
 
 > **Security:** Do not embed credentials, API keys, or auth tokens in Session Config fields — especially `health-endpoints` URLs. These values are stored in your config host file (`CLAUDE.md` / `AGENTS.md`) which may be committed to version control. Use header-based auth or separate secret management instead.
 
@@ -434,7 +481,7 @@ See [examples](examples/) for project-specific configurations (Next.js, Express
 
 ## 6. The Wave Pattern
 
-Feature and deep sessions execute work in structured waves, each assigned one of 5 roles. Each wave has a specific purpose, and agents within a wave run in parallel.
+Feature and deep sessions execute work in structured waves drawn from the same 5 named roles (some combined into one wave, depending on session type — see [§ 4 Session Types](#4-session-types)). Each wave has a specific purpose, and agents within a wave run in parallel.
 
 ### Wave Structure
 
@@ -448,14 +495,15 @@ Feature and deep sessions execute work in structured waves, each assigned one of
 
 ### Role-to-Wave Mapping
 
-Roles map dynamically to the configured wave count (default: 5):
+**As of 2026-09-09, this mapping is resolved by `scripts/session-shape.mjs` per session type — it is no longer a function of the `waves` config value.** The former table (`waves: 3/4/5/6+` → a re-combined role mapping) is retired; a `waves` value that disagrees with a type's natural shape is now IGNORED and reported in the shape's `notes`, never used to re-combine roles. See [§ 4 Session Types](#4-session-types) for the CLI, and the per-type wave lists there:
 
-| `waves` | Mapping |
-|---------|---------|
-| 3 | W1=Discovery+Impl-Core, W2=Impl-Polish+Quality, W3=Finalization |
-| 4 | W1=Discovery, W2=Impl-Core+Impl-Polish, W3=Quality, W4=Finalization |
-| 5 | W1=Discovery, W2=Impl-Core, W3=Impl-Polish, W4=Quality, W5=Finalization |
-| 6+ | W1=Discovery, W2-W3=Impl-Core (split), W4-W5=Impl-Polish (split), W6=Quality+Finalization |
+| Session type | Waves | Roles |
+|---|---|---|
+| `housekeeping` | 1 | Housekeeping (coordinator-direct maintenance loop) |
+| `feature` | 3 | Impl-Core → Impl-Polish+Quality → Finalization |
+| `deep` (scope not yet known) | 5 | Discovery → Impl-Core → Impl-Polish → Quality → Finalization |
+| `deep` (scope known) | 4 | Impl-Core → Impl-Polish → Quality → Finalization |
+| `deep` + `ultradeep` profile | 7 (fixed, ignores `waves`) | Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization |
 
 ### Wave Details
 
@@ -476,13 +524,15 @@ One or two agents update SSOT files, close or update issues, write session hando
 
 ### Agent Counts by Session Type
 
+These are the shape table's RAW per-wave ceilings (`agentCapRaw` in the `scripts/session-shape.mjs` JSON) — not a range the orchestrator picks within by feel:
+
 | Session Type | Discovery | Impl-Core | Impl-Polish | Quality | Finalization |
 |-------------|-----------|-----------|-------------|---------|-------------|
-| housekeeping | 2 | 2 | 1 | 1 | 1 |
-| feature | 4-6 | 6 | 4-6 | 4 | 2 |
-| deep | 6-8 | 6-10 | 6-8 | 6 | 2-4 |
+| housekeeping | — | — (0, coordinator-direct) | — | — | — |
+| feature | — | 4 | 4 (combined w/ Quality) | *(combined)* | 2 |
+| deep | 8 | 10 | 8 | 6 | 4 |
 
-The `agents-per-wave` config value caps the maximum. These counts are guidelines — the orchestrator adjusts based on task complexity.
+**The number actually used (`agentCap`) is `min(raw, agents-per-wave)`.** With the documented default `agents-per-wave: 6`, a `deep` session's Discovery/Impl-Core/Impl-Polish waves are clipped DOWN to 6 — the 8/10/8 above only apply once you raise the cap for that type, e.g. `agents-per-wave: 6 (deep: 18)` (this plugin's own committed config). `feature`'s 4/4/2 already sit under the default 6 and are unaffected by it. These are still ceilings, not targets — the orchestrator adjusts DOWN based on task complexity, per the tier guidance below.
 
 The **Quality column is a cap, not a target**: since this version, test-writing capacity is need-gated on measured demand — roughly one test-writer per three HIGH/MED gaps the review panel actually found, capped by the number above. If no gaps were measured, the Quality wave writes no tests and is skipped (the read-only review panel still runs); with no measurement signal at all, the orchestrator allocates a conservative 1-2 rather than the full cap.
 
@@ -546,18 +596,21 @@ After you choose a direction, the orchestrator decomposes the work into a role-b
 ```
 ## Wave Plan (Session: feature)
 
-### Wave 1: Discovery (4 agents)
-- Agent 1: Audit API endpoint structure → src/api/ → map current routes
-- Agent 2: Verify database schema → prisma/schema.prisma → check relations
-...
+A `feature` session resolves to 3 waves — no Discovery wave; see [§ 4 Session Types](#4-session-types).
 
-### Wave 2: Impl-Core (6 agents)
+### Wave 1: Impl-Core (4 agents)
 - Agent 1: Implement new API route → src/api/users.ts → endpoint returns 200
+- Agent 2: Add database migration → prisma/schema.prisma → check relations
+...
+
+### Wave 2: Impl-Polish+Quality (4 agents)
+- Agent 1: Build frontend form component → src/components/ → wired to the new route
+- Agent 2: Write and run tests → tests/api/users.test.mjs → passing
 ...
 
 ### Inter-Wave Checkpoints
 - After Impl-Core: Design review (Pencil configured)
-- After Quality: Full quality gate
+- After Impl-Polish+Quality: Full quality gate
 
 Ready to execute? Use /go to begin.
 ```
@@ -573,13 +626,12 @@ You can request changes to the plan. When satisfied:
 Waves execute automatically. Agents within each wave run in parallel. Between waves, the orchestrator reviews results, runs checks, and adapts the plan if needed. You see progress updates after each wave:
 
 ```
-## Wave 2 (Impl-Core) Complete ✓
+## Wave 1 (Impl-Core) Complete ✓
 - Agent 1: done — API route implemented, returns correct schema
 - Agent 2: done — Database migration created
-- Agent 3: done — Frontend form component built
 - Tests: 3 new passing | TypeScript: 0 errors
 - Design: ALIGNED
-- Adaptations for Impl-Polish: none
+- Adaptations for Impl-Polish+Quality: none
 ```
 
 ### Step 5: Close the session
@@ -875,7 +927,7 @@ The `/discovery` command runs systematic quality probes to find issues that don'
 
 ### Embedded Mode
 
-Set `discovery-on-close: true` in Session Config to automatically run discovery during `/close`. In embedded mode, critical/high findings become issues; medium/low are listed in the session report.
+Discovery runs automatically during `/close` by default (`discovery-on-close` absent, `true`, or `auto`); set `discovery-on-close: false` in Session Config to skip it. In embedded mode, critical/high findings become issues; medium/low are listed in the session report.
 
 ### Confidence Scoring
 
@@ -954,7 +1006,7 @@ Session Orchestrator persists session state so you can resume after crashes, pau
 
 ### STATE.md
 
-Lives at `.claude/STATE.md` in your project. Contains YAML frontmatter (`session-type`, `branch`, `issues`, `started`, `status`, `current-wave`, `total-waves`) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next `/session` invocation.
+Lives at `.claude/STATE.md` in your project. Contains YAML frontmatter (`session-type`, `branch`, `issues`, `started`, `status`, `current-wave`, `total-waves`) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next `/session` invocation. <!-- path-check: example -->
 
 ### Session Continuity
 
@@ -1163,7 +1215,7 @@ Read-only display of all active learnings with confidence scores and expiry date
 
 ## 18. Adaptive Wave Sizing
 
-Instead of fixed agent counts, the orchestrator scores session complexity and adjusts agent allocation dynamically.
+Instead of always dispatching a wave's full agent-cap ceiling, the orchestrator scores session complexity and relaxes agent allocation downward when the briefed work does not need the full cap.
 
 ### Complexity Scoring
 Three factors are scored (0-2 points each):
@@ -1177,18 +1229,11 @@ Three factors are scored (0-2 points each):
 ### Complexity Tiers
 - **Simple** (0-1 points): fewer agents per wave
 - **Moderate** (2-3 points): standard allocation
-- **Complex** (4-6 points): maximum agents per wave
+- **Complex** (4-6 points): up to the wave's cap
 
-### Dynamic Scaling Between Waves
-After each wave, agent count is adjusted based on performance:
-- All agents fast + no issues → reduce next wave
-- Failures or broken code → add fix agents
-- Scope expansion → scale up
-- Quality regressions → targeted fix agents
+The tier score relaxes agent count **downward only** — a simple-tier session may plan fewer agents than the wave's `agentCap` where the briefed work does not fill it. It never raises the count above that cap; a moderate or complex tier does not scale it up. The cap itself comes from the resolved session shape (`waves[].agentCap`, see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes) — it is not derived from the tier, and the `agents-per-wave` config value is the ceiling that cap was already built against.
 
-The `agents-per-wave` config value always caps the maximum.
-
-> **Note:** Housekeeping sessions skip complexity scoring and use fixed counts.
+> **Note:** Housekeeping has no tier at all — it is a single coordinator-direct wave (0 dispatched agents) running the fixed maintenance loop, not a scored/scaled wave.
 
 ---
 
@@ -1281,7 +1326,7 @@ Yes. Between each wave, the orchestrator reviews results and can adapt the plan.
 
 ### How many agents run in parallel?
 
-This is controlled by the `agents-per-wave` setting in your Session Config. The default is 6. For deep sessions, you can increase this to 10-18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.
+This is controlled by the `agents-per-wave` setting in your Session Config, using the override form `6 (deep: 18)` to raise the ceiling for deep sessions specifically — see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes for the full per-wave cap table. Note that a plain `deep` session's own raw wave caps top out at 10 (the Impl-Core wave) regardless of the override value configured; an override of 18 only actually binds under the `ultradeep` profile (`/session ultradeep`), whose Research+Code-Discovery wave is the one wave sized at 18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.
 
 ### Do I need Pencil?
 
@@ -1377,6 +1422,28 @@ If agents consistently time out during wave execution:
 - Switch from `deep` to `feature` session type if you do not need the extra agent count
 - Check that your machine has sufficient resources for parallel agent execution
 
+### Import-probe warnings and missing ESLint
+
+The post-edit import probe checks edited `.mjs`, `.js`, and `.cjs` files only when the path is listed in the project's `hooks/_lib/hook-import-set.json` and the hook is enabled. It reports likely hook breakage as a warning and always exits 0. Its two checks have different coverage:
+
+- **C1 — ESLint:** reports `no-undef` and fatal/parse errors. Install ESLint with the project's package manager and enable `no-undef` in the **project's ESLint configuration**; the probe does not enable that rule itself. Other lint rules remain the full lint command's responsibility.
+- **C2 — import:** loads allowlisted files under `scripts/lib/**` in a child process to detect errors during module loading. It does not import hook entrypoints or call exported functions. An undefined identifier reached only when a function runs can therefore escape C2 even when importing the module succeeds.
+
+ESLint lookup tries these paths in order: the project's `node_modules/.bin/eslint`, the project's `node_modules/eslint/bin/eslint.js`, then the same two paths under the plugin root. A consumer installation may have no plugin development dependencies, so the project's ESLint installation matters. `SO_IMPORT_PROBE_ESLINT` overrides this search with an explicit script path; use an absolute path to the ESLint entry script. An empty or nonexistent override disables C1 **without falling back** to either installation.
+
+When no ESLint is available, C1 is normally silent and only eligible C2 checks remain. For an edit that reaches the checks, `SO_IMPORT_PROBE_TRACE=1` writes `probe:eslint-unavailable` to stderr when ESLint cannot be located. This trace diagnoses unavailable ESLint; it does not diagnose every timeout or configuration failure. A timed-out ESLint or an unreadable/non-JSON report is skipped, so silence does not prove that C1 ran successfully.
+
+The shipped event wiring is:
+
+| Harness | Import-probe event |
+|---------|--------------------|
+| Claude Code | `PostToolUse` for edit/write tools |
+| Cursor | `postToolUse` and `afterFileEdit` |
+| Pi | `tool_result` for edit/write tools |
+| Codex | **Unwired:** the current Codex hook manifest has no import-probe handler |
+
+Codex does not currently run this probe automatically, and reinstalling the same bundle does not add that missing handler. Use the project's normal lint and tests for verification there. Implementation: [`hooks/post-edit-import-probe.mjs`](../hooks/post-edit-import-probe.mjs); event manifests: [Claude Code](../hooks/hooks.json), [Cursor](../hooks/hooks-cursor.json), [Pi](../hooks/hooks-pi.json), [Codex](../hooks/hooks-codex.json).
+
 ### Design review skipped unexpectedly
 
 If you configured `pencil` but design reviews are not running:

package/docs/agent-authoring.md

@@ -1,4 +1,4 @@
-<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. -->
+<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. --> <!-- path-check: historical -->
 
 # Sub-Agent Authoring Conventions (`agents/**`)
 
@@ -11,7 +11,7 @@
 > plugin loader registers every `agents/*.md` as a dispatchable agent by
 > directory convention, and the manifest's `agents` key is documented as
 > *additive* ("in addition to those in the `agents/` directory"), so it cannot
-> exclude a path. As `agents/AGENTS.md` this file was therefore a registered
+> exclude a path. As `agents/AGENTS.md` this file was therefore a registered <!-- path-check: historical -->
 > agent — first an unnamed one with **full tool access**, later a contained one
 > whose pseudo-frontmatter capped `tools` at `Read`. Moving it out of the
 > directory removes the registration rather than bounding it. The same applies

package/docs/baseline.md

@@ -19,7 +19,61 @@ A separate git repository (not vendored, not a submodule, not on npm) carrying:
   rules are read **from the baseline**, not from this plugin, so the plugin had to
   learn the baseline's frontmatter convention rather than the other way round.
 
-## How the plugin finds it
+## How bootstrap finds it
+
+Bootstrap resolves only explicit local configuration, in this order:
+
+1. `SO_BASELINE_PATH`
+2. A matching entry in the host-local `owner.yaml` `baselines` list
+3. `owner.yaml` `paths.baseline-path`
+4. `plan-baseline-path` in the repository's Session Config
+
+`scripts/baseline-archetypes.mjs --repo <repo>` reuses the existing configuration
+resolvers. Their diagnostics are contained in a bounded local process so paths
+and private match names cannot leak through the bootstrap CLI. An absent or
+missing directory keeps the public fallback. An existing directory with a
+missing producer, unsupported schema, invalid metadata or unsafe source is an
+explicit error; bootstrap does not silently switch to a public default.
+
+The local producer is the baseline's `archetype-manifest.mjs export` CLI. Its reduced v1
+JSON owns IDs, ordering, declarative detection signals, runtimes, package
+managers, UI/API/deploy metadata, command documentation, quality gates, CI,
+browser automation, and rule targets. No private package inventory or source
+evidence is imported into the plugin. Marker inference uses exported priorities;
+an unknown result is `insufficient-evidence`, requiring a selection from the
+returned catalog for Standard/Deep. `--archetype <id>` validates an explicit ID.
+
+The CLI is read-only, offline and dependency-free without a baseline. Commands
+in its JSON are data and are never evaluated. Only the explicit scaffold action
+in [`private-contract.md`](../skills/bootstrap/private-contract.md) invokes the
+configured baseline's local renderer, into temporary staging. It preserves
+existing destination files and excludes staged rules. Deep retains baseline CI
+and its exemption/requirement instead of generating a public Node pipeline.
+New instruction-file command slots come from exactly matching declared gate
+IDs. Missing test/typecheck/lint gates are reported as unavailable and use
+`false` placeholders, never inferred npm commands. Private verification reports
+declared gates separately from unavailable slots; the generic quality runner
+is unchanged and an unavailable slot must not be reported as a passed check.
+
+S99 recomputes the complete exported rule union after rendering, including
+dependency-conditional targets, and validates the baseline's local `rules`
+projection against it. Sources must stay under `.claude/rules/` or
+`templates/shared/.claude/rules/`, with no symlinks. All basenames owned by
+`rules/_index.md` are excluded, including scoped entries: `rules-sync.mjs` remains
+their sole writer. `syncBootstrapRules` passes the contract's required plugin
+basenames to that writer after validating the local export, so a public scope
+tag cannot silently omit a private requirement. Private S99 adds missing local rules and preserves existing
+ones; the public opt-in fetch retains its existing remote behavior with the
+same plugin-ownership exclusion. No baseline is downloaded or located by
+guessing sibling/private host paths.
+
+New private quality policies use the same exact `test`, `typecheck`, and `lint`
+gate IDs as new Session Config blocks. Missing slots use `false` with an
+unavailable explanation; existing owner policies remain unchanged. Bootstrap
+accumulates actual created relative paths through inherited tiers and stages
+those files individually.
+
+## Legacy vault and maintenance resolution
 
 Never by a hardcoded path. Resolution is host-local, most specific first:
 

package/docs/ci-setup.md

@@ -123,7 +123,7 @@ jobs, so a half-revert or a template refresh flipping one site back to
    check diffs real content rather than passing on a broken comparison.
 
 Per `.claude/rules/security.md` § SEC-005, this token's lifecycle belongs in
-`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present
+`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present <!-- path-check: example -->
 in this repo (measured 2026-09-02: no `.claude/docs/` directory tracked), so
 the inventory is not adopted here and this section remains the sole record.
 

package/docs/codex-setup.md

@@ -88,6 +88,14 @@ Every installer run executes `codex plugin marketplace add` and `codex plugin ad
 
 After either refresh path, confirm the installed version with `codex plugin list --available --json` and start a fresh task. Reopen the skill picker and search for `go` or `close`; if the updated entries are still missing, fully restart Codex. Editing the source clone or regenerating skills alone does not refresh the installed bundle.
 
+### Command entry points missing after an update (GH#68)
+
+**Symptom:** the skill picker shows `session-start` but not `session`, `go`, or `close`.
+
+**Cause:** Codex caches a plugin snapshot at install time; in our 0.153.x probes, running `codex plugin update` alone did not refresh `.codex-plugin/skills/`.
+
+**Fix:** remove the plugin, then re-add it (the refresh steps above); verify with `codex plugin list --json` that the installed version is ≥ 4.0.1 and carries 51 skill entries. 4.0.1+ ships the generated entrypoints (`scripts/generate-codex-skills.mjs`).
+
 The tracked Codex manifest uses a version such as `3.14.0+codex.20260717175716`. The base must match `package.json`; the `+codex.<YYYYMMDDHHmmss>` UTC suffix is the repository's explicit invalidation marker. When a shipped bundle needs a new cache identity, maintainers commit a new timestamp in `.codex-plugin/plugin.json`. The installer validates that committed value and never mutates the tracked manifest.
 
 ## Configuration
@@ -255,6 +263,7 @@ codex plugin list --available --json
 - **The `kanevry` marketplace points at another source:** confirm the conflict with `codex plugin marketplace list --json`, run `codex plugin marketplace remove kanevry`, then rerun the installer from the intended clone so it performs the public marketplace add and plugin add lifecycle.
 - **`go` or `close` is missing from the skill picker:** follow [the refresh steps](#refresh-and-explicit-cache-invalidation), verify the installed version, and restart Codex if reopening the picker does not load the new entries. Use the namespaced skill form from [Usage](#usage), rather than selecting the unrelated native Goal command.
 - **Plugin is installed and enabled but hooks do not fire:** start a fresh task or fully restart Codex, run `/hooks`, and review the trust state. Installation does not imply hook approval.
+- **No import-probe warning after an edit:** the post-edit import probe is currently **unwired in Codex**. Reinstalling the same bundle does not add it. Use normal project lint and tests; see [the probe's harness wiring and ESLint requirements](USER-GUIDE.md#import-probe-warnings-and-missing-eslint).
 - **Other pre-public plugin/config/cache/hook-state residue is suspected:** this state is unsupported. Do not modify private Codex files. File an issue with `codex --version`, `codex plugin list --available --json`, and `codex plugin marketplace list --json` output so the public recovery path can be diagnosed.
 - **Agent dispatch fails:** verify Codex multi-agent support and inspect the bundled or project-level role TOMLs.
 - **Hooks report that Node is unavailable:** expose Node 24+ on the Codex hook PATH or set `SO_NODE_BIN` to the absolute Node executable.

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>43 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>25 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>44 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>26 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>14 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,7 +18,7 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (43 user-facing)
+## Skills (44 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `mcp-builder`, `hook-development`, `frontmatter-guard`
@@ -27,14 +27,14 @@ flowchart LR
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `docs-orchestrator`
 - **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `remote-offload`, `spinout`, `npm-publish`
-- **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
+- **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`, `ux-grill`
 - **Content review:** `persona-panel`
 - **Operator ergonomics:** `eli5` (plain-language restatement of the last answer)
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (25)
+## Commands (26)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/eli5`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/release`, `/eli5`, `/ux-grill`.
 
 ## Agents (14 typed sub-agents)
 
@@ -56,7 +56,7 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 - **Cursor:** `.cursor-plugin/plugin.json` registers canonical skills and `.mcp.json` using Cursor's native manifest format. Additional native component discovery is explicitly disabled; `scripts/cursor-install.mjs` supplies the existing command and hook adapters. The former standard root manifest was moved to prevent [Codex manifest interception](codex-setup.md#manifest-compatibility).
 - **Pi:** `package.json` `pi` manifest, `pi/extensions/session-orchestrator.ts` bridge, `hooks/hooks-pi.json`, `scripts/pi-install.mjs`.
 - **Portable cross-harness surface (generated, never hand-edited):** root `AGENTS.md` (byte-identical copy of `CLAUDE.md`) and `.agents/skills/<name>/SKILL.md` — mirrors carrying only spec-legal frontmatter plus a pointer body. These two surfaces are written by `scripts/generate-agents-skills.mjs` and drift-checked via its `--check` form inside `scripts/validate-plugin.mjs`. Native plugin manifests are maintained separately, with versions updated by `scripts/release.mjs`.
-- **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot) plus shared lib under `scripts/lib/*.mjs`, all covered by the vitest suite.
+- **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot, session-shape) plus shared lib under `scripts/lib/*.mjs` — e.g. `session-shape.mjs` (the one wave-shape resolver for `/session` mode + `--profile`), `maintenance-due-banner.mjs` (the single session-start probe for the whole maintenance loop), `session-end/tail-runner.mjs` (the mechanical apply-half of Phase 3.6.4's Expired-Learnings Sweep), `issue-budget-reconcile.mjs` (close-time recorded-vs-charged cross-check), and `telemetry/pricing.mjs` (per-model USD-per-token rates for cost estimation) — all covered by the vitest suite.
 
 ## `/harness-audit` — Anthropic large-codebase rubric
 
@@ -72,7 +72,7 @@ Surface counts measured 2026-09-06 by this repo's 360° ecosystem probe (`docs/a
 
 | Axis | session-orchestrator | `open-gsd/gsd-core` |
 |---|---|---|
-| Commands / skills / agents | 25 / 43 / 14 | 70 / 71 / 35 |
+| Commands / skills / agents | 26 / 44 / 14 | 70 / 71 / 35 |
 | Hook guards | 27 hook files, 10 event types | 28 hooks, incl. write / read / prompt / workflow / secret-read / agent-isolation / worktree-path guards |
 | Cross-session learning | `/evolve` + confidence-scored `learnings.jsonl`; reconcile turns eligible learnings into PROPOSED rules an operator approves one by one | `gsd-extract-learnings`, `gsd-mempalace-*` |
 | Harness coverage | Claude Code, Codex CLI, Cursor IDE, Pi (4) | 44 `capabilities/` directories (pi, hermes, kimi, windsurf, opencode, ollama, …) |
@@ -88,7 +88,7 @@ Both [`maestro-orchestrate`](https://github.com/josstei/maestro-orchestrate) and
 
 | Axis | session-orchestrator | maestro-orchestrate |
 |---|---|---|
-| Execution model | 5 typed waves (Discovery → Impl-Core → Impl-Polish → Quality → Finalization) with inter-wave quality gates and confidence-scored session-reviewer | 4-phase sequential model with parallel subagents |
+| Execution model | typed waves resolved from the session mode by `scripts/session-shape.mjs` (housekeeping 1 · feature 3 · deep 5 · ultradeep 7) with inter-wave quality gates and confidence-scored session-reviewer | 4-phase sequential model with parallel subagents |
 | Runtime coverage | Claude Code + Codex CLI + Cursor IDE + Pi (4) | Gemini CLI + Claude Code + Codex + Qwen Code (4) |
 | VCS integration | GitLab + GitHub (auto-detected); hook events + commands wire to both | Runtime-agnostic; VCS work delegated to user |
 | Cross-session learning | Confidence-scored entries surfaced at session-start; opt-in `/evolve` review | Session archival without explicit learning extraction |

package/docs/cursor-setup.md

@@ -96,5 +96,6 @@ Switch freely between Claude Code, Codex, and Cursor on the same project — all
 - **`/session` missing**: Confirm `.cursor/commands/session.md` exists. Reload Cursor. If this is another project, re-run `node scripts/cursor-install.mjs .`
 - **Rules not loading**: Ensure `.cursor/rules/` exists with `.mdc` files; `000-session-orchestrator.mdc` has `alwaysApply: true`
 - **Hooks not firing**: Confirm `.cursor/hooks.json` exists. Open Cursor Settings → Hooks. Restart Cursor if it was open during install.
+- **No import-probe warning after an edit**: Cursor wires the probe through `postToolUse` and `afterFileEdit`; it still needs an eligible file and ESLint with the project's `no-undef` rule enabled for C1. See [import-probe coverage and ESLint troubleshooting](USER-GUIDE.md#import-probe-warnings-and-missing-eslint).
 - **`'node' not found` in hook PATH**: See README troubleshooting. `hooks/run-node.sh` resolves Homebrew/nvm Node.
 - **State files not created**: Check `.cursor/` is writable