session-orchestrator 3.20.0 → 3.22.0

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. |
@@ -219,3 +245,20 @@ Net: `pid` (field notes above) stays forensic-only; `last_heartbeat` freshness i
 ### Schema v1 → v2 backward-compat
 
 Readers (e.g., `readLock()` in `session-lock.mjs`, `discoverActiveSessions()`) MUST tolerate absent `last_heartbeat` and `semantic_session_id` fields (v1 locks written before Epic #583). When `last_heartbeat` is absent, fall back to TTL-based expiry from `started_at`. When `semantic_session_id` is absent, treat as unknown.
+
+#### Schema v1 Sunset — evaluated 2026-08-15, tolerance RETAINED (#595)
+
+The 90-day sunset window from Epic #583 (target 2026-08-25) came due and the removal was evaluated against the live fleet. **Verdict: keep the three reader tolerances; the blocker is not v1 data, it is a second production copy of the rule.**
+
+**Precondition — zero v1 artefacts on disk (measured 2026-08-15, this host):**
+
+- `find ~/Projects ~/.claude ~/.config /tmp/claude-501 -name 'session.lock' -not -path '*/node_modules/*'` → **12 files, 12/12 carry a non-empty `last_heartbeat`** (0 v1).
+- `~/.config/session-orchestrator/sessions/active/*.json` → **3 entries, 3/3 carry the `mode` key** (0 v1).
+- The only co-installed older plugin build (`~/.claude/plugins/cache/session-orchestrator/session-orchestrator/3.13.0`) already writes `last_heartbeat` (`session-lock.mjs:195`) and `mode` (`session-registry.mjs:209`) — **no v1 writer remains on this host.**
+
+**Why the branches stay anyway:**
+
+1. **`parseLock()` / `isLockLive()` — the rule is duplicated.** `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` inlines the same `last_heartbeat ?? started_at` fallback, and `tests/lib/lock-ttl-parity.test.mjs` asserts the mirror and the SSOT return identical verdicts *for a v1 lock*. Dropping it in `session-lock.mjs` alone breaks that parity by construction. A measured removal attempt turned **18 tests red across 4 files** (`session-discovery` 9, `session-discovery-fallback` 6, `lock-ttl-parity` 1, `on-session-start` 2) — all outside the lock/registry module pair, all seeding v1-shaped fixtures.
+2. **`_validEntry()` optional `mode` — removal is a net safety LOSS.** Rejecting a mode-less registry entry drops a **live peer** from `readRegistry()`, making it invisible to the exclusivity matrix. An absent `mode` already degrades to the `parallel-ok` bucket, so strictening buys no detection and costs peer visibility — the wrong direction under `.claude/rules/development.md` § Guard & Threshold Design.
+
+**What a real sunset needs (co-change set, one atomic MR):** `scripts/lib/session-lock.mjs` + `scripts/lib/harness-audit/categories/category4.mjs` (the mirror) + fixture updates in `tests/lib/session-discovery.test.mjs`, `tests/lib/session-discovery-fallback.test.mjs`, `tests/lib/lock-ttl-parity.test.mjs`, `tests/hooks/on-session-start.test.mjs`. Deleting the *mirror* in favour of importing the SSOT is the durable fix — the duplication, not the v1 data, is what keeps this class alive. The registry item should be closed as won't-do per point 2.

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/claude-md-drift-check/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: claude-md-drift-check
-description: Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys = error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
+description: >
+  Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and
+  live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference
+  freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys =
+  error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness
+  (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match
+  globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference
+  config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an
+  opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
 model: haiku
 ---
 

package/skills/debug/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: debug
-description: Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
+description: >
+  Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase
+  systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE
+  INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
 model: inherit
 color: red
 tools: Read, Grep, Glob, Bash, Write

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/discovery/issue-templates.md

@@ -79,7 +79,7 @@ Used for a single finding from a single probe.
 **CLI Example:**
 ```bash
 # GitHub
-gh issue create \
+gh issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <finding_title>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
@@ -88,7 +88,7 @@ EOF
 )"
 
 # GitLab
-glab issue create \
+glab issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <finding_title>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'
@@ -159,7 +159,7 @@ Used when multiple related findings from the same probe or category are grouped
 **CLI Example:**
 ```bash
 # GitHub
-gh issue create \
+gh issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <category> audit: <summary>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
@@ -168,7 +168,7 @@ EOF
 )"
 
 # GitLab
-glab issue create \
+glab issue create -R <OWNER>/<REPO> \
   --title "[Discovery] <category> audit: <summary>" \
   --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'

package/skills/discovery/probes-code.md

@@ -58,9 +58,9 @@ Grep pattern: (TODO|FIXME|HACK|XXX|TEMP|WORKAROUND)[\s:()\-]
 For each match, check whether a corresponding VCS issue exists:
 ```bash
 # Search for issue referencing the annotation text
-gh issue list --search "<annotation text>" --limit 5
+gh issue list -R <OWNER>/<REPO> --search "<annotation text>" --limit 5
 # or
-glab issue list --search "<annotation text>" --per-page 5
+glab issue list -R <OWNER>/<REPO> --search "<annotation text>" --per-page 5
 ```
 
 Flag annotations with no corresponding issue.

package/skills/discovery/probes-feature.md

@@ -113,11 +113,11 @@ Export Status: exported/public | internal
 1. List open feature/enhancement issues via the VCS CLI (syntax reference: `skills/gitlab-ops/SKILL.md` § "Common CLI Commands" — do not duplicate CLI flags here beyond what's needed to name the call):
 ```bash
 # GitLab
-glab issue list --label "feature" --per-page 100
-glab issue list --label "enhancement" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "feature" --per-page 100
+glab issue list -R <OWNER>/<REPO> --label "enhancement" --per-page 100
 # GitHub
-gh issue list --label "feature" --limit 100
-gh issue list --label "enhancement" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "feature" --limit 100
+gh issue list -R <OWNER>/<REPO> --label "enhancement" --limit 100
 ```
 
 2. Extract theme keywords from each issue's title (and first paragraph of body where available): lowercase, strip stop-words, tokenize on non-alphanumeric boundaries. Group issues that share two or more significant keywords (e.g. "export", "csv", "invoice") into a candidate cluster.
@@ -125,10 +125,10 @@ gh issue list --label "enhancement" --limit 100
 3. For each candidate cluster with 3 or more issues, check whether ANY member issue is already linked to an epic (`epic` label, a GitLab Epic relationship, or an in-body reference such as `part of #<epic-iid>` / `Epic: #<epic-iid>`):
 ```bash
 # GitLab -- inspect labels + description for epic linkage
-glab issue view <IID>
+glab issue view -R <OWNER>/<REPO> <IID>
   Grep pattern: (^Labels:.*\bepic\b|part of #|Epic:\s*#)
 # GitHub -- same check against issue body/labels
-gh issue view <NUMBER>
+gh issue view -R <OWNER>/<REPO> <NUMBER>
   Grep pattern: (^labels:.*\bepic\b|part of #|Epic:\s*#)
 ```
 

package/skills/discovery/probes-infra.md

@@ -10,10 +10,10 @@
 
 ```bash
 # GitLab: query recent pipeline status
-glab pipeline list --per-page 10
+glab pipeline list -R <OWNER>/<REPO> --per-page 10
 
 # GitHub: query recent workflow runs
-gh run list --limit 10
+gh run list -R <OWNER>/<REPO> --limit 10
 
 # Parse output for:
 # - Repeated failures (same pipeline failing 3+ times in a row)

package/skills/discovery/probes-session.md

@@ -55,9 +55,9 @@ Grep pattern: <claimed_addition>
 git show <commit_hash> -- <relevant_files>
 
 # "Closes #N" -> verify acceptance criteria from issue #N are met
-gh issue view <N> --json body -q '.body'
+gh issue view -R <OWNER>/<REPO> <N> --json body -q '.body'
 # or
-glab issue view <N>
+glab issue view -R <OWNER>/<REPO> <N>
 
 # Step 3: Cross-reference claims against actual changes
 git diff <commit_hash>~1..<commit_hash>
@@ -83,10 +83,10 @@ Evidence: <what was found or not found>
 
 ```bash
 # GitLab: list open issues sorted by last update
-glab issue list --per-page 100 | head -50
+glab issue list -R <OWNER>/<REPO> --per-page 100 | head -50
 
 # GitHub: list open issues sorted by last update
-gh issue list --limit 100 --json number,title,labels,updatedAt,assignees --jq '.[] | select(.updatedAt < "<30_days_ago_iso>")'
+gh issue list -R <OWNER>/<REPO> --limit 100 --json number,title,labels,updatedAt,assignees --jq '.[] | select(.updatedAt < "<30_days_ago_iso>")'
 
 # Flag:
 # - Issues with no activity in stale-issue-days (default: 30 days)
@@ -131,7 +131,7 @@ for issue in issues:
 "
 
 # GitHub: fetch issue bodies and parse cross-references
-gh issue list --limit 100 --json number,body --jq '.[] | {number, body}' | python3 -c "
+gh issue list -R <OWNER>/<REPO> --limit 100 --json number,body --jq '.[] | {number, body}' | python3 -c "
 import json, sys, re
 for line in sys.stdin:
     issue = json.loads(line)