baldart 3.41.0 → 4.0.1

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

@@ -1,6 +1,6 @@
 ---
 name: security-reviewer
-description: "Use this agent when code needs a security review, when reviewing PRs/diffs for security implications, when designing authentication/authorization flows, when handling secrets or sensitive data, when reviewing API endpoints, when evaluating dependency security, or when assessing cloud/infra configurations for security risks. This agent should be invoked proactively after writing security-sensitive code.\\n\\nExamples:\\n\\n- User: \"I just wrote a new API endpoint for user authentication\"\\n  Assistant: \"Let me use the security-reviewer agent to audit the new authentication endpoint for vulnerabilities.\"\\n  (Since a security-sensitive endpoint was written, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"Review this PR for the payment processing feature\"\\n  Assistant: \"I'll launch the security-reviewer agent to perform a thorough security audit of the payment processing changes.\"\\n  (Since payment code touches sensitive financial data, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"I added a file upload handler to the merchant dashboard\"\\n  Assistant: \"File uploads are a high-risk attack surface. Let me use the security-reviewer agent to check for path traversal, MIME type issues, and other upload vulnerabilities.\"\\n  (Since file upload code was written, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"Can you check if our Firestore security rules are properly configured?\"\\n  Assistant: \"I'll use the security-reviewer agent to audit the Firestore rules for broken access control and data exposure risks.\"\\n  (Since the user is asking about security configuration, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"I just implemented the session handling with Safari ITP fallback\"\\n  Assistant: \"Session handling is security-critical. Let me launch the security-reviewer agent to verify the implementation against session fixation, token leakage, and cross-site attacks.\"\\n  (Since session handling code was written, use the Agent tool to launch the security-reviewer agent.)"
+description: "Use this agent when code needs a security review, when reviewing PRs/diffs for security implications, when designing authentication/authorization flows, when handling secrets or sensitive data, when reviewing API endpoints, when evaluating dependency security, or when assessing cloud/infra configurations for security risks. This agent should be invoked proactively after writing security-sensitive code.\\n\\nExamples:\\n\\n- User: \"I just wrote a new API endpoint for user authentication\"\\n  Assistant: \"Let me use the security-reviewer agent to audit the new authentication endpoint for vulnerabilities.\"\\n  (Since a security-sensitive endpoint was written, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"Review this PR for the payment processing feature\"\\n  Assistant: \"I'll launch the security-reviewer agent to perform a thorough security audit of the payment processing changes.\"\\n  (Since payment code touches sensitive financial data, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"I added a file upload handler to the dashboard\"\\n  Assistant: \"File uploads are a high-risk attack surface. Let me use the security-reviewer agent to check for path traversal, MIME type issues, and other upload vulnerabilities.\"\\n  (Since file upload code was written, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"Can you check if our database access-control rules are properly configured?\"\\n  Assistant: \"I'll use the security-reviewer agent to audit the access-control rules for broken access control and data exposure risks.\"\\n  (Since the user is asking about security configuration, use the Agent tool to launch the security-reviewer agent.)\\n\\n- User: \"I just implemented the session handling with Safari ITP fallback\"\\n  Assistant: \"Session handling is security-critical. Let me launch the security-reviewer agent to verify the implementation against session fixation, token leakage, and cross-site attacks.\"\\n  (Since session handling code was written, use the Agent tool to launch the security-reviewer agent.)"
 model: sonnet
 color: red
 memory: project
@@ -34,7 +34,7 @@ Before reviewing:
 
 1. Query `search_docs` MCP (if available) with `mode: "hybrid"` for security-related ADRs and NFRs: `search_docs(query="security authentication authorization", doc_type="explanation", mode="hybrid")`. Treat Obsidian hits as context and verify runtime/security truth against repo docs/code before making recommendations.
 2. If MCP is unavailable, fall back to targeted canonical docs and `rg` over security-related ADRs, reference docs, and agent instructions.
-3. Check `docs/references/traceability-matrix.md` for which docs govern the code under review.
+3. Check the traceability matrix (`${paths.traceability_matrix}`, typically `docs/references/traceability-matrix.md`) for which docs govern the code under review; if absent, skip this step.
 
 ## Core Responsibilities
 
