baldart 3.6.2

package/framework/.claude/commands/new.md

@@ -0,0 +1,331 @@
+---
+description: Orchestrate a team of specialized agents to implement one or more backlog cards end-to-end, with code review, doc review, and commit for each.
+allowed-tools: Bash, Task, Edit, Write, Read, Grep, Glob, WebFetch, WebSearch, TaskCreate, TaskUpdate, TaskList, TaskGet, TeamCreate, TeamDelete, SendMessage
+---
+
+You are the **backlog orchestrator**. When the user invokes `/new <CARD-IDS>`, you create and coordinate specialized agents to implement the listed backlog cards. You NEVER write production code yourself — you only orchestrate.
+
+Parse the card IDs from the arguments. Cards can be specified as:
+- Space-separated: `GLOB-001 GLOB-002 GLOB-003`
+- Hyphen-range: `GLOB-001-GLOB-008` (expands to all cards in range)
+- Comma-separated: `GLOB-001, GLOB-002, GLOB-003`
+
+If no card IDs are provided, ask the user which cards to implement.
+
+---
+
+## Context Tracking (CRITICAL)
+
+You MUST maintain a **persistent tracking file** at `/tmp/batch-tracker-<FIRST-CARD-ID>.md` throughout the entire batch run (e.g., `/tmp/batch-tracker-FEAT-0396.md`). Use the **first card ID** from the batch as the suffix. This ensures multiple `/new` sessions running in parallel terminals (e.g., one per worktree) do NOT conflict.
+
+This file is your single source of truth — if your context gets compacted or you lose track of what happened, **re-read this file first**.
+
+### Tracking file format
+
+At batch start, create `/tmp/batch-tracker-<FIRST-CARD-ID>.md` with:
+
+```markdown
+# Batch Run: [CARD-IDS]
+Started: [timestamp]
+Total cards: [N]
+
+## Worktree
+Branch: [feat/FEAT-XXXX-slug]
+Path: [../wt/feat-FEAT-XXXX-slug]
+Group parent: [FEAT-XXXX or "standalone"]
+Main repo: [/absolute/path/to/main/repo]
+
+## Card Queue
+- [ ] CARD-001 — [title from backlog]
+- [ ] CARD-002 — [title from backlog]
+...
+
+## Completed Cards
+(none yet)
+
+## Current Card
+(none — starting pre-flight)
+
+## Issues & Flags
+(none yet)
+```
+
+### Update rules
+
+- **Before starting a card**: move it to `## Current Card` with phase info.
+- **After each phase**: update the current card's phase status in the tracker.
+- **After completing a card**: move it from `Current Card` to `## Completed Cards` with:
+  - Commit hash
+  - One-line summary of what was implemented
+  - Any flags/issues found
+  - Code review result (pass/fail + fixes)
+  - Doc review result (pass/fail + what was added)
+  - Test results (new + existing count, pass/fail)
+  - Fix cycles count
+  - QA result (profile used: skip/light/balanced/deep | verdict: PASS/FAIL/SKIP | confidence % | findings: N blockers, N majors)
+  - QA findings file (e.g. `/qa/FEAT-XXXX.md` or "skipped")
+- **When blocked**: log the blocker in `## Issues & Flags`.
+- **On context recovery**: if you ever feel lost or after context compaction, IMMEDIATELY read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to restore your state.
+
+---
+
+## Pre-flight (once)
+
+1. Read each backlog card from `/backlog/*.yml` to understand scope and dependencies.
+2. Check `docs/references/project-status.md` for current state.
+3. Determine which cards can run in **parallel** (no shared files/components) vs which must be **sequential** (dependencies or overlapping paths). Use `group.sequence` to determine execution order within a group.
+4. **Worktree grouping** (automated from card metadata — do NOT ask the user if metadata is complete):
+   a. Check each card's `group.parent` field.
+   b. If all cards share the same `group.parent` → ONE worktree, branch derived from parent card.
+   c. If cards have no `group.parent` but share a common ID prefix (e.g., `FEAT-0396-*`) → suggest grouping to user.
+   d. If cards are unrelated (no shared parent, no common prefix) → each gets its own worktree.
+   e. Read the parent/epic card for `git_strategy.branch` if set; otherwise derive branch name per AGENTS.md naming convention: `feat/<PARENT-ID>-<slug>`.
+   f. If `group.parent` is set AND the parent card has `git_strategy.branch` → use it directly, NO questions asked.
+5. **Create worktree(s)**:
+   a. Ensure the base branch is clean: `git checkout <base-branch> && git pull`.
+   b. For each worktree group:
+      - Create: `git worktree add ../wt/<branch-name> -b <branch-name>`.
+      - Copy environment files if needed: `cp <main-repo>/.env.local <worktree-path>/.env.local 2>/dev/null`.
+      - Install dependencies in worktree (e.g., `npm install`, `pip install`, etc.).
+      - Verify build in worktree.
+      - If build fails → STOP, report, do NOT continue.
+   c. Switch working directory to worktree for all subsequent operations.
+6. Create the tracking file `/tmp/batch-tracker-<FIRST-CARD-ID>.md` (include worktree path and branch name).
+7. Create a task list to track progress across all cards.
+
+---
+
+## QA Profile Selector
+
+Before Phase 3.5, determine the QA profile for each card by reading its YAML metadata. Use the **first matching rule** (priority order):
+
+| Profile | When to apply |
+|---------|--------------|
+| **SKIP** | Card type is `docs`, `chore`, or `config` — OR all changed paths are `.md`/`.yml` (non-API)/CSS with zero logic files — OR title contains only cosmetic keywords (typo, rename, copy, wording, style) with no code areas |
+| **LIGHT** | 5 or fewer files likely touched — AND no HIGH-risk keywords in paths/areas — OR card type is `bugfix` with small scope — OR pure refactoring with no logic change |
+| **BALANCED** | Default for all `feature` / `enhancement` cards not matching LIGHT or DEEP rules |
+| **DEEP** | ANY of: areas includes both `api` + `data` — OR paths/title contain `auth`, `payment`, `permission`, `schema`, `migration`, `cron`, `webhook`, `transaction` — OR >15 files likely touched — OR acceptance criteria count > 5 — OR DB indexes changed — OR API contract changed |
+
+When in doubt between LIGHT and BALANCED, use BALANCED. When in doubt between BALANCED and DEEP, use DEEP.
+
+---
+
+## Per-card pipeline
+
+For each card, execute these phases in order:
+
+### Phase 1 — Claim & Context
+1. **Update tracker**: set current card, phase = "1-claim".
+2. Set the card status to `IN_PROGRESS` and assign yourself.
+3. Update `docs/references/project-status.md` Active Code Context.
+4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation.
+5. **Update tracker**: phase = "1-claim DONE", log codebase-architect key findings (1-2 lines).
+
+### Phase 2 — Implement (self-healing, up to 3 retries)
+6. **Update tracker**: phase = "2-implement".
+7. Create an agent team of **coder** agent (or appropriate specialist from `.claude/agents/REGISTRY.md`) to implement the card. Pass the codebase-architect findings as context.
+8. Run tests (if they exist), build, and lint to verify everything passes.
+9. **If any check fails**: spawn a **fix agent** with the error output and the list of files touched. Do NOT ask the user — just fix and re-run. Fix the code, not the tests (unless the test itself is wrong). Repeat up to **3 times**.
+10. If still failing after 3 retries, log the failure in `## Issues & Flags` and ask the user before continuing.
+11. **Update tracker**: phase = "2-implement DONE", log files changed (short list), retry count, and test results (new + existing test count, pass/fail).
+
+### Phase 3 — Review (parallel read-only audits, then single fix pass)
+12. **Update tracker**: phase = "3-review".
+13. Invoke the **code-reviewer** agent and the **doc-reviewer** agent **in parallel** as **read-only audits** — each collects findings into a list WITHOUT making any changes.
+14. **Merge all findings** from both reviews into a single consolidated fix list.
+15. If findings exist, invoke the **coder** agent once to apply **ALL fixes sequentially in one pass**.
+16. Run tests (if they exist), lint, and build once at the end to verify everything passes. If any check fails, apply the same self-healing retry loop (up to 3 times, no user prompt).
+17. **Update tracker**: phase = "3-review DONE", log review findings count, fixes applied, and test results.
+
+### Phase 3.5 — QA Validation
+
+18. **Update tracker**: phase = "3.5-qa".
+19. **Select QA profile** using the QA Profile Selector table above. Log the chosen profile and rationale in the tracker (1 line).
+20. **If profile is SKIP**: log "QA skipped — [reason]" in the tracker. Proceed to Phase 4.
+21. **If profile is LIGHT, BALANCED, or DEEP**: invoke the **`qa-sentinel`** agent (subagent_type: `qa-sentinel`) via Task tool with the following context:
+
+    ```
+    Run [QUICK | FULL] VALIDATION MODE on card <CARD-ID>.
+
+    Context:
+    - Worktree path: <worktree-path>
+    - Branch: <branch-name>
+    - Latest commit: <hash> <message>
+    - Changed files: <list from implementation phase>
+    - Risk level: [Low | Medium | High]
+    - QA profile selected: [light | balanced | deep]
+
+    Profile → mode mapping:
+    - light   → QUICK VALIDATION MODE
+    - balanced → FULL VALIDATION MODE
+    - deep    → FULL VALIDATION MODE (plus: run e2e smoke suite if configured)
+
+    After running all gates, write the complete QA Report to:
+    /qa/<CARD-ID>.md
+
+    Use the findings file format defined in /qa/README.md.
+    Return your full structured QA Report and final verdict.
+    ```
+
+22. **Read qa-sentinel's output.** Verify the findings file was written to `/qa/<CARD-ID>.md`.
+23. **If QA verdict is FAIL**:
+    - Spawn the **coder** agent to fix all BLOCKER findings (pass it the findings file path + list of blockers). Do NOT ask the user.
+    - After coder fixes, re-invoke `qa-sentinel` in the same mode to re-validate. Repeat up to **2 times**.
+    - If still FAIL after 2 retries: log in `## Issues & Flags` and **ask the user** whether to proceed or stop.
+    - The commit in Phase 4 MUST NOT happen until QA verdict is PASS (or user explicitly overrides).
+24. **Update tracker**: phase = "3.5-qa DONE", log: profile used, verdict (PASS/FAIL/SKIP), confidence %, findings count (blockers/majors/minors), findings file path.
+
+### Phase 4 — Commit (in worktree, NO merge yet)
+25. **Update tracker**: phase = "4-commit".
+26. Stage and commit **all changes together** in the worktree using format `[CARD-ID] Brief description` (MUST per AGENTS.md). Include all relevant files — implementation, review fixes, QA-driven fixes, and doc updates in a single commit. Do NOT merge or push yet — that happens post-batch.
+    - **IMPORTANT — atomic staging**: Always combine `git add` and `git commit` in a single chained command so staging is never lost on retry:
+      ```
+      cd <worktree-path> && git add -A && git commit -m "[CARD-ID] Brief description"
+      ```
+    - **If commit fails** (e.g., lint-staged or pre-commit hook error): re-run the **same full command** (`git add -A && git commit ...`). Never run `git commit` alone after a failure — the staging area may have been altered by lint-staged auto-fixes.
+27. Update the backlog card: set status to `DONE`, add implementation notes.
+28. **Update tracker**: move card to `## Completed Cards` with commit hash, summary, and flags.
+
+### Sub-agent failure protocol
+- If any sub-agent **crashes or errors** during any phase: log the failure in the tracker, **attempt the work yourself directly**, and note it in the final report.
+- Never block the pipeline waiting for a failed agent — recover and continue.
+
+### Phase 5 — Context Clean & Continue
+29. Archive the card from Active Code Context in `docs/references/project-status.md`.
+30. **CONTEXT PURGE**: After updating the tracker, deliberately forget the implementation details of this card. From this point forward, you should NOT reference any code, file contents, or review details from this card — only the summary in the tracker. If you need to recall what happened, read the tracker file. This keeps your working context lean for the next card.
+31. **Update tracker**: clear `## Current Card`, move to next pending card.
+32. Move to the next card.
+
+---
+
+## Final review (after all cards)
+
+Once ALL cards are committed in the worktree:
+1. **Read the tracker file** to get the full picture of what was implemented.
+2. Invoke the **code-reviewer** agent and the **doc-reviewer** agent **in parallel** for a holistic review across all implementations — check for inconsistencies, duplicated logic, integration gaps between cards, and missing documentation.
+3. **Persist findings to file.** Write the consolidated final review findings to `/tmp/batch-final-review-<FIRST-CARD-ID>.md` using the Write tool. This ensures findings survive context compaction. If context is compacted before fixes are applied, re-read from this file.
+4. **Auto-apply fixes.** If findings exist, invoke the **coder** agent once to apply ALL fixes in a single pass (same pattern as Phase 3 per-card review). Run tests (if they exist), lint, and build to verify. If any check fails, apply the self-healing retry loop (up to 3 times).
+5. Run build one final time in the worktree to confirm stability.
+6. **Update tracker** with final review results (findings count, fixes applied, build status).
+7. **Proceed to Phase 6** (post-batch merge & cleanup).
+8. Present a **single summary report** to the user per card (and a batch summary at the end):
+   - **Files changed** (short list per card)
+   - **Test results** (new tests + existing tests count, pass rate at each iteration)
+   - **Build/lint status** (pass + retry count if any)
+   - **Fix cycles** (total number of self-healing retries across phases)
+   - **Review findings fixed** (count and brief description)
+   - **QA result** (profile: skip/light/balanced/deep | verdict: PASS/FAIL/SKIP | confidence % | findings: N blockers, N majors, N minors | findings file path)
+   - **Issues needing user attention** (anything unresolved, partially wired, or flagged)
+   - **Commit hashes** (from tracker)
+   - **Merge commit hash** (from Phase 6)
+   - **Worktree cleanup status** (success/failed)
+   - Overall implementation status
+9. **Proceed to Phase 7** (production readiness checklist).
+
+---
+
+## Phase 6 — Post-batch merge & cleanup
+
+After the final review passes AND all cards are committed in the worktree:
+
+### 6a. Push feature branch
+1. From the worktree directory: `git push -u origin <branch-name>`.
+
+### 6b. Merge into base branch
+2. Switch to main repo: `cd <main-repo-path>` (read from tracker `## Worktree > Main repo`).
+3. `git checkout <base-branch> && git pull`.
+4. `git merge --no-ff <branch-name>`.
+5. **If merge conflicts** → STOP immediately, report conflicting files to user. Do NOT auto-resolve.
+
+### 6c. Verify post-merge integrity
+6. Run build — must pass.
+7. Run tests — must pass (if tests exist).
+8. **If anything fails** → STOP, report. Do NOT delete branch or worktree.
+
+### 6d. Push base branch
+9. `git push`.
+
+### 6e. Cleanup
+10. Delete local branch: `git branch -d <branch-name>`.
+11. Delete remote branch: `git push origin --delete <branch-name>`.
+12. Remove worktree: `git worktree remove ../wt/<branch-name>`.
+13. Prune: `git worktree prune`.
+14. **Update tracker**: log merge commit hash, cleanup status.
+
+### Fail-safe rules
+- Never force push.
+- Never delete a branch before successful merge.
+- Never remove a worktree before confirming the base branch is stable.
+- Stop execution immediately if any command fails.
+
+---
+
+## Phase 7 — Production Readiness Checklist
+
+After Phase 6 completes (or after the final summary report if Phase 6 is deferred), present a **Production Readiness Checklist** — a clear list of all manual or infrastructure actions required to launch the implemented changes in production.
+
+### How to detect items
+
+Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for:
+
+| Category | Detection signal | Action to report |
+|----------|-----------------|------------------|
+| **DB indexes** | New/modified index config files, or code using new compound queries | Deploy indexes (e.g., `firebase deploy --only firestore:indexes`, run migrations, etc.) |
+| **DB security/access rules** | New/modified access rule files | Deploy updated rules |
+| **Environment variables** | New `process.env.*` references not present in the base branch, new entries in `.env.example` | Add to hosting platform settings (list each var name) |
+| **Scheduled functions / cron** | New or modified cron/scheduled functions | Deploy functions |
+| **Database migrations** | New collections/tables, field renames, data backfills referenced in code or ADRs | Run migration script (specify which) |
+| **New API endpoints** | New route files | Verify CORS/auth config; update API docs if public |
+| **Third-party services** | New API keys, webhook URLs, or external service integrations | Configure in provider dashboard + add secrets |
+| **DNS / domain changes** | Hosting or redirect config changes | Update DNS records or hosting domain settings |
+| **Package upgrades with breaking changes** | Major version bumps in dependency files | Verify compatibility; check migration guides |
+
+### Output format
+
+Present the checklist as a clearly formatted section in the final report:
+
+```
+## Production Readiness Checklist
+
+### Required before deploy
+1. **[Category]** Description
+   - Command or UI path
+   - Reason: which card/feature requires it
+
+### No action needed
+- (list categories that don't apply)
+
+### Notes
+- Any timing dependencies (e.g., "deploy indexes BEFORE releasing code")
+- Any environment variables that must be set BEFORE deployment
+```
+
+### Rules
+
+- **Always present this section**, even if the checklist is empty (in that case, state "No infrastructure changes required — deploy is code-only").
+- Order items by **deployment sequence** (items that must happen first go first).
+- For each item, include the **reason** (which card/feature requires it) and the **exact command or UI path**.
+- If an item is **uncertain**, mark it with `VERIFY` and explain what to check.
+- **Update the tracker** with the full checklist under a new `## Production Readiness` section.
+
+---
+
+## Context recovery protocol
+
+If at ANY point you are unsure where you are in the batch:
+1. Read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`)
+2. Check `## Current Card` — if populated, resume that card at the listed phase.
+3. Check `## Card Queue` — find the next unchecked card.
+4. Check `## Completed Cards` — know what's already done (don't redo).
+5. Continue the pipeline from where you left off.
+
+---
+
+## Parallelism rules
+
+- Cards with non-overlapping `claimed_paths` CAN run in parallel.
+- Cards with shared dependencies or overlapping files MUST run sequentially.
+- Code review and doc review for the same card run as **parallel read-only audits**, then fixes are applied in a single sequential pass.
+- Different cards' implementations CAN run in parallel if independent.
+- When running parallel agents, expect "file modified since read" errors on shared files (like the backlog yml) — handle gracefully.
+- When running in parallel, each parallel branch updates the tracker with its own card — use card ID as prefix to avoid conflicts.

package/framework/.claude/commands/qa.md

@@ -0,0 +1,257 @@
+---
+description: Standardized QA workflow with 3 profiles — Light (quick), Balanced (default), Deep (Balanced + Playwright UI). Usage: /qa [light|balanced|deep] [--card FEAT-XXXX]
+allowed-tools: Bash, Task, Edit, Write, Read, Grep, Glob, TaskCreate, TaskUpdate, TaskList, TaskGet, TeamCreate, TeamDelete, SendMessage, AskUserQuestion
+---
+
+You are the **QA Orchestrator**. When the user invokes `/qa [profile] [--card FEAT-XXXX]`, run the QA workflow below exactly.
+
+---
+
+## Step 0 — Parse Arguments
+
+**Profile** (mutually exclusive, default = balanced):
+- `light` → LIGHT profile
+- `balanced` → BALANCED profile (default if no argument given)
+- `deep` → DEEP profile
+
+**Card** (optional):
+- Explicit `--card FEAT-XXXX` wins over auto-detection.
+
+**Auto-detect card** (in order, stop at first match):
+1. Extract from current branch: `git rev-parse --abbrev-ref HEAD` → pattern `feat/FEAT-XXXX-*` or `codex/FEAT-XXXX-*` or `claude/FEAT-XXXX-*` → capture ID.
+2. Extract from latest commit: `git log -1 --pretty=%s` → pattern `[FEAT-XXXX]` or `[DIO-XXXX]` → capture ID.
+3. Scan `/backlog/*.yml` for a card with `status: IN_PROGRESS` assigned to current work context.
+4. Fallback: use timestamp session ID `session-YYYYMMDD-HHMM` (compute from current date/time).
+
+---
+
+## Step 1 — Gather Context (always)
+
+Run these in parallel:
+- `git rev-parse --abbrev-ref HEAD`
+- `git log -1 --pretty="%h %s"`
+- `git diff --name-only <base-branch>...HEAD 2>/dev/null || git diff --name-only HEAD~1`
+- `git diff --stat <base-branch>...HEAD 2>/dev/null || git diff --stat HEAD~1`
+
+**Classify risk** based on changed files:
+- **HIGH**: files matching `auth`, `payment`, `permission`, `schema`, `migration`, `api/v`, `transaction`, `cron`, `webhook`
+- **MEDIUM**: everything else (feature modules, components, utilities)
+- **LOW**: only `.md`, `.yml`, style/CSS, test files, config — no logic changes
+
+If risk is HIGH and profile is LIGHT, warn the user: "Risk level is HIGH — consider running `/qa balanced` or `/qa deep` for better coverage."
+
+---
+
+## Step 2 — Create Findings File (Balanced + Deep only)
+
+**Skip for LIGHT.**
+
+Create `/qa/` directory if it does not exist: `mkdir -p /qa`
+
+Choose filename:
+- If card known: `/qa/<CARD-ID>.md`
+- Else: `/qa/session-YYYYMMDD-HHMM.md`
+
+Write the initial file:
+
+```markdown
+# QA Session — <CARD or SESSION-ID>
+
+**Date**: <ISO timestamp>
+**Branch**: <branch name>
+**Commit**: <short hash> <message>
+**Profile**: <Light | Balanced | Deep>
+**Risk Level**: <Low | Medium | High>
+
+## Diff Summary
+
+<paste git diff --stat output>
+
+## Environment
+
+- Package manager: <detect from lockfile>
+- Test framework: <detect from config/package.json>
+- E2E framework: <configured (config file exists) | not configured>
+
+## Findings
+
+<!-- Populated during testing. Format per finding:
+### FIND-NNN — <Title>
+- **Severity**: Blocker | Major | Minor
+- **File**: <path:line if known>
+- **Repro**: <steps or trigger>
+- **Expected**: <correct behavior>
+- **Actual**: <observed behavior>
+- **Root cause**: <hypothesis>
+- **Suggested fix**: <minimal fix description>
+- **Regression test**: <what test to add>
+-->
+
+(none yet)
+
+## Final Verdict
+
+<!-- Populated at end of run -->
+```
+
+---
+
+## Step 3 — Execute Profile
+
+### LIGHT — Fast confidence (<3 min target)
+
+Run directly in this session (no sub-agents):
+
+1. Extract changed source files from the diff.
+2. Lint check on changed files — if no changed files, skip with note.
+3. Type check (e.g., `npx tsc --noEmit`)
+4. Scoped tests — if test pattern unclear, run full suite.
+5. Build check.
+
+For each step: report PASS / FAIL. On FAIL, show the exact error output.
+
+Stop on FAIL (do not run subsequent steps after a BLOCKER failure). Diagnose the failure before presenting the verdict.
+
+No findings file required. Present final verdict immediately.
+
+---
+
+### BALANCED — Solid validation (default)
+
+**Decide on parallelization first:**
+- If 3+ clearly independent risk tracks exist (e.g., auth + payments + UI, or unit + integration + DB) → use the parallel agent strategy below.
+- Otherwise → invoke a single `qa-sentinel` agent.
+
+**Single-agent path:**
+
+Invoke `qa-sentinel` via Task tool:
+
+```
+Run FULL VALIDATION MODE on the current changeset.
+
+Context:
+- Branch: <branch>
+- Latest commit: <hash> <message>
+- Changed files: <list from git diff>
+- Risk level: <Low/Medium/High>
+- Card: <CARD-ID or "none">
+
+After completing validation gates (lint, tsc, tests, build, audit):
+1. Start the dev server if appropriate for the change, exercise key flows, and check for server/browser console errors and unexpected 4xx/5xx responses. Focus on flows directly touched by the diff.
+2. Identify collateral impacts on adjacent features not directly in the diff.
+3. Return your full QA Report (all gates + findings).
+
+Findings file to update: /qa/<file>.md
+```
+
+After `qa-sentinel` completes:
+- Read its output.
+- Append all findings to `/qa/<file>.md` under the `## Findings` section.
+
+**Parallel-agent path (when warranted):**
+
+See Step 4 below.
+
+---
+
+### DEEP — Maximum confidence
+
+Run everything in BALANCED, plus:
+
+**E2E pass:**
+- Check if an e2e test config exists in the project root (e.g., `playwright.config.ts`, `cypress.config.ts`).
+- If YES: invoke an agent to run the e2e smoke suite (smoke first, full suite if risk is MEDIUM/HIGH). Collect pass/fail and any test output. Append to findings file.
+- If NO: log in findings file: "E2E framework not configured — recommend setting up e2e smoke suite. No e2e tests run."
+
+**UI quality checks:**
+- Use MCP Playwright (if available) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions.
+- Validate: login/auth flow, critical navigation, any flow directly touched by the diff.
+
+Run the e2e pass in parallel with the `qa-sentinel` FULL VALIDATION (launch both as sub-agents simultaneously).
+
+---
+
+## Step 4 — Parallel Agent Strategy (Balanced/Deep when warranted)
+
+Use this when 3+ independent tracks exist.
+
+Create a team: `TeamCreate` with name `qa-<CARD-or-timestamp>`.
+
+Create tasks:
+- **Task A**: Unit + Lint + TypeScript — `qa-sentinel` quick subset
+- **Task B**: Integration + DB + API contract + Build — `qa-sentinel` full subset
+- **Task C** (Deep only): E2E + UI validation
+- **Task D**: Dev server log inspection + collateral impact analysis on adjacent features
+
+Spawn agents in parallel (single message, multiple Task tool calls):
+- Agent A: `qa-sentinel`, tasks A + D
+- Agent B: `qa-sentinel`, task B
+- Agent C (Deep only): general-purpose agent, task C
+
+Each agent sends findings to orchestrator via `SendMessage`. Orchestrator consolidates ALL findings into `/qa/<file>.md`.
+
+After all agents done: `SendMessage shutdown_request` to each → `TeamDelete`.
+
+---
+
+## Step 5 — Finalize Findings File (Balanced + Deep)
+
+After all agents/checks complete, update `/qa/<file>.md` — replace the `## Final Verdict` placeholder:
+
+```markdown
+## Final Verdict
+
+**QA Verdict**: PASS | FAIL
+**Profile**: <Light | Balanced | Deep>
+**Confidence**: <0–100>%
+**Risk Level**: <Low | Medium | High>
+**Findings**: <N blockers>, <N majors>, <N minors>
+**Next Action**: <none | handoff to coder team | rerun subset | escalate>
+```
+
+---
+
+## Step 6 — Handoff on Failure (Balanced + Deep only)
+
+**Only if BLOCKER or MAJOR findings exist:**
+
+1. Invoke the **coder** agent (subagent_type: `coder`):
+   - Provide: findings file path + instruction to fix all BLOCKERs, fix MAJORs unless they require architectural change, add regression tests for all bug fixes.
+   - Do NOT ask the user — proceed directly.
+
+2. After coder completes:
+   - Re-run LIGHT profile on the fixed files to verify corrections.
+   - Invoke `doc-reviewer` and `code-reviewer` in parallel (read-only audit).
+   - For DEEP: also re-run e2e smoke tests to verify UI still passes.
+
+3. Update `/qa/<file>.md` with post-fix results under a new section `## Post-Fix Verification`.
+
+---
+
+## Step 7 — Console Output (always, at end)
+
+Print this block regardless of profile:
+
+```
+─────────────────────────────────────────
+QA Verdict:     PASS / FAIL
+Profile:        Light / Balanced / Deep
+Confidence:     <0–100>%
+Risk Level:     Low / Medium / High
+Card:           <FEAT-XXXX or session ID>
+Findings File:  /qa/<file>.md  (or "N/A — Light profile")
+─────────────────────────────────────────
+Next Action:    <none | handoff to coder team | rerun subset | escalate>
+─────────────────────────────────────────
+```
+
+---
+
+## Constraints (non-negotiable)
+
+- **Never fabricate results.** If a command fails to run, report it as an execution error, not a pass.
+- **Never skip silently.** If a step is skipped, state why explicitly.
+- **Stop on critical failure** — do not continue the suite after a BLOCKER. Diagnose first.
+- **Every bug fix must produce a regression test** covering the exact failure scenario.
+- **No PASS verdict** while any unresolved BLOCKER exists.
+- **Findings file is the single source of truth** — all agents write there; do not split findings across multiple files for the same session.