openmerit 0.1.3 → 0.1.5

package/docs/adapter-guide.md

@@ -0,0 +1,172 @@
+# Building a harness adapter
+
+OpenMerit adapters are transport bridges. They do not reproduce OpenMerit's lifecycle, validation, persistence, or Pareto rules, and OpenMerit does not reproduce the harness's intelligence.
+
+## Required components
+
+An adapter provides a `HarnessAdapter` with:
+
+- a stable harness descriptor;
+- the OpenMerit protocol versions it supports;
+- declared capabilities;
+- supported execution modes;
+- a `dispatch` method that accepts a canonical `OpenMeritIntent` and returns an acceptance receipt.
+
+```ts
+import {
+  OpenMeritCoordinator,
+  ProjectStore,
+  type HarnessAdapter,
+} from "openmerit/core";
+import { PROTOCOL_VERSION } from "openmerit/protocol";
+
+const adapter: HarnessAdapter = {
+  descriptor: {
+    id: "my-harness",
+    name: "My coding harness",
+    version: "1.0.0",
+    protocolVersions: [PROTOCOL_VERSION],
+    capabilities: [
+      "user_confirmation",
+      "evaluation_authoring",
+      "observability_instrumentation",
+      "production_observation",
+      "candidate_discovery",
+      "challenger_execution",
+      "frontier_calculation",
+      "model_mutation",
+      "post_swap_verification",
+      "rollback",
+    ],
+    executionModes: ["interactive"],
+  },
+  async dispatch(intent) {
+    await myHarness.enqueue(intent);
+    return { accepted: true, harnessJobId: intent.id };
+  },
+};
+
+const coordinator = new OpenMeritCoordinator(
+  new ProjectStore(process.cwd()),
+  adapter,
+);
+```
+
+`ProjectStore` is the included local-filesystem backend. A remote or hosted integration can implement the `OpenMeritStore` interface instead.
+
+## External telemetry export
+
+OpenMerit always writes its canonical, redacted audit stream locally. A host integration may pass `eventExporters` to `ProjectStore` to mirror those same safe events to OpenTelemetry, Langfuse, LangSmith, or another observability backend:
+
+```ts
+const store = new ProjectStore(projectRoot, {
+  eventExporters: [{
+    id: "my-otel-bridge",
+    async export(event) {
+      await telemetry.emit("openmerit.audit", event);
+    },
+  }],
+});
+```
+
+Exporters are not the durable source of truth. They are best effort, and failures are recorded locally without blocking OpenMerit decisions.
+
+## Dispatching work
+
+```ts
+const issued = await coordinator.issue("establish_evals");
+```
+
+The coordinator builds the canonical intent, checks the descriptor's protocol and capabilities, creates durable state, records audit events, and calls the adapter. The harness decides how to execute the job.
+
+If a required capability is absent, dispatch is rejected before harness work starts.
+
+## Reporting progress
+
+A harness may send durable lifecycle progress through `recordLifecycle`:
+
+```ts
+await coordinator.recordLifecycle({
+  protocolVersion: PROTOCOL_VERSION,
+  intentId: issued.intent.id,
+  status: "running",
+  occurredAt: new Date().toISOString(),
+  message: "Generating representative evaluation cases",
+});
+```
+
+Use `waiting_for_user` when an interactive confirmation is required but cannot be completed in the current execution mode.
+
+## Completing work
+
+Each intent kind has a typed output in `IntentOutputMap`. Return an `IntentResult<K>` with durable evidence references, then submit it to the coordinator:
+
+```ts
+await coordinator.acceptResult(result);
+```
+
+The coordinator validates the active intent, version, evidence, intent-specific output, frontier conformance, mutation authorization, and lifecycle transition. Adapters must not duplicate this logic.
+
+### Present the canonical result schema
+
+Import `completionToolSchemaFor(intent.kind)` from `openmerit/protocol` and present it through the harness's strongest structured-output mechanism. Do not recreate result schemas inside an adapter. A harness that supports changing tool definitions should specialize the completion tool whenever an intent becomes active; other harnesses may expose intent-specific tools or perform adapter-side validation.
+
+Declare the behavior in `HarnessDescriptor.structuredOutput`:
+
+- `schemaDialect` identifies the canonical OpenMerit JSON Schema dialect;
+- `presentation` states whether the adapter uses a dynamic tool, a static union, or adapter validation;
+- `enforcement` states whether validation occurs at the provider and harness, harness only, or adapter only.
+
+Schema validation catches malformed structure. The coordinator still owns semantic checks such as authorized candidate identity, evidence sufficiency, lifecycle consistency, and Pareto conformance.
+
+## Reporting normal work and catalogue changes
+
+After a real product task completes:
+
+```ts
+const observation = await coordinator.recordTaskObservation({
+  modelId: "vendor/model",
+});
+
+if (observation.assessmentDue) {
+  await coordinator.issue("run_assessment");
+}
+```
+
+When the harness's available model catalogue changes, compute a stable fingerprint and call `recordModelCatalogFingerprint`. The returned `reassessmentDue` flag tells the adapter whether the lifecycle justifies candidate discovery.
+
+New adapters should use `recordAutomationSignal` for product tasks, metric windows, scheduled ticks, catalogue observations, and verification windows. Signal IDs must remain stable across delivery retries. If the returned decision issues an intent, dispatch it through the coordinator. `recordTaskObservation` and `recordModelCatalogFingerprint` remain compatibility helpers.
+
+Call `reconcileAutomation` after configuration changes or when restoring a project. It returns an `AutomationPlan`. Implement `scheduleWakeup` only when the harness can genuinely arrange the requested wakeup. Declare persistent scheduling, background execution, supported signal sources, and provisioning requirements accurately in `HarnessDescriptor.automation`.
+
+If persistent scheduling is unavailable, expose the plan's active-session or external-scheduler fallback. Do not report a seven-day schedule as configured merely because the adapter checks policy when an interactive session starts.
+
+## Capability mapping
+
+| Intent | Required capability |
+| --- | --- |
+| `establish_evals` | confirmation, evaluation authoring, observability instrumentation |
+| `instrument_observability` | observability instrumentation |
+| `run_assessment` | production observation |
+| `discover_candidates` | candidate discovery |
+| `run_challenger_trials` | challenger execution |
+| `calculate_frontier` | frontier calculation |
+| `investigate_regression` | production observation |
+| `apply_model_swap` | model mutation |
+| `verify_model_swap` | post-swap verification |
+| `rollback_model_swap` | rollback |
+
+## Conformance checklist
+
+An adapter is ready when it:
+
+1. advertises only capabilities it can actually execute;
+2. preserves intent IDs and protocol versions;
+3. never reports success without durable evidence;
+4. returns the typed output for every supported intent;
+5. performs model mutation only when the intent explicitly authorizes it;
+6. reports ordinary product tasks without counting OpenMerit orchestration turns;
+7. passes a durable issue-and-complete cycle using `OpenMeritCoordinator`;
+8. proves the requested side effect, not merely a generated description.
+
+The fake non-Pi adapter in `packages/core/test/adapter-conformance.test.ts` is the executable reference.

package/docs/architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+## Design principle
+
+OpenMerit is an orchestrator, not an intelligence layer.
+
+```text
+User or lifecycle event
+        |
+        v
+OpenMerit deterministic orchestration
+        |
+        | typed intent: outcome, constraints, evidence
+        v
+Coding harness such as Pi
+        |
+        | intelligent work, tools, evals, calculation
+        v
+Typed result and durable evidence references
+        |
+        v
+OpenMerit validation, policy, persistence, next nudge
+```
+
+An automatic OpenMerit action means automatic issuance of an approved intent. OpenMerit does not perform candidate research, evaluate quality, calculate a frontier, or mutate model configuration.
+
+## Packages
+
+### `openmerit/protocol`
+
+Defines the JSON-safe boundary: durable intents, evidence references, metrics, task profiles, candidate assessments, frontier snapshots, budgets, policies, state, and audit events.
+
+It also owns the versioned runtime schema registry for all intent results. Harness adapters consume these schemas rather than defining their own result shapes, report their structured-output capabilities, and may present the active schema using harness-native tools or adapter validation.
+
+### `openmerit/core`
+
+Contains deterministic behavior: choosing the next lifecycle intent, persisting state, checking harness-produced frontiers against the normative definition, and enforcing confirmation or rollback policy. The verifier rejects invalid harness results; it is not a model-selection engine.
+
+`OpenMeritCoordinator` is the reusable adapter boundary. It constructs canonical intents, negotiates capabilities, records lifecycle progress and observations, validates results, and advances durable state. `OpenMeritStore` makes persistence replaceable; `ProjectStore` is the bundled filesystem backend.
+
+The coordinator also accepts idempotent automation signals and evaluates the user-confirmed `AutomationCheckPolicy`. `buildAutomationPlan` tells an adapter which signals and wakeups are required and reports unsupported persistent scheduling honestly. OpenMerit never installs a scheduler or creates a paid cloud worker itself.
+
+### `openmerit/pi`
+
+Exposes the command surface, supplies private typed intent context, triggers Pi, accepts one structured completion for the active intent, records evidence, advances the lifecycle, and detects model-catalog changes.
+
+The Pi package implements `HarnessAdapter`. It does not define canonical intents, per-intent result contracts, stage transitions, or validation rules.
+
+## Intelligence resources
+
+Models, web research, tools, evaluators, and fast decision systems such as Jev System One are harness resources. They are configured and invoked by Pi. This keeps OpenMerit provider-neutral and lets future adapters choose their own implementation.
+
+## Trust boundary
+
+The harness is trusted to perform the work and return honest evidence. OpenMerit reduces unsupported claims through structured outputs, evidence references, compatible profile revisions, complete comparisons, and conservative uncertainty handling. It cannot prove that an arbitrary external evidence URI contains truthful data.

package/docs/automation.md

@@ -0,0 +1,66 @@
+# Harness-neutral automation
+
+The user defines cadence, thresholds, budget, scheduling mode, and automation permission. OpenMerit stores that policy, evaluates durable signals, and decides whether a bounded intent is due. A harness adapter arranges native wakeups and reports events. The coding harness performs the resulting intelligent work.
+
+```text
+User-confirmed policy
+        ↓
+OpenMerit due-check engine
+        ↓
+Harness-native wakeup or lifecycle hook
+        ↓
+Standard automation signal
+        ↓
+No work due, or one typed OpenMerit intent
+```
+
+## Check policy
+
+`AutomationCheckPolicy` independently configures:
+
+- baseline assessment cadence;
+- frontier reassessment cadence and catalogue-change behavior;
+- regression-check cadence and per-metric relative deterioration thresholds;
+- post-swap verification windows;
+- a cooldown between mature-system checks;
+- active-session or persistent execution;
+- whether wakeup provisioning may make infrastructure changes.
+
+Task-count and elapsed-time triggers use OR semantics. A policy with `afterCompletedTasks: 100` and `afterElapsedSeconds: 604800` becomes due at the first threshold reached. A scheduled wakeup does not directly launch expensive work: it submits `scheduled_tick`, and OpenMerit evaluates policy and durable state before issuing an intent.
+
+## Signals
+
+Adapters may report:
+
+- `product_task_completed`;
+- `metric_window_available`;
+- `scheduled_tick`;
+- `model_catalog_changed`;
+- `verification_window_completed`.
+
+Signal IDs are idempotency keys. OpenMerit persists a bounded history, does not count duplicate task completions twice, and keeps due work pending until an adapter successfully dispatches it.
+
+## Capability negotiation
+
+Every `HarnessDescriptor` declares supported signals, persistent scheduling, background execution, and whether wakeup provisioning is native, unavailable, or requires an infrastructure change. OpenMerit produces an `AutomationPlan` containing required signals, the next wakeup, scheduling strategy, and explicit gaps.
+
+If persistent scheduling is requested but unsupported, the plan says `external_scheduler_required`. The adapter must not claim that a schedule exists. Active-session adapters can submit `scheduled_tick` when they start. An external scheduler may also wake a non-interactive harness and submit the same signal.
+
+OpenMerit calls `scheduleWakeup` only when the confirmed policy requests persistent execution, the adapter declares persistent scheduling and background execution, and any infrastructure-changing provisioning has been authorized. Paid agents, system scheduler installation, and cloud infrastructure remain harness implementation details and authorization boundaries.
+
+## Intent mapping
+
+OpenMerit owns deterministic mapping from due conditions to intents:
+
+| Due condition | Intent |
+| --- | --- |
+| Baseline cadence | `run_assessment` |
+| Mature frontier cadence or changed catalogue | `discover_candidates` |
+| Regression cadence or crossed metric threshold | `investigate_regression` |
+| Completed post-swap window | `verify_model_swap` |
+
+Subsequent lifecycle transitions continue through candidate trials, frontier calculation, supervised swap, verification, or rollback. The harness executes those intents; OpenMerit validates their structured result and evidence.
+
+## Pi behavior
+
+Pi reports catalogue and scheduled-tick signals on session start and product-task signals after ordinary settled turns. Its typed `openmerit_report_signal` tool accepts verified metric and post-swap windows from eval or observability work. Pi cannot currently provision persistent background wakeups, so its descriptor says so. A persistent policy therefore produces an external-scheduler gap instead of a false success claim. A Pi-compatible scheduler can start Pi non-interactively; Pi then submits the tick and OpenMerit decides whether work is due.

package/docs/getting-started.md

@@ -0,0 +1,55 @@
+# Getting started
+
+## Prerequisites
+
+- Node.js 22.19 or newer.
+- npm.
+- Pi 0.87-compatible provider authentication.
+- A product repository in which Pi can create and verify evaluation and observability artifacts.
+
+OpenMerit does not require or accept an LLM provider credential. Provider access belongs to the coding harness.
+
+## Install from npm
+
+```sh
+pi install npm:openmerit
+pi list
+```
+
+Run `/openmerit doctor` inside Pi to confirm that the extension is available.
+
+## Install from source
+
+```sh
+git clone https://github.com/laz-aslam/openmerit.git
+cd openmerit
+npm ci
+```
+
+Start Pi with the extension:
+
+```sh
+./node_modules/.bin/pi -e ./packages/pi/src/index.ts
+```
+
+Run `/openmerit doctor` inside Pi to confirm that the adapter and intent executor are available.
+
+## Establish a product profile
+
+Open the product repository in interactive Pi with the extension loaded. If the project has no OpenMerit state, setup begins automatically. `/openmerit setup` is only needed to explicitly rerun or recover setup.
+
+OpenMerit sends Pi a private, typed `establish_evals` intent. Pi must understand the product task, infer objectives, ask the user to confirm requirements, an evaluation budget, check cadence, thresholds, scheduling mode, and automation permissions, create and verify the necessary infrastructure, and complete the intent with durable evidence.
+
+OpenMerit rejects successful setup without a confirmed task profile, at least one valid objective, a supervised-graduation policy, a budget, and evidence.
+
+## Collect the baseline
+
+After setup, use Pi normally. OpenMerit records completed-task checkpoints without treating its own orchestration turn as product evidence. At the required sample threshold, OpenMerit nudges Pi to assess the baseline. Missing evidence is not treated as zero or failure.
+
+## Find the frontier
+
+When Pi reports a sufficient baseline, OpenMerit issues the next approved nudges: discover candidates, run controlled challenger trials, and calculate the Pareto frontier. Pi performs the work. OpenMerit checks the returned result against the [Pareto specification](pareto-spec.md).
+
+## Approve an early swap
+
+During supervised graduation, a verified model proposal pauses for `/openmerit approve`. That authorizes Pi to apply only the proposed change. OpenMerit then requires post-swap verification; the approved policy determines rollback behavior.

