assertledger 1.0.0

package/docs/runtime-doctor.md

@@ -0,0 +1,65 @@
+# Runtime doctor
+
+AssertLedger's default doctor is static. It reads repository metadata and configuration without
+starting an executable:
+
+```text
+assertledger doctor .
+assertledger doctor . --json
+```
+
+Use runtime doctor only after reviewing the repository and creating its current
+`assertledger.config.json` and `assertledger.lock.json` files:
+
+```text
+assertledger doctor . --runtime --allow-unsafe-execution
+assertledger doctor . --runtime --allow-unsafe-execution --json
+```
+
+Runtime doctor is explicitly **UNSANDBOXED trusted-local**. The authorization flag is required to
+start processes; it does not create a sandbox. Omitting it returns a stable `BLOCKED` result before
+configuration inspection or executable probes. Unknown flags, repeated flags, and using
+`--allow-unsafe-execution` without `--runtime` are usage errors.
+
+## What it checks
+
+Version 1.0 supports the generated official `node:test` adapter. It fails closed for other
+frameworks and operator-supplied adapters. In order, it checks:
+
+1. explicit trusted-local authorization;
+2. a current AssertLedger configuration and evidence lock;
+3. the supported generated `node:test` adapter;
+4. a stable Node.js executable at version 22.15 or newer;
+5. availability of Node's built-in `node:test` module;
+6. permission to create, write, and clean up an operating-system temporary workspace;
+7. controlled reporter discovery, liveness, and attribution probes.
+
+The final probes use disposable synthetic tests. One assertion failure must be attributed to the
+candidate; a generic throw with a nested assertion cause must remain a process crash and must not
+be attributed. Malformed reporter output, missing discovery, cleanup failure, timeout, or process
+failure blocks readiness. AssertLedger does not write to the repository during runtime doctor.
+
+## Result contract
+
+The SDK exposes the same strict additive contract:
+
+```ts
+import { AssertLedger, parseRuntimeDoctorResult } from "assertledger";
+
+const result = await new AssertLedger().doctorRuntime(repositoryRoot, {
+  allowUnsafeExecution: true,
+});
+parseRuntimeDoctorResult(result);
+```
+
+`schemaVersion` is `1.0.0`. Each check has `PASS`, `BLOCKED`, or `LIMITATION`, a stable reason code
+when relevant, a concise summary, and a safe next action. The top-level status is `READY` only when
+every supported runtime boundary passes. JSON results contain no subprocess output, environment
+values, credentials, or repository source.
+
+Runtime doctor always records a limitation: it does not run the repository's tests, evaluate a
+candidate, or prove campaign evidence. `READY` means the supported synthetic runtime boundary is
+operational. It is not a test-health or regression-verification verdict. Run an explicitly
+authorized `check` or `verify` workflow for evidence.
+
+The CLI exits with `0` for `READY`, `3` for `BLOCKED`, and `64` for malformed arguments.

package/docs/testexplora-calibration.md

@@ -0,0 +1,71 @@
+# TestExplora curated calibration evidence
+
+TestExplora is the third real-fault source selected after BugsJS, ManyBugs, and BugSwarm failed the
+declared reproducibility gates. Its admission status is `ADMITTED_CURATED_CALIBRATION`: eight cases
+are suitable for threshold and protocol calibration, but they are not a hidden holdout, a
+population-rate estimate, or evidence that H3 is ready.
+
+## Immutable source inputs
+
+- harness: `microsoft/TestExplora@11e6952261f58d3ceb9f4d2571e03aa35dad9523`;
+- harness tree: `98bb0effbcb55b9d15c442660a9de145a7268e14`;
+- harness MIT license bytes: `sha256:98a96c38494df4963951e32b81ec4effebe4c8a812ab8d9e7d185d59e86fe2fc`;
+- dataset revision: `91d8edfb851331bc77eddff40c794336b16c79fe`;
+- source parquet: 19,131,078 bytes,
+  `sha256:0d107eb22a082a3549adaf3ea52473d07ffee13b8d9eec908a243916de171c0a`.
+
+The pinned parquet contains 1,552 rows from 482 repositories. Its released schema exposes
+`instance_id`, `repo`, `pull_number`, `base_commit`, `pr_patch`, `code_patch`, `test_patch`,
+`documentation`, and `test_invokes`. It does not expose the `FAIL_TO_PASS` or `test_invoke_path`
+fields described by earlier material. `test_invokes` is dependency metadata, not an execution
+command or an outcome oracle.
+
+## Qualification protocol
+
+Each admitted case uses the upstream production patch and test patch, while keeping the test patch
+outside any future generator context. The environment was reconstructed from pinned base images,
+wheel or source distributions, and subject commits. Dependencies were downloaded before the lock;
+project images were built and all observations executed with networking disabled.
+
+Every case required three fresh buggy observations with an assertion failure attributable to the
+introduced test, three fresh fixed observations that passed, and a green positive sentinel. A
+compilation, collection, process, timeout, infrastructure, generic-exception, or positive-suite
+failure was inconclusive and never counted as detection.
+
+The eight admitted cases are:
+
+- `almarklein__timetagger-117`;
+- `rigetti__pyquil-1758`;
+- `cloud-custodian__cloud-custodian-9970`;
+- `pyinfra-dev__pyinfra-930`;
+- `reata__sqllineage-431`;
+- `PyCQA__pyflakes-438`;
+- `adrienverge__yamllint-422`;
+- `googleapis__python-genai-739`.
+
+## Evidence index
+
+The external evidence root is `E:\testforge-evidence\corpus-sources`. Subject sources and images
+are not redistributed from this repository.
+
+| Campaign | Admitted | Manifest SHA-256 |
+| --- | ---: | --- |
+| `testexplora-preflight-v1` | 5 | `e461cd48f252b9c16705656f42ca3cb8a6389c70c9be0bedac3ce4aafe5f50ad` |
+| `testexplora-replacements-v1` | 1 | `9faf9acec63b96f9e3849a9b37066607394bc5c5899ecc63cf312a3171470e76` |
+| `testexplora-replacements-v2` | 1 | `ca545ccb83841b929181cbac6cf508974ba2d856f008b4922277b42bc85ef9d5` |
+| `testexplora-replacements-v3` | 1 | `121078b7d80ce677148ae5fc0bb79a44e45297631765059b2189122b77c82b09` |
+
+The combined admission document is
+`testexplora-replacements-v3/COMBINED_ADMISSION.json`, SHA-256
+`05695fb7afa269eb740c092e438561b54aa55f89857ce58d2d842b5a79603560`.
+It binds the prior campaign manifests and the final campaign's selection, plan, pre-run lock, and
+results. The final recursive manifest lists 61 payloads with zero mismatch and zero unlisted file.
+
+## Proof boundary
+
+The environments are AssertLedger reconstructions, not reference environments supplied by
+TestExplora. The multi-campaign selection is intentionally calibrated from prior outcomes. These
+receipts establish eight stable real-fault calibration cases, not sampling representativeness,
+generalization, independent temporal custody, or holdout integrity. TestExplora can contribute to
+mature H3 only through a new unseen selection, a two-party committed allocation, signed provenance,
+an externally pinned experiment plan, and independently executed receipts.

package/examples/agentic-benchmark/benchmark-request.mjs

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import { AssertLedger } from "assertledger";
+
+const requestPath = process.argv[2];
+if (requestPath === undefined) {
+  console.error("Usage: node benchmark-request.mjs <agentic-benchmark-request.json>");
+  process.exitCode = 64;
+} else {
+  const request = JSON.parse(await readFile(requestPath, "utf8"));
+  const assertLedger = new AssertLedger();
+  const artifact = assertLedger.benchmark(request);
+  process.stdout.write(`${JSON.stringify(artifact)}\n`);
+  const statuses = artifact.summaries.map((summary) => summary.status);
+  process.exitCode = statuses.every((status) => status === "MEASURED")
+    ? 0
+    : statuses.some((status) => status === "OBSERVED_RUN_FAILURE")
+      ? 2
+      : 3;
+}

package/examples/agentic-benchmark/structured-phase-adapter-fixture.mjs

@@ -0,0 +1,35 @@
+// Deterministic wire-protocol fixture. Fixed durations are illustrative, not measurements.
+import { writeFile } from "node:fs/promises";
+
+const candidateFiles = JSON.parse(process.env.TESTFORGE_CANDIDATE_FILES ?? "[]");
+const benchmarkResultFile = process.env.TESTFORGE_BENCHMARK_RESULT_FILE;
+
+if (benchmarkResultFile === undefined) {
+  await writeFile(
+    process.env.TESTFORGE_RESULT_FILE,
+    JSON.stringify({
+      protocolVersion: "1.0.0",
+      outcome: "PASS",
+      testsDiscovered: candidateFiles.length === 0 ? 1 : 2,
+      candidateTestsDiscovered: candidateFiles.length === 0 ? 0 : 1,
+      attributed: candidateFiles.length > 0,
+    }),
+  );
+} else {
+  await writeFile(
+    benchmarkResultFile,
+    JSON.stringify({
+      protocolVersion: "1.0.0",
+      outcome: "PASS",
+      testsDiscovered: 1,
+      candidateTestsDiscovered: 1,
+      attributed: true,
+      phases: [
+        { phase: "STARTUP", durationUs: 10 },
+        { phase: "COMPILE_OR_COLLECTION", durationUs: 20 },
+        { phase: "EXECUTION", durationUs: 30 },
+      ],
+      cpuTimeUs: null,
+    }),
+  );
+}

package/examples/agentic-profile/profile-benchmark.mjs

@@ -0,0 +1,34 @@
+import { readFile } from "node:fs/promises";
+import { AssertLedger } from "../../dist/index.js";
+
+const artifactPath = process.argv[2];
+if (artifactPath === undefined) {
+  throw new Error("Usage: node profile-benchmark.mjs <benchmark-artifact.json>");
+}
+
+const benchmarkArtifact = JSON.parse(await readFile(artifactPath, "utf8"));
+const assertLedger = new AssertLedger();
+const report = assertLedger.profileV2({
+  schemaVersion: "2.0.0",
+  benchmarkArtifact,
+  policy: {
+    profileVersion: "2.0.0",
+    profileId: "example/hardening-v2",
+    mode: "HARDENING",
+    requiredComparisonScopeDigest: benchmarkArtifact.comparisonScopeDigest,
+    costBasis: {
+      regime: "WARM",
+      measure: "WALL",
+      aggregation: "TOTAL",
+      statistic: "P95",
+      unit: "MICROSECOND",
+      portfolioAggregation: "SUM_OF_INDIVIDUAL_P95",
+    },
+    lanes: [
+      { id: "instant", maximumWarmTotalWallP95Us: 2_000_000 },
+      { id: "loop", maximumWarmTotalWallP95Us: 10_000_000 },
+    ],
+  },
+});
+
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);

package/examples/agentic-profile/profile-manifest.mjs

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { AssertLedger } from "assertledger";
+
+const manifestPath = process.argv[2];
+if (manifestPath === undefined) {
+  console.error("Usage: node profile-manifest.mjs <manifest.json> [profile-id]");
+  process.exitCode = 64;
+} else {
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const assertLedger = new AssertLedger();
+  const report = assertLedger.profile({
+    schemaVersion: "1.0.0",
+    manifest,
+    policy: {
+      profileVersion: "1.0.0",
+      profileId: process.argv[3] ?? "example/default",
+      mode: "HARDENING",
+      minimumTimingSamples: 3,
+      lanes: [
+        { id: "instant", maximumReferenceP95Ms: 2_000 },
+        { id: "loop", maximumReferenceP95Ms: 10_000 },
+        { id: "gate", maximumReferenceP95Ms: 60_000 },
+      ],
+    },
+  });
+  process.stdout.write(`${JSON.stringify(report)}\n`);
+  process.exitCode = report.status === "QUALIFIED" ? 0 : 2;
+}

package/examples/git-history/README.md

@@ -0,0 +1,44 @@
+# A historical bug, exercised from the installed package
+
+This example uses byte-exact `index.js` snapshots from the MIT-licensed
+[`escape-string-regexp` Unicode-hyphen correction](https://github.com/sindresorhus/escape-string-regexp/commit/732905da074f0220487ad6a27590f89bd0819374).
+The upstream commit and blob IDs, SHA-256 hashes and license are bundled beside them.
+
+The demo creates a **new projected Git history** with an AssertLedger-authored `node:test`
+harness. It does not claim to run the upstream repository's original AVA tests. No network
+access or dependency installation is needed once AssertLedger is installed; Node and Git
+must be available.
+
+Run the following from your project after installing `assertledger`:
+
+```sh
+node node_modules/assertledger/examples/git-history/create-demo.mjs regression-demo
+```
+
+The JSON output gives `before`, `after`, `neutral`, the test path and the declared neutral
+reason. Copy those exact values into `assertledger check`; see the
+[Git command reference](../../docs/git-regression.md). The target directory must not exist.
+
+| Candidate | Expected result | Why |
+| --- | --- | --- |
+| `strong.test.mjs` | `VERIFIED` | An assertion detects the invalid Unicode pattern on the buggy code. |
+| `weak.test.mjs` | `REJECTED` | Checking only the return type passes on both versions. |
+| `crash.test.mjs` | `REJECTED` | A generic error on buggy code is not an attributed assertion. |
+
+Use a new `--out` directory for each candidate. Base tests stay identical across all three
+worlds. The neutral commit changes only documentation, so it is a declared control, not an
+independent demonstration of robustness. `trusted-local` execution remains unsandboxed.
+
+The package smoke runs all three candidates, replays every manifest, checks source and index
+preservation, and retains the manifests, executed requests and summaries as CI artifacts.
+
+## Français
+
+Le cas reproduit une correction réelle : l’ancienne fonction échappait le tiret avec une forme
+invalide dans une expression régulière Unicode. Les deux fichiers sources sont conservés à
+l’octet près, avec leurs références Git et leur licence.
+
+L’historique de démonstration et les tests `node:test` sont créés par AssertLedger. Le test fort
+vérifie que la construction de l’expression régulière ne lève pas d’erreur ; le test faible
+vérifie seulement le type de retour. Une exception générique ne suffit pas pour prouver la
+détection du défaut.

package/examples/git-history/create-demo.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The snapshots retain their upstream bytes and MIT notice. Only the harness is authored here.
+const sources = path.join(path.dirname(fileURLToPath(import.meta.url)), "escape-string-regexp");
+const provenance = JSON.parse(readFileSync(path.join(sources, "provenance.json"), "utf8"));
+for (const source of provenance.sources) {
+  const bytes = readFileSync(path.join(sources, source.file));
+  assert.equal(createHash("sha256").update(bytes).digest("hex"), source.sha256);
+  assert.equal(
+    createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"),
+    source.gitBlob,
+  );
+}
+assert.equal(process.argv.length, 3, "Usage: node create-demo.mjs NEW_DIRECTORY");
+const requested = path.resolve(process.argv[2]);
+mkdirSync(requested); // Exclusive creation: never overwrite a user's repository.
+const root = realpathSync(requested);
+const environment = {
+  PATH: process.env.PATH ?? "",
+  SystemRoot: process.env.SystemRoot ?? "",
+  TEMP: process.env.TEMP ?? "",
+  TMP: process.env.TMP ?? "",
+  GIT_CONFIG_NOSYSTEM: "1",
+  GIT_CONFIG_GLOBAL: path.join(root, ".absent-global-config"),
+  GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z",
+  GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+};
+function git(args) {
+  const result = spawnSync(
+    "git",
+    [
+      "-c",
+      "core.autocrlf=false",
+      "-c",
+      "commit.gpgSign=false",
+      "-c",
+      `core.hooksPath=${path.join(root, ".git/no-hooks")}`,
+      "-c",
+      "user.name=AssertLedger Demo",
+      "-c",
+      "user.email=demo@example.invalid",
+      ...args,
+    ],
+    {
+      cwd: root,
+      env: environment,
+      shell: false,
+      windowsHide: true,
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 1_048_576,
+    },
+  );
+  assert.ifError(result.error);
+  assert.equal(result.signal, null);
+  assert.equal(result.status, 0, result.stderr);
+  return result.stdout.trim();
+}
+function commit(message) {
+  git(["add", "."]);
+  git(["commit", "-m", message]);
+  return git(["rev-parse", "HEAD"]);
+}
+git(["init", "--template=", "--initial-branch=main"]);
+writeFileSync(
+  path.join(root, "package.json"),
+  '{"name":"assertledger-historical-demo","private":true}\n',
+);
+copyFileSync(path.join(sources, "LICENSE"), path.join(root, "LICENSE"));
+copyFileSync(path.join(sources, "before.cjs.txt"), path.join(root, "subject.cjs"));
+writeFileSync(
+  path.join(root, "README.md"),
+  "Projection of a real upstream correction; see AssertLedger example provenance.\n",
+);
+const prelude =
+  'import assert from "node:assert/strict";\nimport test from "node:test";\nimport escape from "./subject.cjs";\n';
+writeFileSync(
+  path.join(root, "base.test.mjs"),
+  `${prelude}test("ordinary characters", () => assert.equal(escape("hello"), "hello"));\n`,
+);
+writeFileSync(
+  path.join(root, "strong.test.mjs"),
+  `${prelude}test("Unicode hyphen regression", () => {
+  assert.doesNotThrow(() => new RegExp(escape("-"), "u"));
+  assert.equal(new RegExp(escape("-"), "u").test("-"), true);
+});\n`,
+);
+writeFileSync(
+  path.join(root, "weak.test.mjs"),
+  `${prelude}test("weak check", () => assert.equal(typeof escape("-"), "string"));\n`,
+);
+writeFileSync(
+  path.join(root, "crash.test.mjs"),
+  `${prelude}test("generic throw is not evidence", () => {
+  if (escape("-") === "\\\\-") throw new Error("generic failure");
+  assert.equal(typeof escape("-"), "string");
+});\n`,
+);
+const before = commit(
+  `Upstream buggy module ${provenance.sources[0].commit}, with node:test harness`,
+);
+copyFileSync(path.join(sources, "fixed.cjs.txt"), path.join(root, "subject.cjs"));
+const after = commit(`Upstream corrected module ${provenance.sources[1].commit}, byte-exact`);
+writeFileSync(
+  path.join(root, "README.md"),
+  "Projection of a real upstream correction; documentation-only neutral control.\n",
+);
+const neutral = commit("Declared neutral: documentation-only edit to corrected tree");
+console.log(
+  JSON.stringify({
+    repository: root,
+    before,
+    after,
+    neutral,
+    neutralReason:
+      "Documentation-only change to the corrected tree; no additional behavioral robustness claim",
+    test: "strong.test.mjs",
+    baseTests: ["base.test.mjs"],
+    out: "evidence-strong",
+    provenance,
+  }),
+);

package/examples/git-history/escape-string-regexp/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/examples/git-history/escape-string-regexp/before.cjs.txt

@@ -0,0 +1,11 @@
+'use strict';
+
+const matchOperatorsRegex = /[|\\{}()[\]^$+*?.-]/g;
+
+module.exports = string => {
+	if (typeof string !== 'string') {
+		throw new TypeError('Expected a string');
+	}
+
+	return string.replace(matchOperatorsRegex, '\\$&');
+};

package/examples/git-history/escape-string-regexp/fixed.cjs.txt

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = string => {
+	if (typeof string !== 'string') {
+		throw new TypeError('Expected a string');
+	}
+
+	// Escape characters with special meaning either inside or outside character sets.
+	// Use a simple backslash escape when it’s always valid, and a \unnnn escape when the simpler form would be disallowed by Unicode patterns’ stricter grammar.
+	return string
+		.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
+		.replace(/-/g, '\\u002d');
+};

package/examples/git-history/escape-string-regexp/provenance.json

@@ -0,0 +1,28 @@
+{
+  "repository": "sindresorhus/escape-string-regexp",
+  "fixUrl": "https://github.com/sindresorhus/escape-string-regexp/commit/732905da074f0220487ad6a27590f89bd0819374",
+  "sources": [
+    {
+      "file": "before.cjs.txt",
+      "upstreamPath": "index.js",
+      "commit": "5085b257c801507460270b747f645276fbc1d937",
+      "gitBlob": "58217a4efa3c835c532499a3dad887017dc70a6b",
+      "sha256": "48b8be4119e6f09b8942c490397fc047da012e0cc223d75a76363856af68fce4"
+    },
+    {
+      "file": "fixed.cjs.txt",
+      "upstreamPath": "index.js",
+      "commit": "732905da074f0220487ad6a27590f89bd0819374",
+      "gitBlob": "e5bb9db7933b7230327c7d99cc8459575f090dd4",
+      "sha256": "44f81777dbee24c245fc220d9e019e031da31a5722743a74272f218b7ffed563"
+    },
+    {
+      "file": "LICENSE",
+      "upstreamPath": "license",
+      "commit": "732905da074f0220487ad6a27590f89bd0819374",
+      "gitBlob": "e7af2f77107d73046421ef56c4684cbfdd3c1e89",
+      "sha256": "48da2f39e100d4085767e94966b43f4fa95ff6a0698fba57ed460914e35f94a0"
+    }
+  ],
+  "scope": "Byte-exact upstream module snapshots, projected into an AssertLedger-authored node:test Git fixture. This does not qualify the complete upstream repository or its original AVA suite."
+}

package/examples/node-test/repository/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "assertledger-node-example",
+  "private": true,
+  "type": "module"
+}

package/examples/node-test/repository/src/is-even.js

@@ -0,0 +1,3 @@
+export function isEven(value) {
+  return value % 2 === 0;
+}

package/examples/node-test/repository/tests/base.test.js

@@ -0,0 +1,6 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+test("baseline arithmetic works", () => {
+  assert.equal(1 + 1, 2);
+});

package/examples/node-test/request.json

@@ -0,0 +1,93 @@
+{
+  "schemaVersion": "1.0.0",
+  "repository": {
+    "root": "./examples/node-test/repository",
+    "exclude": [".git", ".testforge", "node_modules"]
+  },
+  "adapter": {
+    "kind": "node-test",
+    "executable": "node",
+    "baseTestFiles": ["tests/base.test.js"]
+  },
+  "isolation": {
+    "kind": "trusted-local",
+    "acknowledgedUnsafeExecution": true,
+    "environmentAllowlist": ["PATH", "SystemRoot", "WINDIR", "TEMP", "TMP"]
+  },
+  "candidateRoots": ["tests/candidates"],
+  "budgets": {
+    "maximumCandidates": 4,
+    "maximumWorlds": 4,
+    "maximumExecutions": 24,
+    "maximumRepositoryFiles": 10000,
+    "maximumRepositoryBytes": 100000000,
+    "maximumWorldOverlayBytes": 1000000,
+    "maximumCandidateBytes": 16384,
+    "maximumTotalCandidateBytes": 65536,
+    "timeoutMsPerExecution": 5000,
+    "maximumOutputBytes": 65536
+  },
+  "policy": {
+    "policyVersion": "1.0.0",
+    "requiredAttempts": 2,
+    "minimumTargetWeightPermille": 1000,
+    "maximumSelectedCandidates": 1,
+    "acceptedTargetOutcomes": ["ASSERTION_FAILURE"]
+  },
+  "worlds": [
+    {
+      "id": "reference",
+      "kind": "REFERENCE",
+      "required": true,
+      "weight": 0,
+      "provenance": "example:correct-implementation",
+      "files": []
+    },
+    {
+      "id": "target-parity-inversion",
+      "kind": "TARGET",
+      "required": true,
+      "weight": 1,
+      "provenance": "example:known-fault",
+      "files": [
+        {
+          "path": "src/is-even.js",
+          "content": "export function isEven(value) {\n  return value % 2 === 1;\n}\n"
+        }
+      ]
+    },
+    {
+      "id": "neutral-bitwise-equivalence",
+      "kind": "NEUTRAL",
+      "required": true,
+      "weight": 0,
+      "provenance": "example:reviewed-equivalent",
+      "files": [
+        {
+          "path": "src/is-even.js",
+          "content": "export function isEven(value) {\n  return (value & 1) === 0;\n}\n"
+        }
+      ]
+    }
+  ],
+  "candidates": [
+    {
+      "id": "strong",
+      "files": [
+        {
+          "path": "tests/candidates/strong.test.js",
+          "content": "import assert from \"node:assert/strict\";\nimport test from \"node:test\";\nimport { isEven } from \"../../src/is-even.js\";\ntest(\"two is even\", () => assert.equal(isEven(2), true));\n"
+        }
+      ]
+    },
+    {
+      "id": "weak",
+      "files": [
+        {
+          "path": "tests/candidates/weak.test.js",
+          "content": "import assert from \"node:assert/strict\";\nimport test from \"node:test\";\nimport { isEven } from \"../../src/is-even.js\";\ntest(\"returns a boolean\", () => assert.equal(typeof isEven(2), \"boolean\"));\n"
+        }
+      ]
+    }
+  ]
+}

