@ivorycanvas/qamap 0.4.1 → 0.4.2

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 export declare const TOOL_NAME = "QAMap";
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.4.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const TOOL_NAME = "QAMap";
-export const VERSION = "0.4.1";
+export const VERSION = "0.4.2";
 //# sourceMappingURL=version.js.map

package/docs/architecture.md

@@ -128,4 +128,4 @@ Playwright, Maestro, and other tools are executor implementations. They are not
 5. Add explicit, temporary execution and normalized evidence.
 6. Add manifest accept, reject, and repair commands so reviewed outcomes improve later analysis.
 
-Version `0.4.0` establishes the commit-to-intent-to-scenario slice for synthetic web and mobile lifecycle changes. The next minor is reserved for a policy-controlled scenario execution and normalized evidence slice; compatible analyzer and adapter improvements remain patch releases during `0.x` development.
+Version `0.4.0` establishes the commit-to-intent-to-scenario slice for synthetic web and mobile lifecycle changes. The next minor is unscheduled and reserved for a policy-controlled scenario execution and normalized evidence slice that has been proven across unrelated repositories; compatible analyzer and adapter improvements remain `0.4.x` patch releases until that bar is met.

package/docs/benchmarking.md

@@ -64,6 +64,15 @@ Each target can declare:
 | `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`. 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.
 
@@ -79,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, scenario trace coverage, 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/release-validation.md

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

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.
 

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