qamap-pr-qa

name	qamap-pr-qa
description	Local zero-LLM PR QA workflow. Use when an agent is preparing, updating, finalizing, or reviewing a pull request, asks what the PR should test, or needs commit-backed change intent, affected behavior, QA scenarios, evidence, validation commands, optional automation drafts, and manifest repair guidance.

QAMap PR QA

Use QAMap as a final local QA pass before presenting a pull request for human review.

Workflow

1. Detect the comparison base.

   • Prefer the target PR base branch when known.
   • Otherwise use origin/main, then origin/master, then the repository default branch.

2. Run QAMap from the repository root. Prefer the compact agent format — it carries the same decision content as the markdown report in a fraction of the tokens:

   npm exec --yes --registry=https://registry.npmjs.org --package=@ivorycanvas/qamap@latest -- qamap qa . --base <base> --head HEAD --format agent
   

   This one-off form runs outside the target repository's package-manager contract, so it does not invoke Corepack or add a packageManager field. For a project that already installs QAMap, prefer its local binary, for example:

   pnpm exec qamap qa . --base <base> --head HEAD --format agent
   

   Drop --format agent when a human will read the output directly; the default markdown report is written for people. The agent JSON is a versioned contract (schema: qamap.qa v1, additive-only): see docs/agent-format.md in the QAMap repository.

3. Read analysisScope before interpreting package-relative evidence or commands.

   • automatic-package means the root command already reran analysis with the selected package's routes, scripts, fixtures, and runner settings. Run package-relative commands from selectedPath; use the workspace-aware automation.draftCommand as printed.
   • repository-root means QAMap could not safely select one package. Review candidates and reason; do not silently choose a package for a cross-package or root-spanning change.
   • Use an explicit scoped pass only when a human wants to override that decision:

   npm exec --yes --registry=https://registry.npmjs.org --package=@ivorycanvas/qamap@latest -- qamap qa <package-path> --workspace-root . --base <base> --head HEAD
   

4. Read and verify intent before generating code. In agent format:

   • route — the canonical applicable decision. Use status, nextAction, and the optional exact command before looking at legacy readiness scores. A verification-* status means use repository validation; a draft-* status describes optional automation preparation.
   • intents[] — commit/diff evidence, confidence, reviewRequired, ordered lifecycle, and primary/failure/boundary/state-transition scenarios. Read each scenario's structured sources before accepting it; a diff source carries file, head-side line numbers, symbol, and hunk.
   • testContracts — behavior declared by tests added in this diff, with framework and file:line. Preserve these expectations, but do not report them as passed while execution is not-run.
   • If reviewRequired is true or the lifecycle conflicts with the PR, ask a human to confirm the intended behavior before promoting a draft.
   • flows[] — affected flows with draft path, runnable status, entry route, evidence-matched focus, capped steps, and selectors. Prefer focus.action and focus.assertion when stating what changed and what should be observed; steps[0] may only be setup.
   • requiredEvidence[] — evidence that must exist before the PR can be trusted; recommendedEvidenceCount for the rest.
   • requiredBootstrap[] — non-runner repository context that still needs clarification.
   • automation — an optional adapter handoff. It is not required to use the QA judgment.
   • prChecklist[] and commands[] — checklist lines and validation commands for the handoff.

5. Follow the route.nextAction contract:

   • run-repository-command — run the exact existing route.command from the selected analysis scope when permissions allow.
   • define-repository-command — do not invent a passing command. Report the missing repository validation contract.
   • review-and-run-draft — preview the printed automation.draftCommand first. Write or execute the draft only after the scenario and adapter are accepted.
   • complete-draft-evidence — report the first required evidence gap. Do not install a runner or fabricate a selector, fixture, action, or assertion.

6. Only after a human or team accepts the scenario and automation adapter, create or preview executable coverage:

   npm exec --yes --registry=https://registry.npmjs.org --package=@ivorycanvas/qamap@latest -- qamap e2e draft . --base <base> --head HEAD --dry-run
   

   If the selected adapter is absent, inspect and explicitly accept the automation.setupCommand proposal. Never install a runner merely because QAMap detected a web or mobile surface.

7. Include the useful parts in the PR body, review note, or handoff summary.

Agent Action Contract

• Choose exactly one immediate next action from route.nextAction. Do not dump every possible command on the user.
• Verify the strongest scenario source before acting. If it has no exact diff location or is marked reviewRequired, ask one precise question instead of generating code.
• Treat QAMap's execution.status: "not-run" as authoritative. Only a command that this agent actually ran can produce a pass, fail, blocked, or not-verifiable receipt.
• Report QAMap analysis and later command execution as separate facts. A generated or structurally runnable draft is not a passing test.
• Never modify a shared manifest automatically. Present the proposed correction target and require human approval.

Output Rules

• Treat QAMap output as QA planning evidence, not proof that browser, device, API, or manual QA passed.
• Prefer route over compatibility readiness.level. In particular, do not call repository validation blocked merely because the optional-automation score is blocked.
• Preserve change intent, confidence, lifecycle, QA scenarios, their strongest file/line sources, affected flow, missing evidence, and validation command in the handoff.
• Preserve flows[].focus when present. It is the compact changed action and observable proof, not a replacement for the surrounding ordered steps.
• Keep automation optional until the scenario and its evidence have been reviewed.
• Treat Playwright, Maestro, and manual output as adapters after QA design. Do not let runner selection replace review of the inferred intent and scenarios.
• If the output is review only or near runnable, explain what blocks it from becoming trusted regression evidence.
• If qamap qa says no manifest was found, do not stop. The first run is allowed to be manifest-free.

Manifest Repair

When the recommendation is wrong or too broad, do not repeatedly re-prompt for the same QA context. Ask the maintainer which domain, flow, anchor, or check should be corrected.

If the team accepts QAMap for ongoing use, suggest this follow-up:

npm exec --yes --registry=https://registry.npmjs.org --package=@ivorycanvas/qamap@latest -- qamap manifest init .

Then humans should review .qamap/manifest.yaml and keep only durable team QA language.

Handoff Template

QAMap QA
- Change intent and confidence:
- Behavior lifecycle:
- Required QA scenarios:
- Changed repository test contracts:
- Scenario source files/lines:
- Affected flow:
- Suggested E2E/checklist:
- Missing evidence:
- Selected next action:
- Action taken:
- Execution receipt: not run | passed | failed | blocked | not verifiable
- Manifest repair needed: