@ivorycanvas/qamap 0.3.3 → 0.3.4

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 export declare const TOOL_NAME = "QAMap";
-export declare const VERSION = "0.3.3";
+export declare const VERSION = "0.3.4";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const TOOL_NAME = "QAMap";
-export const VERSION = "0.3.3";
+export const VERSION = "0.3.4";
 //# sourceMappingURL=version.js.map

package/docs/adoption.md

@@ -164,3 +164,65 @@ Prefer severity overrides over broad ignores when a rule is useful but too noisy
 ```
 
 Use `ignoreRules` only for findings that the team intentionally accepts.
+
+## Where QAMap Fits
+
+On the QA side, QAMap starts one step earlier than test-writing tools — it decides what a PR must prove before anyone records, generates, or writes a test:
+
+| Tool category | Typical focus | QAMap focus |
+| --- | --- | --- |
+| Test recorders and studios | Turning a known flow into a script by watching you run it. | Deciding which flow a PR affects and what evidence is missing, before recording starts. |
+| LLM test generation | Spending model tokens to write test code from source. | Free, deterministic PR-to-QA mapping; drafts are starter scaffolds an agent or human finishes. |
+| Re-prompting an agent per PR | Re-deriving repo QA context in every session. | Repo-owned QA memory (`.qamap/manifest.yaml`) plus a compact `--format agent` handoff. |
+| Change-impact test selection | Choosing which existing unit/CI tests to run. | Naming the user-facing flow and E2E/checklist work that should exist at all. |
+
+On the guardrails side, QAMap is not trying to replace the larger security ecosystem:
+
+| Tool category | Typical focus | QAMap focus |
+| --- | --- | --- |
+| OpenSSF Scorecard | Broad open source security posture. | AI-agent readiness at the repository boundary. |
+| Secret scanning | Exposed credentials in code or history. | Secret-like values plus unsafe agent, workflow, and script context. |
+| MCP security scanners | Deep analysis of MCP servers, tools, prompts, and skills. | Static repo checks without executing untrusted MCP servers. |
+| General linters | Code style, correctness, or framework rules. | Guardrails that affect AI-assisted development safety. |
+
+
+## Why This Is Different From Recorders And Generators
+
+Recorders such as browser or mobile test studios are useful when you already know the flow to exercise. QAMap starts one step earlier: it asks what the PR changed, which repo-owned QA memory applies, and what test artifact should exist before merge.
+
+A good QAMap result should answer:
+
+- which product flow changed
+- which manifest domain, flow, and checks caused the recommendation
+- which draft test file was generated or previewed
+- which success, failure, edge, contract, or visual cases the draft covers
+- which selector, fixture, auth, runner, or validation gaps still block trusted regression evidence
+- which manifest path to edit when the recommendation is wrong
+
+That is the product bet: one human correction to the repo-local manifest should improve future PR recommendations without another LLM prompt.
+
+You do not need a manifest to start. Without one, QAMap uses the PR diff, package signals, routes, selectors, runner config, and existing tests. Add a manifest only when the team wants durable QA language that improves future recommendations.
+
+## What QAMap Is For
+
+QAMap is intentionally small:
+
+- time-saving: it surfaces missing context, risky settings, and validation gaps before agent work becomes review churn
+- static by default: it does not execute scanned project code
+- no-token by default: it does not call an LLM API
+- verification-focused: it tells reviewers what evidence is missing, not how to style code
+- PR QA skill output: `qamap qa` turns a branch into a PR-ready affected-flow summary, suggested E2E/checklist draft, missing evidence list, and copyable checklist
+- packaged agent skill: `skills/qamap-pr-qa/SKILL.md` gives coding agents a compact PR QA workflow for running QAMap before handoff
+- domain-aware E2E drafting: it turns branch changes into flow language, draft specs, readiness summaries, and action items
+- repo-local verification base: shared manifests can be committed, while generated run history stays ignored by default
+- context-aware baseline generation: manifest init can use repo-local context, ADRs, goals, agent instructions, harness files, skills, and runbooks as advisory bootstrap signals
+- harness/skill role hints: instruction-derived context is classified as agent skill, harness config, workflow lifecycle, verification rubric, safety policy, release policy, or test runner context
+- ecosystem-aware: it suggests validation commands for JavaScript/TypeScript, Python, Go, Rust, Gradle, and Maven projects
+- CI-friendly: text, JSON, Markdown, and SARIF output are supported
+- explainable: every finding includes a concrete fix
+
+It is built for teams using AI coding agents, MCP-powered tools, or any workflow where an agent can read, edit, test, commit, or open pull requests.
+
+For PR verification, QAMap treats the repository itself as the working base: committed manifests hold durable team language, ignored local history holds generated run observations, and the current branch diff supplies what changed now.
+
+

package/docs/agent-format.md

@@ -0,0 +1,52 @@
+# Agent Format Contract
+
+`qamap qa --format agent` prints one line of JSON (~2–4KB) designed to be pasted into a coding agent's context instead of the full markdown report. This page is the contract for that output: what the fields mean, what an agent may rely on, and how the format is allowed to change.
+
+```sh
+qamap qa . --base origin/main --head HEAD --format agent
+```
+
+## Stability policy
+
+- The output is a single JSON object on one line, followed by a newline. Nothing else is printed to stdout, and it is never colorized.
+- Every payload carries `schema: { "name": "qamap.qa", "version": 1 }`. Check both before parsing the rest.
+- Within version 1, fields are **only ever added** — existing fields are never removed, renamed, or retyped. Parse leniently: ignore fields you do not recognize.
+- A breaking change bumps `schema.version` to 2. Version 1 output will not silently change shape underneath you.
+- The machine-readable definition lives at [`schema/qamap-agent.schema.json`](../schema/qamap-agent.schema.json) and is validated against real output in the test suite.
+
+## Consuming it
+
+The intended loop for a coding agent:
+
+1. Run the command above and parse stdout as JSON.
+2. If `readiness.level` is `blocked` or `needs-work`, treat generated drafts as review-only; `requiredBootstrap` lists what unlocks the next stage.
+3. Use `flows[].changedFiles`, `flows[].evidence`, and `flows[].reviewQuestion` to understand why the flow was selected. Use `steps`, `selectors`, and `successSignal` to write or review tests; `runnable` says how much to trust the generated draft.
+4. Surface `requiredEvidence` in the PR description, and paste `prChecklist` items into the PR body.
+5. Run `commands` to validate.
+
+## Fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `schema` | object | `{ name: "qamap.qa", version: 1 }` — check before parsing. |
+| `base`, `head` | string | Git refs the diff was computed from. |
+| `project` | string | Detected project type (for example `web`, `react-native`, `node`, `unknown`). |
+| `runner` | string | Recommended E2E runner: `maestro`, `playwright`, or `manual`. |
+| `manifest` | string \| null | Verification manifest path in use, or `null` when the run used repo signals and the PR diff only. |
+| `readiness` | object | `score` (0–100) and `level` (`ready` \| `near-runnable` \| `needs-work` \| `blocked`). Human reports render the same value as a four-stage journey; the machine value is stable. |
+| `testSuite` | object | `present` (boolean) and `files` (number of detected test files). |
+| `firstDraftCommand` | string? | One command that creates the first E2E draft. Present only when the repository has no test suite and the diff reaches a product journey. |
+| `flows` | array | Affected user flows, most relevant first (capped). Each has `title`, `source`, `draft`, optional `runnable`, `entry`, and `verificationMode`, plus `changedFiles`, `reviewQuestion`, `successSignal`, `steps`, `selectors`, and short `evidence` reasons. Test-only changes expose `existingEvidence`; configuration, docs, generated artifacts, and changed tests use `verificationMode`, keep `draft` only as a fallback artifact path, and omit `firstDraftCommand` rather than inventing a required product journey. |
+| `requiredEvidence` | array | Required-priority QA evidence still missing, capped at 8: `flow`, `kind`, `title`. |
+| `recommendedEvidenceCount` | number | How many recommended-priority items were omitted; run without `--format agent` to see them. |
+| `requiredBootstrap` | array | Setup steps (capped at 3) that must happen before drafts count as regression coverage: `title`, `action`. |
+| `prChecklist` | array of string | Ready-to-paste PR checklist lines (capped). |
+| `commands` | array of string | Suggested next commands, most useful first (capped at 4). |
+
+List fields are capped to keep the payload small; caps may grow within version 1 but the shapes above will not change.
+
+## Example
+
+```json
+{"schema":{"name":"qamap.qa","version":1},"base":"main","head":"HEAD","project":"web","runner":"playwright","manifest":null,"readiness":{"score":51,"level":"needs-work"},"testSuite":{"present":false,"files":0},"firstDraftCommand":"qamap e2e setup . --runner playwright","flows":[{"title":"Checkout Submit","source":"domain-language","draft":"tests/e2e/checkout-submit.spec.ts","runnable":"near-runnable","entry":"route: /checkout (high)","changedFiles":["src/pages/checkout/index.tsx"],"reviewQuestion":"Can a reviewer confirm that Checkout Submit still works from this entrypoint and this outcome is verified: visible text Order confirmed appears?","successSignal":"visible text Order confirmed appears","steps":["Fill Email with realistic data.","Submit Submit using Checkout Submit."],"selectors":["web-test-id: checkout-submit"],"evidence":["Primary entrypoint inferred as route /checkout."]}],"requiredEvidence":[{"flow":"Checkout Submit","kind":"runner","title":"Configure Playwright execution"}],"recommendedEvidenceCount":2,"requiredBootstrap":[{"title":"Configure Playwright before making drafts required","action":"Run qamap e2e setup . --runner playwright."}],"prChecklist":["Review the generated draft path: tests/e2e/checkout-submit.spec.ts."],"commands":["npm run build"]}
+```

package/docs/agent-skill.md

@@ -8,6 +8,22 @@ The goal is not to replace a reviewer or claim QA passed. The goal is to remove
 What user flow did this PR touch, what should be tested, and what evidence is missing?
 ```
 
+## One-Command Setup
+
+The fastest way to make a repository agent-ready is:
+
+```sh
+npx @ivorycanvas/qamap init --agent .
+```
+
+It performs three idempotent steps:
+
+- adds a marked `Pre-PR QA (QAMap)` section to `AGENTS.md` (created if missing, appended if present; re-runs refresh only the marked section and never touch your own content)
+- installs the packaged skill to `.claude/skills/qamap-pr-qa/SKILL.md` so Claude Code discovers it as a project skill (a locally modified copy is left alone unless you pass `--force`)
+- creates a starter `qamap.config.json` when the repository has none
+
+After that, agents that read `AGENTS.md` or project skills will run the QA pass below on their own. The rest of this document explains what that pass does and how to wire it manually on other agent surfaces.
+
 ## Recommended Agent Step
 
 Run this before writing a PR body or asking for review. Agents should prefer the compact agent format — one minified JSON object (about 2 KB for a typical small PR) instead of a long report:
@@ -39,7 +55,7 @@ Use it when an agent surface supports local skill folders, instruction folders,
 After installing QAMap as a dev dependency, inspect the template:
 
 ```sh
-cat node_modules/qamap/skills/qamap-pr-qa/SKILL.md
+cat node_modules/@ivorycanvas/qamap/skills/qamap-pr-qa/SKILL.md
 ```
 
 Or from a cloned QAMap repository:

