baldart 5.7.0 → 5.9.0

package/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.9.0] - 2026-07-06
+
+**`security-reviewer` upgraded to the 2026 AppSec state of the art — benchmarked against Codex `codex-security` + Claude Code `security-guidance`, imported as a single-sourced protocol module.**
+The `security-reviewer` was a high-quality *monolithic* agent (senior persona, dual review/apply, pooled YAML, generic Challenge/CoVe via `review-protocol.md`) but stuck at a single-pass "read → list findings by severity" model. A benchmark against two real corpora — Codex's phased `codex-security` workbench (threat-model → discovery → validation → attack-path → severity, coverage ledgers, instance-preserving proof) and Claude Code's `security-guidance` agentic reviewer (adversarial self-refute, attacker≠victim, modern high-miss patterns) — found BALDART at ~60% of current best practice. This wave closes the gap **without a monolithic rewrite**, following the agent-spine 3-layer model.
+
+- **New protocol module [`framework/agents/security-review-protocol.md`](framework/agents/security-review-protocol.md)** — the AppSec verification engine, the security twin of `review-protocol.md`. `SECTION=` dispatch: `boundary-gate` (read `SECURITY.md` + classify `product_surface`/`source_trust`/`boundary_crossed` before confirming), `threat-model` (repository-scoped, never diff-biased), `discovery-lens` (the modern **high-miss** taxonomy: fail-open state drift, allowlist semantic escape, control regression, gate/action field mismatch, parser/validator differential, sensitive-to-observability, CI/CD trust, IaC omitted arg, over-broad grant, stale identity mapping, security-registry fanout, resource-bound placement), `proof-tuples` (class-specific validation tuples + confidence anchored to validation **method** not bug class + instance-preserving), `attack-path` (structured facts → **mechanical** severity), `adversarial-refute` (SURVIVES-unless-refuted, the **attacker≠victim** privilege-boundary test first, precondition-vs-counterevidence discipline, diff newly-introduced-only), `coverage-ledger` (surface dispositions so a clean verdict is honest). It **EXTENDS** `review-protocol.md`'s generic passes, never duplicates them — no dual-SSOT.
+- **`security-reviewer` agent (v1.0.0)** — gains a versioned frontmatter + a "Security Review Passes (BINDING)" block that cites the module with 1-line binding statements (agent-spine: core inline + module on demand). Mode A pooled YAML schema gains `vuln_class`, `cwe: [CWE-###]`, `validation_method`, and a structured `attack_path` block; the summary header carries a compact `coverage:` block. New **secret-redaction** BINDING (report a leaked credential as first 2–4 chars + `****`, never the live value — a review artifact reproducing a secret is itself a leak).
+- **`framework/agents/security.md`** — the consumer-facing security template modernized from **OWASP Top 10:2017 → 2021** (XXE folded into Security Misconfiguration, insecure deserialization into Software & Data Integrity Failures, XSS into Injection; new A04 Insecure Design + A10 SSRF), with a 2025-draft note.
+- Routing wired in `agents/index.md` (security routing rule + Modules list). README security-reviewer inventory line updated.
+- **Codex parity: portable** — the module is markdown read at runtime by both runtimes; the agent-body edits transpile to `.codex/agents/security-reviewer.toml` automatically. **No new `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
+## [5.8.0] - 2026-07-06
+
+**Suggested launch plan at the end of `/prd` — waves with a NAME, persisted on the epic card.**
+`/prd` used to close with a progress bar and a bare summary (PRD path, card IDs, branch, PR/SHA)
+but never told you **how to launch `/new`** — one run or several waves, where the boundaries are,
+which engine. You had to reason it out by hand. Now every `/prd` run ends with a mandatory
+**"🚀 Piano di implementazione suggerito"** section, and the plan is **persisted on the epic
+card** so `/new`/`/new2` can, at the end of a subset run, remind you which waves remain to close
+the epic — each wave carries a short, memorable **name** ("Wave 1 · Fondamenta server").
+
+The design was hardened by a two-reviewer adversarial pass that refuted the obvious v1
+(a separate `implementation_plan` block, an `engine` field on the card, a new reference module,
+the mechanical card-writer computing the heuristic). The shipped shape:
+
+- **Drift-free persistence — no new block, no new module.** The wave partition is three OPTIONAL
+  sub-keys (`wave` / `wave_name` / `wave_rationale`) on the EXISTING `execution_strategy.groups[]`
+  entries — the single card-ID partition already consumed by `/new` for parallelism. No parallel
+  `waves[]` array re-listing card IDs (that would drift). Because they are sub-keys of an
+  already-`R` field, the baseline validator never sees them: **no new field-state-matrix row, no
+  migration of legacy epics**. Schema SSOT: `framework/agents/card-schema.md`.
+- **Compute-by-orchestrator / persist-by-writer** (the `provenance.planning_session` split):
+  the `/prd` orchestrator (opus/high) computes the single-run-vs-waves judgment + names + rationale
+  — it needs the discovery context (migration-early, `review_profile: deep` pressure, server↔UI
+  cut) the mechanical `prd-card-writer` never holds — and persists it with a targeted Edit on the
+  epic card. The card-writer emits the keys ONLY when handed them; else it omits them (explicit
+  else branch → no fabrication). Single-run is the default (no wave tags).
+- **Engine + hard rules are render-time, never persisted.** The `/new` vs `/new2` recommendation
+  is computed at render and is **runtime-aware** — `/new2` needs the Workflow tool and is
+  Claude-only, so on Codex the plan recommends `/new` only. A durable, cross-tool artifact must
+  not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- **`/new` + `/new2` remaining-waves.** `/new`'s Step F.6 "Prossimi Passi" and `/new2`'s
+  `buildReport()` "Epic goal" render the remaining waves BY NAME (fallback to the flat card list
+  when the epic has no wave tags — no regression). `/new2` runs fs-less, so the `wave_name` is
+  threaded through `cardGraph` (new `waveName` node field derived by the preflight agent).
+- Project-specific between-wave cautions (migration/deploy gate, compile check, stash) stay in
+  `.baldart/overlays/prd.md` and are surfaced at render-time — no stack names in the base.
+
+No new `baldart.config.yml` key (rides on the existing `execution_strategy` + `features.*`) → the
+schema-change propagation rule does NOT apply. **Codex parity: portable** (runtime-neutral field;
+engine computed at render-time; `/new2` remaining-waves via `cardGraph`).
+
+Skills bumped: `prd` 1.6.1→1.7.0, `new` 2.3.1→2.4.0, `new2` 1.8.1→1.9.0.
+
 ## [5.7.0] - 2026-07-06
 
 **Feature-gated skill linking — stop wasting Codex's 2% skill-description budget.** Codex

package/README.md

@@ -92,7 +92,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
 2. **coder**: Writes production code with build/test/lint verification + Post-Approval Complexity Gate
 3. **code-reviewer**: Reviews for bugs, security, quality, maintainability — confidence-based filtering + Findings Schema
-4. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra
+4. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra — boundary-gate → repo-scoped threat-model → modern high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (`security-review-protocol.md`)
 5. **doc-reviewer**: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
 6. **wiki-curator**: Maintains the derived LLM wiki overlay (`docs/wiki/`) — synthesis candidates, anchor + frontmatter validation
 7. **prd**: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions

package/VERSION

@@ -1 +1 @@
-5.7.0
+5.9.0

package/framework/.claude/agents/CHANGELOG.md

@@ -7,6 +7,24 @@ per-item agent merge, the doctor probes, and the discovery hooks — like
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · per-agent SemVer.
 
+## [security-reviewer v1.0.0] — 2026-07-06 (framework v5.9.0 — AppSec state-of-the-art wave)
+
+- **First versioned entry.** Benchmarked against Codex `codex-security` (phased
+  workbench) + Claude Code `security-guidance` (agentic self-refute); imported the
+  gap as a single-sourced protocol module rather than a monolithic rewrite.
+- **New "Security Review Passes (BINDING)" block** — cites the new
+  `agents/security-review-protocol.md` with 1-line binding statements per section
+  (boundary-gate, threat-model, discovery-lens, proof-tuples, attack-path,
+  adversarial-refute, coverage-ledger). Agent-spine 3-layer: core inline + module
+  on demand. EXTENDS `review-protocol.md`, never duplicates it.
+- **Mode A pooled YAML schema extended**: `vuln_class`, `cwe: [CWE-###]`,
+  `validation_method`, structured `attack_path` block; summary header gains a
+  compact `coverage:` block. Other reviewers ignore the security-only fields.
+- **Secret-redaction BINDING** added to Behavior Rules — a leaked credential is
+  reported as first 2–4 chars + `****`, never the live value.
+- Codex parity: agent body transpiles to `.codex/agents/security-reviewer.toml`
+  automatically; the module is portable markdown. No new config key.
+
 ## [prd-card-writer v1.2.0] — 2026-07-04 (framework v5.6.0 — FEAT-0068 post-mortem)
 
 - **Epic AC rules**: mai count di figli hardcodato ("le 6 sub-card"); AC con

package/framework/.claude/agents/prd-card-writer.md

@@ -754,6 +754,29 @@ The consumer (`new/SKILL.md`) reads `execution_strategy.groups[].level` and
 `.cards`. Use these exact keys — `groups`/`level`, not the legacy
 `parallel_groups`/`group`.
 
+**Launch-wave sub-fields (`wave` / `wave_name` / `wave_rationale`) — write ONLY if handed to you.**
+The `/prd` orchestrator may pass a launch-wave partition (a run-sequencing judgment it computes
+AFTER you return the Parallel Execution Map — it needs discovery context you do not hold). When
+and only when the orchestrator hands you these values, add them as optional sub-keys on the
+matching `groups[]` entries:
+
+```yaml
+  groups:
+    - level: 0
+      cards: [FEAT-XXXX-01]
+      description: "Foundation/scaffold"
+      wave: 1                          # only if passed
+      wave_name: "Fondamenta server"   # only if passed
+      wave_rationale: "…"              # only if passed
+```
+
+If the orchestrator does NOT hand you a wave partition, **OMIT all three keys** — do NOT invent a
+wave grouping, a name, or a rationale (a launch judgment fabricated from the card graph alone is
+worse than absent; single-run epics legitimately carry no wave tags). This is the same
+compute-by-orchestrator / persist-by-writer split as `provenance.planning_session`. Schema + the
+render-time derivation live in [`framework/agents/card-schema.md`](../../agents/card-schema.md)
+§ "`execution_strategy.groups[].wave*`".
+
 ## Output Format
 
 **Self-validation BEFORE returning (v5.6.0 — you own your domain's deterministic hygiene).**

package/framework/.claude/agents/security-reviewer.md

@@ -4,6 +4,7 @@ description: "Use this agent when code needs a security review, when reviewing P
 model: sonnet
 color: red
 memory: project
+version: 1.0.0
 ---
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
@@ -73,6 +74,7 @@ file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (
 - NEVER hand-wave or give shallow "looks good" feedback.
 - NEVER approve insecure code because it is "probably internal".
 - NEVER recommend storing secrets in code, env files committed to git, client-side code, or logs.
+- **Secret redaction (BINDING).** When you report a leaked/hardcoded credential, NEVER write its full value — redact to the first 2–4 characters + `****`. Cite the `file:line` (the canonical source location), state what the credential grants and whether it is prod vs test, and recommend rotation if it is live. A review artifact that reproduces a live secret is itself a leak.
 - NEVER suggest disabling security controls for convenience unless explicitly discussing a temporary local-only dev workaround, clearly labeled as unsafe.
 
 ## Threat-Modeling Mindset
@@ -88,6 +90,43 @@ For every review, actively reason about:
 - Insider threat / compromised service misuse
 - Multi-tenant isolation boundaries (critical for any multi-customer platform)
 
+## Security Review Passes (BINDING — full procedure in the protocol module)
+
+These extend `review-protocol.md`'s generic passes (Challenge / Simulation /
+CoVe / risk-scoring) with the AppSec specifics. Keep the 1-line binding here;
+Read the matching section of `agents/security-review-protocol.md SECTION=<name>`
+for the procedure. Order: boundary-gate (once) → threat-model → discovery-lens →
+per candidate proof-tuples → attack-path → adversarial-refute → mechanical
+severity → coverage-ledger.
+
+- **BINDING — boundary-gate**: before confirming anything, read `SECURITY.md` /
+  deployment notes and classify the surface (`product_surface`, `source_trust`,
+  `boundary_crossed`); no boundary crossed → not a finding. `SECTION=boundary-gate`.
+- **BINDING — threat-model**: adopt or generate a REPOSITORY-scoped threat model
+  (never diff-biased); it picks your focus paths. `SECTION=threat-model`.
+- **BINDING — discovery-lens**: sweep the modern high-miss patterns (fail-open,
+  allowlist-escape, control-regression, gate/action mismatch, parser
+  differential, sensitive-to-observability, CI/CD trust, IaC omitted arg,
+  over-broad grant, stale identity, registry fanout) beyond the OWASP core.
+  `SECTION=discovery-lens`.
+- **BINDING — proof-tuples**: ground every finding in its class-specific tuple
+  (authz = path + missing guard + protected object; injection = bytes + sanitizer
+  result + sink; SSRF; deserialization; auth/token; XSS); confidence is anchored
+  to validation METHOD, not to how scary the bug class sounds; never collapse
+  independently exploitable sibling instances. `SECTION=proof-tuples`.
+- **BINDING — attack-path**: write structured attack-path facts (attacker,
+  entrypoint, preconditions, dataflow source→sink, outcome, impact×likelihood)
+  BEFORE severity, then apply severity mechanically. `SECTION=attack-path`.
+- **BINDING — adversarial-refute**: a finding SURVIVES unless refuted; test the
+  privilege boundary FIRST (attacker == victim on own machine → refute); keep
+  precondition (narrows likelihood) distinct from counterevidence (kills the
+  finding). In diff review, flag only newly-introduced/reachable surface.
+  `SECTION=adversarial-refute`.
+- **BINDING — coverage-ledger**: record a disposition for every surface in scope
+  (`reported` / `no_issue_found` / `not_applicable` / `needs_follow_up` /
+  `deferred`) so a clean verdict is honest and a gap is never silent; zero
+  findings on a fully-covered surface is a legitimate outcome. `SECTION=coverage-ledger`.
+
 ## Review Methodology
 
 For each file, code block, PR, or diff you review:
@@ -129,18 +168,27 @@ determine as `N/A` rather than dropping the finding):
   title: <one-line>
   source: security-reviewer
   category: security
+  vuln_class: <concrete class, e.g. "Authorization bypass / IDOR" — never a generic "security finding">
+  cwe: [<CWE-###>, ...]         # e.g. [CWE-22, CWE-434]; [] if none maps cleanly
   target: <one of the orchestrator's TARGET TAG values, or "notes" for informational>
   severity: BLOCKER | HIGH | MEDIUM | LOW
-  confidence: 0-100
+  confidence: 0-100             # anchored to validation_method (proof-tuples), not to the bug class
   evidence:
     file: <path or "N/A">
     lines: <range or "N/A">
     quote: |
       <exact code snippet, ≤8 lines>
   cove_verified: true | false   # true if you verified file/line via Glob/Grep/Read
+  validation_method: <poc | test | debugger | interface-repro | static-trace | code-understanding>
   repro_steps: <exploitation scenario — how an attacker reaches and triggers this>
   expected_behavior: <the secure behavior>
   actual_behavior: <the vulnerable behavior present in the code>
+  attack_path:                  # structured facts → severity falls out mechanically
+    attacker: <who, trust level, from where>
+    entrypoint: <exact reachable entry — route/RPC/CLI/webhook/MCP tool>
+    preconditions: <conditions required; "none" if unconditional>
+    dataflow: <source → sink, one line>
+    outcome: <concrete impact — data read/written, code executed, tenant crossed>
   risk:
     impact: 1-5
     likelihood: 1-5
@@ -148,6 +196,10 @@ determine as `N/A` rather than dropping the finding):
   recommendation: <concrete, minimal, production-ready fix; ≤3 sentences>
 ```
 
+The `# Security Review Summary` header that follows the YAML list carries a
+compact `coverage:` block (surfaces + dispositions per `SECTION=coverage-ledger`)
+so the orchestrator can tell a clean verdict from an incomplete one.
+
 Map your severity labels to the pooled enum: Critical → `BLOCKER`, High → `HIGH`, Medium →
 `MEDIUM`, Low/Informational → `LOW`. Follow the YAML list with a 3–4 line plain-text
 `# Security Review Summary` (scope / overall risk / main attack surfaces / most critical concern) so

package/framework/.claude/skills/new/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.4.0 — 2026-07-06
+
+- **Prossime wave per NOME nel messaggio finale.** Il Step F.6 "Prossimi Passi"
+  (`references/final-review.md`) ora è **wave-aware**: legge la partizione di lancio persistita
+  da `/prd` sull'epic card (sotto-campi opzionali `wave` / `wave_name` su
+  `execution_strategy.groups[]`) e, quando presente, mostra le **wave rimanenti per nome**
+  ("Prossime wave: **Wave 2 · Superfici UI**") invece della sola lista card piatta — così, dopo
+  aver implementato un subset (es. `/new FEAT-0069-01..06`), il riepilogo dice cosa resta per
+  chiudere l'epic senza doverlo ricordare. Engine della prossima wave suggerito runtime-aware
+  (Codex → solo `/new`). Richiede un Read esplicito dell'epic card a F.6 (non è in contesto:
+  letto solo transitoriamente in Phase 0). **Fallback grazioso** alla lista card piatta quando
+  l'epic non ha tag wave (single-run / legacy) → nessuna regressione. Schema SSOT:
+  `framework/agents/card-schema.md` § `execution_strategy.groups[].wave*`.
+  - Codex parity: portable (il campo è runtime-neutral; l'engine è calcolato a render-time).
+
 ## 2.3.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

package/framework/.claude/skills/new/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.3.1
+version: 2.4.0
 requires_feature: has_backlog
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards

package/framework/.claude/skills/new/references/final-review.md

@@ -439,7 +439,42 @@ that is a **gate violation**: log it as
      | xargs grep -L "status: DONE"
    ```
 
-   Present the section:
+   **Wave-aware next steps (v5.8.0).** `/prd` may have persisted a **launch-wave partition** on the
+   epic card — optional `wave` / `wave_name` sub-keys on `execution_strategy.groups[]` (schema:
+   `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`"). The epic card is NOT
+   in context here (it was read only transiently in Phase 0) — so **Read the epic card now**
+   (`${paths.backlog_dir}/<EPIC-ID>.yml`) to fetch the wave tags. Then:
+   - **If wave tags exist:** map each remaining not-DONE card to its `wave_name` (via the group whose
+     `.cards` contains it), and render the **remaining WAVES by name** instead of a flat card list — a
+     wave is "rimanente" when ≥1 of its cards is not-DONE. This keeps the thread across runs: the user
+     recognises "Wave 2 · Superfici UI" from the `/prd` plan. Suggest the engine for the NEXT wave
+     runtime-aware (Claude → `/new2` for a high-volume wave, else `/new`; Codex → `/new` only —
+     `/new2` is Claude-only).
+   - **If NO wave tags** (legacy epic / single-run): render the flat "Card rimanenti nell'epic" table
+     exactly as before (backwards-compat, no regression).
+
+   Present the section — WAVE-AWARE form (when wave tags exist):
+
+   ```
+   ## Prossimi Passi
+
+   ### Prossime wave da sviluppare
+   | Wave | Nome | Card rimanenti | Engine suggerito |
+   |------|------|----------------|------------------|
+   | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | /new2 |
+
+   ### Lancio prossima wave (copia e incolla)
+   ```
+   /new2 FEAT-XXXX-07-FEAT-XXXX-13
+   ```
+
+   ### Card completate in questa sessione
+   | Card | Titolo | Commit |
+   |------|--------|--------|
+   | FEAT-XXXX-01 | [title] | abc1234 |
+   ```
+
+   FLAT form (no wave tags — unchanged):
 
    ```
    ## Prossimi Passi

package/framework/.claude/skills/new2/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.9.0 — 2026-07-06
+
+- **Prossime wave per NOME nel report finale (parità con `/new`).** `buildReport()` (`new2.js`)
+  ora, per ogni epic APERTA nella sezione "Epic goal", elenca le **wave rimanenti per nome**
+  dalla partizione di lancio persistita da `/prd` sull'epic. Poiché il workflow gira senza
+  accesso al filesystem, il `wave_name` è **portato via `cardGraph`** (nuovo campo `waveName`
+  sul nodo — l'agente preflight lo deriva dai `execution_strategy.groups[]` dell'epic). Scope
+  onesto: visibili solo le wave le cui card sono NEL BATCH (le wave interamente fuori dal batch
+  non sono caricate). `''` quando l'epic non ha tag wave (single-run / legacy) → nessuna riga.
+  - Codex parity: portable (il campo è runtime-neutral).
+
 ## 1.8.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

package/framework/.claude/skills/new2/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.8.1
+version: 1.9.0
 requires_feature: has_backlog
 description: >
   Workflow-hosted batch engine for /new. Implements one or

package/framework/.claude/skills/prd/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.7.0 — 2026-07-06
+
+- **Piano di implementazione suggerito nel messaggio finale (sempre).** Il run di `/prd` ora
+  chiude con una sezione **"🚀 Piano di implementazione suggerito"** che dice come lanciare
+  `/new` — unica run vs **wave con NOME**, confini, engine (`/new` vs `/new2`) — invece di
+  lasciare all'utente il compito di ricavarla a mano. La logica del piano è **persistita
+  sull'epic card** così `/new`/`/new2` a fine run possono ricordare quali wave restano.
+  - **Persistenza drift-free:** nessun blocco nuovo — sotto-campi OPZIONALI `wave` / `wave_name`
+    / `wave_rationale` sui `groups[]` esistenti di `execution_strategy` (unica partizione di
+    card-ID; niente `waves[]` parallelo che drifta). Sono sotto-chiavi di un campo già `R` →
+    il baseline validator non le vede, **nessuna riga nuova nella field-state matrix**, epic
+    legacy invariate. Schema SSOT: `framework/agents/card-schema.md`.
+  - **Compute-by-orchestrator / persist-by-writer** (stesso split di `provenance.planning_session`):
+    l'**orchestratore `/prd`** calcola la partizione wave + nomi + rationale (giudizio di lancio
+    che serve il contesto di discovery — migration-early, pressione review `deep`, taglio
+    server/UI) e la persiste con un Edit mirato sull'epic card; il `prd-card-writer` scrive i
+    sotto-campi **solo se gli vengono passati**, altrimenti li omette (ramo else esplicito →
+    niente fabbricazione). Single-run resta il default: nessun tag wave.
+  - **Engine + hard-rule = render-time, non persistiti.** La scelta `/new` vs `/new2` è calcolata
+    a render ed è runtime-aware (Codex → solo `/new`, `/new2` è Claude-only) — un artefatto
+    cross-tool durabile non porta una raccomandazione che un consumer Codex non può eseguire.
+  - **Base generico + overlay:** cautele project-specific tra-wave (migration/deploy gate, compile
+    check, stash) restano in `.baldart/overlays/prd.md`, innestate a render-time.
+  - File: `references/backlog-phase.md` (compute+persist), `references/validation-phase.md`
+    (render), `assets/epic-template.yml` (chiavi commentate), `framework/agents/card-schema.md`
+    (schema), `framework/.claude/agents/prd-card-writer.md` (omit-if-not-passed).
+  - Codex parity: portable (campo runtime-neutral; engine calcolato a render-time).
+
 ## 1.6.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_prd_workflow` frontmatter — this skill is now linked into a consumer only when `features.has_prd_workflow` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

