qaa-agent 1.9.1 → 1.9.5

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 
 All notable changes to QAA (QA Automation Agent) are documented here.
 
+## [1.9.5] - 2026-05-05
+
+### Added
+
+- **Framework Registry** (`frameworks/` directory) — folder-based metadata system with one JSON file per supported framework (Playwright, Cypress, Jest, Vitest, pytest, Selenium, Robot Framework). Each entry declares stable metadata: extensions, detection patterns, validation commands, conventions, Context7 keys. Scanner uses the registry for detection; executor and validator use the detected framework's entry for conventions and validation commands. Code idioms still come from Context7 at runtime — the registry tells the system "what to query in Context7", Context7 returns "how to write the code". Adding a new framework = adding a JSON file (no agent prompt changes).
+- **Intent Detector** (`bin/lib/intent-detector.cjs`) — natural-language argument parser shared by 5 commands (qa-start, qa-create-test, qa-fix, qa-audit, qa-pr). Extracts URLs, paths (with spaces, quoted, Windows/Unix), framework hints, and ticket URLs from any input. Hierarchy: flags > NL > defaults. Robust path detection handles English-word trimming for greedy-matched paths.
+- **INPUT DETECTION banner** — shown before every pipeline run on every command. Displays each resolved value with its source (flag, NL, or default). Always visible — with flags, with NL, or with defaults only. Prevents "wrong directory disasters" by showing assumptions before tokens are spent.
+- **Confirmation checkpoint after intent detection** (interactive mode) — when any value comes from NL or defaults (not all explicit flags), the pipeline pauses and asks the user to confirm the resolved inputs before invoking sub-agents. Skipped when `--auto` is set or when every value has `source: flag`. Prevents pipeline runs based on misinferred NL.
+- **Input validations (5 pre-pipeline checks)** — Capa 1 of 3-layer validation system. Validates: URL reachable, path writable, URL ambiguity with ticket platforms, no multiple AUT URLs, framework in registry. Capa 2 is each agent's `<quality_gate>`; Capa 3 is the bash checklist.
+- **Flag `--app-url` in `/qa-start`** — communicates "app running at this URL" to the pipeline. Propagated to e2e-runner, validator Layer 5, testid-injector verification, bug-detective reproduction. Aligns `/qa-start` with `/qa-create-test`.
+- **Mode `from-aut` in `/qa-create-test`** — single-shot URL → tests. Detector extracts non-ticket URLs and routes them to a lightweight flow that navigates the URL with Playwright MCP and generates tests directly. Bonus: fixes existing bug where non-ticket URLs incorrectly fell to `from-code` mode.
+- **Context7 response cache** (`bin/lib/context7-cache.cjs`) — version-specific cache at `.qa-output/frameworks/FRAMEWORK-VERSION.json` storing raw Context7 responses. Default TTL 30 days. Auto-invalidates when project version changes (filename includes version). CLI: `read`, `write`, `status`, `clear`, `init` operations.
+- **Verification Cascade in Context7-using agents** — researcher, executor, e2e-runner, bug-detective now follow `cache → research docs → query Context7 → WebFetch fallback`. Verification remains mandatory; the cascade just prioritizes cheaper local sources first. Reduces Context7 free-tier pressure (60 req/h limit).
+
+### Fixed
+
+- **Deployment gap — installer never synced to Claude Code's live locations (finding #52)** — `install.cjs` copied everything to `~/.claude/qaa/` (or `./.claude/qaa/`), but Claude Code loads slash commands from `<claudeDir>/commands/`, sub-agents from `<claudeDir>/agents/`, and global standards from `<claudeDir>/CLAUDE.md`. New versions never activated — even after reinstalling — because the live locations kept the old files. Added **Step 4: Sync to live locations** — scope-aware (global → `~/.claude`, local → `./.claude`), mirrors only QAA-owned files (`qa*.md` / `qaa-*.md`) into `commands/` and `agents/`, prunes QAA orphans that no longer ship (never touching foreign files like `gsd-*`, `sc:*`), and merges `CLAUDE.md` via `<!-- QAA-BEGIN --> / <!-- QAA-END -->` markers. **First install with this fix requires reinstall + restart of Claude Code.** If a global `CLAUDE.md` existed without QAA markers, it is backed up to `CLAUDE.md.bak-<timestamp>` before being replaced with a marked version. Also added a `--dry-run` flag (prints planned copies/prunes without writing) and a guard for missing `HOME`/`USERPROFILE`.
+- **`qaa-codebase-mapper`, `qaa-discovery`, `qaa-project-researcher` were missing both quality_gate and bash checklist** — added both to all 3 agents. `qaa-e2e-runner` was missing only quality_gate (added). `qaa-scanner` was missing only bash checklist (added). All 12 agents now have both verification mechanisms in place.
+- **Framework hardcode dispersed across 20+ files** — agents now consult the Framework Registry as the source of truth for detection, validation commands, and conventions. Existing hardcoded examples remain as fallback/illustration. New `<framework_registry>` section in qaa-scanner, qaa-executor, qaa-validator explains the lookup order.
+- **`required_reading` of agents and `<files_to_read>` of workflow updated** — scanner reads all `frameworks/*.json` for detection; executor and validator read only the framework JSON for the detected framework. Module Boundaries and "MUST Read Before Producing Output" tables in CLAUDE.md updated accordingly.
+
+### Documentation
+
+- **CLAUDE.md** — added "Framework Registry" section (~70 lines) documenting registry structure, consumers, fallback behavior, and Context7 cache. Added "Intent Detection" section (~30 lines) explaining hierarchy, banner, and validations.
+- **README.md** — Robot Framework added to supported frameworks list. Architecture diagram updated with `frameworks/` and `bin/lib/`. New examples in Quick Start: `--app-url`, `from-aut` mode, natural language input.
+- **QAA_SYSTEM_OVERVIEW.md** — new sections: Framework Registry, Intent Detection, Context7 Cache. Version updated to 1.9.5.
+
+## [1.9.2] - 2026-05-05
+
+### Fixed
+
+- **`qaa-codebase-mapper` was missing from `/qa-start` pipeline since v1.6.3** — the codebase-mapper agent existed and was documented as part of the pipeline (CLAUDE.md, README.md, qa-pipeline-orchestrator.md), but the `workflows/qa-start.md` file never invoked it as a step. Downstream agents (analyzer, planner, executor) had `(if exists)` references to the 8 codebase docs that always failed because no agent produced them. The fix adds a new `<step name="codebase_map">` between scan and research that spawns 4 parallel sub-agents (testability, risk, patterns, existing-tests) producing the 8 documents in `.qa-output/codebase/`. Pipeline order now matches documentation: `scan → codebase-map → research → analyze → ...`.
+- **Pipeline order corrected: `research` now runs AFTER `codebase-map`** — research stage was previously placed before codebase-map (added in v1.9.0 as STAGE 1b). The correct logical order is `scan → codebase-map → research` so the researcher can use codebase findings (RISK_MAP, CODE_PATTERNS, API_CONTRACTS) to make Context7 queries specific to the project's actual stack instead of generic framework questions. Research stage renamed to STAGE 1c.
+- **Downstream agents now receive the appropriate codebase docs in their `<files_to_read>`** — analyzer reads RISK_MAP, CRITICAL_PATHS, TEST_ASSESSMENT, COVERAGE_GAPS; planner reads TESTABILITY, TEST_SURFACE, CRITICAL_PATHS, COVERAGE_GAPS; executor reads TEST_SURFACE, CODE_PATTERNS, API_CONTRACTS. Mapping follows the codebase-mapper's own `why_this_matters` contract.
+- **`qaa-executor`, `qaa-e2e-runner`, and `qaa-bug-detective` now declare Context7 tools explicitly in frontmatter** — these agents had prompts saying "MUST query Context7" but did not declare the `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` tools in their YAML frontmatter, relying on tool inheritance from the parent. Now declared explicitly along with Playwright MCP tools where applicable. Improves portability and respects the principle of least privilege.
+- **`VERSION` file now distributed in npm package** — added `"VERSION"` to the `files` array in `package.json` so the `VERSION` file is included in published packages. Previously, end users who ran `npx qaa-agent` never received an updated `VERSION` file because it was excluded from the npm package whitelist, leaving stale version numbers that did not match `package.json`.
+
+### Added
+
+- **Version-aware `libraryId` in Context7 queries** — when the project's framework version is detected from `package.json`/`requirements.txt`/lock files, agents now use a versioned library ID format (`/org/project/v1.40.0`) in `query-docs` calls. Context7 returns documentation specific to that version, not the latest. Generated code matches the framework version the project actually uses, avoiding APIs that don't exist or have changed. Applied to `qaa-project-researcher`, `qaa-executor`, `qaa-e2e-runner`, and `qaa-bug-detective`. Falls back to base library ID if version cannot be detected.
+- **`<codebase_grounding>` section in `qaa-project-researcher`** — explicit instructions for the researcher to use codebase map findings (RISK_MAP, CODE_PATTERNS, API_CONTRACTS, etc.) to ground Context7 queries to project specifics (e.g., "MSW integration with Playwright" instead of "Playwright mocking capabilities"). Includes a comparison table of generic vs grounded queries.
+
 ## [1.9.1] - 2026-04-27
 
 ### Added