package/docs/benchmarking.md

@@ -1,31 +1,71 @@
 # Benchmarking QAMap
 
-`scripts/bench.mjs` scores QAMap's plan/qa output against a fixed set of repositories with pinned commits, so heuristic changes can be judged by numbers instead of feel. The runner is read-only against every target.
+QAMap's unit tests prove that the implementation behaves as coded. The benchmark contract checks a different question: does a representative PR receive a useful QA answer?
 
-## Setup
+`bench.config.json` is committed and runs in CI. Each target under `test/benchmarks/` contains a `base/` repository snapshot and a `head/` overlay. The runner materializes them as a temporary Git repository with a `main` baseline and one feature commit. QAMap reads those repositories but never installs dependencies or executes their code.
 
-1. Copy `bench.config.example.json` to `bench.config.local.json` (gitignored).
-2. Point each target at a local repository checkout, pin `base`/`head` commit SHAs, and optionally declare expectations:
-   - `expect.runner` — the runner a human would pick for this repo (`playwright`, `maestro`, `manual`).
-   - `expect.mustReachFiles` — files a human QA would name for this diff window; recall against generated flows is reported.
-   - `expect.mustNameFlows` — substrings that should appear in at least one flow title.
+## Run the public contract
 
-## Run
+```sh
+pnpm bench:ci
+```
+
+The command fails when any target violates its declared expectations. The initial corpus covers:
+
+- a web app with no tests;
+- a web app with Playwright and an existing mock handler;
+- an Expo app with Maestro;
+- an API service that should produce a contract checklist instead of a browser journey;
+- a design-token repository that should stay on artifact verification;
+- a shared component change that must reach its consuming page through reverse imports;
+- an Expo native configuration-only change that must stay out of product journeys and prefer existing build commands;
+- a Maestro test-only change that must run existing evidence instead of generating a duplicate journey.
+
+## Expectations
+
+Each target can declare:
+
+| Field | Meaning |
+| --- | --- |
+| `runner` | Expected `playwright`, `maestro`, or `manual` recommendation. |
+| `minFlows` | Minimum number of affected flows. |
+| `minImportPropagatedFlows` | Minimum flows discovered through reverse imports. |
+| `minDiffAnchoredFlows` | Minimum flows using selector evidence introduced by the diff. |
+| `mustReachFiles` | Files that the selected flows must reach. |
+| `mustNameFlows` | Product terms that must appear in a user-facing flow title. |
+| `mustNotNameFlows` | Misleading flow-title terms that must not be emitted. |
+| `mustDraftFiles` | Expected generated draft path fragments. |
+| `mustIncludeSteps` | Behavior terms that must appear in draft steps. |
+| `mustFindSelectors` | Stable selector evidence that must be recovered from the repository. |
+| `mustFindSuccessSignals` | Observable outcome text that must appear in the flow's success criteria. |
+| `mustFindEvidence` | Required evidence or fixture terms that must be reported. |
+| `mustNotFindEvidence` | Evidence terms that would be false positives for this change. |
+| `mustRecommendCommands` | Commands the setup or validation path must expose. |
+| `maxBlankActions` | Maximum malformed or empty draft steps; public fixtures keep this at zero. |
+| `maxGenericTitles` | Maximum titles ending in generic `primary journey` or `smoke flow` wording. |
+| `maxAgentBytes` | Maximum UTF-8 payload size for `qa --format agent`. |
+
+## Local repositories
+
+Private or large repositories remain useful as a local smoke layer. Copy `bench.config.example.json` to `bench.config.local.json`, pin base/head SHAs, and run:
 
 ```sh
-pnpm bench                      # table only
-node scripts/bench.mjs --save   # also writes bench-results/<timestamp>.json
-node scripts/bench.mjs --baseline bench-results/<file>.json   # delta vs a saved run
+pnpm bench
+node scripts/bench.mjs --save
+node scripts/bench.mjs --baseline bench-results/<file>.json
 ```
 
-## Metrics
+When both files exist, `pnpm bench` prefers the gitignored local config. CI always passes `--config bench.config.json --assert`, so private paths cannot affect the public quality gate.
+
+Saved results include flow titles, draft paths, recall gaps, readiness, agent payload size, and timing. Use a saved baseline to see heuristic movement, but treat the committed expectation contract as the merge gate.
+
+## Adding a regression
+
+When a real repository produces a poor recommendation:
 
-- `runner` mismatch lines — wrong tool recommendation for a known repo shape.
-- `viaImport` — flows produced through the reverse import graph (shared-file changes reaching surfaces).
-- `diffAnchor` — flows whose selector set includes at least one selector introduced by the diff itself; higher means drafts act on what the change added instead of pre-existing UI.
-- `blank` — steps with blank action slots (must stay 0).
-- `generic` — flows with content-free names (`... primary journey`, `... smoke flow`); lower is better.
-- `reach` — recall of `mustReachFiles`; missing files are listed per target.
-- `agentBytes` — size of the `--format agent` payload.
+1. Reduce it to the smallest reproducible `base/` and `head/` fixture.
+2. Write the human expectation in `bench.config.json` before changing heuristics.
+3. Confirm `pnpm bench:ci` fails for the intended reason.
+4. Fix the inference and keep the fixture as permanent regression evidence.
 
