session-orchestrator 5.3.0 → 5.5.0

package/skills/wave-executor/references/wave-loop-review.md

@@ -373,8 +373,6 @@ If the commit itself fails (e.g., nothing to commit, pre-commit hook rejects), d
    - `agent_count_completed`: distinct agents whose task-notification (`<status>completed</status>`) arrived (#1115). A gap `agent_count_started > agent_count_completed` at wave end is an agent that started and never returned — the started-but-never-returned state, not a silent drop.
    - Per-agent results: `{description, status: done|partial|failed, files_changed_count}`
    - `files_changed`: total unique files changed this wave (from `git diff --stat --name-only`)
-   - `planned_files_count`: size of this wave's Planned set (union of agent file scopes) as computed in step 3c File-level grounding above. Reuse that value — do not recompute.
-   - `over_delivery_ratio`: files_changed / max(planned_files_count, 1), rounded to 2 decimals. > 1 = agents touched more files than briefed (under-sizing signal, #730/H4). Omit both fields when `grounding-check: false`.
    - `quality_check`: incremental check result (pass/fail/skipped)
    - `suite_passed` / `suite_failed` (+ optional `suite_platform`): the full-suite counts feeding the § 3a Wave History header `— suite <passed>/<failed> on <platform>`. `quality_check` is a traffic light; these are the number the light was derived from, and unlike STATE.md (gitignored, demoted to `## Previous Session` and then overwritten) the metrics record survives the session.
      **Copy the two counts off the gate's own event — do not re-read them from the terminal (#966 step 3).** `scripts/run-quality-gate.mjs`, the wrapper that fires between waves, emits `orchestrator.quality_gate.{passed,failed}` carrying a machine-measured `counts: {passed, failed, total}` (admitted by `admitSuiteCounts()`) plus the `wave_number` it resolved from `wave-scope.json`. Payload fields are flat at the record's top level:
@@ -391,7 +389,7 @@ If the commit itself fails (e.g., nothing to commit, pre-commit hook rejects), d
      > **What is NOT on the event, and stays hand-written:** `suite_platform` — the payload has no platform field, so keep writing it from the § 3a header as before. Likewise, the auto-fix-loop producer (`scripts/lib/quality-gate.mjs`, active only under `verification-auto-fix.enabled: true`) emits `counts` WITHOUT `wave_number`, so its retry records correctly never match the selector above; they are mid-wave attempts, not the wave's verdict. If the wave's gate ran outside `run-quality-gate.mjs` entirely, no event exists — fall back to the gate output you read, and say so in the progress update. The reader side (`skills/session-end/metrics-collection.md` § 1.7) reads the event first and this hand-written trio second, so keep writing the trio: it is the compatibility path for those two cases and for sessions already in flight.
    Append this wave record to the session metrics `waves` array.
 
-7a. **Scope drift tripwire (S2 — #896, warn-only)**: distinct from `over_delivery_ratio` above — that metric is per-wave and unfiltered; this one is session-cumulative (since `session-start-ref`) and filtered through `DRIFT_EXCLUDE_PATTERNS`, so the two numbers are NOT expected to agree. Call `computeDrift()` from the same `scripts/lib/scope-baseline.mjs` module as `wave-loop-dispatch.md` § 0a Scope Baseline Freeze. Never blocks — exit code stays 0 and the next wave is dispatched regardless of the result.
+7a. **Scope drift tripwire (S2 — #896, warn-only)**: session-cumulative and filtered through `DRIFT_EXCLUDE_PATTERNS`, so its `filesRatio` is NOT expected to agree with this wave's unfiltered `files_changed` from step 7. Only the committed part of its numerator starts at `session-start-ref`; the uncommitted and untracked parts read the checkout as it is now, so files already dirty at session start and a same-checkout peer's files count too (an over-report, named as a ceiling in `computeDrift()`'s JSDoc). Call `computeDrift()` from the same `scripts/lib/scope-baseline.mjs` module as `wave-loop-dispatch.md` § 0a Scope Baseline Freeze. Never blocks — exit code stays 0 and the next wave is dispatched regardless of the result.
 
    ```js
    import { computeDrift } from '$PLUGIN_ROOT/scripts/lib/scope-baseline.mjs';
@@ -405,7 +403,7 @@ If the commit itself fails (e.g., nothing to commit, pre-commit hook rejects), d
    }
    ```
 
-   Include the WARN line verbatim in the wave progress update when `breached` is true — name `filesRatio`, `plannedFiles`, `actualFiles`, and the configured `threshold`, not merely the word "drift". `drift.skipped === true` (`no-state-md`, `unreadable-state-md`, `no-baseline`, `stale-baseline`, or `unresolvable-ref` — see `computeDrift()`'s JSDoc for the precedence order) is silent: no WARN, no progress-update line. `persistence: false` implies `no-state-md`, so this step degrades to a silent no-op in that mode without a separate gate check.
+   Include the WARN line verbatim in the wave progress update when `breached` is true — name `filesRatio`, `plannedFiles`, `actualFiles`, and the configured `threshold`, not merely the word "drift". `drift.skipped === true` (`no-state-md`, `unreadable-state-md`, `no-baseline`, `stale-baseline`, `no-baseline-ref`, or `unresolvable-ref` — see `computeDrift()`'s JSDoc for the precedence order) is silent: no WARN, no progress-update line. `persistence: false` implies `no-state-md`, so this step degrades to a silent no-op in that mode without a separate gate check.
 
 ### 3. Adapt Plan (if needed)
 
@@ -446,13 +444,13 @@ After each wave completes and before the progress update, update `<state-dir>/ST
 
 1. **Frontmatter**: set `current-wave` to the just-completed wave number; set `status` to `active` (or `paused` if waiting on user input). Readers that need the RUNNING wave (e.g. `scripts/memory-propose.mjs`) read `<state-dir>/wave-scope.json` `wave` (only when the manifest is bound to this session via `semantic_session_id`; an unbound manifest is ignored — it may be a peer's, #1123) and fall back to `current-wave + 1` (#1166) — do not change this field's meaning.
 2. **`## Current Wave`**: replace contents with next wave info — wave number, role, agents to dispatch and count
-3. **`## Wave History`**: append an entry for the completed wave (the `(planned … → actual …, over-delivery …)` parenthetical is omitted when `grounding-check: false`, since the counts are unavailable):
+3. **`## Wave History`**: append an entry for the completed wave:
    > **Record the SUITE COUNT, not just "gates green" — and name the platform (#944).** The wave line MUST carry the full-suite pass/fail count from the gate that just ran (`<passed>/<failed>`), not merely that typecheck and lint were clean. A deep session on 2026-07-30 logged typecheck/lint/validate-plugin for every wave and no suite count; a test that had been vacuous for its entire life sat red on HEAD through three waves and was found only by the review panel — in a session whose own premise was turning CI from red to green.
    >
    > **A green gate on one platform is not evidence for another.** That same session's local gate reported 541/541 three times on a tree CI could not build: two tests encoded macOS assumptions (a `TMPDIR` that carries a trailing slash; an `ARG_MAX` that tolerates a 200 KB argv entry). Both passed locally and failed on the Linux runner. When the wave touched anything platform-sensitive — spawn/argv shapes, `os.tmpdir()`, path separators, file modes, `$PATH` lookups of external binaries — say so in the wave line, and treat CI, not the local run, as the verdict.
 
    ```
-   ### Wave N — <Role> (planned <P> files → actual <A>, over-delivery <R>) — suite <passed>/<failed> on <platform>
+   ### Wave N — <Role> — suite <passed>/<failed> on <platform>
    - Agent "<description>": <done|partial|failed> — <files changed> — <1-line note>
    - Agent "<description>": <done|partial|failed> — <files changed> — <1-line note>
    ```

package/skills/wave-executor/references/wave-loop-scope-manifest.md

@@ -16,12 +16,12 @@ Before each wave dispatch:
    **Deriving `blockedCommands` (effective floor∪overlay policy, #155/#972):** Before writing `wave-scope.json`, derive the blocked patterns from the EFFECTIVE policy via the shared merge module — the plugin's floor policy united with the repo's overlay policy. (A bare `jq` over the repo-local policy file alone under-counts the merged result since #972.)
    ```bash
    BLOCKED=$(node --input-type=module -e "
-   import { loadEffectivePolicy } from '$PLUGIN_ROOT/scripts/lib/blocked-commands-policy.mjs';
+   import { loadEffectivePolicy, blockedCommandPatterns } from '$PLUGIN_ROOT/scripts/lib/blocked-commands-policy.mjs';
    const { rules } = await loadEffectivePolicy({ cwd: process.cwd(), projectDir: process.env.CLAUDE_PROJECT_DIR ?? null, pluginRoot: '$PLUGIN_ROOT' });
-   console.log(JSON.stringify((rules ?? []).filter(r => r.severity === 'block').map(r => r.pattern)));
+   console.log(JSON.stringify(blockedCommandPatterns(rules)));
    ")
    ```
-   Use `$BLOCKED` as the `blockedCommands` value in `wave-scope.json`. Since #972 this is the effective floor∪overlay policy — identical to what the destructive-guard hook enforces.
+   Use `$BLOCKED` as the `blockedCommands` value in `wave-scope.json`. Since #972 the rules come from the effective floor∪overlay policy the destructive-guard hook enforces. `blockedCommandPatterns()` keeps only the UNTYPED `block` rules (#1509): a typed rule (`redirect-truncate`, `path-delete`) carries a target-decided `pattern` (`">"`, a free-text label) that `hooks/enforce-commands.mjs` would misread as a command pattern. The destructive guard still enforces the typed rules on every Bash call — do not re-inline the filter here.
 
    **Fallback:** If the command fails or prints `[]` (neither the plugin's floor policy nor a repo policy resolvable — pre-#155 setup), use the legacy hardcoded array and log a warning in the wave progress update:
    ```bash
@@ -49,7 +49,7 @@ Before each wave dispatch:
      "session_id": "<raw session id from attributionForRecord(); OMIT the key if unavailable>",
      "semantic_session_id": "<semantic_session_id from the same call; OMIT if unavailable>",
      "allowedPaths": ["<from agent specs in session plan>"],
-     "blockedCommands": "<derived dynamically from the effective floor∪overlay policy via loadEffectivePolicy (severity: block rules, #972); falls back to legacy 5-element array if no policy resolves>",
+     "blockedCommands": "<derived dynamically from the effective floor∪overlay policy via loadEffectivePolicy + blockedCommandPatterns (untyped severity: block rules, #972/#1509); falls back to legacy 5-element array if no policy resolves>",
      "gates": "<copy of enforcement-gates from Session Config, or omit if unset>"
    }
    ```
@@ -163,4 +163,12 @@ Before each wave dispatch:
    5. Delete `<state-dir>/wave-scope.json`
    6. Write Phase 2 wave-scope.json with test file allowedPaths (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
    7. Dispatch test/review agents
-7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.
+7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified. Delete THIS session's dispatch ledger in the same step too — `hooks/pre-task-scope-disjoint.mjs` keeps one file per session since #1493, `.orchestrator/wave-dispatch-scopes.<session-id>.json` plus its `.lock`, under the session root (the repo root, or the worktree the session entered). Only your own: a file beside it named after another id holds a peer session's live claims. Delete only an id that is already path-safe (the hook names the file after it unchanged); anything else is left behind, inert, because no other session reads it:
+
+   ```bash
+   SID="${CLAUDE_CODE_SESSION_ID:-}"
+   case "$SID" in
+     ''|*[!A-Za-z0-9._-]*) ;;  # no id on this harness, or not path-safe: leave the file
+     *) rm -f ".orchestrator/wave-dispatch-scopes.$SID.json" ".orchestrator/wave-dispatch-scopes.$SID.lock" ;;
+   esac
+   ```

package/templates/personas/README.md

@@ -39,7 +39,7 @@ Subject-matter experts (SMEs) reviewing outputs for technical correctness — ac
 
 **Exemplars:** `accounting-tax-advisor.v1.md`, `klima-ai-expert.v1.md`, `klima-physicist.v1.md`
 
-**Recommended model:** `claude-opus-4-7` — Opus surfaces nuances Sonnet misses (vault learning `[[persona-opus-finds-real-failing-cibadge]]`).
+**Recommended model:** the Opus tier via alias `opus` — Opus surfaces nuances Sonnet misses (vault learning `[[persona-opus-finds-real-failing-cibadge]]`); the alias tracks the current Opus; pin a full model ID only for a named reproducibility need.
 
 #### `buyer-persona`
 
@@ -47,7 +47,7 @@ Synthetic archetype of a target customer reviewing for market fit, pain-point re
 
 **Exemplars:** `buyer-p1-cto.v1.md` through `buyer-p6-ld.v1.md` (6-persona set covering CTO, Kanzlei, Build-buyer, Tech-veto, Solopreneur, L&D).
 
-**Recommended model:** `claude-opus-4-7` for high-stakes go/no-go reviews; Sonnet acceptable for lower-stakes copy tests.
+**Recommended model:** alias `opus` (tracks the current Opus) for high-stakes go/no-go reviews; Sonnet acceptable for lower-stakes copy tests.
 
 #### `compliance`
 
@@ -55,7 +55,7 @@ Compliance officers auditing outputs against regulation (GDPR/DSGVO, tax law, se
 
 **Exemplar:** `accounting-compliance.v1.md` (DSGVO Art. 5/17/20 audit trail).
 
-**Recommended model:** `claude-opus-4-7` — false negatives in compliance reviews are expensive.
+**Recommended model:** alias `opus` (tracks the current Opus) — false negatives in compliance reviews are expensive.
 
 #### `auditor`
 
@@ -63,7 +63,7 @@ Independent auditor checking that outputs match a stated standard, framework, or
 
 **No exemplar yet — first author should propose a starter template.**
 
-**Recommended model:** `claude-opus-4-7` for high-stakes audits; Sonnet for routine standard-conformance checks.
+**Recommended model:** alias `opus` (tracks the current Opus) for high-stakes audits; Sonnet for routine standard-conformance checks.
 
 #### `reviewer`
 
@@ -119,7 +119,7 @@ name: tax-law-reviewer
 schema_version: 1
 version: "1"
 role: "Austrian tax accountant reviewing accounting AI outputs for UStG/BAO law compliance"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "UStG compliance: VAT rate and reverse-charge correctly applied to outputs"

package/templates/personas/accounting-compliance.v1.md

@@ -3,7 +3,7 @@ name: accounting-compliance
 schema_version: 1
 version: "1"
 role: "DSGVO/GDPR Compliance Officer — audits AI-accountant outputs for privacy and audit-trail conformance"
-model: claude-opus-4-7
+model: opus
 tier: compliance
 evaluation_criteria:
   - "Keine PII im Output: kein Klarname, E-Mail, IBAN ausserhalb des eigenen Mandanten-Kontexts"

package/templates/personas/accounting-tax-advisor.v1.md

@@ -3,7 +3,7 @@ name: accounting-tax-advisor
 schema_version: 1
 version: "1"
 role: "Austrian Steuerberater (StBKO §47) — reviews AI-accountant outputs for AT tax-law compliance"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "UStG-Konformität: correct VAT rate applied; exemptions follow §6 UStG; Reverse-Charge correctly identified"

package/templates/personas/buyer-p1-cto.v1.md

@@ -3,7 +3,7 @@ name: buyer-p1-cto
 schema_version: 1
 version: "1"
 role: "CTO, Mittelstand-Maschinenbau (~180 FTE) — bewertet B2B-AI-Produkt aus technischer Einkäuferperspektive"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "Tech-Stack-Fit: kompatibel mit Microsoft 365, on-prem AD, kein erzwungener Cloud-Lock-in"

package/templates/personas/buyer-p2-kanzlei.v1.md

@@ -3,7 +3,7 @@ name: buyer-p2-kanzlei
 schema_version: 1
 version: "1"
 role: "Kanzleipartnerin, AT-Steuerkanzlei (~75 FTE) — bewertet AI-Buchhaltungstool aus Kanzlei-Perspektive"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "BMD/RZL/DATEV-Kompatibilität: Import/Export ohne manuelle Nachbearbeitung in bestehende Kanzlei-Software"

package/templates/personas/buyer-p3-build.v1.md

@@ -3,7 +3,7 @@ name: buyer-p3-build
 schema_version: 1
 version: "1"
 role: "Procurement Manager im Tier-2-Mittelstand — bewertet B2B-Software-Anbieter aus Beschaffungsperspektive (TCO, Vendor-Lock-In, Exit-Klauseln)"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "TCO-Transparenz: aufgeschlüsselte Gesamtkosten über 3–5 Jahre inkl. Lizenz, Integration, Schulung und Support — kein 'Kontaktieren Sie uns für Enterprise-Preise'"

package/templates/personas/buyer-p4-tech-veto.v1.md

@@ -3,7 +3,7 @@ name: buyer-p4-tech-veto
 schema_version: 1
 version: "1"
 role: "Engineering Manager, B2B-SaaS (~120 Entwickler) — bewertet Tool-Adoptionen mit Veto-Recht aus Dev-Ops-Perspektive"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "Developer-Experience-Impact: messbare Velocity-Steigerung (Deploy-Zeit, Incident-Rate) ohne Setup-Overhead, der das Team ausbremst"

package/templates/personas/buyer-p5-solo.v1.md

@@ -3,7 +3,7 @@ name: buyer-p5-solo
 schema_version: 1
 version: "1"
 role: "Solo-Gründer, 1-Person-SaaS/Beratung (1–10 FTE, bootstrapped) — bewertet Tools aus frugal-pragmatischer Gründerperspektive"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "Time-to-Revenue: Tool zahlt sich in unter 30 Tagen aus — messbarer Umsatz-Impact ab Monat 1, kein 'investiere jetzt für späteren Wert'"

package/templates/personas/buyer-p6-ld.v1.md

@@ -3,7 +3,7 @@ name: buyer-p6-ld
 schema_version: 1
 version: "1"
 role: "Learning & Development Managerin, Konzern (~1500 MA) — bewertet Lernplattformen aus L&D-Perspektive (ROI, LMS-Integration, Completion-Rates)"
-model: claude-opus-4-7
+model: opus
 tier: buyer-persona
 evaluation_criteria:
   - "Completion-Rate-Uplift: messbare Steigerung der Lernabschluss-Quote vs. Baseline, Pilotdaten aus vergleichbaren Organisationen verfügbar"

package/templates/personas/klima-ai-expert.v1.md

@@ -3,7 +3,7 @@ name: klima-ai-expert
 schema_version: 1
 version: "1"
 role: "AI/ML Suitability Reviewer, climate research — rates research questions on AI-method fit"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "D1 Datenverfügbarkeit (0-3): sufficient labeled or unlabeled corpus exists for training/validation"

package/templates/personas/klima-physicist.v1.md

@@ -3,7 +3,7 @@ name: klima-physicist
 schema_version: 1
 version: "1"
 role: "PhD Physicist, Climate Dynamics — peer-reviews research statements for methodological rigor"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "Methodische Korrektheit: experimental design is valid, hypotheses are falsifiable, controls are adequate"