baldart 3.41.0 → 4.0.1

package/framework/.claude/skills/prd/references/api-perf-gate.md

@@ -6,11 +6,34 @@ This gate audits the PRD for performance bottlenecks and cost inefficiencies
 **before** the user sees it, so findings are integrated into the spec — not
 flagged after implementation.
 
+> **Execution model:** This protocol is run by the `api-perf-cost-auditor`
+> agent when invoked at Step 4.5. The `/prd` skill spawns the agent via the
+> Task tool with this file as the gate specification; the agent does NOT
+> execute inline. See `prd-writing-phase.md` § Step 4.5 for the spawn
+> instruction. At the audit phase (audit-phase.md), the same agent re-audits
+> the backlog cards using a narrower card-level scope — that is a distinct run;
+> it MUST read the `## API Performance Gate` section from the state file
+> written by this Step 4.5 run to avoid re-flagging already-resolved items.
+
 ---
 
 ## When to Run
 
-**Gate 5 (Text Scan) runs ALWAYS** on every PRD. It is a fast keyword match.
+**Step 0 — Check Skip Conditions first.** Before running any gate, evaluate
+the skip table below. If a skip condition applies, log the skip reason in the
+state file and stop.
+
+### Skip Conditions
+
+| Card / PRD type | Action |
+|-----------------|--------|
+| Hotfix (single-line bug fix, no data/API touch) | Gate 5 only — skip Gates 1-4 |
+| Purely frontend (no persistence or API changes) | Skip all gates entirely |
+| Documentation-only | Skip all gates entirely |
+| Prototype / spike (throw-away) | Skip all gates entirely |
+
+**Gate 5 (Text Scan) runs on every PRD that passes the skip check.** It is a
+fast keyword match and takes precedence over all other conditions.
 
 **Gates 1-4 run ONLY** when Gate 5 finds matches OR the PRD contains any of:
 - `## API contract changes` section with endpoints
@@ -19,15 +42,16 @@ flagged after implementation.
 - Server-side mutations touching the persistence layer
 - Background jobs, cron, batch operations
 
-If none of the above: log `API Performance Gate: N/A — no API/data surface` in
-state file and skip to "Present and Confirm".
+If Gate 5 finds zero matches AND none of the above sections are present: log
+`API Performance Gate: N/A — no API/data surface` in state file and return
+control to the `/prd` skill (proceed to "Present and Confirm").
 
 **Stack-awareness:** before running Gates 1-4, read `stack.database` and
 `stack.framework` from `baldart.config.yml`. The gate sections below have a
 universal core (works for any stack) PLUS stack-specific addenda that activate
 only when the matching value is set. When `stack.database: ""` (unset), the
-gate degrades to the universal core and logs a recommendation to run `npx
-baldart configure` so future gates pick up the stack-specific rules.
+gate degrades to the universal core and logs a recommendation to run
+`npx baldart configure` so future gates pick up the stack-specific rules.
 
 ---
 
@@ -63,8 +87,10 @@ Scan the PRD text for these keywords. Each match = a finding.
 | postgres / supabase | "JSONB column" + indexed query | Verify GIN index exists | MEDIUM |
 | dynamodb | "filter expression" instead of KeyCondition | Filter scans full partition — pick a GSI instead | HIGH |
 
-**If 0 matches AND no API/data sections**: skip Gates 1-4, proceed to present.
-**If any match**: continue to Gates 1-4.
+**If 0 matches AND no API/data sections**: skip Gates 1-4; this result was
+already handled by the early-exit in the "When to Run" block above — log
+`API Performance Gate: N/A — no API/data surface` in state file and return.
+**If any match OR API/data sections present**: continue to Gates 1-4.
 
 ### Gate 1 — Data Model Review
 
@@ -83,7 +109,7 @@ Stack-specific addenda (activate when matching `stack.database`):
 - [ ] firestore: **Index exemptions** for large text fields → MEDIUM (N+1 index writes per doc write)
 - [ ] mongodb: **Embedded vs referenced** — embedded grows the parent doc; referenced needs $lookup → MEDIUM
 - [ ] postgres/supabase: **JSONB vs typed columns** — JSONB without GIN index = full scan → MEDIUM
-- [ ] supabase: **RLS coverage** — every new table MUST have RLS policies aligned with the auth contract → CRITICAL
+- [ ] supabase: **RLS coverage** — every new table MUST have RLS policies aligned with the auth contract → CRITICAL. **This is a security requirement, not a performance finding.** When triggered: flag the missing policy as CRITICAL in the findings list AND note `→ HANDOFF TO security-reviewer` (do not attempt to write the RLS policy inline). The `/prd` skill MUST route this finding to `security-reviewer` before the PRD is presented to the user; the performance gate records the finding but does not resolve it unilaterally.
 - [ ] dynamodb: **Hot partition** — does the partition key distribute evenly under load? → HIGH
 
 ### Gate 2 — Query & Index Review
@@ -100,7 +126,7 @@ Stack-specific addenda:
 - [ ] firestore: **orderBy + inequality on different fields** requires composite index, max 1 inequality per query (inequality field MUST be last) → HIGH
 - [ ] firestore: **>3 inequality filters on different fields** = index explosion → MEDIUM
 - [ ] firestore: **Full-text search** — not native, needs Algolia/Typesense or array-contains workaround → HIGH