package/docs/lifecycle.md

@@ -0,0 +1,30 @@
+# Improvement lifecycle
+
+## Stages
+
+1. **Unconfigured** — no confirmed profile exists.
+2. **Establishing evidence** — Pi creates and verifies evals and observability.
+3. **Collecting baseline** — normal product work accumulates evidence.
+4. **Baseline ready** — Pi establishes sufficiency for every required objective.
+5. **Discovering candidates** — Pi researches credible candidates within budget.
+6. **Running challenger trials** — Pi runs comparable controlled trials.
+7. **Calculating frontier** — Pi calculates and explains the Pareto frontier.
+8. **Frontier ready** — OpenMerit verifies the returned snapshot.
+9. **Approval or swap** — policy decides whether confirmation is required.
+10. **Verifying swap** — every applied change receives post-swap evaluation.
+11. **Monitoring** — production evidence continues to accumulate.
+12. **Rollback** — a covered regression restores the prior verified route.
+
+## Event-driven nudges
+
+OpenMerit remains quiet when no action is justified. On first interactive entry to an unconfigured product, it automatically nudges Pi to establish the user-confirmed profile, evals, observability, check policy, and automation permission. Later nudges become due when durable harness signals satisfy the configured task-count or elapsed-time cadence, a metric crosses a regression threshold, the model catalogue changes under an enabled policy, a post-swap window completes, an intent enables the next stage, rollback policy covers a regression, or the user invokes a command.
+
+Every signal has an idempotency key. A due intent is persisted before dispatch so duplicate webhooks, restarts, and retrying adapters do not double-count tasks or silently lose pending work.
+
+## Evaluation budget
+
+Candidate work can cost money but is bounded by the confirmed policy. The contract can constrain currency, spend, candidate count, runs per candidate, and expiration. Pi decides how to work within those limits and must return evidence.
+
+## Supervised graduation
+
+Early proposals wait for `/openmerit approve`. A policy may enable bounded automatic swaps only after the configured number of verified swaps. Post-swap verification remains mandatory.

package/docs/metrics-and-evidence.md

@@ -0,0 +1,40 @@
+# Metrics and evidence
+
+## Task-specific profiles
+
+The full catalogue is available to every product, but a confirmed task profile selects required metrics, direction, minimum sample count, tolerance, and optional hard constraints.
+
+## Initial metric catalogue
+
+Quality and behavior: task quality, task success, consistency, instruction following, tool-use performance, structured-output reliability, hallucination rate, reasoning efficiency, recovery ability, context handling, retrieval-use quality, long-horizon performance, and preference fit.
+
+Cost and resources: input tokens, output tokens, total task cost, cost per successful task, and agent steps.
+
+Latency and operations: time to first useful output, end-to-end latency, throughput, retry rate, and human-intervention rate.
+
+## Metric states
+
+- `measured` — numeric value and evidence exist.
+- `not_applicable` — the metric does not apply.
+- `not_configured` — collection or evaluation is missing.
+- `insufficient_evidence` — relevant, but without enough representative samples.
+
+Missing measurements are never converted to zero.
+
+## Single and repeated runs
+
+A single execution can report its cost, latency, token use, steps, success, and evaluator score. Distribution and reliability claims require repeated runs: rates, consistency, variance, averages, percentiles, throughput, prompt sensitivity, and regression stability.
+
+Two forms of repetition may be needed: repeat the same input to measure stochastic variance, and run representative task instances to measure general task performance.
+
+## Evidence references
+
+Results point to durable evidence rather than embedding arbitrary traces. Sources include harness traces, evaluation artifacts, observability records, external sources, and user feedback. References may contain a URI, media type, and digest. Successful intents require evidence; frontier certification also requires calculation evidence and exact assessment IDs.
+
+## Readiness contract
+
+Setup must return an explicit observability coverage report containing every required metric, which metrics are covered, which remain missing, and when the check occurred. OpenMerit derives readiness from those sets; a harness cannot label coverage `ready` while a required metric is absent.
+
+If setup reports a required gap, OpenMerit issues `instrument_observability`. A successful instrumentation result is accepted only when every required metric is covered. This prevents a configured task profile from being mistaken for working telemetry.
+
+Product instrumentation and OpenMerit auditing are separate. The product emits measurements such as quality, success, tokens, cost, latency, retries, tool calls, and intervention. OpenMerit records the signals, policy decision, intent lifecycle, evidence identifiers, and readiness or frontier decision that followed.

package/docs/operations.md

@@ -0,0 +1,31 @@
+# Project state and operations
+
+## State location
+
+Operational data lives under `.openmerit/` in the target product repository. It should be ignored by version control because it can contain local lifecycle state and evidence locations.
+
+- `config.json` — task profiles and policy.
+- `state.json` — current cycle, active or pending intent, last result, explicit observability coverage, processed signal IDs, task counters, metric baselines, catalogue fingerprint, and assessment/swap checkpoints.
+- `events.jsonl` — append-only audit events.
+- `audit-export-errors.jsonl` — failures from optional external event exporters; these failures never replace or erase the canonical local event.
+- `evidence/*.json` — evidence-reference manifests.
+
+Snapshot writes are atomic. Files use owner-only permissions where POSIX modes are supported.
+
+## Diagnostics
+
+Start with `/openmerit status`, which reports profile, metric and evaluation readiness, active work, next assessment, lifecycle, and pause state. `/openmerit doctor` confirms adapter loading without printing secrets.
+
+`/openmerit pause` stops proactive nudges for the current process; explicit commands still work. `/openmerit resume` re-enables them.
+
+`/openmerit logs` prints the exact local paths to the audit log, exporter failures, evidence manifests, and current state. During an end-to-end run, `tail -f .openmerit/events.jsonl | jq .` shows signals and decisions as they occur.
+
+## Audit and recovery
+
+OpenMerit records initialization, intent requests and completions, automation signals and duplicates, due checks, task checkpoints, catalogue changes, frontier validation, confirmation boundaries, and lifecycle advancement.
+
+Automation-signal records include safe measurement summaries: model ID and token context for completed tasks; or metric ID, state, scope, direction, method, value, unit, sample count, interval/window, and evidence IDs for metric windows. Intent completions record their kind, status, next stage, harness, summary, and evidence IDs/sources. Secret-shaped keys and common API-key patterns are redacted before local persistence or export.
+
+The local JSONL file is the canonical source of truth. `ProjectStore` can also receive optional event exporters for OpenTelemetry or vendor-specific adapters. Export is best effort: a failed exporter is written to `audit-export-errors.jsonl` and does not interrupt lifecycle state or canonical logging.
+
+If Pi stops during an intent, durable state retains it. Inspect `state.json` and `events.jsonl` before manual changes. Deleting `.openmerit/` discards the audit trail, budget, profile, and evidence references.

package/docs/pareto-spec.md

@@ -0,0 +1,76 @@
+# OpenMerit Pareto conformance specification
+
+Status: initial normative specification
+
+OpenMerit owns this definition. A connected harness performs the calculation, returns a `FrontierSnapshot`, and supplies calculation evidence. OpenMerit verifies the returned result against these rules.
+
+## Comparable assessment set
+
+Every assessment in one frontier calculation must share:
+
+- task-profile ID and revision;
+- product revision;
+- harness identity and materially equivalent tool configuration;
+- objective definitions, units, and directions;
+- a representative evaluation workload and compatible evidence window.
+
+The harness must not silently compare measurements from incompatible conditions.
+
+## Metric readiness
+
+A required objective is ready only when:
+
+- a metric record exists;
+- its state is `measured`;
+- it has a numeric value;
+- its sample count meets the objective's minimum;
+- its unit and direction are compatible across candidates.
+
+Missing or immature evidence is `unresolved`. It is never converted to zero and never treated as success.
+
+## Feasibility
+
+Hard constraints are evaluated conservatively against uncertainty intervals. If an interval is absent, the point value is both bounds.
+
+- `at_least`: eligible only when the lower bound meets the threshold; ineligible when the upper bound is below it; otherwise unresolved.
+- `at_most`: eligible only when the upper bound meets the threshold; ineligible when the lower bound exceeds it; otherwise unresolved.
+
+Only eligible candidates may be certified as members of the frontier.
+
+## Dominance
+
+For candidate A to dominate candidate B, A must be proven no worse than B on every objective and proven materially better on at least one objective.
+
+For a maximize objective with tolerance `t`:
+
+- A is proven no worse when `A.lower + t >= B.upper`.
+- A is proven materially better when `A.lower > B.upper + t`.
+
+For a minimize objective with tolerance `t`:
+
+- A is proven no worse when `A.upper <= B.lower + t`.
+- A is proven materially better when `A.upper + t < B.lower`.
+
+If complete evidence proves A worse on any objective, A does not dominate B. If the evidence cannot establish no-worse or worse because intervals overlap, the comparison is unresolved.
+
+## Frontier
+
+An eligible candidate is on the certified frontier when:
+
+- no eligible candidate is proven to dominate it; and
+- none of its required pairwise comparisons is unresolved.
+
+Candidates with incomplete evidence, unresolved constraints, or unresolved comparisons are reported separately. A dominated, ineligible, or unresolved candidate must not appear on the certified frontier.
+
+## Required result evidence
+
+Every frontier result must include:
+
+- the assessment IDs used;
+- all directed pairwise comparisons between eligible candidates;
+- reasons for every comparison;
+- separate frontier, dominated, ineligible, and unresolved sets;
+- at least one durable calculation-evidence reference.
+
+The calculation evidence should identify the harness execution or artifact that produced the result.
+

package/docs/pi-extension.md

@@ -0,0 +1,44 @@
+# Pi extension
+
+## Supported version
+
+The adapter targets Pi 0.87 and declares `>=0.87.0 <0.88.0`. Development uses 0.87.0 without modifying a globally installed Pi.
+
+## Loading
+
+Install the published package with `pi install npm:openmerit`. For development
+from a checkout, load the source extension with:
+
+```sh
+./node_modules/.bin/pi -e ./packages/pi/src/index.ts
+```
+
+Use `/openmerit doctor` to confirm that the adapter and intent executor are available.
+
+Use `/openmerit logs` to locate the project-local audit stream, exporter failures, evidence manifests, and state while testing an end-to-end run.
+
+On `session_start`, an interactive unconfigured project automatically receives one `establish_evals` intent. Durable active-intent state prevents the setup nudge from being reissued on every session. Non-interactive runs do not attempt a confirmation flow; `/openmerit setup` remains an explicit recovery command.
+
+For configured projects, session start reports the current model catalogue and a scheduled tick. Ordinary settled product work reports an idempotent completed-task signal. OpenMerit evaluates the confirmed policy before issuing work. Pi currently declares no persistent scheduling or background execution, so persistent policies require an external scheduler to start Pi; the adapter reports that gap explicitly.
+
+Pi also exposes `openmerit_report_signal` for verified `metric_window_available` and `verification_window_completed` events. Evals or observability work performed by Pi can submit measured metric records through this typed ingress using stable signal IDs. This does not create a background scheduler; it gives the active harness a validated way to connect the infrastructure it built to OpenMerit's due-check engine.
+
+## Intent delivery
+
+The extension persists each intent as a custom Pi session entry, sends private extension-authored context with `display: false`, and triggers a follow-up Pi turn. The intent describes the outcome, constraints, evidence, task profile, and authorization boundary without prescribing Pi's method.
+
+Pi must finish by calling `openmerit_complete_intent` exactly once. Success without evidence is rejected. Setup, assessment, and frontier intents receive additional structured-output checks.
+
+The extension replaces the completion tool definition whenever an intent becomes active. Its `outputs` property therefore exposes the canonical schema for that exact intent instead of untyped JSON. Pi validates the arguments before execution and requests provider-side JSON Schema constrained sampling when supported. OpenMerit validates the canonical schema and semantic rules again when accepting the result.
+
+## Model changes
+
+The extension does not use Pi's model setter as a substitute for harness work. After policy authorization, it sends a bounded `apply_model_swap` intent. Pi performs the change and returns configuration proof.
+
+## Jev System One
+
+Jev is not integrated into OpenMerit. If configured in Pi, the intent asks Pi to use harness-configured fast decision resources aggressively for bounded ranking, triage, and judgment. Credentials remain outside OpenMerit.
+
+## Non-interactive modes
+
+A harness must not attempt interactive confirmation in a mode without dialog-capable UI. It should return a waiting-for-user or failed result with an actionable reason.

package/docs/roadmap.md

@@ -0,0 +1,26 @@
+# Current limitations and roadmap
+
+## Current status
+
+OpenMerit is ready for an initial supervised product trial with Pi. Its protocol, lifecycle, persistence, metric catalogue, frontier verifier, and Pi adapter are implemented and tested. That is not evidence that it optimizes every product; each target workload requires its own profile and representative evaluations.
+
+## Known limitations
+
+- No second harness adapter exists.
+- Jev must be configured and invoked by the harness; OpenMerit intentionally provides no client.
+- Generic Pi task checkpoints do not replace product telemetry. Setup must create the infrastructure required by the profile.
+- Pi reports active-session signals and typed metric windows but cannot provision persistent background wakeups; persistent policies require an external scheduler until a capable adapter is added.
+- Pause state is process-local rather than persisted.
+- External evidence authenticity depends on the referenced system.
+- The core and protocol workspaces are private; the single `openmerit` npm
+  package exposes their public entry points.
+
+## Next validation milestones
+
+1. Run setup in one representative product.
+2. Verify generated eval and observability artifacts and their side effects.
+3. Collect repeated evidence for the confirmed profile.
+4. Complete a budgeted A/B/C challenger cycle.
+5. Validate the harness-calculated frontier and recommendation.
+6. Perform a supervised swap, post-swap verification, and rollback drill.
+7. Repeat with a materially different product task before broad readiness claims.

package/docs/security.md

@@ -0,0 +1,23 @@
+# Security
+
+## Credential ownership
+
+OpenMerit accepts no model-provider or Jev credential. Credentials belong to the coding harness, its environment, or an external secret store.
+
+Never place secrets in profiles, policies, intent constraints, summaries, evidence URIs, audit events, fixtures, traces, or committed environment files.
+
+## Mutation authorization
+
+Most intents carry `modelMutationAllowed: false`. Only apply-swap and rollback intents can authorize a mutation, limited to the active proposal. Early swaps require confirmation; automatic swaps require explicit policy opt-in and sufficient verified history. Every swap requires verification.
+
+Persistent wakeup provisioning is a separate authorization boundary. An adapter that needs to install a system scheduler, create a paid cloud agent, or change infrastructure must declare `wakeupProvisioning: "infrastructure_change"`; OpenMerit will not request that provisioning unless the confirmed check policy sets `infrastructureChangesAllowed: true`.
+
+## Local state
+
+`.openmerit/` may reveal task names, candidate identifiers, evidence locations, budgets, or model choices. Treat it as sensitive project metadata even though it must not contain credentials.
+
+## Evidence integrity
+
+OpenMerit validates structure and deterministic Pareto conformance, not the truth of arbitrary external evidence. Use authenticated observability, immutable artifacts, and digests where stronger provenance is required.
+
+Do not include credentials, private traces, or proprietary evaluation data in public issues.