supercov 0.0.43 → 0.0.45

package/README.md

@@ -10,8 +10,8 @@ No account, config file, import, custom reporter, or hosted service is required.
 
 Supported by [Supercorp](https://supercorp.ai).
 
-[Try the worked example](https://supercov.com/docs/code-verification): find an
-untested session-expiry condition, run an additional test, and compare the results.
+[Agent workflow](https://supercov.com/docs/agent-loop): ask your coding agent
+to add a test in your own project, with a recorded example to follow along.
 
 ## Start with the suite you already have
 
@@ -46,22 +46,30 @@ npx supercov -- python -m unittest
 npx supercov -- bundle exec rspec
 ```
 
-## Inspect assertion evidence (JS/TS)
+## Map what assertions check
 
-After a run, inspect what existing assertions appear to check:
+Each normal test run creates an assertion map automatically. An agent can
+optionally fill in what the assertions check:
 
 ```sh
-npx supercov runs latest assertions --limit 5
-npx supercov runs latest assertions --pragmas --json
-npx supercov runs latest assertions --evidence /tests --limit 5 --json
+npx supercov runs latest assertions --json
+# Pin the returned run ID. Inspect assertions and the source that ran:
+npx supercov runs <run> assertion <assertion-id>
+npx supercov runs <run> source src/example.ts
+# Edit assertions.json, then validate and acknowledge:
+npx supercov runs <run> assertions validate --json
+# Copy examined expectedBasis tokens into assertions.json; save again.
+npx supercov runs <run> assertions check --require-mappings --require-observed --json
+npx supercov runs <run>  # includes the assertion percentage in the regular report
 ```
 
-This npm-only query uses the run archive and matching source; it adds no new
-test-time instrumentation. It requires a compatible project TypeScript compiler
-API (5.8.3 and native 7.0.2 are tested). Results are candidates, not proof
-that changes are safe or a verified assertion percentage. Follow
-[`assertion-evidence.md`](docs/assertion-evidence.md) for provenance, optional
-assertion hints, pagination, and limitations.
+After code or tests change, run the same test command again. Supercov reuses the
+newest available map for that command and language and identifies dirty flows. Rust owns
+validation, change tracking and reporting; the agent supplies semantic reasoning.
+The score is agent-assessed and separate from MC/DC. See
+[assertion maps](docs/assertion-maps.md) for the format and JS/TS limits, or run
+`supercov docs assertion-agent` for the agent workflow. `supercov assertions schema`
+exports the editor schema; `assertions validate --file <path>` checks JSON syntax.
 
 ## Give Supercov a job
 
@@ -170,7 +178,7 @@ Supercov uses exact per-test attribution where an adapter is available. For othe
 | --- | --- |
 | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
 | Vitest | Exact per test, with setup execution kept separate |
-| Jest | Exact per test, including parameterized tests; `expect` assertions link the evidence they check |
+| Jest | Exact per test, including parameterized tests; exact `expect` occurrence identity for assertion maps |
 | `node:test` | Exact per test |
 | AVA and Mocha | Aggregate structural coverage |
 | Cargo's standard libtest runner | Exact test, attempt, and passing-assertion identity |
@@ -223,6 +231,7 @@ npx supercov clean             # remove all runs and the build cache
 
 - [Getting started](https://supercov.com/docs/getting-started)
 - [Agent workflow](https://supercov.com/docs/agent-loop)
+- [Understanding assertions](docs/assertions.md)
 - [Troubleshooting](https://supercov.com/docs/troubleshooting)
 - [CLI reference](https://supercov.com/docs/cli)
 - [Supported languages and test suites](https://supercov.com/docs/supported-suites)

package/docs/agent-loop.md

@@ -1,41 +1,33 @@
 # Agent workflow
 
-Supercov works best as a small, repeatable loop: run the suite, choose one useful
-gap, write one test, rerun, and prove what improved.
+Use Supercov with your coding agent and the test suite you already have.
+Supercov reports coverage and gaps. Your agent writes a test, reruns the suite,
+and checks what improved.
 
-```text
-run the suite  →  choose a gap  →  write one test  →  rerun  →  compare
-      ↑                                                            |
-      └────────────────────────────────────────────────────────────┘
-```
-
-Supercov supplies the coverage signal and evidence. Your coding agent writes
-the tests.
+## Start with one test
 
-## Choose the job
+Open your own repository in your coding agent and paste this prompt. You don't
+need to install Supercov first; the agent can handle that.
 
-For one careful first pass, ask:
-
-```text
-Measure code coverage with `npx supercov` and write the first useful test based
-on coverage. Only edit tests. Rerun the complete suite and report what improved.
+```text supercov-prompt
+Measure code coverage with npx supercov and write one missing test.
+Only change tests. Rerun the full test suite and show me the test you
+added and the before-and-after coverage.
 ```
 
-For an overnight run or leftover token budget, ask:
+If the project has several test commands, tell the agent which full suite to
+use. Let it run the commands and edit the tests, approving those actions if
+your agent asks.
 
-```text
-Use `npx supercov` to improve coverage. Only write tests. Keep going while
-useful gaps remain. Never weaken assertions or change application code to make
-coverage easier. Stop at a measurement limit, unreachable behavior, or the end
-of the available time budget. Report the run ids compared and what improved.
-```
-
-The second prompt is intentionally open-ended, but 100% is a direction rather
-than permission to write meaningless tests or reshape application code.
+The result is a normal test-file change and a coverage comparison in the
+conversation. Ask separately if you want a commit or pull request.
 
 ## One safe pass
 
-```sh
+The agent should run the suite, inspect a gap, write a test, then rerun the
+same suite and compare. These are the commands it can use:
+
+```sh supercov-example
 # 1. Establish a baseline.
 npx supercov -- npm test
 
@@ -52,29 +44,126 @@ npx supercov -- npm test
 npx supercov diff <previous-run-id> latest
 ```
 
-For Rust, use `cargo test` or `cargo nextest run` in both runs. Keep the baseline
-and verification commands identical.
+Everything after `--` is your project's test command. Use your actual command
+and file paths in place of the examples. For example,
+Rust projects can use `cargo test`, Python projects `pytest`, and Ruby projects
+`bundle exec rspec`. Keep the baseline and verification commands identical.
 
 The `line` query is useful before writing a test because it shows which tests
 already reach that line. Extending a nearby test is often better than adding a
 duplicate.
 
-For supported JS/TS projects, inspect assertion evidence before adding tests:
+Every new test run creates `assertions.json`. To investigate what tests assert:
 
 ```sh
-npx supercov runs latest assertions --file app/checkout/session.ts --limit 5 --json
-npx supercov runs latest assertions --pragmas --json
+npx supercov runs latest assertions --json
+# Pin data.run and edit the file at data.map.
 ```
 
-This post-run query needs the matching source and a compatible
-project TypeScript API. An `evident` candidate is not a proof of safety; keep
-test gaps separate from analysis limits. Follow the returned evidence pointers
-and `pagination.nextOffset`, pinning `--analysis` and the run id while paging.
-See [assertion evidence](assertion-evidence.md) for requirements and examples.
+Inspect an entry with `runs <run> assertion <id>` and read archived code with
+`runs <run> source <path>`. Edit its `assertions.json`, declare credited nodes
+and broader watch inputs, then obtain expectedBasis tokens with `assertions validate --json` and save the examined tokens in the map or repeated `--flow ASSERTION/FLOW`. After the next run of
+the same command, its map automatically inherits prior work; repair affected entries. Supercov
+validates references and freshness, while the agent owns semantic meaning.
+Run `supercov docs assertion-agent` for the full mapping instructions. Validate
+with `runs <run> assertions validate`, save examined expectedBasis tokens in the map, then use
+`runs <run> assertions check --require-mappings --require-observed` as the
+completion gate. See [assertion maps](assertion-maps.md) for the contract and JS/TS limits.
+
+## Example
+
+Here's a recorded Codex run in a JavaScript project, using the first prompt.
+The files are from our checkout example; you don't need to add them to your
+project.
+
+[`src/session.js`](https://github.com/supercorp-ai/supercov/blob/main/examples/checkout-verification/starter/src/session.js)
+allows checkout only when the customer is signed in and their session has
+not expired:
+
+```js
+export function canCheckout(signedIn, expired) {
+  if (signedIn && !expired) return true;
+  return false;
+}
+```
 
-## A complete prompt for longer runs
+The two tests in
+[`tests/session.test.js`](https://github.com/supercorp-ai/supercov/blob/main/examples/checkout-verification/starter/tests/session.test.js)
+check a valid session and a signed-out visitor:
+
+```js
+assert.equal(canCheckout(true, false), true);
+assert.equal(canCheckout(false, false), false);
+```
+
+The agent ran `npx supercov -- npm test`. Both tests passed, and the summary
+from `npx supercov runs latest` showed:
 
 ```text
+Coverage
+  Lines      100.00% (3/3)
+  Branches   100.00% (2/2)
+  MC/DC      50.00% (1/2)
+```
+
+It listed the gaps and inspected the file. You can open those views with:
+
+```sh
+npx supercov runs latest gaps
+npx supercov runs latest file src/session.js
+```
+
+The file query explained the gap:
+
+```text
+ LINE  STATUS        SOURCE
+    2  PARTIAL       signedIn && !expired
+       Unobserved: no witness pair shows `!expired` independently changing the decision result
+```
+
+Both return paths had run, but neither test checked an expired session. MC/DC
+checks whether each condition has been shown to affect the decision
+independently. Here, `signedIn` had; `!expired` had not.
+
+The agent added one test to `tests/session.test.js`, leaving the application
+code and existing tests unchanged:
+
+```js
+test('a signed-in visitor with an expired session cannot check out', () => {
+  assert.equal(canCheckout(true, true), false);
+});
+```
+
+It reran the same full suite. All three tests passed, and MC/DC reached 100%.
+The comparison from `npx supercov diff <before-run-id> latest` showed:
+
+```text
+lines +0pp, branches +0pp, MC/DC +50pp
+gained: 0 lines, 0 branches, 1 MC/DC conditions
+lost: 0 lines, 0 branches, 0 MC/DC conditions
++ MC/DC src/session.js:2 C2 !expired
+```
+
+The new assertion checks that checkout is denied when a signed-in customer's
+session has expired. Removing the expiry check makes this test fail; the
+original two tests still pass.
+
+In your project, look for the same evidence: the test checks the behavior the
+agent identified, and the full suite passes. One useful test won't necessarily
+take coverage to 100%.
+
+To try these exact files, [download the starter](https://supercov.com/downloads/supercov-tutorial.zip),
+extract it, open the `supercov-tutorial` folder in your agent, and run `npm ci`.
+Then use the JavaScript prompt above. The completed test is not included in the
+download. The [recorded run](https://github.com/supercorp-ai/supercov/tree/main/examples/checkout-verification/agent-run)
+includes the commands, full output, and completed test.
+
+## A complete prompt for longer runs
+
+Once you've reviewed the first test, use this prompt to continue through
+useful gaps—for example, during an overnight run:
+
+```text supercov-prompt
 Use `npx supercov` to improve coverage. Only write tests. Keep going while
 useful gaps remain.
 
@@ -110,7 +199,7 @@ reason to manufacture a test.
 
 If the repository separates test levels, narrow the view:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --kind e2e --limit 10
 ```
 

package/docs/assertion-agent.md

@@ -0,0 +1,156 @@
+# Agent workflow for assertion maps
+
+You are the semantic author. Supercov supplies source identities, execution
+records, file hashes and a JSON validator. It does not infer or prove your
+explanations. Use your ordinary source-reading tools and edit one run-owned
+`assertions.json`; no model is embedded in Supercov.
+
+## Start with a real run
+
+1. Run the intended suite through `supercov -- <test command>` if no matching
+   current run exists. Use the full suite for a suite-wide result.
+2. Read `supercov runs --json`, pin its concrete run ID, then read
+   `supercov runs <run> assertions --json`. Edit `data.map`; the run creates it
+   automatically and inherits compatible prior work. Check `data.inheritance`
+   for fallback errors. Keep old runs and their maps.
+3. Read `supercov docs assertion-maps`. Page the assertion, statement, test and
+   change views. Do not mistake one page for the whole suite:
+
+   ```sh
+   supercov runs <run> assertions --limit 100 --json
+   supercov runs <run> assertions report --view statements --limit 100 --json
+   supercov runs <run> assertions report --view tests --limit 100 --json
+   supercov runs <run> assertions report --view changes --limit 100 --json
+   ```
+
+Follow `pagination.nextOffset` with `--offset`; restart if `revision` changes.
+Use a single map writer. Save edits atomically where your editor supports it.
+The outer object contains `schemaVersion: 2` and `assertions`; do not insert run IDs.
+
+## Investigate precise claims
+
+Read current test setup, inputs, mocks, callbacks, branches, callees, helper
+modules and relevant configuration. Current files must match the pinned run.
+Supercov retains hashes and identities, not a source checkout. Optional
+`runs <run> source <path> --offset 0 --limit 100` prints matching code with line
+numbers; `assertions files` lists input hashes even when files no longer match.
+
+Use `runs <run> assertion <id>` for the exact site and graph. Preserve its ID and
+full `at` anchor, usually the complete assertion call without a trailing semicolon.
+Use one-based UTF-8 byte columns, not character counts. An `inMap: false` site
+was recognized but is missing from the map; restore it when investigating.
+
+For each assertion:
+
+- Describe exactly what its predicate distinguishes in `observes`. Truthiness,
+  existence, length or substring checks do not imply equality of every field.
+- Write independently maintainable flows with stable IDs, `basis: null`, a
+  concrete explanation, exact nodes and authored edges to `$assertion`.
+- Use explicit `appliesTo: [{file, name}]` from the test view. File and name
+  must resolve unambiguously. Empty means no credit. Runtime IDs never belong
+  in selectors. Shared/parameterized sites may need multiple cases or flows.
+- Take production statement anchors from the `statements` view when possible.
+  Put only nodes you judge asserted in `countsAsAsserted`. Each counted node
+  needs an authored path to `$assertion`; a block does not credit nested code.
+- Put additional dependency paths in `watch`, as whole-file strings. Assertion,
+  selected-test and node files are already dependencies. Include setup, guards,
+  alternate paths and helpers your explanation relies on, even without nodes.
+- Preserve uncertainty in `questions`. Flow questions block that flow's credit.
+  Assertion questions record unfinished exploration without implying a known
+  total. There is no `analysis`, `mapped`, or `complete` flag.
+- A fixture-only or absence explanation can have `countsAsAsserted: []`. Explain
+  the absence, including ordering/barriers and the observation window. Never
+  credit an unexecuted body just because its execution would violate a check.
+
+Inspect `selectors`, `blockers`, `reasons`, empty `observedPassingTests`, and
+statement `at: null` entries. They may represent skipped tests, unsupported
+syntax, ambiguous test names or missing evidence. Do not borrow another site's
+identity, fabricate events, delete inconvenient entries or edit managed state.
+Zero-credit explanations are useful; invented credit is not.
+
+## Account for changes before finalizing flow tokens
+
+When inheriting a map, inspect **every** item in `--view changes`, including files
+already watched by some flows. Dependencies may be missing. In root
+`changeAssessments`, write one response per managed change ID:
+
+```json
+{
+  "id": "c_copy_from_changes_view",
+  "basis": null,
+  "affectedFlows": ["assertion-id/flow-id"],
+  "explanation": "What changed, which claims it affects, and why other existing claims remain valid."
+}
+```
+
+Include all known dependent flows still present, plus any others affected.
+Repair watches if the change reveals a missing dependency. An empty list needs
+an actual explanation. Removing a response does not clear the outstanding change.
+A changed test/assertion can affect all its flows; a production file used by one
+sibling may affect only that flow. No machine can tell you an expected flow total.
+
+Save the responses and graph edits. Run:
+
+```sh
+supercov assertions validate --file <map-path> --json
+supercov runs <run> assertions validate --json
+```
+
+For large maps, page `validate --view changes`, `validate --view flows`, or
+`validate --view errors` with `--offset` and `--limit`; tokens appear under
+`items` and overall validity still covers the whole map. Pin `revision` across pages.
+
+Validation checks shape, IDs, graph links, anchors and state binding. It returns
+`changes[].expectedBasis` and `flows[].expectedBasis`; null/stale tokens alone
+are unfinished work, not syntax errors. Copy change tokens **only after inspecting
+those impact assessments**, then save. Validate again and copy flow tokens only
+for claims you have examined. Save the map again. Change acknowledgements can
+invalidate additional flows, so obtain final flow tokens after change tokens.
+Changing a graph, selector, observation or watch after obtaining its token makes
+that token stale. Do not implement the hashing algorithm or manufacture tokens.
+
+There is no `review` command. All commands are read-only; acknowledgement is your
+explicit file edit. Passing reference validation does not prove your reasoning.
+
+## Check and report
+
+```sh
+supercov runs <run> assertions check --require-mappings --require-observed --json
+supercov runs <run> assertions report --view statements --limit 100 --json
+supercov runs <run>
+```
+
+Basic `check` permits untouched sites without flows, but fails on invalid or
+unfinished authored claims, open questions and outstanding change impact.
+`--require-mappings` requires at least one current observed explanation for every
+recognized passing site, including legitimate zero-credit explanations.
+`--require-observed` checks every site and selector. Neither means every semantic
+flow was found. Use `--min <percentage>` only for the project's chosen target.
+Do not lower a target or hide unknowns to make a check pass.
+
+The normal report includes the percentage immediately from the edited file.
+`notAssessed`, `pending`, `unavailable` and `notApplicable` have null percentages,
+not fabricated zeroes. A numeric partial-map result still reports counts of
+assertions without flows and claims needing work. Describe the score as
+agent-assessed statements; successful same-test coexecution is evidence, not
+proof of causality or mutation resistance.
+
+## Continue after edits
+
+Run the same suite command again. The new run carries IDs, explanations and
+unchanged acknowledgements using prior file hashes, without needing old source.
+Use `assertions --needs-attention` and the change view. Repair only affected
+claims; keep current siblings. Any dependency byte edit, including comments,
+requires rechecking. Unique relocation preserves identity as a suggestion;
+ambiguous/removed sites remain in `retiredAssertions`. Old v1 flows are imported
+as drafts with questions about selectors and graph paths; inspect them explicitly.
+
+Do not edit `assertions.state.json`. Dirty generations persist across reruns and
+reverts until current tokens are recorded. Resolved change responses are folded
+and retired on the next publication. Runtime evidence never carries forward.
+If source differs from the pinned run, rerun tests before continuing.
+
+Finish with the pinned run ID, status, numeric percentage/counts when available,
+assertions without flows, remaining questions/stale or unobserved claims, and
+verification commands used. Explain remaining limits. The property in `observes`
+matters: changing a credited line while preserving that property can still pass.

package/docs/assertion-evidence.md

@@ -1,135 +1,9 @@
-# Assertion evidence (JS/TS)
-
-Supercov can analyze which source behaviors existing assertions appear to check,
-using an ordinary run archive, its matching source, and the existing statement
-and assertion-phase evidence. This work happens after tests. It adds no new
-test-time probes, does not run mutants, and does not rewrite your tests.
-
-This is candidate evidence, not a proof that arbitrary changes are safe.
-`assertionScore` remains null. Execution-only links, test gaps and analysis limits
-are different things; do not interpret a passing assertion nearby as protection.
-
-## Requirements
-
-Use the **npm Supercov launcher**, which supplies the installed analyzer assets.
-The current JS/TS adapter is exercised with Node's test runner and Vitest.
-Browser, background, merged, retried and ambiguously attributed records have
-explicit limitations; other language assertion analyzers are not enabled here.
-
-The analyzed project must provide a TypeScript compiler API, **even for a
-JavaScript project**. For example, add TypeScript as a development dependency
-before recording the run. The analyzer uses that project's compiler, not a
-silently substituted global or bundled version. Installing it afterward changes
-the dependency fingerprint, so rerun the suite. Missing/incompatible compiler APIs
-produce an error. **TypeScript 5.8.3 and native 7.0.2 are tested.** Version 7.0.2
-uses its own native parser/checker, not a fallback to TypeScript 5. Install its
-platform-specific optional dependency too; the report hashes both the JS client
-and the native compiler package, including its standard libraries. This backend
-requires Node 22.12 or newer (Node 24 tested), and uses original-source evidence
-from ordinary Supercov archives, not legacy ts-node/V8 generated-line coverage.
-Native module resolution currently follows actual import/export references;
-unresolved helper-only specifiers remain visible as compiler limitations.
-Other native compiler versions are not enabled until separately calibrated.
-Do not downgrade an application's compiler just to improve an assertion report.
-
-Compiler compatibility and regression checks do not prove general correctness.
-All candidates remain unverified and `assertionScore` remains null. Query-side
-native compiler work adds no test-time instrumentation.
-
-Standalone native/Python/Ruby distributions do not currently bundle this JS/TS
-analyzer. Use the npm launcher, or explicitly set `SUPERCOV_PACKAGE_ROOT` to an
-installed npm package directory. Normal coverage commands are unaffected.
-
-## Run, inspect, follow evidence
-
-`assertions` analyzes source behaviors and their assertion evidence; it does not
-just count or list assertion calls. Use `npx supercov docs assertion-evidence`
-to read this guide from the installed package.
-
-```sh
-npx supercov -- npm test
-npx supercov runs latest assertions --limit 5
-npx supercov runs latest assertions --file src/core.ts --json
-npx supercov runs latest assertions --site '<site-id>' --json
-```
-
-The summary reports candidate counts and the site denominator, without claiming
-a verified assertion percentage. Each ordinary site row contains its source,
-candidate classification, available facts, and an `evidence.pointer` for full
-details. Global tests, attempts, execution links, diagnostics and source-scope
-limits are referenced under `evidence`, not repeated inside every site page.
-
-```sh
-npx supercov runs latest assertions --evidence /tests --limit 5 --json
-npx supercov runs latest assertions --evidence /diagnostics --json
-npx supercov runs latest assertions --evidence /sites/0/facts --json
-```
-
-Pointers use JSON Pointer syntax: escape `/` in a property name as `~1` and `~`
-as `~0`. Use an empty pointer (`--evidence ''`) for the document root. Follow
-returned pointers rather than constructing indices from filtered page offsets:
-site pointers index the complete, stable inventory.
-
-## Pagination and oversized records
-
-All JSON responses stay within the normal response budget. Pages may contain
-fewer than `--limit` results: **follow `pagination.nextOffset`**, not offset plus
-the requested limit. `hasMore: false` marks the end.
-
-An oversized site/hint is returned as `detailOnly: true` with an
-`evidence.pointer`. Nothing has been discarded. An evidence page returns immediate
-object members or array entries as `items`. Small entries contain `value`; large
-ones contain `detailOnly: true` and another `pointer` to inspect. String leaves
-return `text` chunks, with offsets/counts measured in Unicode scalar values,
-not bytes. This allows reading one large observation or diagnostic completely.
-
-```sh
-npx supercov runs '<run-id>' assertions --evidence '<returned-pointer>' \
-  --offset 0 --limit 4000 --analysis '<analysisId>' --json
-```
-
-Every page carries an `analysisId` hashing the complete derived document and its
-provenance. Pass the first page's id as `--analysis` on follow-ups to reject mixed
-analyses if the compiler, analyzer, or derived results change. Use a fixed run id
-instead of `latest` while paging. Source/run freshness checks still run on every
-query. Derived results are not cached or written into the archive.
-
-JSON reports use `reportSchema: 2`. Shared evidence is accessed through the
-evidence pointers above.
-Success and error JSON envelopes identify this query as `coverage.assertions`.
-
-## Optional assertion hints
-
-```ts
-// observes: src/core.ts#compute return value
-assert.equal(compute(), 4);
-```
-
-The comment must precede a statement containing exactly one recognized assertion.
-The project-relative file, exact function/owner name, and optional literal source
-substring must select one inventory site. Optional `via ...` is explanation only.
-
-```sh
-npx supercov runs latest assertions --pragmas --json
-```
-
-Origin is `user-suggested`; validation is separately `analyzer-supported`,
-`unresolved`, or `invalid`. Support requires the named assertion's exact passing
-witness and a connection supported by the ordinary effect rules. Strength remains
-presence/value/total; presence does not mean value protection. Unsupported
-decision, absence and internal-state paths remain unresolved. A missing inventory
-match may reflect unsupported source rather than a bad declaration.
-
-Hints cannot inject observations, borrow another assertion's evidence, inflate
-coverage or remove sites from the denominator. Editing comments changes test
-source and requires a new run. Supported hints retain the analyzer's limitations;
-they are not formal proofs.
-
-## Agent workflow
-
-Read coverage first, then inspect assertion candidates and their evidence before
-writing another test. An execution gap may need a reachable scenario; an assertion
-gap may need a stronger check. An analysis limit needs investigation—not a test
-written just to satisfy the analyzer. Keep the original denominator and unresolved
-work visible. Never automatically treat an `evident` candidate as permission to
-change application behavior.
+# Assertion evidence
+
+The earlier automatic JS/TS analyzer has been replaced by agent-authored
+assertion maps. Use [Understanding assertion coverage](assertions.md) to get
+started, [Agent-authored assertion maps](assertion-maps.md) for the file format
+and CLI reference, and [the agent instructions](assertion-agent.md) to build or
+update a map. Existing structural runs remain readable; mapping requires a new
+run with an assertion input manifest. Old `--pragmas`, `--analysis` and `--evidence`
+options do not apply to the map workflow.