@ivorycanvas/qamap 0.4.0 → 0.4.2

package/docs/benchmarking.md

@@ -48,6 +48,8 @@ Each target can declare:
 | `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. |
@@ -61,7 +63,16 @@ Each target can declare:
 | `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. |
+| `minReadinessScore` | Minimum aggregate draft-readiness score after self-check, TODO, required-action, and execution-blocker penalties. |
+| `allowedReadinessLevels` | Accepted aggregate levels: `ready`, `near-runnable`, `needs-work`, or `blocked`. Use this to prevent a semantically plausible but unusable draft from satisfying the contract. |
+| `minTryableDrafts` | Minimum files classified as `runnable-candidate` or `near-runnable`. |
+| `minRunnableCandidates` | Minimum files classified as `runnable-candidate` with no known execution blockers. |
+| `minSelfCheckPass` | Minimum generated files whose static draft self-check passes. This does not claim that the target application was executed. |
+| `maxSelfCheckFail` | Maximum generated files whose static draft self-check fails. Warnings may remain for honest setup or domain-assertion gaps. |
+| `maxReviewOnlyFiles` | Maximum generated files that remain reference-only instead of tryable automation. |
+| `maxTodos` | Maximum unresolved TODO markers across generated drafts. |
+| `maxExecutionBlockers` | Maximum unresolved execution blockers across generated drafts. Contract failures name the most common blocker. |
 
 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.
 
@@ -77,7 +88,7 @@ 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 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.
+Saved results include intent titles, lifecycle and scenario terms, scenario trace coverage, flow titles, draft paths, recall gaps, raw readiness counts, self-check outcomes, TODOs, execution blockers, agent payload size, and timing. The table reports draft status as `runnable/near-runnable/review-only`. 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.
 

package/docs/commands.md

@@ -223,6 +223,10 @@ The draft result is meant to be useful as a PR artifact, not only as generated f
 - `actionSummary`: total required/recommended action counts, ready file count, and the most common action categories
 - `readinessSummary`: an overall 0-100 score, readiness level, self-check counts, starter-code gaps, execution blocker counts, and top blockers
 
+`runnable-candidate` means QAMap found no known blocker to trying the generated file with the detected local command. It is not a claim that the scenario is complete or that the PR is safe to merge. Missing failure coverage, unconfirmed fixture values, and other proof gaps remain visible as required or recommended action items and in the validation matrix. `near-runnable` means the file still has a concrete setup or execution gap; `review-only` means it should be used as design guidance rather than executed as automation.
+
+Playwright self-checks also reject false confidence from `body`-only smoke assertions. When static evidence includes a mockable endpoint, a stable action selector, and visible failure copy, QAMap emits a deterministic 4xx/5xx route, repeats the action, and asserts the failure outcome. When any of those facts are missing, the draft keeps a domain-assertion warning rather than inventing behavior.
+
 See [docs/e2e-output-examples.md](e2e-output-examples.md) for compact examples of web, mobile, API/service, CLI, test-light, and monorepo output.
 
 Generated Playwright drafts use the flow language as `test.step()` names so the file reads like the user journey it protects:

package/docs/e2e-output-examples.md

@@ -330,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`
-
-Bootstrap summary:
-4 required bootstrap steps must be resolved before generated E2E drafts should be treated as regression coverage.
-
-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
+## Optional Automation
+
+The QA judgment above does not require adopting this adapter.
+
+- 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:

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
@@ -148,11 +149,12 @@ Output
 - 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
-- automation adapter selected after QA design
-- draft file path
+- optional automation adapter selected after QA design
+- optional draft file path
 - flow language brief
 - runnable status
 - self-check status
@@ -160,7 +162,7 @@ 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
 
@@ -168,29 +170,32 @@ The result should not stop at "selector needed" or "fixture needed." A useful QA
 # 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
+- Change intent: Submit notification preferences and show the saved state [high]
+- Behavior lifecycle: trigger -> state-change -> side-effect -> observable-outcome
 
 Summary
 - Project: Web
-- Automation adapter: 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

package/docs/release-validation.md

@@ -1,5 +1,39 @@
 # Release Validation
 
+## 0.4.2 - 2026-07-13
+
+Validated as an automation-readiness honesty patch. Benchmark contracts now fail when QAMap finds a plausible flow but emits a draft that cannot be tried, and generated Playwright failure paths require a repository-observed endpoint, stable action, and visible failure outcome before QAMap writes executable steps:
+
+| Gate | Current result |
+| --- | --- |
+| `pnpm release:check` | Passed end to end |
+| `pnpm test` | 146/146 passing |
+| `pnpm scan` | 0 findings |
+| `pnpm bench:ci` | 12/12 synthetic PR targets pass; readiness, runnable-candidate, self-check, TODO, review-only, and execution-blocker contracts are enforced |
+| Coverage | Lines 87.53%, branches 84.18%, functions 95.22% |
+| Existing Playwright golden | Improved from `needs-work 67` with one blocker to `near-runnable 97`, one runnable candidate, and zero execution blockers |
+| Honest weak-draft handling | Testless checkout and shared-component fixtures remain `needs-work 48` because missing execution facts and body-only assertions are not promoted to runnable evidence |
+| Package preview | `pnpm pack --dry-run` and `npm publish --dry-run --access public` pass for `@ivorycanvas/qamap@0.4.2`; 129 files, 828.8 kB packed |
+
+This patch does not claim that all generated E2E files are green in their target applications. It makes that gap measurable: repository validation guidance no longer masquerades as a generated-file execution blocker, body-only smoke assertions remain warnings, and only evidence-backed failure flows compile into Playwright actions and assertions.
+
+## 0.4.1 - 2026-07-13
+
+Validated as an evidence-first QA patch. A proposed scenario now exposes the commit or exact base/head diff file, line, symbol, hunk, and direct/supporting/contextual relation that caused it. Removed guards remain visible as base-side critical evidence, contextual-only scenarios cannot become critical, and runner adoption remains an explicit step after review:
+
+| Gate | Current result |
+| --- | --- |
+| `pnpm release:check` | Passed end to end |
+| `pnpm test` | 146/146 passing |
+| `pnpm scan` | 0 findings |
+| `pnpm bench:ci` | 12/12 synthetic PR targets pass; web and mobile lifecycle scenarios both retain 4/4 exact diff traces |
+| Coverage | Lines 87.49%, branches 83.99%, functions 95.20% |
+| Agent payload | Evidence-rich lifecycle fixtures are 5,288 and 5,659 bytes; a large real mobile branch compacts from 10,873 to 8,111 bytes while disclosing omitted counts |
+| Package preview | `pnpm pack --dry-run` and `npm publish --dry-run --access public` pass for `@ivorycanvas/qamap@0.4.1`; 129 files, 825.5 kB packed |
+| Read-only repository smoke | A large mobile branch and a web workspace branch were rechecked after base-side evidence and output compaction; both target worktrees remained unchanged |
+
+The large mobile branch retained zero untraced critical scenarios. A removed release guard was tied to its exact base-side line and translated into local/development/QA/production configuration checks rather than an unrelated user-authorization scenario. Its agent payload reports 44 total intents, 2 retained intents, and 42 omitted intents within 8,111 bytes. The release-shaped web branch still had no behavior-bearing commit intent and therefore emitted four broader review-only flows with zero critical scenarios; this remains an explicit precision limit rather than promoted confidence.
+
 ## 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:

package/docs/releasing.md

@@ -10,8 +10,9 @@ QAMap keeps major and minor changes deliberately rare during `0.x` development.
 - 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.
+- Do not schedule `0.5.x` by date or implementation count. Continue `0.4.x` patches until external repository evidence shows that static QA design and automation drafts are dependable enough to support a new execution contract.
 
-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 `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 remains unscheduled and is reserved for explicit temporary execution and normalized evidence without modifying the target repository. That capability must be proven across unrelated repositories before a `0.5.0` candidate is cut.
 
 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.
 
@@ -20,6 +21,7 @@ Version `1.0.0` requires a stable public contract and external adoption, not imp
 Before publishing, confirm:
 
 - `package.json` version matches the intended npm version.
+- The canonical release identifier is `vX.Y.Z` (for example, `v0.4.0`). The Git tag and GitHub Release title must match this identifier exactly.
 - `CHANGELOG.md` has a dated section for the version being published.
 - `README.md`, [adoption](adoption.md), [E2E examples](e2e-output-examples.md), and [release validation](release-validation.md) describe the current CLI behavior.
 - `pnpm run release:check` passes from a clean checkout.
@@ -93,11 +95,20 @@ Use a fresh shell or temporary directory for the smoke check when possible.
 After npm publish succeeds:
 
 ```sh
-git tag "v$VERSION"
-git push origin "v$VERSION"
+TAG="v$VERSION"
+git tag -a "$TAG" -m "$TAG"
+git push origin "$TAG"
 ```
 
-Create a GitHub Release for the tag with:
+Create a GitHub Release whose display title is exactly the tag:
+
+```sh
+gh release create "$TAG" --title "$TAG" --notes-file <release-notes.md>
+```
+
+Do not prefix the title with `QAMap` or `CodeWard`, and do not add a descriptive subtitle. Product positioning and highlights belong in the release notes body so the release list remains consistently sortable as `vX.Y.Z`.
+
+The release notes body should contain:
 
 - a concise release summary
 - the current `CHANGELOG.md` section

package/docs/roadmap.md

@@ -24,16 +24,20 @@ Before treating the next public release as ready, the golden demo must satisfy t
 - 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.
+- The public benchmark distinguishes a tryable file from complete PR evidence: golden automation fixtures contract on self-checks, TODOs, execution blockers, and runnable status instead of passing on flow naming alone.
 - 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: 0.4.x
 
+There is no fixed end date or patch count for `0.4.x`. QAMap will remain on compatible patch releases while real repositories still expose material gaps in change intent, affected-flow selection, scenario evidence, or automation-draft quality. `0.5.x` is not the next scheduled milestone; it is a release bar that must be earned by a stable, explicitly approved execution contract and evidence from repeated use outside the maintainer's repositories.
+
 - 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.
+- Keep execution readiness separate from validation completeness. A draft may be locally runnable while still requiring failure coverage, fixture confirmation, or reviewer approval before it becomes trusted PR evidence.
 - 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.
@@ -42,12 +46,13 @@ Before treating the next public release as ready, the golden demo must satisfy t
 - 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
+## Longer-Term Release Bar (No Scheduled 0.5.x Date)
 
 - 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.
+- Compile critical success and failure scenarios into concrete runner actions before execution, so a green smoke assertion cannot satisfy a lifecycle or coverage contract by itself.
 - 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; runner detection itself is not a product success metric.
@@ -55,6 +60,8 @@ Before treating the next public release as ready, the golden demo must satisfy t
 - 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.
 
+These items do not imply that the next completed item triggers a minor release. Analyzer improvements, new deterministic scenarios, stronger adapters, and additional benchmark fixtures continue as `0.4.x` patches when they preserve the public CLI, schema, and safety contracts. A `0.5.0` candidate should be considered only when policy-controlled execution is useful across unrelated repositories, the target repository remains unmodified by default, and normalized evidence is stable enough to document as a new public capability.
+
 ## Later
 
 - Policy packs for open source, startup teams, and security-sensitive repositories.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ivorycanvas/qamap",
-  "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.",
+  "version": "0.4.2",
+  "description": "Local zero-LLM PR QA designer that maps commit intent and diffs to traceable behavior lifecycles, QA scenarios, and optional automation drafts.",
   "type": "module",
   "packageManager": "pnpm@10.32.1",
   "bin": {

package/schema/qamap-agent.schema.json

@@ -5,6 +5,25 @@
   "description": "The single-line JSON object printed by `qamap qa --format agent`. Within schema version 1, fields are only ever added — existing fields are never removed or retyped. A breaking change bumps schema.version to 2.",
   "type": "object",
   "additionalProperties": true,
+  "definitions": {
+    "evidenceSource": {
+      "type": "object",
+      "required": ["kind", "reason"],
+      "properties": {
+        "kind": { "type": "string", "enum": ["commit", "diff", "source"] },
+        "reason": { "type": "string" },
+        "commit": { "type": "string" },
+        "file": { "type": "string" },
+        "previousFile": { "type": "string" },
+        "symbol": { "type": "string" },
+        "relation": { "type": "string", "enum": ["direct", "supporting", "contextual"] },
+        "side": { "type": "string", "enum": ["base", "head"] },
+        "startLine": { "type": "integer", "minimum": 0 },
+        "endLine": { "type": "integer", "minimum": 0 },
+        "hunk": { "type": "string" }
+      }
+    }
+  },
   "required": [
     "schema",
     "base",
@@ -82,6 +101,17 @@
           "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
           "reviewRequired": { "type": "boolean" },
           "evidence": { "type": "array", "items": { "type": "string" } },
+          "sources": {
+            "type": "array",
+            "items": { "$ref": "#/definitions/evidenceSource" },
+            "description": "Structured commit and diff locations behind the intent (capped)."
+          },
+          "scenarioCount": { "type": "integer", "minimum": 0 },
+          "omittedScenarioCount": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of lower-ranked scenarios omitted from the compact payload. Use the human or JSON format when non-zero."
+          },
           "lifecycle": {
             "type": "array",
             "items": {
@@ -105,6 +135,13 @@
                 "priority": { "type": "string", "enum": ["critical", "recommended"] },
                 "kind": { "type": "string", "enum": ["primary", "failure", "boundary", "state-transition"] },
                 "title": { "type": "string" },
+                "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+                "reviewRequired": { "type": "boolean" },
+                "sources": {
+                  "type": "array",
+                  "items": { "$ref": "#/definitions/evidenceSource" },
+                  "description": "The strongest diff or commit locations that caused this scenario to be proposed (capped)."
+                },
                 "assertions": { "type": "array", "items": { "type": "string" } }
               }
             }
@@ -112,9 +149,31 @@
         }
       }
     },
+    "intentCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total inferred intents before compact output capping."
+    },
+    "omittedIntentCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Intents omitted from the compact payload."
+    },
     "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."
+      "description": "Deprecated v1 field retained for compatibility. New output uses the opt-in automation object instead of promoting runner setup as the default QA action."
+    },
+    "automation": {
+      "type": "object",
+      "description": "Optional adapter handoff after a reviewer accepts the QA scenario. It is not required to use the QA judgment.",
+      "required": ["optIn", "adapter", "setupStatus", "draftCommand"],
+      "properties": {
+        "optIn": { "const": true },
+        "adapter": { "type": "string", "enum": ["maestro", "playwright", "manual"] },
+        "setupStatus": { "type": "string", "enum": ["ready", "proposed", "not-applicable"] },
+        "draftCommand": { "type": "string" },
+        "setupCommand": { "type": "string" }
+      }
     },
     "flows": {
       "type": "array",
@@ -168,6 +227,25 @@
         }
       }
     },
+    "flowCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total affected flows before compact output capping."
+    },
+    "omittedFlowCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Flows omitted from the compact payload."
+    },
+    "compaction": {
+      "type": "object",
+      "description": "Present when QAMap reduced lower-priority detail to keep the complete line at or below 8KB.",
+      "properties": {
+        "maxBytes": { "type": "integer", "minimum": 1 },
+        "originalBytes": { "type": "integer", "minimum": 1 },
+        "emergency": { "type": "boolean" }
+      }
+    },
     "requiredEvidence": {
       "type": "array",
       "description": "QA evidence the change still needs before merge (required priority only, capped at 8).",
@@ -188,7 +266,7 @@
     },
     "requiredBootstrap": {
       "type": "array",
-      "description": "Setup steps that must happen before drafts can be treated as regression coverage (capped at 3).",
+      "description": "Non-runner repository context steps (capped at 3). Runner adoption is exposed separately under the opt-in automation object.",
       "items": {
         "type": "object",
         "required": ["title", "action"],

package/schema/qamap-behavior.schema.json

@@ -96,6 +96,38 @@
         "file": {
           "type": "string",
           "minLength": 1
+        },
+        "previousFile": {
+          "type": "string",
+          "minLength": 1
+        },
+        "symbol": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "minLength": 1
+        },
+        "relation": {
+          "type": "string",
+          "enum": ["direct", "supporting", "contextual"]
+        },
+        "side": {
+          "type": "string",
+          "enum": ["base", "head"]
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "hunkHeader": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },

package/skills/qamap-pr-qa/SKILL.md

@@ -34,28 +34,28 @@ Use QAMap as a final local QA pass before presenting a pull request for human re
    ```
 
 4. Read and verify intent before generating code. In agent format:
-   - `intents[]` — commit/diff evidence, confidence, `reviewRequired`, ordered lifecycle, and primary/failure/boundary/state-transition scenarios.
+   - `intents[]` — commit/diff evidence, confidence, `reviewRequired`, ordered lifecycle, and primary/failure/boundary/state-transition scenarios. Read each scenario's structured `sources` before accepting it; a diff source carries `file`, head-side line numbers, symbol, and hunk.
    - If `reviewRequired` is true or the lifecycle conflicts with the PR, ask a human to confirm the intended behavior before promoting a draft.
    - `flows[]` — affected flows with `draft` path, `runnable` status, entry route, capped steps, and selectors.
    - `requiredEvidence[]` — evidence that must exist before the PR can be trusted; `recommendedEvidenceCount` for the rest.
-   - `requiredBootstrap[]` — setup steps that block trusting generated drafts.
+   - `requiredBootstrap[]` — non-runner repository context that still needs clarification.
+   - `automation` — an optional adapter handoff. It is not required to use the QA judgment.
    - `prChecklist[]` and `commands[]` — checklist lines and validation commands for the handoff.
 
-5. If the intent is credible and QAMap prints `First E2E Draft Bootstrap`, create the starter draft instead of stopping at broad QA notes:
+5. Only after a human or team accepts the scenario and automation adapter, create or preview executable coverage:
 
    ```sh
-   pnpm exec qamap e2e setup . --runner <runner>
+   pnpm exec qamap e2e draft . --base <base> --head HEAD
    ```
 
-   Use the exact create command from the output when it differs.
-   `firstDraftCommand` is present only when the repo has no test suite; run it to create the first starter draft. In markdown format, start from `At a Glance` and `Change Intent Evidence`, then read the PR comment, missing evidence, and checklist sections.
+   If the selected adapter is absent, inspect and explicitly accept the `automation.setupCommand` proposal. Never install a runner merely because QAMap detected a web or mobile surface.
 6. Include the useful parts in the PR body, review note, or handoff summary.
 
 ## Output Rules
 
 - Treat QAMap output as QA planning evidence, not proof that browser, device, API, or manual QA passed.
-- Preserve change intent, confidence, lifecycle, QA scenarios, affected flow, suggested E2E/checklist path, missing evidence, and validation command in the handoff.
-- Prefer creating the suggested starter E2E draft over only reporting that a draft is needed.
+- Preserve change intent, confidence, lifecycle, QA scenarios, their strongest file/line sources, affected flow, missing evidence, and validation command in the handoff.
+- Keep automation optional until the scenario and its evidence have been reviewed.
 - Treat Playwright, Maestro, and manual output as adapters after QA design. Do not let runner selection replace review of the inferred intent and scenarios.
 - If the output is `review only` or `near runnable`, explain what blocks it from becoming trusted regression evidence.
 - If `qamap qa` says no manifest was found, do not stop. The first run is allowed to be manifest-free.
@@ -79,6 +79,7 @@ QAMap QA
 - Change intent and confidence:
 - Behavior lifecycle:
 - Required QA scenarios:
+- Scenario source files/lines:
 - Affected flow:
 - Suggested E2E/checklist:
 - Missing evidence: