@ivorycanvas/qamap 0.3.5 → 0.4.1

package/docs/release-validation.md

@@ -1,5 +1,36 @@
 # Release Validation
 
+## 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:
+
+| 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 +114,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 +173,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 +186,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 +206,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 +236,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 +254,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 +281,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,11 +2,25 @@
 
 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.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.
@@ -80,11 +94,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

@@ -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.1",
+  "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": {
@@ -39,6 +39,8 @@
     "mcp",
     "preflight",
     "pull-request",
+    "change-intent",
+    "behavior-graph",
     "e2e",
     "e2e-testing",
     "qa",

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",
@@ -45,7 +64,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,9 +90,90 @@
         "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" } },
+          "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": {
+              "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" },
+                "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" } }
+              }
+            }
+          }
+        }
+      }
+    },
+    "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",
@@ -127,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).",
@@ -147,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"],