-Re-run with `--baseline` before merging heuristic changes; a PR that moves these numbers should say so in its body.
+Do not copy proprietary code, credentials, or production data into a public fixture.

package/docs/commands.md

@@ -0,0 +1,242 @@
+# Command Reference
+
+Every QAMap command, with what it produces and when to reach for it. For the shortest path, see the [README](../README.md) quick start; for rollout order, see [adoption](adoption.md).
+
+## Quick Commands
+
+```sh
+pnpm exec qamap qa . --base origin/main --head HEAD
+pnpm exec qamap qa . --base origin/main --head HEAD --format agent
+pnpm exec qamap qa . --manifest /tmp/qamap-manifest.yaml --base origin/main --head HEAD --output QAMAP_QA.md
+pnpm exec qamap scan .
+pnpm exec qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md
+pnpm exec qamap manifest context .
+pnpm exec qamap manifest init .
+pnpm exec qamap manifest validate .
+pnpm exec qamap manifest explain . --base origin/main --head HEAD
+pnpm exec qamap e2e draft . --base origin/main --head HEAD --dry-run
+```
+
+Use `pnpm dlx @ivorycanvas/qamap ...` for one-off runs without installing QAMap into the target repository.
+
+## Reading The Output
+
+Human-facing reports (`text` and `markdown` formats) open with an **At a Glance** section: affected behavior, the reviewer question to answer before merge, concrete repository evidence, the proposed draft path, the next command, and the one or two missing trust requirements. When printed to an interactive terminal the report is colorized (headings, statuses, priority tags, inline commands); files written with `--output`, pipes, CI logs, and the machine formats (`json`, `agent`, `sarif`) are always plain. The standard `NO_COLOR` and `FORCE_COLOR` environment variables are honored.
+
+Draft readiness is reported as a **stage on a fixed four-step journey**, for example `Stage: setup needed (1 of 4) — readiness 0/100`. A fresh repository usually starts at stage 1 — that is the expected starting point, not a failure. Each stage maps to a stable `readiness.level` value in the `json` and `agent` formats, which keeps machine output unchanged:
+
+| Stage line | JSON `readiness.level` | Meaning |
+| --- | --- | --- |
+| `setup needed (1 of 4)` | `blocked` | Drafts describe the flow but need runner config or other required setup before they can run. |
+| `draft in progress (2 of 4)` | `needs-work` | Drafts exist; close the required action items to make them runnable. |
+| `almost runnable (3 of 4)` | `near-runnable` | Run the drafts locally and clear the remaining review items. |
+| `ready to run (4 of 4)` | `ready` | Drafts are ready to try as local regression evidence. |
+
+
+## What QAMap Produces
+
+On a changed branch, QAMap tries to produce reviewable verification artifacts instead of only saying "write more tests":
+
+- a branch-aware verification plan that names the changed domain, actor, trigger, goal, success signal, and edge cases
+- draft Playwright, Maestro, CLI command, or manual checklist files when the repository shape supports them
+- a repo-level verification manifest loop where humans correct durable flows once and later PRs get sharper route/check/test draft suggestions
+- a runner setup proposal that explains why Playwright or Maestro fits the changed surface and which files/commands would be created if the team accepts it
+- readiness evidence that explains missing runner config, selectors, fixture data, assertions, validation commands, or flow manifests
+- repo-local suggestions for `.qamap/domains.yml`, `.qamap/flows.yml`, and ignored `.qamap/runs/` history so teams can improve the next run without spending LLM tokens
+
+That means QAMap is most valuable when it becomes the team's verification base: humans define the durable language and critical flows once, QAMap reuses that base on each PR, and generated observations stay local unless the team intentionally promotes them into shared policy.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `qamap scan .` | Scan the current repository and print a text report. |
+| `qamap scan . --fail-on medium` | Exit with code `1` when findings at or above the threshold exist. |
+| `qamap scan . --json` | Print machine-readable JSON for custom automation. |
+| `qamap scan . --format sarif --output qamap.sarif` | Generate SARIF for code scanning integrations. |
+| `qamap report . --output QAMAP_REPORT.md` | Generate a Markdown report for PRs or audits. |
+| `qamap doctor . --format markdown` | Summarize whether the repo is ready for AI-assisted work. |
+| `qamap review . --base origin/main --head HEAD --format markdown` | Show new findings and changed risky files introduced by a branch. |
+| `qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md` | Combine review findings, readiness scoring, domain tests, and next actions. |
+| `qamap eval . --base origin/main --head HEAD --pr-body-file pr-body.md` | Score change readiness across intent, risk, tests, and review size. |
+| `qamap github-action . --mode review --base origin/main --head HEAD` | Generate GitHub Action annotations, step summary, and PR comment body. |
+| `qamap test-plan . --base origin/main --head HEAD --include-working-tree` | Suggest domain test scenarios for changed files. |
+| `qamap qa . --base origin/main --head HEAD` | One-command PR QA: affected flows, missing QA evidence, a PR checklist, and E2E starter drafts, opening with At a Glance. |
+| `qamap qa . --base origin/main --head HEAD --format agent` | The same decision content as one ~2-4KB JSON line for coding agents — a versioned contract documented in [docs/agent-format.md](agent-format.md). |
+| `qamap e2e plan . --base origin/main --head HEAD` | Suggest E2E runner, bootstrap steps, user flows, coverage targets, existing test evidence, and missing testability hooks for changed files. |
+| `qamap e2e plan . --base origin/main --head HEAD --record-history` | Save a compact local run snapshot under `.qamap/runs/` while keeping JSON/Markdown output usable. |
+| `qamap e2e setup . --runner playwright` | Explicitly apply the accepted runner setup and create the first changed-flow E2E draft without overwriting existing files. |
+| `qamap e2e draft . --base origin/main --head HEAD --dry-run` | Preview generated Maestro, Playwright, or manual E2E drafts without writing files. |
+| `qamap e2e draft . --base origin/main --head HEAD` | Write generated Maestro, Playwright, or manual E2E drafts with flow language, readiness summaries, and action items. |
+| `qamap manifest init .` | Create a baseline `.qamap/manifest.yaml` with inferred domains, flows, anchors, checks, source, and confidence. |
+| `qamap manifest validate .` | Check whether `.qamap/manifest.yaml` is present, parseable, anchored to real files, and ready to shape PR evidence. |
+| `qamap manifest context .` | Preview repo-local context sources, role classifications, validation commands, safety rules, and manifest repair diagnostics. |
+| `qamap manifest explain . --base origin/main --head HEAD` | Explain which manifest domains, flows, and checks match the current branch and which manifest path to edit if the match is wrong. |
+| `qamap flows init .` | Create a starter `.qamap/flows.yml` for team-approved core flow definitions. |
+| `qamap flows suggest . --base origin/main --head HEAD` | Generate suggested `.qamap/flows.yml` entries with commit-readiness guidance from changed files and E2E plan context. |
+| `qamap domains init .` | Create a starter `.qamap/domains.yml` for shared product/domain language. |
+| `qamap domains suggest . --base origin/main --head HEAD` | Generate suggested `.qamap/domains.yml` entries with commit-readiness guidance from changed files and inferred product language. |
+| `qamap history init .` | Create local QAMap history directories and protect generated run history with `.gitignore`. |
+| `qamap doctor services/listing --workspace-root .` | Scan a monorepo package while using root guardrails. |
+| `qamap context . --write AGENTS.md` | Generate starter agent instructions for the repo. |
+| `qamap init .` | Create a starter `qamap.config.json`. |
+| `qamap init --agent .` | One-command agent onboarding: add a marked QAMap Pre-PR QA section to `AGENTS.md`, install the packaged skill to `.claude/skills/qamap-pr-qa/SKILL.md`, and create `qamap.config.json` if missing. Idempotent; existing `AGENTS.md` content is preserved. |
+
+For monorepos, pass `--workspace-root` when scanning a package. Package-local checks still use the package directory, while repo-level guardrails such as `AGENTS.md`, `.github/workflows`, `LICENSE`, `SECURITY.md`, and `CONTRIBUTING.md` are read from the workspace root.
+
+`qamap review` compares a branch against a base ref for PR-style workflows. It separates newly introduced findings from risky files that already had findings on the base branch but were modified again, which helps reviewers notice when a PR touches known-dangerous surfaces such as committed `.env` files, MCP configs, or release scripts.
+
+`qamap verify` is the easiest PR-facing command. It combines `review`, `test-plan`, and `eval` into one report with review findings, readiness gates, suggested domain tests, suggested commands, and next actions.
+
+`qamap test-plan` turns changed file paths into a review-ready domain test checklist. It also discovers common validation commands from `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, Gradle files, and Maven `pom.xml`. Add `--include-working-tree` for local, uncommitted changes while iterating.
+
+`qamap e2e plan` turns changed file paths into a first-pass E2E testing plan. It detects whether a project looks like Expo/React Native, web, API/service, or CLI package, recommends a runner such as Maestro or Playwright, starts backend services with an API contract checklist, starts executable packages with a CLI command verification checklist, suggests bootstrap steps for repos with little or no test history, suggests domain language for the changed behavior, suggests candidate user flows, adds coverage targets, compares those targets with existing test-suite evidence when tests are present, flags API-dependent flows that need mock or fixture responses, and points out missing stable selectors such as `testID` or `data-testid` before anyone starts writing tests from a blank file.
+
+The plan also includes an execution profile: detected start command, test command, Playwright `baseURL`, mobile app id, runner config files, env fixture files, confidence, and blockers. This keeps generated E2E drafts honest about whether they are runnable candidates or still review-only scaffolds.
+
+When a repository does not already have the selected E2E runner, the plan includes a runner setup proposal instead of silently changing the project. The proposal explains why the runner fits the changed surface, which package command installs the library, which config/script files would be created, and the explicit acceptance command such as `qamap e2e setup . --runner playwright`.
+
+`qamap e2e setup` is the opt-in apply step. For Playwright it can create `playwright.config.ts`, `tests/e2e/`, a `test:e2e` script, and the first changed-flow Playwright spec. For Maestro it can create `.maestro/`, `.maestro/README.md`, a `test:e2e` script, and the first changed-flow YAML draft. Existing draft files are skipped unless `--force` is passed. It does not run package installation automatically; it prints the install command so teams can keep dependency policy under review.
+
+When run at a monorepo root, the E2E plan also reports changed app/package targets. This helps a maintainer move from a broad workspace diff to scoped commands such as `qamap e2e plan services/listing --workspace-root . --base origin/main --head HEAD`, where package-specific runner detection and flow naming are usually sharper.
+
+Each candidate flow also includes a flow language brief: actor, trigger, goal, success signal, reviewer question, and edge cases. The brief keeps generated tests tied to product behavior rather than only changed file names.
+
+The bootstrap section answers what must happen before generated drafts can be treated as real regression coverage. For example, a testless web project can get required steps for Playwright setup, first draft generation, stable selector work, fixture/mock data, and missing validation evidence, plus recommended steps for `.qamap/manifest.yaml`, `.qamap/domains.yml`, `.qamap/flows.yml`, and local history recording.
+
+Run `qamap manifest init .` to create a baseline verification manifest. QAMap infers domains, flows, route/component anchors, checks, runner hints, source, and confidence from the current checkout.
+
+The scan reads up to 2,500 files by default (alphabetically, skipping vendor trees such as `node_modules`, `Pods`, `.gradle`, and build output). The init summary reports how many files were scanned, and warns when the scan stopped at the cap — on very large repositories rerun with `--max-files` so domains and flows are inferred from the whole project.
+
+Validation commands come from two sources, ground truth first: `package.json` scripts whose names look like verification (`test`, `lint`, `typecheck`, `check`, `e2e`, `coverage`, `build`, …) plus a detected pytest setup, then commands found in instruction docs — inline code spans (like a `pnpm test` mentioned in a sentence) anywhere, and bare command lines only when they sit inside fenced code blocks. Prose sentences that merely mention a tool name are not treated as commands. Scripts that block, open a UI, or mutate state (`test:watch`, `e2e:open`, `test:update`, `lint:fix`, …) are excluded. Safety rules are only harvested from prose lines that state a prohibition or obligation (`never …`, `do not …`, `절대/금지 …`); code blocks, CI YAML, and diagram fragments inside instruction docs are ignored.
+
+> **Important:** create the shared team baseline from the repository's default branch, after pulling the latest changes. QAMap does not silently switch branches or rewrite the repository state, so running `manifest init` from a feature branch creates a feature-branch snapshot, not the team's default QA map.
+
+```sh
+git switch main
+git pull
+qamap manifest context .
+qamap manifest init . --write .qamap/manifest.yaml
+```
+
+`qamap manifest context .` is a read-only preview of the repo-local knowledge QAMap can see before writing the manifest. It reports context sources such as `CONTEXT.md`, ADRs, goals, runbooks, agent instructions, harness files, and skills under agent directories (`.claude/`, `.codex/`, `.agent-core/`, `.github/instructions/`), then shows role classifications, validation commands, safety rules, and diagnostics for stale or missing context.
+
+After the baseline is committed, feature branches should usually run `manifest explain`, `e2e plan`, or `e2e draft` against the PR base such as `origin/main`. The manifest is not meant to be perfect on the first run. It is meant to start the feedback loop: QAMap recommends E2E work from the manifest, shows why a recommendation happened, and points to the manifest path to edit when the recommendation is wrong.
+
+Generated manifests include a `$schema` reference to `schema/qamap-manifest.schema.json`, so teams can validate and edit `.qamap/manifest.yaml` with a documented contract. See [docs/manifest.md](manifest.md) for the full field guide and adoption workflow.
+
+Use `qamap manifest validate .` before treating the manifest as shared team policy. It reports missing manifests, invalid YAML/schema shape, duplicate ids, missing domain paths, stale anchor files, suspicious route hints, and low-confidence inferred entries that should be reviewed.
+
+Use `qamap manifest explain . --base origin/main --head HEAD` when you want to understand one branch. It reads the git diff, lists the matched manifest domains/flows/checks, shows the declared entry route and required checks, and names the exact manifest path to update if the recommendation is wrong.
+
+When `.qamap/manifest.yaml` exists, `qamap verify`, `qamap e2e plan`, and `qamap e2e draft` include a Manifest Recommendations section:
+
+```txt
+Why this was recommended:
+- Changed files match anchors for the Bundle Submission Complete flow.
+
+Manifest evidence:
+- .qamap/manifest.yaml > flows.bundle-submission-complete.anchors
+
+Next actions:
+- Draft or review E2E coverage for the Bundle Submission Complete flow.
+- Cover the declared checks: Submit media link successfully; Show validation error for invalid media link.
+
+If this is wrong:
+- Update .qamap/manifest.yaml > flows.bundle-submission-complete.anchors
+
+Repair hints:
+- If these files do not belong to this flow, update .qamap/manifest.yaml > flows.bundle-submission-complete.anchors.
+- If the recommended assertions feel vague, rewrite .qamap/manifest.yaml > flows.bundle-submission-complete.checks in team language.
+```
+
+When a matched manifest flow has an entry route and checks, `qamap e2e draft` promotes it ahead of heuristic candidates. The generated Playwright, Maestro, or manual draft carries the manifest evidence, uses the manifest route as an entrypoint when possible, and turns manifest checks into draft steps and required coverage notes. If a check includes concrete hints such as `[data-testid=coupon-input]`, `with WELCOME10`, or optional `selector`, `value`, and `steps` fields, QAMap uses those facts before falling back to fuzzy selector inference. This is the core cost-saving loop: humans fix durable QA context once, then future PRs start from a stronger draft instead of a blank test file.
+
+Flow and scenario names prefer what the diff itself introduced: an added `aria-label`/`data-testid`/`testID`/placeholder value or button/link inner text with an action word names the journey ("Checkout Apply Coupon" instead of "Checkout primary journey"). Korean action labels qualify the same way — `저장하기` and 35 other common stems, with `~하기/~합니다`-style endings normalized — and draft filenames keep Hangul. When a diff changes only logic or styles (no labeled elements added), the surface's primary action-bearing control names the journey instead.
+
+The domain language section is intentionally less implementation-oriented than the raw file list. For example, changes under `src/features/in-app-purchase/` become terms such as `In App Purchase` and scenarios such as `In App Purchase primary journey`. When a changed component or service file names a concrete behavior, QAMap should prefer that behavior before the generic primary journey: `src/features/listing/components/MediaLinkSubmitModal.tsx` can become `Listing Media Link Submit`, and the generated draft file can become `.maestro/listing-media-link-submit.yaml`. When `.qamap/domains.yml` exists, declared product terms and routes receive higher confidence. When `.qamap/flows.yml` exists, team-approved flow names appear as preferred scenario names.
+
+If `.qamap/domains.yml` exists, `qamap e2e plan` also matches changed files against shared product or domain language:
+
+```yaml
+domains:
+  - id: billing
+    name: Billing
+    aliases:
+      - checkout
+      - subscription
+    files:
+      - src/features/billing/**
+    routes:
+      - /billing
+    scenarios:
+      - title: Billing primary journey
+        checks:
+          - Start from the normal billing entry point.
+          - Complete the primary billing action with realistic data.
+```
+
+Run `qamap domains init .` to create a starter domain manifest. Run `qamap domains suggest . --base origin/main --head HEAD` when you want QAMap to draft manifest entries from the current branch and classify each candidate as `commit-candidate`, `needs-review`, or `low-signal`. Use domains for naming and route hints; use core flows when the team wants to define a durable verification journey.
+
+If `.qamap/flows.yml` exists, `qamap e2e plan` also matches changed files against team-approved core flows. This lets maintainers encode the product or domain flows humans already care about:
+
+```yaml
+flows:
+  - id: checkout-purchase
+    name: Checkout purchase
+    priority: critical
+    domains:
+      - checkout
+    files:
+      - src/pages/checkout/**
+      - src/features/checkout/**
+    routes:
+      - /checkout
+    checks:
+      - Complete checkout with a valid payment method.
+      - Verify declined payment recovery.
+```
+
+Run `qamap flows init .` to create a starter manifest. Run `qamap flows suggest . --base origin/main --head HEAD` when you want QAMap to draft flow entries from changed files, inferred domain language, routes, and E2E checks, then classify which entries are close enough to review as shared policy. Unlike generated run history, `.qamap/flows.yml` is meant to be reviewed and committed when those flow definitions should become team policy.
+
+Pass `--record-history` when you want QAMap to keep a compact local snapshot of an E2E plan under `.qamap/runs/`. QAMap automatically protects `.qamap/runs/`, `.qamap/cache/`, `.qamap/tmp/`, and `.qamap/*.local.json` with `.gitignore` so generated history stays local by default. Shared project policy, such as `qamap.config.json`, `.qamap/domains.yml`, and `.qamap/flows.yml`, remains commit-friendly.
+
+`qamap e2e draft --dry-run` previews the same draft analysis without creating directories or files. Use it first when evaluating a new repository or PR. The output still includes planned file paths, self-checks, readiness status, action items, starter-code gaps, and execution blockers.
+
+`qamap e2e draft` writes draft files from that plan. Expo and React Native projects get Maestro YAML flows under `.maestro/` by default, web projects get Playwright specs under `tests/e2e/`, API/service projects get contract checklist drafts, and CLI packages get command verification checklists until a project-specific runner is documented. For web apps, QAMap recognizes common Next.js, React Router, Vite, Vue/Nuxt, Svelte, Remix, Astro, and Angular signals. It can infer routes from Next Pages Router files, Next App Router files such as `src/app/(group)/products/[id]/page.tsx`, React Router `path` objects, links, and imperative navigation calls. Drafts infer stable selectors such as `testID`, `accessibilityLabel`, `data-testid`, `aria-label`, placeholder text, role-based buttons or links, and visible text where possible. They also carry fixture/mock readiness notes and inferred API endpoint hints. When the repository already contains mock, fixture, or seed files, QAMap statically reads their contents and turns the fixture guidance into named instructions — which handler file to extend for which uncovered endpoint, or which exported mock data to reuse — and exposes the matched files as `mockInsights` on `fixtureReadiness` in JSON output. Client-only flows may get sample Playwright response scaffolds whose bodies reuse the response keys observed in the matched fixture file, but endpoints changed by the PR are observed rather than intercepted with synthetic responses so the generated draft does not hide the contract under test. When selectors or route params are incomplete, QAMap now prefers runnable starter code with safe smoke assertions and sample params over non-executable placeholder locators. Existing files are not overwritten unless `--force` is passed.
+
+The draft result is meant to be useful as a PR artifact, not only as generated files. Markdown and JSON output include:
+
+- `languageBrief`: actor, trigger, goal, success signal, reviewer question, and edge cases for each draft file
+- `promotionStatus`: whether the draft is a `commit-candidate`, `needs-review`, or `low-signal`
+- `runnableStatus`: whether the draft is a `runnable-candidate`, `near-runnable`, or `review-only`
+- selectors carry `addedInDiff: true` when the value was introduced by the diff itself, so agents can bind actions to what the change added
+- `selfCheck`: static runner checks for generated draft structure, unresolved placeholders, starter-code quality, and the execution profile
+- `status`: whether the file was `preview`ed by `--dry-run`, `created`, or `skipped`
+- `actionItems`: required and recommended follow-up work, grouped by assertion, fixture, selector, runner, validation, and manifest
+- `actionSummary`: total required/recommended action counts, ready file count, and the most common action categories
+- `readinessSummary`: an overall 0-100 score, readiness level, self-check counts, starter-code gaps, execution blocker counts, and top blockers
+
+See [docs/e2e-output-examples.md](e2e-output-examples.md) for compact examples of web, mobile, API/service, CLI, test-light, and monorepo output.
+
+Generated Playwright drafts use the flow language as `test.step()` names so the file reads like the user journey it protects:
+
+```ts
+await test.step("Open route /checkout.", async () => {
+  await page.goto("/checkout");
+});
+
+await test.step("Complete checkout with a valid payment method.", async () => {
+  // Step intent: Complete checkout with a valid payment method.
+  await page.getByTestId("checkout-submit").click();
+});
+
+await test.step("Fill profile email.", async () => {
+  // Step intent: Fill profile email.
+  await page.getByPlaceholder("Profile email").fill("qamap@example.com");
+});
+```
+
+`qamap history init` prepares that local storage explicitly without running an analysis. It creates `.qamap/runs/`, `.qamap/cache/`, and `.qamap/tmp/`, then adds the generated-history ignore patterns to `.gitignore` idempotently.
+
+`qamap eval` scores whether a branch has enough validation evidence, changed-test coverage, intent capture, risk explanation, domain verification paths, and reviewable size. In GitHub Actions, QAMap can read the pull request body from the event payload and append the evaluation to the PR comment.

package/docs/configuration.md

@@ -274,4 +274,15 @@ High-confidence terms usually come from committed core flows or domain manifests
 - Playwright route fulfillment helpers
 - mock data files that match the changed domain
 
+File-name conventions are matched as whole name tokens (`demoSeedService.ts`, `mock-users.json`), never as substrings, so ordinary source files such as `useSeedlingCatalog.ts` or `errorHandler.ts` are not misread as fixtures.
+
 If a client flow calls an API but the branch does not include backend, mock, or fixture evidence, the E2E plan marks fixture readiness as `missing` and the generated draft includes next actions for deterministic success and failure responses. This lets teams validate UI and flow behavior before the real server implementation is complete.
+
+QAMap also reads the contents of the discovered mock and fixture files (up to 24 per plan, statically, without executing anything) and extracts their exported symbols, the routes their handlers already serve (MSW `rest.*`/`http.*` handlers, Mirage and express-style routes, Playwright `route(...)` patterns), and the response keys they use. That analysis turns generic advice into named instructions:
+
+- when an existing handler file already covers some of the flow's endpoints, the next action says which file to extend and which endpoints are still uncovered (for example `Extend src/mocks/handlers.ts (already handles /api/invoices) to also cover /api/payments/summary`)
+- when a mock or seed module exports reusable data, the next action names the export to reuse for the uncovered endpoint
+- generated Playwright drafts fill `mockApiResponses` bodies with the response keys observed in the matched fixture file instead of a generic placeholder, and note which file the shape came from
+- the fixture action item title carries the affected endpoints, so the compact `--format agent` output keeps the concrete target
+
+The matched insights are exposed as an optional `mockInsights` array (file, exports, handled endpoints, sample keys) on each flow's `fixtureReadiness` in the JSON output.

package/docs/e2e-output-examples.md

@@ -19,7 +19,7 @@ Summary
 - Project: Web
 - Recommended runner: Playwright
 - Manifest: not found; using repo signals and PR diff only
-- Readiness: near-runnable
+- Stage: almost runnable (3 of 4)
 
 PR Comment Draft
 - Affected flow: Checkout UI smoke flow
@@ -349,7 +349,7 @@ Draft action items should make the next developer action explicit:
 
 ```txt
 Action summary:
-- readiness score: 64/100 (needs-work)
+- readiness stage: draft in progress (2 of 4), score 64/100
 - runnable status: near-runnable
 - self-check: pass or warning based on generated starter code and execution profile
 - top blocker: No Playwright config file was detected.
@@ -363,13 +363,17 @@ Action summary:
 
 When a client-side change calls an API path but the branch does not include backend or fixture evidence, QAMap should name that as a readiness gap and still give the tester a concrete mock slot:
 
-If reusable repo-local evidence already exists, the PR QA output should point at it instead of only saying "add a fixture":
+If reusable repo-local evidence already exists, the PR QA output reads its contents (exports, handled routes, response keys) and points at the concrete thing to reuse instead of only saying "add a fixture":
 
 ```txt
 Missing evidence before trusting this PR
-- [recommended] fixture: Confirm fixture coverage - Reuse or extend existing fixture/mock evidence for this flow: src/services/demoSeedService.ts, src/services/metricsMockService.ts.
+- [recommended] fixture: Confirm fixture coverage for /api/sentiments/current - Reuse src/services/demoSeedService.ts (exports demoSeedService) to build a deterministic response for /api/sentiments/current.
 ```
 
+When an existing handler file already covers part of the flow, the next action names the file and the still-uncovered endpoints, for example `Extend src/mocks/handlers.ts (already handles /api/invoices) to also cover /api/payments/summary`. The generated Playwright mock bodies then reuse the response keys observed in that file (`invoices: "qamap-invoices"`) instead of the generic placeholder below, with a comment noting the source file.
+
+When no fixture file contents are available, the draft falls back to the generic placeholder:
+
 ```ts
 const mockApiResponses = {
   "**/api/orders/fixture-order-id": {