@ivorycanvas/qamap 0.3.5 → 0.4.1

package/docs/agent-format.md

@@ -1,6 +1,6 @@
 # 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.
+`qamap qa --format agent` prints one compact line of JSON designed to be pasted into a coding agent's context instead of the full markdown report. The complete line is capped at 8KB. When the uncapped result would be larger, QAMap preserves the strongest evidence and reports total and omitted counts instead of silently overflowing the context budget. 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
@@ -19,10 +19,11 @@ qamap qa . --base origin/main --head HEAD --format agent
 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.
+2. Read `intents` first. Confirm its confidence, lifecycle, and QA scenarios. Inspect `scenarios[].sources` before accepting a recommendation: diff sources identify the base/head file, line, symbol, hunk, and relation that caused the scenario to be proposed. `direct` is scenario-specific evidence, `supporting` completes the lifecycle, and `contextual` explains intent but cannot independently promote a scenario to critical. When `reviewRequired` is true, ask a human to confirm it.
+3. Treat `readiness` as automation readiness, not as a verdict on the PR. `requiredBootstrap` contains non-runner repository context only; runner adoption lives under the opt-in `automation` object.
+4. 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.
+5. Surface `requiredEvidence` in the PR description, and paste `prChecklist` items into the PR body.
+6. Run `commands` to validate.
 
 ## Fields
 
@@ -31,15 +32,20 @@ The intended loop for a coding agent:
 | `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`. |
+| `runner` | string | Automation output adapter selected after QA intent analysis: `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. |
+| `intentCount`, `omittedIntentCount` | number | Total inferred intents and the count omitted from the compact payload. |
+| `intents` | array | Evidence-backed change intents (capped). Each includes `title`, `confidence`, `reviewRequired`, backward-compatible string `evidence`, structured `sources`, ordered `lifecycle` phases, and runner-independent QA `scenarios`. Every compact scenario carries `confidence`, `reviewRequired`, structured `sources`, and assertions; `scenarioCount` and `omittedScenarioCount` disclose capping. Empty when commit and diff evidence cannot support a behavior intent. |
+| `firstDraftCommand` | string? | Deprecated v1 compatibility field. New output omits it so runner setup is not promoted as the default QA action. |
+| `automation` | object? | Explicitly optional adapter handoff: `optIn`, `adapter`, `setupStatus`, `draftCommand`, and optional `setupCommand`. Use it only after the QA scenario is accepted. |
+| `flowCount`, `omittedFlowCount` | number | Total affected flows and the count omitted from the compact payload. |
+| `flows` | array | Affected user flows, most relevant first (capped). Each has `title`, `source`, backward-compatible `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`. |
+| `compaction` | object | Present only when lower-priority detail was reduced to keep the complete line within 8KB. Carries `maxBytes` and the uncapped `originalBytes`. |
 | `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`. |
+| `requiredBootstrap` | array | Non-runner repository context steps (capped at 3): `title`, `action`. Runner setup is represented only under `automation`. |
 | `prChecklist` | array of string | Ready-to-paste PR checklist lines (capped). |
 | `commands` | array of string | Suggested next commands, most useful first (capped at 4). |
 
@@ -48,5 +54,5 @@ List fields are capped to keep the payload small; caps may grow within version 1
 ## 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"]}
+{"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},"intentCount":1,"omittedIntentCount":0,"intents":[{"title":"Submit notification preferences","confidence":"high","reviewRequired":false,"evidence":["feat: submit notification preferences"],"sources":[{"kind":"diff","reason":"Invoke fetch.","file":"src/pages/preferences.tsx","symbol":"fetch","relation":"supporting","side":"head","startLine":7,"endLine":7,"hunk":"@@ -1,5 +1,19 @@"}],"scenarioCount":1,"omittedScenarioCount":0,"lifecycle":[{"phase":"trigger","label":"Submit notification preferences."},{"phase":"side-effect","label":"Invoke fetch."},{"phase":"observable-outcome","label":"Show the saved state."}],"scenarios":[{"priority":"critical","kind":"primary","title":"Submit notification preferences","confidence":"high","reviewRequired":false,"sources":[{"kind":"diff","reason":"Invoke fetch.","file":"src/pages/preferences.tsx","symbol":"fetch","relation":"supporting","side":"head","startLine":7,"endLine":7,"hunk":"@@ -1,5 +1,19 @@"}],"assertions":["Verify the saved state becomes observable."]}]}],"automation":{"optIn":true,"adapter":"playwright","setupStatus":"proposed","draftCommand":"qamap e2e draft . --base main --head HEAD","setupCommand":"qamap e2e setup . --runner playwright"},"flowCount":1,"omittedFlowCount":0,"flows":[{"title":"Submit notification preferences","source":"commit-and-diff-intent","draft":"tests/e2e/submit-notification-preferences.spec.ts","runnable":"near-runnable","entry":"route: /preferences (high)","changedFiles":["src/pages/preferences.tsx"],"reviewQuestion":"Does the changed preference lifecycle produce the saved state?","successSignal":"visible text Preferences saved appears","steps":["Submit preferences.","Invoke fetch.","Verify the saved state."],"selectors":["web-test-id: preferences-save"],"evidence":["Commit and diff evidence support this change intent."]}],"requiredEvidence":[],"recommendedEvidenceCount":1,"requiredBootstrap":[],"prChecklist":["Review the proposed QA scenario and its diff source."],"commands":["npm run build"]}
 ```

package/docs/agent-skill.md

@@ -32,7 +32,7 @@ Run this before writing a PR body or asking for review. Agents should prefer the
 pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD --format agent
 ```
 
-The result carries `flows[]` (draft path, runnable status, entry route, steps, selectors), `requiredEvidence[]`, `requiredBootstrap[]`, `prChecklist[]`, and `commands[]` under `schema: qamap.qa`.
+The result carries `intents[]` with scenario-level structured diff `sources`, `flows[]` (affected behavior, entry route, steps, selectors), `requiredEvidence[]`, optional `automation`, `prChecklist[]`, and `commands[]` under `schema: qamap.qa`.
 
 For a human-readable report, drop the flag; for installed projects write it to a file:
 
@@ -68,12 +68,15 @@ If your agent supports symlinked skills, point its skill directory at `skills/qa
 
 ## What The Agent Should Do With The Output
 
-Use the `PR Comment Draft` section as review context:
+Use `Change Intent Evidence` and the `PR Comment Draft` as review context:
 
+- commit-backed intent, confidence, and whether human review is required
+- ordered behavior lifecycle
+- primary, failure, boundary, and state-transition QA scenarios
+- the strongest commit or `file:line` source for every proposed scenario
 - affected flow
-- recommended runner
-- draft E2E or checklist path
-- missing fixture, selector, assertion, runner, or validation evidence
+- missing fixture, selector, or assertion evidence
+- optional automation adapter selected only after QA design
 - PR checklist items
 
 If the command says a generated recommendation is wrong, do not keep re-prompting the agent with the same context. Update the repo-local manifest after human review:

package/docs/architecture.md

@@ -0,0 +1,131 @@
+# Architecture
+
+QAMap is moving from deterministic PR-to-draft heuristics toward a local, change-aware QA engine. The core must remain useful without cloud services, source upload, or LLM calls.
+
+The target pipeline is:
+
+```txt
+commit range + base/head diff
+  -> change intent analysis
+  -> analyzer adapters
+  -> behavior graph
+  -> behavior lifecycle + impact selection
+  -> runner-independent QA scenarios
+  -> Playwright / Maestro / manual adapter
+  -> explicit local execution
+  -> normalized evidence and verdict
+```
+
+The repository, not a model session, is the source of truth. Commit subjects and bodies provide author intent, source code supplies observable structure, and `.qamap/manifest.yaml` supplies reviewed product intent that commits and code alone cannot prove.
+
+## Change Intent
+
+`src/change-intent.ts` reads behavior-bearing commits in the selected base/head range and joins related `feat`, `fix`, `hotfix`, `perf`, and supporting `refactor` commits through normalized domain terms. Added diff symbols provide independent evidence for triggers, conditions, state changes, side effects, and observable outcomes.
+
+Each intent contains:
+
+- the original commit evidence and source scope;
+- an explicit confidence and `reviewRequired` flag;
+- an ordered behavior lifecycle;
+- runner-independent primary, failure, boundary, and state-transition QA scenarios.
+
+One richly evidenced squash commit can reach high confidence. A title without connected diff evidence cannot. Working-tree-only inference is always low confidence and review-required. Release, docs, style, CI, and test-only commits do not become product intents.
+
+The analysis is deterministic and local. It does not execute repository code, contact GitHub, upload source, or call an LLM.
+
+## Behavior Graph
+
+`src/behavior.ts` defines the framework-neutral intermediate representation. A graph contains stable nodes, typed edges, confidence, evidence, and direct or propagated change impact.
+
+Generated graphs identify the shipped contract through `schema/qamap-behavior.schema.json` and `schemaVersion: 1`. The schema URL and node, edge, surface, and evidence enums are exported from the package so adapters and consumers can reject unsupported shapes deterministically.
+
+Initial node kinds cover:
+
+- domains and flows;
+- routes, screens, endpoints, commands, and artifact surfaces;
+- actions, states, effects, contracts, and assertions;
+- fixtures, locators, and source files.
+
+Initial edges describe containment, entrypoints, ordering, expected outcomes, fixture use, locators, implementation sources, and diff impact.
+
+Every inferred node must retain provenance. A node without a commit, source, diff, selector, fixture, test, manifest, or named inference reason should not influence a QA verdict.
+
+Node and edge ids are content-derived and stable. Re-running analysis against the same repository state must produce the same graph identity even when report timestamps differ.
+
+## Compatibility Adapter
+
+The first graph integration uses `qamap.inferred-flow-compat`. It translates the existing E2E flow observations into the new graph so the IR can be introduced without changing existing CLI recommendations.
+
+This adapter is a migration bridge, not the final analysis architecture. Framework adapters should gradually emit graph fragments directly, after which draft generation will consume the graph instead of the graph consuming completed drafts.
+
+`qamap.change-intent` is the first direct product adapter. It emits intent contracts, lifecycle actions/states/effects, scenario assertions, source links, and commit provenance before an automation runner is selected.
+
+## Analyzer Adapters
+
+An analyzer adapter has two operations:
+
+```ts
+interface BehaviorAnalyzerAdapter {
+  id: string;
+  version: string;
+  detect(context): Detection;
+  analyze(context): BehaviorGraphFragment;
+}
+```
+
+Detection must be evidence-based and may decline a repository. Analysis failures are isolated and reported as diagnostics so one optional adapter cannot erase useful output from the others.
+
+Adapters should be layered:
+
+1. language adapters provide symbols, imports, calls, and schemas;
+2. framework adapters provide routes, screens, handlers, and lifecycle conventions;
+3. repository adapters provide manifests, tests, fixtures, and local policy;
+4. executor adapters compile selected scenarios for an existing runner.
+
+Support is reported by capability rather than a single yes/no framework badge:
+
+| Level | Contract |
+| --- | --- |
+| Deep | Behavior impact, deterministic scenarios, and local execution are supported. |
+| Structural | Routes, contracts, existing tests, and validation commands are understood. |
+| Generic | Diff and dependency evidence are available; QAMap does not invent a product journey. |
+
+TypeScript-based web stacks are the first deep-analysis target because the existing import, route, selector, and fixture signals already provide a useful base. Vue, Nuxt, and SvelteKit should reuse the common web behavior model rather than fork the QA pipeline. Mobile, API, Python, Go, and JVM support should enter through the same adapter contract.
+
+## Manifest Boundary
+
+The generated graph is local cache material and should not be committed in full. The verification manifest stores only durable, reviewed knowledge:
+
+- important flows and criticality;
+- expected and forbidden outcomes;
+- auth, permission, fixture, and environment requirements;
+- stable anchors and invariants;
+- accepted corrections and suppressions.
+
+This keeps first-run setup light while allowing one human correction to improve later PRs deterministically.
+
+## Execution Boundary
+
+`qamap qa` remains static and read-only. It must not execute scanned project code.
+
+Future execution belongs to an explicit `qamap verify` mode with a visible execution plan. The intended safeguards are:
+
+- generated tests live in an operating-system temporary directory by default;
+- target repository files are not modified unless a separate write command is requested;
+- commands, environment variables, network access, and time limits are policy controlled;
+- existing mocks and fixtures are preferred over fabricated data;
+- missing setup becomes `not verifiable`, never a false pass;
+- source code and evidence remain local and no LLM is called.
+
+Playwright, Maestro, and other tools are executor implementations. They are not the product-level recommendation shown first to users.
+
+## Migration Order
+
+1. Derive change intent and runner-independent QA scenarios from commit and diff evidence.
+2. Move route, screen, endpoint, selector, fixture, and contract discovery into graph-producing adapters.
+3. Compare base and head graphs to select affected behavior rather than relying on file categories alone.
+4. Compile selected graph paths through Playwright, Maestro, or manual adapters.
+5. Add explicit, temporary execution and normalized evidence.
+6. Add manifest accept, reject, and repair commands so reviewed outcomes improve later analysis.
+
+Version `0.4.0` establishes the commit-to-intent-to-scenario slice for synthetic web and mobile lifecycle changes. The next minor is reserved for a policy-controlled scenario execution and normalized evidence slice; compatible analyzer and adapter improvements remain patch releases during `0.x` development.

package/docs/benchmarking.md

@@ -2,7 +2,7 @@
 
 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?
 
-`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.
+`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. Intent fixtures set a synthetic `commitMessage` so commit-to-lifecycle behavior is part of the contract. QAMap reads those repositories but never installs dependencies or executes their code.
 
 ## Run the public contract
 
@@ -14,6 +14,9 @@ The command fails when any target violates its declared expectations. The initia
 
 - a web app with no tests;
 - a web app with Playwright and an existing mock handler;
+- Vue and SvelteKit web changes with framework-native route files;
+- a web preferences change that must become submit, persistence, request-failure, and re-entry QA instead of a generic journey;
+- a mobile reminder change that must become scheduling, calendar, duplicate, resynchronization, and entry-routing QA;
 - 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;
@@ -27,13 +30,26 @@ Each target can declare:
 
 | Field | Meaning |
 | --- | --- |
-| `runner` | Expected `playwright`, `maestro`, or `manual` recommendation. |
+| `commitMessage` | Synthetic feature-commit message used when materializing a fixture. |
+| `runner` | Expected `playwright`, `maestro`, or `manual` output adapter. Runner correctness alone is not a useful intent benchmark. |
 | `minFlows` | Minimum number of affected flows. |
+| `minChangeIntents` | Minimum evidence-backed Change Intents. |
+| `minHighConfidenceIntents` | Minimum intents supported strongly enough by commit and diff evidence to avoid mandatory review. |
+| `minCommitBehaviorNodes` | Minimum Behavior Graph nodes carrying commit provenance. |
 | `minImportPropagatedFlows` | Minimum flows discovered through reverse imports. |
 | `minDiffAnchoredFlows` | Minimum flows using selector evidence introduced by the diff. |
 | `minManifestMatches` | Minimum domain, flow, and check matches from an external base manifest. |
 | `minManifestFlowMatches` | Minimum flow-level matches from the external base manifest. |
 | `minManifestBackedFlows` | Minimum QA flows that preserve manifest provenance. |
+| `minManifestBehaviorNodes` | Minimum Behavior Graph nodes carrying verification-manifest evidence. |
+| `mustHaveBehaviorKinds` | Behavior Graph node kinds that must be present, such as `flow`, `surface`, `source`, `assertion`, or `locator`. |
+| `mustNameIntents` | Concrete terms that must appear in the inferred intent title. |
+| `mustNotNameIntents` | Misleading terms that must not appear in inferred intent titles. |
+| `mustIncludeLifecycle` | Trigger, condition, action, state, effect, or outcome terms that must survive in the ordered lifecycle. |
+| `mustIncludeQaScenarios` | Failure, boundary, state-transition, or primary QA terms that must be proposed before runner compilation. |
+| `mustFindIntentEvidence` | Commit or diff terms that must remain attached to intent provenance. |
+| `mustTraceScenarioFiles` | Changed files that must appear in at least one scenario's exact direct/supporting base- or head-side diff source. |
+| `maxUntracedCriticalScenarios` | Maximum critical scenarios without a direct/supporting diff source carrying a file and line number. Contextual commit evidence cannot satisfy this contract; lifecycle fixtures keep it at zero. |
 | `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. |
@@ -41,12 +57,13 @@ Each target can declare:
 | `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. |
+| `mustFindEntrypoints` | Route, screen, or command entrypoints that affected flows must recover. |
 | `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`. |
+| `maxAgentBytes` | Maximum UTF-8 payload size for `qa --format agent`. Production output also has a global 8KB ceiling and discloses omitted intent/flow counts. |
 
 Set `manifestBaseline: true` on a committed fixture to generate its manifest from the base snapshot into the benchmark temp directory, then pass that external manifest to analysis of the head commit. The fixture repository is never modified by this step. This protects the feedback loop itself: a baseline must affect the next PR, not merely serialize valid YAML.
 
@@ -62,7 +79,9 @@ node scripts/bench.mjs --baseline bench-results/<file>.json
 
 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.
+Saved results include intent titles, lifecycle and scenario terms, scenario trace coverage, 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.
+
+Every benchmark target also enforces the Behavior Graph base contract: graph schema version 1, at least one graph flow for every planned flow, at least one impacted node for a non-empty diff, and no edge whose endpoint is missing. The table reports `graph n/i` as total nodes versus impacted nodes. These checks keep the graph connected to real PR analysis while framework-specific adapters are introduced incrementally.
 
 ## Adding a regression
 

package/docs/commands.md

@@ -21,7 +21,7 @@ Use `pnpm dlx @ivorycanvas/qamap ...` for one-off runs without installing QAMap
 
 ## 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.
+Human-facing reports (`text` and `markdown` formats) open with an **At a Glance** section: evidence-backed change intent, behavior lifecycle, affected behavior, the reviewer question to answer before merge, concrete repository evidence, the proposed draft path, and missing trust requirements. Runner information appears later as an automation adapter. 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:
 
@@ -37,7 +37,9 @@ Draft readiness is reported as a **stage on a fixed four-step journey**, for exa
 
 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
+- a commit-and-diff-backed change intent with confidence, review requirements, and source evidence
+- an ordered trigger, condition, action, state-change, side-effect, and observable-outcome lifecycle
+- runner-independent primary, failure, boundary, and state-transition QA scenarios
 - 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
@@ -61,9 +63,9 @@ That means QAMap is most valuable when it becomes the team's verification base:
 | `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 qa . --base origin/main --head HEAD` | One-command PR QA: change intent, behavior lifecycle, QA scenarios, affected flows, missing evidence, and optional automation drafts. |
+| `qamap qa . --base origin/main --head HEAD --format agent` | The same decision content as one compact 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` | Derive change intent and QA scenarios, then map them to coverage, test evidence, testability gaps, and an automation adapter. |
 | `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. |
@@ -90,7 +92,9 @@ For monorepos, pass `--workspace-root` when scanning a package. Package-local ch
 
 `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.
+`qamap e2e plan` first reads behavior-bearing commits in the selected base/head range. Related `feat`, `fix`, `hotfix`, `perf`, and supporting `refactor` commits are grouped into change intents, then connected to added diff symbols. The result is an evidence-backed lifecycle and a set of runner-independent primary, failure, boundary, and state-transition scenarios. Low-confidence or working-tree-only intent remains review-required instead of becoming trusted regression policy.
+
+After that judgment, QAMap detects whether the target looks like Expo/React Native, web, API/service, CLI, or another repository shape and selects a Maestro, Playwright, or manual output adapter. The plan compares scenario targets with existing test evidence, identifies required mocks and fixtures, and reports missing stable selectors such as `testID` or `data-testid`. Runner detection is an implementation detail, not the first value shown to the user.
 
 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.
 
@@ -100,7 +104,7 @@ When a repository does not already have the selected E2E runner, the plan includ
 
 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.
+Each candidate flow also includes a flow language brief: actor, trigger, goal, success signal, reviewer question, and edge cases. Intent-backed flows additionally retain the original commits, ordered lifecycle, QA scenarios, confidence, and review requirement so generated tests can be traced to evidence 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.
 
@@ -207,6 +211,8 @@ Pass `--record-history` when you want QAMap to keep a compact local snapshot of
 
 The draft result is meant to be useful as a PR artifact, not only as generated files. Markdown and JSON output include:
 
+- `changeAnalysis`: commit-backed intents, confidence, review requirements, source evidence, lifecycle stages, and runner-independent QA scenarios
+- intent-backed draft files retain `intentId`, `intentConfidence`, `lifecycle`, and `qaScenarios`; generated files include the same evidence as comments
 - `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`

package/docs/e2e-output-examples.md

@@ -15,20 +15,31 @@ The output should be specific enough to paste into a PR comment:
 ```txt
 # QAMap QA Draft
 