package/framework/.claude/skills/prd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.6.1
+version: 1.7.0
 requires_feature: has_prd_workflow
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -135,6 +135,12 @@ execution_strategy:
     - level: 0
       cards: [{{FEAT-XXXX-01}}]
       rationale: "{{foundation / first dependency layer}}"
+      # Optional launch-wave tags — written by the /prd ORCHESTRATOR only (not the card-writer),
+      # and only when the epic is launched across multiple /new runs. Omit entirely for
+      # single-run epics. Schema: agents/card-schema.md § execution_strategy.groups[].wave*
+      # wave: 1
+      # wave_name: "{{Fondamenta server}}"
+      # wave_rationale: "{{migration + config + resolver + enforcement server}}"
     - level: 1
       cards: [{{FEAT-XXXX-02}}, {{FEAT-XXXX-03}}]
       rationale: "{{parallel after L0}}"

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -290,6 +290,42 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - Presenting results to the user (the agent returns summary, main context displays it)
 - Proceeding to Step 6 (validation phase)
 
+## Launch-wave partition (orchestrator judgment — YOU compute it, not the card-writer)
+
+After the card-writer returns the Parallel Execution Map, **you** (the `/prd` orchestrator)
+decide how the epic should be **launched** across `/new` runs — a judgment the mechanical
+card-writer cannot make because it needs the discovery context you hold (Tier, review-profile
+mix, migration, UI/server split). This is the durable half of the "Piano di implementazione
+suggerito" the final message renders (validation-phase.md § Final output).
+
+**Decide single-run vs waves (scoped — default single-run).** Keep the epic as ONE run unless
+at least one split trigger fires; if none fires, do NOT tag any wave (single-run is the explicit
+else branch — never fabricate a wave grouping just to have one):
+- **Large batch** — many children over several dependency levels (a long single run drifts the
+  trunk mid-batch → merge conflicts instead of fast-forward; keep this rationale generic, do not
+  name a stack).
+- **Migration / schema card present** — land it in an EARLY wave so its migration/deploy gate runs
+  once and later waves build on the real schema.
+- **Review pressure** — many `review_profile: deep` children; splitting keeps the orchestrator
+  context lucid on exactly the cards that need lucid review.
+- **Clear server↔UI cut** — server/data foundation vs UI surfaces is a natural wave boundary
+  (UI/E2E cards exercise the server, so they belong in the later wave).
+- **Cross-domain file conflicts** — `execution_strategy.file_conflicts` that straddle a domain
+  boundary force sequencing.
+
+**Assign waves over the EXISTING groups (one partition, no re-listing of card IDs).** Waves are a
+contiguous grouping of `execution_strategy.groups[]` in `level` order. For each group in a wave,
+set `wave` (1-based, ascending), `wave_name` (a short, unique, human-memorable name derived from
+the wave's dominant domain/role — e.g. "Fondamenta server", "Superfici UI & closer"), and
+`wave_rationale` (one line). Persist them by **editing the epic card** (`backlog/<slug>-00.yml`)
+in the worktree — a targeted Edit adding the three sub-keys to the matching `groups[]` entries.
+Do NOT re-spawn the card-writer; do NOT create a parallel `waves[]` block. Schema:
+`framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`".
+
+**Do NOT persist the engine (`/new` vs `/new2`) or the hard rules** — those are render-time,
+runtime-aware (validation-phase.md § Final output). On a single-run epic, skip this step entirely
+(no wave keys written).
+
 ## Present and Proceed
 
 Present the plan to the user (traceability matrix + parallel execution map) for

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -410,4 +410,34 @@ A run that prints "local `git.trunk_branch` did not fast-forward, handle the fil
 yourself and then pull" has FAILED Step 7.5 — go back and resolve it before
 printing the summary.
 
+Then, ALWAYS, append the launch plan:
+
+### 🚀 Piano di implementazione suggerito (MANDATORY — always render)
+
+Derive it from the epic card's `execution_strategy` (the wave partition you persisted in
+backlog-phase.md § "Launch-wave partition"); nothing here is recomputed from scratch. Rules +
+schema: `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`" (Launch waves).
+
+- **Single-run** (≤1 distinct `wave_name`, e.g. a light-lane 1-child epic): render ONE line —
+  `**Lancia in un'unica run:** \`/new <all card IDs>\`` — no table. Stop here.
+- **Waves** (≥2 distinct `wave_name`): render a table, one row per wave in `wave` order:
+
+  | Wave | Nome | Card | Contenuto |
+  |------|------|------|-----------|
+  | 1 | Fondamenta server | FEAT-XXXX-01…06 | <wave_rationale> |
+  | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | <wave_rationale> |
+
+  Then, below the table:
+  - **Engine (runtime-aware — computed here, never read from the card).** On **Claude** (the
+    `Workflow` tool is available) recommend `/new2` for a high-volume wave (off-context batch, no
+    interactive gates) and `/new` (classic) for a wave that wants human gates (migration / risky
+    review) — a hybrid (`/new` on the risky early wave, `/new2` on the rest) is a valid call. On
+    **Codex** recommend `/new` only — `/new2` needs the `Workflow` tool and does not exist there
+    (`framework/agents/runtime-portability-protocol.md` § "Workflow acceleration"). Give the exact
+    command per wave, e.g. `/new2 FEAT-XXXX-01-FEAT-XXXX-06`.
+  - **Hard rule:** niente altro lavoro in parallelo sugli stessi file tra una wave e l'altra.
+  - **Post-wave gates:** if `.baldart/overlays/prd.md` declares project-specific between-wave
+    cautions (e.g. a migration/deploy gate, a compile check, a stash check), surface them after the
+    relevant wave. Omit this line when the overlay declares none — never invent stack-specific steps.
+
 Display completed Progress Bar.

