session-orchestrator 3.21.0 → 3.22.0

package/scripts/run-quality-gate.mjs

@@ -277,8 +277,22 @@ if (!existsSync(gatePath)) {
   die(`Gate script not found: ${gatePath}`);
 }
 
+// `npm_config_loglevel` is INHERITED by every descendant, and the pre-push hook
+// invokes this script as `npm run --silent quality-gate` — which sets it to
+// `silent`. That level then reached the gate's own children: `npm pack
+// --dry-run` emitted ZERO `npm notice` lines instead of 818 (measured
+// 2026-08-22), so the release leakage test saw an empty listing, and several
+// validate-plugin/e2e tests that shell out to npm went red the same way. Every
+// one of them passes under a bare `npm test` and fails only INSIDE the gate,
+// which is the hardest shape to diagnose and cost an hour of chasing phantoms.
+//
+// Pinned rather than deleted: an explicit level makes the gate's children
+// independent of how the gate itself was invoked. `--silent` still does its real
+// job — keeping THIS process's stdout to the single JSON envelope — because the
+// children's output is captured by `runCheck`, never streamed.
 const env = {
   ...process.env,
+  npm_config_loglevel: 'notice',
   TYPECHECK_CMD,
   TEST_CMD,
   LINT_CMD,

package/scripts/validate-plugin.mjs

@@ -259,6 +259,9 @@ if (runCheck('check-owner-leakage.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-rules.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-auq-clarity.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-unicode-safety.mjs') !== 0) checkFailed = 1;
 

package/scripts/validate-wave-scope.mjs

@@ -115,6 +115,11 @@ function die(msg, code = 1) {
  * inherit it: a swallowed flag is silent (the mode never runs, and the caller
  * believes it did), whereas this refusal is loud and one line long.
  *
+ * An EMPTY value is the same failure class and is refused for the same reason.
+ * `--assert-disjoint ""` is what a failed `$(...)` capture of the materializer's
+ * stdout produces; since the mode is gated on a truthy path, the empty string
+ * silently skipped the collision check and still exited 0 (#1083).
+ *
  * @param {string[]} argv
  * @param {number} i - index of the FLAG token
  * @param {string} flag - the flag name, for the error message
@@ -122,7 +127,7 @@ function die(msg, code = 1) {
  */
 function flagValue(argv, i, flag) {
   const value = argv[i + 1];
-  if (value === undefined || value.startsWith('--')) {
+  if (value === undefined || value === '' || value.startsWith('--')) {
     die(`${flag} requires a file-path argument`, 1);
   }
   return value;

package/scripts/vault-backfill.mjs

@@ -25,12 +25,12 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 
 import {
   assertGlabExists, setVerbose as setGlabVerbose,
-  listGroupRepos, checkVaultYaml, fetchRepoOwner,
+  listGroupRepos, checkVaultYaml,
 } from './lib/vault-backfill/glab.mjs';
 
 import {
@@ -155,11 +155,25 @@ function createVaultFolderStub(vaultDir, slug) {
 
 // ── Process one repo ──────────────────────────────────────────────────────────
 
+/** Derive the complete parent namespace from a canonical GitLab project path. */
+function parentNamespace(repoPath) {
+  if (typeof repoPath !== 'string') return 'unknown';
+
+  const segments = repoPath.split('/');
+  if (
+    segments.length < 2 ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..')
+  ) {
+    return 'unknown';
+  }
+
+  return segments.slice(0, -1).join('/');
+}
+
 function processRepo(entry, vaultDir, templateContent) {
   const { path: repoPath, slug, tier, visibility, group, id } = entry;
   const humanName = slugToHumanName(slug);
-
-  const owner = applyWrites ? fetchRepoOwner(id) : 'unknown';
+  const owner = parentNamespace(repoPath);
 
   let renderedContent;
   try {
@@ -184,7 +198,20 @@ function processRepo(entry, vaultDir, templateContent) {
   }
 
   // Apply: write to staging directory at <out-dir>/<group>/<repo>/.vault.yaml
-  const writePath = join(outDir, repoPath, '.vault.yaml');
+  const writePath = resolve(outDir, repoPath, '.vault.yaml');
+  const writePathRelativeToOutDir = relative(outDir, writePath);
+  if (
+    writePathRelativeToOutDir === '..' ||
+    writePathRelativeToOutDir.startsWith(`..${sep}`) ||
+    isAbsolute(writePathRelativeToOutDir)
+  ) {
+    const error = 'refusing to write outside staging directory';
+    emitAction('write-failed', '', { error });
+    process.stderr.write(`[vault-backfill] ERROR: ${error}\n`);
+    hadWriteError = true;
+    return;
+  }
+
   try {
     mkdirSync(dirname(writePath), { recursive: true });
     writeFileSync(writePath, renderedContent, 'utf8');

package/skills/_shared/parallel-aware-auq.md

@@ -22,15 +22,18 @@ Fires when an `exclusive`-class session (`bootstrap`, `housekeeping`, `memory-cl
 ### Claude Code (AskUserQuestion)
 
 ```js
+// Unpacked once so the question reads as one sentence instead of five key=value pairs.
+const { mode, host, pid, worktreePath } = blockingSession;
+
 AskUserQuestion({
   questions: [{
-    question: `An exclusive session is active in this repository (mode=${blockingSession.mode}, started ${ageHours}h ago, host=${blockingSession.host}, pid=${blockingSession.pid}, worktree=${blockingSession.worktreePath}). This blocks all other modes. How should I proceed?`,
-    header: "Parallel-Exclusive",
+    question: `A ${mode} session (process ${pid} on ${host}) started ${ageHours}h ago in ${worktreePath}. What now?`,
+    header: "Repo belegt",
     multiSelect: false,
     options: [
-      { label: "Warten (Recommended)", description: "Wait for the exclusive session to finish. The preamble will not retry automatically — re-run the command after the other session closes." },
-      { label: "Andere Session beenden", description: "I will close the other session myself, then re-run this command. The preamble surfaces but does NOT terminate the other session." },
-      { label: "Abbrechen", description: "Exit cleanly. No STATE.md initialization, no lock acquired." },
+      { label: "Warten (Recommended)", description: "Nothing else can start here until that session closes. This command does not retry — run it again afterwards." },
+      { label: "Andere Session beenden", description: "You close it yourself, then run this command again. Nothing here stops the other session for you." },
+      { label: "Abbrechen", description: "Exit now. Nothing is written: no STATE.md, no lock." },
     ],
   }],
 });
@@ -39,19 +42,17 @@ AskUserQuestion({
 ### Codex CLI / Cursor IDE / Pi fallback (numbered Markdown list)
 
 ```
-Parallel-Exclusive conflict — an exclusive session is active in this repository.
-  Mode: <blockingSession.mode>
-  Started: <ageHours>h ago (host=<host>, pid=<pid>)
-  Worktree: <blockingSession.worktreePath>
-This blocks all other modes.
+A <mode> session (process <pid> on <host>) started <ageHours>h ago in <worktreePath>. What now?
 
-1. Warten (Recommended) — wait for the exclusive session to finish; re-run after it closes.
-2. Andere Session beenden — I will close the other session myself.
-3. Abbrechen — exit cleanly without initializing STATE.md.
+1. Warten (Recommended) — nothing else can start here until that session closes; this command does not retry, so run it again afterwards.
+2. Andere Session beenden — you close it yourself, then run this command again. Nothing here stops the other session for you.
+3. Abbrechen — exit now. Nothing is written: no STATE.md, no lock.
 
 Reply with the number of your choice.
 ```
 
+The four slots are `blockingSession.mode`, `blockingSession.host`, `blockingSession.pid` and `blockingSession.worktreePath`; `<ageHours>` is the age of that session in hours.
+
 ### Outcome handling
 
 - **Warten** → exit Phase-0 cleanly with stderr note `parallel-aware: waiting on exclusive session_id=<id>`. No retry loop.
@@ -65,34 +66,39 @@ Fires when the caller is `parallel-ok`-class AND another `parallel-ok` session i
 ### Claude Code (AskUserQuestion)
 
 ```js
+// Unpacked once so the question reads as one sentence instead of three key=value pairs.
+const { mode, pid } = parallelPeer;
+
 AskUserQuestion({
   questions: [{
-    question: `A compatible parallel session is active in this worktree (mode=${parallelPeer.mode}, started ${ageHours}h ago, pid=${parallelPeer.pid}). You can either: (a) auto-promote to a sibling worktree to run isolated, or (b) run in-place alongside the existing session (file conflicts likely). How should I proceed?`,
-    header: "Worktree-Promo",
+    question: `A ${mode} session (process ${pid}) started ${ageHours}h ago in this same folder. Run separately or alongside?`,
+    header: "Wo starten?",
     multiSelect: false,
     options: [
-      { label: "Worktree anlegen + starten (Recommended)", description: "Create a sibling git worktree at ../<repo-name>-<semantic-session-id>/ and start the new session there. Isolates file edits; recommended for parallel deep/feature sessions. Calls enterWorktree() from scripts/lib/autopilot/worktree-pipeline.mjs." },
-      { label: "Manuell — in-place daneben", description: "Run in the current worktree alongside the existing session. File conflicts possible; PSA-001/002/004 discipline required. A Deviation is logged." },
-      { label: "Abbrechen", description: "Exit cleanly. No STATE.md initialization." },
+      { label: "Worktree anlegen + starten (Recommended)", description: "Creates a second working folder beside this one and starts there — isolates your edits, so nothing collides." },
+      { label: "Manuell — in-place daneben", description: "Both sessions write in this same folder — conflicts are likely and you resolve them yourself. A Deviation is logged." },
+      { label: "Abbrechen", description: "Exit now. Nothing is written: no STATE.md, no lock." },
     ],
   }],
 });
 ```
 
+The second working folder is a git worktree at `<basePath>/<repo-name>-<sessionId>/`; `enterWorktree()` from `scripts/lib/autopilot/worktree-pipeline.mjs` creates it (see Outcome handling below). Running in-place puts PSA-001/PSA-002/PSA-004 discipline on the operator.
+
 ### Codex CLI / Cursor IDE / Pi fallback (numbered Markdown list)
 
 ```
-Worktree-Promotion offer — a compatible parallel session is active in this worktree.
-  Peer mode: <parallelPeer.mode>
-  Started: <ageHours>h ago (pid=<pid>)
+A <mode> session (process <pid>) started <ageHours>h ago in this same folder. Run separately or alongside?
 
-1. Worktree anlegen + starten (Recommended) — create sibling worktree and start isolated session.
-2. Manuell — in-place daneben — run alongside (file conflicts possible, Deviation logged).
-3. Abbrechen — exit cleanly.
+1. Worktree anlegen + starten (Recommended) — creates a second working folder beside this one and starts there; isolates your edits, so nothing collides.
+2. Manuell — in-place daneben — both sessions write in this folder; conflicts are likely and you resolve them. A Deviation is logged.
+3. Abbrechen — exit now. Nothing is written: no STATE.md, no lock.
 
 Reply with the number of your choice.
 ```
 
+The two slots are `parallelPeer.mode` and `parallelPeer.pid`; `<ageHours>` is the age of that session in hours.
+
 ### Outcome handling
 
 - **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. Once the worktree exists, exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.

package/skills/_shared/parallel-aware-preamble.md

@@ -29,6 +29,33 @@ If an `exclusive`-class session is also active, the Exclusive-Conflict AUQ takes
 **Always-OK class** (`discovery`, `evolve`, `plan`, `repo-audit`, `portfolio`):
 The preamble passes through with zero AUQ regardless of other active sessions. Read-only modes never conflict.
 
+## Identity Binding for `findPeers` (#1085)
+
+`mySessionId` / `callerSessionId` is a **hint for the caller's original
+surface**, not a license to turn an attribution label into ownership. A native
+raw id self-excludes on the discovered lock/registry surface directly. Given a
+semantic hint, `findPeers` may translate it to a concrete local raw id only when
+both proofs hold: `current-session.json` has the same semantic label **and** its
+raw `session_id` exactly equals the readable local lock's raw `session_id`.
+
+On a missing, malformed, or mismatched binding, `findPeers` must map nothing and
+leave the discovered lock visible. The STATE.md surface always receives the
+original hint and therefore compares STATE.md `session` as the attribution label
+it is; it is never rewritten to a raw id. This guarded translation is only
+self-exclusion for discovery, not lock/registry ownership and not a continuity
+bridge across a host rotation that changes both values.
+
+**What the binding does not prove.** Both files it reads are repo-global, so the
+check establishes that they are mutually CONSISTENT — not that they describe
+*this* process. Semantic labels are routinely shared between simultaneously live
+sessions, and when a foreign live session wrote both files last under a label
+equal to this hint, its raw id is filtered out and the peer disappears from the
+result. Measured 2026-08-21: with a null hint the foreign peer is returned, with
+the colliding semantic hint `peers` is empty. Treat a quiet `findPeers` result as
+weaker evidence than a git or filesystem signal, and prefer passing the native
+raw id whenever the caller has one. Closing this needs a per-process ownership
+proof; see #1091.
+
 ## Preamble Algorithm
 
 Execute these steps in order. Any classification determines outcome.
@@ -152,8 +179,10 @@ findPeers(repoRoot, { mySessionId }) → peer = peers.find((p) => p.source === '
 ```js
 import { findPeers } from '../../scripts/lib/peer-discovery.mjs';
 
-// Inside Phase 1b, before writing STATE.md:
-const { peers } = await findPeers(repoRoot, { mySessionId: sessionId });
+// Inside Phase 1b, before writing STATE.md. Preserve the original
+// attribution-label hint for the STATE.md surface; findPeers guards any
+// semantic→raw translation for discovered peers internally.
+const { peers } = await findPeers(repoRoot, { mySessionId: callerSessionHint });
 const peer = peers.find((p) => p.source === 'state-md') ?? null;
 // Phase 1.2.1 consumes only the 'state-md' subset (STATE.md surface only).
 if (peer !== null) {

package/skills/_shared/state-ownership.md

@@ -17,7 +17,7 @@ current-wave: <N>
 total-waves: <N>
 # Optional fields (schema-version 1, additive for backward-compat):
 updated: <ISO 8601 UTC>      # last write timestamp, touched by any writer
-session: <session-id>        # <branch>-<YYYY-MM-DD>-<mode>-<n> (semantic, since #573); legacy UUID-v4 also accepted by parseSessionId
+session: <session-label>     # attribution/history label; normally semantic since #573, legacy UUID-v4 remains readable; never a lock/registry ownership key
 session-start-ref: <sha>     # git ref at session start
 ---
 ```
@@ -25,7 +25,7 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
-- `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. The `session` field's value format is `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat).
+- `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
 The `session-type: none` + `status: idle` combination is used only for bootstrap-scaffolded placeholder files (no active session).
 
@@ -79,6 +79,32 @@ A log of unresolved, user-facing questions surfaced by wave agents during a sess
 
 Helpers: `readOpenQuestions` (pure), `appendOpenQuestion` (pure), `markOpenQuestionAnswered` (pure), `appendOpenQuestionOnDisk` (lock-guarded write), `markOpenQuestionAnsweredOnDisk` (lock-guarded write) — all exported from `scripts/lib/state-md.mjs`.
 
+## Session Identity and Lock Ownership (#1085)
+
+This contract distinguishes a physical live-session key from labels that make a
+session intelligible to people and history readers. It does not add an identity
+layer.
+
+- **`session_id` is the only live ownership key.** It is the native raw identity
+  supplied by the active harness, or a generated UUID when no trustworthy raw
+  identity is available. Lock acquisition, registry membership, self-exclusion,
+  proof checks, and lock release use this physical key.
+- **`semantic_session_id` and STATE.md `session` are attribution/history
+  labels, never ownership.** They may describe the same work to a human, but
+  equality of either label cannot acquire, refresh, release, or reclaim a lock.
+  A legacy UUID in STATE.md remains readable only as historical data.
+- **Never bridge a raw mismatch with a label or a proof.** If the current raw
+  id and a live lock's raw id differ, ownership is ambiguous. Leave the live
+  lock visible and let its TTL/Reaper lifecycle resolve it; do not substitute a
+  semantic match, STATE.md `session` match, or owner-proof match.
+- **There is no `logical_session_id`.** A true cross-harness restart-continuity
+  contract requires a trusted native resume identifier and remains a follow-up.
+  In particular, a host rotation that changes both raw and semantic values has
+  no guaranteed continuity.
+
+The peer-discovery and issue-budget procedures below apply these rules at their
+narrow surfaces; neither creates a second ownership model.
+
 ## CCU-009 — Status = Index, Never History (#730/H6)
 
 > Adopted from an external-repo fleet-mining finding (2026-07-02): narrative
@@ -174,8 +200,8 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 
 ```json
 {
-  "session_id":          "<UUID-v4 OR semantic-id>",
-  "semantic_session_id": "<branch>-<YYYY-MM-DD>-<mode>-<n>",
+  "session_id":          "<native-raw-id OR generated-UUID>",
+  "semantic_session_id": "<attribution-label>",
   "started_at":          "<ISO-8601 UTC>",
   "last_heartbeat":      "<ISO-8601 UTC>",
   "mode":                "deep|feature|housekeeping|session|...",
@@ -189,8 +215,8 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 
 | Field | Required since | Description |
 |---|---|---|
-| `session_id` | v1 | The session identifier (UUID-v4 on Claude Code, semantic on Codex/Cursor). |
-| `semantic_session_id` | v2 (Epic #583) | The semantic form (`<branch>-<YYYY-MM-DD>-<mode>-<n>`) **always present**, even when `session_id` is a UUID. Closes D4 gap: semantic-id branch was previously dead code on Claude Code (stdin always provides UUID). |
+| `session_id` | v1 | The physical live lock/registry ownership key: a native raw harness identity, or a generated UUID when no trustworthy raw identity exists. Never use a semantic label here. |
+| `semantic_session_id` | v2 (Epic #583) | An attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>`, surfaced alongside the raw key. It never establishes lock or registry ownership, including when it equals STATE.md `session`. |
 | `started_at` | v1 | ISO-8601 timestamp when the lock was written. |
 | `last_heartbeat` | v2 (Epic #583) | ISO-8601 timestamp updated by the `SessionStart` hook and by `PostToolBatch`/`Stop` hooks. **Basis for liveness determination** — replaces PID-liveness (see below). |
 | `mode` | v1 | Session mode consulted by exclusivity-matrix. May be `"unknown"` in the provisional lock written by the hook before Session Config + AUQ have settled. |

package/skills/bootstrap/SKILL.md

@@ -79,7 +79,6 @@ AskUserQuestion({
     question: "Leeres Repo erkannt. Basierend auf '<HEURISTIC_REASON>' empfehle ich **<RECOMMENDED_TIER>**. Passt das?",
     header: "Bootstrap",
     options: [
-      { label: "<RECOMMENDED_TIER> (Empfohlen)", description: "<one-line description of what this tier scaffolds>" },
       { label: "fast", description: "Nur CLAUDE.md + .gitignore + README. Für Demos, Spikes, Playgrounds." },
       { label: "standard", description: "Fast + package.json/Manifest + TypeScript + Linting + Tests. Für MVPs und echte Produkte." },
       { label: "deep", description: "Standard + CI + CODEOWNERS + CHANGELOG. Für Production, Team, Langlebige Repos." },
@@ -90,6 +89,8 @@ AskUserQuestion({
 })
 ```
 
+Before rendering: append ` (Empfohlen)` to whichever of the three tier labels equals `<RECOMMENDED_TIER>`, and move that option to position 1. The recommended tier is one of the three — listing it a fourth time as its own option made five options, one more than `AskUserQuestion` accepts, and repeated the same choice twice.
+
 If user selects "Abbrechen": stop. Report "Bootstrap abgebrochen. Kein Kommando wird ausgeführt." Do not continue.
 
 Store confirmed tier as `CONFIRMED_TIER`.

package/skills/brainstorm/SKILL.md

@@ -48,12 +48,12 @@ Run a single AUQ to let the user characterize the problem in their own words:
 ```
 AskUserQuestion({
   questions: [{
-    question: "Describe the feature or problem you want to brainstorm. What's the core pain point it addresses, and what's still ambiguous to you?",
-    header: "Feature Frame",
+    question: "What do you want to brainstorm, and what is still unclear about it?",
+    header: "Frame",
     options: [
-      { label: "UX / user-facing surface is unclear", description: "You know what you want to build but not how it should work for the user." },
-      { label: "Scope / boundaries are unclear", description: "You're not sure how much to build, or where one feature ends and another begins." },
-      { label: "Multiple approaches exist — need to pick one", description: "You see 2-3 ways to solve this and aren't sure which is best." },
+      { label: "The user-facing surface", description: "You know what to build but not how it should work for the user." },
+      { label: "Scope / boundaries", description: "You're not sure how much to build, or where one feature ends and another begins." },
+      { label: "Several approaches — pick one", description: "You see 2-3 ways to solve this and aren't sure which is best." },
       { label: "Other / describe below", description: "Free-form: describe the ambiguity in the next prompt." }
     ],
     multiSelect: false
@@ -98,9 +98,9 @@ Example round (adapt to the actual feature):
 AskUserQuestion({
   questions: [{
     question: "Who is the primary user of this feature, and how do they trigger it?",
-    header: "User Surface — Round 2",
+    header: "User surface",
     options: [
-      { label: "Authenticated user via UI action (Recommended)", description: "Pro: fits existing session model. Con: requires UI component work." },
+      { label: "Signed-in user, UI action (Recommended)", description: "Pro: fits existing session model. Con: requires UI component work." },
       { label: "Automated trigger (webhook, cron, event)", description: "Pro: no manual user step. Con: harder to debug and test." },
       { label: "Admin-only operation", description: "Pro: simpler access control. Con: limits who can self-serve." },
       { label: "Other / describe below", description: "Describe the trigger mechanism." }
@@ -128,12 +128,12 @@ Once the dialogue has enough signal, synthesize 2-3 concrete implementation appr
 ```
 AskUserQuestion({
   questions: [{
-    question: "Based on your answers, here are the viable approaches. Which fits best?",
-    header: "Design Approach",
+    question: "Which of these approaches fits best?",
+    header: "Approach",
     options: [
-      { label: "Approach A — [1-sentence summary] (Recommended)", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
-      { label: "Approach B — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
-      { label: "Approach C — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." }
+      { label: "A — [short summary] (Recommended)", description: "Best balance of value, reversibility and scope, because [key pro]. Cost: [key con]. Complexity: low/medium/high." },
+      { label: "B — [short summary]", description: "Trade-offs: [key pro]. Cost: [key con]. Complexity: low/medium/high." },
+      { label: "C — [short summary]", description: "Trade-offs: [key pro]. Cost: [key con]. Complexity: low/medium/high." }
     ],
     multiSelect: false
   }]
@@ -231,13 +231,13 @@ Present the spec path and summary to the user. Then ask via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "The design spec has been written to docs/specs/YYYY-MM-DD-<slug>-design.md. How do you want to proceed?",
-    header: "Design Hand-off",
+    question: "The spec is at docs/specs/YYYY-MM-DD-<slug>-design.md. How do you want to proceed?",
+    header: "Hand-off",
     options: [
-      { label: "Proceed to /plan feature (Recommended)", description: "Formalize this spec into a PRD with acceptance criteria and issue creation." },
-      { label: "Proceed to /write-executable-plan", description: "Skip the formal PRD and go straight to an executable plan (issue #39, once shipped)." },
-      { label: "Revise the spec", description: "I have feedback — describe what to change and I'll update the spec." },
-      { label: "Done for now", description: "Keep the spec as a reference; no immediate next step." }
+      { label: "Proceed to /plan feature (Recommended)", description: "Turns the spec into a PRD with acceptance criteria, then files the issues. Cost: one more question round." },
+      { label: "Proceed to /write-executable-plan", description: "Skips the formal PRD and writes a step-by-step executable plan instead — tracked in #39 (a numbered ticket, not yet released)." },
+      { label: "Revise the spec", description: "Describe what to change; the spec is updated and comes back here." },
+      { label: "Done for now", description: "The spec stays on disk as a reference. Nothing else runs." }
     ],
     multiSelect: false
   }]

package/skills/brainstorm/soul.md

@@ -62,6 +62,18 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: explain WHY each option is on the table, name the paths you already discarded and why, define unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say; the register sets *how*. It is
+defined once, in `skills/session-start/soul.md` § "Register — how a sentence
+reads", and binds here unchanged: the frame ("write for someone who knows this
+project but has not seen what you just saw"), the plain-words test with its
+five worked cases, and its precedence over § "Never traded for brevity" above.
+Read it there. It is not repeated here on purpose — the § Output Levels intro
+sentence already exists in four copies across the four souls with nothing
+checking their parity, and a fifth copied rule would drift the same way. A
+pointer cannot.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/discovery/SKILL.md

@@ -104,13 +104,13 @@ When the gate above is satisfied, present exactly this AskUserQuestion (AUQ-003
 ```
 AskUserQuestion({
   questions: [{
-    question: "Scope `feature` was requested. How should this run handle feature discovery?",
-    header: "Feature Scope",
+    question: "Scope `feature` was requested. How should this run handle it?",
+    header: "Scope",
     options: [
-      { label: "Grounded scan (Recommended)", description: "Run the evidence-anchored feature probes (intent-drift, stubbed-dead-feature) on the probe→verify→triage rails." },
-      { label: "Also judgment topics", description: "Grounded scan PLUS collect judgment-based product questions (opportunity framing, personas). A follow-up prompt after Phase 5 offers inline synthesis or hand-off to /brainstorm or /plan feature — judgment items never enter the verified-findings pipeline." },
-      { label: "Route out", description: "No scan; hand off to /brainstorm (product ideation) or /grill (assumption stress-test) instead." },
-      { label: "Skip", description: "Drop `feature` from this run's scope set." }
+      { label: "Grounded scan (Recommended)", description: "Every finding is tied to a file and line and is verified before it can become an issue. Cost: two extra probes (intent-drift, stubbed-dead-feature)." },
+      { label: "Also judgment topics", description: "Same scan, plus open product questions (opportunity framing, personas) kept as notes. They never become issues; after Phase 5 you pick where they go." },
+      { label: "Route out", description: "No scan at all. You get a pointer to /brainstorm (product ideation) or /grill (assumption stress-test) instead." },
+      { label: "Skip", description: "Drops `feature` (the probes for half-built and drifted features) from this run; the other scopes still run." }
     ],
     multiSelect: false
   }]
@@ -125,12 +125,12 @@ AskUserQuestion({
 ```
 AskUserQuestion({
   questions: [{
-    question: "Judgment topics were collected alongside the grounded scan. How should they be handled?",
-    header: "Judgment Topics",
+    question: "Where should the collected judgment topics go?",
+    header: "Topics",
     options: [
-      { label: "Inline synthesis (Recommended)", description: "Sketch a lightweight OST/persona pass directly in the report's `### Judgment Topics (non-verified)` appendix — explicitly marked non-verified, no separate skill invocation needed." },
-      { label: "Route to /brainstorm", description: "Hand the collected topics off as pre-filled context to /brainstorm for a full Socratic ideation dialogue." },
-      { label: "Route to /plan feature", description: "Hand the collected topics off as pre-filled context to /plan feature for feature-PRD scoping." }
+      { label: "Inline synthesis (Recommended)", description: "Sketches an outcome/persona pass into `### Judgment Topics (non-verified)` (a report section that never becomes issues). Cost: no second run." },
+      { label: "Route to /brainstorm", description: "Hands the topics to /brainstorm as its opening context, for a full question-and-answer design dialogue." },
+      { label: "Route to /plan feature", description: "Hands the topics to /plan feature as its opening context, for feature-PRD scoping." }
     ],
     multiSelect: false
   }]
@@ -370,14 +370,16 @@ For each Critical or High finding, use AskUserQuestion (on Codex CLI where AskUs
 ```
 AskUserQuestion({
   questions: [{
-    question: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>",
-    header: "<severity>",
+    question: "<severity> finding in <file_path> — what should happen with it?",
+    header: "Finding",
     options: [
-      { label: "Create issue (<severity>)", description: "Create a priority::<severity> issue for this finding" },
-      { label: "Adjust priority", description: "Create issue with different priority" },
-      { label: "Dismiss -- intentional", description: "This is by design, skip" },
-      { label: "Dismiss -- false positive", description: "Detection was wrong, skip" }
-    ]
+      { label: "Create issue (<severity>)", description: "Files it as priority::<severity>, so it is tracked outside this session. The code below is copied into the issue body.",
+        preview: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>" },
+      { label: "Adjust priority", description: "Same issue, a priority you pick — this question then comes back with the new label." },
+      { label: "Dismiss -- intentional", description: "The code is deliberate. Nothing is filed, and the finding stays only in this run's report." },
+      { label: "Dismiss -- false positive", description: "The probe misread the code. Nothing is filed; worth reporting if the same probe misfires again." }
+    ],
+    multiSelect: false
   }]
 })
 ```
@@ -391,13 +393,15 @@ Group remaining findings by category. For each category with medium/low findings
 ```
 AskUserQuestion({
   questions: [{
-    question: "[N] medium/low findings in [category]:\n\n1. [title] -- [file_path]:[line] ([severity])\n2. [title] -- [file_path]:[line] ([severity])\n...",
-    header: "[Category]",
+    question: "Create issues for all [N] medium/low findings in [category]?",
+    header: "Findings",
     options: [
-      { label: "Accept all (Recommended)", description: "Create issues for all [N] findings" },
-      { label: "Review individually", description: "Walk through each finding one by one" },
-      { label: "Dismiss all", description: "Skip all medium/low findings in this category" }
-    ]
+      { label: "Accept all (Recommended)", description: "Medium and low findings are cheap to file and cheap to close. Cost: [N] issues, roughly one second apart.",
+        preview: "1. [title] -- [file_path]:[line] ([severity])\n2. [title] -- [file_path]:[line] ([severity])\n..." },
+      { label: "Review individually", description: "One question per finding, same options as the critical ones. Cost: [N] more prompts." },
+      { label: "Dismiss all", description: "Nothing is filed for this category. The findings stay in this run's report only." }
+    ],
+    multiSelect: false
   }]
 })
 ```

package/skills/eli5/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: eli5
+description: Explain a topic like I'm a 5 year old — restate my last output, or a named topic, in plain words without dropping a single fact. Use when the user types /eli5 [topic], or says an answer was too technical, too long, or unclear about what he now has to do.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# eli5
+
+Say it again in plain words. Same facts, in the order he needs them.
+
+## The frame
+
+**Write for someone who knows this project but has not seen what you just saw.**
+
+He owns this repo. He is not missing knowledge, he is missing observation — he did not watch the command run or read the file it points at. Write across, not down. `.claude/rules/ask-via-tool.md` § AUQ-006 and `skills/session-start/soul.md` § Register are the canonical statement of this register; apply them, do not restate them.
+
+## What to restate
+
+- `/eli5` — my last substantial output in this conversation. If there is none yet, say so instead of inventing a topic.
+- `/eli5 <topic>` — that topic (`$ARGUMENTS`), grounded in what THIS session already measured: name the file, command, or record it came from. If it was never measured here, say that rather than filling the gap from memory.
+
+Answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and follow the operator's own language the moment he writes in another one.
+
+## Two limits, and they are the whole skill
+
+**1. Say more simply what actually happens — introduce nothing that does not exist.**
+Test: delete every noun the system does not contain. Sentence still true and complete → it was no analogy. Sentence collapses → describe what actually happens instead.
+✓ "Waiting means the other session finishes first." ✗ "Think of the session as a level crossing."
+
+**2. Simplifying removes words, never facts.** If a path, a number, an error code, an identifier, or an instruction to act disappears, that is data loss, not simplification. The mechanical decider: **could the token you are about to cut ever appear in a `grep`? Then it stays.** `skills/session-start/soul.md` § "Never traded for brevity" outranks every brevity instruction in this file.
+
+## Shape
+
+Line 1 answers the question he actually has: **do I have to do something now, and what happens if I don't?** Then the facts, in the order he needs them — not the order you found them.
+
+This is a terminal, so there is no picture to draw. The second channel is the `preview` field on an `AskUserQuestion` option: when the options differ in something literal — a diff, a title, a config block, a file list — put that text there and he reads the thing instead of a description of it.
+
+## What this is not
+
+- **Not shorter by default.** Eight lines before may be eight lines after. Reorder first; cut only filler.
+- **Not a children's explanation.** The label is a poster, the reader is an expert who was not in the room.
+- **Not a second attempt at the answer.** If the first answer was wrong, fix the answer — `/eli5` restates, it never re-derives.