assertledger 1.0.0

package/docs/reference.md

@@ -0,0 +1,336 @@
+# CLI, SDK and MCP reference
+
+[Back to the introduction](../README.md) · [Introduction en français](../README.fr.md)
+
+## JSON CLI
+
+This reference uses the installed or locally linked `assertledger` command. When working from
+the source branch, build first and replace `assertledger` with `node dist/cli.js`.
+
+For a first run, use `assertledger doctor .` and the [Git qualification guide](git-regression.md).
+`assertledger connect . --client codex` prints a read-only MCP configuration; see
+[developer entry points](developer-experience.md) for creation, conflicts and trust requirements.
+
+```sh
+assertledger init . --dry-run --json
+assertledger init . --json
+assertledger audit . --json
+assertledger analyze . --json
+assertledger schema verification-request --json
+assertledger verify assertledger.request.json --allow-unsafe-execution --json
+assertledger replay assertledger.manifest.json --json
+assertledger profile assertledger.profile-request.json --json
+assertledger profile-replay assertledger.profile-report.json --json
+assertledger profile-v2 assertledger.profile-v2-request.json --json
+assertledger profile-v2-replay assertledger.profile-v2-report.json --json
+assertledger benchmark assertledger.benchmark-request.json --json
+assertledger benchmark-replay assertledger.benchmark-artifact.json --json
+assertledger benchmark-acquire assertledger.benchmark-acquisition-request.json --allow-unsafe-execution --json
+assertledger benchmark-acquire-replay assertledger.benchmark-acquisition-result.json --json
+assertledger mcp
+# Operator-only opt-in: assertledger mcp --allow-unsafe-execution
+```
+
+Every command above also runs identically under the legacy `testforge` binary name.
+
+`init` is static: it never executes detected commands or adapters and manages only
+`assertledger.config.json` and `assertledger.lock.json`. It requires operator-owned worlds and
+candidates rather than inventing a verification request. See
+[`docs/repository-init.md`](repository-init.md) for detection conflicts, recovery behavior,
+adapter availability, and the trust boundary.
+
+Repository analysis reports a test framework only from framework-specific evidence such as a
+declared dependency, a dedicated configuration file, or a real `node:test` import below a test
+directory or in a colocated `*.test.*`/`*.spec.*` source file. Comments, string examples, and
+documentation-like config filenames do not count; no evidence produces an empty list. Detection is
+intentionally incomplete: an unrecognized manifest layout or test-file convention yields no claim.
+
+`verify`, `replay`, `profile`, `profile-replay`, `profile-v2`, `profile-v2-replay`, `benchmark`, and
+`benchmark-replay`, `benchmark-acquire`, and `benchmark-acquire-replay` also accept `-`
+or an omitted file argument and
+then read JSON from stdin. The CLI rejects file and stdin JSON inputs larger than 16 MiB. JSON
+results go to stdout. Diagnostics go to stderr. `assertledger mcp` reserves stdout for JSON-RPC.
+
+`--allow-unsafe-execution` is an external authorization signal. The CLI requires it for every
+campaign and sets the request's local acknowledgement before validation. The flag does not create a
+sandbox.
+
+Versioned JSON Schemas are published for the
+[`verification request`](../schemas/verification-request.v1.json),
+[`repository analysis`](../schemas/repository-analysis.v1.json),
+[`repository init config`](../schemas/repository-init-config.v1.json),
+[`repository init lock`](../schemas/repository-init-lock.v1.json),
+[`repository init result`](../schemas/repository-init-result.v1.json),
+[`evidence manifest`](../schemas/evidence-manifest.v1.json),
+[`replay result`](../schemas/replay-result.v1.json),
+[`Agentic Test Profile request`](../schemas/agentic-profile-request.v1.json),
+[`Agentic Test Profile report`](../schemas/agentic-profile-report.v1.json),
+[`Agentic Test Profile replay result`](../schemas/agentic-profile-replay-result.v1.json),
+[`Agentic Benchmark request`](../schemas/agentic-benchmark-request.v1.json),
+[`Agentic Benchmark artifact`](../schemas/agentic-benchmark-artifact.v1.json), and
+[`Agentic Benchmark replay result`](../schemas/agentic-benchmark-replay-result.v1.json),
+[`Agentic Benchmark acquisition request`](../schemas/agentic-benchmark-acquisition-request.v1.json),
+[`Agentic Benchmark acquisition result`](../schemas/agentic-benchmark-acquisition-result.v1.json),
+[`Agentic Benchmark acquisition replay result`](../schemas/agentic-benchmark-acquisition-replay-result.v1.json),
+[`Agentic Test Profile v2 request`](../schemas/agentic-profile-request.v2.json),
+[`Agentic Test Profile v2 report`](../schemas/agentic-profile-report.v2.json), and
+[`Agentic Test Profile v2 replay result`](../schemas/agentic-profile-replay-result.v2.json), plus the
+[`corpus trust policy`](../schemas/agentic-corpus-trust-policy.v1.json) and paired
+[`corpus provenance`](../schemas/agentic-corpus-provenance.v1.json), six corpus allocation and
+two-party [`commitment/reveal`](../schemas/agentic-corpus-allocation-commitment.v1.json) contracts,
+plus six pre-declared [`H3 experiment`](../schemas/agentic-corpus-experiment-plan.v1.json) contracts.
+The main CLI `schema` command prints the thirty-one facade schemas by name; the corpus evaluator consumes
+the two trust/provenance schemas directly.
+A complete runnable verification request
+is available at
+[`examples/node-test/request.json`](../examples/node-test/request.json).
+After building the package, the
+[`Agentic Test Profile example`](../examples/agentic-profile/profile-manifest.mjs) derives a report
+directly from any replay-valid manifest. The first two real-campaign results and their limitations
+are recorded in [`docs/agentic-test-profile-pilot.md`](agentic-test-profile-pilot.md).
+The [`Agentic Benchmark example`](../examples/agentic-benchmark/benchmark-request.mjs) consumes a
+strict benchmark request. See [`docs/agentic-benchmark.md`](agentic-benchmark.md) for the fixed
+protocol, comparison scope, replay rails, and current acquisition limitation.
+The benchmark-backed [`Agentic Test Profile v2`](agentic-test-profile-v2.md) replaces v1's
+campaign wall-time proxy with an exact scoped warm-total-wall p95 cost basis. It is additive: v1
+artifacts and commands remain supported.
+
+The checked-in [`conformance v1 bundle`](conformance-v1.md) locks autonomous inputs, complete
+expected outputs, negative replay witnesses, all published schema bytes, and selected public
+digests. `pnpm check` validates this static oracle without regenerating it.
+
+## TypeScript SDK
+
+```ts
+import { readFile } from "node:fs/promises";
+import { AssertLedger } from "assertledger";
+
+const assertLedger = new AssertLedger();
+const initialized = await assertLedger.init("/absolute/path/to/repository", { dryRun: true });
+const context = await assertLedger.analyze("/absolute/path/to/repository");
+const request = JSON.parse(await readFile("assertledger.request.json", "utf8"));
+const manifest = await assertLedger.verify(request);
+const integrity = assertLedger.replay(manifest);
+
+const profile = assertLedger.profile({
+  schemaVersion: "1.0.0",
+  manifest,
+  policy: {
+    profileVersion: "1.0.0",
+    profileId: "my-repository/default",
+    mode: "HARDENING",
+    minimumTimingSamples: 3,
+    lanes: [
+      { id: "instant", maximumReferenceP95Ms: 2_000 },
+      { id: "loop", maximumReferenceP95Ms: 10_000 },
+    ],
+  },
+});
+const profileIntegrity = assertLedger.replayProfile(profile);
+
+const benchmarkRequest = JSON.parse(await readFile("assertledger.benchmark-request.json", "utf8"));
+const benchmark = assertLedger.benchmark(benchmarkRequest);
+const benchmarkIntegrity = assertLedger.replayBenchmark(benchmark);
+
+const profileV2 = assertLedger.profileV2({
+  schemaVersion: "2.0.0",
+  benchmarkArtifact: benchmark,
+  policy: {
+    profileVersion: "2.0.0",
+    profileId: "my-repository/hardening-v2",
+    mode: "HARDENING",
+    requiredComparisonScopeDigest: benchmark.comparisonScopeDigest,
+    costBasis: {
+      regime: "WARM",
+      measure: "WALL",
+      aggregation: "TOTAL",
+      statistic: "P95",
+      unit: "MICROSECOND",
+      portfolioAggregation: "SUM_OF_INDIVIDUAL_P95",
+    },
+    lanes: [{ id: "loop", maximumWarmTotalWallP95Us: 10_000_000 }],
+  },
+});
+const profileV2Integrity = assertLedger.replayProfileV2(profileV2);
+```
+
+`AssertLedger` is exported alongside a deprecated `TestForge` subclass alias with an identical
+surface, for consumers migrating from the prior name.
+
+The SDK accepts plain JSON-compatible values and validates them against the same contracts as the
+CLI. Unlike the CLI and MCP tool, `AssertLedger.verify()` has no separate authorization parameter: the
+caller must set `isolation.acknowledgedUnsafeExecution` to `true` after applying its own policy.
+
+`AssertLedger.replay()` reports schema validity, both digest checks, and deterministic
+decision-semantic validity. Its aggregate `valid` field is true only when all four checks pass. Replay
+does not rerun the campaign, authenticate the producer, or establish that the observations were
+truthful.
+
+`AssertLedger.profile()` accepts only a replay-valid manifest. It qualifies selected `ELIGIBLE`
+hardening candidates against repository-scoped latency lanes and publishes evidence strength,
+observed consistency, nearest-rank p50/p95, marginal target weight, and Pareto status. Latency never
+compensates for a failed evidence gate. For each declared lane, the report also selects an
+explainable greedy portfolio that maximizes new target weight per unit of recorded reference p95
+within the lane's total budget. See
+[`docs/agentic-test-profile.md`](agentic-test-profile.md) for the contract and its non-claims.
+
+`AssertLedger.benchmark()` accepts only a replay-valid `VERIFIED` source manifest plus a complete,
+fingerprinted cold/warm run plan. It summarizes declared microsecond phase timings and never changes
+the source decision. `await assertLedger.acquireBenchmark()` runs the fresh campaign and strict
+framework-neutral phase acquisition directly. The built-in `node:test` adapter remains unsupported
+because it cannot faithfully expose all four phase boundaries.
+`AssertLedger.replayBenchmarkAcquisition()` independently checks the source, artifact, context, result
+digest, and exact status/reason semantics.
+
+H3 replay requires three externally pinned digests and separate SDK options for the trust policy,
+two-party commitment/reveal, allocation, pre-declared plan, subject provenance and evidence bytes.
+Allocation is source-stratified; arms use content-addressed candidate references and derived suite
+digests. Replay resolves and re-hashes every candidate's supplied bytes; this proves byte identity,
+not that those bytes were executed. Scheduled process counts and planned timeout ceilings must be
+exactly equal. H3
+non-inferiority must hold per source and in aggregate. Receipts attest the applied timeout limit but
+do not independently prove enforcement or equal observed CPU/wall time.
+The CLI exposes the same boundary through mandatory `--trust-policy-digest`,
+`--allocation-commitment-digest`, and `--experiment-plan-digest` flags plus separate files. See
+[`docs/agentic-corpus-experiment-h3.md`](agentic-corpus-experiment-h3.md).
+
+`AssertLedger.profileV2()` accepts only a replay-valid benchmark artifact. Its comparison scope must
+match the policy, all warm measurements must be usable, and every cost is the declared warm total
+wall p95 in microseconds. It publishes a Pareto frontier and deterministic greedy portfolios only
+over source-selected eligible candidates. The portfolio cost is a sum of individual p95 values,
+not a measured portfolio p95 and not a universal optimum.
+
+## Calibration corpus
+
+The versioned scaffold under [`benchmarks/agentic-profile`](../benchmarks/agentic-profile) evaluates
+the falsifiable H1-H4 hypotheses without an LLM judge. It remains `NOT_READY` until at least 20
+strict cases from three sources cover every hypothesis and include physically separate public and
+private splits.
+
+```sh
+tsx scripts/evaluate-agentic-profile-corpus.ts status benchmarks/agentic-profile \
+  --trust-policy operator-policy.json --trust-policy-digest sha256:...
+tsx scripts/evaluate-agentic-profile-corpus.ts evaluate-public benchmarks/agentic-profile \
+  --trust-policy operator-policy.json --trust-policy-digest sha256:...
+tsx scripts/evaluate-agentic-profile-corpus.ts evaluate-holdout benchmarks/agentic-profile \
+  --trust-policy operator-policy.json --trust-policy-digest sha256:...
+```
+
+Public evaluation returns per-case reason codes. Holdout evaluation returns aggregate hypothesis
+counts only and suppresses case identifiers, source identifiers, raw values, and readiness counts.
+The repository intentionally contains no fabricated cases; private `*.case.json` files are ignored.
+The first empirical calibration is frozen in the
+[24-case corpus plan](agentic-corpus-plan.md). The plan fixes sources and admission rules; it
+is not evidence that every tranche has already been executed. The receipt-linked
+[TestExplora calibration](testexplora-calibration.md) contributes eight real, stable cases but
+is explicitly curated calibration rather than holdout or `READY_H3` evidence.
+
+## MCP v2 over stdio
+
+Start the read-only server with `assertledger mcp`, or configure an MCP client with `assertledger` as
+the command and `["mcp"]` as its argument array (`testforge mcp` runs the identical server). The
+server name reported to clients is `assertledger`. Every tool is registered twice, under a preferred
+`assertledger_*` name and a legacy `testforge_*` name bound to the same handler and the same tool
+configuration. The schema lookup pair has no single fixed output schema because its selected JSON
+Schema document varies; every other pair shares the same output-schema object. The default server
+exposes twenty-eight read-only tools:
+
+| Preferred tool | Legacy alias | Purpose |
+| --- | --- | --- |
+| `assertledger_analyze` | `testforge_analyze` | Produce repository context for test generation |
+| `assertledger_doctor` | `testforge_doctor` | Return a static repository initialization plan without writing files or executing repository code |
+| `assertledger_explain` | `testforge_explain` | Explain bounded reason codes with versioned guidance and safe next actions |
+| `assertledger_benchmark` | `testforge_benchmark` | Derive scoped cold/warm phase summaries from declared raw runs |
+| `assertledger_benchmark_replay` | `testforge_benchmark_replay` | Replay a self-contained benchmark artifact |
+| `assertledger_profile` | `testforge_profile` | Derive an Agentic Test Profile from replay-valid evidence |
+| `assertledger_profile_replay` | `testforge_profile_replay` | Replay a self-contained profile report |
+| `assertledger_profile_v2` | `testforge_profile_v2` | Derive a benchmark-backed strength and warm-cost profile |
+| `assertledger_profile_v2_replay` | `testforge_profile_v2_replay` | Replay a self-contained Profile v2 report |
+| `assertledger_schema` | `testforge_schema` | Return any of the published JSON Schemas |
+| `assertledger_replay` | `testforge_replay` | Validate and replay a manifest's schema, digests, and decision semantics |
+| `assertledger_benchmark_acquire_replay` | `testforge_benchmark_acquire_replay` | Replay acquisition source, artifact, context, digest, and status bindings |
+| `assertledger_corpus_allocate` | `testforge_corpus_allocate` | Create a deterministic calibration/holdout allocation |
+| `assertledger_corpus_allocation_replay` | `testforge_corpus_allocation_replay` | Replay allocation scores, partition, and digest semantics |
+
+H3 creation and replay are deliberately absent from the default agent-facing MCP server. Its
+operator-owned policy, commitment and plan pins cannot be supplied safely as self-attested tool
+input.
+
+`assertledger_verify`/`testforge_verify` and `assertledger_benchmark_acquire`/`testforge_benchmark_acquire`
+are absent by default, as are `assertledger_check`/`testforge_check` and
+`assertledger_doctor_runtime`/`testforge_doctor_runtime`. A server operator may register these pairs by starting
+`assertledger mcp --allow-unsafe-execution`, or by calling `createAssertLedgerServer({
+allowUnsafeExecution: true })` (the deprecated `createTestForgeServer` alias calls the identical
+factory). The tool then accepts a verification request and executes it without a second per-call
+authorization field. Run that server only inside the intended isolation boundary; do not let an MCP
+caller decide whether the capability exists. The server resolves repository roots to real paths and
+confines them to the server process's current working directory by default. Programmatic operators
+may supply a different `allowedRepositoryRoots` allowlist.
+
+The doctor pair accepts a strict `{ "root": "..." }` input and returns the existing
+`repository-init-result` contract. It is read-only in both the default and operator-enabled server;
+enabling unsafe execution does not change doctor behavior. Dynamic runtime and client diagnostics
+remain outside this static readiness result.
+
+`doctor_runtime` accepts the same strict root input and returns the separate
+[runtime diagnostic contract](runtime-doctor.md). `check` accepts the
+[high-level Git options](git-regression.md), without a permission field, and returns the existing
+evidence manifest. The operator's capability is required for both tools.
+
+## Continuous integration
+
+Run `pnpm check` on every change. The included GitHub Actions workflow runs this gate on Node.js 22
+and 24 on Ubuntu and Windows. A separate matrix installs and exercises the packed artifact on both
+operating systems with Node.js 22.15.0 and 24. A CI job that executes campaigns must
+also treat `trusted-local` as `UNSANDBOXED`: use an isolated runner without secrets or host
+credentials, and pass `--allow-unsafe-execution` only from reviewed CI configuration.
+
+## Decision semantics
+
+- `VERIFIED`: at least one candidate completed all required evidence and was selected.
+- `REJECTED`: the campaign completed, but no candidate satisfied the policy.
+- `INCONCLUSIVE`: controls or candidate evidence were incomplete, unstable, timed out, or affected
+  by infrastructure failure.
+- `ENGINE_ERROR`: the deterministic core could not normalize the supplied evidence safely.
+
+Only an attributed `ASSERTION_FAILURE` can kill a target in protocol v1. Compilation errors,
+collection failures, crashes, timeouts, and infrastructure errors never count as target evidence.
+
+Campaign budgets cover aggregate candidate, world, repository, overlay, and execution counts or
+bytes. `timeoutMsPerExecution` and `maximumOutputBytes` apply to each process execution; the timeout
+and process-tree termination are best effort on the local host.
+
+Before a built-in `node:test` campaign runs, AssertLedger probes the requested executable, resolves its
+real path, probes that resolved file again, and requires matching Node.js versions of at least
+22.15. The manifest records the requested executable, resolved path, Node.js version, and executable
+SHA-256 digest.
+
+Each candidate records the ordered gates `COMPLETENESS`, `STABILITY`, `DISCOVERY`, `REFERENCE`,
+`NEUTRAL`, and `TARGET_STRENGTH`, including evidence run IDs and reason codes. See
+[docs/proof-model.md](proof-model.md) for candidate statuses, controls, selection, and digest
+scope.
+
+The manifest is sufficient to replay AssertLedger's deterministic decision, but it is not a complete
+audit archive. It stores content and process-output digests, not candidate or world bodies, a
+repository archive, or raw logs. Preserve the original request, repository snapshot or trusted
+source reference, raw logs, dependencies, and any structured-command executable identity separately
+when independent audit or reproduction matters. Manifest digests detect changes; they do not
+authenticate the producer.
+
+## Project status and roadmap
+
+The [intent and restart assessment](project-intent.md) records the current implementation,
+adoption gaps, and proposed delivery order. It distinguishes local evidence from release and
+empirical claims.
+
+Version `1.0.0` qualifies the supported node:test workflow. The
+deterministic core and protocols are framework-independent; `node:test` is the first built-in
+framework adapter. Other frameworks integrate through the structured-command protocol described in
+[docs/adapter-protocol.md](adapter-protocol.md).
+
+Planned work is not shipped behavior. Priorities include a real sandbox backend, additional
+framework reporters with runtime attribution, signed provenance, cross-runtime conformance
+fixtures, and more built-in adapters. See [docs/roadmap.md](roadmap.md).
+
+Contributions are welcome under the [MIT license](../LICENSE). Read [CONTRIBUTING.md](../CONTRIBUTING.md)
+before changing a public contract.

package/docs/release-1.0.md

@@ -0,0 +1,63 @@
+# AssertLedger 1.0
+
+Cap décidé par le propriétaire le 8 septembre 2026. Ce document fixe les critères de la version 1.0 ;
+la publication est attestée séparément par le tag, le registre npm et la release GitHub.
+Le nom du package reste `assertledger` et le dépôt public est
+[hoklims/assertledger](https://github.com/hoklims/assertledger).
+
+## Résultat utilisateur
+
+Un développeur ou son agent apporte le test d’une correction. AssertLedger vérifie que ce test
+passe sur la correction et les contrôles déclarés, puis détecte la faute connue par assertion.
+Le résultat identifie les révisions, les octets du test, les essais, les raisons et les limites.
+Le même artefact se rejoue sans modèle dans le terminal et en CI.
+
+La première cible est une équipe Node.js/TypeScript utilisant des agents. La première exécution
+officielle repose sur `node:test` ; les variantes de TypeScript ou de dépendances non qualifiées
+doivent être annoncées comme telles. Détecter un framework ne signifie pas savoir le qualifier.
+
+## Parcours et critères de livraison
+
+| Étape | Critère observable | Issue |
+| --- | --- | --- |
+| Première preuve | Version fautive, correction, test et contrôle neutre déclarés ; test utile et inutile distingués ; manifeste rejouable | [HOK-658](https://linear.app/hoklims/issue/HOK-658) |
+| Adaptateur de référence | Matrice adversariale, trois mondes, deux essais, candidat fort seul sélectionné | [HOK-570](https://linear.app/hoklims/issue/HOK-570) |
+| Diagnostic | Prérequis, permissions et limites expliqués avant exécution ; prochaine action sûre | [HOK-420](https://linear.app/hoklims/issue/HOK-420) |
+| Agents | CLI/SDK/MCP compatibles ; configuration idempotente et confinée aux racines autorisées | [HOK-423](https://linear.app/hoklims/issue/HOK-423) |
+| Restitution | Verdict humain et JSON cohérents, raisons stables, aucune suggestion qui contourne un gate | [HOK-428](https://linear.app/hoklims/issue/HOK-428) |
+| Distribution | Installation du tarball dans un consommateur neuf ; binaires, SDK, fichiers runtime et replay vérifiés | [HOK-659](https://linear.app/hoklims/issue/HOK-659) |
+| Publication | CI et revue du candidat exact, tag/package/release publiés, réinstallation de la version publiée | [HOK-399](https://linear.app/hoklims/issue/HOK-399) |
+
+La documentation doit être copiée et exécutée sans correction implicite. Mesurer le temps jusqu’à
+la première preuve comprise ; cinq minutes reste un objectif, sans résultat annoncé d’avance.
+Une démo locale n’est pas une preuve d’adoption. [Trois pilotes](https://linear.app/hoklims/issue/HOK-660)
+doivent ensuite documenter réutilisation, effort, abandon et volonté de conserver l’intégration.
+
+## Frontières de la version
+
+- Les gates, schémas, projections de digest et aliases TestForge conservent leur compatibilité.
+- Seule une assertion attribuée peut compter comme détection ; les erreurs opérationnelles restent
+  des non-kills. La vitesse ne compense aucun défaut de preuve.
+- Les mondes attendus relèvent de l’opérateur. Un contrôle identique à la référence ne devient pas
+  une preuve indépendante de robustesse.
+- `trusted-local` reste `UNSANDBOXED`, opt-in, réservé au code de confiance. Les exemples CI refusent
+  les contributions non fiables et l’exécution sur un runner privilégié.
+- Le replay vérifie intégrité et cohérence ; il n’authentifie pas le producteur des observations.
+- Profils statistiques et holdout gardent leurs critères avant toute affirmation empirique.
+
+## Extensions conservées
+
+Les adaptateurs Vitest, Jest, Bun et pytest suivent les besoins des pilotes. Cache incrémental,
+landing automatique, profils de performance et isolation des contributions hostiles sont des
+travaux distincts. Leurs critères restent dans Linear ; ils ne sont pas annoncés comme livrés par
+la seule publication d’un package 1.0.
+
+## État de départ vérifié
+
+Le candidat local du 8 septembre passe `pnpm check` avec 307 tests. La version du package est
+encore `0.1.0`. Le dépôt public dédié est créé et `origin` configuré ; aucune release n’est publiée.
+Le contrôle npm initial retournait `E401`. L’authentification du compte personnel `hoklims` a
+ensuite été vérifiée ; elle ne vaut pas preuve de publication.
+Le diff hérité est conservé ; sa présence ne constitue pas une acceptation de tous ses travaux.
+La preuve externe [HOK-406](https://linear.app/hoklims/issue/HOK-406) reste ouverte et ne donne pas
+autorité pour modifier la politique active.

package/docs/repository-audit.md

@@ -0,0 +1,52 @@
+# Repository audit v1
+
+`assertledger audit` inventories a repository without executing tests, adapters, candidates, or
+campaigns. Its output is descriptive: it contains no score, note, quality label, coverage claim, or
+verification verdict.
+
+```sh
+assertledger audit . --json
+assertledger audit . --verification-request request.json --json
+assertledger audit . --emit-verification-request --no-git | assertledger verify - --allow-unsafe-execution
+```
+
+The command discovers `assertledger.request.json` at the audited root unless
+`--verification-request` is supplied. A request is emitted only after v1 validation and exact
+repository-root binding. Emitted requests always have
+`acknowledgedUnsafeExecution: false`; the receiving `verify` command owns the explicit unsafe
+authorization. Exit code `3` means no request was available for `--emit-verification-request`, and
+exit code `4` means the supplied or discovered request was invalid.
+
+## Signals and limits
+
+JavaScript and TypeScript files use the TypeScript lexical scanner. Decision points count `if`,
+loop, `catch`, `case`, conditional, `&&`, `||`, and `??` tokens. Declared exports and test-root
+identifier occurrences produce `noObservedTestReference`; this name deliberately does not claim
+coverage. Test association is conservative: source and `.test`/`.spec` files must share a basename.
+Weak assertion shapes are syntactic occurrences of truthiness-only, constant-boolean equality,
+definedness-only (`toBeDefined`), type-only (`typeof` asserted against a type name), and
+non-throw-only forms. Unsupported languages report `supported: false` and nullable measurements.
+
+Git history is optional. The 90-day window is anchored to the commit timestamp of `HEAD`, never the
+wall clock, and is capped at 1,000 commits. Correction commits are messages containing the explicit
+words `fix`, `bug`, `repair`, `hotfix`, or `regression` (case-insensitive). Missing, shallow, failed,
+or truncated history is represented by nulls and reason codes, not invented zeroes.
+
+Modules use `PATH_PREFIX_V1` (the first two path segments when available). Their contiguous order is
+the descending factual tuple: decision points, exports with no observed test reference, correction
+commits, commits in the window, sources newer than associated tests, weak assertion occurrences;
+the POSIX path prefix breaks ties. The tuple is not a score.
+
+Campaign bounds use decimal BigInt strings. For candidates `C`, worlds `W`, attempts `A`, repository
+bytes `R`, total world-overlay bytes `OW`, total candidate bytes `OC`, timeout `T`, and output limit
+`O`:
+
+- executions = `(C + 1) * W * A`
+- controls = `W * A`; candidate executions = `C * W * A`
+- overlay bytes = `A * ((C + 1) * OW + W * OC)`
+- materialization bytes = `R * (executions + 1) + overlay bytes`
+- timeout limit = `executions * T`
+- captured stream limit = `executions * O * 2`
+
+Two complete inventories bind the audit. A digest change aborts with
+`REPOSITORY_CHANGED_DURING_AUDIT`.

package/docs/repository-init.md

@@ -0,0 +1,60 @@
+# Repository initialization
+
+`assertledger init` performs a static, provider-neutral repository detection pass and manages exactly
+two root files: `assertledger.config.json` and `assertledger.lock.json`. It never runs a test command,
+adapter, candidate, or campaign, and it never edits package manifests, lockfiles, CI configuration,
+or tests.
+
+```sh
+assertledger init . --dry-run --json
+assertledger init . --json
+assertledger audit . --json
+```
+
+The dry run emits the exact canonical bytes and SHA-256 digests that a subsequent write plans to
+use. Writes use a same-directory temporary file followed by an atomic rename. A second run returns
+`UNCHANGED` without rewriting matching files. A missing lock or a stale, structurally valid lock
+bound to the same config can be recovered; invalid files and config-binding conflicts fail closed
+without a `--force` mode.
+
+Detection is conservative. Package-manager declarations and root lockfiles must converge. Multiple
+plausible test frameworks, composite shell scripts, contradictory overrides, and invalid explicit
+adapter configurations return `CONFLICT`. Multiple CI providers are only sorted evidence and do not
+block initialization.
+
+Files at or below the managed `candidateRoots` are deliberately excluded from framework inference,
+evidence, built-in control tests, and repository-change comparison. Candidate generation therefore
+cannot silently redefine initialization facts or invalidate an otherwise unchanged lock.
+
+The built-in ready adapter is currently `node-test`. Bun, pytest, Vitest, and Jest can be detected,
+but initialization returns `BLOCKED` with `OFFICIAL_ADAPTER_UNAVAILABLE` unless the operator supplies
+an existing structured adapter configuration:
+
+```sh
+assertledger init . --adapter-config integrations/my-adapter.json --json
+```
+
+The adapter document is parsed through the public adapter contract and is operator-owned. Its
+executable is recorded as argv but is not resolved or executed by `init`. This is not an official
+adapter endorsement and does not reduce the later `trusted-local` execution boundary.
+`node-test` adapters are accepted only for the `node:test` framework; every other framework requires
+an operator-owned `testforge-command` adapter.
+
+All detections and evidence digests come from one byte snapshot. Immediately before returning or
+writing managed files, initialization rechecks the in-scope inventory and every evidence byte. A
+change returns `CONFLICT` with `REPOSITORY_CHANGED_DURING_INIT` and writes nothing.
+
+Initialization deliberately does not generate a verification request. Both `worlds` and
+`candidates` remain required operator or harness inputs because repository detection cannot infer
+valid semantic faults, neutral transformations, or oracle expectations. The next command is
+`assertledger audit . --json`; that audit may report `VERIFICATION_REQUEST_UNAVAILABLE` until the
+harness supplies those inputs.
+
+Exit codes are `0` for `CREATED`, `UNCHANGED`, or `WOULD_CREATE`; `3` for `BLOCKED`; `4` for
+ambiguity, invalid overrides, conflicts, or contract validation; `5` for unexpected I/O; and `64`
+for CLI usage errors.
+
+The public `repository-init-config.v1`, `repository-init-lock.v1`, and
+`repository-init-result.v1` contracts contain no timestamps, absolute repository roots, environment
+values, worlds, or candidates. The lock binds normalized detections and sorted evidence digests; it
+does not authenticate the detector, repository, adapter, or later execution evidence.

package/docs/research-basis.md

@@ -0,0 +1,27 @@
+# Research basis
+
+AssertLedger's evidence model follows several established testing and provenance principles.
+
+- Mutation testing distinguishes killed mutants from live mutants and reveals oracle weakness that
+  coverage alone cannot show: [PIT](https://pitest.org/) and
+  [Just et al., FSE 2014](https://homes.cs.washington.edu/~mernst/pubs/mutation-effectiveness-fse2014-abstract.html).
+- Repetition measures observed flakiness; a successful retry does not erase a contradictory run:
+  [Gruber et al., 2021](https://arxiv.org/abs/2101.09077) and
+  [Lam et al., ISSTA 2019](https://www.microsoft.com/en-us/research/publication/root-causing-flaky-tests-in-a-large-scale-industrial-setting/).
+- Selection is stated only over executed evidence; “safe” regression-test selection requires stronger
+  assumptions: [Rothermel and Harrold, IEEE TSE 1998](https://digitalcommons.unl.edu/csearticles/11/).
+- The manifest separates external parameters, resolved inputs, builder identity, and byproducts,
+  inspired by [SLSA build provenance v1.2](https://slsa.dev/spec/v1.2/build-provenance). AssertLedger does
+  not claim a SLSA level.
+- The proposed Agentic Test Profile keeps evidence strength and observed execution cost as separate
+  dimensions. This follows cost-aware regression-test prioritization rather than treating line
+  coverage as an oracle-quality score: [Elbaum, Rothermel, and Penix, FSE
+  2014](https://research.google/pubs/techniques-for-improving-regression-testing-in-continuous-integration-development-environments/)
+  and [Meta predictive test
+  selection](https://engineering.fb.com/2018/11/21/developer-tools/predictive-test-selection/).
+- Mutation-guided agentic testing now has industrial hardening and catching-test evidence. The two
+  modes have different reference directions and must remain distinct: [Mutation-Guided LLM-based
+  Test Generation at Meta](https://arxiv.org/abs/2501.12862) and [Just-in-Time Catching Test
+  Generation at Meta](https://arxiv.org/abs/2601.22832).
+
+These sources motivate the design; they do not turn mutant detection into a proof of correctness.

package/docs/roadmap.md

@@ -0,0 +1,74 @@
+# Roadmap
+
+This roadmap separates locally implemented v0.1 behavior from the agreed 1.0 delivery scope.
+See the [intent assessment](project-intent.md) and [1.0 release contract](release-1.0.md) for the
+regression-test qualification workflow, acceptance criteria, and evidence boundaries.
+
+## Implemented locally in v0.1
+
+- deterministic repository analysis;
+- thirty-four versioned public JSON Schemas, all frozen by conformance v1;
+- reference, target, and neutral overlay worlds;
+- one campaign snapshot and disposable execution workspaces;
+- built-in `node:test` runtime reporter and structured-command adapter;
+- deterministic gates, candidate selection, reason codes, and evidence run links;
+- decision and artifact integrity digests;
+- derived Agentic Test Profiles with replay, repository-scoped latency lanes, marginal evidence,
+  and a multi-dimensional Pareto frontier;
+- replayable Agentic Benchmark Artifacts with fingerprinted comparison scopes, cold/warm regimes,
+  deterministic phase quantiles, and explicit sample/failure states;
+- fresh phase-aware benchmark acquisition for `testforge-command`, gated by replay-valid
+  `VERIFIED` evidence and bound to adapter and dependency identities;
+- benchmark-backed Agentic Test Profile v2 reports with an exact warm-total-wall p95 cost basis,
+  selected-only cohort disclosure, deterministic Pareto comparison, and summed-cost portfolios;
+- externally pinned Ed25519 corpus trust policies and canonical dual-signed provenance sidecars;
+- deterministic source-stratified corpus allocations with dual-principal commitment/reveal and
+  private holdout custody;
+- externally pinned H3 experiment plans and artifacts with byte-resolved run receipts, exact
+  planned-process and planned-timeout equality, content-addressed suites, per-source
+  non-inferiority, and a shared frozen candidate universe;
+- a static conformance-v1 oracle locking canonicalization, decisions, replay witnesses, Profile v1,
+  Benchmark v1, and all 34 published schema bytes;
+- a pinned 24-case, three-source empirical corpus plan with signed admission and holdout rules,
+  including eight receipt-linked TestExplora cases admitted only for curated calibration;
+- JSON CLI, TypeScript SDK, MCP v2 stdio server, and integration skill;
+- `trusted-local`, explicitly recorded as `UNSANDBOXED`.
+
+## Release 1.0 priority
+
+1. Qualify a regression test against declared buggy, fixed, and neutral revisions using existing
+   deterministic gates, with useful diagnostics and preserved artifacts.
+2. Verify installation and the documented workflow from the packed package in a fresh consumer.
+3. Add repository diagnostics and agent integration, then a PR/CI report and replay path.
+4. Publish only after exact-candidate checks and required independent review; install and verify
+   the published version before closing delivery.
+
+The first built-in adapter is `node:test`. Broader adapters and optimizations follow pilot needs.
+The empirical work below remains required for scientific claims, rather than for releasing the
+scoped deterministic qualification workflow.
+
+## Further evidence and extensions
+
+1. Complete the [24-case corpus plan](agentic-corpus-plan.md), including provenance sidecars, a
+   separately selected and pre-committed holdout, reviewed historical faults, mutants, and neutral
+   rewrites, before claiming an empirically established sweet spot. The current TestExplora 8/8
+   tranche is curated calibration evidence and cannot satisfy the holdout requirement.
+2. Add faithful framework-specific phase adapters. The framework-neutral acquisition path is
+   shipped, but the built-in `node:test` reporter cannot attribute all four phases.
+3. Add an isolation backend backed by an independently administered container or VM boundary.
+4. Add framework reporters beyond `node:test` that derive discovery and attribution from runtime
+   events.
+5. Publish cross-runtime conformance fixtures for canonicalization, decisions, and both digests.
+6. Add mature replayable experiment artifacts for H1, H2, and H4 without allowing them to
+   compensate for an H3 failure.
+7. Add adapters only when their outcome mapping has adversarial contract tests.
+8. Extend provenance to cover executed dependencies, structured-command binary identities, and
+   effective environment inputs without leaking secrets.
+
+## Explicitly out of scope for v0.1
+
+- hostile-code containment;
+- automatic trust in agent-supplied worlds or policy;
+- proof of program correctness or complete fault detection;
+- proof that a test will never become flaky;
+- SLSA conformance or authenticated provenance.