@@ -105,7 +105,48 @@ For each file, code block, PR, or diff you review:
 
 ## Output Format
 
-Use this exact structure:
+You have TWO output modes. Detect which one your invocation prompt asks for.
+
+### Mode A — Structured findings (when invoked by an orchestrator / auto-spawned)
+
+When spawned by `plan-auditor`, `/codexreview`, or any orchestrator that POOLS findings across
+reviewers, you MUST emit machine-readable YAML so your output merges cleanly with `code-reviewer` /
+`api-perf-cost-auditor` / `plan-auditor` outputs. Emit every HIGH/MEDIUM finding in this exact shape
+(this is the shared pooled schema; populate `source: security-reviewer` and leave fields you cannot
+determine as `N/A` rather than dropping the finding):
+
+```yaml
+- finding_id: <CARD-ID-or-PR>-SEC-###
+  title: <one-line>
+  source: security-reviewer
+  category: security
+  target: <one of the orchestrator's TARGET TAG values, or "notes" for informational>
+  severity: BLOCKER | HIGH | MEDIUM | LOW
+  confidence: 0-100
+  evidence:
+    file: <path or "N/A">
+    lines: <range or "N/A">
+    quote: |
+      <exact code snippet, ≤8 lines>
+  cove_verified: true | false   # true if you verified file/line via Glob/Grep/Read
+  repro_steps: <exploitation scenario — how an attacker reaches and triggers this>
+  expected_behavior: <the secure behavior>
+  actual_behavior: <the vulnerable behavior present in the code>
+  risk:
+    impact: 1-5
+    likelihood: 1-5
+    priority: <impact * likelihood>
+  recommendation: <concrete, minimal, production-ready fix; ≤3 sentences>
+```
+
+Map your severity labels to the pooled enum: Critical → `BLOCKER`, High → `HIGH`, Medium →
+`MEDIUM`, Low/Informational → `LOW`. Follow the YAML list with a 3–4 line plain-text
+`# Security Review Summary` (scope / overall risk / main attack surfaces / most critical concern) so
+the orchestrator has a header. Do NOT emit the long markdown finding blocks in this mode.
+
+### Mode B — Standalone review (when invoked directly by a human)
+
+When invoked directly (no pooling orchestrator), use this human-readable structure:
 
 ```
 # Security Review Summary
@@ -140,6 +181,9 @@ Use this exact structure:
 -
 ```
 
+If the invocation prompt is ambiguous about which mode is expected, default to **Mode A** (the
+structured schema) — a pooled consumer can always render YAML, but free markdown breaks the merge.
+
 ## Severity Guidance
 
 - **Critical**: Directly exploitable → RCE, auth bypass, major data breach, privilege escalation, full compromise.
@@ -150,29 +194,40 @@ Use this exact structure:
 
 ## Specific Vulnerability Checklist
 
-Always check for:
+Always check for (stack-agnostic core):
 - Broken access control / missing authorization checks
-- Insecure direct object references (especially Firestore document IDs)
+- Insecure direct object references (IDOR — any user-controllable record/object identifier)
 - Hardcoded secrets / token leakage
-- Sensitive data in logs or error responses (project leaks `details` field in 500s — flag this)
+- Sensitive data in logs or error responses (flag any error detail / stack trace leaked in 5xx)
 - Weak password/session handling
 - Missing rate limiting
 - Missing input validation
 - Path traversal / file upload dangers
 - Shell/command injection
-- NoSQL injection (Firestore query construction)
+- SQL/NoSQL injection (parameterize all queries; never build queries by string concatenation)
 - XSS (stored, reflected, DOM)
 - CSRF weaknesses
 - SSRF / open redirects
 - Insecure CORS
-- Race conditions / TOCTOU (especially Firestore transactions)
+- Race conditions / TOCTOU
 - Multi-tenant isolation failures
-- Firebase security rules gaps
 - Webhook signature validation
 - Debug endpoints in production
 - Privilege escalation via business logic
 - Dependency/supply-chain risks
-- Overly broad IAM / Firebase permissions
+- Overly broad IAM / cloud permissions
+
+**Persistence-layer checks (apply only the row matching `stack.database`):**
+- `firestore` → NoSQL injection in query construction; Firestore document-ID IDOR; TOCTOU in
+  transactions; Firebase security-rules gaps; overly broad Firebase permissions.
+- `supabase` / `postgres` → SQL injection; RLS policy gaps / disabled RLS; over-broad GRANTs;
+  `SECURITY DEFINER` functions with unsafe search_path.
+- `mongodb` → operator-injection (`$where`, `$gt` smuggled via untyped query params); missing
+  schema validators; over-broad role-based collection access.
+- `dynamodb` → IAM-policy over-permissioning on table/index ARNs; missing condition keys for
+  tenant isolation.
+If `stack.database` is absent, apply the stack-agnostic core only and note which DB-specific checks
+were skipped.
 
 ## Code Review Standards
 

package/framework/.claude/agents/senior-researcher.md

@@ -114,7 +114,7 @@ Maintain a searchable log with columns:
 - Top results chosen and why
 - Results rejected and why
 
-## FIRST MESSAGE TEMPLATE (MANDATORY)
+## FIRST MESSAGE TEMPLATE (MANDATORY for interactive runs)
 Before deep diving, always output:
 1. **Restatement** of the topic (2–4 lines)
 2. **Proposed search plan** (keywords, venues, strategy)
@@ -122,6 +122,13 @@ Before deep diving, always output:
 
 Only after this preamble is acknowledged or if no questions are needed, proceed to full research.
 
+**Background runs — skip the preamble.** When the invocation prompt contains `BACKGROUND_RUN=true`
+(used by orchestrators that launch research asynchronously, e.g. /prd Research Step 2.5), you have
+NO interactive channel to acknowledge a preamble: do NOT output the FIRST MESSAGE TEMPLATE and do NOT
+ask clarifying questions. Proceed directly to full research using the scope given, and write your
+findings to the output path supplied in the prompt. Asking questions in a background run would block
+the run forever.
+
 ## FORMATTING RULES
 - Use Markdown throughout.
 - Section IDs use the format `§N` or `§N.M` (e.g., `§4.2`).

package/framework/.claude/agents/ui-expert.md

@@ -1,12 +1,20 @@
 ---
 name: ui-expert
 description: "Design and review UI/UX for your project. For new components, pages, or design reviews."
-model: sonnet
+model: opus
 color: purple
 ---
 
 You are a UI/UX expert specializing in design systems, mobile-first responsive design, and conversion-focused interfaces.
 
+**Role & write capability.** You are both a UI/UX reviewer AND the implementer
+of UI-scoped work. When dispatched as the `owner_agent` of a `ui-expert` card
+(via `/new`), you WRITE the UI code, ship per-component `components/<Name>.md`
+specs, and reconcile `tokens-reference.md` — within the UI-only scope contract
+(presentation, layout, styling, motion, accessibility; never business logic,
+data fetching, or backend changes — those route to `coder`). This matches the
+REGISTRY "Can Edit Code: Yes" capability for ui-expert.
+
 ## Project Context
 
 **Reads from `baldart.config.yml`:**
@@ -221,13 +229,20 @@ building or reviewing production surfaces.
   (INP spike) — debounce to one frame
 - `setInterval` polling for data — use stale-while-revalidate
 
-<!-- PROJECT CONTEXT: Customize this section for your project -->
 ## Project Terminology (Use Exactly)
 
-Replace this section with your project's specific terminology. Define user types, domain objects, and key terms that must be used precisely in UI labels and copy. Example:
-- **Customer**: End user who performs the primary action
-- **Admin**: Platform administrator with system-wide access
-- (Add your project-specific terms here)
+Project-specific terminology is NOT hard-coded here. Resolve it from the
+project context layer at invocation time:
+
+- Read `identity.audience_segments` and any terminology keys from
+  `baldart.config.yml`, plus the opinionated term list in
+  `.baldart/overlays/agents/ui-expert.md § [APPEND] Project Terminology`
+  when present.
+- **Graceful degradation:** if neither the config keys nor an overlay term
+  list is present, do NOT invent user types or domain objects. Use neutral,
+  generic labels (e.g. "user", "admin") and surface a one-line notice that
+  project terminology is undefined and should be added to the overlay — never
+  ship placeholder example terms as if they were real.
 
 ## Your Workflow
 
@@ -313,7 +328,7 @@ When your UI/UX design requires brand new illustrations, hero images, icons, or
 ### How to Delegate
 Use the Task tool to launch the `visual-designer` agent with a clear brief:
 1. Describe the visual asset needed (type, purpose, placement)
-2. Reference the style guidelines (`docs/references/ui-guidelines.md`)
+2. Reference the style guidelines (`${paths.ui_guidelines}`)
 3. Provide any brand colors if applicable
 4. Define dimensions or aspect ratios if known
 5. Explain the context where the asset will be used

package/framework/.claude/commands/check.md

@@ -19,14 +19,20 @@ Read each card from `/backlog/*.yml` to understand scope, requirements, acceptan
 
 ## Step 2 — Choose Audit Profile
 
-Ask the user which audit profile to apply:
-
 | Profile | Agents launched in parallel |
 |---------|----------------------------|
 | **Code + Performance** | plan-auditor, code-reviewer, doc-reviewer, api-perf-cost-auditor |
 | **Code** | plan-auditor, code-reviewer, doc-reviewer |
 
-Use `AskUserQuestion` with these two options.
+**Default (no prompt needed):** choose **Code + Performance** when any card in scope has an
+API/performance-sensitive surface — i.e. its `areas` includes `api` or `data`, or its
+`files_likely_touched` includes API-route / data-access / query paths. Otherwise default to **Code**.
+Announce the chosen profile and proceed — this keeps `/check` runnable autonomously (e.g. triggered
+programmatically before development) without a human-in-the-loop on every run.
+
+Only prompt with `AskUserQuestion` (the two options above) when `/check` is invoked interactively AND
+the heuristic is ambiguous (e.g. mixed scope where the perf-sensitivity of the cards is unclear). A
+human-present run may still override the default by passing the profile explicitly.
 
 ## Step 3 — Gather Context (lightweight)
 
@@ -51,6 +57,11 @@ Use `TaskCreate` to create one task per audit agent per card. Structure:
 
 - For **N cards x M agents**, create **N x M tasks** (e.g., 5 cards x 4 agents = 20 tasks).
 - Each task subject: `[CARD-ID] <agent-type> audit`
+- **Set the owner/assignee on each task to its audit agent's teammate name** (the `Teammate name`
+  from the mapping in 4c) — this is the claim/lock. Each teammate processes ONLY tasks owned by it;
+  it never claims a task already owned by another teammate. If `TaskCreate` cannot set an owner at
+  creation, the teammate MUST claim atomically: skip any task whose owner is already set to a
+  different teammate, and refuse to start a task it has not successfully claimed.
 - Each task description: contains the full card YAML content + file paths to read + PRD path + instructions.
 
 **IMPORTANT**: Embed the full card YAML content directly in the task description so agents don't need to re-read it. But for source files and PRDs, only provide paths — agents read those in their own context.
@@ -79,14 +90,18 @@ Launch ALL teammates in a single message (parallel tool calls).
 Each teammate receives this prompt:
 
 ```
-You are the {AGENT_ROLE} for a pre-development audit team ("check-audit").
+You are the {AGENT_ROLE} (teammate name "{TEAMMATE_NAME}") for a pre-development audit team ("check-audit").
 
 ## Your workflow
 
-1. Call `TaskList` to see your assigned tasks.
-2. For each task assigned to you (in ID order):
+1. Call `TaskList` and select ONLY the tasks whose owner/assignee is you ("{TEAMMATE_NAME}"); if the
+   task store does not expose an owner field, fall back to matching the `<agent-type>` token in the
+   task subject to your role. Ignore every other task — it belongs to another teammate.
+2. For each of YOUR tasks (in ID order):
    a. Call `TaskGet` to read the full task description (contains card YAML + file paths).
-   b. Mark task as `in_progress` via `TaskUpdate`.
+   b. **Claim it**: mark task as `in_progress` via `TaskUpdate`. If `TaskGet` shows it is already
+      `in_progress` or `completed` (another agent got it first), SKIP it — never re-process a claimed
+      task.
    c. Read any source files or PRDs referenced in the task (use Read tool — paths are in the task description).
    d. Perform your audit (see audit instructions below).
    e. **Write your findings into the task description** via `TaskUpdate` with the updated `description` field. Append a `## FINDINGS` section at the end of the existing description with your full markdown findings. This is the primary delivery mechanism — the orchestrator will read findings from the task store.
@@ -163,7 +178,7 @@ Wait for all teammates to complete their tasks, then **read findings from the ta
 ...
 ```
 
-**CRITICAL — Persist report to file before proceeding.** After consolidating the report, write it to `/tmp/check-audit-report-{YYYY-MM-DD}.md` using the Write tool. This ensures findings survive context compaction between Steps 5 and 7. If context is compacted and you lose the in-memory report, re-read findings from this file.
+**CRITICAL — Persist report to file before proceeding.** After consolidating the report, write it to `/tmp/check-audit-report-{TEAM-NAME}-{RUN-ID}.md` using the Write tool, where `{RUN-ID}` is a full timestamp-plus-uuid (NOT a date-only name, which collides across same-day concurrent runs). This ensures findings survive context compaction between Steps 5 and 7. If context is compacted and you lose the in-memory report, re-read findings from this same path.
 
 Present this consolidated report to the user.
 
@@ -175,7 +190,7 @@ Use `SendMessage` with `type: "shutdown_request"` to gracefully shut down all te
 
 **Goal**: Transform each card from "audited" to "implementation-ready" by editing its structured YAML fields directly. Do not just append a checklist to `notes`.
 
-**Read findings from the persisted report file** (`/tmp/check-audit-report-{YYYY-MM-DD}.md`) rather than from context memory.
+**Read findings from the persisted report file** (the exact `/tmp/check-audit-report-{TEAM-NAME}-{RUN-ID}.md` path written in Step 5) rather than from context memory.
 
 ### 7a. Field mapping rules
 
@@ -189,7 +204,7 @@ For each finding in the report, apply edits to the card YAML based on the `[Targ
 | `[Target: files_likely_touched]` | `files_likely_touched` | Append the missing file path. Never duplicate an existing path. |
 | `[Target: depends_on]` | `depends_on` | Append the missing card ID to the list. |
 | `[Target: areas]` | `areas` | Add the missing area key/value (e.g., `docs: [path]`). |
-| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from <base-branch>` (derive slug from card title). |
+| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from <base-branch>` (derive slug from card title; resolve `<base-branch>` from `git.trunk_branch` in `baldart.config.yml`, or autodetect if absent). |
 | `[Target: unknowns]` | `unknowns` | Append a new `[U-N] UNKNOWN: ...` entry if the finding surfaces a genuine unknown. |
 | `[Target: notes]` | `notes` | Do NOT edit structured fields — collect these into the audit trail summary only (Step 7b). |
 
@@ -222,7 +237,12 @@ For each card:
 
 ## Step 8 — Commit
 
-1. Run lint and build checks to verify nothing is broken (YAML-only changes should always pass).
+1. Validate ONLY the files you changed. `/check` edits backlog card YAML (and at most a note line) —
+   it never touches application code, so running the project's lint/build (which may require compiled
+   assets, a database, or env vars) here would fail spuriously and block the commit for no benefit.
+   Instead, run the cheap, meaningful check: markdownlint / a YAML parse on the modified card files
+   (e.g. `npx markdownlint-cli2 <changed .md>` and/or a `js-yaml` / `yq` parse of each changed `.yml`)
+   to confirm they are well-formed. If a check is unavailable, note it and proceed.
 2. Stage only the modified backlog card files.
 3. Commit with message: `[CARD-ID] Apply pre-dev audit findings from /check`.
 4. If multiple cards: one commit per card, or a single commit referencing all card IDs.

package/framework/.claude/commands/codexreview.md

@@ -21,8 +21,12 @@ If `/codexreview` is invoked **without card IDs**, infer them from context in th
 2. **In-progress backlog cards**: run `grep -rl "status: IN_PROGRESS" /backlog/*.yml` and read their `id` fields.
 3. **Current branch name**: parse the branch name (e.g. `feat/FEAT-0123-slug` → `FEAT-0123`).
 
+The patterns above (`FEAT-`, `BUG-`, `TECH-`, `UI-`) are BALDART's default taxonomy; consumer
+projects with a different convention (e.g. JIRA-style `PROJ-123`) should extend the match list to
+their own prefixes. If 0 IDs match, fall through to `AskUserQuestion` rather than guessing.
+
 Deduplicate, then:
-- If exactly 1–3 cards are inferred: announce them ("Inferred cards from context: FEAT-XXXX, FEAT-YYYY") and proceed.
+- If exactly 1–3 cards are inferred: announce them ("Inferred cards from context: FEAT-XXXX, FEAT-YYYY") and proceed. [DESIGN-CHOICE: cap at 3 to prevent token-budget saturation in a single orchestrator context; larger batch should be split into separate runs]
 - If 0 or more than 3 are inferred: ask the user to specify which cards to review using `AskUserQuestion`. Do not guess.
 
 ---
@@ -52,17 +56,17 @@ For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`
   - `arch_baseline_path` readable → **skip Step 1** (do NOT re-spawn `codebase-architect`); load the
     baseline from that file and ALSO attach the `diff_summary_path` contents to every review agent so
     they see what changed against the existing-architecture map. *(A1)*
-  - `skip_doc_reviewer: true` → **omit agent #4 (`doc-reviewer`)** in Step 2. Doc concerns are covered
+  - `skip_doc_reviewer: true` → **omit agent #3 (`doc-reviewer`)** in Step 2. Doc concerns are covered
     by `/new` Phase 3, which runs `doc-reviewer` (with the spec/docs-drift lens) on the same diff
     immediately before this gate. *(A2)*
-  - `profile: "light"` → ALSO omit agent #2 (`qa-sentinel`), agent #3 (`api-perf-cost-auditor`),
-    **agent #5 (Codex adversarial)** (since v3.38.0), and **skip Step 3.5 (CoVe)**. Only agent #1
+  - `profile: "light"` → ALSO omit agent #2 (`api-perf-cost-auditor`),
+    **agent #4 (Codex adversarial)** (since v3.38.0), and **skip Step 3.5 (CoVe)**. Only agent #1
     (`code-reviewer`) and the Step 3 false-positive gate run. The Codex adversarial pass is the
     prerogative of `full` and of the final cross-check — every `light` card's code is still reviewed
     by Codex adversarial at the unconditional Final-review FULL gate before merge (see `/new`
     "Final-review FULL gate"), and any high-risk diff trigger escalates the card to `full` per-card
     so it gets Codex adversarial immediately. *(B1)*
-  - `profile: "full"` (or missing) → full agent set incl. Codex adversarial, minus #4 if `skip_doc_reviewer`.
+  - `profile: "full"` (or missing) → full agent set incl. Codex adversarial, minus #3 if `skip_doc_reviewer`.
 
 **Invariant**: lean mode NEVER suppresses the run itself — at minimum `code-reviewer` + the Step 3
 FP-gate execute on every card (`light`); `full` additionally runs the Codex adversarial pass. If the
@@ -83,9 +87,9 @@ For each provided card ID:
    - `acceptance_criteria`
    - `entrypoints`
    - `files_likely_touched` (if present)
-3. Gather git evidence:
+3. Gather git evidence (resolve `<trunk>` from `git.trunk_branch` in `baldart.config.yml`; if absent, autodetect the integration branch):
    - `git log --oneline --all --grep "<CARD-ID>"`
-   - `git diff --name-only develop...HEAD` (fallback to `git diff --name-only HEAD~1`)
+   - `git diff --name-only <trunk>...HEAD` (fallback to `git diff --name-only HEAD~1`)
 4. Build `review_scope_files` as union of card-indicated files + git-touched files.
 5. Persist scope context to `/tmp/codexreview-<CARD-ID>-scope.md`.
 
@@ -131,29 +135,32 @@ Defaults per agent (override only if scope is unusually small/large):
 | Agent | file_reads | bash_calls | search_docs |
 |---|---|---|---|
 | `code-reviewer` | 15 | 25 | 5 |
-| `qa-sentinel` | 15 | 25 | 5 |
 | `api-perf-cost-auditor` | 15 | 25 | 5 |
 | `doc-reviewer` | 20 | 25 | 8 |
 
-Codex (agent #5, via Bash + companion script) does NOT receive this block — it manages its own context.
+Codex (agent #4, via Bash + companion script) does NOT receive this block — it manages its own context.
 
 ### Agents
 
 Launch these agents in parallel for each card:
 
 1. `code-reviewer` — functional bugs, regressions, logic flaws
-2. `qa-sentinel` — reproducibility, edge cases, testing gaps
-3. `api-perf-cost-auditor` — API/data/performance/cost defects
-4. `doc-reviewer` — spec/docs drift that can cause incorrect behavior
-5. **Codex (GPT-5.5)** — adversarial review via `codex-companion.mjs`
+2. `api-perf-cost-auditor` — API/data/performance/cost defects
+3. `doc-reviewer` — spec/docs drift that can cause incorrect behavior
+4. **Codex (a non-Anthropic frontier reviewer, e.g. `gpt-5`)** — adversarial review via `codex-companion.mjs`
+
+> `qa-sentinel` is intentionally NOT in this set. It is a mechanical gate-runner (lint / tsc / tests /
+> build / audit → PASS/FAIL); it cannot read source files or perform the source-level review this step
+> requires. Gate-running for the card happens in the QA flow, not in this deep-review parallel set.
 
 > **Lean agent set (Step -0.5)**: when a contract file is active, launch only the agents the resolved
-> mode permits — `skip_doc_reviewer` omits #4; `profile: light` additionally omits #2, #3, AND **#5
-> (Codex adversarial)** (since v3.38.0). At `light`, only agent #1 (`code-reviewer`) launches (+ the
-> Step 3 FP-gate). At `full` (and in full mode with no contract file), launch all five (Codex #5
-> included). The standalone `/codexreview <CARD-ID>` invocation (no contract) is always full.
+> mode permits — `skip_doc_reviewer` omits #3 (`doc-reviewer`); `profile: light` additionally omits #2
+> (`api-perf-cost-auditor`) AND **#4 (Codex adversarial)** (since v3.38.0). At `light`, only agent #1
+> (`code-reviewer`) launches (+ the Step 3 FP-gate). At `full` (and in full mode with no contract
+> file), launch all four (Codex #4 included). The standalone `/codexreview <CARD-ID>` invocation (no
+> contract) is always full.
 
-**Codex invocation rules (agent #5):**
+**Codex invocation rules (agent #4):**
 
 Codex is NOT invoked via the `Agent` tool (the `codex:codex-rescue` subagent_type is not registered in the harness). Instead, invoke it directly with Bash:
 
@@ -164,12 +171,21 @@ node "$PLUGIN_ROOT/scripts/codex-companion.mjs" task \
   --wait
 ```
 
-- Use `--wait` to get results synchronously in the same turn.
+- **Path-safety (MUST)**: the `<file list>` is built from `review_scope_files` (card-indicated +
+  git-touched paths). Before interpolating any path into a shell command, pass each path as a
+  separate, properly-quoted argument — never splice an unvalidated, unquoted path into a command
+  string, and never feed the list through `xargs -I{} git show HEAD:{}` (an unquoted `{}` lets a
+  crafted path inject shell metacharacters). When you must read a tree blob, validate the path
+  against `review_scope_files` and quote it (`git show "HEAD:$path"` with `$path` from a vetted
+  array), or read the working-tree file directly with the `Read` tool.
+- Use `--wait` to get results synchronously in the same turn. Run this Codex call ONLY as a
+  foreground `--wait` invocation — do NOT also pass it to `run_in_background` in the same call;
+  `--wait` already blocks for the synchronous result and the two are mutually exclusive.
 - The `PLUGIN_ROOT` discovery handles version upgrades automatically.
 - Capture stdout verbatim in a `codex_raw_output` field, then normalize each Codex finding into the schema.
-- If Codex exits non-zero or the script is not found, log `CODEX_UNAVAILABLE` with the error and continue with the remaining 4 agents. Do not block the run.
+- If Codex exits non-zero or the script is not found, log `CODEX_UNAVAILABLE` with the error and continue with the remaining 3 agents. Do not block the run.
 
-Each agent (1–4) MUST return findings using this schema:
+Each agent (1–3) MUST return findings using this schema:
 
 - `finding_id`: unique ID (`<CARD-ID>-F###`)
 - `title`
@@ -182,7 +198,7 @@ Each agent (1–4) MUST return findings using this schema:
 - `risk_if_unfixed`
 - `minimal_fix_direction`
 
-Codex findings (agent #5) are normalized into the same schema after capture, with `source: "codex"` appended.
+Codex findings (agent #4) are normalized into the same schema after capture, with `source: "codex"` appended.
 
 No generic findings allowed. Every finding must have concrete evidence.
 
@@ -190,10 +206,10 @@ No generic findings allowed. Every finding must have concrete evidence.
 
 ## Step 3 — Mandatory False-Positive Check
 
-Collect all findings from Step 2 — including normalized Codex findings — into a single pool, then run independent validation in parallel for each finding:
+Collect all findings from Step 2 — including normalized Codex findings — into a single pool, then run independent validation in parallel for each finding. Both validators must be **code-aware** (able to read the source and reason about the claimed behavior) — `qa-sentinel` is excluded here because it is a mechanical gate-runner that cannot read source files:
 
-1. Static validator: `code-reviewer` or `codebase-architect`
-2. Behavior validator: `qa-sentinel`
+1. Path/pattern validator: `codebase-architect` — confirms the cited file/symbol exists and the structural claim holds.
+2. Behavior validator: `code-reviewer` — reads the cited code and confirms or refutes the claimed runtime behavior.
 
 Classify each finding strictly as:
 
@@ -215,8 +231,8 @@ Only `VERIFIED` findings can be reported as bugs.
 
 After Step 3 false-positive gating, the orchestrator runs ONE additional Chain-of-Verification pass on the consolidated VERIFIED pool. This catches two failure modes the per-agent CoVe doesn't:
 
-1. **Cross-agent echo allucination**: 2+ agents independently produce the same hallucinated finding (e.g. wrong file path that "looks plausible") and reinforce each other through Step 3 cross-validation.
-2. **Undetected ripple effects**: a VERIFIED finding is real but its scope is wider than reported (e.g. "missing withAuth on route X" is true, but routes Y and Z have the same gap and weren't flagged).
+1. **Cross-agent echo hallucination**: 2+ agents independently produce the same hallucinated finding (e.g. wrong file path that "looks plausible") and reinforce each other through Step 3 cross-validation.
+2. **Undetected ripple effects**: a VERIFIED finding is real but its scope is wider than reported (e.g. "an authz guard is missing on route X" is true, but routes Y and Z have the same gap and weren't flagged).
 
 ### Procedure
 
@@ -224,7 +240,7 @@ For each VERIFIED finding in the pool, generate ONE residual verification questi
 
 > "If this finding is true, which OTHER file or function SHOULD also be modified and is not currently flagged?"
 
-Execute targeted grep/read commands (max 10 total across all findings — shared budget). Two outcomes:
+Execute targeted grep/read commands (max 10 total across all findings — shared budget [DESIGN-CHOICE: limits CoVe cost to a bounded constant regardless of finding count; findings not reached are tagged `cove_unverified`]). Two outcomes:
 
 - **Verification expands the finding**: append a `ripple_files: [<paths>]` field to the finding's evidence, and bump severity by one level if ≥2 ripple files found. Note: `[ripple-expanded]` tag.
 - **Verification disproves the finding**: cross-validators were both fooled. Move the finding to `Hallucinated findings dropped (post-validation CoVe)` with the falsifying evidence quoted. Do NOT report as a bug.
@@ -239,7 +255,10 @@ Execute targeted grep/read commands (max 10 total across all findings — shared
 
 ## Step 4 — Final Report
 
-Write one consolidated report per run to `/tmp/codexreview-report-<TIMESTAMP>.md`.
+Write one consolidated report per run to `/tmp/codexreview-report-<CARD-ID>-<RUN-ID>.md`, where
+`<RUN-ID>` is a full timestamp-plus-uuid (e.g. `20260601T142233Z-a1b2c3`) — a date-only name collides
+across same-day concurrent runs. Return this exact path to the caller; downstream consumers must use
+the returned path, never reconstruct it via wildcard/timestamp guess.
 
 Report structure: