@markstanden/opencode-test-container 0.0.0-stage → 0.1.0

package/dist/reporting/report.d.ts

@@ -0,0 +1,79 @@
+/** The derived report document. */
+export interface Report {
+    /** The schema version value. */
+    schemaVersion: 1;
+    /** The campaign id value. */
+    campaignId: string;
+    /** The suite id value. */
+    suiteId: string;
+    /** The report sha256 value. */
+    reportSha256: string;
+    /** The closed at value. */
+    closedAt: string | null;
+    /** The image id value. */
+    imageId: string;
+    /** The generated at value. */
+    generatedAt: string;
+    /** The denominators value. */
+    denominators: {
+        scheduled: number;
+        assessed: number;
+        valid: number;
+        invalid: number;
+        unknown: number;
+        unrun: number;
+        judged: number;
+        unjudged: number;
+    };
+    /** The totals value. */
+    totals: {
+        pass: number;
+        fail: number;
+        unknown: number;
+    };
+    /** The slots value. */
+    slots: Array<{
+        slotId: string;
+        caseId: string;
+        armId: string;
+        repetitionId: string;
+        expected: string;
+        observed: string;
+        validity: string;
+        outcome: string;
+        reasons: string[];
+        counts: Record<string, number>;
+        usage: Record<string, unknown> | null;
+        judgement: {
+            selectedAttemptId: string;
+            attempts: number;
+            documentationOutcome: string | null;
+            utility: number | null;
+            status: string;
+        } | null;
+        judgeProblems: string[];
+    }>;
+}
+/** A report render result. */
+export type ReportResult = {
+    ok: true;
+    report: Report;
+    markdown: string;
+    outDir: string;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * Render the final analysis from checked evidence. Requires a closed ledger
+ * and writes only to a fresh output directory outside the evidence tree.
+ * @param root The campaign root.
+ * @param outDir The fresh report directory.
+ * @param now Injected clock.
+ * @returns The report, or the refusals.
+ */
+export declare function analyseCampaign(root: string, outDir: string, now?: () => string): ReportResult;
+/** The canonical identity of a report without its own identity field. */
+export declare function reportIdentity(report: Report): string;
+/** Ensure a report's identity still matches its content. */
+export declare function reportIntact(report: Report): boolean;

package/dist/reporting/report.js

@@ -0,0 +1,242 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256Of } from "../contracts/canonical.js";
+import { isRecord } from "../contracts/validate.js";
+import { loadPreparedManifest, } from "../campaign/prepare.js";
+import { loadFrozen } from "../campaign/freeze.js";
+import { readLedger } from "../campaign/ledger.js";
+import { readAssessments } from "../campaign/assess.js";
+import { checkedSelectionForSlot, readSelectedJudgement, } from "../campaign/judge.js";
+import { trialDirectory } from "../campaign/run.js";
+/** Read a trial's usage record, or null. */
+function readUsage(root, slotId) {
+    const path = join(trialDirectory(root, slotId), "usage.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The expected/observed pair for either evaluator. */
+function observedOf(assessment) {
+    if (assessment.kind === "skill-activation") {
+        return {
+            expected: assessment.expected,
+            observed: assessment.observed,
+            counts: assessment.counts,
+        };
+    }
+    return {
+        expected: assessment.expected,
+        observed: assessment.outcome,
+        counts: assessment.counts,
+    };
+}
+/** The selected judgement summary for one slot. */
+function judgementOf(root, slotId) {
+    const selected = readSelectedJudgement(root, slotId);
+    if (selected === null)
+        return null;
+    return {
+        selectedAttemptId: selected.selection.selectedAttemptId,
+        attempts: selected.selection.attempts.length,
+        documentationOutcome: selected.judgement.documentationOutcome,
+        utility: selected.judgement.utility,
+        status: selected.judgement.status,
+    };
+}
+/** The packet and selection integrity diagnostics for one judged slot. */
+function judgeProblemsOf(root, manifest, slotId) {
+    if (manifest.campaign.assessment.judge === undefined)
+        return [];
+    const checked = checkedSelectionForSlot(root, slotId);
+    return checked.ok ? [] : checked.problems;
+}
+/** The slot table rows. */
+function slotRows(report) {
+    return report.slots.map((slot) => {
+        const counts = Object.entries(slot.counts)
+            .map(([key, value]) => `${key}=${value}`)
+            .join(" ");
+        return `| ${slot.slotId} | ${slot.caseId} | ${slot.armId} | ${slot.repetitionId} | ${slot.expected} | ${slot.observed} | ${slot.validity} | ${slot.outcome} | ${counts} | ${slot.judgement === null ? "unjudged" : `${slot.judgement.documentationOutcome} (${String(slot.judgement.utility)}); ${slot.judgement.selectedAttemptId}`} |`;
+    });
+}
+/** The refusal and unknown section, when any slot has a reason. */
+function reasonSection(report) {
+    const reasons = report.slots.filter((slot) => slot.reasons.length > 0);
+    if (reasons.length === 0)
+        return [];
+    return [
+        "",
+        "## Refusals and unknowns",
+        "",
+        ...reasons.map((slot) => `- **${slot.slotId}**: ${slot.reasons.join("; ")}`),
+    ];
+}
+/** The judge integrity section, when any slot has a diagnostic. */
+function judgeIntegritySection(report) {
+    const problems = report.slots.filter((slot) => slot.judgeProblems.length > 0);
+    if (problems.length === 0)
+        return [];
+    return [
+        "",
+        "## Judge integrity",
+        "",
+        ...problems.flatMap((slot) => slot.judgeProblems.map((problem) => `- **${slot.slotId}**: ${problem}`)),
+    ];
+}
+/** The per-run usage section. */
+function usageSection(report) {
+    return report.slots.flatMap((slot) => {
+        const usage = slot.usage;
+        if (usage === null)
+            return [`- ${slot.slotId}: unknown (no usage record)`];
+        return [
+            `- ${slot.slotId}: input ${String(usage.inputTokens ?? "unknown")}, output ${String(usage.outputTokens ?? "unknown")}, cache read ${String(usage.cacheReadTokens ?? "unknown")}, reported ${String(usage.reported ?? false)}`,
+        ];
+    });
+}
+/** Render the human-readable report. */
+function markdownOf(report) {
+    return [
+        `# OTC report — ${report.campaignId}`,
+        "",
+        `- Suite: \`${report.suiteId}\``,
+        `- Image: \`${report.imageId}\``,
+        `- Closed: ${report.closedAt ?? "no"}`,
+        `- Generated: ${report.generatedAt}`,
+        `- Report identity: \`${report.reportSha256}\``,
+        "",
+        "## Denominator",
+        "",
+        `Scheduled ${report.denominators.scheduled}; assessed ${report.denominators.assessed}; valid ${report.denominators.valid}; invalid ${report.denominators.invalid}; unknown ${report.denominators.unknown}; unrun ${report.denominators.unrun}; judged ${report.denominators.judged}; unjudged ${report.denominators.unjudged}.`,
+        "",
+        `Pass ${report.totals.pass}; fail ${report.totals.fail}; unknown ${report.totals.unknown}. The valid denominator is pass + fail (${report.totals.pass + report.totals.fail}); invalid and unrun runs are excluded and listed below.`,
+        "",
+        "## Slots",
+        "",
+        "| Slot | Case | Arm | Rep | Expected | Observed | Validity | Outcome | Counts | Judgement |",
+        "| ---- | ---- | --- | --- | -------- | -------- | -------- | ------- | ------ | --------- |",
+        ...slotRows(report),
+        ...reasonSection(report),
+        ...judgeIntegritySection(report),
+        "",
+        "## Per-run usage",
+        "",
+        ...usageSection(report),
+        "",
+    ].join("\n");
+}
+/**
+ * Render the final analysis from checked evidence. Requires a closed ledger
+ * and writes only to a fresh output directory outside the evidence tree.
+ * @param root The campaign root.
+ * @param outDir The fresh report directory.
+ * @param now Injected clock.
+ * @returns The report, or the refusals.
+ */
+export function analyseCampaign(root, outDir, now = () => new Date().toISOString()) {
+    const prepared = loadPreparedManifest(root);
+    if (!prepared.ok) {
+        return { ok: false, problems: [prepared.problem] };
+    }
+    const frozen = loadFrozen(root);
+    if (!frozen.ok)
+        return { ok: false, problems: [frozen.problem] };
+    const ledger = readLedger(root);
+    if (ledger.state !== "closed") {
+        return {
+            ok: false,
+            problems: [
+                `campaign is ${ledger.state}; close it before the final analysis`,
+            ],
+        };
+    }
+    if (existsSync(outDir)) {
+        return {
+            ok: false,
+            problems: [
+                `${outDir} already exists; reports are never overwritten`,
+            ],
+        };
+    }
+    const assessments = readAssessments(root);
+    const slots = prepared.manifest.campaign.schedule.slots.map((slot) => {
+        const assessment = assessments.find((entry) => entry.slotId === slot.slotId);
+        if (assessment === undefined) {
+            return {
+                slotId: slot.slotId,
+                caseId: slot.caseId,
+                armId: slot.armId,
+                repetitionId: slot.repetitionId,
+                expected: "unknown",
+                observed: "unrun",
+                validity: "unrun",
+                outcome: "unknown",
+                reasons: ["no assessment was recorded"],
+                counts: {},
+                usage: readUsage(root, slot.slotId),
+                judgement: judgementOf(root, slot.slotId),
+                judgeProblems: judgeProblemsOf(root, prepared.manifest, slot.slotId),
+            };
+        }
+        const observed = observedOf(assessment);
+        return {
+            slotId: slot.slotId,
+            caseId: slot.caseId,
+            armId: slot.armId,
+            repetitionId: slot.repetitionId,
+            ...observed,
+            validity: assessment.validity,
+            outcome: assessment.outcome,
+            reasons: assessment.reasons,
+            usage: readUsage(root, slot.slotId),
+            judgement: judgementOf(root, slot.slotId),
+            judgeProblems: judgeProblemsOf(root, prepared.manifest, slot.slotId),
+        };
+    });
+    const body = {
+        schemaVersion: 1,
+        campaignId: prepared.manifest.campaignId,
+        suiteId: prepared.manifest.suiteId,
+        closedAt: ledger.closedAt,
+        imageId: frozen.record.imageId,
+        generatedAt: now(),
+        denominators: {
+            scheduled: slots.length,
+            assessed: assessments.length,
+            valid: slots.filter((slot) => slot.validity === "valid").length,
+            invalid: slots.filter((slot) => slot.validity === "invalid").length,
+            unknown: slots.filter((slot) => slot.validity === "unknown").length,
+            unrun: slots.filter((slot) => slot.validity === "unrun").length,
+            judged: slots.filter((slot) => slot.judgement !== null).length,
+            unjudged: slots.filter((slot) => slot.judgement === null).length,
+        },
+        totals: {
+            pass: slots.filter((slot) => slot.outcome === "pass").length,
+            fail: slots.filter((slot) => slot.outcome === "fail").length,
+            unknown: slots.filter((slot) => slot.outcome === "unknown").length,
+        },
+        slots,
+    };
+    const report = { ...body, reportSha256: sha256Of(body) };
+    const markdown = markdownOf(report);
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, "report.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    writeFileSync(join(outDir, "report.md"), markdown, "utf8");
+    return { ok: true, report, markdown, outDir };
+}
+/** The canonical identity of a report without its own identity field. */
+export function reportIdentity(report) {
+    const body = { ...report };
+    delete body.reportSha256;
+    return sha256Of(body);
+}
+/** Ensure a report's identity still matches its content. */
+export function reportIntact(report) {
+    return reportIdentity(report) === report.reportSha256;
+}

package/docs/architecture.md

@@ -0,0 +1,106 @@
+# Architecture and extraction ownership
+
+Status: implemented 2026-11-15. Source repository:
+`markstanden/opencode-docs-plugin` @ `76ed331` (`main`, clean at review).
+Destination: this repository.
+
+## Decision
+
+Two repositories, one OTC package. The docs plugin owns the product and its
+real evaluation corpus; OTC owns the reusable lifecycle, sandbox adapters,
+evidence boundary and evaluator implementations. OTC does not depend on the
+docs plugin at runtime, and the docs plugin does not depend on OTC at runtime.
+The docs repository's development tooling pins an immutable OTC artifact.
+
+The extraction is not a directory move. The new lifecycle validates versioned
+suite/campaign data, stages immutable subject payloads, freezes the resolved
+image and CLI identity, appends an explicit ledger, separates capture validity
+from criterion outcome, and derives read-only status. Docs-specific semantics
+live only under `src/evaluators/docs`.
+
+## Why these seams
+
+- **Subject vs runtime vs suite vs campaign.** A skill-only subject must run
+  without a plugin or lake; a paired docs comparison must not force a skill
+  case into a docs schema. One discriminated contract serves both.
+- **Capture vs outcome.** A complete stream ending normally is valid evidence;
+  an activation expectation can then fail. A truncated stream, missing key or
+  failed target load is an operational unknown, never a passing negative.
+- **Trusted evaluators.** The CLI wires evaluator implementations. Campaign
+  data names an assessment kind; it never names executable JavaScript loaded
+  from evidence.
+- **Historical identity.** Old stamps, scenario ids and frozen `.mjs` bytes are
+  records. `legacy/prod014.ts` translates them without renaming. Old roots are
+  not resumed by this engine.
+
+## Source-to-destination manifest
+
+| Source (`opencode-docs-plugin` @ 76ed331)                                                               | Destination                                                                   | Class                                    |
+| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------- |
+| `tests/fixtures/placement-harness/harness.mts` (case schemas, generation, run, capture)                 | `src/contracts`, `src/campaign`, `src/adapters`                               | split + rewrite                          |
+| `.../analysis/{budget,closure,freeze,ledger,recovery,selector}.ts`                                      | `src/campaign/{ledger,freeze,close,run,assess}.ts`                            | split + rewrite                          |
+| `.../analysis/journal.ts`                                                                               | `src/evaluators/docs/journal.ts`                                              | move (bytes preserved apart from header) |
+| `.../analysis/{accounting,records,guardrails,measures,render,model,decision,pairing,bounds,closure}.ts` | `src/evaluators/docs/analysis/*`                                              | move                                     |
+| `.../analysis/screening/*`                                                                              | `src/evaluators/docs/analysis/screening/*`                                    | move                                     |
+| `.../ac/*`, `prod014/campaign/active/*`, `status.mts`                                                   | `src/legacy/prod014.ts` readers; old engine stays pinned in docs              | legacy                                   |
+| `.../Containerfile`, `container-run.sh`                                                                 | `container/Containerfile`, `src/adapters/podman`                              | rewrite                                  |
+| `.../primary-checks/*`, placement corpus, truth, measurement                                            | docs `evaluations/docs-placement/`; OTC stages and executes supplied checkers | data stays; execution moves              |
+| `.../ac-scoring.mts` judge prompt, classification, recovery policy                                      | `src/evaluators/docs/scoring.ts`, `src/campaign/judge.ts`                     | move + rewrite                           |
+| docs `src/index.ts` (metadata, ranking, collection, convention)                                         | docs `src/{metadata,ranking,collection,convention}.ts`                        | split                                    |
+| docs `src/index.ts` (lakes, publication, tools, plugin)                                                 | docs `src/lakes.ts`, `src/publication.ts`, `src/index.ts`                     | split                                    |
+
+## Dependency direction
+
+```
+cli -> campaign lifecycle -> contracts
+       |                    |
+       +-> adapters (opencode, podman, process)
+       +-> evaluators (docs, skills) -> evidence/contracts
+       +-> reporting
+legacy -> contracts only
+```
+
+`src/contracts` imports only Node built-ins. `src/evaluators/docs/journal.ts`
+imports only `node:crypto` and `node:util`. No core module imports a docs
+checkout or reads an ambient Git repository at import time.
+
+The migrated `harness/run.ts` CLI has been removed: it could spawn the docs
+repository's `tests/fixtures/placement-harness/harness.mts`, which is an active
+cross-repository engine dependency. The reusable evidence guard now lives at
+`src/campaign/evidence-guard.ts`, and the one judge-operation renderer is local
+to `src/evaluators/docs/assess.ts`. Product-supplied suites and checker bytes
+remain external data; OTC stages, hashes and executes them.
+
+## Sandbox boundary
+
+- Subject payloads are staged into `prepare/subjects/<armId>`, inventories
+  hashed, and mounted read-only at `/subjects`.
+- Case workspaces are staged once and copied per trial; only that copy is
+  writable at `/workspace`.
+- The config home (skills catalogue and `opencode.json`) is read-only at
+  `/config-home`.
+- The docs journal is the only other writable mount, and only for docs cases.
+- A product checker is staged at `prepare/primary-checks/<caseId>` and run in
+  a separate `network: "none"` container with the completed workspace and the
+  pristine workspace read-only. It is never mounted into the trial.
+- The judge runs in a neutral container with the packet read-only, a neutral
+  config home and no arm subjects, campaign manifest or evidence root. Its
+  standing-permission block comes from the pristine prepared workspace, never
+  the trial's live `AGENTS.md`.
+- Suite, campaign, manifest, truth, criteria and other slots are outside the
+  model-visible filesystem.
+- Credentials travel through a 0600 env file; argv and receipts carry names and
+  hashes only.
+- `network: "host"` is honest host networking, not provider-only egress.
+
+## Removal condition for the docs bridge
+
+The old prod014 engine remains in the docs repository, pinned to its original
+runtime and code, until an OTC campaign reaches parity on the same frozen
+evidence. It is not a second active engine: new campaigns use OTC only. The
+docs `evaluations/README.md` names the owner and the removal condition.
+
+Primary-check execution now has an OTC home; the docs repository still owns
+the checker bytes and corpus. The removal condition therefore waits on the
+docs agent repinning the new OTC artifact and, if it chooses, deleting the old
+prod014 route after its own parity check. OTC does not rewrite old roots.

package/docs/capability-matrix.md

@@ -0,0 +1,84 @@
+# Diagnosis capability matrix
+
+Status at the reconciliation head. "Parity" means the same recorded evidence
+produced identical structured analysis; permitted differences are listed
+separately.
+
+| Capability                         | Original implementation                                      | OTC implementation                                                                               | Tests                                                                             | Offline parity evidence                                                                 | Remaining owner                                               |
+| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Preparation / materialisation      | docs `harness.mts`, `prod014` materialise                    | `src/campaign/prepare.ts` (new campaigns)                                                        | OTC lifecycle/prepare/freeze tests                                                | not applicable (dispatch-side)                                                          | Docs legacy for frozen prod014 roots; OTC for new campaigns   |
+| Recording credit / journal         | docs `analysis/journal.ts`                                   | `src/evaluators/docs/journal.ts`                                                                 | OTC docs assessment tests + ported analysis tests                                 | mini + confirmation + screening exact                                                   | none                                                          |
+| Utility / opportunity counts       | docs `analysis/{accounting,measures}.ts`                     | same modules under `src/evaluators/docs/analysis`                                                | ported analysis aggregation/measures, decision-authority                          | mini utility totals (10/10, 20/20), screening 24/24                                     | none                                                          |
+| Retrieval measures                 | docs `analysis/measures.ts`, `records.ts`                    | same                                                                                             | ported measures suite + `measures-gaps` (path/lake/contradiction)                 | recorded campaigns declare no measurement spec; synthetic/contract coverage only        | OTC; real-declaration parity needs a campaign with `measures` |
+| Preservation                       | docs `analysis/{scoring,measures,guardrails}.ts`             | same                                                                                             | ported measures/guardrails/screening tests                                        | mini R02 preservation and screening findings exact                                      | none                                                          |
+| Guardrails                         | docs `analysis/guardrails.ts`                                | same                                                                                             | ported decision/guardrails tests                                                  | mini both guardrails clean; screening exact                                             | none                                                          |
+| Pairing / bounds                   | docs `analysis/{pairing,bounds}.ts`                          | same                                                                                             | ported aggregation/decision tests                                                 | mini 2 complete pairs, delta 0 [0,0]; confirmation bounds exact                         | none                                                          |
+| Screening                          | docs `analysis/screening/*`                                  | same                                                                                             | ported screening suite (rules/inventory/scan/reconcile)                           | screening campaign `SCREENING.json` byte-identical                                      | none                                                          |
+| Judge output classification        | docs `ac-scoring.mts`                                        | `src/evaluators/docs/scoring.ts` (`judgeFailureClass`, parse/validate) + `src/campaign/judge.ts` | ported ac-scoring + judge-recovery-policy + OTC judge tests                       | fresh scripted judge lifecycle; classification/recovery pure contracts exact            | none                                                          |
+| Judge recovery                     | docs `analysis/recovery.ts`, `analysis/budget.ts`            | same + OTC judge dispatch                                                                        | ported judge-recovery-policy (28 tests, concurrent ceilings) + OTC recovery tests | fresh scripted malformed-then-valid judge; selection attempt-002                        | none                                                          |
+| Primary checks / corpus generation | docs harness and `primary-checks/`                           | OTC stages and executes supplied checkers; docs owns case data, truth and checker bytes          | OTC primary tests + fresh rehearsal                                               | fresh checker pass/fail/timeout; checker never in trial payload                         | Docs product corpus ownership                                 |
+| Budgets                            | docs `analysis/{budget,closure}.ts` + campaign ledger        | migrated analysis budget/closure + OTC campaign ledger                                           | ported closure/launch-boundary + OTC lifecycle budget tests                       | exact analysis accounting/ledger sections                                               | none                                                          |
+| Selection                          | docs `analysis/selector.ts`, `recovery.ts`                   | same                                                                                             | ported recovery/selection tests                                                   | exact `assessmentSelection` in parity outputs                                           | none                                                          |
+| Closure                            | docs `analysis/closure.ts` + `close-campaign.mts`            | migrated closure + `otc close`                                                                   | ported closure tests + OTC close idempotence                                      | transaction/ledger state exact                                                          | none                                                          |
+| Reporting                          | docs `analysis/{render,measures,decision}.ts`, `analyse.mts` | migrated render/measures/decision + `otc replay`, OTC campaign report                            | ported report/integrity + OTC report tests                                        | `analysis.json`, `REPORT.md`, `SCREENING.json` exact; receipt only `renderedAt` differs | none for recorded replay; OTC campaign report separate        |
+| Status                             | docs `prod014/status.mts`                                    | `src/campaign/status.ts`                                                                         | OTC CLI/status tests                                                              | not applicable (new roots)                                                              | Docs legacy for frozen roots                                  |
+| Container / process adapters       | docs `Containerfile`, `container-run.sh`                     | `container/Containerfile`, `src/adapters/podman`                                                 | OTC adapter tests + real rehearsal                                                | real Podman/OpenCode rehearsal                                                          | none                                                          |
+| Skill activation                   | none                                                         | `src/evaluators/skills`                                                                          | OTC skill tests + real scripted rehearsal                                         | real adapter rehearsal                                                                  | none                                                          |
+
+## Fresh lifecycle capability
+
+The migrated `harness/run.ts` CLI is removed. No OTC source can spawn the docs
+repository's old `tests/fixtures/placement-harness/harness.mts`; only
+product-supplied suite, truth and checker bytes remain external data. A
+campaign can now execute the complete path without the docs repository's old
+harness:
+
+| Stage                    | OTC implementation                                | Evidence                                                        |
+| ------------------------ | ------------------------------------------------- | --------------------------------------------------------------- |
+| Validate / prepare       | `contracts/validate.ts`, `campaign/prepare.ts`    | unit + CLI tests; staged immutably                              |
+| Delivery / freeze        | `campaign/freeze.ts`                              | image ID, suite, subjects, workspaces, prompts and checkers     |
+| Trial dispatch           | `campaign/run.ts`, `adapters/{opencode,podman}`   | real Podman/OpenCode rehearsal; dry-run plan                    |
+| Product primary check    | `campaign/primary.ts`                             | separate no-network container; pass/fail/timeout/error recorded |
+| Deterministic assessment | `evaluators/{docs,skills}`                        | primary outcome folded into the docs criterion                  |
+| Blind judge              | `campaign/judge.ts`, `evaluators/docs/scoring.ts` | neutral packet; established parse/validate/failure classes      |
+| Bounded recovery         | `analysis/recovery.ts`, `analysis/budget.ts`      | one `json-syntax` retry, identical packet, durable claims       |
+| Validated selection      | `analysis/selector.ts`, `campaign/judge.ts`       | per-slot selection record checked against attempts              |
+| Closure / analysis       | `campaign/close.ts`, `reporting/report.ts`        | pending judgement and unsettled claims block closure            |
+| Status                   | `campaign/status.ts`                              | read-only counts, judgement and next actions                    |
+
+Evidence guarantees added at the repair head:
+
+- one checked-selection reader is used by judge, status, closure and reporting;
+  a readable object is not a judgement, and slot/attempt packet bytes are
+  re-hashed and reconstructed from current evidence;
+- judge and recovery claims share `<root>/evidence` as their only location and
+  both are settled by the dispatch outcome;
+- the judge's standing permission comes from the pristine prepared workspace,
+  never the trial's live `AGENTS.md`, so A/B instruction overlays stay out of
+  the packet;
+- the executing tool's artifact hash is compared with the freeze before
+  dispatch, derived from the executing module's `src`/`dist` location so
+  changed code is detected under the same package version.
+
+## Semantic parity runs
+
+All runs replay recorded evidence offline; no model call was made.
+
+| Corpus                                               | Trials | Original vs OTC                                                                                      |
+| ---------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
+| committed mini replay (`tests/fixtures/docs-parity`) | 4      | `analysis.json`, `REPORT.md`, `SCREENING.json` deep-equal; receipt equal after removing `renderedAt` |
+| recorded confirmation (`recording-confirm-20261110`) | 40     | all three artefacts byte-identical; receipt only `renderedAt`                                        |
+| recorded screening (`docs-desc-fresh-20261110`)      | 48     | all three artefacts byte-identical                                                                   |
+
+The committed parity test exercises the mini corpus in `npm test`. The two
+larger corpora were replayed manually because they total ~56 MB and are not
+committed. The frozen published `ANALYSIS-confirmation.json` uses an older
+schema and was not treated as a byte target; the comparison is between the
+original analyser at the extraction base and the OTC port on the same evidence.
+
+## Permitted differences
+
+- `renderedAt` in `analysis-receipt.json` (wall-clock).
+- Absolute evidence/manifest paths when a caller supplies a different root.
+- OTC campaign reports (`analysis`/`report`) use the new lifecycle schema; they
+  are not claimed to be byte-compatible with docs analysis reports.

package/docs/offline-rehearsal.md

@@ -0,0 +1,75 @@
+# Offline real-adapter rehearsals
+
+## Baseline (`npm run rehearse:offline`)
+
+Recorded 2026-11-15 from `npm run rehearse:offline` on the dev box.
+
+- Image: `localhost/opencode-placement-trials:latest`
+- Image ID: `sha256:58505eac2fe9161a02db4719e6a8a34e9106b644e9eee0aaa00184269b643beb`
+- OpenCode: `v2.2.6` (the tested CLI; not upgraded by this work)
+- Provider: scripted loopback OpenAI-compatible server
+- Paid provider calls: **0**
+- Scripted chat requests: **22**
+- Readiness/model-list probes: **0**
+
+| Suite  | Slot            | Validity | Observed           | Outcome | Chat requests |
+| ------ | --------------- | -------- | ------------------ | ------- | ------------- |
+| skills | positive        | valid    | target-activation  | pass    | 2             |
+| skills | negative        | valid    | no-invocation      | pass    | 1             |
+| skills | wrong-skill     | valid    | other-skill-only   | pass    | 2             |
+| skills | failed-load     | unknown  | failed-target-load | unknown | 2             |
+| skills | invalid-capture | invalid  | unrun              | unknown | 11            |
+| docs   | useful-write    | valid    | —                  | pass    | 2             |
+| docs   | gate-blocked    | valid    | —                  | pass    | 2             |
+
+Docs counts: useful write credited 1 call / 1 write; gate-blocked credited 1
+call / **0 writes**, attempted 1. Both journals verified with the per-run key.
+The truncated capture retried at the adapter level (11 HTTP requests) and is
+recorded as invalid, not as a passing negative. A failed target load is
+`unknown`, not a negative.
+
+Isolation checks: no suite, campaign, manifest or freeze file appeared in a
+trial workspace or config home; no hidden criteria string appeared in either;
+every slot made at least one provider request.
+
+This proves the machinery and the evidence boundary offline. It is **not**
+evidence of real model quality.
+
+## Fresh docs lifecycle (`npm run rehearse:fresh-docs`)
+
+Same image and scripted provider, plus the product primary check, blind judge
+and recovery path:
+
+| Slot            | Primary | Outcome | Selected attempt | Trial chat | Judge chat |
+| --------------- | ------- | ------- | ---------------- | ---------- | ---------- |
+| useful-write    | pass    | pass    | attempt-001      | 2          | 1          |
+| gate-blocked    | pass    | pass    | attempt-001      | 2          | 1          |
+| primary-failure | fail    | fail    | attempt-001      | 1          | 1          |
+| recovery        | —       | pass    | attempt-002      | 1          | 2          |
+
+The recovery's first judge attempt returned prose, the second a valid
+`none` verdict; both recorded the same `packetSha256`. The separate
+exhausted-budget root refused recovery after one judge claim, made one chat
+request and wrote no selection. The gate-blocked write kept zero credited
+writes. The checker never appeared in the trial workspace or config home.
+Post-close `run` and `judge` both exited 1; analysis after closure recorded all
+four judgements.
+
+Totals: 6 trial + 5 judge + 1 exhausted scripted chat requests, 0 readiness
+probes, 0 paid provider calls.
+
+## Installed tarball (`npm run rehearse:installed`)
+
+The checkout is packed, installed into a consumer directory whose path
+contains a space, and the same fresh docs lifecycle runs through
+`node_modules/.bin/otc`. The 2026-11-15 run used image
+`sha256:58505eac…`, OpenCode 2.2.6 and installed version `0.1.0`; it produced
+the same four-slot result, one recovery, one exhausted refusal and zero paid
+calls. The receipt records the tarball filename, SHA-256 and npm integrity;
+the exact identity is reported with the handback attestation.
+The development-only provider stays outside the tarball.
+
+The migrated `harness/run.ts` CLI is gone: it could spawn the docs
+repository's old `placement-harness/harness.mts`. The generic evidence guard
+lives at `src/campaign/evidence-guard.ts`; OTC now accepts only product data
+(suite, truth, checker bytes), never a sibling engine.