package/integrations/skill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: assertledger
+description: Analyze a repository, submit candidate tests, and accept only deterministic AssertLedger evidence.
+metadata:
+  version: "1.0.0"
+---
+
+# AssertLedger skill
+
+Use this skill when an agent is asked to generate tests whose actual evidence must be checked.
+
+AssertLedger was formerly named TestForge. The `assertledger` CLI is the preferred binary; the
+`testforge` binary remains a legacy-compatible alias for the same commands during the compatibility
+window.
+
+## Preferred path: a committed regression
+
+1. Run `assertledger doctor <repo> --json` for static readiness. Runtime probes require the separate
+   `doctor --runtime --allow-unsafe-execution` command and prior operator authorization.
+2. Ask the operator or harness for the buggy, corrected and neutral revisions, the neutral reason,
+   candidate path and unchanged base tests. Do not invent a neutral control's meaning.
+3. For committed dependency-free JavaScript `node:test`, use `assertledger check` or the MCP
+   `assertledger_check` tool. The server operator must enable execution; a tool payload cannot grant it.
+4. Preserve the manifest and run `assertledger replay`. Use `assertledger explain CODE` or the
+   read-only `assertledger_explain` tool to understand a refusal without changing the policy.
+5. The configuration, skill and server do not grant trust. Never treat a crash, timeout, compilation
+   error or missing test as detection. The returned limitations remain part of the result.
+
+## Lower-level verification requests
+
+1. Run `assertledger init <repo> --dry-run --json`, review conflicts and planned bytes, then run
+   `assertledger init <repo> --json`. Initialization is static and manages only the two AssertLedger
+   root files; it never executes a command or generates worlds or candidates.
+2. Run `assertledger audit <repo> --json`, then `assertledger analyze <repo> --json` for generation
+   context. Audit may report `VERIFICATION_REQUEST_UNAVAILABLE` until the harness supplies the two
+   required operator inputs: `worlds` and `candidates`.
+3. Propose candidate files only under the config's `candidateRoots`.
+4. Do not let candidate content choose worlds, expected outcomes, policy, or budgets. Those belong to
+   the operator or harness.
+5. Submit all candidates in one versioned verification request.
+6. Run `assertledger verify <request> --allow-unsafe-execution --json` only when the controlling human
+   or CI policy has authorized the `UNSANDBOXED` local backend.
+7. Preserve the returned manifest, then run `assertledger replay <manifest> --json`.
+8. Treat only `VERIFIED` plus a replay result whose `valid` field is true as positive evidence. This
+   requires valid schema, decision digest, artifact digest, and decision semantics. `REJECTED`,
+   `INCONCLUSIVE`, invalid input, engine errors, and invalid replay results are stop conditions, not
+   soft passes.
+9. Preserve the emitted manifest as the auditable artifact. Never summarize away failed attempts,
+   controls, limitations, or isolation level.
+
+Never claim that AssertLedger proves overall program correctness or universal non-flakiness.