@ivorycanvas/qamap 0.3.5 → 0.4.0

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,24 @@ 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. |
 | `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,6 +55,7 @@ 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. |
@@ -62,7 +77,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, 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
@@ -460,9 +471,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

@@ -145,10 +145,13 @@ Input
 ```txt
 Output
 - PR comment/checklist draft
+- commit-backed change intent and confidence
+- ordered behavior lifecycle
+- primary, failure, boundary, and state-transition QA scenarios
 - changed domain language
 - candidate user flow
 - manifest evidence when a repo-local flow/check matches
-- recommended runner
+- automation adapter selected after QA design
 - draft file path
 - flow language brief
 - runnable status
@@ -164,9 +167,13 @@ The result should not stop at "selector needed" or "fixture needed." A useful QA
 ```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 confirmation
+
 Summary
 - Project: Web
-- Recommended runner: Playwright
+- Automation adapter: Playwright
 - Manifest: .qamap/manifest.yaml
 - Stage: almost runnable (3 of 4)
 

package/docs/release-validation.md

@@ -1,5 +1,19 @@
 # Release Validation
 
+## 0.4.0 - 2026-07-12
+
+Validated as the first intent-first QA design release. The release contract starts with behavior-bearing commits and diff evidence, reconstructs an ordered behavior lifecycle, proposes runner-independent QA scenarios, and only then compiles an optional automation draft:
+
+| Gate | Current result |
+| --- | --- |
+| `pnpm test` | 139/139 passing |
+| `pnpm bench:ci` | 12/12 synthetic PR targets pass; dedicated web and mobile lifecycle targets require commit intent, ordered lifecycle phases, failure/boundary/state QA, observable success text, and commit-backed Behavior Graph evidence |
+| Coverage | Lines 86.80%, branches 83.37%, functions 94.86% |
+| Change Intent coverage | Lines 94.76%, branches 88.57%, functions 98.04% |
+| `npm publish --dry-run --access public` | Passed for `@ivorycanvas/qamap@0.4.0`; 129 files, 813.8 kB packed |
+| Intent-first output | Markdown, JSON, agent output, Behavior Graph, and generated drafts preserve confidence, commit evidence, lifecycle, and QA scenarios before automation-adapter guidance |
+| Read-only safety | Public regression coverage uses synthetic repositories; optional local smoke validation runs from temporary copies and does not modify target repositories |
+
 ## 0.3.5 - 2026-07-11
 
 Validated as a manifest-feedback reliability patch:
@@ -83,7 +97,9 @@ For each target, record:
 
 - command used
 - base/head refs or working-tree mode
-- recommended runner
+- inferred change intent, confidence, commit evidence, and review requirement
+- lifecycle and runner-independent QA scenario quality
+- selected automation adapter
 - generated flow language brief quality
 - draft readiness summary
 - draft self-check status and blockers
@@ -140,7 +156,9 @@ node dist/cli.js e2e draft <package> --workspace-root <repo-root> --base <base>
 
 The E2E plan should show:
 
-- runner recommendation with clear evidence
+- change intent with commit and diff evidence, confidence, and review requirement
+- ordered behavior lifecycle and concrete primary, failure, boundary, and state-transition QA scenarios
+- automation adapter selection after the runner-independent QA sections
 - execution profile with start command, test command, base URL or app id when discoverable, confidence, and blockers
 - runner setup proposal with install commands, explicit `qamap e2e setup` acceptance command, files to create/update, and next commands when the repo lacks an E2E runner
 - setup output that reports the first generated changed-flow draft file after the accepted runner setup is applied
@@ -151,6 +169,7 @@ The E2E plan should show:
 
 The E2E draft should show:
 
+- intent evidence, lifecycle, and QA scenario comments inside generated artifacts
 - `verification-manifest` as the draft source when a matched manifest flow is strong enough
 - manifest evidence comments inside generated drafts
 - external `--manifest <file>` previews that let teams test generated manifest quality without writing `.qamap/manifest.yaml` into target repos
@@ -170,9 +189,11 @@ The QA draft should show:
 
 - no-write PR comment/checklist output from `qamap qa`
 - no cloud and no LLM token positioning in the output
+- change intent and lifecycle before automation setup
+- primary, failure, boundary, and state-transition QA scenarios when evidence supports them
 - affected flow language with changed files and reviewer question
 - suggested E2E or manual checklist path
-- runner recommendation inherited from the E2E planner
+- automation adapter inherited from the E2E planner
 - missing fixture, selector, assertion, runner, validation, or manifest evidence
 - PR checklist items that can be pasted into a pull request
 - optional manifest repair path when a manifest-backed recommendation is wrong
@@ -198,6 +219,9 @@ The manifest commands should show:
 The public demo must prove the product shape, not only command execution. Before promoting a release, run or update a small demo where a realistic PR diff produces a concrete E2E starting point:
 
 - The output names the affected product feature and user flow in domain language.
+- The output shows the behavior-bearing commit evidence, confidence, and review requirement behind the inferred intent.
+- The output orders trigger, condition, action, state change, side effect, and observable outcome before selecting a runner.
+- The output proposes concrete primary, failure, boundary, and state-transition QA where evidence supports them.
 - The output names the draft file that would be created or previewed.
 - The draft includes route or screen entry, realistic actions, and at least one meaningful assertion.
 - The report explains why the test was recommended from changed files and manifest evidence.
@@ -213,11 +237,12 @@ The matrix below is public, fixture-backed evidence from the repository test sui
 
 | Target | Fixture-backed coverage | Expected output |
 | --- | --- | --- |
+| Commit intent and lifecycle | `change intent clusters related commits into one evidence-backed lifecycle`; `change intent keeps unrelated feature commits separate`; `change intent ignores release-only commit metadata`; `E2E planning promotes commit intent before runner-specific draft generation` | Related feature commits become one evidence-backed intent; unrelated features remain separate; release-only changes do not become product intent; lifecycle and QA scenarios appear before Playwright or Maestro compilation; generic `primary journey` and `smoke flow` titles are suppressed when evidence supports a concrete name. |
 | Manifest-free QA skill entrypoint | `qa command emits a PR comment draft without requiring a manifest` | `qamap qa` works without `.qamap/manifest.yaml`, emits a local-first PR QA draft, names affected flow, changed files, suggested E2E/checklist path, missing evidence, PR checklist, agent handoff, and says manifest is optional upgrade rather than a first-use gate. |
 | Packaged PR QA skill template | `package metadata includes the portable PR QA skill template` | npm package metadata includes `skills`, and `skills/qamap-pr-qa/SKILL.md` contains the local PR QA workflow, `qamap qa` command, and manifest repair guidance. |
 | Verification manifest loop | `manifest init creates a baseline verification manifest`; `manifest init keeps Expo app file domains specific`; `manifest init captures advisory instruction context`; `manifest bootstrap produces concrete PR E2E draft from repo QA memory`; `e2e draft can use an external verification manifest for read-only adoption preview`; `manifest matches explain e2e and verify recommendations`; `manifest validate reports missing and stale manifest policy` | Generated `.qamap/manifest.yaml` includes `$schema`, domains, flows, anchors, checks, runner, source, and confidence; context preview reports repo-local instruction sources, role summaries, validation commands, safety rules, and diagnostics; validator reports missing/stale/duplicate policy; explain output maps branch changes to manifest domains/flows/checks; E2E drafts prefer `verification-manifest` sources with manifest evidence, route entry, detected input/action selectors, required checks, and manifest repair paths; external manifests can be passed with `--manifest` for read-only adoption smoke tests. |
-| Web app with Playwright routes | `generateE2ePlan matches committed core flow definitions`; `generateE2eDraft uses web selectors in Playwright specs`; `generateE2eDraft dry run previews files without writing drafts`; `generateE2eDraft asserts changed HTML success copy in Playwright specs`; `generateE2ePlan captures Playwright execution profile and self-check blockers`; `generateE2ePlan infers Playwright base URLs from dev scripts`; `generateE2eDraft supports Next app router route groups and concrete route hints`; `generateE2ePlan reads React Router object route paths`; `generateE2eDraft fills dynamic route params from concrete route hints`; `generateE2eDraft emits runnable Playwright role and input actions` | `Web` project profile, `playwright` runner, core-flow names such as `Checkout purchase`, route-aware Playwright drafts, dry-run preview status without filesystem writes, stable selector hints, changed HTML success copy assertions, execution profile, dev-script base URL hints, opt-in Playwright setup proposal, Next App Router route groups, React Router object paths, dynamic route params, draft self-check status, action items, and validation gaps. |
-| Expo / React Native mobile app | `generateE2ePlan recommends mobile flows for Expo changes`; `generateE2ePlan detects Maestro app ids from app config files`; `generateE2eDraft scopes entrypoint hints to each domain scenario`; `generateE2eDraft names changed component actions before generic primary journeys` | `Expo / React Native` project profile, `maestro` runner, app id and launch command hints from `app.json` or `app.config.*`, Maestro YAML drafts, `testID`/`accessibilityLabel` selector hints, action-specific scenario names such as `Listing Media Link Submit`, and mobile setup actions. |
+| Web app with Playwright routes | `generateE2ePlan matches committed core flow definitions`; `generateE2eDraft uses web selectors in Playwright specs`; `generateE2eDraft dry run previews files without writing drafts`; `generateE2eDraft asserts changed HTML success copy in Playwright specs`; `generateE2ePlan captures Playwright execution profile and self-check blockers`; `generateE2ePlan infers Playwright base URLs from dev scripts`; `generateE2eDraft supports Next app router route groups and concrete route hints`; `generateE2ePlan reads React Router object route paths`; `generateE2eDraft fills dynamic route params from concrete route hints`; `generateE2eDraft emits runnable Playwright role and input actions` | `Web` project profile, Playwright output adapter, intent-backed or core-flow names, route-aware drafts, dry-run preview status without filesystem writes, stable selector hints, changed HTML success copy assertions, execution profile, dev-script base URL hints, opt-in setup proposal, route groups, object paths, dynamic params, draft self-check status, action items, and validation gaps. |
+| Expo / React Native mobile app | `generateE2ePlan recommends mobile flows for Expo changes`; `generateE2ePlan detects Maestro app ids from app config files`; `generateE2eDraft scopes entrypoint hints to each domain scenario`; `generateE2eDraft names changed component actions before generic primary journeys` | `Expo / React Native` project profile, Maestro output adapter, app id and launch command hints from `app.json` or `app.config.*`, YAML drafts, `testID`/`accessibilityLabel` selector hints, and mobile setup actions after runner-independent QA intent. |
 | API or backend service | `generateE2ePlan detects API service projects and suggests contract checklists`; `generateE2ePlan detects Django service apps from a workspace root`; `generateE2ePlan names versioned API service paths with domain language`; `generateE2ePlan uses matched core flow names for API service contracts` | `API / service` project profile, manual contract checklist, Django/FastAPI-style service signals when present, domain-aware titles such as `Listing API contract`, API consumer actor, endpoint/handler/service-path trigger, service start/test command hints, and contract failure coverage. |
 | CLI package | `generateE2ePlan detects CLI packages and suggests command verification checklists` | `CLI` project profile from `package.json` bin entries, manual command verification checklist, CLI user or maintainer actor language, command invocation trigger, stdout/stderr/generated-file/exit-code success signal, valid and invalid argument coverage, and no required API fixture action unless the changed command path explicitly exposes network or fixture evidence. |
 | Design tokens and data catalogs | `generateE2ePlan detects design token packages and suggests artifact validation`; `generateE2ePlan detects data catalog repositories and suggests catalog verification` | `Design tokens` and `Data catalog` project profiles, manual artifact/catalog checklist, token or catalog actor language, schema/generated output/consumer fixture coverage, fixture readiness marked not needed for API mocks, and validation matrix rows that do not require browser/device selectors. |
@@ -239,7 +264,8 @@ Private repositories may be used as local, read-only diagnostics, but their raw
 The release candidate must pass the fixture-backed suite, package dry-run, and read-only smoke protocol. Record only public synthetic evidence in this document or in release notes:
 
 - whether the generated flow names match the team's domain language
-- whether the recommended runner is plausible
+- whether commit evidence supports the inferred intent and lifecycle
+- whether the automation adapter is plausible without being mistaken for the product value
 - whether generated drafts identify the right actor, trigger, success signal, and edge cases
 - whether action items are concrete enough for a developer to convert into runnable tests
 - whether false positives are caused by missing manifests, weak selectors, or unsupported project structure

package/docs/releasing.md

@@ -2,6 +2,19 @@
 
 This runbook defines the release process for `qamap`. It is intentionally conservative: the package should be published only when the local release gate, documentation, and representative repository validation all agree.
 
+## Pre-1.0 Version Policy
+
+QAMap keeps major and minor changes deliberately rare during `0.x` development.
+
+- Patch is the default for bug fixes, inference quality, performance, internal architecture, benchmarks, documentation, and additional adapters that preserve the existing CLI, schema, and safety contracts.
+- Minor is reserved for a new product-level capability, an incompatible CLI or manifest contract, or a meaningful change to default execution and safety behavior.
+- Risky minor work should ship through `alpha`, `beta`, and `rc` prereleases before the final minor.
+- Do not pre-allocate a minor version to every roadmap phase. Define the next minor release bar and continue compatible work as patches until that bar is met.
+
+Version `0.4.0` is earned by the first commit-to-intent-to-scenario vertical slice: behavior-bearing commits and diff symbols become an evidence-backed lifecycle and concrete runner-independent QA, then existing Playwright, Maestro, or manual adapters compile the result. The next minor is reserved for explicit temporary execution and normalized evidence without modifying the target repository.
+
+Version `1.0.0` requires a stable public contract and external adoption, not implementation volume alone. CLI commands, exit codes, machine output, manifest migration, adapter compatibility, no-LLM/no-upload guarantees, and release operations must be dependable. Repository stars are useful social proof, but repeated use in unrelated repositories and reported QA value are stronger release evidence.
+
 ## Release Owner Checklist
 
 Before publishing, confirm:

package/docs/roadmap.md

@@ -1,47 +1,56 @@
 # Roadmap
 
-QAMap starts as a local CLI for repo-level AI agent readiness. The project can grow in layers without becoming heavy.
+QAMap is a local CLI for evidence-backed PR QA design. The project can grow in layers without becoming a hosted platform or token-dependent agent.
 
 ## North Star
 
-QAMap should become a local-first QA skill plus optional QA memory layer: it maps PR changes to affected flows, drafts the E2E/checklist work needed before merge, and improves over time through a repository-level verification manifest. The goal is not to replace reviewers or QA. The goal is to remove the repeated blank-page work that makes developers skip good verification.
+QAMap should become a local, zero-LLM, change-aware QA engine. It should map any PR change to affected behavior, select the smallest relevant QA set, and eventually execute that QA with local evidence. A repository-level verification manifest supplies reviewed product intent that static code evidence cannot prove. The goal is not to replace reviewers or QA. The goal is to remove the repeated blank-page and manual verification work that makes developers skip good QA.
 
 The sharp product position is:
 
 ```txt
-Do not re-prompt AI for the same QA context.
-Run a local PR QA draft first, then capture team QA memory in the repo when repeated corrections should improve future recommendations.
+Read the change, find the affected behavior, and produce local QA evidence.
+No source upload. No LLM token. Let reviewed repository memory improve every later PR.
 ```
 
-This means QAMap should be judged less like a generic test recorder and more like a manifest-backed PR verification assistant. A recorder captures what a person just clicked. QAMap should explain what the PR changed, which durable flow/check knowledge applies, and what test artifact should now exist.
+This means QAMap should be judged by whether it identifies the right behavior and catches a seeded regression, not only whether it writes plausible test code. Playwright, Maestro, and other runners are implementation details behind that product contract.
 
 ## Release Bar
 
 Before treating the next public release as ready, the golden demo must satisfy these conditions:
 
 - First-run output is concrete, not broad: it names the affected feature, flow, draft file, and checks.
+- Commit evidence becomes an explicit change intent and ordered behavior lifecycle before any runner is recommended.
+- Generic `primary journey` and `smoke flow` names fail the benchmark when commit and diff evidence can support a concrete lifecycle.
 - Manifest authoring burden stays low: `manifest context` and `manifest init` provide a useful baseline before a human edits YAML.
 - Generated E2E draft is a usable starting point: it has route/screen entry, meaningful actions, assertions, and clear TODOs only where repo data is missing.
 - Recommendation evidence is explainable: output shows the changed file, manifest flow/check, and manifest path to repair when wrong.
 - README demo shows the full loop: manifest-free PR QA draft, optional repo context baseline, PR mapping, E2E draft, and remaining validation gaps.
 - One manifest correction should improve future PR recommendations without another LLM prompt.
 
-## Now
+## Now: 0.4.x
 
+- Stabilize commit-range Change Intent analysis: related behavior commits, diff symbols, confidence, review requirements, lifecycle stages, and runner-independent QA scenarios.
+- Keep `qamap.change-intent` as a direct Behavior Graph adapter while moving more source observations out of the compatibility adapter.
+- Preserve `qa` as the static, read-only product surface while designing explicit execution behind `verify`; never turn a scan into implicit project-code execution.
 - Treat the committed [benchmark contract](benchmarking.md) as the quality gate for recommendations, not only implementation correctness. Reduce real failures into public fixtures and require `pnpm bench:ci` on every PR.
-- Make `qa` the primary product surface. Its first screen and `--format agent` payload should agree on affected behavior, reviewer question, repository evidence, draft path, and missing trust requirements.
+- Make `qa` the primary product surface. Its first screen and `--format agent` payload must agree on change intent, lifecycle, QA scenarios, affected behavior, repository evidence, draft path, and missing trust requirements.
 - Improve changed-file impact mapping from shared symbols and components to consuming routes, screens, API contracts, and manifest flows.
 - Keep the [release validation checklist](release-validation.md), [manifest guide](manifest.md), public [E2E output examples](e2e-output-examples.md), and README examples aligned with captured output from the public fixtures.
 - Stabilize the manifest feedback loop with `.qamap/manifest.yaml`, `manifest init`, `manifest validate`, `manifest explain`, JSON Schema, and manifest-driven E2E draft shaping.
 - Keep `manifest context` useful as a pre-init sanity check for repo-local QA memory, harness docs, agent instructions, and runbooks.
-- Improve generated drafts until the golden demo feels like a real starting point, not a generic checklist.
+- Improve Playwright and Maestro compilation from intent scenarios while keeping runner choice behind the runner-independent QA contract.
 - Keep `verify`, `e2e`, and `manifest` as deeper layers behind `qa`; freeze new scanner, doctor, eval, domains, flows, and history features until the core QA contract is consistently useful.
 
 ## Next
 
+- Move route, screen, endpoint, selector, fixture, test, and contract discovery into analyzer adapters, starting with TypeScript web stacks and reusing one web behavior model across Next.js, React Router, Vue/Nuxt, and SvelteKit.
+- Compare base and head Behavior Graphs, then select impacted graph paths before refining deterministic success, validation, failure, empty, loading, auth, and contract scenarios.
+- Add policy-controlled temporary execution so selected scenarios can produce normalized pass, fail, blocked, and not-verifiable evidence without modifying the target repository.
+- Add an execution benchmark that injects known regressions and requires QAMap to select and fail the relevant scenario without changing the fixture repository.
 - Add symbol-level anchors for exported components, hooks, API clients, handlers, schemas, and queries after the public import-impact fixture stays stable.
 - Add a manifest correction command that proposes the exact flow/anchor patch and applies it only after human approval, avoiding routine hand-edits to YAML.
-- Add stronger deterministic draft adapters for Playwright and Maestro while keeping `manual` output for API, CLI, token, and catalog repositories.
+- Add stronger deterministic draft adapters for Playwright and Maestro while keeping `manual` output for API, CLI, token, and catalog repositories; runner detection itself is not a product success metric.
 - Expand the public benchmark corpus with package-scoped monorepos, auth/session changes, dynamic routes, API failure fixtures, and non-JavaScript services.
 - Keep the `--format agent` output a stable, versioned contract that skills and MCP wrappers can rely on.
 - Continue expanding agent surface detection across popular coding-agent tools without making the public workflow depend on a single vendor.
@@ -55,7 +64,8 @@ Before treating the next public release as ready, the golden demo must satisfy t
 
 ## Non-Goals
 
-- QAMap will not execute untrusted project code.
+- Static commands such as `qa`, `scan`, and planning modes will not execute scanned project code. Future execution requires an explicit command and a visible, policy-controlled execution plan.
+- QAMap will not implement its own browser or device automation engine; it will orchestrate proven local executors behind a framework-neutral QA contract.
 - QAMap will not replace tests, review, branch protection, threat modeling, or security review.
 - QAMap will not become a general-purpose code style linter.
 - QAMap will not become a deep MCP server analysis engine.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ivorycanvas/qamap",
-  "version": "0.3.5",
-  "description": "Local-first QA skill that turns PR diffs into affected flows, missing evidence, and E2E drafts with no cloud or LLM token.",
+  "version": "0.4.0",
+  "description": "Local zero-LLM PR QA designer that turns commit intent and diffs into behavior lifecycles, QA scenarios, and deterministic automation drafts.",
   "type": "module",
   "packageManager": "pnpm@10.32.1",
   "bin": {
@@ -39,6 +39,8 @@
     "mcp",
     "preflight",
     "pull-request",
+    "change-intent",
+    "behavior-graph",
     "e2e",
     "e2e-testing",
     "qa",

package/schema/qamap-agent.schema.json

@@ -45,7 +45,7 @@
     "runner": {
       "type": "string",
       "enum": ["maestro", "playwright", "manual"],
-      "description": "Recommended E2E runner for this repository."
+      "description": "Automation output adapter selected after runner-independent QA intent analysis."
     },
     "manifest": {
       "type": ["string", "null"],
@@ -71,6 +71,47 @@
         "files": { "type": "number", "minimum": 0 }
       }
     },
+    "intents": {
+      "type": "array",
+      "description": "Evidence-backed change intents derived before runner selection (capped).",
+      "items": {
+        "type": "object",
+        "required": ["title", "confidence", "reviewRequired", "evidence", "lifecycle", "scenarios"],
+        "properties": {
+          "title": { "type": "string" },
+          "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+          "reviewRequired": { "type": "boolean" },
+          "evidence": { "type": "array", "items": { "type": "string" } },
+          "lifecycle": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["phase", "label"],
+              "properties": {
+                "phase": {
+                  "type": "string",
+                  "enum": ["trigger", "condition", "action", "state-change", "side-effect", "observable-outcome"]
+                },
+                "label": { "type": "string" }
+              }
+            }
+          },
+          "scenarios": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["priority", "kind", "title", "assertions"],
+              "properties": {
+                "priority": { "type": "string", "enum": ["critical", "recommended"] },
+                "kind": { "type": "string", "enum": ["primary", "failure", "boundary", "state-transition"] },
+                "title": { "type": "string" },
+                "assertions": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          }
+        }
+      }
+    },
     "firstDraftCommand": {
       "type": "string",
       "description": "One command that creates the first E2E draft. Only present when the repository has no test suite and the diff reaches a product journey."