@ivorycanvas/qamap 0.3.4 → 0.4.0

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
@@ -367,7 +378,7 @@ If reusable repo-local evidence already exists, the PR QA output reads its conte
 
 ```txt
 Missing evidence before trusting this PR
-- [recommended] fixture: Confirm fixture coverage for /api/sentiments/current - Reuse src/services/demoSeedService.ts (exports demoSeedService) to build a deterministic response for /api/sentiments/current.
+- [recommended] fixture: Confirm fixture coverage for /api/sample/status - Reuse src/services/sampleSeed.ts (exports sampleSeed) to build a deterministic response for /api/sample/status.
 ```
 
 When an existing handler file already covers part of the flow, the next action names the file and the still-uncovered endpoints, for example `Extend src/mocks/handlers.ts (already handles /api/invoices) to also cover /api/payments/summary`. The generated Playwright mock bodies then reuse the response keys observed in that file (`invoices: "qamap-invoices"`) instead of the generic placeholder below, with a comment noting the source file.
@@ -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/manifest.md

@@ -56,6 +56,10 @@ QAMap cannot know every team's product priorities from file paths alone. The man
 
 When a recommendation is wrong, edit the manifest path shown in QAMap output. The next branch should get better recommendations without another explanation.
 
+For server projects, the generated baseline can include manual API contract flows inferred from common route, controller, handler, and framework-backed service modules. These flows use file anchors and start with success-contract and invalid-request checks; maintainers should still review names, criticality, and project-specific failure behavior before committing them as team policy.
+
+A domain match is useful even when no declared flow anchor matches. In that case QAMap keeps the existing code-derived flow, steps, selectors, and entrypoint, and adds the manifest domain as provenance. It does not fabricate flow-level checks. Add or correct a flow anchor when the team wants the manifest to supply durable checks and runner details on later PRs.
+
 ## Concrete Bootstrap Example
 
 A first baseline can be useful before a human writes YAML by hand. Suppose the default branch has:

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,33 @@
 # 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:
+
+| Gate | Current result |
+| --- | --- |
+| `pnpm test` | 127/127 passing |
+| `pnpm bench:ci` | Eight public PR fixtures pass; API and reverse-import fixtures also generate an external base manifest and require a manifest-backed head flow |
+| Coverage | Lines 86.09%, branches 83.18%, functions 94.66% |
+| `npm publish --dry-run --access public` | Passed for `@ivorycanvas/qamap@0.3.5`; 115 files, 772.8 kB packed |
+| API manifest baseline | Common server modules produce manual contract flows with API anchors and success/failure checks |
+| Domain fallback | Domain-only matches preserve manifest provenance without claiming unrelated files or inventing manifest checks |
+| Privacy | Public changes use synthetic fixtures; private smoke output remains outside the repository |
+
 ## 0.3.4 - 2026-07-10
 
 Validated before publishing `0.3.4` with a committed, CI-enforced recommendation contract instead of relying only on private smoke repositories:
@@ -69,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
@@ -126,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
@@ -137,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
@@ -156,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
@@ -184,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.
@@ -199,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. |
@@ -216,43 +255,17 @@ The matrix below is public, fixture-backed evidence from the repository test sui
 
 See [E2E output examples](e2e-output-examples.md) for the kind of plan and draft snippets users should see from the current release.
 
-## Latest PR Validation Snapshot
-
-Last verified on 2026-07-03 for the 0.3.1 README demo patch after removing the stale animated GIF from the README and npm tarball:
-
-| Check | Result |
-| --- | --- |
-| `pnpm test` | 95 tests passed. |
-| `git diff --check` | Passed. |
-| `pnpm pack --dry-run` | Passed; tarball includes 97 files and no committed demo GIF. |
-| `npm publish --dry-run --access public` | Passed for `@ivorycanvas/qamap@0.3.1`; package size is 289.1 kB and includes the manifest schema, quick-start docs, release docs, and `skills/qamap-pr-qa/SKILL.md`. |
-
-## Real Repository Smoke Snapshot
-
-The latest smoke run used private representative repositories and wrote draft output only under `/tmp/qamap-preview-*`. The smoke commands did not run `e2e setup` or write generated files into the target repositories. The table records public-safe target shapes rather than private repository names.
-
-2026-07-02 follow-up smoke on PR #71 ran `manifest context`, `manifest init --write /tmp/...`, `e2e plan`, and `e2e draft --dry-run` across 14 local Git repositories plus package-scoped scans for a large frontend monorepo. All commands completed without changing target repository status. The run exposed one important adoption need: users should be able to generate a manifest outside the target repo and pass it back into PR commands. PR #71 now supports that read-only preview through `--manifest <file>`.
-
-The same follow-up also showed the next quality gap. External manifest previews work, but many real branch changes did not match route/page-only manifest anchors, so generated drafts often stayed `domain-language`, `review-only`, or `near-runnable` instead of `verification-manifest`. The next release bar should improve component, function, API client, query, schema, and test anchors so manifest matches cover more than route files.
-
-| Target shape | Base/head mode | Result | Follow-up signal |
-| --- | --- | --- | --- |
-| Expo / React Native manifest baseline | `manifest init` wrote only to `/tmp/qamap-journal-note-manifest.yaml` | Generated 9 domains, 8 flows, 8 anchors, and 16 checks without changing the target repo. Direct `app/*.tsx` screens now produce specific paths such as `app/SentimentChatPage.tsx`; `+not-found.tsx` is not promoted as a product domain. | Good 0.2.x signal for baseline quality. Remaining work is richer screen/route semantics and selector-specific checks. |
-| Web monorepo package | Package scan with `--workspace-root`, feature branch compared with `main`, working tree included | Detected `web`, recommended Playwright, inferred a concrete route, produced changed-flow specs, and correctly blocked promotion because Playwright config, deterministic fixture/mock data, selector evidence, and validation evidence were missing. | Flow naming improved, but docs/design-only files can still create low-signal drafts that should be filtered or demoted. |
-| Expo / React Native app | Feature branch compared with `develop`, working tree included | Detected `expo-react-native`, recommended Maestro, found an existing Jest suite, produced multiple near-runnable YAML drafts, and gave useful blockers for missing Maestro directory plus missing stable mobile selectors. | Strongest current real-repo result; remaining gap is selector and app-specific setup quality. |
-| Nuxt / Vue web app with existing Playwright tests | `origin/develop` to `HEAD`, working tree included | Detected `web`, recommended Playwright, recognized existing test evidence, and blocked draft promotion because no Playwright config or runnable route/screen entrypoint was inferred. | Test-only or generated-test changes can still produce generic smoke draft names; QAMap should better distinguish changed tests from changed product behavior. |
-| Django-style API service | `origin/develop` to `HEAD`, working tree included | Detected `api-service`, selected manual output, found a large pytest suite, generated API contract and configuration checklists with zero TODOs, and avoided browser/device runner assumptions. | Good service classification; fixture readiness should become more endpoint-specific. |
-| Design token repository | `main` to `HEAD`, working tree included | Detected `design-tokens`, selected manual output, avoided browser/device selector requirements, and produced review-only artifact validation output. | Docs-only or style-only changes may still surface content/theme wording instead of token artifact language. |
-| Taxonomy / data catalog repository | `main` to `HEAD`, working tree included | Detected `data-catalog`, selected manual output, avoided API mock requirements, and produced review-only checklist output with no TODOs. | Catalog-specific changes are handled, but docs/config-only changes should be labeled more explicitly as low-signal. |
+## Private Smoke Protocol
 
-Interpretation: the next release should be described as a planner that removes blank-page verification work by combining static analysis with repo-local manifest memory. The smoke results are useful, but they also show that many real repositories will start at `review-only` or `near-runnable` until teams add runner config, selectors, fixtures, validation evidence, and durable manifests.
+Private repositories may be used as local, read-only diagnostics, but their raw output is never release documentation or fixture input. Write manifests and drafts only to an operating-system temp directory, compare target `git status` before and after, and retain no repository names, paths, flow titles, source excerpts, or domain vocabulary in commits or pull requests. Reduce every confirmed defect to a minimal synthetic fixture before it enters the public suite.
 
 ## Ongoing Validation Notes
 
-The release candidate has passed the fixture-backed suite, package dry-run, npm publish dry-run, and representative private-repository smoke checks recorded above. For future patch releases, record only public-safe notes in this document or in release notes:
+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
@@ -260,7 +273,7 @@ The release candidate has passed the fixture-backed suite, package dry-run, npm
 
 ## Stop Conditions
 
-Do not publish `0.2.1` if any representative target shows one of these problems:
+Do not publish the current candidate if any representative target shows one of these problems:
 
 - generated flow names are dominated by generic folder names instead of product language
 - test-only or docs-only changes are presented as confident product journeys without low-signal wording

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.4",
-  "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."