docs/releases/0.5.0.md

# QAMap 0.5.0

Reusable repository evidence and an opt-in report-review workflow. QAMap stays
local and makes no model calls. An agent invoking it and interpreting its output
still consumes tokens.

## Changes

- Reuse supported JS/TS syntax evidence and trace declared cross-package links.
- Save private local reports with `qa report`; add `--handoff` for source and test evidence.
- Preserve declaration, import, consumer and assertion context, including deletion
  boundaries, distant expectations and supported literal policy-module choices.
- Retain large-change overflow in a checked archive. Factor repeated text without
  losing rows, source locations or explicit uncertainty when complete evidence fits inline.
- Save an explicit project choice with `init --agent --review-mode report`;
  use `--review-mode ask` to restore consent prompts. Installation alone is not consent.
- Keep tests `not-run`, missing evidence unknown, and execution separately authorized.

## Compatibility

Existing `qa`, `qa run`, agent-format and receipt-only output remain available.
The `qamap.qa` v1 summary keeps its 4,096-byte limit. The separate
`qamap.qa.handoff` v1 envelope permits 16,384-byte previews or up to 32,768 bytes
for complete lossless inline evidence. Checked reader pages stay at 16,384 bytes.
Consumers must not apply the summary limit to the full handoff.

The packaged skill requires the matching CLI version; do not pair it with 0.4.17.
No manifest migration is required. Existing agent instructions change only when
setup is explicitly rerun; user-authored guidance and saved preferences are preserved.

## Measured Results

| Synthetic case | Standalone total tokens | Report-review total tokens |
| --- | ---: | ---: |
| Literal runtime policy | 46,301 | 41,300 |
| 160 repeated-structure changes | 84,518 | 30,563 |
| Forty distinct direct contracts | 79,571 | 48,180 |
| Forty cross-package contracts, including first consent | 86,521 | 62,922 |

Each comparison retained its predefined findings and required evidence. These
are separate protocols on known synthetic cases, using one model and author
review, not blinded external validation. The two mixed architectures share the
same contracts. Do not pool them into a universal savings or quality score.

Earlier truncated, 401,557-token and 100,730-token failures remain in the
[full validation record](../release-validation.md). Total-token reductions do
not establish lower monetary cost; some uncached-input counts increased.

The final feature candidate passed 763 tests, 44 static contracts, 11 repository
checks, 10 context checks and 3 execution contracts. Coverage was 92.03% lines,
89.23% branches and 96.21% functions. Package installation, explicit preference
and revocation, existing guidance preservation and corrupted-report rejection
also passed. Final version and publication receipts belong to the release checks.

## Remaining Limits

- Reports do not include the previous implementation's source context. A current
  test disagreement alone does not prove when a regression was introduced.
- Unknown runtime choices, unlinked consumers and syntax or retention limits stay unknown.
- Reports that cannot fit inline still need checked archive reads; their caller
  efficiency has not been demonstrated for every shape of PR.
- QAMap scenarios are review drafts, not executed tests or a bug-free guarantee.
- Host instruction discovery and behavior vary; a skill file cannot enforce every agent's actions.

## Publication

Follow the [release runbook](../releasing.md): synchronize version pins, pass the
clean-checkout local gate and exact-head CI, merge, publish npm, verify that exact
registry installation, then prepare the matching plugin bundle. Results are
recorded in [PR #287](https://github.com/IvoryCanvas/QAMap/pull/287) and
[GitHub Releases](https://github.com/IvoryCanvas/QAMap/releases).

npm publication does not update the OpenAI or Claude plugin listing. Each
directory version requires its own publication process; preparing a ZIP is not approval.