session-orchestrator 3.22.0 → 3.23.0

package/skills/bootstrap/_shared-template.md

@@ -11,25 +11,34 @@
 
 ---
 
-## #parallel-sessions-rule — Step 3a: Install Parallel-Sessions Rule
+## #parallel-sessions-rule — Step 3a: Install Canonical Rules
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to `$REPO_ROOT/.claude/rules/parallel-sessions.md`.
+Vendor the canonical always-on rules from the plugin's `rules/` library into `$REPO_ROOT/.claude/rules/`. `rules/` is the single source of truth for every distributable rule — never `cp` a rule file from anywhere else (see "Why one writer" below).
 
-Idempotency:
+Idempotency is handled by the writer itself:
 - Missing → create
-- Exists and byte-identical → skip silently
-- Exists and differs → overwrite (vendored is canonical)
+- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
+- Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 
 Shell:
 ```bash
-mkdir -p "$REPO_ROOT/.claude/rules"
-cp "$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md" "$REPO_ROOT/.claude/rules/parallel-sessions.md"
+mkdir -p "$REPO_ROOT/.claude"
+node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
 cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
 ```
 
-Why: PSA-003 destructive-command safeguards require every consumer repo to carry the rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. Surface `errors[]` to the operator; a non-empty `preserved[]` is normal and means a repo-private rule was left alone.
 
