baldart 3.40.0 → 3.41.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.41.0] - 2026-06-01
+
+**`qa-sentinel` is now profile-driven: `balanced` cards run SCOPED tests (only the tests related to the touched files), and the FULL suite is reserved for `deep` cards (or a `balanced` change whose diff reveals undeclared risk).** This is a **behavioral change to QA depth** — the default for an ordinary feature/refactor changes from "run the whole suite" to "run the related tests" — not an additive feature. **No new `baldart.config.yml` keys** — it reuses the existing `review_profile` field; scoped/smoke test selection is auto-probed at runtime from the project's test runner.
+
+> **Why.** The `review_profile` (skip/light/balanced/deep) is computed deterministically upstream by `prd-card-writer` (Rule C) and passed to `qa-sentinel` by `/new` — but the agent **ignored it**. Its prompt literally said `Run FULL VALIDATION MODE` while the line below passed `QA profile: balanced`, and the agent re-decided QUICK-vs-FULL from a crude `>5 files` heuristic. Net effect: a 6-file UI-only `balanced` card triggered the entire regression suite. The fix makes the profile **authoritative**: it selects the tier; file *count* no longer escalates (the framework already treats file count as advisory-only — `prd-card-writer.md`). The only upgrade path is **risk drift** — the diff itself touching auth/permission/payment/schema/migration/API-contract — which catches a card the author under-classified. An adversarial review of the first design rejected three over-reaches kept out of this release: putting the executable tier table in `agents/testing.md` (the agent never reads it), a ghost `SMOKE` tier mapped to `light` (which never invokes the agent), and a `>15 files` escalation (re-introducing the very full-too-often problem).
+
+### Changed — `qa-sentinel` honors `review_profile` (scoped-by-default)
+
+- **[framework/.claude/agents/qa-sentinel.md](framework/.claude/agents/qa-sentinel.md)** — Step 0 + `Operating Modes`: tier is now selected from the `QA profile` in the prompt, not file count. MODE 1 is **SCOPED VALIDATION** (profile `balanced`): a stack-aware test-impact cascade (`jest --findRelatedTests` → `vitest related` → `pytest <paths>` → `--testPathPattern`, monorepo-workspace-aware) that runs only related tests and **never** falls through to the full suite. MODE 2 is **FULL VALIDATION** (profile `deep`, or `balanced` escalated by risk drift). Confidence rule added: a SCOPED run that finds no related tests for a *logic* change records `Tests: SKIP — no related tests` and caps confidence at ≤70% instead of reporting PASS 95%. The H2 headings are unchanged (preserves consumer agent overlays); only the section bodies were rewritten.
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** — Phase 3.5 qa-sentinel prompt no longer says "FULL VALIDATION MODE"; it passes the tier contract (`balanced → SCOPED`, `deep → FULL`, risk-drift-only escalation) and derives the E2E depth from the profile (`deep` full+blocking, `balanced` `--grep` advisory). Duplicate step "22" renumbered. Team-mode **D.4** documents that a mixed group with any `deep` card runs FULL (max-profile intentionally overrides the per-card SCOPED tier).
+- **[framework/.claude/commands/qa.md](framework/.claude/commands/qa.md)** — `/qa` now passes `QA profile` to qa-sentinel (so the agent never defaults to absent), and the LIGHT path no longer falls back to the full suite when the test pattern is unclear.
+
+### Changed — documentation aligned
+
+- **[framework/agents/testing.md](framework/agents/testing.md)** — new stack-neutral **Scope-aware Test Selection** section documenting the principle (balanced→scoped / deep→full / risk-drift→escalate), explicitly pointing at `qa-sentinel` as the executable SSOT and fencing TIA as heuristic (no coverage maps / AST / ML). Runner-specific commands deliberately kept out (Codex / non-Node consumers read this module).
+- **[framework/agents/index.md](framework/agents/index.md)** + **[README.md](README.md)** — routing pointer and the qa-sentinel one-liner updated (`Quick/Full/Deep profiles` → `profile-driven: scoped-by-default, full on deep`).
+
 ## [3.40.0] - 2026-06-01
 
 **Doc fixes surfaced by `/new`'s doc-review are now applied by the `doc-reviewer` itself, not delegated to `coder`.** The `doc` fix-domain owner changes from `coder` to `doc-reviewer` (write mode) across every `/new` site that previously spawned a coder for documentation: sequential Phase 3, team-mode D.4a, and the post-batch Final review. **No new `baldart.config.yml` keys** — this is a fix-routing change internal to `/new`.

package/README.md

@@ -99,7 +99,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 9. **plan-auditor**: MANDATORY after planning — 4-persona plan review + High-Risk Path triggers + Specialist Auto-Spawn
 10. **senior-researcher**: Evidence-based research with AI-readable retrieval-optimized reports
 11. **api-perf-cost-auditor**: API performance and cost analysis with Findings Schema emission
-12. **qa-sentinel**: SDET-grade gate runner (Quick/Full/Deep profiles) — lint, tsc, test, build, audit
+12. **qa-sentinel**: SDET-grade gate runner (profile-driven: scoped-by-default, full on deep) — lint, tsc, test, build, audit
 
 **Design & UX**
 13. **ui-expert**: UI/UX design and review

package/VERSION

@@ -1 +1 @@
-3.40.0
+3.41.0

package/framework/.claude/agents/REGISTRY.md

@@ -97,21 +97,23 @@ Weekly skill/agent improvement?        --> skill-improver
 
 ### Profile selection
 
-| Profile | Mode | Use when |
+| Profile | Tier | Use when |
 |---------|------|----------|
-| `light` | QUICK VALIDATION | Small bugfix, ≤5 files, no core modules, style/docs only |
-| `balanced` | FULL VALIDATION | Normal feature card, medium scope (default) |
-| `deep` | FULL VALIDATION + Playwright | Auth/payments/DB/permissions, >15 files, Feature Complete cards |
+| `light` | SCOPED (related tests) | Small bugfix, no core modules, style/docs only |
+| `balanced` | SCOPED (related tests) | Normal feature card, medium scope (default) |
+| `deep` | FULL (whole suite) + Playwright | Auth/payments/DB/permissions, broad blast radius, Feature Complete cards |
 | `skip` | — | Docs-only or cosmetic cards with zero logic changes |
 
+Tier is selected by the **profile**, not file count. A `balanced` change is escalated to FULL only when the diff reveals undeclared risk (auth/permission/payment/schema/migration/API contract); file count never escalates.
+
 ### Invocation pattern
 
 ```
 subagent_type: "qa-sentinel"
 prompt: |
-  Run [QUICK | FULL] VALIDATION MODE on card <CARD-ID>.
+  Run QA on card <CARD-ID> at the tier dictated by the profile (do NOT default to FULL).
   Worktree: <path>  Branch: <branch>  Changed files: <list>
-  Profile: [light | balanced | deep]
+  QA profile: [light | balanced | deep]   (light/balanced → SCOPED, deep → FULL)
   Run gates ONLY. No AC verification, no code analysis, no recommendations.
   Write gate results + verdict to: /qa/<CARD-ID>.md (under 40 lines)
 ```

package/framework/.claude/agents/qa-sentinel.md

@@ -1,6 +1,6 @@
 ---
 name: qa-sentinel
-description: "Use this agent when code changes need quality assurance validation before merging, after implementing a feature or bugfix, when running pre-commit or pre-merge checks, when a backlog card is marked Feature Complete, or when you need structured QA reports with risk assessments. Also use proactively after significant code changes to core modules like authentication, payments, DB schema, or API contracts.\\n\\n<example>\\nContext: The user has just implemented a new feature touching the authentication middleware and multiple API routes.\\nuser: \"I've finished implementing the merchant session refresh logic across 8 files. Can you check it's ready?\"\\nassistant: \"This touches authentication and multiple API routes — I'll invoke QA-Sentinel to run a full validation.\"\\n<commentary>\\nThe change set affects core auth logic (>threshold files, critical path), so use the Task tool to launch qa-sentinel in FULL VALIDATION MODE.\\n</commentary>\\nassistant: \"Let me launch the QA-Sentinel agent to validate this change set.\"\\n</example>\\n\\n<example>\\nContext: Developer refactored a utility function used only in non-critical UI components.\\nuser: \"Just cleaned up the formatCurrency helper and updated the 3 components that use it.\"\\nassistant: \"Small refactor on a non-core module — I'll have QA-Sentinel do a quick validation pass.\"\\n<commentary>\\nThis is a small, non-core change, so use the Task tool to launch qa-sentinel in QUICK VALIDATION MODE.\\n</commentary>\\nassistant: \"Launching QA-Sentinel for a quick validation of the refactor.\"\\n</example>\\n\\n<example>\\nContext: A backlog card has just been marked as Feature Complete by the implementing agent.\\nuser: \"FEAT-0096 is done, all acceptance criteria checked.\"\\nassistant: \"Feature Complete status reached — I'll invoke QA-Sentinel to run release-level validation before we open the PR.\"\\n<commentary>\\nFeature Complete cards require FULL VALIDATION MODE. Use the Task tool to launch qa-sentinel.\\n</commentary>\\nassistant: \"Invoking QA-Sentinel for release-level confidence on FEAT-0096.\"\\n</example>\\n\\n<example>\\nContext: A bug was fixed and the developer wants to ensure it won't regress.\\nuser: \"Fixed the table control race condition in FEAT-0177.\"\\nassistant: \"Bug fix complete — I'll run QA-Sentinel to validate the fix and ensure a regression test is in place.\"\\n<commentary>\\nEvery bug fix should be validated and covered by a regression test. Use the Task tool to launch qa-sentinel.\\n</commentary>\\nassistant: \"Launching QA-Sentinel to validate the fix and check regression coverage.\"\\n</example>"
+description: "Use this agent when code changes need quality assurance validation before merging, after implementing a feature or bugfix, when running pre-commit or pre-merge checks, when a backlog card is marked Feature Complete, or when you need structured QA reports with risk assessments. Also use proactively after significant code changes to core modules like authentication, payments, DB schema, or API contracts.\\n\\n<example>\\nContext: The user has just implemented a new feature touching the authentication middleware and multiple API routes.\\nuser: \"I've finished implementing the merchant session refresh logic across 8 files. Can you check it's ready?\"\\nassistant: \"This touches authentication and multiple API routes — I'll invoke QA-Sentinel to run a full validation.\"\\n<commentary>\\nThe change set affects core auth logic (>threshold files, critical path), so use the Task tool to launch qa-sentinel in FULL VALIDATION MODE.\\n</commentary>\\nassistant: \"Let me launch the QA-Sentinel agent to validate this change set.\"\\n</example>\\n\\n<example>\\nContext: Developer refactored a utility function used only in non-critical UI components.\\nuser: \"Just cleaned up the formatCurrency helper and updated the 3 components that use it.\"\\nassistant: \"Small refactor on a non-core module — I'll have QA-Sentinel do a quick validation pass.\"\\n<commentary>\\nThis is a small, non-core change (profile balanced), so use the Task tool to launch qa-sentinel in SCOPED VALIDATION.\\n</commentary>\\nassistant: \"Launching QA-Sentinel for a quick validation of the refactor.\"\\n</example>\\n\\n<example>\\nContext: A backlog card has just been marked as Feature Complete by the implementing agent.\\nuser: \"FEAT-0096 is done, all acceptance criteria checked.\"\\nassistant: \"Feature Complete status reached — I'll invoke QA-Sentinel to run release-level validation before we open the PR.\"\\n<commentary>\\nFeature Complete cards require FULL VALIDATION MODE. Use the Task tool to launch qa-sentinel.\\n</commentary>\\nassistant: \"Invoking QA-Sentinel for release-level confidence on FEAT-0096.\"\\n</example>\\n\\n<example>\\nContext: A bug was fixed and the developer wants to ensure it won't regress.\\nuser: \"Fixed the table control race condition in FEAT-0177.\"\\nassistant: \"Bug fix complete — I'll run QA-Sentinel to validate the fix and ensure a regression test is in place.\"\\n<commentary>\\nEvery bug fix should be validated and covered by a regression test. Use the Task tool to launch qa-sentinel.\\n</commentary>\\nassistant: \"Launching QA-Sentinel to validate the fix and check regression coverage.\"\\n</example>"
 model: sonnet
 color: pink
 memory: project
@@ -35,7 +35,11 @@ Default pre-commit gates (MUST pass before any commit verdict):
 
 Before running any checks:
 1. Run `git diff --name-only HEAD` (or against base branch) to get the actual change set.
-2. Select the appropriate operating mode based on file count and paths.
+2. Read the authoritative `QA profile` from your invocation prompt (`balanced` | `deep`) and map it
+   to a test tier via the table in **Operating Modes**. The profile — NOT file count — selects the
+   tier. The only allowed adjustment is `balanced → FULL` when the diff itself reveals risk the card
+   did not declare (see the risk-drift rule below). If the prompt carries no profile, default to
+   SCOPED and note it — never invent your own classification.
 
 Never fabricate test results. Never assume what changed — always read the diff.
 Do NOT read the changed files to "understand scope" — that's the code-reviewer's job. Just run the gates.
@@ -73,7 +77,12 @@ Long-running commands (especially `npm run build`) produce thousands of lines th
 # Build — only capture exit code and last 20 lines
 npm run build 2>&1 | tail -20; echo "EXIT:$?"
 
-# Tests — capture summary only
+# Tests (SCOPED — default for balanced) — related tests only, summary
+npx jest --findRelatedTests <changed files> 2>&1 | tail -30; echo "EXIT:$?"
+npm test -- --testPathPattern="<touched-module-regex>" 2>&1 | tail -30; echo "EXIT:$?"
+pytest <related test paths> 2>&1 | tail -30; echo "EXIT:$?"
+
+# Tests (FULL — only for deep / risk-drift) — whole suite, summary
 npm test 2>&1 | tail -30; echo "EXIT:$?"
 
 # ESLint — full output is OK (usually short), but cap at 50 lines
@@ -89,38 +98,54 @@ If a gate FAILS, you may re-run WITHOUT `tail` to get the full error — but onl
 
 ## Operating Modes
 
-### MODE 1: QUICK VALIDATION
+The `QA profile` from your prompt selects the tier. The `skip` profile never reaches you (handled
+upstream). Two execution tiers — **SCOPED** (default for `light`/`balanced`) and **FULL** (`deep`):
+
+| QA profile | Tier | Tests | Audit | E2E | Target |
+|------------|------|-------|-------|-----|--------|
+| `light`    | SCOPED | related tests only (TIA cascade below); skip if upstream gates already ran | skip | none | <3 min |
+| `balanced` | SCOPED | related tests only (TIA cascade below) | skip unless new deps | advisory | <5 min |
+| `deep`     | FULL   | whole suite | `npm audit --audit-level=high` | blocking | <15 min |
+
+> Some orchestrator entry points run the upstream gates themselves and skip invoking you for `light`;
+> others invoke you with `light` — in that case run SCOPED. Either way `light` never means FULL.
 
-Triggers:
-- ≤5 files changed
-- Non-core modules (UI components, utility helpers, config)
-- Pure refactoring (no logic change)
-- UI-only adjustments
-- Documentation changes only
+**Risk-drift escalation (the ONLY upgrade path):** run `balanced` as FULL when the diff itself
+reveals risk the card did not declare — paths touching `auth`/`permission`/`payment`/`billing`,
+DB schema / migration / index changes, or an API contract change. File **count** never escalates
+(it is advisory only). When you escalate, log: `escalated balanced→FULL (risk drift: <reason>)`.
+Never de-escalate `deep` to SCOPED.
+
+### MODE 1: SCOPED VALIDATION (profile `balanced`)
 
 Execution:
 1. `npx eslint --max-warnings=0 <changed files>`
 2. `npx tsc --noEmit`
-3. `npm test -- --testPathPattern=<impacted modules>` (scoped, not full suite)
+3. **Scoped tests** — run only the tests related to the changed files, via the first cascade rung
+   that applies to the repo (graceful degradation, never fall through to the full suite):
+   - Jest (`jest.config*` / `jest` in package.json): `npx jest --findRelatedTests <changed files>`
+   - Vitest (`vitest.config*` / `vitest`): `npx vitest related --run <changed files>`
+   - Pytest (`pytest.ini` / `pyproject` with pytest): `pytest <test paths matching touched modules>`
+   - Generic fallback: `npm test -- --testPathPattern="<regex of touched module dirs>"`
+   - Monorepo: resolve the workspace from the changed-file paths before invoking the runner.
+   - If no runner is determinable, or the runner reports "no tests found" for a **logic** change:
+     do NOT FAIL and do NOT run the full suite — record `Tests: SKIP — no related tests found` and
+     apply the confidence cap (see QA Report Format). For a docs/config-only change, a test SKIP is
+     legitimate at full confidence.
 4. `npm run build`
-5. Minimal smoke check if smoke tests exist for changed area
+5. Smoke check if the project exposes one (`test:smoke` script or `tests/smoke/` — opt-in convention,
+   absent is fine).
 
-Goal: Fast confidence without blocking flow. Target: <3 minutes.
+Goal: Fast confidence on the touched surface without blocking flow. Target: <5 minutes.
 
 ---
 
-### MODE 2: FULL VALIDATION
-
-Triggers (any one is sufficient):
-- >5 files changed
-- Core logic touched (auth, payments, Firestore schema, API contracts)
-- Backlog card marked "Feature Complete"
-- Bug fix, DB queries/transactions/indexes changed, new external dependency, API route changes, permission logic
+### MODE 2: FULL VALIDATION (profile `deep`, or `balanced` escalated by risk drift)
 
 Execution:
 1. `npx eslint --max-warnings=0 <changed .ts/.tsx files>`
 2. `npx tsc --noEmit`
-3. `npm run test` (full suite)
+3. `npm run test` (whole suite — or the project's full-suite equivalent, e.g. `pytest`)
 4. `npm run build`
 5. `npm audit --audit-level=high` (security baseline — flag HIGH/CRITICAL only)
 6. `npx markdownlint-cli2 <changed .md files>` (if any)
@@ -169,7 +194,7 @@ Keep reports **under 40 lines**. No prose, no analysis, no recommendations. Just
 ```
 ## QA REPORT — [FEAT-XXXX] — [DATE]
 
-Mode: QUICK / FULL | Files changed: N
+Tier: SCOPED / FULL | Profile: balanced / deep | Files changed: N
 
 | Gate | Status | Notes |
 |------|--------|-------|
@@ -193,6 +218,9 @@ Rules:
 - Pre-existing test failures: exclude from count, note as "N pre-existing excluded"
 - Security audit: only report NEW vulnerabilities vs baseline (24 vulns as of 2026-03-06). If no new packages added, write "no delta"
 - If all gates PASS → verdict is PASS, confidence 95-100%
+- **Scoped coverage gap**: if a SCOPED run found no related tests for a **logic** change, write
+  `Tests: SKIP — no related tests found` and cap confidence at **≤70%** with a one-line coverage-gap
+  note. Do not report PASS at 95% when no test actually ran on a logic change.
 - If any gate FAIL → verdict is FAIL, list only the failing gates
 
 ---

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

@@ -146,7 +146,7 @@ For each card, execute these phases in order:
 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>.
+    Run QA on card <CARD-ID> at the tier dictated by the QA profile (do NOT default to FULL).
 
     Context:
     - Worktree path: <worktree-path>
@@ -156,10 +156,12 @@ For each card, execute these phases in order:
     - 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)
+    Profile → tier mapping:
+    - light    → SCOPED (related tests only)
+    - balanced → SCOPED (related tests only; risk drift in the diff may escalate to FULL)
+    - deep     → FULL (whole suite + audit + e2e smoke suite if configured)
+    Only path-based risk drift (auth/permission/payment/schema/migration/API contract) escalates;
+    file count never does.
 
     After running all gates, write the complete QA Report to:
     /qa/<CARD-ID>.md

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

@@ -105,7 +105,7 @@ 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.
+4. Scoped tests — run only tests related to the changed files (related-tests / testPathPattern on touched modules). If no related tests are found, record `Tests: SKIP — no related tests` and cap confidence; do NOT fall through to the full suite.
 5. Build check.
 
 For each step: report PASS / FAIL. On FAIL, show the exact error output.
@@ -127,7 +127,7 @@ No findings file required. Present final verdict immediately.
 Invoke `qa-sentinel` via Task tool:
 
 ```
-Run FULL VALIDATION MODE on the current changeset.
+Run QA on the current changeset at the tier dictated by the QA profile below (do NOT default to FULL).
 
 Context:
 - Branch: <branch>
@@ -135,6 +135,11 @@ Context:
 - Changed files: <list from git diff>
 - Risk level: <Low/Medium/High>
 - Card: <CARD-ID or "none">
+- QA profile: <the profile this /qa was invoked with: balanced | deep>
+
+Tier contract: balanced → SCOPED (related tests on touched modules); deep → FULL suite. Only
+path-based risk drift (auth/permission/payment/schema/migration/API contract in the diff) may
+escalate balanced→FULL.
 
 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.

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

@@ -1199,7 +1199,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 22. **If profile is BALANCED or DEEP**: invoke the **`qa-sentinel`** agent (subagent_type: `qa-sentinel`) via Task tool with the following context:
 
     ```
-    Run FULL VALIDATION MODE on card <CARD-ID>.
+    Run QA on card <CARD-ID> at the tier dictated by the QA profile below (do NOT default to FULL).
 
     Context:
     - Worktree path: <worktree-path>
@@ -1207,9 +1207,13 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     - Changed files: <list from implementation phase>
     - QA profile: [balanced | deep]
 
-    Run E2E tests: `npx playwright test --reporter=list`
-    E2E failures are BLOCKING for deep profile, ADVISORY for balanced profile.
-    Also run gates (lint, tsc, test, build, markdownlint) as sanity check.
+    Tier contract: balanced → SCOPED (related tests on touched modules); deep → FULL suite.
+    Only path-based risk drift (auth/permission/payment/schema/migration/API contract in the diff)
+    may escalate balanced→FULL. File count never escalates.
+
+    E2E: deep → `npx playwright test --reporter=list` (BLOCKING);
+         balanced → `npx playwright test --grep "<changed area>" --reporter=list` (ADVISORY).
+    Also run gates (lint, tsc, build, markdownlint) as sanity check.
     Do NOT verify acceptance criteria (Phase 2.5 already did this).
     Do NOT analyze code for bugs/patterns (deferred to /codexreview post-batch).
     Do NOT write recommendations or follow-up actions.
@@ -1219,14 +1223,14 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     Return verdict: PASS or FAIL.
     ```
 
-22. **Read qa-sentinel's output.** Verify the findings file was written to `/qa/<CARD-ID>.md`.
-23. **If QA verdict is FAIL**:
+23. **Read qa-sentinel's output.** Verify the findings file was written to `/qa/<CARD-ID>.md`.
+24. **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).
     - **Telemetry** — after each coder spawn, append one row per blocker to `## Fix Application Log`: `3.5 | qa-blocker | est_lines=<n> | decision=coder | applied_by=coder | retry=<0|1|2>`. After PASS without any spawn (initial verdict PASS), append one row: `3.5 | qa-none | est_lines=0 | decision=skipped | applied_by=- | reason=qa-pass`.
-24. **Update tracker**: phase = "3.5-qa DONE", log: profile used, verdict (PASS/FAIL/SKIP), confidence %, findings count (blockers/majors/minors), findings file path.
+25. **Update tracker**: phase = "3.5-qa DONE", log: profile used, tier run (SCOPED/FULL) + any risk-drift escalation, verdict (PASS/FAIL/SKIP), confidence %, findings count (blockers/majors/minors), findings file path.
 
 ### Phase 3.7 — Pre-Merge Codex Review Gate (MANDATORY — UNCONDITIONAL)
 
@@ -2237,7 +2241,7 @@ After ALL agents in the group complete successfully:
 
 3c. **D.3c — Phase 2.6 E2E-Review (per-card)** — For EACH card in the group, honor the existing Gate table (skip when `features.has_e2e_review: false`, backend-only diff per the diff predicate documented in Phase 2.6, or card type `docs`/`chore`/`config`). For cards that pass the gate, invoke `/e2e-review` in programmatic mode with that card's payload. BLOCKING per-card: if `/e2e-review` returns `"blocked"` or `"error"`, surface to the user via the same `AskUserQuestion` documented in Phase 2.6 — do NOT proceed to D.4 with an unresolved card. Skips are logged with the documented gate reason, never with `"time budget"` or similar.
 
-4. **D.4 — QA gate (group)** — Read each card's `review_profile` field (fallback: compute via the QA Profile Selector table for legacy cards). Select the HIGHEST profile across all cards in the group (e.g., if one card is BALANCED and another is DEEP, use DEEP). Invoke **qa-sentinel** once for the group.
+4. **D.4 — QA gate (group)** — Read each card's `review_profile` field (fallback: compute via the QA Profile Selector table for legacy cards). Select the HIGHEST profile across all cards in the group (e.g., if one card is BALANCED and another is DEEP, use DEEP) and pass it as the `QA profile` to **qa-sentinel** (invoked once for the group) using the same prompt contract as Phase 3.5 step 22 (`do NOT default to FULL`; balanced → SCOPED, deep → FULL). Note: a mixed group containing any DEEP card runs the group at FULL — the max-profile intentionally overrides the SCOPED tier the BALANCED cards would get individually, because the combined diff must be validated together.
 
 4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0; doc-reviewer-applied since v3.40.0)** — Do NOT re-run the doc AUDIT (D.2 already produced per-card-attributed findings). If any card in the group has doc findings, invoke the **doc-reviewer once in write mode** over the group, passing the per-card-attributed findings from D.2, to APPLY all doc fixes in a single pass (it is now alone — code-reviewer is done — so the D.2 parallel-safety constraint no longer applies). Do **NOT** spawn a fix-coder for doc findings: `doc` is owned by `doc-reviewer` (see "Domain-Override Domains"); a code-oriented coder lacks the doc-invariant contract. The only exception is a doc-drift→bug finding rooted in CODE — that follows the D.4b code fix path. (Previously D.4a spawned a fix-coder per card; the audit was already collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so the doc AUDIT runs once per group while the doc FIXES run once per group via doc-reviewer.) **Telemetry** — append one row per applied doc finding to `## Fix Application Log`: `D.4a | doc | est_lines=<n> | decision=doc-reviewer | applied_by=doc-reviewer | card=<ID> | finding=<1-line>`.
 

package/framework/agents/index.md

@@ -22,7 +22,8 @@ Route agents to the right module with minimal reading.
 - If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
 - If touching architecture, auth, or tech stack -> read `agents/architecture.md`.
 - If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
-- If touching testing or QA issues -> read `agents/testing.md`.
+- If touching testing or QA issues -> read `agents/testing.md` (also documents the scope-aware,
+  profile-driven test-selection strategy consumed by `qa-sentinel`).
 - If touching GitHub issues or issue workflow -> read `agents/github-issue-subagent.md`.
 - If touching terminology or naming -> read `agents/coding-standards.md`.
 - If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.

package/framework/agents/testing.md

@@ -9,6 +9,32 @@ Define required manual testing and QA issue workflow, including browser automati
 **In**: Manual testing steps, QA issue creation and handling, browser automation.
 **Out**: Performance testing strategy (see agents/performance.md).
 
+## Scope-aware Test Selection (Automated QA)
+
+The automated QA gate (`qa-sentinel`) does **not** run the full test suite on every change. It runs
+the depth dictated by the card's `review_profile` (the deterministic SSOT computed at authoring
+time), so test effort matches change risk:
+
+- **balanced → SCOPED**: run only the tests *related to the changed files* (test-impact selection),
+  not the whole suite. This is the default for ordinary features and refactors.
+- **deep → FULL**: run the whole suite + security audit + blocking E2E. Reserved for high-risk
+  changes (data model, security, broad blast radius).
+- **skip / light**: the gate is not invoked — these are handled upstream (docs/chore, or gates
+  already run during implementation).
+- **Risk-drift escalation**: a `balanced` change is promoted to FULL only when the diff itself
+  reveals undeclared risk — paths touching auth, permissions, payment/billing, DB schema/migration,
+  or an API contract. Change *count* never escalates (it is advisory only).
+
+Test selection is **heuristic**, not instrumented: it relies on file paths, naming, and the test
+runner's native related-tests capability — no coverage maps, AST analysis, or ML. When no related
+tests can be resolved for a logic change, the gate records a coverage-gap and lowers its confidence
+rather than silently passing or falling back to the full suite. The concrete per-runner commands
+live in the `qa-sentinel` agent (which is stack-aware); this module states the principle only.
+
+> The executable tier table + runner cascade is owned by `qa-sentinel` (`.claude/agents/qa-sentinel.md`),
+> kept stack-specific there. Optional smoke convention: a `test:smoke` script or `tests/smoke/`
+> directory, if present, is used as a minimal sanity set — its absence is fine, not a misconfiguration.
+
 ## Do
 
 - Run project build command before marking a card done.

package/package.json

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