@ivorycanvas/qamap 0.4.2 → 0.4.3

package/docs/assets/qamap-cover.svg

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-labelledby="title description">
+  <title id="title">QAMap</title>
+  <desc id="description">A local PR QA workflow from commits and diffs to behavior and QA evidence.</desc>
+  <rect width="1280" height="640" fill="#07111f"/>
+  <rect x="40" y="40" width="1200" height="560" rx="24" fill="none" stroke="#27466e" stroke-width="2"/>
+
+  <g font-family="Arial, Helvetica, sans-serif">
+    <text x="112" y="150" fill="#eef5ff" font-size="74" font-weight="700">QAMap</text>
+    <text x="116" y="208" fill="#32c4f5" font-size="30">Find what a change needs to prove.</text>
+    <text x="116" y="258" fill="#a9bddb" font-size="23">Local PR QA design from commits and diffs.</text>
+
+    <g transform="translate(116 306)">
+      <rect width="142" height="36" rx="18" fill="#103e38"/>
+      <text x="71" y="24" fill="#56e0b0" font-family="Menlo, Monaco, monospace" font-size="16" text-anchor="middle">LOCAL</text>
+      <rect x="160" width="162" height="36" rx="18" fill="#173b5a"/>
+      <text x="241" y="24" fill="#50caff" font-family="Menlo, Monaco, monospace" font-size="16" text-anchor="middle">ZERO LLM</text>
+      <rect x="340" width="192" height="36" rx="18" fill="#4e3610"/>
+      <text x="436" y="24" fill="#ffbf38" font-family="Menlo, Monaco, monospace" font-size="16" text-anchor="middle">OPEN SOURCE</text>
+    </g>
+
+    <g transform="translate(114 422)">
+      <rect x="0" y="0" width="238" height="92" rx="12" fill="#0d1a2d" stroke="#315277" stroke-width="2"/>
+      <text x="28" y="37" fill="#eef5ff" font-family="Menlo, Monaco, monospace" font-size="19">commit + diff</text>
+      <text x="28" y="65" fill="#8fa8c8" font-size="16">intent evidence</text>
+
+      <path d="M260 46H332" fill="none" stroke="#4a87b7" stroke-width="3"/>
+      <path d="M322 35L336 46L322 57" fill="none" stroke="#4a87b7" stroke-width="3"/>
+
+      <rect x="354" y="0" width="238" height="92" rx="12" fill="#0d1a2d" stroke="#315277" stroke-width="2"/>
+      <text x="382" y="37" fill="#eef5ff" font-family="Menlo, Monaco, monospace" font-size="19">behavior flow</text>
+      <text x="382" y="65" fill="#8fa8c8" font-size="16">what changed</text>
+
+      <path d="M614 46H686" fill="none" stroke="#4a87b7" stroke-width="3"/>
+      <path d="M676 35L690 46L676 57" fill="none" stroke="#4a87b7" stroke-width="3"/>
+
+      <rect x="708" y="0" width="238" height="92" rx="12" fill="#0d1a2d" stroke="#315277" stroke-width="2"/>
+      <text x="736" y="37" fill="#eef5ff" font-family="Menlo, Monaco, monospace" font-size="19">QA evidence</text>
+      <text x="736" y="65" fill="#8fa8c8" font-size="16">what to verify</text>
+    </g>
+
+    <g transform="translate(946 139)">
+      <path d="M0 40V84C0 115 18 134 48 144" fill="none" stroke="#19bef2" stroke-width="7" stroke-linecap="round"/>
+      <path d="M94 40V84C94 115 76 134 48 144" fill="none" stroke="#19bef2" stroke-width="7" stroke-linecap="round"/>
+      <path d="M47 40V144" fill="none" stroke="#19bef2" stroke-width="7" stroke-linecap="round"/>
+      <path d="M48 144V179" fill="none" stroke="#19bef2" stroke-width="7" stroke-linecap="round"/>
+      <circle cx="0" cy="29" r="17" fill="#07111f" stroke="#19bef2" stroke-width="7"/>
+      <circle cx="47" cy="29" r="17" fill="#07111f" stroke="#19bef2" stroke-width="7"/>
+      <circle cx="94" cy="29" r="17" fill="#07111f" stroke="#19bef2" stroke-width="7"/>
+      <circle cx="48" cy="144" r="17" fill="#07111f" stroke="#19bef2" stroke-width="7"/>
+      <circle cx="48" cy="211" r="35" fill="#07111f" stroke="#ffb414" stroke-width="8"/>
+      <path d="M29 211L43 225L68 197" fill="none" stroke="#ffb414" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+
+    <text x="806" y="538" fill="#c8d8ed" font-family="Menlo, Monaco, monospace" font-size="20">github.com/IvoryCanvas/qamap</text>
+  </g>
+</svg>

package/docs/benchmarking.md

@@ -50,6 +50,11 @@ Each target can declare:
 | `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. |
+| `minScenarioReceipts` | Minimum routed scenario receipts emitted by the E2E adapter. |
+| `maxMissingScenarioReceipts` | Maximum selected QA scenarios with no corresponding automation receipt. Public lifecycle fixtures keep this at zero. |
+| `minRoutedRequiredScenarios` | Minimum critical scenarios promoted to required by located direct or supporting diff evidence. |
+| `maxRequiredScenarioGaps` | Maximum required scenarios that remain partial or not compiled. Use only for fixtures whose adapter coverage is expected to be complete. |
+| `minMappedScenarioAssertions` | Minimum selected assertions mapped to observable runner assertions across scenario receipts. |
 | `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. |
@@ -88,7 +93,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, 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.
+Saved results include intent titles, lifecycle and scenario terms, scenario trace coverage, scenario receipt 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` and scenario compilation as `compiled/partial/not-compiled`. 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.
 
@@ -101,4 +106,6 @@ When a real repository produces a poor recommendation:
 3. Confirm `pnpm bench:ci` fails for the intended reason.
 4. Fix the inference and keep the fixture as permanent regression evidence.
 
+Any new production heuristic must be exercised by at least two unrelated positive domains and one negative or false-positive control. Domain vocabulary belongs in synthetic fixtures, not in shared inference rules.
+
 Do not copy repository names, proprietary code, domain language, file paths, credentials, production data, or raw smoke output into a public fixture. Reduce the behavior to neutral synthetic vocabulary and keep private diagnostics outside the repository.

package/docs/e2e-output-examples.md

@@ -10,44 +10,55 @@ First contact should work without a manifest:
 pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD
 ```
 
-The output should be specific enough to paste into a PR comment:
+The output should be specific enough to paste into a PR comment. This excerpt uses the committed web preferences lifecycle benchmark; it deliberately keeps the current compiler gaps visible:
 
 ```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: Submit notification preferences and show the saved state [high]
+- Behavior lifecycle: trigger: submit preferences -> state-change: update saved state -> side-effect: invoke fetch -> observable-outcome: show saved state
+- Affected behavior: Submit notification preferences and show the saved state
 
 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
+- Commit: feat: submit notification preferences, persist the selected timezone, and show the saved state after the request completes
+- Critical scenario: Submit notification preferences and show the saved state
+  - Routing: required; 3 supporting diff hunks
+  - E2E mapping: partial; steps 0/3, assertions 1/1
+  - Assert: the saved state becomes observable
 - Recommended scenario: Failure, timeout, and retry handling
+  - Routing: recommended; 1 supporting diff hunk
+  - E2E mapping: not compiled; no deterministic failure compiler matched all required evidence
 
 Summary
 - Project: Web
 - Automation adapter: Playwright
 - Manifest: not found; using repo signals and PR diff only
-- Stage: almost runnable (3 of 4)
+- Stage: setup needed (1 of 4); readiness 37/100
+- Scenario routing: 2 required, 2 recommended, 0 review-only
+- E2E mapping: 0 compiled, 1 partial, 3 not compiled
 
 PR Comment Draft
-- 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
+- Affected flow: Submit notification preferences and show the saved state
+- User journey: User -> Open route /preferences -> Submit preferences
+- Success signal: visible text "Preferences saved" appears
+- Changed files: src/pages/preferences.tsx
 
 Suggested E2E / QA Draft
-- tests/e2e/submit-checkout-and-persist-the-confirmed-order.spec.ts: near runnable
-- Open route /checkout.
-- Fill checkout email.
-- Submit checkout.
-- Assert confirmation state is visible after submit.
+- tests/e2e/submit-notification-preferences-persist-the-selected-timezone-and-show-the-saved.spec.ts: near runnable
+- Open route /preferences.
+- Submit notification preferences.
+- Assert visible text "Preferences saved" appears.
+
+Scenario automation receipts
+- [required] Submit notification preferences and show the saved state: partial (steps 0/3, assertions 1/1)
+  - Blocker: three selected action steps remain outside executable coverage
+- [recommended] Failure, timeout, and retry handling: not compiled (steps 0/2, assertions 0/2)
+  - Blocker: no deterministic failure compiler matched an entrypoint, action, fixture boundary, and observable outcome
 
 Missing evidence before trusting this PR
-- [required] fixture: Add deterministic fixture or mock data.
-- [recommended] selector: Confirm stable selectors.
+- [required] fixture: Add deterministic fixture or mock data for /api/preferences.
+- [required] assertion: Compile required QA scenarios into executable coverage.
 
 PR checklist
 - [ ] Review the generated draft path.
@@ -55,6 +66,8 @@ PR checklist
 - [ ] Run local validation: pnpm run test:e2e
 ```
 
+The counts above describe static compilation, not execution. `compiled` means the selected steps and assertions were mapped to concrete runner code. Only an explicit validation command can turn that draft into pass or fail evidence.
+
 If this recommendation is useful but slightly wrong, the next step is not another long AI prompt. Generate and correct repo-local QA memory:
 
 ```sh

package/docs/release-validation.md

@@ -1,5 +1,22 @@
 # Release Validation
 
+## 0.4.3 - 2026-07-14
+
+Validated as an evidence-routed QA-to-automation patch. Intent-backed scenarios are selected from exact diff evidence before an adapter is chosen, and every selected scenario carries a receipt that states whether its setup, action, and assertion were compiled, partially mapped, left uncompiled, or retained for review only:
+
+| Gate | Current result |
+| --- | --- |
+| `pnpm release:check` | Passed end to end |
+| `pnpm test` | 148/148 passing |
+| `pnpm scan` | 0 findings |
+| `pnpm bench:ci` | 12/12 synthetic PR targets pass; both lifecycle fixtures preserve 4/4 exact diff traces and 4/4 scenario automation receipts |
+| Coverage | Lines 87.64%, branches 84.19%, functions 95.32% |
+| Required QA honesty | Required scenarios that are only partially mapped or not compiled lower readiness and remain explicit blockers instead of being hidden behind a syntactically valid draft |
+| Failure-path safety | A positive fixture compiles repository-backed failure setup, action, and outcome evidence; a negative control proves an unrelated stable selector is not reused |
+| Package preview | `pnpm pack --dry-run` and `npm publish --dry-run --access public` pass for `@ivorycanvas/qamap@0.4.3`; 134 files, 914.2 kB packed |
+
+This patch does not add product-specific payment, order, or upload rules. The shared engine ranks scenarios from runner-independent evidence relations and only compiles a failure path when the repository exposes a compatible endpoint boundary, related action selector, and observable outcome. Review-only and incomplete mappings remain visible to humans and agents rather than being presented as runnable E2E coverage.
+
 ## 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:

package/docs/roadmap.md

@@ -44,6 +44,8 @@ There is no fixed end date or patch count for `0.4.x`. QAMap will remain on comp
 - 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 Playwright and Maestro compilation from intent scenarios while keeping runner choice behind the runner-independent QA contract.
+- Keep scenario selection and automation compilation independently measurable: exact diff evidence routes each scenario as required, recommended, or review-only, then runner receipts report compiled, partial, or not-compiled coverage. Required compilation gaps must lower readiness instead of hiding behind a green smoke assertion.
+- Require every new shared heuristic to pass unrelated web/mobile or UI/service fixtures plus a negative control. Product-specific vocabulary stays in fixtures and optional manifests, never in global rules.
 - 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.
 
 ## Longer-Term Release Bar (No Scheduled 0.5.x Date)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivorycanvas/qamap",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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",

package/schema/qamap-agent.schema.json

@@ -134,6 +134,7 @@
               "properties": {
                 "priority": { "type": "string", "enum": ["critical", "recommended"] },
                 "kind": { "type": "string", "enum": ["primary", "failure", "boundary", "state-transition"] },
+                "id": { "type": "string" },
                 "title": { "type": "string" },
                 "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
                 "reviewRequired": { "type": "boolean" },
@@ -142,7 +143,29 @@
                   "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" } }
+                "assertions": { "type": "array", "items": { "type": "string" } },
+                "routing": {
+                  "type": "object",
+                  "required": ["decision", "reason", "requiredSources", "referenceSources"],
+                  "properties": {
+                    "decision": { "type": "string", "enum": ["required", "recommended", "review-only"] },
+                    "reason": { "type": "string" },
+                    "requiredSources": { "type": "integer", "minimum": 0 },
+                    "referenceSources": { "type": "integer", "minimum": 0 }
+                  }
+                },
+                "automation": {
+                  "type": "object",
+                  "required": ["status", "mappedSteps", "totalSteps", "mappedAssertions", "totalAssertions"],
+                  "properties": {
+                    "status": { "type": "string", "enum": ["compiled", "partial", "not-compiled", "review-only"] },
+                    "mappedSteps": { "type": "integer", "minimum": 0 },
+                    "totalSteps": { "type": "integer", "minimum": 0 },
+                    "mappedAssertions": { "type": "integer", "minimum": 0 },
+                    "totalAssertions": { "type": "integer", "minimum": 0 },
+                    "blocker": { "type": "string" }
+                  }
+                }
               }
             }
           }
@@ -163,6 +186,20 @@
       "type": "string",
       "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."
     },
+    "scenarioCoverage": {
+      "type": "object",
+      "description": "Counts that connect routed QA scenarios to generated automation without claiming execution.",
+      "required": ["required", "recommended", "reviewOnly", "compiled", "partial", "notCompiled", "requiredGaps"],
+      "properties": {
+        "required": { "type": "integer", "minimum": 0 },
+        "recommended": { "type": "integer", "minimum": 0 },
+        "reviewOnly": { "type": "integer", "minimum": 0 },
+        "compiled": { "type": "integer", "minimum": 0 },
+        "partial": { "type": "integer", "minimum": 0 },
+        "notCompiled": { "type": "integer", "minimum": 0 },
+        "requiredGaps": { "type": "integer", "minimum": 0 }
+      }
+    },
     "automation": {
       "type": "object",
       "description": "Optional adapter handoff after a reviewer accepts the QA scenario. It is not required to use the QA judgment.",
@@ -219,6 +256,19 @@
             "items": { "type": "string" },
             "description": "Changed test files to execute instead of generating another draft. Present for test-evidence-only changes."
           },
+          "scenarioAutomation": {
+            "type": "array",
+            "description": "Compact receipts connecting selected scenario ids to generated automation status.",
+            "items": {
+              "type": "object",
+              "required": ["id", "decision", "status"],
+              "properties": {
+                "id": { "type": "string" },
+                "decision": { "type": "string", "enum": ["required", "recommended", "review-only"] },
+                "status": { "type": "string", "enum": ["compiled", "partial", "not-compiled", "review-only"] }
+              }
+            }
+          },
           "evidence": {
             "type": "array",
             "items": { "type": "string" },