package/framework/.claude/workflows/new2.js

@@ -219,6 +219,11 @@ const PREFLIGHT_SCHEMA = {
           // Drives the epic-closure blocklist (an epic with open scope residuals/follow-ups must
           // not close) and the Epic goal section of the final report.
           parentEpic: { type: 'string', description: "parent epic id from group.parent or parent: ('' when none)" },
+          // v5.8.0 — the launch-wave this card belongs to, IFF /prd persisted a wave partition on
+          // the epic card (optional wave_name on execution_strategy.groups[] whose .cards includes
+          // this id — schema: agents/card-schema.md § execution_strategy.groups[].wave*). '' when the
+          // epic has no wave tags (single-run / legacy). Drives the "Prossime wave" report line.
+          waveName: { type: 'string', description: "launch wave_name from the epic's execution_strategy.groups[] ('' when none)" },
         },
       },
     },
@@ -305,7 +310,7 @@ try {
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c, card-schema.md consumer contract): card missing acceptance_criteria/files_likely_touched/scope → EXCLUDE (excluded[] + reason). \`requirements\` is CONDITIONAL, not an auto-exclude: if it is missing BUT acceptance_criteria + scope are both present and non-empty, FAITHFULLY DERIVE it (a concrete restatement/decomposition of the existing AC + scope — faithful, never inventing new scope) and WRITE it back to the card YAML on disk in ${MAIN}/${paths.backlog_dir || 'backlog'} (F-040: main repo, not the worktree copy; the card artifact is NOT a source/doc file, so this is allowed despite the role boundary), logging \`[BACKFILL] <id>: requirements=<N items, AC+scope-derived>\`. Only EXCLUDE for missing requirements when acceptance_criteria OR scope is ALSO empty (a genuinely thin card). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
-      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), waveName (v5.8.0 — when the parent epic card carries a launch-wave partition, the wave_name of the execution_strategy.groups[] entry whose .cards includes this id; '' when the epic has no wave tags — single-run/legacy; drives the "Prossime wave" report line), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
       (migrationApplied
@@ -1687,7 +1692,19 @@ function buildReport(o) {
       const epicHigh = residuals.filter((r) => ((graphById[r.card] && graphById[r.card].parentEpic) === e || r.card === e) && (sevRank[residualSeverity(r)] || 0) >= 2)
       if (closedEpics.includes(e) && !closureBlockedEpics.has(e)) L.push(`- **${e}: CHIUSA** (children DONE + AC epic verificati dal merge agent)`)
       else if (closedEpics.includes(e)) L.push(`- **${e}: ⚠️ CHIUSA CONTRO BLOCKLIST (false DONE)** — riaprire: ${epicHigh.length} residuo/i HIGH aperti`)
-      else L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+      else {
+        L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+        // v5.8.0 — remaining launch waves by NAME (parity with /new final-review F.6). Uses the
+        // waveName threaded through cardGraph (buildReport has no fs access to re-read the epic).
+        // Honest scope: only waves whose cards are IN THIS BATCH are visible — waves entirely
+        // outside the batch aren't loaded, so this reflects the batch, not the whole epic.
+        const openWaves = dedupe(
+          cardGraph
+            .filter((n) => (n.parentEpic || '') === e && n.waveName && (perCardResults.find((r) => r.card === n.id) || {}).status !== 'DONE')
+            .map((n) => n.waveName)
+        )
+        if (openWaves.length) L.push(`  - Prossime wave (batch): ${openWaves.map((w) => `**${w}**`).join(' · ')}`)
+      }
     }
   }
   if (finalSummary) {

package/framework/agents/card-schema.md

@@ -230,6 +230,56 @@ Rules:
 - Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
   placeholder.
 
+### `execution_strategy.groups[].wave*` — launch-wave annotation (epic-only, optional, orchestrator-written)
+
+The epic's `execution_strategy.groups[]` is the **single card-ID partition** consumed by `/new`
+for parallelism (`groups[].level` + `.cards` — the machine schedule). A **launch wave** is a
+coarser, human-facing partition layered ON TOP of those same groups so the user can sequence the
+epic across multiple `/new` runs and refer to each run by a stable NAME. It is expressed as three
+**optional sub-fields on the existing `groups[]` entries** — never a parallel block that re-lists
+card IDs (that would be a second SSOT that drifts from `groups[].cards`):
+
+```yaml
+execution_strategy:
+  recommended_mode: team | sequential      # existing — scheduling shape, runtime-neutral
+  groups:
+    - level: 0
+      cards: [FEAT-0069-01, FEAT-0069-02]   # existing — the ONLY card-ID partition
+      description: "Foundation/scaffold"     # existing
+      wave: 1                                # opt — 1-based wave index (contiguous over groups)
+      wave_name: "Fondamenta server"         # opt — short, unique human NAME for the wave
+      wave_rationale: "migration + config + resolver + enforcement server"  # opt — why this wave
+```
+
+Rules:
+- **Optional (`C`)**, epic-only. They are **sub-keys of `execution_strategy`** (already `R`), NOT
+  top-level fields — the field-state matrix carries **no new row** and the baseline validator (which
+  checks only top-level presence/non-emptiness) never sees them. Legacy epics lack them → no HALT,
+  no migration.
+- **Ownership split (same as [`provenance`](#provenance-session-id-traceability--optional-skill-written)):**
+  the `/prd` **orchestrator** COMPUTES the wave partition + names + rationale (a launch judgment that
+  needs discovery context — migration-early, review-`deep` pressure, server↔UI cut — which the
+  mechanical `prd-card-writer` does not hold), and it is PERSISTED onto the epic card. The card-writer
+  emits these keys ONLY when handed them; otherwise it **omits** them.
+- **Contiguity invariant:** waves partition the groups in `level` order — a wave is a contiguous run
+  of groups. `wave` numbers ascend 1,2,3…; every group in the same wave shares one `wave_name`.
+- **Single-run:** ≤1 distinct `wave_name` across all groups (e.g. a light-lane 1-child epic) means
+  "launch in one run" — the orchestrator leaves the wave keys ABSENT rather than tagging everything
+  `wave: 1`.
+
+**Launch waves (render-time — NOT persisted):** the human-facing launch plan is derived, never
+stored beyond the three keys above:
+- The **wave view** = group the epic's `groups[]` by `wave_name`, ordered by `wave`; each wave's
+  cards = the union of its groups' `.cards`. Consumers: `/prd` final message ("Piano di
+  implementazione suggerito") and `/new`/`/new2` final message ("prossime wave rimanenti", joining
+  wave membership with each card's on-disk `status`).
+- The **engine recommendation** (`/new` vs `/new2`) is computed at render time and is **runtime-aware**
+  — `/new2` needs the Workflow tool and is **Claude-only** (see `framework/agents/runtime-portability-protocol.md`
+  § "Workflow acceleration" — *no Codex equivalent*). It is **never persisted** on the card: a durable,
+  cross-tool artifact must not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- The anti-parallel hard rule ("no other work on the same files between waves") and any project-specific
+  post-wave gates (surfaced from `.baldart/overlays/prd.md`) are render-time constants, likewise not persisted.
+
 ## Acceptance-criteria grammar (EARS) + per-AC oracles (since the EARS+verify wave)
 
 **Why**: a prose AC passes gates without being verifiable ("handle it correctly"), and

package/framework/agents/index.md

@@ -37,7 +37,7 @@ Route agents to the right module with minimal reading.
 - If touching terminology or naming -> read `agents/coding-standards.md`.
 - If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.
 - If touching operational procedures (backup, cleanup, secrets) -> read `docs/operations/` if it exists in your project.
-- If touching security or auth risk -> read `agents/security.md`.
+- If touching security or auth risk -> read `agents/security.md` (OWASP 2021 posture + secure-defaults). If performing a dedicated AppSec review (the `security-reviewer` agent, `/codexreview` security pass) -> also read `agents/security-review-protocol.md` (the matching `SECTION=` only): boundary-gate → repo-scoped threat-model → high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (attacker≠victim) → coverage-ledger. It EXTENDS `review-protocol.md` (generic passes), never duplicates it.
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
@@ -86,6 +86,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/runtime-portability-protocol.md` — Runtime-mechanics binding: the abstract-operation ↔ Claude/Codex map (spawn / permissions / workflow-accel / state-spine / decision-gate / read-write path / adversarial-vs-cross-model), detect-once capability contract; cited by `/new` + `/prd`. The runtime-mechanics twin of `effort-protocol.md` + `return-contract-protocol.md` (since the Codex-parity S4 wave)
 - `agents/agent-operating-protocol.md` — Shared operating procedures for the core agents (injection guard, doc-retrieval consumption, persistent-memory hygiene, tool-budget discipline), `SECTION=` dispatch, read only the matching section; agents keep 1-line binding versions inline (since v5.0.0)
 - `agents/review-protocol.md` — The shared verification engine for reviewers: Challenge + Actionability, Simulation (diff-walk / plan-walk), Chain-of-Verification, quantified risk scoring + absolute severity calibration, specialist-spawn discipline incl. orchestrated-mode `specialist_dispatch` suppression; `SECTION=` dispatch (since v5.0.0)
