@ivorycanvas/qamap 0.4.0 → 0.4.1

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,22 @@
 # 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:

package/docs/releasing.md

@@ -20,6 +20,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 +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/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.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": {

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: