session-orchestrator 3.21.0 → 3.23.0

package/skills/journey-audit/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: journey-audit
+description: >
+  Use this skill when the user wants the PRODUCT audited from the outside in — what the website
+  promises vs what the code does vs what a real user experiences vs what actually arrives by mail
+  vs what the data says is used. Runs a 7-role read-only wave (R5 writes only under an explicit
+  SAFETY block) against a per-repo `.orchestrator/journey-manifest.md` and writes a dossier to
+  docs/audits/. Distinct from /discovery, which checks code quality inside-out — this checks
+  product truth outside-in; they complement, neither replaces the other. Triggers "journey audit",
+  "Nutzersicht-Audit", "audit the product from the user's side", "/journey-audit".
+model: inherit
+color: purple
+tools: Read, Grep, Glob, Bash, Write, Task
+---
+
+# Journey Audit
+
+> Outside-in product audit as a repeatable deep session. Code review checks code against code;
+> this checks the product against the user's experience. Quarterly, never a CI component.
+
+## Purpose
+
+The most expensive defects of the first run (EventDrop `main-2026-08-28-a6`: a core feature with no
+entry point anywhere in the UI, burned free quota, a plan gate that could be bypassed, a
+claim-vs-code contradiction, EUR copy in a USD context) are **invisible to every code-centric
+check**. They are not bugs in a function; they are gaps between five surfaces — marketing copy,
+code constants, live UI, outbound mail, real usage data — that no single surface can reveal.
+
+This skill dispatches seven roles that each own one surface, then makes the coordinator personally
+re-verify every P0 before it is written down. The re-verification is the value, not the fan-out:
+the first run caught 2 agent errors that way and confirmed 3 real P0s.
+
+## Phase 0: Gates
+
+### 0.1 Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. GATE_CLOSED → invoke
+`skills/bootstrap/SKILL.md` first. GATE_OPEN → continue.
+
+### 0.2 Manifest HARD-GATE
+
+<HARD-GATE>
+Read `.orchestrator/journey-manifest.md` in the target repo (or the path passed as `$ARGUMENTS`).
+
+**A — File missing or empty → REFUSE the whole run.** Say exactly this, then stop:
+
+> `/journey-audit` needs `.orchestrator/journey-manifest.md` in this repo and it is not there.
+> The audit is repo-specific: without personas, entry points, truth-SSOTs, the chat-interview key
+> and the SAFETY block, seven agents would invent their own definition of "correct" and every
+> finding would be unfalsifiable.
+> Copy the template — `templates/_shared/journey-manifest.md` in the session-orchestrator plugin —
+> to `.orchestrator/journey-manifest.md`, fill it in, then re-run `/journey-audit`.
+
+**B — Manifest present, `## SAFETY` heading absent or its body empty → REFUSE R5 ONLY.** R5 is the
+only role that touches production with a real account. Say:
+
+> The manifest has no filled `## SAFETY` block, so R5 (real end-to-end run against production) is
+> NOT dispatched. Running as dry-run: R1–R4 + R7 (R6 additionally needs the read-only DB
+> credentials named in the manifest). Fill in allowed accounts/events, no-go actions, the checkout
+> limit and the cleanup rule to enable R5.
+
+Do NOT infer a SAFETY block from other sections, do NOT ask the operator to dictate one into chat,
+do NOT dispatch R5 "read-only, just this once". A production write without a written, committed
+safety envelope is the one thing this skill never does.
+</HARD-GATE>
+
+Both gates are cheap and mechanical:
+
+```bash
+MANIFEST="${1:-.orchestrator/journey-manifest.md}"
+[ -s "$MANIFEST" ] || { echo "GATE-A: no manifest"; exit 1; }
+awk '/^## SAFETY/{f=1;next} /^## /{f=0} f&&NF{c++} END{exit c>0?0:1}' "$MANIFEST" \
+  || echo "GATE-B: SAFETY block absent or empty → R5 disabled"
+```
+
+### 0.3 Peer-session check (before dispatch, not after)
+
+Run `ListAgents` / read `.orchestrator/` session locks and check for peer sessions in this working
+copy per `.claude/rules/parallel-sessions.md`. A journey audit reads wide and R5 writes to
+production — a peer holding the same files must know before the wave starts, not from the diff.
+Announce the audit and the file scope you will touch; the audit itself claims almost no write
+scope, which is exactly why it is easy to forget.
+
+## Phase 1: Read the manifest
+
+Parse the manifest into `$MANIFEST` and derive per-role inputs. Every role prompt below is filled
+from these fields — an empty field is reported to the operator, never guessed:
+
+`personas` · `entry_points` · `truth_ssots` · `touchpoints` (template dir, send path, cron sources,
+render idiom) · `chat_interview` (question → expected answer → SSOT) · `safety` · `credentials`
+(env-var NAMES) · `realdata_queries` · `platform_expectation` · `known_exceptions`.
+
+## Phase 2: The wave — R1–R7
+
+All roles are **read-only** except R5. All run in parallel in one wave; none depends on another's
+output (the coordinator, not an agent, joins their findings).
+
+| R | Rolle | Generisch | Aus dem Manifest |
+|---|-------|-----------|------------------|
+| R1 | Flow-Zensus | Trigger→Empfänger→Zeitpunkt→Dedupe map of every outbound touchpoint (mail/push/webhook) | Template dir, send path, cron sources |
+| R2 | Artefakt-Rendering | Render templates to HTML, screenshots desktop/mobile/dark, consistency matrix | Render idiom, example props |
+| R3 | Claim-vs-Code-Matrix | Every marketing/FAQ/chat claim against the SSOT constants; feature inventory × surfaces | SSOT files, i18n namespaces, chat fact source |
+| R4 | Anonymer Live-Rundgang | agent-browser desktop+mobile, chat interview against the truth key, dead links, console | Route list, chat questions + expected answers |
+| R5 | Echter E2E-Durchstich | Prod, real account, actually execute each core flow, DB counter-check, mail-log reconciliation | **SAFETY block (mandatory)** |
+| R6 | Realdaten-Funnel | Usage funnel, never-fired flows, delivery defects, name what is not measurable | Read-only DB access, identity rules, mail-provider API |
+| R7 | Plattform-Ausnutzung | Self-built vs platform matrix (hosting/DB/realtime/queues/CDN/WAF), limits at 10× | CLI logins, expected plan, open perf issues |
+
+### Shared prompt preamble (prepend to every role)
+
+> You are role `<R#>` of a journey audit of `<repo>`. Manifest: `.orchestrator/journey-manifest.md`
+> — read it first; it is your only definition of "correct". You are **read-only**: no `Edit`, no
+> `Write` outside your own report, no git write operations (PSA-007), no production writes.
+> Every distributional claim ("all N routes", "no template does X") carries the executed command
+> and its output (PSA-006). A finding you cannot reproduce with a quoted command is a suspicion —
+> label it as one. Findings listed under `Bekannte Ausnahmen` in the manifest are reported as
+> `known-exception`, never as new. Severity: **P0** = money, data loss, or a core flow unreachable ·
+> **P1** = a broken flow or a UX dead end · **P2** = content/platform. Return the FULL report as
+> your last message.
+
+### Role prompt skeletons
+
+Each is self-contained; fill the `<…>` from `$MANIFEST`.
+
+**R1 — Flow-Zensus.** Inputs: template dir `<…>`, send path `<…>`, cron sources `<…>`.
+Task: enumerate every outbound touchpoint and produce one row per flow: trigger (code location) →
+recipient (which persona) → timing → dedupe/idempotency → is it reachable at all. Grep the send
+path for callers; a template with zero callers is a P1 finding, a caller with no dedupe on a
+money-relevant flow is P0. Output: Markdown table + a list of `never-fired` candidates with the
+grep that proves zero callers.
+
+**R2 — Artefakt-Rendering.** Inputs: render idiom `<…>`, example props `<…>`.
+Task: render every template found by R1's directory to HTML, screenshot desktop + mobile + dark,
+and build a consistency matrix (logo, sender, footer, legal block, CTA, language, currency).
+Output: matrix table + the artifact paths under `.orchestrator/journey-audit/<date>/`, plus every
+divergence as a finding. Do not fix a template; report it.
+
+**R3 — Claim-vs-Code-Matrix.** Inputs: SSOT files `<…>`, i18n namespaces `<…>`, chat fact source `<…>`.
+Task: extract every quantitative or capability claim from marketing pages, FAQ, pricing, chat facts
+and mail copy; compare each against the SSOT constant. One row: claim · where it is said · SSOT
+value · verdict (`match` / `drift` / `unbacked`). Then a feature inventory × surfaces grid: a
+feature that exists in code but appears on no surface is a P0 candidate ("no entry point").
+**i18n files are owned by R3 alone** — no other role opens them.
+Output: two tables + findings.
+
+**R4 — Anonymer Live-Rundgang.** Inputs: route list `<…>`, chat questions + expected answers `<…>`.
+Task: `agent-browser`, logged OUT, desktop and mobile viewport. Walk every route: dead links,
+console errors, layout breaks, CTA that goes nowhere. Then run the chat interview verbatim and
+score each answer against the expected answer from the manifest (`match` / `drift` / `refused` /
+`hallucinated`). Output: route table (status, console, findings), interview table, screenshots.
+Read-only: never submit a form that creates data, never sign up.
+
+**R5 — Echter E2E-Durchstich.** Inputs: SAFETY block `<…>`, credentials by env-var NAME `<…>`.
+Task: with the allowed account only, actually execute each core flow end to end in production;
+counter-check in the DB read-only that the expected records exist; reconcile against the mail log.
+**Before every step, re-read the SAFETY block and state which rule permits this step.** Stop at the
+first no-go, do not improvise around a block, honour the checkout limit exactly, and run the
+cleanup rule at the end and prove it ran. Output: per-flow trace (step → observed → expected →
+verdict), the DB counter-check output, the cleanup proof.
+
+**R6 — Realdaten-Funnel.** Inputs: read-only queries `<…>`, identity rules `<…>`, mail-provider API `<…>`.
+Task: run the manifest's `SELECT`s only. Build the funnel per persona, list flows that never fired
+in production, and pull delivery defects from the mail provider (bounces, suppressions, a
+permanently silenced owner address). Then name explicitly what the data CANNOT answer — an unnamed
+blind spot reads as a zero. Output: funnel table, never-fired list, delivery-defect list,
+`not-measurable` list. No writes, no schema changes, no query outside the manifest.
+
+**R7 — Plattform-Ausnutzung.** Inputs: CLI logins `<…>`, expected plan/tier `<…>`, open perf issues `<…>`.
+Task: self-built vs platform matrix across hosting, DB, realtime, queues, CDN, WAF, cron, mail:
+what does the repo hand-roll that the paid platform already provides, and what breaks at 10× today's
+load (quote the actual limit from the provider CLI/API, not from memory). Output: matrix
+(capability · self-built? · platform feature · effort to switch · limit at 10×) + findings.
+
+## Phase 3: Koordinator-Disziplin
+
+Numbered MUSTs. This phase is the skill; the wave is only its input.
+
+1. **Every P0 claim is re-verified by the coordinator, individually, with its OWN grep/curl/DB read,
+   before it enters the dossier.** Not "the agent quoted a command" — you run one yourself, and the
+   dossier carries YOUR command and output. An unreproduced P0 is downgraded to P1 with the note
+   `agent claim, not reproduced`, or dropped. First run: 2 of 5 P0 claims were agent errors
+   ("instantly unreachable" — it was selectable in the UI; "USD on prod" — a session artifact).
+2. **A finding is attributed.** Every dossier row names the role that found it and the command that
+   proves it — the reader must be able to re-run it without asking anyone.
+3. **i18n files are owned by exactly ONE agent (R3).** They were the known contention point in the
+   first run: many roles want to quote them, and a second reader turns into a second writer the
+   moment a fix is suggested. Same rule for any other file two roles both want.
+4. **Peer-session check before the wave starts** (Phase 0.3), not after the diff.
+5. **The coordinator never lets an agent write the dossier.** Agents return reports; the joining,
+   de-duplication and severity decision are the coordinator's, because contradictions between two
+   agents are only visible in one place.
+6. **Contradictions are reported as contradictions.** Two roles disagreeing is a finding about the
+   product, not a merge conflict to smooth over.
+7. **No fixes during the audit.** Findings only. The fix wave is Phase 5 and is a separate decision.
+
+## Phase 4: Dossier
+
+Write `docs/audits/YYYY-MM-DD-user-journey-audit.md` with this fixed section order:
+
+1. `## P0 — Geld & Kern-Flows` (each: symptom · evidence (coordinator's own command + output) ·
+   impact · suggested fix · role)
+2. `## P1 — Flows`
+3. `## P1 — UX`
+4. `## P2 — Inhalt`
+5. `## P2 — Plattform`
+6. `## Realdaten` (funnel, never-fired flows, delivery defects, explicitly not-measurable)
+7. `## Marketing-Hebel` (what the product does well and says nowhere)
+
+Header carries: date, repo, HEAD SHA, roles dispatched (and which were skipped, with the reason —
+"R5 skipped: no SAFETY block" is a result, not a gap), manifest path, artifact directory.
+
+## Phase 5: Closing AskUserQuestion
+
+One `AskUserQuestion` call, per `.claude/rules/ask-via-tool.md` (option 1 `(Recommended)`, every
+description carries reason + cost + consequence, `header` ≤ 12 codepoints):
+
+```
+AskUserQuestion({ questions: [
+  { question: "Which fix packages should the follow-up wave carry?",
+    header: "Fix-Wellen", multiSelect: true,
+    options: [
+      { label: "P0 money+core (Recommended)", description: "The <N> P0s I re-verified myself. Blocks revenue/core flow today; ~<X>h; freezes nothing else." },
+      { label: "P1 flows",  description: "<N> broken/undedupliced flows. ~<X>h; needs the R1 map as input." },
+      { label: "P1 UX",     description: "<N> dead ends. Cheap individually, touches i18n — one owner." },
+      { label: "P2 content+platform", description: "<N> items. No user impact today; do in cooldown." } ] },
+  { question: "Create issues for the selected packages?",
+    header: "Issues", multiSelect: false,
+    options: [
+      { label: "Yes, batch now (Recommended)", description: "One issue per finding via gitlab-ops; labels priority::critical|high|medium + area:* + type:bug/feature. ~<N> issues; respects issue-budget." },
+      { label: "Dossier only", description: "No issues; the dossier stays the record. Choose when the backlog is already over budget." } ] } ] })
+```
+
+Issue creation follows `skills/gitlab-ops/SKILL.md` § Label Taxonomy: `priority::critical` for P0,
+`priority::high` for P1, `priority::medium` for P2, plus the repo's `area:` and `type:` axes. Each
+issue links back to the dossier section that produced it.
+
+## Offload note (R6/R7)
+
+R6 and R7 are pure CLI/API roles — no browser, no repo writes — so they can run headless on a
+second machine (`claude -p "<prompt>"`, see the `m5-offload` skill). Two rules from the first run,
+both learned the hard way:
+
+- **`claude -p` prints only the LAST message.** The prompt MUST end with: *"Return the complete
+  report in your last message — not a summary, not a pointer to a file. Nothing you say before the
+  last message will be read."*
+- **No background processes.** The prompt MUST forbid `&`, `run_in_background`, and any "I'll keep
+  it running" pattern: the process is killed when `-p` returns, and a half-finished role looks
+  identical to a clean one.
+
+## Cadence & Abgrenzung
+
+- **Quarterly, or after a large feature drop.** Deliberately **not a CI component** — it is
+  expensive and judgment-heavy, and a judgment-heavy gate that runs on every pipeline becomes a
+  rubber stamp.
+- **Optional monthly light variant:** R3 + R4 only, as a scheduled cloud session.
+- **vs `/discovery`:** discovery checks code quality inside-out (probes over the tree);
+  journey-audit checks product truth outside-in (five user-facing surfaces against each other).
+  Neither replaces the other; a repo needs both.
+- **Follow-through:** after each run, freeze the mechanizable parts per repo — a `report:*` script,
+  a claim-drift test pinned to the SSOT constant — so the next run is cheaper. The audit's job is
+  to find what no test knows how to look for yet.
+
+## Anti-Patterns
+
+- Dispatching R5 without a SAFETY block "because the operator said it's fine in chat" — the block
+  is a committed artifact for a reason.
+- Copying an agent's P0 into the dossier because its command looked convincing (Phase 3.1).
+- Two roles both editing/owning the i18n files (Phase 3.3).
+- Running the audit as a CI job to "keep it honest" — it turns into a stamp nobody reads.
+- Fixing findings mid-audit, so the later roles measure a moving product.

package/skills/memory-cleanup/SKILL.md

@@ -246,8 +246,8 @@ const peerWarning = wt.activePeer
 
 AskUserQuestion({
   questions: [{
-    question: `Stale auto-promoted worktree found: ${path.basename(wt.wtPath)} (age ${ageDays}d, branch=${wt.branch}).${peerWarning} Remove?`,
-    header: "Stale-Worktree",
+    question: `Auto-promoted worktree ${path.basename(wt.wtPath)} is ${ageDays}d old (branch ${wt.branch}).${peerWarning} Remove?`,
+    header: "Worktree",
     multiSelect: false,
     options: [
       {

package/skills/npm-publish/SKILL.md

@@ -7,7 +7,7 @@ description: Use when publishing this package to npm — a version release (npm
 
 # npm-publish — token auth, and the calls the script cannot make
 
-> **The release itself is `/release` → `scripts/release.mjs`.** That script mechanizes the whole sequence: version surfaces, CHANGELOG gate, drift sweep, tag/registry collision, CI, leakage gate, publish, tag-after-publish, push to both remotes, live-site poll. This skill does not restate it.
+> **The release itself is `/release` → `scripts/release.mjs`.** That script mechanizes the whole sequence: version surfaces, CHANGELOG gate, drift sweep, tag/registry collision, CI, leakage gate, publish, the target-confirmed npm receipt boundary, tag-after-receipt, push to both remotes, GitHub-release handling, and live-site poll. This skill does not restate it.
 >
 > What lives here is the half a script cannot own: the **token setup**, the **auth failure diagnosis**, and the **judgement calls** — which version, what a leak means, when to abort rather than repair.
 
@@ -39,7 +39,7 @@ The script gates mechanics. These three are yours, and it will not make them for
 
 **2. What a leak means when one is found.** A hit from the leakage gate is not a pattern to silence. Decide which of two it is: a real leak (fix `package.json` `files`, re-pack, re-check) or genuine over-matching (fix `LEAKAGE_PATTERNS` in `scripts/release.mjs` **with a test**). There is no third option, and neither is "publish anyway and clean it up in the next version" — an npm publish is not revocable, and unpublishing burns the version number permanently. Operator handling detail: `docs/distribution/npm-publish-checklist.md` § 3.
 
-**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the publish: a red preflight row, a lagging `github` mirror, CI not green on the exact commit, a dead token. These are cheap to fix and re-run from the top. Repair-in-place is only ever appropriate *after* a verified publish, where the version is already immutable: a missing GitHub release or a lagging site deploy can be reconciled, because npm already has the correct artifact. The dividing line is whether the registry has accepted the tarball — before that point, restart; after it, reconcile. `commands/release.md` § Abort criteria is the operative list.
+**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit, a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `commands/release.md` § Abort criteria is the operative list.
 
 ## Failure-mode table
 
@@ -48,13 +48,13 @@ The script gates mechanics. These three are yours, and it will not make them for
 | `E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required` — no OTP prompt | Account has no 2FA enrolled AND token (if any) lacks Bypass-2FA | Create granular token with all four requirements above, or enroll 2FA |
 | Same E403 despite a fresh token | Token created without the Bypass-2FA checkbox, or Read-only, or package-scoped on a first publish | Re-create: RW + All packages + Bypass-2FA |
 | `npm whoami` silent or non-zero | Token expired, or `.env.local` missing | Re-create the token; do not proceed — the preflight fails this row on purpose |
-| `E404` on `npm view` after publish | Registry propagation (rare, seconds) or publish actually failed | Re-check the publish output for `+ <name>@<version>` |
+| `E404` on `npm view` after a target-confirmed publish receipt | Registry propagation (rare, seconds) | Let the script finish its tag/push/GitHub/site tail, then reconcile the registry result; do **not** rerun `--publish` |
 | `ENEEDAUTH` | No login/token at all | Token flow above, or `npm login` |
 | OTP prompt appears but flow is non-interactive (`!`-prefix, script) | No TTY for the prompt | Use the token flow, or a real terminal |
 
 ## Post-publish — the human half
 
-`--publish` verifies the registry and polls the live site itself, and prints the rest. What still needs a person:
+`--publish` attempts registry verification and polls the live site itself. A target-confirmed receipt plus a delayed registry result is a reconciliation outcome, not a failed publish or a retry instruction. What still needs a person:
 
 1. **Rotate/delete the token** at https://www.npmjs.com/settings/<user>/tokens. A token that ever transited a conversation, a screenshot, or any log is burned — rotate immediately.
 2. **pi.dev gallery**: indexing is asynchronous — check https://pi.dev/packages later; do not block on it.

package/skills/peekaboo-driver/SKILL.md

@@ -96,10 +96,10 @@ For each `${PERM_NAME}` in `$MISSING`:
 ```
 AskUserQuestion({
   questions: [{
-    question: `${PERM_NAME} permission is required but not granted. Open System Settings > Privacy & Security > ${PERM_NAME}, enable the terminal entry, then confirm here.`,
-    header: `Missing Permission: ${PERM_NAME}`,
+    question: `${PERM_NAME} is not granted. Enable the terminal entry under System Settings > Privacy & Security, then confirm.`,
+    header: "Zugriff",
     options: [
-      { label: "Granted — continue (Recommended)", description: `I have enabled ${PERM_NAME} in System Settings.` },
+      { label: "Granted — continue (Recommended)", description: "I enabled the terminal entry in that pane — the driver then checks again and carries on if the grant took effect." },
       { label: "Skip this run", description: "Abort peekaboo-driver. Test-runner will record a framework-error finding." }
     ],
     multiSelect: false
@@ -156,11 +156,15 @@ For SwiftUI 26+ targets (projects with `Package.swift` declaring `.iOS("26")` or
 ```bash
 # Gate: glass-modifiers emit is opt-in per the active profile's rubric_features flag (v1 rubric does not consume).
 PROFILES_FILE=".orchestrator/policy/test-profiles.json"
-HAS_GLASS_V2="false"
+HAS_GLASS_V2="false"   # preconditions unmet (no PROFILE / no file / no jq) = feature not requested
 if [ -n "${PROFILE:-}" ] && [ -f "$PROFILES_FILE" ] && command -v jq >/dev/null 2>&1; then
-  HAS_GLASS_V2=$(jq -r --arg p "$PROFILE" '(.[$p].rubric_features // []) | contains(["glass-v2"])' "$PROFILES_FILE" 2>/dev/null || echo false)
+  # Fallback is `unknown`, NOT `false`: false is jq's legitimate "feature off" answer,
+  # so a jq crash on a malformed profiles file would read as a deliberate opt-out.
+  HAS_GLASS_V2=$(jq -r --arg p "$PROFILE" '(.[$p].rubric_features // []) | contains(["glass-v2"])' "$PROFILES_FILE" 2>/dev/null || echo unknown)
 fi
-if [ "$HAS_GLASS_V2" = "true" ]; then
+if [ "$HAS_GLASS_V2" = "unknown" ]; then
+  echo "WARN: glass-v2 probe failed (jq could not read $PROFILES_FILE) — no conformance artifact emitted" >&2
+elif [ "$HAS_GLASS_V2" = "true" ]; then
   cat > "${RUN_DIR}/ax-snapshots/glass-modifiers-$(date +%s%3N).json" <<EOF
 {
   "schema_version": "v1",
@@ -175,6 +179,14 @@ EOF
 fi
 ```
 
+`HAS_GLASS_V2` has **three** states, and the third is the reason the fallback is not `false`:
+
+| Value | Meaning | Driver action |
+|---|---|---|
+| `true` | The active profile lists `glass-v2` in `rubric_features` | Emit the conformance artifact |
+| `false` | The profile does not list it — a real answer from a readable file, or preconditions unmet (no `PROFILE`, no profiles file, no `jq`) | Skip the artifact silently |
+| `unknown` | The probe itself failed — `jq` could not read/parse `$PROFILES_FILE` | WARN on stderr, skip the artifact. **Never** collapsed into `false`: a crashed probe is not an opt-out, and ux-evaluator Check 4 would otherwise report screenshot-only fallback as if the profile had chosen it |
+
 The ux-evaluator Check 4 reads this file. `glassEffect_frames` = compliant (uses `.glassEffect()`). `legacy_material_frames` = non-compliant (uses `.background(.thinMaterial)` etc.). `blur_modifier_frames` = non-compliant (uses `.blur(radius:)` as background). In v1 the arrays are always empty — the evaluator falls back to screenshot-only analysis. Do NOT emit a bare `{}` — use the full schema structure with empty arrays.
 
 ## Composability Contract

package/skills/persona-panel/SKILL.md

@@ -334,7 +334,7 @@ result. If `final_verdict == "warn"`: exit 0 with a warning line on stderr. If
 - **NEVER** dispatch more than 20 personas per panel (security M2 cap).
 - **NEVER** write a sidecar that fails schema validation — validate BEFORE write (security M3).
 - **NEVER** skip `validatePathInsideProject` for the target path OR the sidecar output path (H1).
-- **NEVER** use `run_in_background: true` for persona agents — lose coordination ability.
+- **NEVER** use `run_in_background: true` for persona agents — the panel synthesis needs every reviewer's findings before Phase 4; background dispatch would add turn-juggling with no consumer for early results.
 - **ALWAYS** validate `model:` fields from the catalog against `MODEL_ID_RE` + aliases (H2).
 - **ALWAYS** run `output_contract` structural pre-check before `ajv.compile()` (H3).
 - **ALWAYS** emit the `aggregator_warning` to BOTH stderr and sidecar when using

package/skills/plan/SKILL.md

@@ -281,17 +281,17 @@ If any criterion is FAIL:
 2. Revise the affected PRD sections
 3. Re-submit to the reviewer
 
-Maximum 3 iterations. After 3 iterations with remaining issues, present them to the user via AskUserQuestion:
+Maximum 3 iterations. After 3 iterations with remaining issues, list the flagged points in plain text (they are context, not a choice), then ask via AskUserQuestion:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "The PRD reviewer flagged these remaining issues after 3 revision rounds:\n\n[list issues]\n\nHow do you want to proceed?",
+    question: "The reviewer still flags [N] points after 3 revision rounds. Proceed anyway?",
     header: "PRD Review",
     options: [
-      { label: "Accept as-is (Recommended)", description: "Issues are minor, proceed with current PRD." },
-      { label: "Manual edit", description: "I'll edit the PRD myself before continuing." },
-      { label: "Re-run review", description: "Try one more revision round." }
+      { label: "Accept as-is (Recommended)", description: "Three rounds did not close them, so a fourth probably will not. The flags then stay in the PRD and travel into the issues filed from it." },
+      { label: "Manual edit", description: "You edit the PRD yourself; the flow waits, then re-runs the reviewer on your version." },
+      { label: "Re-run review", description: "One more revision round. Cost: another reviewer pass, and the same points may come back unchanged." }
     ],
     multiSelect: false
   }]
@@ -300,16 +300,16 @@ AskUserQuestion({
 
 ### 5.3 User Review Gate
 
-After the reviewer passes (or user accepts), present the final PRD:
+After the reviewer passes (or user accepts), present the final PRD in plain text — path plus a short section summary — then ask:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "PRD is ready for your review. It has been saved to [path].\n\nPlease review the document and confirm.",
+    question: "Approve the PRD at [path]?",
     header: "PRD Approval",
     options: [
-      { label: "Approve PRD (Recommended)", description: "PRD looks good, proceed to issue creation." },
-      { label: "Request changes", description: "I have feedback — let me describe what to change." }
+      { label: "Approve PRD (Recommended)", description: "Nothing further is checked after this: approval commits the PRD to HEAD (Phase 5.5), then issue creation starts." },
+      { label: "Request changes", description: "Describe what to change; the PRD is rewritten and comes back here. No limit on rounds." }
     ],
     multiSelect: false
   }]
@@ -395,18 +395,20 @@ Assign labels from the standard taxonomy:
 
 ### 6.3 User Review
 
-Present the full issue structure via AskUserQuestion before creating anything:
+Present the full issue structure via AskUserQuestion before creating anything. The table is the text that is about to be filed, so it belongs in `preview` — not in the question:
 
 ```
 AskUserQuestion({
   questions: [{
-    question: "Proposed issue structure:\n\n**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |\n\nTotal: [N] issues. Confirm or adjust.",
-    header: "Issue Review",
+    question: "Create these [N] issues from the PRD?",
+    header: "Issues",
     options: [
-      { label: "Create all issues (Recommended)", description: "Proceed with the proposed structure." },
-      { label: "Adjust priorities", description: "I want to change some priorities before creating." },
-      { label: "Remove issues", description: "Some issues should not be created." },
-      { label: "Cancel", description: "Do not create any issues." }
+      { label: "Create all [N] (Recommended)",
+        description: "Priorities and blocked-by links come straight from the approved PRD. Cost: one API call per issue, ~1s apart.",
+        preview: "**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |" },
+      { label: "Adjust priorities", description: "Same [N] issues, different priority labels. Name them and this question comes back with the table updated." },
+      { label: "Remove issues", description: "Name the ones to drop; the rest are created unchanged." },
+      { label: "Cancel", description: "Nothing is created. The PRD stays committed, so Phase 6 can run again later." }
     ],
     multiSelect: false
   }]

package/skills/plan/mode-feature.md

@@ -127,7 +127,7 @@ Apply per gitlab-ops skill label taxonomy:
 
 ### User Review Gate
 
-Present the full issue structure via AskUserQuestion before creation:
+Present the full issue structure via the AskUserQuestion payload in `SKILL.md` § 6.3 — the issue table belongs in the option's `preview` field, not in the question text:
 
 - Epic title and description
 - Each sub-issue: title, priority, labels, dependency links

package/skills/plan/mode-new.md

@@ -38,7 +38,7 @@ Agent({ subagent_type: "Explore", description: "Check ecosystem for conflicts",
 3. **Target audience** — Options informed by market research agent. User selects or provides custom.
 4. **User-Story-Schicht** — "User-Story-Schicht für dieses Feature erzeugen?" Immer fragen (kein Audience-Heuristik-Gate). Drei Antwortoptionen: **Ja (Als/möchte/damit)** — klassische Persona-Story-Form; **Ja (job-story)** — job-story-Form ("When [situation], I want [motivation], so I can [outcome]"); **Nein** — byte-identisches Status-quo-Verhalten. Bei einer der beiden "Ja"-Optionen emittiert die PRD eine optionale ## User Stories Sektion (je Story ein ↳ AC-Pointer) in der gewählten Form; bei "Nein" wird die Sektion vollständig weggelassen.
 5. **Core problem being solved** — Open-ended. Claude suggests structure if answer is vague.
-6. **GitLab group** — Discover available groups dynamically. Run `ls $BASELINE_PATH/templates/` for project types, and check for a groups config in `$BASELINE_PATH/config/` or run `glab api "groups?per_page=100&min_access_level=10"` to discover GitLab groups — read each entry's `full_path` field. (`glab` has no `group` subcommand at all — invoking one exits 1 with `Unknown command "group"`.) Present findings via AskUserQuestion.
+6. **GitLab group** — Select the GitLab host explicitly, then discover available groups dynamically. Run `ls $BASELINE_PATH/templates/` for project types, and check for a groups config in `$BASELINE_PATH/config/` or run `glab api --hostname "$GITLAB_HOST" "groups?per_page=100&min_access_level=10"` to discover GitLab groups — read each entry's `full_path` field. (`glab` has no `group` subcommand at all — invoking one exits 1 with `Unknown command "group"`.) Present findings via AskUserQuestion.
 
 ### Wave 2 — Technical Details (5 questions, dynamic per archetype)
 
@@ -134,6 +134,12 @@ Map gathered answers to script input choices:
 # namespace in a separate variable — every later step addresses the project as
 # "<group-path>/<project>", and a numeric index there silently targets nothing.
 GROUP_PATH="$(...)"    # e.g., "products" — the full_path of the chosen group
+
+# These values identify the NEW project, not the directory in which this plan runs.
+# Select the host with the group; do not let glab infer it from an ambient remote.
+GITLAB_HOST="<selected GitLab hostname>"
+PROJECT_PATH="$GROUP_PATH/$PROJECT_NAME"
+ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$PROJECT_PATH")"
 (
   echo "$TYPE_CHOICE"    # e.g., "1" for nextjs-saas
   echo "$STYLE_CHOICE"   # e.g., "1" for vega (only if nextjs-saas)
@@ -145,10 +151,12 @@ GROUP_PATH="$(...)"    # e.g., "products" — the full_path of the chosen group
 
 ### Step 2: Verify success
 
-Check exit code. Confirm repo exists:
+Check the setup script exit code. Confirm the selected path exists without fetching a full REST project object:
 
 ```bash
-glab repo view "$GROUP_PATH/$PROJECT_NAME"
+glab api --hostname "$GITLAB_HOST" graphql \
+  -f query='query($fullPath: ID!) { project(fullPath: $fullPath) { fullPath } }' \
+  -f fullPath="$PROJECT_PATH" | jq -er '.data.project.fullPath'
 ```
 
 ### Step 3: Adjust visibility
@@ -157,27 +165,29 @@ If visibility is not `internal` (the default):
 
 ```bash
 # There is no `glab repo edit`, and `glab repo update` carries no --visibility
-# flag (its FLAGS are --archive/--defaultBranch/-d/--description). Go through the
-# API, addressing the project by its URL-encoded path — `projects/:id` resolves
-# from the CWD remote, which is the wrong project right after scaffolding.
-ENCODED="${GROUP_PATH}%2F${PROJECT_NAME}"
-glab api -X PUT "projects/${ENCODED}" -f visibility=private   # or visibility=public
-
-# Verify (this GET is the read-only proof the PUT landed). Note `glab api` has
-# no --jq flag — that is `gh api`'s. Pipe to jq instead.
-glab api "projects/${ENCODED}" | jq -r '.visibility'
+# flag (its FLAGS are --archive/--defaultBranch/-d/--description). The encoded
+# endpoint and explicit host target the new project independently of the CWD.
+glab api --silent --hostname "$GITLAB_HOST" -X PUT \
+  "projects/${ENCODED_PROJECT_PATH}" \
+  -f visibility=private   # or visibility=public
+
+# Fetch only the scalar needed to verify the mutation, never a full REST object.
+glab api --hostname "$GITLAB_HOST" graphql \
+  -f query='query($fullPath: ID!) { project(fullPath: $fullPath) { visibility } }' \
+  -f fullPath="$PROJECT_PATH" | jq -er '.data.project.visibility'
 ```
 
-> The GET path above is verified against glab 1.91.0; the PUT is the documented
-> GitLab API shape but was **not** executed during authoring (write operations
-> were out of scope). Confirm with the GET before relying on it.
+> The GraphQL verification query is read-only and requests only `visibility`; the
+> PUT's unused response is intentionally suppressed. Confirm the selected host and
+> path before running the mutation.
 
 For public/OSS, also configure GitHub mirror if applicable.
 
 ### Step 4: Set branch protection
 
 ```bash
-glab api -X PUT projects/:id/protected_branches \
+glab api --silent --hostname "$GITLAB_HOST" -X POST \
+  "projects/${ENCODED_PROJECT_PATH}/protected_branches" \
   -f name=main \
   -f push_access_level=30 \
   -f merge_access_level=30
@@ -282,7 +292,7 @@ Always use the `priority::<level>` format in VCS CLI commands, not P0/P1/P2/P3.
 
 ### Step 4: Present for user confirmation
 
-Use AskUserQuestion to present the full issue structure:
+Use the AskUserQuestion payload in `SKILL.md` § 6.3 verbatim — the issue table belongs in the option's `preview` field, not in the question text:
 
 - Epic title and description
 - Sub-issues with: title, priority, labels, dependency links
@@ -292,11 +302,11 @@ Use AskUserQuestion to present the full issue structure:
 
 ```bash
 # Create epic
-glab issue create -R "$GROUP_PATH/$PROJECT_NAME" --title "$EPIC_TITLE" --description "$EPIC_DESC" \
+glab issue create -R "https://${GITLAB_HOST}/${PROJECT_PATH}" --title "$EPIC_TITLE" --description "$EPIC_DESC" \
   --label "type:epic,priority::$PRIORITY" --milestone "$MILESTONE"
 
 # Create sub-issues
-glab issue create -R "$GROUP_PATH/$PROJECT_NAME" --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
+glab issue create -R "https://${GITLAB_HOST}/${PROJECT_PATH}" --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
   --label "type:feature,priority::$PRIORITY,status:ready,area:$AREA,appetite:$APPETITE"
 ```
 
@@ -305,10 +315,12 @@ glab issue create -R "$GROUP_PATH/$PROJECT_NAME" --title "$ISSUE_TITLE" --descri
 For issues with technical dependencies, set `blocks`/`is-blocked-by` relationships:
 
 ```bash
-# Issue #2 is blocked by Issue #1
-glab api -X POST projects/:id/issues/:issue2_iid/links \
-  -f target_project_id=:id \
-  -f target_issue_iid=:issue1_iid \
+# Issue #2 is blocked by Issue #1 in this project. An encoded project path is
+# valid for target_project_id, so no numeric project ID is needed.
+glab api --silent --hostname "$GITLAB_HOST" -X POST \
+  "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_2_IID}/links" \
+  -f target_project_id="$ENCODED_PROJECT_PATH" \
+  -f target_issue_iid="$ISSUE_1_IID" \
   -f link_type=is_blocked_by
 ```
 

package/skills/plan/soul.md

@@ -69,6 +69,18 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: name the alternatives you rejected and why, spell out the appetite and the scope cuts, 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: