baldart 3.6.2

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

@@ -0,0 +1,478 @@
+# Quality Audit Phase (Step 6)
+
+**Precondition:** Backlog cards created (Step 5 complete). Card IDs available from Step 5.
+
+> **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
+
+This phase coordinates parallel audit agents on backlog cards **before development starts** to catch issues early. Each audit agent runs as an independent teammate with its own context window (prevents context saturation).
+
+---
+
+## Step 6.1 — Identify Cards
+
+Use the card IDs produced by Step 5 (prd-card-writer output). No user prompt needed — cards are a mechanical derivation from the approved PRD.
+
+Read each card from `${paths.backlog_dir}/*.yml` to understand scope, requirements, acceptance criteria, and planned changes.
+
+## Step 6.2 — Signal Detection: Security (AUTOMATIC)
+
+Scan each card for security signals to decide whether the `security-reviewer` agent joins the audit.
+
+**Triggered if ANY card meets ONE OR MORE conditions:**
+
+| Signal | Where to look |
+|--------|---------------|
+| **New or modified API route** | `files_likely_touched` contains `route.ts`, `api/`, or requirements mention new endpoints |
+| **Authentication/authorization changes** | Requirements/files mention `withAuth`, `checkPermission`, `permissions`, login, session, token, JWT, OAuth |
+| **Firestore security rules** | `files_likely_touched` contains `firestore.rules` or requirements mention rule changes |
+| **External integrations** | Requirements mention webhooks, third-party APIs, payment, SMS, email providers, or external callbacks |
+| **File upload or media handling** | Requirements mention upload, image, file, media, or `files_likely_touched` contains upload/media paths |
+| **User input processing** | Requirements mention forms, search, filters, or query parameters that flow into DB queries or server logic |
+| **Multi-tenant data access** | Requirements mention cross-store, cross-merchant, 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.
+
+**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."
+
+## Step 6.3 — Signal Detection: Performance (AUTOMATIC)
+
+Scan each card for performance signals to decide whether the `api-perf-cost-auditor` agent joins.
+
+**Triggered if ANY card meets ONE OR MORE conditions:**
+
+| Signal | Where to look |
+|--------|---------------|
+| **New or modified API route** | `files_likely_touched` contains `route.ts`, `api/`, or requirements mention new endpoints |
+| **Firestore read/write operations** | Requirements mention collection, query, document, write, transaction, batch, listener, onSnapshot |
+| **List/search/filter endpoints** | Requirements mention listing, searching, filtering, sorting, pagination, or "show all" |
+| **Background/batch processing** | Requirements mention cron, batch, import, export, bulk, queue, or scheduled tasks |
+| **Real-time/live updates** | Requirements mention real-time, live, auto-update, listener, onSnapshot, subscription |
+| **File upload/download** | Requirements mention upload, download, file, media, image processing, or signed URL |
+| **Caching decisions** | Requirements mention cache, revalidate, freshness, or card lacks caching strategy for read-heavy endpoints |
+| **Cost-sensitive operations** | Requirements mention counters, aggregations, analytics, or denormalization |
+
+**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."
+
+## 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%.
+
+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`.
+
+This enables agents to detect:
+- File conflicts between cards planned for parallel execution
+- Missing `depends_on` entries where Card A modifies a file Card B reads
+- Duplicated requirements across sibling cards
+- Ordering constraints not captured in the dependency graph
+
+## Step 6.5 — Gather Context (lightweight)
+
+Gather **only metadata** to build agent prompts — do NOT read full file contents into your own context:
+
+1. Read the backlog card(s) YAML — store the raw text for each card.
+2. If the card has `files_likely_touched` → note the file paths (do NOT read the files yourself).
+3. If the card has `links.prd` → note the PRD path (do NOT read it yourself).
+4. If the card references parent/child cards → note their paths.
+
+**The audit agents will read files themselves in their own context windows.**
+
+## Step 6.6 — Create Agent Team & Launch Audits
+
+### 6.6a. Create the team
+
+Use `TeamCreate` with name `check-audit` and description based on the cards being reviewed.
+
+### 6.6b. Create tasks
+
+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).
+- Each task subject: `[CARD-ID] <agent-type> audit`
+- Each task description: full card YAML + adjacent card summaries + file paths + PRD path + instructions.
+
+**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
+
+For each audit agent type (except plan-auditor), spawn ONE teammate using the `Task` tool with `team_name: "check-audit"`.
+
+**Agent type mapping:**
+
+| Audit Role | `subagent_type` | Name | Condition |
+|------------|-----------------|------|-----------|
+| ~~plan-auditor~~ | — | — | **Replaced by Codex adversarial audit (Step 6.6d)** |
+| 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`.
+
+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.
+
+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" && \
+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 "
+<task>
+Perform an adversarial plan audit of the following backlog cards as a pre-development quality gate.
+Your job is to find the strongest reasons these cards are NOT ready for implementation.
+Default to skepticism. Assume each card can fail in subtle, high-cost ways.
+Do not give credit for good intent or likely follow-up work.
+
+Cards to audit (read each file):
+${CARD_PATHS}
+
+PRD reference: ${PRD_PATH}
+Data model reference: ${paths.references_dir}/data-model.md
+API reference: ${paths.api_index}
+Adjacent cards context: ${ADJACENT_CARD_PATHS}
+</task>
+
+<attack_surface>
+INVEST criteria violations:
+- Independent: hidden dependencies on in-flight cards not in depends_on
+- Negotiable: requirements too rigid or too vague for implementation
+- Valuable: card does not deliver user-visible or system-critical value
+- Estimable: scope unclear, cannot estimate effort
+- Small: card too large for one dev session
+- Testable: acceptance criteria not binary pass/fail
+
+Requirements smell detection:
+- Ambiguous pronouns without clear antecedent
+- Passive voice hiding the actor
+- Unbounded scope (all, every, any) without limits
+- Missing error/failure paths (happy path only)
+- Implicit ordering assumptions
+- Conflicting constraints
+- Missing units or thresholds
+- Compound requirements covering multiple behaviors
+- Dependency shadows: implicit deps not in depends_on
+
+Firestore-specific (this project uses Firestore):
+- Unbounded reads without .limit()
+- Offset-based pagination instead of cursor-based
+- getDoc() in loops instead of batch reads
+- Missing composite index declarations
+- Transaction hotspot risks
+
+Card structure:
+- files_likely_touched missing entries or conflicting across cards
+- areas field incomplete
+- git_strategy set to TBD
+- acceptance_criteria not binary testable
+- definition_of_done missing items
+- existing_patterns with stale line_range or missing anchor_text
+- validation_commands missing for cards with testable outputs
+- anti_patterns empty for cards modifying shared state
+- scope_boundaries missing for multi-card epics
+- error_handling missing for cards with network calls or user input
+- reuse_analysis missing for cards creating new components
+</attack_surface>
+
+<grounding_rules>
+Every finding MUST quote the exact YAML field or PRD text it references.
+Do not invent issues without evidence from the card files.
+If a conclusion depends on inference, state that explicitly and keep confidence honest.
+Prefer one strong finding over several weak ones. Do not dilute with filler.
+</grounding_rules>
+
+<structured_output_contract>
+For each card return:
+
+### [CARD-ID] — Adversarial Plan Findings
+
+- [ ] **Finding title** — Description. (Severity: HIGH/MEDIUM/LOW) [Target: <field>]
+  > **Evidence:** exact quote from card YAML or PRD
+  > **Source:** file path or field name
+  > **Recommendation:** concrete fix
+
+Target tags: requirements, acceptance_criteria, definition_of_done, files_likely_touched, depends_on, areas, git_strategy, unknowns, notes.
+
+Severity rules:
+- HIGH: data loss, security bypass, breaking change, or unbounded read
+- MEDIUM: missing dep, vague AC, incomplete files_likely_touched
+- LOW: informational only
+
+End with a one-line ship/no-ship assessment per card.
+Suppress findings where the strongest false-positive argument is convincing.
+</structured_output_contract>
+" 2>&1 | tee "$AUDIT_FILE"
+```
+
+**Variable interpolation** (build the command string before execution):
+- `${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
+
+**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.
+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
+
+Each teammate receives this prompt:
+
+```
+## Identity
+
+You are a SKEPTICAL auditor for a pre-development audit team ("check-audit").
+Your default stance is that the card is NOT ready for implementation.
+Do not rationalize away issues. Do not give benefit of the doubt.
+If something COULD be a problem, flag it. The challenge pass (later) will filter false positives.
+Your job is RECALL, not precision — catch everything, filter later.
+
+## Your Workflow
+
+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).
+   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).
+   e. Run the Challenge Pass on your findings (see below).
+   f. Run Severity Calibration on surviving findings (see below).
+   g. **Write findings into the task description** via `TaskUpdate` — append a `## FINDINGS` section.
+   h. Send a brief notification to orchestrator via `SendMessage` (task ID + one-line summary only).
+   i. Mark task as `completed` via `TaskUpdate`.
+3. After all tasks: send "all tasks complete" to orchestrator.
+
+**IMPORTANT**: Always write findings to task description (step g) before notification (step h). Task description is durable; message is just a ping.
+
+## Audit Instructions
+
+{AGENT_SPECIFIC_INSTRUCTIONS}
+
+## Output Format (mandatory evidence quotes)
+
+For each card, return findings as:
+
+### [CARD-ID] — {Agent Role} Findings
+
+- [ ] **Finding title** — Description of the issue, risk, or gap. (Severity: HIGH/MEDIUM/LOW) [Target: <field>]
+  > **Evidence:** "<exact quote from the card YAML, PRD, or source file>"
+  > **Source:** `<file path or field name>`
+
+**MANDATORY**: Every finding MUST include an evidence quote — a direct excerpt that grounds it. Findings without quotable evidence MUST be discarded. State: "Considered but discarded — no quotable evidence found."
+
+If no findings: "No issues found for [CARD-ID]."
+
+### `[Target: <field>]` tag reference (mandatory on every finding)
+
+| Target tag | When to use |
+|---|---|
+| `[Target: requirements]` | Missing or wrong requirement text |
+| `[Target: acceptance_criteria]` | Missing AC, vague AC needing rewrite |
+| `[Target: definition_of_done]` | Missing DoD checkbox |
+| `[Target: files_likely_touched]` | Missing file path |
+| `[Target: depends_on]` | Missing dependency card ID |
+| `[Target: areas]` | Missing area entry (api, docs, data, ui) |
+| `[Target: git_strategy]` | `git_strategy: TBD` or wrong value |
+| `[Target: unknowns]` | Unresolved unknown to surface |
+| `[Target: existing_patterns]` | Missing or stale pattern reference |
+| `[Target: validation_commands]` | Missing verification command |
+| `[Target: anti_patterns]` | Missing DO NOT constraint |
+| `[Target: scope_boundaries]` | Missing scope boundary item |
+| `[Target: input_output_examples]` | Missing or incorrect I/O example |
+| `[Target: error_handling]` | Missing failure mode spec |
+| `[Target: reuse_analysis]` | Missing reuse opportunity or wrong path |
+| `[Target: notes]` | LOW severity only — informational |
+
+## Challenge Pass (mandatory before reporting)
+
+After generating initial findings, challenge EACH one:
+
+"What is the strongest argument that this is a false positive?"
+
+Consider:
+- Is this already handled elsewhere in the codebase?
+- Is this a convention in this project I'm unfamiliar with?
+- Is the card intentionally deferring this to a later card?
+- Am I applying a generic best practice that doesn't fit this context?
+
+**Suppress the finding if the FP argument is convincing.** Record suppressed findings:
+
+<details>
+<summary>Suppressed findings (N items — challenge pass)</summary>
+- **Finding title** — FP argument: <why suppressed>
+</details>
+
+## Severity Calibration (after challenge pass)
+
+After challenge pass, rank ALL surviving findings relative to each other by impact:
+
+1. List all surviving findings in order of impact (most impactful first).
+2. Assign severity based on position:
+   - Top 20% → HIGH (must apply)
+   - Middle 40% → MEDIUM (should apply)
+   - Bottom 40% → LOW (notes only)
+3. Exception: data loss, security bypass, or breaking change = automatically HIGH regardless of position.
+
+### Severity Calibration Examples
+
+**HIGH** (must fix before implementation):
+- "acceptance_criteria says 'user can see bookings' but doesn't specify pagination → unbounded Firestore read"
+  > Evidence: "AC-2: Il merchant visualizza le prenotazioni" — no limit/pagination mentioned
+
+**MEDIUM** (should fix, skip if ambiguous):
+- "files_likely_touched missing the API route doc update"
+  > Evidence: files_likely_touched lists "src/app/api/v1/<domain>/route.ts" but not "${paths.references_dir}/api/<domain>.md"
+
+**LOW** (note only):
+- "Card title could be more descriptive"
+  > Evidence: title is "Booking API" — functional but generic
+```
+
+### Agent-specific instructions
+
+**plan-auditor**: **Handled by Codex adversarial audit (Step 6.6d).** Not included in the teammate agent team. If Codex is unavailable, the fallback plan-auditor uses INVEST criteria, DoR checks, and requirements smell detection — see Step 6.6d attack_surface for the full checklist.
+
+**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`.
+
+**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. Check: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, missing GET Route Handler caching, listener vs polling costs, 4.5MB payload limits, transaction hotspots.
+
+**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, Firestore rules alignment, sensitive data exposure, webhook validation, rate limiting, IDOR risks.
+
+## 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.
+
+Consolidate into a single report:
+
+```
+# Pre-Dev Audit Report — YYYY-MM-DD
+
+## [CARD-ID-1] — Card Title
+
+### Codex Plan Audit Findings (GPT-5.4)
+- [ ] Finding 1...
+
+### Code Review Findings
+- [ ] Finding 1...
+
+### Doc Review Findings
+- [ ] Finding 1...
+
+### Performance Findings (if applicable)
+- [ ] Finding 1...
+
+### Security Findings (if applicable)
+- [ ] Finding 1...
+
+## [CARD-ID-2] — Card Title
+...
+
+## Audit Engine Summary
+- Plan audit: Codex GPT-5.4 (cross-model) | 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.
+
+Present the consolidated report to the user.
+
+## Step 6.8 — Cleanup Team
+
+Use `SendMessage` with `type: "shutdown_request"` to shut down all teammates, then `TeamDelete`.
+
+## Step 6.9 — Apply Findings to Cards
+
+**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`).
+
+### Field mapping rules
+
+| Target tag | Card field | Action |
+|---|---|---|
+| `[Target: requirements]` | `requirements` | Append missing requirement or rewrite existing one |
+| `[Target: acceptance_criteria]` | `acceptance_criteria` | Append new `"[ ] [AC-N] ..."` item or rewrite vague AC |
+| `[Target: definition_of_done]` | `definition_of_done` | Append new `"[ ] ..."` item |
+| `[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: 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 |
+| `[Target: anti_patterns]` | `anti_patterns` | Append missing DO NOT constraint |
+| `[Target: scope_boundaries]` | `scope_boundaries` | Add missing in_scope or out_of_scope item |
+| `[Target: input_output_examples]` | `input_output_examples` | Append missing scenario or fix incorrect example |
+| `[Target: error_handling]` | `error_handling` | Append missing failure mode or fix incorrect action |
+| `[Target: reuse_analysis]` | `reuse_analysis` | Add missing reuse opportunity or correct file path |
+| `[Target: notes]` | `notes` | Audit trail only (Step 6.9c) |
+
+### Severity policy
+
+- **HIGH**: MUST apply. Card cannot be safely implemented without these.
+- **MEDIUM**: SHOULD apply. Skip only if human judgment needed (mark `[MANUAL]`).
+- **LOW**: Do NOT edit structured fields. Audit trail note only.
+
+### Audit trail in `notes`
+
+After applying all edits, append to `notes`:
+
+```yaml
+## Applied by quality audit — YYYY-MM-DD
+Applied N findings to structured fields (H high, M medium).
+Manual review needed: [list [MANUAL] items, or "none"].
+```
+
+### Per-card workflow
+
+For each card:
+1. Read persisted report → collect all findings for this card ID.
+2. Read current card YAML.
+3. Apply HIGH findings first, then MEDIUM, then write audit trail.
+4. Write updated card YAML.
+5. Re-read to verify edits landed correctly.
+
+**Note**: No separate commit here — the validation-phase.md Step 7 handles committing all PRD artifacts together.
+
+---
+
+## Maintenance Note
+
+> Source: Anthropic "Harness Design for Long-Running Apps" — capability-boundary adaptation principle.
+
+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:
+
+- Remove one component at a time, measure audit quality delta.
+- If delta < 5%, 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

@@ -0,0 +1,145 @@
+# Backlog Cards Phase (Step 5)
+
+**Precondition:** PRD specs confirmed by user.
+
+Mark task 4 as `in_progress`.
+
+## MANDATORY Card Structure (zero tolerance — read first)
+
+Every PRD generates **1 epic card + N children**, regardless of N. The
+`prd-card-writer` agent enforces this; the skill MUST verify it post-generation
+and HALT if violated.
+
+- **Epic**: `backlog/FEAT-XXXX-00-<slug>-epic.yml` — tracker only (no code work);
+  contains AC-EPIC, execution_strategy with parallel groups, documentation_impact
+  map.
+- **Children**: `backlog/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M — atomic
+  implementation cards. `group.parent: FEAT-XXXX-00`, `group.sequence: N`.
+
+**Forbidden** (post-write verification: skill MUST `ls backlog/FEAT-XXXX-*.yml`
+and confirm a `-00-...-epic.yml` exists, plus at least one `-NN-` child):
+
+- Flat cards `FEAT-XXXX-<slug>.yml` (no `-NN-` segment).
+- `group.parent` as placeholder string (e.g. `TIPS-EPIC`) instead of the
+  epic's actual `FEAT-XXXX-00` id.
+- Epic missing when N=1.
+
+If the agent returns flat cards: re-invoke with explicit correction prompt. Do
+NOT commit flat cards.
+
+Reference examples: `FEAT-0875-00..08` (Survey Analytics), `FEAT-0876-00..11`
+(Menu TIPS).
+
+Templates: `.claude/skills/prd/assets/epic-template.yml` for the epic,
+`.claude/skills/prd/assets/card-template.yml` for children.
+
+## Specialist Audits (conditional, before cards)
+
+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.
+- **`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
+  endpoint into multiple, or adds a caching layer not in the original design).
+  If re-invoked, scope the audit to card-specific additions only.
+
+If neither applies, note "Specialist audits: N/A" in the state file.
+
+## Complexity Gate (pre-write)
+
+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**.
+
+**If flagged:**
+
+- Warn: `"COMPLEXITY: [scope] has [N] files / [M] ACs — consider splitting by layer (API/UI) or by flow."`
+- **Advisory, not blocking.** User can confirm to proceed. Log override in state file.
+
+**If clean:** proceed silently.
+
+## Card Writing — Delegated to `prd-card-writer` Agent
+
+This phase is delegated to the **`prd-card-writer`** agent (`subagent_type: "prd-card-writer"`)
+to free main context and ensure high-precision card generation under `effort: high`.
+
+**DO NOT use `EnterPlanMode`/`ExitPlanMode`.** This skill manages its own multi-turn
+approval flow. Plan mode risks context loss if the user accidentally accepts
+"clear context and accept plan", destroying the entire skill session.
+
+### Invocation
+
+Launch the agent with all necessary context in the prompt:
+
+```
+Agent(
+  subagent_type: "prd-card-writer",
+  prompt: """
+    Generate backlog cards from the approved PRD.
+
+    PRD path: <prd_path>
+    State file path: <state_file_path>
+    Card template: .claude/skills/prd/assets/card-template.yml
+    Feature slug: <slug>
+
+    The PRD has been approved by the user. Read it in full, read the state file
+    for discovery context, and produce atomic cards following your instructions.
+
+    The card template includes 7 agent-optimization fields (existing_patterns,
+    validation_commands, anti_patterns, scope_boundaries, input_output_examples,
+    error_handling, reuse_analysis). Populate them per your field-mapping instructions.
+    Use Grep/Glob to verify file paths and line numbers for existing_patterns and reuse_analysis.
+
+    Write all card YAML files to backlog/.
+    Update the state file ## Backlog Cards section with card list and traceability matrices.
+    Return the Parallel Execution Map summary.
+  """,
+  mode: "bypassPermissions"
+)
+```
+
+### What the agent handles
+
+The `prd-card-writer` agent owns the entire card writing pipeline:
+- Card atomicity and splitting
+- All required fields per card (27+ fields from template, including 7 agent-optimization fields)
+- business_rationale field (extracted from PRD Section 1b — 2-3 line summary per card)
+- `existing_patterns` with codebase-verified file:line references (requires Grep during card generation)
+- `validation_commands` derived from acceptance criteria and definition_of_done
+- `anti_patterns` extracted from PRD constraints and cross-card scope boundaries
+- `scope_boundaries` with explicit in/out of scope and sibling card references
+- `input_output_examples` from PRD API contracts (Section 5)
+- `error_handling` from PRD failure modes and edge cases (Sections 5, 11)
+- `reuse_analysis` with codebase-verified component references (requires Grep/Glob during generation)
+- FR/NFR traceability matrix
+- ISA traceability matrix (if PRD has section 15)
+- UI Element traceability matrix (if PRD has UI Element Inventory)
+- 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: []`.
+
+### What stays in the main context
+
+- Specialist audit invocations (above) — they may modify the PRD before cards are generated
+- Presenting results to the user (the agent returns summary, main context displays it)
+- Proceeding to Step 6 (validation phase)
+
+## Present and Proceed
+
+Present the plan to the user (traceability matrix + parallel execution map) for
+visibility, then **proceed immediately** — no approval gate needed at this stage.
+The PRD specs were already confirmed in Step 4b; card creation is a mechanical
+derivation from approved specs, so a second approval would be redundant.
+
+Mark task 4 as `completed`. Update state file `## Backlog Cards` with card list.
+
+**MANDATORY: Immediately proceed to Step 6 in the SAME turn.** Read
+[validation-phase.md](validation-phase.md) and execute the quality audit protocol
+from [audit-phase.md](audit-phase.md) with the card IDs. Do NOT display the progress
+bar and stop. Do NOT wait for user input. Do NOT ask the user if they want to skip
+the audit. Just run it.