+At a Glance
+- Change intent: Submit checkout and persist the confirmed order [high]
+- Behavior lifecycle: trigger: Submit checkout -> side-effect: Create order -> observable-outcome: Show order confirmation
+- Affected behavior: Submit checkout and persist the confirmed order
+
+Change Intent Evidence
+- Commit: feat: submit checkout and persist the confirmed order
+- Critical scenario: Submit checkout and persist the confirmed order
+  - Assert: order confirmation is visible and persisted
+- Recommended scenario: Failure, timeout, and retry handling
+
 Summary
 - Project: Web
-- Recommended runner: Playwright
+- Automation adapter: Playwright
 - Manifest: not found; using repo signals and PR diff only
 - Stage: almost runnable (3 of 4)
 
 PR Comment Draft
-- Affected flow: Checkout UI smoke flow
+- Affected flow: Submit checkout and persist the confirmed order
 - User journey: Customer -> Open route /checkout -> Complete checkout with realistic form data
 - Success signal: confirmation state is visible after submit
 - Changed files: src/pages/checkout/index.tsx
 
 Suggested E2E / QA Draft
-- tests/e2e/checkout-ui-smoke-flow.spec.ts: near runnable
+- tests/e2e/submit-checkout-and-persist-the-confirmed-order.spec.ts: near runnable
 - Open route /checkout.
 - Fill checkout email.
 - Submit checkout.
@@ -139,7 +150,7 @@ flows:
 
 ```txt
 Project: Web
-Recommended runner: Playwright
+Automation adapter: Playwright
 Execution profile: high
 Start command: pnpm run dev
 Test command: pnpm run test:e2e
@@ -224,7 +235,7 @@ For an Expo or React Native change, QAMap should recommend Maestro and carry mob
 
 ```txt
 Project: Expo / React Native
-Recommended runner: Maestro
+Automation adapter: Maestro
 
 Flow: Ink Drawing UI smoke flow
 Actor: User
@@ -269,7 +280,7 @@ For backend changes such as `src/v1/listing/utils.ts`, QAMap should not invent a
 
 ```txt
 Project: API / service
-Recommended runner: Manual
+Automation adapter: Manual
 
 Flow: Listing API contract smoke checklist
 Actor: API consumer or upstream service
@@ -296,7 +307,7 @@ For an npm package that exposes `package.json` bin entries, QAMap should not inv
 
 ```txt
 Project: CLI
-Recommended runner: Manual
+Automation adapter: Manual
 
 Flow: CLI command verification checklist
 Actor: CLI user or maintainer
@@ -319,30 +330,17 @@ The manual draft should name concrete command evidence:
 
 ## Test-Light Project
 
-When a project has little or no E2E setup, QAMap should move the user toward a concrete starter draft, not just a task list:
+When a project has little or no E2E setup, `qamap qa` still returns the same runner-independent QA judgment. Runner setup remains an explicit team choice:
 
 ```txt
-## First E2E Draft Bootstrap
-
-QAMap did not find committed test files for this target. The next step is to create the first runnable starter draft, not to stop at a checklist.
-
-- Recommended first runner: Playwright
-- Create command: `qamap e2e setup . --runner playwright`
-- Install command: `pnpm add -D @playwright/test`
-- Draft files QAMap can create:
-  - `playwright.config.ts`
-  - `tests/e2e/`
-  - `tests/e2e/checkout-primary-journey.spec.ts`
-- Files to update: `package.json`
+## Optional Automation
 
-Bootstrap summary:
-4 required bootstrap steps must be resolved before generated E2E drafts should be treated as regression coverage.
+The QA judgment above does not require adopting this adapter.
 
-Required:
-- Configure Playwright before making drafts required
-- Create the first changed-flow E2E draft
-- Add deterministic fixture or mock responses
-- Add stable selectors for changed UI surfaces
+- Adapter candidate: Playwright
+- Draft target: `tests/e2e/checkout-primary-journey.spec.ts`
+- Preview or create a draft: `qamap e2e draft . --base main --head HEAD`
+- If the team accepts this adapter, inspect its setup proposal: `qamap e2e setup . --runner playwright`
 ```
 
 Draft action items should make the next developer action explicit:
@@ -460,9 +458,12 @@ Related Changed Files
 Good QAMap output should answer these questions quickly:
 
 - What behavior did this branch probably change?
+- Which commits and diff symbols support that intent, and how confident is the inference?
+- What trigger, condition, state change, side effect, and observable outcome form its lifecycle?
+- Which primary, failure, boundary, and state-transition checks follow from that lifecycle?
 - What does the team call that behavior?
 - Who or what exercises it?
-- Which runner or checklist is the right first shape?
+- Which existing automation adapter can compile the selected QA scenario?
 - Which setup, selector, fixture, or validation gap blocks this from becoming real regression coverage?
 
 If the output only says "make an E2E test" without these answers, it is not ready for the current release bar.

package/docs/quickstart-demo.md

@@ -15,6 +15,7 @@ src/features/checkout/submitCheckout.ts
 The reviewer wants to know:
 
 - Which user flow is affected?
+- Which diff hunk caused each QA scenario to be proposed?
 - Should this become a Playwright test, a manual checklist, or only a review note?
 - What blocks the generated draft from being trusted as regression coverage?
 
@@ -26,9 +27,9 @@ Run QAMap on the branch:
 pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD
 ```
 
-`qa` is important for first contact. It lets maintainers preview the PR comment draft, affected flow, draft path, readiness, and blockers without writing files.
+`qa` is important for first contact. It lets maintainers review change intent, behavior lifecycle, scenario confidence, exact diff sources, and a PR checklist without writing files or selecting a test runner.
 
-When the team wants actual draft files:
+After the team accepts a scenario and wants executable coverage:
 
 ```sh
 pnpm dlx @ivorycanvas/qamap e2e draft . --base origin/main --head HEAD --dry-run
@@ -145,11 +146,15 @@ Input
 ```txt
 Output
 - PR comment/checklist draft
+- commit-backed change intent and confidence
+- ordered behavior lifecycle
+- primary, failure, boundary, and state-transition QA scenarios
+- scenario-level confidence, review status, and exact commit or head-side `file:line` sources
 - changed domain language
 - candidate user flow
 - manifest evidence when a repo-local flow/check matches
-- recommended runner
-- draft file path
+- optional automation adapter selected after QA design
+- optional draft file path
 - flow language brief
 - runnable status
 - self-check status
@@ -157,33 +162,40 @@ Output
 - blockers that explain why a draft is not ready yet
 ```
 
-The result should not stop at "selector needed" or "fixture needed." A useful QAMap draft should say which flow changed, which test file would be generated, which checks it covers, why those checks were selected, and where to update the manifest if the recommendation is wrong.
+The result should not stop at "selector needed" or "fixture needed." A useful QAMap report should say which behavior changed, which scenarios follow, which exact hunk supports each scenario, what remains uncertain, and where to update the manifest if the recommendation is wrong. Automation comes after that review.
 
 ## Markdown Preview
 
 ```txt
 # QAMap QA Draft
 
+At a Glance
+- Change intent: Submit notification preferences and show the saved state [high]
+- Behavior lifecycle: trigger -> state-change -> side-effect -> observable-outcome
+
 Summary
 - Project: Web
-- Recommended runner: Playwright
 - Manifest: .qamap/manifest.yaml
-- Stage: almost runnable (3 of 4)
 
-PR Comment Draft
-- Affected flow: Checkout purchase
-- Suggested draft: tests/e2e/checkout-purchase.spec.ts
-- User journey: Customer -> Open route /checkout -> Complete checkout with realistic form data
-- Success signal: confirmation state is visible after submit
+QA scenarios
+- [critical] changed preference lifecycle [high]
+  - Source: src/pages/preferences.tsx:17, symbol onClick
+  - Assert: the saved state is visible
+- [recommended] failure, timeout, and retry handling [medium; review required]
+  - Source: src/pages/preferences.tsx:7, symbol fetch
+  - Assert: retries do not duplicate requests or side effects
 
-Missing evidence before trusting this PR
-- [required] fixture: Add deterministic payment/customer fixture data.
-- [recommended] selector: Confirm stable selectors for changed checkout controls.
+Evidence gaps in this QA proposal
+- [required] fixture: Add deterministic response data for /api/preferences.
 
 PR checklist
-- [ ] Review tests/e2e/checkout-purchase.spec.ts.
-- [ ] Confirm success and failed-response assertions.
+- [ ] Review each QA scenario and its diff source.
+- [ ] Confirm success and failed-response assertions for /api/preferences.
 - [ ] Run pnpm run test:e2e.
+
+Optional automation
+- Adapter candidate: Playwright
+- qamap e2e draft . --base origin/main --head HEAD
 ```
 
 ## Draft Shape