-Note: This step runs before the baseline-fetch step (S99/D99). If that step executes and fetches a newer version of `parallel-sessions.md` from the baseline, the baseline version wins (S99 overwrites by design — acceptable).
+Also surface `sanitizer[]` (issue #1098) — `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`). The CLI additionally prints each one to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it to the operator; do not act on it automatically** — the sanitizer never rewrites content and never changes the exit code, because silently stripping a citation would change a rule's meaning at vendoring time. A human decides whether the citation is a leak.
+
+Archetype-scoped entries in `rules/_index.md` resolve from `.orchestrator/bootstrap.lock`, which does not exist yet at this step — they report `archetype-unknown` and are skipped. The always-on rules (including `parallel-sessions.md`) are universal and vendor regardless. Re-run `/bootstrap --sync-rules` after the lock is written to pick up the archetype-scoped ones.
+
+Why: PSA-003 destructive-command safeguards require every consumer repo to carry the parallel-sessions rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+
+Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever — so the plugin can never update it again, and whichever rival copy is smaller silently wins. `rules/` is the only source with a manifest, archetype scoping, a basename-collision guard and a pre-write validator, so it is the only sanctioned writer to `.claude/rules/`.
+
+Note: This step runs before the baseline-fetch step (S99/D99), and S99 must NOT overwrite a rule that `rules/` owns. The baseline's copy carries no provenance header, so letting it win would permanently mark the target as a repo-private override — the exact failure described above. `.claude/rules/parallel-sessions.md` has therefore been removed from the S99 manifest. Any other basename present in BOTH `rules/_index.md` and the S99 manifest has the same defect and needs the same treatment.
 
 ---
 
@@ -133,7 +142,6 @@ if [[ -n "$BASELINE_REF" && -n "${GITLAB_TOKEN:-}" && -n "${GITLAB_HOST:-}" && -
 .claude/rules/swift.md
 .claude/rules/mvp-scope.md
 .claude/rules/cli-design.md
-.claude/rules/parallel-sessions.md
 .claude/rules/ai-agent.md
 .claude/rules/claude-code-usage.md
 MANIFEST

package/skills/bootstrap/deep-template.md

@@ -492,14 +492,18 @@ If the call fails, log the structured message above and continue. Raw API respon
 
 Canonical implementation in [`_shared-template.md#parallel-sessions-rule`](_shared-template.md).
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to
-`$REPO_ROOT/.claude/rules/parallel-sessions.md` (idempotent: missing→create, identical→skip,
-differs→overwrite). The shared partial also runs
+Run `node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"` — it vendors every
+rule registered in `rules/_index.md` (idempotent: missing→create, identical→skip, differs→overwrite),
+and it is the only writer that applies the pre-write validator, the basename-collision guard and the
+copy-on-write branch that preserves repo-private rules. The shared partial also runs
 `cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"` so bare `/loop` gets a
-repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633.
+repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633, #1060.
 
-Note: Runs before D99. If D99 (via inherited S99) fetches a newer `parallel-sessions.md` from
-the baseline, the baseline version wins (acceptable — S99 is canonical).
+Note: Runs before D99. D99 (via inherited S99) no longer fetches `parallel-sessions.md` from the
+baseline — that entry was removed from the S99 manifest in #1060. The baseline copy carries no
+provenance header, so letting it win would make the next `--sync-rules` classify the target as a
+repo-private override and preserve it permanently, i.e. the plugin could never update that rule
+again. `rules/` is the single source for it.
 
 ## Step 3b: Initialize .orchestrator/metrics/ (Deep) (#185)
 

package/skills/bootstrap/fast-template.md

@@ -162,23 +162,30 @@ build/
 
 Note: `.orchestrator/` is NOT gitignored — `bootstrap.lock` must be committed. Only the platform state dirs (`.claude/`, `.codex/`, `.cursor/`) are excluded.
 
-## Step 3a: Install Parallel-Sessions Rule
+## Step 3a: Install Canonical Rules
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to `$REPO_ROOT/.claude/rules/parallel-sessions.md`.
+Vendor the canonical always-on rules from the plugin's `rules/` library into `$REPO_ROOT/.claude/rules/`. `rules/` is the single source of truth for every distributable rule — never `cp` a rule file from anywhere else.
 
-Idempotency:
+Idempotency is handled by the writer itself:
 - Missing → create
-- Exists and byte-identical → skip silently
-- Exists and differs → overwrite (vendored is canonical)
+- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
+- Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 
 Shell:
 ```bash
-mkdir -p "$REPO_ROOT/.claude/rules"
-cp "$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md" "$REPO_ROOT/.claude/rules/parallel-sessions.md"
+mkdir -p "$REPO_ROOT/.claude"
+node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
 cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
 ```
 
-Why: PSA-003 destructive-command safeguards require every consumer repo to carry the rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. At fast tier `.orchestrator/bootstrap.lock` does not exist yet (Step 5 writes it), so archetype-scoped entries report `archetype-unknown` and are skipped — the always-on rules vendor regardless.
+
+Surface `errors[]` and `sanitizer[]` to the operator. `sanitizer[]` (issue #1098) carries `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`); the CLI also prints each to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it, do not act on it automatically** — it never rewrites content and never changes the exit code, so a human decides whether the citation is a leak.
+
+Why: PSA-003 destructive-command safeguards require every consumer repo to carry the parallel-sessions rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+
+Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever, so the plugin can never update it again — and whichever rival copy is smaller silently wins.
 
 ## Step 4: Generate README.md
 

package/skills/bootstrap/standard-template.md

@@ -592,14 +592,18 @@ indent_size = 2
 
 Canonical implementation in [`_shared-template.md#parallel-sessions-rule`](_shared-template.md).
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to
-`$REPO_ROOT/.claude/rules/parallel-sessions.md` (idempotent: missing→create, identical→skip,
-differs→overwrite). The shared partial also runs
+Run `node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"` — it vendors every
+rule registered in `rules/_index.md` (idempotent: missing→create, identical→skip, differs→overwrite),
+and it is the only writer that applies the pre-write validator, the basename-collision guard and the
+copy-on-write branch that preserves repo-private rules. The shared partial also runs
 `cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"` so bare `/loop` gets a
-repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633.
+repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633, #1060.
 
-Note: Runs before S99. If S99 fetches a newer `parallel-sessions.md` from the baseline, the
-baseline version wins (acceptable — S99 is canonical).
+Note: Runs before S99. S99 no longer fetches `parallel-sessions.md` from the baseline — that entry
+was removed from the S99 manifest in #1060. The baseline copy carries no provenance header, so
+letting it win would make the next `--sync-rules` classify the target as a repo-private override and
+preserve it permanently, i.e. the plugin could never update that rule again. `rules/` is the single
+source for it.
 
 ## Step 3b: Initialize .orchestrator/metrics/ (#185)
 

package/skills/claude-md-drift-check/checker.mjs

@@ -910,11 +910,18 @@ function main() {
   //   kebab(s) = s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   //
   // WARN (never error) when:
-  //   - learnings.jsonl is present AND no entry's derived key matches the rule's
-  //     `learning-key` (absent learning), OR
+  //   - NEITHER a learnings.jsonl entry NOR a valid `evidence-digest` frontmatter
+  //     scalar is present (the rule's provenance is unresolvable), OR
   //   - the matching entry's `expires_at` < now (expired learning).
-  // When learnings.jsonl is absent, every key counts as absent — warn on each
-  // generated rule's key.
+  //
+  // #1101 — the digest branch. `.orchestrator/metrics/learnings.jsonl` is
+  // GITIGNORED, so in a fresh clone it does not exist and every generated rule
+  // used to warn (measured 2026-08-26: 23 of 23). A rule carrying a valid
+  // `evidence-digest: sha256-v1:<64 hex>` is SELF-CONTAINED — its `## Evidence`
+  // block plus its own `## Provenance` header fields re-derive the seal with no
+  // jsonl lookup — so its provenance is resolvable offline and it must not warn.
+  // The digest is EVIDENCE, not a second pointer; see
+  // `scripts/lib/reconcile/renderer.mjs` § computeEvidenceDigest.
   // The check is silently skipped (no id pushed) when .claude/rules/ is absent
   // or contains no .md files with auto-generated: true.
   if (!args.skipGeneratedRuleStaleness) {
@@ -926,15 +933,17 @@ function main() {
     // Reads the opening --- ... --- block from a markdown file.
     function extractFrontmatterFields(mdContent) {
       const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(stripLeadingRuleHeaderLines(mdContent));
-      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null };
+      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null, evidenceDigest: null };
       const block = m[1];
       const autoGenM = /^auto-generated:\s*(.+)$/m.exec(block);
       const learningKeyM = /^learning-key:\s*(.+)$/m.exec(block);
       const expiresAtM = /^expires-at:\s*(.+)$/m.exec(block);
+      const evidenceDigestM = /^evidence-digest:\s*(.+)$/m.exec(block);
       return {
         autoGenerated: autoGenM ? autoGenM[1].trim() === 'true' : false,
         learningKey: learningKeyM ? learningKeyM[1].trim() : null,
         expiresAt: expiresAtM ? expiresAtM[1].trim() : null,
+        evidenceDigest: evidenceDigestM ? evidenceDigestM[1].trim() : null,
       };
     }
 
@@ -955,12 +964,20 @@ function main() {
         relPath: relative(vaultDir, absPath),
         learningKey: fields.learningKey,
         expiresAt: fields.expiresAt,
+        evidenceDigest: fields.evidenceDigest,
       });
     }
 
     // No generated rules found → silently skip (don't push the check id).
     if (generatedRules.length === 0) return;
 
+    // #1101 — a LITERAL COPY of `EVIDENCE_DIGEST_RE` from
+    // `scripts/lib/reconcile/renderer.mjs`. Copied, not imported: this checker
+    // is a standalone skill script, and importing across the skill/script
+    // boundary would add real coupling for one 30-character literal. The two
+    // copies are pinned equal by `tests/lib/reconcile/renderer.test.mjs`.
+    const EVIDENCE_DIGEST_RE = /^sha256-v1:[0-9a-f]{64}$/;
+
     // Slugify function mirroring emitter.mjs `kebab()`.
     const kebab = (s) =>
       String(s)
@@ -1001,26 +1018,37 @@ function main() {
     const nowMs = Date.now();
 
     for (const rule of generatedRules) {
-      const { relPath, learningKey, expiresAt } = rule;
+      const { relPath, learningKey, expiresAt, evidenceDigest } = rule;
 
       // If we cannot evaluate the key (no learning-key frontmatter), skip
       // silently — avoid false positives on malformed rules.
       if (!learningKey) continue;
 
-      if (!learningsPresent || !knownKeys.has(learningKey)) {
-        // Learning is absent from learnings.jsonl (or the file is missing entirely).
+      const hasJsonlEntry = learningsPresent && knownKeys.has(learningKey);
+      const hasValidDigest =
+        typeof evidenceDigest === 'string' && EVIDENCE_DIGEST_RE.test(evidenceDigest);
+
+      if (!hasJsonlEntry && !hasValidDigest) {
+        // NEITHER resolution path is available: the learning is absent from
+        // learnings.jsonl (or the file is missing entirely) AND the rule carries
+        // no self-contained evidence digest, so nothing can vouch for it.
         warnings.push({
           check: 'generated-rule-staleness',
           file: relPath,
           line: 1,
-          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl`,
+          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl, and the rule carries no valid evidence-digest to verify it offline`,
           extracted: learningKey,
         });
         continue;
       }
 
-      // Learning exists — check expiry.
-      const storedExpiresAt = knownKeys.get(learningKey);
+      // Provenance resolves — check expiry.
+      // `storedExpiresAt` is only meaningful when the jsonl entry actually
+      // exists. A digest-only rule (fresh clone, or a learning aged out of the
+      // store) is AUTHORITATIVE FOR ITS OWN EXPIRY via frontmatter; reading a
+      // stored value that is not there would make `expiryStr` null and silently
+      // skip the expiry gate for a rule that has a perfectly good `expires-at`.
+      const storedExpiresAt = hasJsonlEntry ? knownKeys.get(learningKey) : null;
       // Prefer the frontmatter expires-at on the rule file; fall back to the
       // stored expires_at from the learning entry (both should agree, but the
       // rule file is authoritative for its own expiry).

package/skills/dispatcher/SKILL.md

@@ -113,7 +113,7 @@ const res = claimRepo({ repoRoot: R, sessionId, mode, ttlHours, semanticSessionI
 Or reuse the primitive directly: `acquire({ sessionId, mode, ttlHours, repoRoot, semanticSessionId })` from `scripts/lib/session-lock.mjs`. The claim is a `linkSync` create-or-fail = **atomic**.
 
 - **`ok: true`** → the claim is held. Proceed to Phase 4.
-- **`ok: false`** (race lost / busy — reasons: `active`, `stale-pid-alive`, `stale-pid-dead`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
+- **`ok: false`** (race lost / busy — reasons: `active`, `stale-heartbeat`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
 
 Do NOT reinvent the claim — always go through `claimRepo`/`acquire`. The `ok:false` path is the load-bearing concurrency guard: two parallel dispatchers can both recommend R, but only one wins the `linkSync`; the loser must re-rank, never force.
 

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/peekaboo-driver/SKILL.md

@@ -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