open-multi-agent-kit 0.90.5 → 0.90.6

package/docs/correctness-wall.md

@@ -0,0 +1,117 @@
+# Correctness Wall (B2C patch safety harness)
+
+## Purpose
+
+The **Correctness Wall** is a **policy- and evidence-limited screen** for AI-proposed patches in OMK. It runs **before** `edit` / `write` apply (via the `correctness-wall` extension) or on demand through the `correctness_wall_evaluate` tool.
+
+It helps answer:
+
+- Are changed paths inside an **approved write scope**?
+- Does the diff look like it may contain **secrets**?
+- When run evidence exists, does **outcome adjudication** corroborate success?
+
+It does **not** prove that code is correct, complete, or safe for production.
+
+## 4-state user verdict
+
+| Verdict | Meaning (default apply behavior) |
+|---------|----------------------------------|
+| **PASS** | Fast wall (and optional OA) found no blocking issues. |
+| **ADVISORY** | Proceed with caution; preview limits or weak discrimination may apply. |
+| **INCONCLUSIVE** | Not enough evidence (empty diff, missing fixture, verifier error). |
+| **BLOCKED** | Scope, secret heuristic, or OA contradiction — do not apply by default. |
+
+Structured next steps on the verdict card: **Apply**, **Deep Check**, **Regenerate** (see `packages/adaptorch-wpl` B2C mapper).
+
+**Can apply** vs **should submit** are separate gates on the verification receipt: mechanical apply safety is not the same as trusting downstream submission.
+
+## Fast wall vs deep wall
+
+- **Fast wall (default):** Pure policy — diff paths, scope globs, secret-shaped lines, preview-only limits (`BATCH1_NO_DOCKER_RUNNER`). No Docker runner in batch 1.
+- **Deep wall (Pro / future):** Hermetic paired base/patch replay. Today `deepWall: true` returns **unavailable** with the same batch-1 limit code.
+
+## Relationship to Adaptorch
+
+- Hidden engine: `omk-adaptorch-wpl` (`evaluateCorrectnessWall`, outcome adjudicator, repair hints).
+- Optional OA path: `runIds` + `previewOnly: false` + in-memory or MCP transport.
+- Adaptorch **preview** planning is separate; see [adaptorch-preview.md](./adaptorch-preview.md).
+
+## Operator environment
+
+```bash
+omk --extension packages/coding-agent/examples/extensions/correctness-wall/index.ts
+```
+
+| Variable | Role |
+|----------|------|
+| `OMK_PATCH_SAFETY_WALL_MODE` | `shadow` (default), `soft`, `hard` |
+| `OMK_WALL_SCOPE` | Comma-separated path globs |
+| `OMK_WALL_OVERRIDE` | Soft-mode override for BLOCKED |
+| `OMK_WALL_REPAIR_BUDGET` | Capped regenerate hints (default 1) |
+| `OMK_WALL_OA_FIXTURE_PATH` | JSON fixture for local OA adjudication |
+| `OMK_WALL_AUTO_REGENERATE` | Capped `regeneratePacket` in tool JSON (hints only) |
+| `OMK_WALL_RECEIPT_SIGNING_SECRET` | Optional HMAC `signedReceipt` on verification receipt |
+| `OMK_WALL_DEEP_PHASE` | `stub` (default) or `docker` (intent only; runner not wired) |
+| `OMK_WALL_OA_TRANSPORT` | `fixture` (default) or `mcp` / `live` (session `callTool` injection) |
+
+Telemetry (no diff bodies): `.omk/wall-cache/latest.json`, `shadow-telemetry.ndjson`, `repair-budget.json`.
+
+## Explicit non-goals
+
+- **Not proof of correctness** or formal verification.
+- Does not replace human review, CI, or full `npm run check` / test suites.
+- Does not expose internal thresholds, AST overlap, or raw repro bodies to end users.
+
+## Loadout & preset
+
+The correctness wall is **not** part of the default `omk-core-verified` preset or any built-in role loadout in `packages/coding-agent/src/core/loadouts.ts`. Operators opt in explicitly:
+
+| Surface | How to enable |
+|---------|----------------|
+| **Session** | `omk --extension packages/coding-agent/examples/extensions/correctness-wall/index.ts` (or a copy under `~/.omk/agent/extensions/correctness-wall/`) |
+| **Scope** | `OMK_WALL_SCOPE` — comma-separated path globs that approve write targets in the diff |
+| **Mode** | `OMK_PATCH_SAFETY_WALL_MODE` — `shadow` \| `soft` \| `hard` (see [Operator environment](#operator-environment)) |
+| **Role loadouts** | `code` / `executor` lanes still get `pre-shell-guard`, `protect-secrets`, and `typecheck-after-edit`; the wall **adds** a pre-apply policy gate on `edit` / `write` only when the extension is loaded |
+| **Domain router** | No dedicated domain profile today; patch-safety work may route to [`ai-agent-ops`](./loadout-domains/ai-agent-ops.md) for harness/eval discipline, but that does **not** auto-load this extension |
+
+**Future hook (code, not batch-1):** `packages/coding-agent/src/core/domain-loadouts.ts` could gain triggers (e.g. `patch safety`, `correctness wall`) and a curated extension entry pointing at the correctness-wall example. Until then, document-only reference — do not hand-edit auto-generated files under `docs/loadout-domains/`.
+
+Regression coverage for the wall library surface lives in `packages/coding-agent/test/suite/regressions/018-b2c-correctness-wall.test.ts` (imports `omk-adaptorch-wpl` the same way the extension does).
+
+## Recommended rollout: shadow → soft → hard
+
+Roll out in **three phases** so telemetry and false positives are understood before writes are blocked.
+
+| Phase | `OMK_PATCH_SAFETY_WALL_MODE` | Operator expectation |
+|-------|------------------------------|--------------------|
+| **1 — Shadow** | `shadow` (default) | All `edit` / `write` calls proceed. Verdicts land in `.omk/wall-cache/latest.json` and `shadow-telemetry.ndjson`. Review BLOCKED/INCONCLUSIVE rates and tune `OMK_WALL_SCOPE`. |
+| **2 — Soft** | `soft` | **BLOCKED** verdicts block apply unless `OMK_WALL_OVERRIDE=1` (or `true` / `yes`). **INCONCLUSIVE** still applies in shadow-like fashion for scope tuning. Use for pilot teams with an explicit override path. |
+| **3 — Hard** | `hard` | **BLOCKED** and **INCONCLUSIVE** both block `edit` / `write`. Reserve for repos with stable scope globs, OA fixtures wired (`OMK_WALL_RUN_IDS` + `OMK_WALL_OA_FIXTURE_PATH`), and acceptable INCONCLUSIVE rate (missing files, empty diff). |
+
+**Checklist between phases**
+
+1. AC-1 vitest green for `packages/adaptorch-wpl` and regression `018-b2c-correctness-wall`.
+2. Root `npm run check` green after any source touch (includes unrelated **browser-smoke** esbuild gate — wall work does not require loading the extension in that script).
+3. Shadow NDJSON reviewed: no systematic secret false negatives; scope globs cover intended packages only.
+4. Document team override policy before enabling **soft**.
+
+## Wave 2 / Wave 3 roadmap (pointer)
+
+Goal orchestration v2 artifacts (planner P3) live beside batch-1 plan files:
+
+| Artifact | Path |
+|----------|------|
+| 11-step evaluation algorithm + decision table | `.omk/goals/b2c-correctness-wall-2026-07-08/algorithm-v2.md` |
+| Three-wave execution DAG (JSON) | `.omk/goals/b2c-correctness-wall-2026-07-08/dag-v2.json` |
+| Explorer: browser-smoke vs extension load + loadout gaps | `.omk/goals/b2c-correctness-wall-2026-07-08/laneE-explorer.md` |
+
+**Wave 2 (prove / integrate):** wire `AdaptOrchClient` on hooks when session has run context; lift `BATCH1_NO_DOCKER_RUNNER` for non-preview deep wall; optional preset documentation in `~/.omk/runtime-preset.json` comments only (no default-on extension).
+
+**Wave 3 (productize):** publish `omk-adaptorch-wpl` from `dist/` for out-of-monorepo extensions; optional `domain-loadouts.ts` profile + `gen-domain-docs.mjs` regen; default **soft** for internal dogfood presets after Wave 2 evidence.
+
+## See also
+
+- [adaptorch-preview.md](./adaptorch-preview.md)
+- [LOADOUT.md](../examples/extensions/correctness-wall/LOADOUT.md) — copy-paste for `omk-core-verified` sessions
+- Goal artifacts: `.omk/goals/b2c-correctness-wall-2026-07-08/` (`algorithm-v2.md`, `dag-v2.json`)
+- Extension README: `packages/coding-agent/examples/extensions/correctness-wall/README.md`

package/docs/grok-harness.md

@@ -0,0 +1,63 @@
+# Grok harness
+
+This page is the project-local operator guide for running OMK with the xAI OAuth proxy. The canonical Grok playbook remains `~/.omk/agent/grok.md`; keep this page as a short routing and preset reference, not a duplicate source of truth.
+
+## Presets
+
+Project presets live in `.omk/presets.json` and are consumed by the preset extension from `packages/coding-agent/examples/extensions/preset.ts`. The shared Grok presets intentionally omit the `tools` key so role/domain lane grants keep control of the active tools.
+
+| Preset | Provider | Model | Thinking | Use |
+| --- | --- | --- | --- | --- |
+| `grok-verified` | `grok-oauth-proxy` | `grok-4.5` | `high` | Default Grok text-chat baseline (local OAuth proxy). |
+| `grok-adaptorch-prod` | `grok-oauth-proxy` | `grok-4.5` | `high` | Same baseline, with AdaptOrch reserved for explicit DAG routing, synthesis, or consistency-verification lanes. |
+
+Register the provider in `~/.omk/agent/models.json` with `baseUrl: http://127.0.0.1:9996/v1` and chat models including `grok-4.5` (and optional fallbacks such as `grok-4.3`). Loopback proxy accepts a dummy `apiKey`; do not put OAuth tokens in models.json. Confirm proxy health with `curl -fsS http://127.0.0.1:9996/health` before long sessions.
+
+Suggested TUI flow:
+
+1. Run `/grok` to inject the pointer to `~/.omk/agent/grok.md`.
+2. Select `/preset grok-verified` for normal chat/coding work.
+3. Select `/preset grok-adaptorch-prod` only when the task has an explicit DAG, routing, or synthesis objective.
+4. Keep credentials and OAuth material out of preset JSON.
+
+## Domain routing
+
+Domain routing is opt-in. Start OMK with `OMK_DOMAIN_ROUTING=1` when you want the domain router to compose the role loadout with a domain profile before dispatch. With the variable unset or any value other than `1`, the domain dispatch layer does not apply a domain access policy.
+
+The router selects one of the documented domain profiles under [`loadout-domains/`](loadout-domains/README.md), then composes that profile with the active role loadout. Grok presets do not replace this mechanism; they only set provider, model, thinking level, and instruction pointers.
+
+## Composer model
+
+`grok-composer-2.5-fast` is a valid Grok chat model, but the project presets keep `grok-4.5` as the default. Use Composer only for explicit Composer validation or comparison work. `grok-4.3` remains a supported fallback chat model. Do not use `grok-imagine-*` ids as chat models; session `setModel` / `prompt` reject them on `grok-oauth-proxy`.
+
+## Imagine tools
+
+Imagine media generation is tool-based, not model-selection-based:
+
+| Task | OMK tool |
+| --- | --- |
+| Text-to-image, image edits, restyles | `grok_imagine_image` |
+| Text-to-video or image-to-video | `grok_imagine_video` |
+
+Do not select `grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-video`, or similar Imagine ids as the chat model. For media tasks, require tool output evidence such as the final saved path or URL before claiming success.
+
+## Skill and MCP matrix summary
+
+Use the normal OMK lane grant model: grant the smallest skill and MCP surface that matches the task, and keep media exceptions explicit.
+
+| Task class | Skills | MCP |
+| --- | --- | --- |
+| Multi-package or repo-context work | `packages`; add `headroom` only under context pressure | none by default |
+| Repo graph or broad comprehension | `understand-anything`; optionally `packages` | `understand-anything` |
+| DAG planning or synthesis | `adaptorch` / `adaptorch-route` / `adaptorch-synthesize` | `adaptorch` |
+| TypeScript/Rust/Python/Go edits | `programming`; add `lsp` or `ast-grep` only for symbol/structural work | none by default |
+| Runtime failures or broken behavior | `debugging` | task-specific only |
+| UI/TUI verification | `visual-qa` | `playwright` only when browser/UI evidence is required |
+| Current public URL or docs lookup | task skill as needed | `fetch` |
+| Image prompts or media generation | explicit-only `image-prompt`, `omnigen-vault`, or `gpt-image-2-prompts` | none by default |
+
+Relevant evidence hooks for Grok lanes are `pre-shell-guard`, `protect-secrets`, `typecheck-after-edit`, and `stop-verify`. Hook output is incremental evidence; code changes still need the project's required final verification command before claiming type/lint cleanliness.
+
+## Canonical reference
+
+For proxy health checks, chat model rules, Imagine tool behavior, Hermes parity, Telegram behavior, and unsafe `GROK.MD` handling, read `~/.omk/agent/grok.md`.

package/docs/loadout-domains/README.md

@@ -21,7 +21,7 @@ OMK routes incoming tasks to a **domain capability profile** ("inherited documen
 
 Thresholds: `STRONG_THRESHOLD = 8`, `WEAK_THRESHOLD = 4`, `AMBIGUITY_MARGIN = 2`.
 
-## Domains (12 + 1 fallback)
+## Domains (13 + 1 fallback)
 
 - [`frontend-ui`](frontend-ui.md) — Frontend & UI
 - [`visual-qa`](visual-qa.md) — Visual QA & Website Cloning
@@ -34,6 +34,7 @@ Thresholds: `STRONG_THRESHOLD = 8`, `WEAK_THRESHOLD = 4`, `AMBIGUITY_MARGIN = 2`
 - [`mobile`](mobile.md) — Mobile (iOS / Android / KMP)
 - [`docs-writing`](docs-writing.md) — Docs & Technical Writing
 - [`qa-testing`](qa-testing.md) — QA & Testing
+- [`grok-harness`](grok-harness.md) — Grok xAI Harness
 - [`ai-agent-ops`](ai-agent-ops.md) — AI Agent Engineering & Ops
 - [`general`](general.md) — General (fallback)
 

package/docs/loadout-domains/ai-agent-ops.md

@@ -29,6 +29,8 @@ SEQUENCE:
 6. Orchestration: harness (team-architecture factory) for multi-agent topology; dispatching-parallel-agents / subagent-driven-development for parallel lanes; ralphinho-rfc-pipeline for DAG + merge queue.
 
 HARD RULES: every agent/skill change has an eval; prompts are versioned and tested, not vibe-edited; MCP servers validate inputs; autonomy is bounded by explicit stop conditions + stop-verify hook.
+
+PATCH SAFETY (B2C Correctness Wall): for pre-apply patch screening, load the correctness-wall extension explicitly (not in default preset). Read packages/coding-agent/docs/correctness-wall.md and examples/extensions/correctness-wall/README.md. Roll out shadow → soft → hard; never claim formal correctness proof.
 ```
 
 ## Curated skills (23)
@@ -71,7 +73,7 @@ HARD RULES: every agent/skill change has an eval; prompts are versioned and test
 - `stop-verify`
 - `subagent-stop-audit`
 
-## Routing triggers (18)
+## Routing triggers (23)
 
 | kind | pattern | weight |
 |---|---|---|
@@ -93,3 +95,8 @@ HARD RULES: every agent/skill change has an eval; prompts are versioned and test
 | path | `.claude/agents` | 6 |
 | path | `.omk/` | 5 |
 | path | `SKILL.md` | 5 |
+| keyword | `correctness wall` | 8 |
+| keyword | `patch safety` | 8 |
+| regex | `\bpatch[- ]safety\b` | 7 |
+| path | `correctness-wall` | 7 |
+| path | `adaptorch-wpl` | 5 |

package/docs/loadout-domains/grok-harness.md

@@ -0,0 +1,74 @@
+# Grok xAI Harness (`grok-harness`)
+
+> Inherited domain capability document. Auto-generated from `src/core/domain-loadouts.ts` — do not edit by hand.
+
+
+## Identity
+
+| field | value |
+|---|---|
+| id | `grok-harness` |
+| authority | `write-scoped` |
+| tools | read, grep, find, ls, edit, write, bash |
+| command mode | `scoped-shell` |
+
+## Routing prompt
+
+> Prepended to the lane task prompt when the router selects this domain.
+
+```text
+DOMAIN: Grok xAI Harness. You are operating in a Grok/xAI integration lane.
+Prioritize the Grok operational playbook, small capability loadouts, and evidence-bound provider/tool routing.
+
+SEQUENCE:
+1. Before implementing or routing Grok/xAI provider work, read and enforce ~/.omk/agent/grok.md. Treat it as the required Grok playbook for chat models vs Imagine tools, proxy health, tool-use/loop discipline, and Telegram parity unless higher-priority instructions conflict.
+2. Keep text chat flows and Imagine/media tool flows separate. Text work uses Grok chat/OAuth/provider surfaces; image/video/Imagine work routes through explicit Imagine tools only. Never conflate model ids with Imagine tool names.
+3. Capability discipline: load at most 2-3 skills for any lane. The allowed skill gate is packages, headroom, programming, debugging, adaptorch-route, adaptorch-synthesize, and understand-anything; choose the smallest subset and add headroom only under context pressure.
+4. Adaptorch is advisory only. Use adaptorch-route for routing/decomposition advice and adaptorch-synthesize for evidence synthesis, but do not treat Adaptorch as an automatic executor, source of truth, permission grant, or substitute for explicit tests.
+5. Use minimal MCP: adaptorch for advice/synthesis, fetch for bounded public retrieval, understand-anything for repo comprehension, and playwright only when browser or Imagine UI behavior needs real verification.
+6. Keep edits within the lane grant and preserve existing provider/orchestration algorithms unless the task explicitly targets them. Never route through legacy KIMICLI or deleted wrappers.
+7. Verification: run the narrowest relevant test/typecheck after edits. Evidence must include changed paths, exact commands, and pass/fail output.
+
+HARD RULES: grok.md is mandatory context for Grok/xAI harness work; text chat surfaces and Imagine tools are distinct; maximum 2-3 active skills; Adaptorch is advisory route/synthesis support only; never log OAuth tokens, cookies, or proxy credentials; protect-secrets applies.
+```
+
+## Curated skills (7)
+
+- `packages`
+- `headroom`
+- `programming`
+- `debugging`
+- `adaptorch-route`
+- `adaptorch-synthesize`
+- `understand-anything`
+
+## Curated MCP servers (4)
+
+- `adaptorch`
+- `fetch`
+- `understand-anything`
+- `playwright`
+
+## Curated hooks (5)
+
+- `pre-shell-guard`
+- `protect-secrets`
+- `typecheck-after-edit`
+- `stop-verify`
+- `session-context`
+
+## Routing triggers (11)
+
+| kind | pattern | weight |
+|---|---|---|
+| keyword | `grok` | 8 |
+| keyword | `xai` | 7 |
+| keyword | `grok-oauth` | 8 |
+| keyword | `grok oauth` | 8 |
+| keyword | `imagine` | 6 |
+| keyword | `composer` | 5 |
+| keyword | `adaptorch` | 7 |
+| keyword | `adaptorch-route` | 8 |
+| keyword | `adaptorch-synthesize` | 8 |
+| regex | `\b(grok(?:[- ]oauth)?|xai|imagine|composer)\b` | 7 |
+| regex | `\badapt\s*orch\b|\badaptorch[- ]?(route|routing|synthes(?:is|ize))\b` | 8 |

package/docs/providers.md

@@ -35,6 +35,10 @@ Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party h
 - Press Enter for github.com, or enter your GitHub Enterprise Server domain
 - If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
 
+### Grok harness presets
+
+For `grok-oauth-proxy` project presets, Composer routing, and Imagine tool guidance, see [Grok harness](grok-harness.md).
+
 ## API Keys
 
 ### Environment Variables or Auth File

package/examples/extensions/correctness-wall/LOADOUT.md

@@ -0,0 +1,87 @@
+# Correctness Wall — optional loadout (copy-paste)
+
+Use this when you run OMK with the default **`omk-core-verified`** preset and want a **B2C patch safety screen** on `edit` / `write` before changes land on disk. The wall is policy- and evidence-limited; it is **not** proof of correctness. Canonical operator doc: [`docs/correctness-wall.md`](../../docs/correctness-wall.md).
+
+## When to enable
+
+| Situation | Action |
+|-----------|--------|
+| AI-generated or high-risk patches in a scoped lane | Load extension + set `OMK_WALL_SCOPE` |
+| Shadow telemetry only (no blocking) | `OMK_PATCH_SAFETY_WALL_MODE=shadow` (default) |
+| Block out-of-scope or secret-shaped diffs | `soft` or `hard` + explicit scope globs |
+| Full outcome adjudication (OA) | Call tool `correctness_wall_evaluate` with fixture — not on the edit hook path |
+
+**Routing note:** Domain router may send similar work to [`qa-testing`](../../docs/loadout-domains/qa-testing.md) (`execute-tests`, green-run evidence). The wall complements that lane: it gates **apply**, not **test execution**. For monorepo layout and extension paths, load skill **`packages`** when wiring paths from a checkout.
+
+## Copy-paste: session start
+
+From repo root (paths assume monorepo checkout):
+
+```bash
+export OMK_PATCH_SAFETY_WALL_MODE=shadow
+export OMK_WALL_SCOPE='packages/coding-agent/**,packages/adaptorch-wpl/**'
+export OMK_WALL_REPAIR_BUDGET=1
+
+omk --extension packages/coding-agent/examples/extensions/correctness-wall/index.ts
+```
+
+Persistent install (user extensions dir):
+
+```bash
+cp -r packages/coding-agent/examples/extensions/correctness-wall ~/.omk/agent/extensions/correctness-wall/
+# Then start omk; discovery depends on your agent config loading ~/.omk/agent/extensions/
+```
+
+## Dogfood phase 2 (soft) — internal lanes
+
+After shadow telemetry review (see [correctness-wall.md](../../docs/correctness-wall.md#recommended-rollout-shadow--soft--hard)):
+
+```bash
+export OMK_PATCH_SAFETY_WALL_MODE=soft
+export OMK_WALL_SCOPE='packages/adaptorch-wpl/**,packages/coding-agent/examples/extensions/correctness-wall/**'
+export OMK_WALL_OVERRIDE=   # set only for intentional human override
+omk --extension packages/coding-agent/examples/extensions/correctness-wall/index.ts
+```
+
+Live OA (optional): `OMK_WALL_OA_TRANSPORT=mcp`. The extension entry calls `autoWireLiveAdaptOrch(omk)` so live transport uses host `omk.callMcpTool` when the harness binds a handler at `bindCore`. Until a session MCP hub binds that handler, invocations throw and fixture transport remains the safe default. Manual `setWallAdaptOrchCallTool` is still available for tests.
+
+## Copy-paste: `omk-core-verified` + extension
+
+Keep your usual preset (`~/.omk/runtime-preset.json` or project default). Add **one** extra flag for this harness:
+
+```bash
+omk --extension packages/coding-agent/examples/extensions/correctness-wall/index.ts
+```
+
+Optional hardening for a single lane (example owned paths only):
+
+```bash
+export OMK_PATCH_SAFETY_WALL_MODE=soft
+export OMK_WALL_SCOPE='packages/coding-agent/examples/extensions/correctness-wall/**'
+export OMK_WALL_OVERRIDE=   # unset unless human override is intentional
+```
+
+## On-demand evaluation (tool)
+
+Does not require blocking mode; useful for planners/reviewers:
+
+- Tool: `correctness_wall_evaluate`
+- Params: `kind`, optional `diffPath`, `approvedWriteScope`, `previewOnly`, `runIds`, `adjudicationFixturePath`
+- OA fixture format: see [README.md](./README.md#oa-adjudication-fixture-format)
+
+## Evidence & cache (no secrets in logs)
+
+| Artifact | Purpose |
+|----------|---------|
+| `.omk/wall-cache/latest.json` | Last verdict summary |
+| `.omk/wall-cache/shadow-telemetry.ndjson` | Shadow-mode audit trail |
+| `.omk/wall-cache/repair-budget.json` | Capped repair hints per packet |
+
+Final claims still need project rules: e.g. `npm run check` / targeted tests per [`AGENTS.md`](../../../../AGENTS.md) — the wall does not replace those.
+
+## See also
+
+- [correctness-wall.md](../../docs/correctness-wall.md) — verdicts, fast vs deep wall, Adaptorch relationship
+- [adaptorch-preview.md](../../docs/adaptorch-preview.md) — preview planning (separate from apply gate)
+- [README.md](./README.md) — env vars, hook behavior, limitations
+- Domain catalog: [loadout-domains/README.md](../../docs/loadout-domains/README.md)

package/examples/extensions/correctness-wall/README.md

@@ -0,0 +1,111 @@
+# Correctness Wall extension
+
+B2C patch safety gate for `edit` and `write` tool calls, plus an explicit `correctness_wall_evaluate` tool. Policy checks come from `omk-adaptorch-wpl` via a **relative import** (no workspace `package.json` dependency).
+
+## Usage
+
+From the `packages/coding-agent` directory (or repo root with a valid path):
+
+```bash
+omk --extension examples/extensions/correctness-wall/index.ts
+```
+
+Copy into user extensions for auto-discovery:
+
+```bash
+cp -r examples/extensions/correctness-wall ~/.omk/agent/extensions/correctness-wall/
+```
+
+## Claim boundaries
+
+- **In scope**: unified-diff preview for pending `edit`/`write`, fast policy wall (write scope, flags), optional OA adjudication when `correctness_wall_evaluate` is called with `runIds`, `previewOnly: false`, and an OA fixture file (env or tool param).
+- **Out of scope**: Replacing core hooks, modifying `packages/adaptorch-wpl` from this lane, or adding npm workspace dependencies. The extension only **imports** `evaluateCorrectnessWall` and `AdaptOrchClient` from `../../../../adaptorch-wpl/src/index.ts`.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `OMK_PATCH_SAFETY_WALL_MODE` | `shadow` | `shadow` — log/notify only, never block. `soft` — block `BLOCKED` unless override. `hard` — block `BLOCKED` and `INCONCLUSIVE`. |
+| `OMK_WALL_SCOPE` | *(empty)* | Comma-separated glob/path prefixes allowed in the diff. Empty means scope checks do not approve any path (out-of-scope diffs can trigger blocking flags when paths are present). |
+| `OMK_WALL_OVERRIDE` | unset | When `1` / `true` / `yes`, `soft` mode does not block `BLOCKED` verdicts (human override). |
+| `OMK_WALL_REPAIR_BUDGET` | `1` | Capped regenerate budget: max **blocked attempts** per packet (keyed by `packetId` or SHA-256 of `kind` + sorted `OMK_WALL_SCOPE`) before repair hints are treated as exhausted. Also caps hint string count in UI/JSON. Persisted in `.omk/wall-cache/repair-budget.json`. Hints only — no auto-regenerate. |
+| `OMK_WALL_RUN_IDS` | *(empty)* | Comma-separated AdaptOrch run ids. On `edit`/`write` hooks, when non-empty **and** `OMK_WALL_OA_FIXTURE_PATH` (or per-tool `adjudicationFixturePath`) is set, evaluation uses `previewOnly: false` and OA adjudication via `resolveOaClientForEvaluation`. Otherwise hooks stay preview-only. |
+| `OMK_WALL_OA_FIXTURE_PATH` | unset | Path to OA adjudication fixture JSON. Used when `correctness_wall_evaluate` runs with `previewOnly: false` and non-empty `runIds`, and on edit/write hooks when combined with `OMK_WALL_RUN_IDS`. Overridden per call by `adjudicationFixturePath`. |
+| `OMK_WALL_AUTO_REGENERATE` | unset | When `1` / `true` / `yes`, `correctness_wall_evaluate` JSON may include a `regeneratePacket` (capped hints only; no automatic patch apply). |
+| `OMK_WALL_RECEIPT_SIGNING_SECRET` | unset | When set, verification receipts include `signedReceipt` (HMAC-SHA256 over digest composite). Never log or commit this value. |
+| `OMK_WALL_DEEP_PHASE` | `stub` | `docker` records deep-wall intent; hermetic runner still unavailable (batch-2). |
+| `OMK_WALL_OA_TRANSPORT` | `fixture` | `mcp` or `live` uses session-injected MCP `callTool` via `setWallAdaptOrchCallTool` (see `adjudication-fixture.ts`). Fixture path optional for receipt metadata when using `mcp`. |
+
+## OA adjudication fixture format
+
+Fixture file (JSON object). Each `run_id` must define the three AdaptOrch introspection payloads the in-memory client serves:
+
+```json
+{
+  "wall_version": "1",
+  "dispatchRecordId": "local-dev-dispatch",
+  "runsById": {
+    "run-oa-1": {
+      "run": { "run_id": "run-oa-1", "status": "completed" },
+      "artifacts": [{ "path": "out.md", "size_bytes": 42 }],
+      "traces": [{ "kind": "write", "level": "info" }]
+    }
+  }
+}
+```
+
+- **`wall_version`**: optional string copied onto the verification **receipt** returned by `correctness_wall_evaluate` (defaults to extension version `1`).
+- **`dispatchRecordId`**: optional; passed to OA adjudication when not set elsewhere.
+- **`runsById`**: required map; keys must match `runIds` in the tool call.
+
+`createInMemoryAdaptOrchClient` (in `adjudication-fixture.ts`) wraps these entries with the same transport pattern as `packages/adaptorch-wpl/test/b2c-wall-oa.test.ts`.
+
+## Tools
+
+### `correctness_wall_evaluate`
+
+Parameters:
+
+- `kind` (string, required)
+- `approvedWriteScope` (optional string array)
+- `previewOnly` (optional boolean, default `true`)
+- `diffPath` (optional string) — if omitted, returns an `INCONCLUSIVE` verdict card JSON
+- `runIds` (optional string array)
+- `packetId` (optional string)
+- `adjudicationFixturePath` (optional string) — OA fixture file; falls back to `OMK_WALL_OA_FIXTURE_PATH`
+
+Returns JSON text: `{ verdictCard, receipt }`, and `repairHints` when `verdictCard.verdict` is `BLOCKED`.
+
+The **`receipt`** includes standard `VerificationReceipt` fields from adaptorch-wpl plus **`wall_version`** (from the fixture or default).
+
+Example receipt fragment:
+
+```json
+{
+  "schemaVersion": 1,
+  "evaluatedAt": "2026-07-08T12:00:00.000Z",
+  "kind": "code-edit",
+  "runIds": ["run-oa-1"],
+  "previewOnly": false,
+  "wall_version": "1",
+  "adjudicationVerdict": "CONFIRMED",
+  "policyFlags": []
+}
+```
+
+## Edit/write gate
+
+On each `edit` or `write` `tool_call` hook:
+
+1. Build a unified diff preview from `event.input` (edits or write content).
+2. Call `evaluateCorrectnessWall` with scope from `OMK_WALL_SCOPE`. Default `previewOnly: true`; when `OMK_WALL_RUN_IDS` is non-empty and an OA fixture path is set (`OMK_WALL_OA_FIXTURE_PATH`), hooks use `previewOnly: false`, pass `runIds`, and supply the OA client from `resolveOaClientForEvaluation`.
+3. Apply `OMK_PATCH_SAFETY_WALL_MODE` blocking rules; blocked calls return `{ block: true, reason: "<short user message>" }`.
+4. Write a summary snapshot to `.omk/wall-cache/latest.json` (mode, verdict, `wouldBlock`, compact card summary, timestamp — no full diff or secrets).
+5. In `shadow` mode, append one NDJSON line per gated tool call to **`.omk/wall-cache/shadow-telemetry.ndjson`** (`event`, `wall_version`, `mode`, `verdict`, `wouldBlock`, `kind`, `tool`, `previewOnly`, `usedOaFixture`, `timestamp` — no diff or secrets).
+6. On `BLOCKED`, increment per-packet attempts in `.omk/wall-cache/repair-budget.json`. In `shadow` mode, append capped repair hints to the UI notification; when `attempts >= OMK_WALL_REPAIR_BUDGET`, append a repair-budget-exhausted message.
+
+## Limitations
+
+- Edit preview reads the target file from disk relative to session `cwd`; if the file is missing or paths are wrong, the hook may return `INCONCLUSIVE` (and block in `hard` mode).
+- Hook OA requires both `OMK_WALL_RUN_IDS` and a fixture path; if either is missing, hooks remain preview-only. Explicit `correctness_wall_evaluate` can still pass `runIds`, `previewOnly: false`, and `adjudicationFixturePath` per call.
+- Relative imports require loading this extension from the monorepo layout (or an equivalent path to `adaptorch-wpl` and `coding-agent` sources).

package/examples/extensions/correctness-wall/adjudication-fixture.ts

@@ -0,0 +1,151 @@
+/**
+ * OA adjudication fixture loader and in-memory AdaptOrch client for local/dev evaluation.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { AdaptOrchCallToolFn, AdaptOrchClient } from "../../../../adaptorch-wpl/src/index.ts";
+import {
+	createLiveAdaptOrchClient,
+	createInMemoryAdaptOrchClient as createWplInMemoryClient,
+	parseOaTransportModeFromEnv,
+} from "../../../../adaptorch-wpl/src/index.ts";
+
+/** Optional session-injected MCP `callTool` when `OMK_WALL_OA_TRANSPORT=mcp`. */
+let wallAdaptOrchCallTool: AdaptOrchCallToolFn | undefined;
+
+export function setWallAdaptOrchCallTool(fn: AdaptOrchCallToolFn | undefined): void {
+	wallAdaptOrchCallTool = fn;
+}
+
+/** Minimal capability surface an extension host may expose for live MCP transport. */
+export interface McpCallToolCapable {
+	callMcpTool?(server: string, name: string, args: Record<string, unknown>): Promise<unknown>;
+}
+
+/** Default MCP server name used by the live adaptorch transport. */
+export const ADAPTORCH_MCP_SERVER = "adaptorch";
+
+/**
+ * Build an {@link AdaptOrchCallToolFn} that forwards to a session MCP capability,
+ * or return `undefined` when the host does not expose `callMcpTool`. The adaptorch
+ * server name is used as the MCP target by default. Pure: does not touch module state.
+ */
+export function buildLiveCallToolFromCapability(
+	api: McpCallToolCapable,
+	server: string = ADAPTORCH_MCP_SERVER,
+): AdaptOrchCallToolFn | undefined {
+	if (typeof api.callMcpTool !== "function") return undefined;
+	return (name, args) => api.callMcpTool!(server, name, args);
+}
+
+/**
+ * Auto-wire live adaptorch MCP transport when the host exposes `callMcpTool`.
+ * Called once from the extension entry. Idempotent and a no-op when the capability
+ * is absent (fixture transport remains the default). Using the live client is still
+ * gated by `OMK_WALL_OA_TRANSPORT=mcp` (explicit operator opt-in).
+ */
+export function autoWireLiveAdaptOrch(api: McpCallToolCapable): void {
+	setWallAdaptOrchCallTool(buildLiveCallToolFromCapability(api));
+}
+
+export const CORRECTNESS_WALL_EXTENSION_VERSION = "1" as const;
+
+/** Per-run payloads returned by fake adaptorch_get_run / _get_artifacts / _get_traces. */
+export interface OaRunFixture {
+	run: unknown;
+	artifacts: unknown;
+	traces: unknown;
+}
+
+export interface AdjudicationFixtureFile {
+	/** Extension / fixture schema version (surfaced on verification receipts as wall_version). */
+	wall_version?: string;
+	/** Optional default dispatch record id for adjudication requests. */
+	dispatchRecordId?: string;
+	/** Map of AdaptOrch run_id → MCP tool payloads. */
+	runsById: Record<string, OaRunFixture>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseFixtureJson(raw: unknown): AdjudicationFixtureFile {
+	if (!isRecord(raw)) {
+		throw new Error("OA fixture root must be a JSON object");
+	}
+	const runsById = raw.runsById;
+	if (!isRecord(runsById)) {
+		throw new Error("OA fixture missing runsById object");
+	}
+	const normalized: Record<string, OaRunFixture> = {};
+	for (const [runId, entry] of Object.entries(runsById)) {
+		if (!isRecord(entry)) {
+			throw new Error(`OA fixture runsById.${runId} must be an object`);
+		}
+		if (!("run" in entry) || !("artifacts" in entry) || !("traces" in entry)) {
+			throw new Error(`OA fixture runsById.${runId} must include run, artifacts, and traces`);
+		}
+		normalized[runId] = {
+			run: entry.run,
+			artifacts: entry.artifacts,
+			traces: entry.traces,
+		};
+	}
+	return {
+		wall_version:
+			typeof raw.wall_version === "string" && raw.wall_version.length > 0
+				? raw.wall_version
+				: CORRECTNESS_WALL_EXTENSION_VERSION,
+		dispatchRecordId: typeof raw.dispatchRecordId === "string" ? raw.dispatchRecordId : undefined,
+		runsById: normalized,
+	};
+}
+
+export async function loadAdjudicationFixtureFile(filePath: string): Promise<AdjudicationFixtureFile> {
+	const text = await readFile(filePath, "utf-8");
+	const parsed: unknown = JSON.parse(text);
+	return parseFixtureJson(parsed);
+}
+
+/** In-memory {@link AdaptOrchClient} backed by fixture run payloads (delegates to omk-adaptorch-wpl). */
+export function createInMemoryAdaptOrchClient(fixture: AdjudicationFixtureFile): AdaptOrchClient {
+	return createWplInMemoryClient(fixture.runsById);
+}
+
+export function resolveAdjudicationFixturePath(toolParamPath?: string): string | undefined {
+	const fromTool = toolParamPath?.trim();
+	if (fromTool) return fromTool;
+	const fromEnv = process.env.OMK_WALL_OA_FIXTURE_PATH?.trim();
+	return fromEnv && fromEnv.length > 0 ? fromEnv : undefined;
+}
+
+export async function resolveOaClientForEvaluation(options: {
+	previewOnly: boolean;
+	runIds?: string[];
+	adjudicationFixturePath?: string;
+}): Promise<{ client?: AdaptOrchClient; fixture?: AdjudicationFixtureFile }> {
+	const runIds = options.runIds ?? [];
+	if (options.previewOnly || runIds.length === 0) {
+		return {};
+	}
+	const transportMode = parseOaTransportModeFromEnv();
+	if (transportMode === "mcp" && wallAdaptOrchCallTool !== undefined) {
+		const fixturePath = resolveAdjudicationFixturePath(options.adjudicationFixturePath);
+		const fixture = fixturePath !== undefined ? await loadAdjudicationFixtureFile(fixturePath) : undefined;
+		return {
+			client: createLiveAdaptOrchClient(wallAdaptOrchCallTool),
+			fixture,
+		};
+	}
+	const fixturePath = resolveAdjudicationFixturePath(options.adjudicationFixturePath);
+	if (!fixturePath) {
+		return {};
+	}
+	const fixture = await loadAdjudicationFixtureFile(fixturePath);
+	return { client: createInMemoryAdaptOrchClient(fixture), fixture };
+}
+
+export function wallVersionFromFixture(fixture?: AdjudicationFixtureFile): string {
+	return fixture?.wall_version ?? CORRECTNESS_WALL_EXTENSION_VERSION;
+}