+- `agents/security-review-protocol.md` — The AppSec verification engine for `security-reviewer`: boundary-gate, repository-scoped threat-model, modern high-miss discovery-lens (fail-open / allowlist-escape / control-regression / gate-action mismatch / parser differential / CI-CD trust / IaC omitted arg / over-broad grant), class-specific proof-tuples (method-anchored confidence, instance-preserving), structured attack-path → mechanical severity, adversarial-refute (attacker≠victim, precondition vs counterevidence), coverage-ledger; `SECTION=` dispatch. EXTENDS `review-protocol.md`, never duplicates it. Portable Claude+Codex (since v5.9.0)
 - `agents/doc-audit-protocol.md` — doc-reviewer's audit-mode procedures (drift validator suite, topological generation, epistemic metadata, SCIP anchors, schema/registry drift, coverage gauges); read ONLY when invoked without card context; `SECTION=` dispatch (since v5.0.0)
 - `agents/research-protocol.md` — Research discipline: `PROFILE=<decision|deep|compare|regulatory>` output contracts (+ `DEPTH=` iterative loop), the research library (`paths.research_dir` — layout, report frontmatter, INDEX, archive-not-delete), the reuse pre-flight (`FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs), and the versioned source matrix with its growth loop (`SOURCE_MATRIX_CANDIDATE`); `SECTION=` dispatch. The research-side sibling of `analysis-profiles.md` (since v5.1.0)
 

package/framework/agents/security-review-protocol.md

@@ -0,0 +1,233 @@
+# Security Review Protocol — the AppSec verification engine
+
+**Purpose**: the security-specific passes that turn a generic code review into
+an adversarial AppSec audit — repository-scoped threat modeling, the modern
+high-miss discovery lens, class-specific proof tuples, structured attack-path →
+mechanical severity, adversarial self-refutation (attacker vs victim), and a
+coverage ledger so *"not observed" never reads as "not reviewed"*. Distilled
+from the Codex `codex-security` workbench + the Claude Code `security-guidance`
+agentic reviewer. This module is the **single SSOT** of that methodology.
+
+**Relationship to `review-protocol.md`**: that module owns the GENERIC verifier
+passes (Challenge, Actionability, Simulation, Chain-of-Verification, risk
+scoring). This module **extends**, never duplicates them: `adversarial-refute`
+is the security-specialized layer that runs *inside* the generic Challenge pass;
+`proof-tuples` is the security grounding for the generic CoVe pass. On the
+generic passes, `review-protocol.md` wins; on AppSec specifics, this module
+wins.
+
+**Consumer**: `security-reviewer` (body citations). Portable as-is across Claude
+Code and Codex (read at runtime by both).
+
+## Contract
+
+- **Dispatch**: cite `agents/security-review-protocol.md SECTION=<threat-model|discovery-lens|proof-tuples|attack-path|adversarial-refute|coverage-ledger|boundary-gate>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order of passes** (normative): `boundary-gate` (once, at kickoff) →
+  `threat-model` (adopt or generate) → discovery under the `discovery-lens` →
+  per candidate: `proof-tuples` (validation) → `attack-path` (structured facts)
+  → `adversarial-refute` → mechanical severity (`review-protocol.md
+  SECTION=risk-scoring`) → `coverage-ledger` close. The generic Challenge + CoVe
+  passes still run; the security passes feed them.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report —
+  the report/YAML shape stays defined in the agent body.
+
+---
+
+### SECTION: boundary-gate
+
+Run ONCE before confirming any finding. A vulnerability only exists when an
+attacker crosses a trust boundary of a **shipped/deployed** surface — so
+classify the surface first, or you will flag same-privilege local code as a
+"vuln".
+
+1. **Read the repo's own policy FIRST**: `SECURITY.md`, `AGENTS.md` deployment
+   notes, package metadata. They define which surfaces are in-scope and what the
+   supported threat model is. A finding that contradicts a documented,
+   intentional design is a policy question, not a confirmed vuln.
+2. **Classify the surface under review**:
+   - `product_surface`: hosted service | library API | CLI | local dev UI |
+     MCP/tooling | example/demo | test | docs | generated | vendored.
+   - `source_trust` of the input: untrusted (remote/attacker) |
+     trusted_operator | trusted_developer_config | local_only |
+     intentional_code_execution.
+   - `boundary_crossed`: does attacker-controlled input reach the sink across a
+     real privilege/trust boundary? true | false | unknown.
+3. **Gate**: no boundary crossed (attacker == victim, same privilege, local dev
+   tool with no request handler) → NOT a finding. Record the disposition in the
+   coverage ledger, do not emit it as LOW.
+
+### SECTION: threat-model
+
+Establish (or adopt) a **repository-scoped** threat model — deliberately NOT
+biased by the current diff, so it stays valid for any change in the same repo.
+
+- **Adopt** an existing model from the user, `SECURITY.md`, or `AGENTS.md` when
+  present. Only **generate** a fallback when none exists.
+- Fallback generation, repository-level (not diff-scoped):
+  1. Real-world purpose + primary product/runtime surfaces actually exposed
+     (separate them from test/demo/tooling/docs paths).
+  2. Trust boundaries + the actors on each side; separate **attacker-controlled**
+     vs **operator-controlled** vs **developer-controlled** inputs explicitly.
+  3. Sensitive assets: user data, auth artifacts, authorization state,
+     secrets/keys, config, models/weights, audit logs, availability-critical
+     resources, tenant-isolation state.
+  4. Vulnerability CLASSES relevant to this repo's context (not the diff's
+     findings) + existing mitigations grounded in real files.
+  5. When realistic vs out-of-scope: state attacker (non-)capabilities so
+     severity is not inflated.
+- Use it to pick **focus paths** for the review; do not let the diff recenter it
+  unless the user asks for a diff-scoped model.
+
+### SECTION: discovery-lens
+
+Beyond the OWASP core checklist (in the agent body), sweep for the **modern
+high-miss patterns** — the ones a generic checklist walks past. For each changed
+region, ask:
+
+- **FAIL-OPEN state drift**: a default that *allows* on the unknown/error path —
+  catch-all `default: allow`, `unwrap_or({})`, a removed `finally` that left the
+  deny, an early-return before the check. Security must fail *closed*.
+- **ALLOWLIST semantic escape**: a matcher weakened — a `||`/disjunction added, a
+  regex left unanchored (`^…$` missing), an allowlist checked by `startsWith`/
+  substring, a URL trusted by substring instead of parsed host.
+- **CONTROL regression**: a deny-by-default replaced by a single positive
+  condition; an authz/confirm/audit control loosened or removed in the diff.
+- **GATE / ACTION field mismatch**: the gate checks resource A (parent, id X) but
+  the action writes/reads resource B (child, id Y) — the check and the effect
+  disagree.
+- **UNDER-VALIDATED sink arg**: user data flows into sink arg *X* while a sibling
+  path validates arg *Y* — asymmetry between siblings is the tell.
+- **PARSER/VALIDATOR differential**: the validator and the consumer parse the
+  input differently (two URL parsers, JSON vs form, unicode/normalization) — the
+  gap is the exploit.
+- **SENSITIVE-to-observability**: secrets/tokens/PII reaching logs, traces,
+  error responses, analytics, crash dumps.
+- **CI/CD trust**: `pull_request_target` / `workflow_dispatch` / injectable
+  `${{ github.event.*.body }}` combined with secrets or repo-write; a workflow
+  running untrusted code with elevated tokens.
+- **IaC omitted arg**: a Terraform/CDK/K8s resource missing a security flag
+  (public bucket, open SG, no encryption, over-broad IAM `*`).
+- **OVER-BROAD grant**: an admin/`*` role/scope where a narrower one exists;
+  new IAM/RLS/role wider than the action needs.
+- **STALE identity mapping**: a window between unregister/rotate and the new
+  binding where the old identity still resolves.
+- **SECURITY-REGISTRY fanout**: a new entity type (model, scope, route, event)
+  added but missing from the sanitizer/allowlist/authz registries that must
+  enumerate it.
+- **RESOURCE-bound placement**: a cap/limit on the wrong accumulator; an
+  under/overflow; a size check after the allocation.
+
+### SECTION: proof-tuples
+
+A security finding is a *hypothesis* until its **class-specific proof tuple** is
+grounded against real code (this is the AppSec form of the CoVe pass). Confirm
+every element by grep/read before emitting; drop the finding if any element is
+missing.
+
+- **authz / IDOR**: attacker reachability path + the missing/bypassed guard + the
+  protected object or state it exposes.
+- **injection** (SQL/NoSQL/OS/LDAP/template): attacker-controlled bytes + the
+  sanitizer/parameterization result (or its absence) + the dangerous sink.
+- **deserialization**: attacker serialized input + the unsafe loader + the
+  execution/instantiation effect.
+- **SSRF / open redirect**: attacker-controlled destination + the control bypass
+  + the network reach / side effect.
+- **auth / token**: attacker-supplied value + the validator's exact semantics +
+  the mismatch with the trusted value.
+- **XSS**: attacker string + the encoding/escaping context at output + the sink
+  (`innerHTML`/`dangerouslySetInnerHTML`/template) with no encode.
+
+**Confidence anchored to validation METHOD, never to how scary the bug class
+sounds**:
+- reproduced PoC / failing test that triggers the sink → confidence 90–100.
+- debugger/trace or a proven interface reproduction → 75–90.
+- static source→sink trace fully grounded in read code → 60–80.
+- code-understanding argument with a defensible but not fully-traced path →
+  30–55. Below that, it is a hypothesis — do not ship as HIGH.
+
+**Instance-preserving**: do NOT collapse independently exploitable sibling
+instances (`execute` / `executemany` / `executescript`; two routes with the same
+flaw) into one finding. Each independently triggerable sink gets its own
+finding/closure row.
+
+### SECTION: attack-path
+
+BEFORE assigning severity, write the attack path as **structured facts**, then
+let severity fall out of them mechanically (`review-protocol.md
+SECTION=risk-scoring`) — this stops severity from being argued emotionally.
+
+- `attacker`: who, at what trust level, from where.
+- `entrypoint`: the exact reachable entry (route/RPC/CLI/webhook/MCP tool).
+- `preconditions`: conditions that must hold for the exploit (feature flag on,
+  authenticated user, specific config). A **precondition** narrows likelihood but
+  does NOT refute — keep it distinct from counterevidence (which kills the
+  finding, see `adversarial-refute`).
+- `dataflow`: source → sink in one line.
+- `outcome`: the concrete impact (data read/written, code executed, tenant
+  crossed).
+- `impact` (1–5) and `likelihood` (1–5), each with one line of repo evidence.
+
+Severity is then `review-protocol.md SECTION=risk-scoring` applied to
+`impact × likelihood` — do not re-argue it afterward.
+
+### SECTION: adversarial-refute
+
+The security-specialized layer of the generic Challenge pass. Stance: **a finding
+SURVIVES unless you produce concrete refuting evidence** — but the single most
+common false positive is a **missing privilege boundary**, so test that first.
+
+**Privilege-boundary test (BINDING)**: name the attacker (who controls the input)
+and the victim (who is harmed). If attacker == victim operating on their own
+machine / same-privilege process (a CLI arg in a same-trust process, a dev
+script, a local tool with no remote entrypoint) → **REFUTE**. Keep it only when
+the attacker is a lower-trust actor and the impact reaches other users, tenants,
+or infrastructure.
+
+**Refute the finding when**:
+- it is **pre-existing** code untouched by the diff (in diff-scoped review, flag
+  only newly introduced or newly reachable surface; an off-diff finding must name
+  the specific `+`/`-` line that enables the sink).
+- a sanitizer / validator / parameterization / authz check on the real path
+  already prevents the exploit.
+- the sink is not actually dangerous here (typed-schema decoder, hardcoded
+  `https` URL, ORM/parameterized query, non-HTML context for an "XSS").
+- a frontend-only gate is independently enforced by the backend (or vice-versa).
+- validation is delegated to a caller/framework that provably runs it.
+- it is throwaway/dev-only code (`scripts/`, `dev/`, `__main__`, fixtures, tests)
+  with no shipped surface.
+- a dependency bump moved the control into the library (documented).
+
+**Precondition vs counterevidence (keep precise)**: "deployment is internal-only"
+is a *precondition* on the finding (still exploitable if it holds) → keep, lower
+likelihood. "the code is test-only" is *counterevidence* → refute. Do not confuse
+the two.
+
+**Never-refute guard**: an item the agent's never-demote list marks (auth bypass,
+RCE, secret exposure, cross-tenant breach with a grounded proof tuple) is never a
+false positive — do not refute it however convincing the argument sounds.
+
+Record refuted candidates (title + one-line refutation) so the audit trail shows
+they were considered, not missed.
+
+### SECTION: coverage-ledger
+
+Make the review's *coverage* explicit so a clean verdict is honest and a gap is
+never silent. For each security-relevant surface in scope, record a disposition:
+
+- `reported` — a finding was emitted.
+- `no_issue_found` — reviewed, no credible issue survived the passes.
+- `not_applicable` — the class does not apply to this surface (with the reason).
+- `needs_follow_up` — a real concern out of this review's scope/ownership
+  (surfaces as residual).
+- `deferred` — could not complete (tool/access/time), with the reason + paths.
+
+Rules:
+- A **complete** review has zero `deferred` / `needs_follow_up` rows; otherwise
+  it is **partial** — say so. Zero findings on a fully-covered surface is a
+  legitimate, reportable outcome.
+- A seeded obligation (a CVE/advisory/user pointer at a specific file/function)
+  stays OPEN until its exact row is closed as reported / not_applicable /
+  deferred — a neighboring same-family finding does not close it.
+- In the pooled YAML mode, carry this as a compact `coverage:` block in the
+  `# Security Review Summary` header, not as fake LOW findings.

package/framework/agents/security.md

@@ -55,72 +55,76 @@ Document security requirements, threats, and mitigation strategies.
 - [Sensitive data masking in logs]
 - [Secrets management]
 
-## Common Vulnerabilities (OWASP Top 10)
+## Common Vulnerabilities (OWASP Top 10 — 2021)
 
-### Injection Attacks
+> Modernized to the OWASP Top 10:2021 categories (the 2017 list — with XXE and
+> "Sensitive Data Exposure" as standalone entries — is superseded). XXE now folds
+> into Security Misconfiguration; insecure deserialization into Software & Data
+> Integrity Failures; XSS into Injection. A 2025 revision is in draft — revisit
+> when it is finalized (expected consolidation of supply-chain risks).
 
-- Use parameterized queries
-- Validate and sanitize inputs
-- Implement least privilege database access
+### A01 Broken Access Control
 
-### Broken Authentication
+- Enforce authorization on every request, server-side; deny by default
+- Prevent IDOR — never trust a user-supplied record/object identifier
+- Enforce ownership + tenant isolation on every sensitive action
+- Principle of least privilege; no privilege escalation via business logic
 
-- Implement secure session management
-- Use strong password policies
-- Implement account lockout
-- Protect against brute force
+### A02 Cryptographic Failures
 
-### Sensitive Data Exposure
+- Encrypt sensitive data at rest and in transit (HTTPS/TLS everywhere)
+- Use strong, modern algorithms (no MD5/SHA1 for security, no AES-ECB, no static IV)
+- Proper key management + rotation; never log secrets or PII
+- Strong password hashing (argon2/bcrypt/scrypt) with per-user salt
 
-- Encrypt sensitive data
-- Use HTTPS everywhere
-- Don't log sensitive information
-- Implement secure key management
+### A03 Injection (incl. XSS)
 
-### XML External Entities (XXE)
+- Parameterized queries / ORM; never build queries by string concatenation
+- Validate + sanitize inputs; allowlists over denylists
+- Least-privilege database access
+- Output encoding at the right context + Content Security Policy for XSS
 
-- Disable XML external entity processing
-- Use safe XML parsers
-- Validate XML inputs
+### A04 Insecure Design
 
-### Broken Access Control
+- Threat-model the feature before building; secure-by-default patterns
+- Establish trust boundaries and enforce them; fail closed
+- Rate limits, resource bounds, and abuse cases considered up front
 
-- Implement proper authorization
-- Validate permissions on every request
-- Use principle of least privilege
+### A05 Security Misconfiguration (incl. XXE)
 
-### Security Misconfiguration
+- Harden defaults; remove unnecessary features/debug endpoints in prod
+- Set security headers; keep software updated
+- Disable XML external-entity processing; use safe parsers/validators
 
-- Harden default configurations
-- Keep software updated
-- Remove unnecessary features
-- Implement security headers
+### A06 Vulnerable & Outdated Components
 
-### Cross-Site Scripting (XSS)
+- Keep dependencies patched; monitor security advisories (CVE/GHSA)
+- Run dependency + vulnerability scanning in CI (e.g. audit / govulncheck)
+- Remove unused dependencies and features
 
-- Escape output
-- Use Content Security Policy
-- Validate and sanitize inputs
-- Use framework protections
+### A07 Identification & Authentication Failures
 
-### Insecure Deserialization
+- Secure session management (rotation, expiry, secure cookies)
+- Strong password policy, account lockout / brute-force protection, MFA where applicable
+- No session fixation, no token leakage in URLs/logs
 
-- Validate serialized data
-- Use safe deserialization libraries
-- Implement integrity checks
+### A08 Software & Data Integrity Failures (incl. insecure deserialization)
 
-### Using Components with Known Vulnerabilities
+- Never deserialize untrusted data with unsafe loaders; validate + integrity-check
+- Verify integrity of updates/CI artifacts (signatures, SRI, pinned digests)
+- Guard the CI/CD supply chain — no untrusted code with elevated tokens
 
-- Keep dependencies updated
-- Monitor security advisories
-- Use dependency scanning tools
+### A09 Security Logging & Monitoring Failures
 
-### Insufficient Logging & Monitoring
+- Log security events; monitor for suspicious activity; alert
+- Protect log integrity; never log secrets/PII
+- Ensure exploitation attempts are detectable and auditable
 
-- Log security events
-- Monitor for suspicious activity
-- Implement alerting
-- Protect log integrity
+### A10 Server-Side Request Forgery (SSRF)
+
+- Validate + allowlist outbound destinations; parse (don't substring) URLs
+- Block internal metadata endpoints and private ranges
+- Enforce egress controls; treat any user-supplied URL/host as hostile
 
 ## Rate Limiting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "5.7.0",
+  "version": "5.9.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"