@@ -162,25 +204,4 @@ All notable changes to QAA (QA Automation Agent) are documented here.
 ## [1.2.0]
 
 ### Added
-- `qaa-codebase-mapper` agent -- 4 parallel focus areas (testability, risk, patterns, existing tests)
-- `qaa-project-researcher` agent -- researches best testing stack and practices
-- 8 codebase map documents produced by mapper
-
-## [1.1.0]
-
-### Added
-- Workflow definitions for all pipeline stages
-- Interactive installer (`npx qaa-agent`)
-- `qaa init` command for per-project initialization
-- npm package distribution
-
-## [1.0.0]
-
-### Added
-- Full QA automation pipeline -- 11 agents, 17 commands, 10 templates, 7 workflows
-- 3 workflow options (dev-only, immature QA, mature QA)
-- 4-layer test validation (syntax, structure, dependencies, logic)
-- Page Object Model generation with CLAUDE.md standards
-- Test ID injection for frontend components
-- Bug detective failure classification
-- Draft PR delivery with branch naming convention
+- `qaa-codebase-mapper` agent -- 4 parallel fo

package/CLAUDE.md

@@ -197,7 +197,7 @@ The QA automation system runs agents in a defined pipeline. Each stage produces
 ### Pipeline Stages
 
 ```
-scan -> research -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
+scan -> codebase-map -> research -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
 
 ### Workflow Options
@@ -205,7 +205,7 @@ scan -> research -> codebase-map -> analyze -> [testid-inject if frontend] -> pl
 **Option 1: Dev-Only Repo (no existing QA repo)**
 Full pipeline from scratch:
 ```