-- [ ] postgres/supabase: **EXPLAIN check** on the slowest query in the PRD — sequential scans on >100k rows → CRITICAL
+- [ ] postgres/supabase: **EXPLAIN check** on the slowest query in the PRD — sequential scans on tables above the project's sequential-scan threshold → CRITICAL. Threshold: read `${paths.references_dir}/perf-budgets.md`; if absent, use >100k rows as the ad-hoc default and emit a `BUDGETS_GAP` warning. [DESIGN-CHOICE: 100k-row fallback chosen as a conservative p95-safe default for OLTP workloads; calibrate via perf-budgets.md for your project]
 - [ ] postgres/supabase: **Covering index** for hot read paths → MEDIUM
 - [ ] mongodb: **Compound index field order** matches query equality → range → sort rule → HIGH
 - [ ] dynamodb: **GSI / LSI definition** for every access pattern that doesn't hit the primary key → CRITICAL
@@ -109,7 +135,7 @@ Stack-specific addenda:
 
 Universal checks:
 
-- [ ] **Payload size**: any endpoint accepting/returning >4.5MB → CRITICAL (use signed URL / multipart upload pattern). Limit varies by deployment (Vercel 4.5MB, Cloudflare Workers 100MB, AWS Lambda 6MB sync) — calibrate to `stack.deployment`.
+- [ ] **Payload size**: any endpoint accepting/returning a payload above the platform limit → CRITICAL (use signed URL / multipart upload pattern). Resolve threshold from `stack.deployment`: Vercel → 4.5 MB, AWS Lambda → 6 MB sync / 256 KB async, Cloudflare Workers → 100 MB, Firebase Functions gen 2 → 32 MB. When `stack.deployment` is unset, use 4.5 MB as a conservative fallback and emit a `BUDGETS_GAP` warning. [DESIGN-CHOICE: 4.5 MB unset-fallback matches the most restrictive common platform (Vercel) to avoid silent over-limit on unknown deployments]
 - [ ] **Sync vs async**: long operations (email, PDF, image processing) in request path → HIGH (use queue / waitUntil / background worker per stack)
 - [ ] **Function duration**: operations that may exceed the platform timeout (Vercel 300s Hobby / 800s Pro; Lambda 900s; Cloudflare Workers 30s CPU) → HIGH
 - [ ] **CPU-intensive ops**: image resize, PDF gen, heavy computation in serverless → MEDIUM (consider dedicated worker / container)
@@ -135,27 +161,115 @@ Check data display and freshness requirements for:
 
 ## Severity Actions
 
-| Severity | Action |
-|----------|--------|
-| CRITICAL | MUST fix in PRD before presenting to user. Add/modify NFR, add edge case, change API design. |
-| HIGH | MUST add as NFR or documented design decision in PRD. User sees it in the spec. |
-| MEDIUM | Add to `Edge cases and failure modes` table in PRD as advisory. |
-| LOW | Log in state file only. No PRD change. |
+> **Taxonomy note:** This gate uses CRITICAL/HIGH/MEDIUM/LOW. When the
+> `api-perf-cost-auditor` agent runs this protocol (as it does at Step 4.5
+> and Step 6), its output schema uses BLOCKER/HIGH/MEDIUM/LOW. Mapping:
+> agent BLOCKER (Priority ≥ 16) = gate CRITICAL; agent HIGH = gate HIGH.
+> The agent's BLOCKER findings MUST be treated as CRITICAL for PRD action
+> purposes. Never present a PRD with an unresolved BLOCKER/CRITICAL finding.
+
+| Severity (gate) | Agent equivalent | Action |
+|-----------------|-----------------|--------|
+| CRITICAL | BLOCKER | MUST fix in PRD before presenting to user. Add/modify NFR, add edge case, change API design. If the fix requires architectural redesign the skill cannot determine unilaterally, **STOP** — see "Unresolvable CRITICAL" procedure below. |
+| HIGH | HIGH | MUST add as NFR or documented design decision in PRD. User sees it in the spec. |
+| MEDIUM | MEDIUM | Add to `Edge cases and failure modes` table in PRD as advisory. |
+| LOW | LOW | Log in state file only. No PRD change. |
+
+### Unresolvable CRITICAL Procedure
+
+When a CRITICAL finding cannot be resolved by editing the PRD (e.g. the PRD
+describes an inherently fan-out write or unbounded read that requires an
+architectural redesign), the skill MUST:
+
+1. Record the finding verbatim in the `## API Performance Gate` section of the
+   state file with status `UNRESOLVED`.
+2. **Do NOT present the PRD to the user without surfacing the blocker.** Instead,
+   surface an explicit blocker message before "Present and Confirm":
+
+```
+PERFORMANCE GATE BLOCKER — unresolvable CRITICAL finding:
+  Finding: <title>
+  Reason it cannot be auto-resolved: <one line>
+  Required action: <what the user must decide / redesign>
+
+The PRD cannot be presented until this is resolved. Please clarify the
+architectural direction so the spec can be updated.
+```
+
+3. Wait for user input. Resume "Present and Confirm" only after the user
+   provides a resolution direction and the PRD is updated accordingly.
 
 ---
 
 ## Execution Procedure
 
-1. Run Gate 5 on the full PRD text.
-2. If matches found OR API/data sections present → run Gates 1-4.
-3. For each finding:
-   - CRITICAL/HIGH: edit the PRD directly (add NFR, modify API contract, add edge case).
-   - MEDIUM: add to edge cases table.
-   - LOW: note in state file.
-4. Update state file: `## API Performance Gate` section with findings count and actions taken.
-5. If any CRITICAL findings were resolved, add a `### Performance-Informed Decisions` subsection
-   to the PRD listing what was changed and why.
-6. Proceed to "Present and Confirm" — the user sees an already-optimized PRD.
+> **Who runs this:** the `api-perf-cost-auditor` agent, spawned by the `/prd`
+> skill at Step 4.5. Steps below are instructions to that agent. The agent
+> MUST complete all steps before returning control to the skill.
+
+**Step 0 — Prior findings check (delta-run guard).**
+Read the `## API Performance Gate` section of the state file. If a prior run
+exists (e.g. `/prd-add` re-triggered this gate):
+- Extract all entries from the `findings[]` array where `status: RESOLVED`.
+- Do NOT re-flag any resolved item unless the PRD delta introduces a new
+  instance of the same pattern (same root cause, different location is a new
+  finding; same location + same root cause = duplicate, skip).
+- Record the prior run's resolved-finding list in your working context as
+  `PRIOR_RESOLVED = [...]` before starting Gate 5.
+
+**Step 1 — Skip-condition check.**
+Evaluate the Skip Conditions table in the "When to Run" section. If a skip
+condition applies, write `API Performance Gate: SKIPPED — <reason>` to the
+state file and return `status: SKIPPED` to the calling skill. Stop here.
+
+**Step 2 — Run Gate 5 on the full PRD text.**
+
+**Step 3 — If Gate 5 finds zero matches AND the PRD has no API/data sections:**
+Write `API Performance Gate: N/A — no API/data surface` to the state file and
+return `status: NA`. Stop here.
+
+**Step 4 — Run Gates 1-4.** Apply stack-specific addenda from `baldart.config.yml`.
+
+**Step 5 — For each finding, apply the Severity Actions table:**
+- CRITICAL: attempt to fix in PRD. If unresolvable → follow "Unresolvable
+  CRITICAL" procedure (STOP and surface to user; do NOT proceed to Present).
+- CRITICAL + security handoff (RLS): record as CRITICAL with
+  `→ HANDOFF TO security-reviewer`; do not attempt to write security policy.
+- HIGH: add as NFR or design decision in PRD.
+- MEDIUM: add to edge cases table.
+- LOW: note in state file.
+
+**Step 6 — Update state file.** Write the machine-readable block below to the
+`## API Performance Gate` section. This is consumed by the audit-phase
+`api-perf-cost-auditor` run (prd/references/audit-phase.md § Step 6) to avoid
+re-flagging already-resolved items when auditing backlog cards:
+
+```
+## API Performance Gate
+run_at: <ISO timestamp>
+status: PASS | PASS_WITH_NOTES | BLOCKER | SKIPPED | NA
+findings_total: N
+findings_by_severity:
+  critical: N  # resolved in PRD (or UNRESOLVED — see below)
+  high: N      # added as NFR
+  medium: N    # added to edge cases
+  low: N       # state file only
+findings:
+  - title: <finding title>
+    severity: CRITICAL | HIGH | MEDIUM | LOW
+    status: RESOLVED | UNRESOLVED | SECURITY_HANDOFF
+    resolution: <one line — what was changed in the PRD, or "" if UNRESOLVED>
+    handoff_to: security-reviewer  # only when status == SECURITY_HANDOFF
+```
+
+**Step 7 — If any CRITICAL findings were resolved:** add a
+`### Performance-Informed Decisions` subsection to the PRD listing what was
+changed and why.
+
+**Step 8 — Return to skill.** Return `status: <value>` from Step 6
+(machine-readable). If `status == BLOCKER`, the skill MUST NOT proceed
+to "Present and Confirm" — the blocker message in the Severity Actions section
+is displayed to the user instead.
 
 ---
 
@@ -169,7 +283,7 @@ informational and should be removed from the populated PRD section.
 
 **Firestore (Blaze Plan):** Reads $0.06/100K, Writes $0.18/100K, Deletes $0.02/100K. Offset pagination charges for ALL skipped docs. Index writes: N+1 per document. Listener: 1 read/matched doc at attach + 1 per change.
 
-**Supabase / Postgres:** Compute + storage + egress billing. Hot row updates serialize on a single page; HOT updates and `FILLFACTOR` matter for write-heavy tables. Sequential scan >100k rows is a HIGH finding regardless of price.
+**Supabase / Postgres:** Compute + storage + egress billing. Hot row updates serialize on a single page; HOT updates and `FILLFACTOR` matter for write-heavy tables. Sequential scans above the project's threshold (see `${paths.references_dir}/perf-budgets.md`; default: >100k rows) are a CRITICAL finding regardless of price (see Gate 2).
 
 **MongoDB Atlas:** Cluster tier dictates IOPS ceiling. Aggregation `$lookup` cost ≈ N queries when uncached. WiredTiger cache hit rate <90% on hot path = HIGH finding.
 
@@ -194,9 +308,5 @@ informational and should be removed from the populated PRD section.
 
 **Astro:** SSG by default; `output: 'server'` enables on-demand rendering; per-route `prerender` toggle.
 
-### When to Skip
-
-- Hotfix cards (single-line bug fixes): Gate 5 only
-- Purely frontend cards (no persistence/API touch): skip entirely
-- Documentation-only: skip entirely
-- Prototype/spike (throw-away): skip entirely
+<!-- Skip conditions have been moved to "When to Run" § Skip Conditions table
+     and Execution Procedure Step 1. Do not add skip logic here. -->

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

@@ -31,13 +31,13 @@ Scan each card for security signals to decide whether the `security-reviewer` ag
 | **Multi-tenant data access** | Requirements mention cross-tenant boundaries (cross-org, cross-workspace, cross-store, cross-account — actual tenant noun from `identity.audience_segments[]`) or data visible to multiple tenants |
 | **Sensitive data handling** | Requirements mention PII, credentials, tokens, secrets, or personal data |
 
-**How to assess**: Read each card's `requirements`, `acceptance_criteria`, `files_likely_touched`, `areas`, `existing_patterns`, `anti_patterns`, `validation_commands`, `error_handling`, and `scope_boundaries` fields. This is a deterministic check — no LLM judgment calls needed.
+**How to assess**: Read each card's `requirements`, `acceptance_criteria`, `files_likely_touched`, `areas`, `existing_patterns`, `anti_patterns`, `validation_commands`, `error_handling`, and `scope_boundaries` fields. This is a **SEMANTIC** check — keyword and path matching on card prose requires interpretation, so it is biased toward RECALL: when a signal is ambiguous, INCLUDE the reviewer rather than skip it. (It is not "deterministic" — a card whose auth change lives in an auth-suggestive `files_likely_touched` path but whose `requirements` omit the trigger keywords can still slip through; prefer the path heuristic over relying on prose keywords alone.)
 
 **Output**: Set internal flag `security_review_needed: true/false`. If ANY card triggers → include `security-reviewer` for ALL cards.
 
 **Transparency**: Inform the user:
-- If triggered: "Security review attivato — rilevate superfici esposte: [list signals]."
-- If not: "Security review non necessario — nessuna superficie esposta rilevata."
+- If triggered: "Security review triggered — exposed surfaces detected: [list signals]."
+- If not: "Security review not required — no exposed surfaces detected."
 
 ## Step 6.3 — Signal Detection: Performance (AUTOMATIC)
 
@@ -59,20 +59,21 @@ Scan each card for performance signals to decide whether the `api-perf-cost-audi
 **Output**: Set internal flag `perf_review_needed: true/false`. If ANY card triggers → include `api-perf-cost-auditor` for ALL cards.
 
 **Transparency**: Inform the user:
-- If triggered: "Performance audit attivato — rilevate superfici con impatto costi/performance: [list signals]."
-- If not: "Performance audit non necessario — nessuna superficie API/data rilevata."
+- If triggered: "Performance audit triggered — surfaces with cost/performance impact detected: [list signals]."
+- If not: "Performance audit not required — no API/data surfaces detected."
 
 ## Step 6.4 — Adjacent Card Retrieval (dependency detection)
 
-> Source: Arora 2023 — LLMs miss 60-70% of implicit dependencies without retrieval. With adjacent context, miss rate drops to ~30%.
+[DESIGN-CHOICE: adjacent card context is retrieved to reduce implicit dependency misses — LLMs processing cards in isolation are likely to miss cross-card file conflicts and ordering constraints not captured in explicit `depends_on` fields]
 
 To detect implicit dependencies, gather adjacent context:
 
 1. For each card being audited, check its `depends_on` field for referenced cards → read those cards.
 2. Read ALL cards in `${paths.backlog_dir}/` that share the same `epic:` or `parent:` field as the audited cards.
 3. Read ALL cards whose `files_likely_touched` overlaps with any audited card's files.
-4. Build a summary for each adjacent card: `{id, title, status, requirements (first 3 lines), files_likely_touched}`.
-5. Include these summaries in each audit agent's task description (Step 6.6) under `## Adjacent Cards`.
+4. **Deduplicate**: merge the results from steps 1-3 into a single set by card ID before building summaries. A card matched by multiple criteria counts once.
+5. Build a summary for each unique adjacent card: `{id, title, status, requirements (first 3 lines), files_likely_touched}`. Cap at 10 adjacent cards per audited card `[CALIBRATION-NEEDED: the cap is a context-budget guard, not an empirically tuned value — validate against prompt-size telemetry on large epics]`; if more are present, prefer `depends_on` references, then same-epic, then file-overlap.
+6. Include these summaries in each audit agent's task description (Step 6.6) under `## Adjacent Cards`.
 
 This enables agents to detect:
 - File conflicts between cards planned for parallel execution
@@ -101,10 +102,12 @@ Use `TeamCreate` with name `check-audit` and description based on the cards bein
 
 Use `TaskCreate` to create one task per audit agent per card:
 
-- For **N cards × M agents**, create **N × M tasks** (excluding Codex plan-audit — see 6.6d).
+- For **N cards × M agent types**, create **N × M tasks** (one task per agent type per card; excluding Codex plan-audit — see 6.6d). In Step 6.6c, ONE teammate agent per type handles all N tasks in its queue — M agents run in parallel, not N×M.
 - Each task subject: `[CARD-ID] <agent-type> audit`
 - Each task description: full card YAML + adjacent card summaries + file paths + PRD path + instructions.
 
+**Claim-lock (atomicity on the N×M fan-out)**: each task carries a `claimed_by` field, empty at creation. Before a teammate processes a task it MUST atomically set `claimed_by: <its name>` via `TaskUpdate` and re-read; if the field is already non-empty and not its own name, it SKIPS that task (another worker owns it). This prevents two workers — for example a re-spawn after a transient failure, or an overlapping re-audit (Step 6.9) — from both processing the same card+agent pair and producing duplicate findings. The teammate workflow (Step 6.6e) embeds the claim step.
+
 **IMPORTANT**: Embed the full card YAML directly in the task description. For source files and PRDs, only provide paths — agents read those themselves.
 
 ### 6.6c. Launch teammate agents in parallel
@@ -119,21 +122,20 @@ For each audit agent type (except plan-auditor), spawn ONE teammate using the `T
 | code-reviewer | `code-reviewer` | `code-reviewer` | Always |
 | doc-reviewer | `doc-reviewer` | `doc-reviewer` | Always |
 | api-perf-cost-auditor | `api-perf-cost-auditor` | `perf-auditor` | `perf_review_needed: true` |
-| security-reviewer | `general-purpose` | `security-reviewer` | `security_review_needed: true` |
-
-**Note**: security-reviewer uses `subagent_type: "general-purpose"` — load its prompt from `.claude/agents/security-reviewer.md`.
+| security-reviewer | `security-reviewer` | `security-reviewer` | `security_review_needed: true` |
 
 Launch ALL applicable teammates in a single message (parallel tool calls).
 
 ### 6.6d. Codex Adversarial Plan Audit (replaces plan-auditor)
 
-> **Why Codex**: Cross-model validation — GPT-5.4 reviews artifacts produced by Claude,
-> providing genuine diversity of perspective. Codex reads files directly from the filesystem.
+> **Why Codex**: Cross-model validation — a non-Anthropic frontier model reviews artifacts produced by Claude,
+> providing genuine diversity of perspective. [DESIGN-CHOICE: adversarial cross-model review catches blind spots that a single model cannot self-detect] Codex reads files directly from the filesystem.
 
 Launch **in parallel** with the teammate agents (6.6c). Use `Bash` with `run_in_background: true` so Claude can launch teammate agents concurrently:
 
 ```bash
-AUDIT_FILE="/tmp/codex-plan-audit-$(date +%Y-%m-%d).md" && \
+SESSION_ID="${SESSION_ID:-$(date +%s%N | md5sum | head -c8)}" && \
+AUDIT_FILE="/tmp/codex-plan-audit-${CARD_ID_SLUG}-${SESSION_ID}.md" && \
 CODEX_SCRIPT="$(ls -d ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)" && \
 [ -z "$CODEX_SCRIPT" ] && echo "CODEX_NOT_FOUND" && exit 1; \
 node "$CODEX_SCRIPT" task --wait "
@@ -223,21 +225,27 @@ Suppress findings where the strongest false-positive argument is convincing.
 " 2>&1 | tee "$AUDIT_FILE"
 ```
 
-**Variable interpolation** (build the command string before execution):
+**Variable interpolation** (build the command string before execution; read all values from the session tracker written at Phase 0 — never guess):
 - `${CARD_PATHS}`: newline-separated list of `- backlog/FEAT-XXXX-*.yml` paths from Step 5
 - `${PRD_PATH}`: the PRD file path from the session state
 - `${ADJACENT_CARD_PATHS}`: newline-separated list from Step 6.4
+- `${CARD_ID_SLUG}`: hyphen-separated list of card IDs being audited (e.g. `FEAT-0042-FEAT-0043`) — written to session tracker at Phase 0
+- `${SESSION_ID}`: unique run identifier written to the session tracker at Phase 0; the bash fallback `$(date +%s%N | md5sum | head -c8)` is a last resort only
 
 **Timeout**: Set `timeout: 300000` (5 minutes) on the Bash call.
 
-**Output handling**: The `tee` in the command persists output to `$AUDIT_FILE` (`/tmp/codex-plan-audit-{YYYY-MM-DD}.md`) as it streams. This ensures findings survive regardless of foreground/background execution or stdout truncation.
-1. Read findings from `/tmp/codex-plan-audit-{YYYY-MM-DD}.md` (always available — written by `tee`).
-2. If the file is empty or missing, fall back to `plan-auditor` subagent.
+**Output handling**: The `tee` in the command persists output to `$AUDIT_FILE` (`/tmp/codex-plan-audit-<CARD-ID-SLUG>-<SESSION-ID>.md`) as it streams. This ensures findings survive regardless of foreground/background execution or stdout truncation.
+1. Read findings from the path stored in `$AUDIT_FILE` (always available — written by `tee`).
+2. If the file is empty or its content is `CODEX_NOT_FOUND`, fall back to `plan-auditor` subagent.
 3. Merge into the consolidated report at Step 6.7 under `### Codex Plan Audit Findings`.
 
 **Fallback**: If Codex is unavailable (not installed, not authenticated, or timeout), fall back to the `plan-auditor` subagent with `subagent_type: "plan-auditor"`. Log the fallback reason in the audit report.
 
-### 6.6d. Teammate prompt template
+**Dedup guard on the fallback spawn (avoid double fan-out).** plan-auditor internally auto-spawns `codebase-architect` (always) and `security-reviewer` (when the cards carry auth/session signals). This audit session may have ALREADY produced those artifacts — `security-reviewer` runs as a first-class teammate whenever `security_review_needed: true` (Step 6.6c). To prevent a redundant second pass, the fallback `plan-auditor` invocation MUST be passed a context note instructing it to REUSE this session's artifacts rather than re-spawn:
+- If `codebase-architect` was already spawned earlier this session (its summary is in the session tracker artifact registry), pass that summary in the prompt and instruct plan-auditor NOT to re-invoke `codebase-architect`.
+- If `security_review_needed: true` (security-reviewer already ran as a teammate), instruct plan-auditor NOT to spawn `security-reviewer`; its security findings are already in the task store and will be merged at Step 6.7. plan-auditor should rely on those rather than running an independent, un-merged second review.
+
+### 6.6e. Teammate prompt template
 
 Each teammate receives this prompt:
 
@@ -255,6 +263,7 @@ Your job is RECALL, not precision — catch everything, filter later.
 1. Call `TaskList` to see your assigned tasks.
 2. For each task (in ID order):
    a. Call `TaskGet` to read the full task description (card YAML + adjacent cards + file paths).
+   a2. **Claim the task**: if `claimed_by` is already set to a name other than yours, SKIP this task (another worker owns it). Otherwise set `claimed_by: <your name>` via `TaskUpdate`, then re-read via `TaskGet` to confirm your claim held; if a different name won the race, SKIP.
    b. Mark task as `in_progress` via `TaskUpdate`.
    c. Read any source files or PRDs referenced in the task (use Read tool).
    d. Perform your audit (see instructions below).
@@ -357,17 +366,22 @@ After challenge pass, rank ALL surviving findings relative to each other by impa
 
 **code-reviewer**: Read existing files in `files_likely_touched` and assess: conflicts with existing patterns? Architectural concerns? Alignment with conventions (per `identity.design_philosophy`, project lint/type-check rules, `identity.language`)? Existing utilities the card should reuse but doesn't mention? Check `## Adjacent Cards` for parallel file modifications.
 
-**doc-reviewer**: Check documentation links, PRD references are valid and aligned, planned changes requiring doc updates not mentioned. Verify `files_likely_touched` includes doc files. Check `areas` completeness. Flag `git_strategy: TBD`. Include Obsidian trigger assessment (section H) in findings -- evaluate whether the planned docs will require KB sync per `.claude/skills/doc-reviewer-support/references/obsidian-integration.md`.
+**doc-reviewer**: Check documentation links, PRD references are valid and aligned, planned changes requiring doc updates not mentioned. Verify `files_likely_touched` includes doc files. Check `areas` completeness. Flag `git_strategy: TBD`. Include Obsidian trigger assessment (section H) in findings — evaluate whether the planned docs will require KB sync. If `.claude/skills/doc-reviewer-support/references/obsidian-integration.md` is present, use its criteria; otherwise apply a minimal check: does the card introduce new or significantly modified public documentation that should appear in the knowledge base? Proceed with a notice if the file is absent.
 
-**api-perf-cost-auditor** (only when `perf_review_needed: true`): Apply the 5-gate protocol from `.claude/agent-memory/senior-researcher/api-perf-cost-audit-protocol.md`. Read referenced source files. Universal checks: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, listener vs polling costs, payload size limits per `stack.deployment`, transaction hotspots. Stack-specific addenda apply per `stack.database` + `stack.framework` (see `framework/.claude/skills/prd/references/api-perf-gate.md`).
+**api-perf-cost-auditor** (only when `perf_review_needed: true`): Apply the 5-gate protocol from `api-perf-gate.md` (see `framework/.claude/skills/prd/references/api-perf-gate.md`). Read referenced source files. Universal checks: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, listener vs polling costs, payload size limits per `stack.deployment`, transaction hotspots. Stack-specific addenda apply per `stack.database` + `stack.framework` (see `framework/.claude/skills/prd/references/api-perf-gate.md`). **Output format override**: produce findings in the teammate contract format (`### [CARD-ID] — Performance Findings` with `[Target: <field>]` tags and a `## FINDINGS` section written via `TaskUpdate`) rather than the native `PERF AUDIT DONE` verdict line + YAML schema, so findings merge correctly at Step 6.7 (symmetric with the `security-reviewer` override below).
 
-**security-reviewer** (only when `security_review_needed: true`): Read `.claude/agents/security-reviewer.md` for full methodology. Focus on: auth gaps, input validation, multi-tenant isolation, persistence-layer access rules alignment (Firestore rules / Supabase RLS / Mongo validator / DynamoDB IAM — per `stack.database`), sensitive data exposure, webhook validation, rate limiting, IDOR risks.
+**security-reviewer** (only when `security_review_needed: true`): Apply the full security-reviewer methodology. Focus on: auth gaps, input validation, multi-tenant isolation, persistence-layer access rules alignment (Firestore rules / Supabase RLS / Mongo validator / DynamoDB IAM — per `stack.database`), sensitive data exposure, webhook validation, rate limiting, IDOR risks. **Output format override**: produce findings in the teammate contract format (`### [CARD-ID] — Security Findings` with `[Target: <field>]` tags and `## FINDINGS` section written via `TaskUpdate`) rather than the native `# Security Review Summary` format, so findings merge correctly at Step 6.7.
 
 ## Step 6.7 — Collect & Merge Findings
 
-Wait for all teammates AND Codex to complete, then:
-1. **Read teammate findings from the task store** (not `SendMessage`). Use `TaskList` to check all tasks are `completed`, then `TaskGet` on each to read the `## FINDINGS` section.
-2. **Read Codex plan audit findings** from `/tmp/codex-plan-audit-{YYYY-MM-DD}.md` (persisted by `tee` in Step 6.6d). If the file is empty or missing, note "Codex audit unavailable — fallback to plan-auditor" and invoke the `plan-auditor` subagent.
+**Fan-in barrier (explicit completion gate — do not read findings before it clears).** The consolidation below MUST NOT begin until BOTH the teammate pool AND the Codex background job have reached a terminal state. Resolve each independently:
+
+- **Teammates**: poll `TaskList` until every task is `completed`. Bound the wait with a window of `[CALIBRATION-NEEDED: per-agent budget; align with the 5-min Codex timeout once teammate-duration telemetry exists]` — as a working default, 10 minutes wall-clock from team launch. On expiry, classify any task still `in_progress`/`pending` as **TIMED_OUT**: proceed fail-open with findings from completed tasks, and record `audit_status: partial` plus the timed-out task IDs in the consolidated report so the omission is visible (never wait indefinitely; never silently drop the gap). Do NOT substitute a generic agent for a hung teammate (AGENTS.md anti-fallback rule).
+- **Codex**: the background Bash job (Step 6.6d) is terminal once `$AUDIT_FILE` is non-empty OR its own `timeout: 300000` elapses. Do not block teammate consolidation on Codex beyond its 5-minute cap.
+
+Once the barrier clears:
+1. **Read teammate findings from the task store** (not `SendMessage`). Use `TaskGet` on each `completed` task to read the `## FINDINGS` section.
+2. **Read Codex plan audit findings** from the path stored as `$AUDIT_FILE` in the session tracker (persisted by `tee` in Step 6.6d; pattern: `/tmp/codex-plan-audit-<CARD-ID-SLUG>-<SESSION-ID>.md`). If the file is absent, empty, or its content is `CODEX_NOT_FOUND`, note "Codex audit unavailable — fallback to plan-auditor" and invoke the `plan-auditor` subagent **with the dedup guard from Step 6.6d** (reuse this session's `codebase-architect` summary and already-merged `security-reviewer` findings instead of re-spawning).
 
 Consolidate into a single report:
 
@@ -376,7 +390,7 @@ Consolidate into a single report:
 
 ## [CARD-ID-1] — Card Title
 
-### Codex Plan Audit Findings (GPT-5.4)
+### Codex Plan Audit Findings (cross-model)
 - [ ] Finding 1...
 
 ### Code Review Findings
@@ -395,14 +409,14 @@ Consolidate into a single report:
 ...
 
 ## Audit Engine Summary
-- Plan audit: Codex GPT-5.4 (cross-model) | Fallback: Claude plan-auditor
+- Plan audit: Codex (cross-model adversarial) | Fallback: Claude plan-auditor
 - Code review: Claude code-reviewer
 - Doc review: Claude doc-reviewer
 - Performance: Claude api-perf-cost-auditor (if triggered)
 - Security: Claude security-reviewer (if triggered)
 ```
 
-**CRITICAL — Persist report to file before proceeding.** Write to `/tmp/check-audit-report-{YYYY-MM-DD}.md` using the Write tool. This ensures findings survive context compaction.
+**CRITICAL — Persist report to file before proceeding.** Write to `/tmp/check-audit-report-<CARD-ID-SLUG>-<SESSION-ID>.md` (using `$CARD_ID_SLUG` and `$SESSION_ID` from the session tracker) using the Write tool. Store the path in the session tracker. This ensures findings survive context compaction.
 
 Present the consolidated report to the user.
 
@@ -414,7 +428,7 @@ Use `SendMessage` with `type: "shutdown_request"` to shut down all teammates, th
 
 **Goal**: Transform each card from "audited" to "implementation-ready" by editing YAML fields directly.
 
-**Read findings from the persisted report file** (`/tmp/check-audit-report-{YYYY-MM-DD}.md`).
+**Read findings from the persisted report file** (path stored in the session tracker as `$REPORT_FILE`; pattern: `/tmp/check-audit-report-<CARD-ID-SLUG>-<SESSION-ID>.md`).
 
 ### Field mapping rules
 
@@ -426,7 +440,7 @@ Use `SendMessage` with `type: "shutdown_request"` to shut down all teammates, th
 | `[Target: files_likely_touched]` | `files_likely_touched` | Append missing path (no duplicates) |
 | `[Target: depends_on]` | `depends_on` | Append missing card ID |
 | `[Target: areas]` | `areas` | Add missing area key/value |
-| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from develop` |
+| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from ${git.trunk_branch}` |
 | `[Target: unknowns]` | `unknowns` | Append new `[U-N] UNKNOWN: ...` entry |
 | `[Target: existing_patterns]` | `existing_patterns` | Append missing pattern reference or fix stale line_range/anchor_text |
 | `[Target: validation_commands]` | `validation_commands` | Append missing verification command |
@@ -468,11 +482,11 @@ For each card:
 
 ## Maintenance Note
 
-> Source: Anthropic "Harness Design for Long-Running Apps" — capability-boundary adaptation principle.
+[DESIGN-CHOICE: each audit component encodes a capability boundary; periodic stress-testing prevents dead scaffolding as model capabilities evolve]
 
-Every component in this audit encodes an assumption about what the model can't do alone. Periodically (every 2-3 months or on major model upgrade), stress-test each component:
+Every component in this audit encodes an assumption about what the model can't do alone. Periodically (every 2-3 months `[CALIBRATION-NEEDED: cadence is a team convention, not validated against model-release frequency]` or on major model upgrade), stress-test each component:
 
 - Remove one component at a time, measure audit quality delta.
-- If delta < 5%, remove permanently.
+- If delta < 5% `[CALIBRATION-NEEDED: removal threshold is a heuristic; validate against a labelled audit-quality benchmark before treating it as a hard cutoff]`, remove permanently.
 - **Current load-bearing assumptions**: challenge pass, adjacent card retrieval, evidence quotes, adversarial evaluator tuning.
 - **Assumptions to re-test**: agent team separation (could single-agent handle N cards?), relative severity ranking (does absolute assignment work with better models?).

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

@@ -12,11 +12,9 @@ and HALT if violated.
 
 ### Rule A — `owner_agent` is mandatory and enum-validated
 
-Every child card MUST declare `owner_agent` with one of the five values:
-
-```
-coder | ui-expert | plan | visual-designer | motion-expert
-```
+Every child card MUST declare `owner_agent` with a value from the **`owner_agent` enum**
+defined in `framework/.claude/agents/REGISTRY.md` (the SSOT for all valid values). Do
+not re-list the enum here — consult REGISTRY.md directly to avoid drift.
 
 There is no implicit default and `claude` is NOT a valid value. Cards with
 missing, empty, placeholder, or non-enum values fail Step 6 (validation-phase)
@@ -119,8 +117,37 @@ Templates: `.claude/skills/prd/assets/epic-template.yml` for the epic,
 Invoke mandatory specialist agents when the feature qualifies:
 
 - **`hyper-gamification-designer`** — MUST invoke if the feature touches B2C rewards,
-  loyalty, engagement, progression, points, referrals, or retention loops. Integrate
-  findings into requirements and risk sections of the PRD.
+  loyalty, engagement, progression, points, referrals, or retention loops.
+
+  Invoke with:
+
+  ```
+  Agent(
+    subagent_type: "hyper-gamification-designer",
+    prompt: """
+      Audit the approved PRD for gamification / retention quality.
+
+      WORKING_DIRECTORY: <$WORKTREE_PATH absolute path>
+      PRD path: <$WORKTREE_PATH>/<prd_path>
+      Feature slug: <slug>
+
+      Review the PRD's requirements, acceptance criteria, and risks for
+      gamification mechanics, reward loop design, progression clarity, and
+      retention risks. Return a structured findings list: each finding has
+      a section reference, severity (HIGH/MEDIUM/LOW), and a concrete
+      recommendation. Do NOT rewrite the PRD — return findings only.
+    """,
+    mode: "bypassPermissions"
+  )
+  ```
+
+  After the agent returns: **present its findings to the user** via
+  `AskUserQuestion` (list each HIGH finding explicitly) and request
+  confirmation before applying any changes to the PRD. Only incorporate
+  findings the user approves. Once the PRD is updated, re-confirm the
+  final PRD state with the user before proceeding to card generation —
+  the Step 4b gate applies to the post-audit PRD, not only the pre-audit version.
+
 - **`api-perf-cost-auditor`** — already executed at Step 4.5 (API Performance Gate)
   if the PRD contained API/data surfaces. Do NOT re-invoke here unless the card
   introduces NEW API patterns not covered in the PRD (e.g., card splits a single
@@ -133,8 +160,8 @@ If neither applies, note "Specialist audits: N/A" in the state file.
 
 Before delegating to `prd-card-writer`, check each logical card boundary:
 
-1. Count expected `files_likely_touched` — flag if **> 12**.
-2. Count expected `acceptance_criteria` — flag if **> 5**.
+1. Count expected `files_likely_touched` — flag if **> 12**. `[CALIBRATION-NEEDED: pre-write advisory threshold; prd-card-writer Rule C (SSOT) uses > 15 as the DEEP-profile trigger and 8 as the per-card atomicity target — these three thresholds serve distinct purposes and are not interchangeable; empirical grounding is missing for all three]`
+2. Count expected `acceptance_criteria` — flag if **> 5**. `[DESIGN-CHOICE: matches Rule C's DEEP trigger for AC count — the advisory here prompts a split before delegation, while Rule C deterministically assigns deep regardless of the user's override choice]`
 
 **If flagged:**
 
@@ -215,8 +242,8 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - Parallel group computation (dependency graph + file-conflict map)
 - `execution_strategy` block on epic parent card
 - State file update with card list and matrices
-- `env_vars` field: per ogni card che introduce/modifica/rimuove env vars (rilevabile da PRD Section 6 o da requirements che menzionano `process.env`, segreti, API keys, feature flags), popola il campo con `action: new|modified|removed`, `scope`, `required`, `note`. Se la card non tocca env vars, scrivi `env_vars: []`.
-- `review_profile` field: deterministic per-card review depth (`skip|light|balanced|deep`) computed via `prd-card-writer.md § Rule C` from the card's own metadata (type, areas, data_fields, db_indexes, AC count, estimated_complexity). This materializes the review decision at authoring time so `/new` reads it instead of re-deriving it. Epics always get `review_profile: skip`. Honor any explicit author override already present in the YAML.
+- `env_vars` field: for every card that introduces/modifies/removes env vars (detectable from PRD Section 6 or requirements that mention `process.env`, secrets, API keys, feature flags), populate the field with `action: new|modified|removed`, `scope`, `required`, `note`. If the card does not touch env vars, write `env_vars: []`.
+- `review_profile` field: deterministic per-card review depth (`skip|light|balanced|deep`). The decision criteria (how each profile is chosen) live ONLY in `prd-card-writer.md § Rule C` — see that file for the criteria. The `/new` orchestrator reads this value from the card and runs an escalation-only detector; it does NOT re-derive from a duplicate criteria table. Epics always get `review_profile: skip`. Honor any explicit author override already present in the YAML.
 
 ### What stays in the main context