-scan -> research -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
+scan -> codebase-map -> research -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
 Produces: SCAN_MANIFEST.md -> 8 codebase map documents -> QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md -> [TESTID_AUDIT_REPORT.md] -> generation plan -> test files + POMs + fixtures + configs -> VALIDATION_REPORT.md -> [E2E_RUN_REPORT.md] -> branch + PR
 
@@ -249,12 +249,12 @@ Each agent owns specific artifacts. No agent may produce artifacts assigned to a
 
 | Agent | Reads | Produces | Template |
 |-------|-------|----------|----------|
-| qa-scanner | repo source files, package.json, file tree | SCAN_MANIFEST.md | templates/scan-manifest.md |
+| qa-scanner | repo source files, package.json, file tree, frameworks/*.json (registry) | SCAN_MANIFEST.md | templates/scan-manifest.md |
 | qa-project-researcher | SCAN_MANIFEST.md, repo source files, Context7 MCP, WebSearch, WebFetch | TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md | -- |
 | qa-codebase-mapper | SCAN_MANIFEST.md, repo source files, CLAUDE.md | TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md | -- |
 | qa-analyzer | SCAN_MANIFEST.md, codebase map documents, CLAUDE.md | QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md (Option 1) or GAP_ANALYSIS.md (Option 2/3) | templates/qa-analysis.md, templates/test-inventory.md, templates/qa-repo-blueprint.md, templates/gap-analysis.md |
 | qa-planner | TEST_INVENTORY.md, QA_ANALYSIS.md, codebase map documents | Generation plan (internal) | -- |
-| qa-executor | TEST_INVENTORY.md, codebase map documents, CLAUDE.md | test files, POMs, fixtures, configs | qa-template-engine patterns |
+| qa-executor | TEST_INVENTORY.md, codebase map documents, CLAUDE.md, frameworks/{detected_framework}.json (registry) | test files, POMs, fixtures, configs | qa-template-engine patterns |
 | qa-validator | generated test files, CLAUDE.md | VALIDATION_REPORT.md (validation mode) or QA_AUDIT_REPORT.md (audit mode) | templates/validation-report.md, templates/qa-audit-report.md |
 | qa-e2e-runner | generated E2E test files, POM files, CLAUDE.md, live application | E2E_RUN_REPORT.md, fixed test/POM files with real locators | -- |
 | qa-testid-injector | repo source files, SCAN_MANIFEST.md, CLAUDE.md | TESTID_AUDIT_REPORT.md, modified source files with data-testid attributes | templates/scan-manifest.md, templates/testid-audit-report.md |
@@ -399,8 +399,8 @@ Each agent operates on the same branch. No worktree splits are needed for this s
 
 Respect stage transitions from the Agent Pipeline section:
 1. qa-scanner runs first (no dependencies)
-2. qa-project-researcher runs after scanner (depends on SCAN_MANIFEST.md, uses Context7 MCP — non-blocking, pipeline continues if it fails)
-3. qa-codebase-mapper runs after researcher (depends on SCAN_MANIFEST.md, spawns 4 parallel focus agents)
+2. qa-project-researcher runs after codebase-map (depends on SCAN_MANIFEST.md, uses Context7 MCP — non-blocking, pipeline continues if it fails)
+3. qa-codebase-mapper runs after scanner (depends on SCAN_MANIFEST.md, spawns 4 parallel focus agents)
 4. qa-analyzer and qa-testid-injector run after codebase-map (both depend on SCAN_MANIFEST.md + codebase map documents + research documents if available)
 5. qa-planner runs after analyzer (depends on QA_ANALYSIS.md + TEST_INVENTORY.md + codebase map documents)
 6. qa-executor runs after planner (depends on generation plan + codebase map documents + research documents if available + Context7 MCP)
@@ -429,12 +429,12 @@ Every agent MUST read its required inputs before producing any output. Failure t
 
 | Agent | MUST Read Before Producing Output |
 |-------|-----------------------------------|
-| qa-scanner | package.json (or equivalent), folder tree structure, all source file extensions to detect framework and language |
+| qa-scanner | package.json (or equivalent), folder tree structure, all source file extensions, frameworks/*.json (registry) for detection patterns |
 | qa-project-researcher | SCAN_MANIFEST.md, repo source files, MY_PREFERENCES.md. Uses Context7 MCP as primary source. |
 | qa-analyzer | SCAN_MANIFEST.md (complete, verified), CLAUDE.md (all QA standards sections), research documents (if available) |
 | qa-planner | TEST_INVENTORY.md (all test cases), QA_ANALYSIS.md (architecture and risk context) |
-| qa-executor | TEST_INVENTORY.md (test cases to implement), CLAUDE.md (POM rules, locator hierarchy, assertion rules, naming conventions, quality gates), research documents (if available). Must query Context7 MCP before generating code. |
-| qa-validator | CLAUDE.md (quality gates, locator tiers, assertion rules), all generated test files to validate |
+| qa-executor | TEST_INVENTORY.md (test cases to implement), CLAUDE.md (POM rules, locator hierarchy, assertion rules, naming conventions, quality gates), research documents (if available), frameworks/{detected_framework}.json (registry: conventions, extensions, context7_keys). Must query Context7 MCP before generating code. |
+| qa-validator | CLAUDE.md (quality gates, locator tiers, assertion rules), all generated test files to validate, frameworks/{detected_framework}.json (registry: validation_commands) |
 | qa-testid-injector | SCAN_MANIFEST.md (component file list), CLAUDE.md (data-testid Convention section for naming rules) |
 | qa-bug-detective | Test execution output (stdout/stderr, exit codes), test source files (to read the failing code), CLAUDE.md (classification rules), research documents (if available). Must query Context7 MCP before auto-fixing. |
 | qa-e2e-runner | Generated E2E test files, POM files, CLAUDE.md, live application, research documents (if available). Must query Context7 MCP before fixing locators. |
@@ -555,3 +555,164 @@ When adding `data-testid` to third-party UI library components, use this priorit
    <TextField inputProps={{ 'data-testid': 'login-email-input' }} />
    <Autocomplete slotProps={{ input: { 'data-testid': 'search-query-input' } }} />
    ```
+---
+
+## Framework Registry
+
+The Framework Registry is a folder-based metadata system at `frameworks/` containing one JSON file per supported framework. Each file declares stable metadata that the system needs to recognize and operate the framework — extensions, detection patterns, validation commands, conventions, Context7 keys.
+
+### What lives in `frameworks/<name>.json`
+
+```json
+{
+  "name": "playwright",
+  "display_name": "Playwright",
+  "languages": ["typescript", "javascript"],
+  "extensions": [".spec.ts", ".spec.js"],
+  "detection": {
+    "manifest_files": ["package.json"],
+    "manifest_grep": "@playwright/test",
+    "config_files": ["playwright.config.ts"],
+    "file_patterns": ["tests/**/*.spec.ts"]
+  },
+  "validation_commands": {
+    "syntax_check_ts": "tsc --noEmit",
+    "dry_run": "npx playwright test --list",
+    "lint": "eslint {file}"
+  },
+  "conventions": {
+    "test_dirs": ["tests/", "e2e/"],
+    "pom_dirs": ["pages/"],
+    "fixture_dirs": ["fixtures/"],
+    "config_filename": "playwright.config.ts"
+  },
+  "context7_keys": ["playwright", "@playwright/test"]
+}
+```
+
+### What does NOT live in the registry
+
+The registry stores **stable metadata**, NOT **code idioms**. Code idioms (imports, syntax, API usage, pattern examples) come from **Context7** at runtime — they change with framework releases and Context7 always has the latest. The registry tells the system "what to query in Context7" via `context7_keys`; Context7 tells the system "how to write the code".
+
+### Who consumes the registry
+
+| Agent | What it reads | How |
+|-------|---------------|-----|
+| qa-scanner | All `frameworks/*.json` | Iterate for detection (manifest_grep, config_files, file_patterns) |
+| qa-executor | `frameworks/<detected>.json` | Use `extensions`, `conventions`, `context7_keys` |
+| qa-validator | `frameworks/<detected>.json` | Use `validation_commands` for Layer 1 (Syntax) and Layer 2 (Structure) |
+
+Other agents (analyzer, planner, testid-injector, bug-detective, e2e-runner) get the framework name from the scanner's output (SCAN_MANIFEST.md) and don't need to read the registry directly.
+
+### Adding a new framework
+
+1. Create `frameworks/<new-framework>.json` with the schema above
+2. Add `"VERSION"` and `"frameworks/"` are already in `package.json` `files` array (no change needed)
+3. Test detection by running scanner against a project that uses the framework
+4. Test code generation: executor will read `context7_keys` and query Context7 for syntax
+
+### Fallback when framework not in registry
+
+If a project uses a framework not in `frameworks/`, the system:
+1. Logs a WARNING: "Framework `<name>` not in registry — relying on Context7 only"
+2. Asks Context7 for everything (slower, more queries, but still works)
+3. The pipeline does NOT halt unless the user requests `--strict-registry`
+
+The registry is an **optimization**, not a gate. Common frameworks are pre-registered for speed; rare frameworks fall back to Context7.
+
+### Context7 cache (project-local)
+
+Each project, after the first pipeline run, has a `.qa-output/frameworks/<framework>-<version>.json` file that caches Context7 query responses. This:
+- Reduces Context7 API calls (free tier: 60/hour)
+- Auto-invalidates when project framework version changes (filename includes version)
+- Default TTL: 30 days
+
+The cache is consumed by 4 agents: project-researcher (writes), executor / e2e-runner / bug-detective (read first, fall back to Context7 if cache miss). See the `<context7_verification>` → "Verification Cascade" section in those agents.
+
+---
+
+## Intent Detection
+
+The Intent Detector at `bin/lib/intent-detector.cjs` parses command arguments to extract structured intent (URLs, paths, framework hints, tickets, flags) and supports both explicit flags and natural language.
+
+### Hierarchy
+
+```
+Flags > Natural Language > Defaults
+```
+
+- **Flags always win**: `--app-url https://example.com` is authoritative
+- **NL fills gaps**: if `--app-url` is not passed but a URL is mentioned, the detector extracts it
+- **Defaults**: if neither flag nor NL provides a value, fall back to defaults (cwd for dev-repo, etc.)
+
+### INPUT DETECTION banner
+
+Every command (qa-start, qa-create-test, qa-fix, qa-audit, qa-pr) shows an **INPUT DETECTION** banner before starting work. This banner is shown ALWAYS — with flags, with NL, or with defaults — and lists every resolved value with its source:
+
+```
+=== INPUT DETECTION ===
+From explicit flags:
+  --dev-repo           /home/user/proj  (source: flag)
+Detected from natural language:
+  --app-url            https://staging.example.com  (source: NL)
+  --framework          playwright  (source: NL)
+Defaults applied:
+  --auto               false  (source: default)
+=======================
+```
+
+In interactive mode, the user can press Ctrl-C if the detection looks wrong. In `--auto` mode, the banner serves as a structured log.
+
+### Input validations (5 pre-pipeline checks)
+
+After intent detection, qa-start runs 5 validation checks before invoking any sub-agent:
+
+1. **URL reachable** — `curl` ping with 5s timeout (warning, not fatal)
+2. **Path writable** — verify dev-repo path exists and is writable, or parent is writable
+3. **URL not ambiguous with ticket platforms** — warn if AUT URL looks like a ticket URL
+4. **No multiple AUT URLs** — fail if more than 1 AUT URL detected (excluding tickets)
+5. **Framework in registry** — warn if `--framework <name>` not in `frameworks/`
+
+These are **Capa 1** of a 3-layer validation system. Capa 2 is each agent's `<quality_gate>`. Capa 3 is each agent's mandatory bash checklist.
+
+---
+
+## Standard Task() Directive
+
+Every `Task()` / `Agent()` spawn in this codebase (orchestrator, commands, workflows) MUST embed the following directive **verbatim** at the very top of the spawned prompt, substituting ONLY `<AGENT_FILE>` with the target agent's exact filename (e.g. `qaa-scanner`, `qa-pipeline-orchestrator`). Do NOT paraphrase it, and do NOT add `subagent_type: "qaa-X"` — native subagent routing for QAA agents is not enabled and would hard-error (see the architectural note below).
+
+```
+<critical_directive priority="MANDATORY">
+You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+~/.claude/qaa/agents/<AGENT_FILE>.md and adopt it as your operating contract.
+
+Even though you may be running as a general-purpose agent (native subagent type
+routing for QAA agents is not yet enabled), you MUST behave exactly as the
+dedicated agent defined in that file: read everything in its <required_reading>,
+obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+Never modify application source code (src/, app/, lib/, or equivalent
+directories) unless the agent's <scope> section explicitly permits it. If the
+agent's contract restricts what files it can touch, honor that restriction —
+even if a fix seems obvious or trivial.
+
+If you cannot read ~/.claude/qaa/agents/<AGENT_FILE>.md (file missing, corrupted, parse
+error), STOP and report the failure. Do NOT proceed with default agent
+behavior — that defeats the purpose of this directive.
+
+Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+make, or skip any of the above. Skipping the agent's required_reading,
+quality_gate, or bash checklist makes the run INVALID — its output cannot be
+trusted.
+</critical_directive>
+```
+
+### Architectural convention: wrap the flow in MANDATORY
+
+QAA hardens execution at two layers, and new commands/agents MUST follow both:
+
+1. **Command headers** — every NL command opens with a `## ⚠ MANDATORY: How to Execute This Command` block defining the full ordered flow + DO / DO NOT (not just the first tool call).
+2. **Task() prompts** — every spawn embeds the Standard Task() Directive above.
+
+This is the standard QAA enforcement pattern. Native `subagent_type` routing is deferred (the agents are not registered in `~/.claude/agents/`); until then the embedded directive is the enforcement mechanism.
+