open-multi-agent-kit 0.79.1 → 0.80.0

package/docs/native-root-runtime-hardening.md

@@ -0,0 +1,141 @@
+# Native Root Runtime Hardening
+
+Last updated: 2026-06-15
+Current package version: `open-multi-agent-kit@0.79.3`
+Runtime contract family: `v1.2`
+Release channel: `pre-1.0`
+
+## Current State
+
+OMK is the root orchestrator. Kimi, Codex, DeepSeek, OpenCode, CommandCode, GLM, and future providers are runtime/provider lanes selected through OMK-owned contracts. API advisory runtimes remain read/review/advisory unless a runtime-mode contract grants write/shell/merge authority.
+
+This is still a hardening milestone, not a stable 1.x or OS-level sandbox claim. The current release stop condition is:
+
+- Local `npm run release:check` must pass on the exact release diff.
+- GitHub Actions Smoke Test must pass on the exact commit/tag.
+- GitHub Actions CI or Release workflow gates must pass on the exact commit/tag.
+- npm registry `latest` must be verified when a release claim references a published version.
+- Release evidence must be kept under `.omk/runs/<run-id>/`, `.omk/release-evidence/<short-sha>/`, or an equivalent run artifact path.
+
+Fresh verification at the time of this update:
+
+- `open-multi-agent-kit@0.79.3` is published as npm `latest`.
+- Main CI, main Smoke, tag Release, and tag Smoke passed for `v0.79.3` after rerunning transient failures.
+- Local verification for the machine-checkable hardening slice passed: `npm run check`, `npm run build:clean`, `npm run lint`, `npm run secret:scan`, `npm run version:check`, targeted runtime tests, and `npm test`.
+
+For the LaTeX/paper-ready algorithm appendix and acceptance criteria, see
+[Native Root Runtime Algorithms](./native-root-runtime-algorithms.md). Treat
+that appendix as hardening criteria; release claims still require exact-diff
+local gates, CI/smoke, and registry evidence.
+
+## Runtime Safety Contract
+
+Related algorithm appendix:
+[Native Root Runtime Algorithms](./native-root-runtime-algorithms.md)
+documents the current acceptance criteria for turn construction, capsule
+conversion, runtime fallback, Kimi prompt transport, and scoped worker
+environment construction.
+
+### Turn risk and capability routing
+
+Related: Algorithm 2.
+
+Native chat turns must be default-safe. A turn should request only the minimum capability needed:
+
+| Turn risk | Typical intent | Capabilities |
+|-----------|----------------|--------------|
+| `read` | explain, review, summarize, inspect docs | `read` only |
+| `write` | edit, fix, implement, refactor | `read`, `write`, `patch` |
+| `shell` | run tests, build, execute commands | `read`, `write`, `shell` with approval policy and required command evidence |
+| `merge` | publish, release, push, merge, destructive changes | authority provider plus release/security gates |
+
+DeepSeek remains an advisory/read/review lane unless an explicit future contract grants safe write/shell execution. Write/shell tasks should route to Kimi, Codex, or a configured authority provider with the matching approval and sandbox policy.
+
+### Approval and sandbox propagation
+
+Related: Algorithm 2, Algorithm 4, and Algorithm 7.
+
+`--execution ask|auto|never` must flow from chat command parsing into `AgentTask.safety`, runtime routing, and the final adapter invocation.
+
+| OMK execution | Runtime expectation |
+|---------------|---------------------|
+| `ask` | request approval before write/shell side effects; Codex should not use `never` |
+| `auto` | allow only low-risk automatic actions; elevate risky shell/write operations |
+| `never` | explicit high-trust/yolo mode only |
+| read-only turn | use read-only sandbox where adapter supports it |
+
+### Authority provider resolution
+
+Related: Algorithm 5.
+
+`authority`, `primary`, and `omk` are policies, not executable providers. They must resolve to a concrete provider before bootstrap or routing:
+
+1. `OMK_AUTHORITY_PROVIDER`, if set and healthy.
+2. Kimi, when installed/authenticated and compatible with task risk.
+3. A configured fallback provider that satisfies the task capability contract.
+
+Unknown or unresolved authority must fail with remediation instead of silently degrading to advisory-only mode.
+
+### Provider health probes
+
+Related: Algorithm 5. Runtime routing now filters unavailable runtimes in async execution paths and includes health in normalized route scoring. The next hardening step is to expand every adapter to a uniform auth/model/quota/rate-limit/latency vector.
+
+Provider bootstrap must distinguish:
+
+- `runtimeOk`: binary/API client available.
+- `authOk`: authenticated enough to make a real call.
+- `modelOk`: selected/default model is supported.
+- `quotaOk`: quota/rate-limit known good, known bad, or unknown.
+
+Binary existence alone is not enough. CLI adapters should probe version and auth/session status where possible; API adapters should validate key presence and perform a cheap health/model check when safe.
+
+### Tool-plane diagnostics
+
+Related: Algorithm 4 and Algorithm 7.
+
+MCP, skills, and hooks must not disappear silently. Runtime manifests should include diagnostics for parse/read failures, unknown names, and scope drops. If a task requires runtime MCP, invalid MCP config is a hard failure.
+
+## Current status after 0.79.3 hardening
+
+Completed foundations:
+
+- Runtime authority is resolved by `(provider, runtimeMode)` through `src/runtime/authority-matrix.ts`; native routing also consults this matrix instead of maintaining a separate advisory-provider list.
+- `OMK_TOOL_AUTHORITY_MODE=enforce` coverage is release-gated through the shared `release:gate-core` script and includes a native-turn subprocess enforcement smoke.
+- Native prompt payloads are private artifacts; public synthetic node labels carry prompt hashes, not raw prompts.
+- `prompt:privacy:check` audits private prompt artifacts against public run artifacts, decision traces, and graph-memory snapshots, and is part of the release gate.
+- Per-turn route/result artifacts are written best-effort and replay-indexed with SHA-256 hashes.
+- Evidence declarations and produced observations are type-separated; command/test evidence requires high-confidence metadata or artifact observations, not stdout keywords alone, and DAG executor/verify/replay paths bridge through the same EvidenceGate v2 contract.
+- Provider route/evidence audit nodes are materialized into local graph memory on native turns, with Provider/Artifact nodes, `EvidenceRequirement -> SATISFIED_BY -> EvidenceObservation` semantics, and route/evidence/artifact edges.
+- Runtime health checks accept requested probe levels; API, local LLM, Codex CLI, and external CLI adapters perform static/cheap/live probes with latency and auth/model/quota/rate-limit dimensions where observable. Router health scoring is normalized and high-risk probes fail closed on unknown runtime/auth/model dimensions.
+- Runtime failure stderr is redacted before public exposure and can be retained as a private redacted full artifact in debug mode, including direct `toTaskResult` conversion paths outside `RuntimeRouter`.
+- Mixed-provider advisory reviewer + CLI coder/verifier routing has regression coverage.
+- Native risk classification is negation-aware, so excluded scopes such as `릴리즈 제외`, `no release`, or `npm 체크 제외` do not trigger false merge/shell routing.
+- Runtime routing now classifies failed attempts (`auth`, `quota`, `rate_limit`, `timeout`, `model`, `runtime`, `authority`, `transient`) and opens short-lived in-process circuit breakers so fallback runtimes are tried without repeatedly hitting known-bad adapters.
+- Runtime scoring reads audit-graph `ProviderRoute -> EVIDENCED_BY -> Evidence` pass/fail observations, so local graph memory can influence future route ordering without exposing raw logs.
+- The scheduler exposes critical-path runnable-plan metadata (`criticalPathDepth`, downstream fanout, score, evidence flags) for replay/debug panels.
+- Headroom compaction uses an explicit `omk.structured-compaction.v1` contract for required task/routing/evidence/safety/capability sections.
+
+## P0 Backlog
+
+1. Keep release evidence current; do not tag/publish while exact-diff CI/smoke or registry verification is missing.
+
+## P1 Backlog
+
+1. Extend exact-diff CI status ingestion once a remote check surface is available in the current runtime.
+2. Add provider-specific model-existence probes where vendors expose safe no-token model metadata or non-generating validation endpoints.
+
+## P2 Backlog
+
+1. Add configurable non-zero exit behavior for native root-loop turn failures.
+2. Add experimental OS sandbox modes only behind explicit opt-in and without public stable claims.
+3. Add broader pty/TTY regression coverage for scroll-safe rendering and interactive selectors.
+
+## Spec-Kit Acceptance Gates
+
+Any spec-kit plan for native root runtime work should include:
+
+- Safety fields: `risk`, `approvalPolicy`, and `sandbox`.
+- Authority fields: requested provider policy and resolved concrete provider.
+- Capability fields: MCP, skills, hooks, write, patch, shell, and review.
+- Diagnostics: provider health, tool-plane parse failures, capability mismatches, and fallback reasons.
+- Evidence: exact commands, local/remote run URLs where available, pass/fail state, and release stop/go decision.

package/docs/neo4j-memory.md

@@ -0,0 +1,5 @@
+# Graph memory and Kuzu
+
+OMK uses project-local ontology graph memory by default and supports the embedded Kuzu backend for Cypher-style graph queries. See [`docs/local-graph-memory.md`](./local-graph-memory.md) for the current memory policy, mind-map ontology, and MCP query examples.
+
+Neo4j support has been removed from the runtime path; stale `[neo4j]` config blocks are ignored and should be deleted from local config files.

package/docs/openai-platform-image-keys.md

@@ -0,0 +1,23 @@
+# OpenAI Platform keys for image generation
+
+OMK separates Codex login from OpenAI API access.
+
+- **Codex/ChatGPT OAuth**: proves the Codex CLI login state only.
+- **OpenAI Platform project API key**: required for `omk image generate` and `omk image edit`, including `gpt-image-2`.
+
+Safe local flow:
+
+1. Complete OpenAI Platform OAuth in a trusted setup surface.
+2. Create an encrypted project API key for the target Platform project.
+3. Decrypt the key locally only when needed.
+4. Run one image command with an ephemeral runtime environment variable.
+5. Unset the env var and remove any decrypted temp key.
+
+Example with a placeholder value:
+
+```bash
+OPENAI_API_KEY=<platform-project-key> omk image generate "ping-pong test" --model gpt-image-2
+unset OPENAI_API_KEY
+```
+
+OMK reads the key only from the runtime environment and does not store it in project files, MCP config, image metadata, or run evidence. Use `--api-key-env <name>` if your local encrypted-key helper injects a different one-shot env var.

package/docs/phase1-final-report.md

@@ -0,0 +1,154 @@
+# Final Report: Phase 1 Integration
+
+**Run ID:** .omk/runs/latest
+**Date:** 2025-05-01
+**Scope:** v0.2 -> v0.3 engine + platform foundation
+**Status:** Complete — all gates passed
+
+---
+
+## Executive Summary
+
+Successfully implemented and merged Phase 1 features (engine + platform layers) using isolated worktree workers with non-overlapping file ownership. All critical review findings were fixed pre-merge. Type check, build, CLI load, doctor, and HUD regression gates all pass with zero errors.
+
+---
+
+## Worker Architecture
+
+| Phase | Worker | Role | Worktree | Branch |
+|-------|--------|------|----------|--------|
+| 0 | Contract | Define cross-worker APIs | .omk/worktrees/contract | work/contract |
+| 1 | B | Engine Layer | .omk/worktrees/engine | work/engine |
+| 1 | C | Platform Layer | .omk/worktrees/platform | work/platform |
+| 2 | A | Commands Layer (pending) | .omk/worktrees/commands | work/commands |
+| 2 | D | Content Layer (pending) | .omk/worktrees/content | work/content |
+| 3 | Integration | Merge + QA | .omk/worktrees/integration | work/integration |
+
+---
+
+## What Was Delivered
+
+### Contracts (Phase 0)
+
+| File | Exports |
+|------|---------|
+| src/contracts/orchestration.ts | DagExecutor, TaskRunner, RunState, RunResult, RunOptions |
+| src/contracts/safety.ts | PolicyEngine, ApprovalDecision, ApprovalContext |
+| src/contracts/hud.ts | HudRenderer, MetricSnapshot, LogHandler |
+
+### Engine Layer (Worker B)
+
+| File | Purpose |
+|------|---------|
+| src/orchestration/executor.ts | Parallel DAG execution up to N workers; state persistence; onStateChange handlers |
+| src/orchestration/scheduler.ts | Runnable node queue; retry logic; completion/failure detection |
+| src/orchestration/state-persister.ts | RunState persistence with path traversal protection |
+| src/safety/guard-hooks.ts | preShellGuard — blocks destructive commands; protectSecrets — blocks sensitive files/patterns |
+| src/kimi/wire-client.ts | createKimiTaskRunner — wire-client-based TaskRunner adapter |
+| src/safety/approval-policy.ts | createPolicyEngine — async PolicyEngine implementation |
+
+### Platform Layer (Worker C)
+
+| File | Purpose |
+|------|---------|
+| src/util/worktree.ts | createWorktree, removeWorktree, listWorktrees |
+| src/util/run-dir.ts | getRunDir, ensureRunDir, writeRunState, readRunState |
+| src/util/kimi-runner.ts | createKimiTaskRunner — runShell-based TaskRunner adapter |
+| src/util/shell.ts | runShellStreaming — line-by-line stdout/stderr callbacks |
+| src/util/git.ts | removeWorktree |
+| src/util/fs.ts | getRunPath |
+| src/memory/memory-store.ts | readRunMemory, writeRunMemory |
+| src/mcp/omk-project-server.ts | omk_list_worktrees, omk_run_quality_gate MCP tools |
+
+---
+
+## Review Findings & Resolutions
+
+### Critical (All Fixed Pre-Merge)
+
+| # | Finding | Worker | File | Fix |
+|---|---------|--------|------|-----|
+| 1 | Unhandled rejection -> permanent deadlock | B | executor.ts | Added catch/finally around runNode promises |
+| 2 | workers: 0 -> indefinite deadlock | B | executor.ts | Validate workers >= 1 at execute() entry |
+| 3 | Generic regex blocks SHA-256, UUIDs, base64 | B | guard-hooks.ts | Removed overly broad generic pattern |
+| 4 | detectPm() always returns npm | C | omk-project-server.ts | Fixed falsy empty-string check |
+| 5 | Path traversal via unsanitized runId | C | memory-store.ts | Reject runId containing .. or absolute paths |
+| 6 | Path traversal via runId/nodeId | C | worktree.ts | Reject IDs containing .. or absolute paths |
+
+---
+
+## Merge Conflicts
+
+| File | Conflict Type | Resolution |
+|------|--------------|------------|
+| WORKER_MANIFEST.md | Both workers added own manifest | Replaced with unified integration manifest |
+| src/util/kimi-runner.ts | Main had runKimiInteractive; Platform added createKimiTaskRunner | Combined both functions in one file |
+
+No other conflicts. Clean ort-strategy merge.
+
+---
+
+## Regression Gates
+
+| Gate | Result | Details |
+|------|--------|---------|
+| npm run check | Pass | tsc --noEmit — 0 errors |
+| npm run build | Pass | All .ts -> .js + .d.ts + .map |
+| node dist/cli.js --help | Pass | All 11 commands render |
+| Dist artifacts | Pass | New modules present in dist/ |
+| node dist/cli.js doctor | Pass | 19/20 checks OK, 1 pre-existing warning |
+| node dist/cli.js hud | Pass | All panels render correctly |
+
+---
+
+## Git History
+
+```
+302f67d merge: integrate work/engine + work/platform into main
+27a6e5b Merge branch work/engine
+533e95d chore: checkpoint pre-merge WIP
+84f4b41 feat(engine): Phase 1 executor, scheduler, state-persister, guard-hooks
+4badf27 feat(platform): Phase 1 worktree, run-dir, streaming shell, MCP tools
+a77ee11 feat(contracts): Phase 0 cross-worker contracts
+```
+
+---
+
+## Remaining Work
+
+### Phase 2 (Ready to Dispatch)
+- Worker A (Commands): Wire run.ts -> DagExecutor, live HUD --watch, dynamic team.ts windows, merge queue
+- Worker D (Content): Update templates, docs, DESIGN.md, AGENTS.md for v0.3
+
+### Known Technical Debt
+1. Executor has no per-node timeout/AbortSignal
+2. KimiWireClient cannot restart with per-task env vars
+3. runShellStreaming uses raw chunks instead of line-buffering
+4. State persister lacks atomic writes (write-to-temp-then-rename)
+5. getProjectRoot() spawns sync shell on every call — should cache
+
+---
+
+## Risk Assessment
+
+| Category | Level | Rationale |
+|----------|-------|-----------|
+| Type safety | Low | All new code typed; tsc passes |
+| Runtime correctness | Low | Reviewer found and fixed deadlock/traversal bugs |
+| Backward compatibility | Very Low | All changes additive; existing exports untouched |
+| Security | Low | Path traversal sanitized; guards are best-effort heuristic |
+| Merge conflict (future) | Low | Clean boundaries; contract layer isolates changes |
+
+---
+
+## Files Changed Summary
+
+New files: 12
+Modified files: 9
+Deleted files: 0
+Lines added: ~830
+Lines removed: ~49
+
+---
+
+Report generated by Integration Worker. Phase 1 complete.

package/docs/post-0793-hardening-roadmap.md

@@ -0,0 +1,123 @@
+# OMK Post-0.79.3 Algorithm Hardening Roadmap
+
+> Package version: `open-multi-agent-kit@0.79.3`  
+> Runtime contract family: `v1.2`  
+> Release channel: `pre-1.0`  
+> Last updated: 2026-06-16
+
+## 1. Current state
+
+OMK v0.79.3 already moved past the "single Kimi wrapper" stage. The following native-orchestrator hardening is already in place:
+
+- `RuntimeHealthVector` and health-aware routing in `RuntimeRouter`.
+- Authority policy resolver (`authority`/`primary`/`omk` → concrete provider).
+- Evidence-required blocking in `RuntimeBackedTaskRunner` and `CompiledDagExecutor`.
+- Advisory-only runtime boundary for API providers (DeepSeek, Kimi API, local-llm, MiMo).
+- Native turn risk classifier with confidence/matched-signal trace.
+- Per-turn route/result artifacts under `.omk/runs/<runId>/turns/`.
+- Headroom compaction guard that preserves required structural context.
+- Theme/version sync gate.
+
+This document describes the next stages of algorithm hardening and how to execute them safely.
+
+## 2. Hardening philosophy
+
+1. **Contract-first**: change types and contracts before implementations.
+2. **Evidence-driven**: every gate must be replayable; declarations are not evidence.
+3. **Runtime-mode authority**: authority belongs to `(provider, runtimeMode)`, not provider identity alone.
+4. **Fail-closed by default**: missing authority, missing evidence, or unknown health must block, not fall back silently.
+5. **Backward compatible**: existing Kimi chat smoke tests and public CLI behavior must keep passing.
+6. **Gradual rollout**: use feature flags, staged tool authority modes (`shadow` → `warn` → `enforce`), and isolated test files.
+
+## 3. Phase roadmap
+
+### Phase 1 — Foundation (contract stabilization)
+
+**Goal**: make authority, safety, and health first-class contracts so later phases do not fight the type system.
+
+| Task | Deliverable | Acceptance |
+|------|-------------|------------|
+| P1.1 Runtime-mode authority matrix | `src/runtime/authority-matrix.ts` + matrix doc update | Single source of truth; provider-maturity.md aligned |
+| P1.2 `AgentTask.safety` elevation | `AgentTask.safety` required field + `capsuleToTask` injection | TypeScript compile fails if adapter ignores safety |
+| P1.3 Tri-state health vector v2 | `HealthState` + probe cache + adaptive TTL | Unknown penalized less than fail; all adapters return v2 or unknown |
+
+**Verification**: `npm run check`, `npm run version:check`, existing tests still pass.
+
+### Phase 2 — Evidence semantics v2
+
+**Goal**: separate declared evidence requirements from actual observations.
+
+| Task | Deliverable | Acceptance |
+|------|-------------|------------|
+| P2.1 Evidence model split | `EvidenceRequirement` vs `EvidenceObservation` types | No function treats declaration as proof |
+| P2.2 Observation extraction | Extractors for metadata/stdout/artifact/file | Each observation has timestamp, source, replay flag, redaction flag |
+| P2.3 Runtime evidence gate v2 | `RuntimeBackedTaskRunner` uses observations | Pre-check is declaration-only; post-check is observation-based |
+| P2.4 DAG executor alignment | `CompiledDagExecutor` uses same observation model | `checkNodeEvidence` returns observations, not gate marks |
+
+**Verification**: New negative tests: missing observation → exit 78; declared gate without observation → not satisfied.
+
+### Phase 3 — Observability and audit
+
+**Goal**: make every turn replayable and auditable through graph memory and private artifacts.
+
+| Task | Deliverable | Acceptance |
+|------|-------------|------------|
+| P3.1 Prompt payload separation | `DagNode.name` is a redacted label; full prompt stored privately | Public summary contains no compiled prompt |
+| P3.2 Turn audit graph materialization | Turn/ProviderRoute/Evidence nodes in local graph | Query `run → provider → evidence` works |
+| P3.3 Replay index with artifact hashes | `.omk/runs/<runId>/replay-index.json` | All artifact refs are hash-matched |
+
+**Verification**: `omk graph view` shows audit nodes; replay index validates against filesystem.
+
+### Phase 4 — Release gate hardening
+
+**Goal**: make authority and evidence failures part of the release pipeline.
+
+| Task | Deliverable | Acceptance |
+|------|-------------|------------|
+| P4.1 Tool-authority enforce smoke matrix | `scripts/authority-smoke.mjs` | enforce/warn/shadow cases pass |
+| P4.2 Health-degraded routing tests | Tests for unknown/fail health states | Routing scores reflect tri-state correctly |
+| P4.3 Evidence-v2 negative tests | Missing observation tests | Failures produce exit 78 + diagnostic |
+| P4.4 CI integration | GitHub Actions runs authority smoke | CI fails on authority regression |
+
+**Verification**: `npm run release:check` includes new smoke matrix.
+
+## 4. Dependency graph
+
+```text
+P1.1 authority matrix
+    ├── P1.2 safety contract
+    │       ├── P2.1 evidence model split
+    │       │       ├── P2.3 runtime evidence gate v2
+    │       │       ├── P2.4 DAG executor alignment
+    │       │       ├── P3.1 prompt payload separation
+    │       │       └── P3.2 audit graph materialization
+    │       └── P4.1 tool-authority enforce smoke
+    └── P1.3 health vector v2
+            └── P4.2 health-degraded routing tests
+```
+
+## 5. Rollback strategy
+
+- Each phase lives in a separate feature branch or at minimum a separate commit.
+- Phase 1 changes are foundational; if they break main, revert immediately and re-plan.
+- Phases 2–4 can be toggled via environment flags if implementations are feature-flagged:
+  - `OMK_EVIDENCE_MODEL=v2`
+  - `OMK_HEALTH_VECTOR=v2`
+  - `OMK_PROMPT_PAYLOAD=private`
+- Keep existing tests green; add new tests for new behavior; never delete old tests until a full release passes.
+
+## 6. Success criteria
+
+1. `npm run check` passes after every phase.
+2. `npm run release:check` passes after Phase 4.
+3. All new negative tests pass.
+4. Provider-maturity.md and hardening.md reflect runtime-mode authority.
+5. No compiled prompt appears in public graph nodes or run summaries.
+6. Every high-risk turn leaves replayable evidence artifacts.
+
+## 7. Related documents
+
+- `docs/native-root-runtime-hardening.md`
+- `docs/provider-maturity.md`
+- `docs/algorithm-hardening-playbook.md`
+- `.omk/runs/post-0793-hardening-2026-06-16/orchestration-spec.md`

package/docs/provider-maturity.md

@@ -0,0 +1,46 @@
+# Provider maturity
+
+This page documents provider status for the current source tree.
+
+## Current source target
+
+- Package version: `0.80.0`
+- Runtime contract family: `v1.2`
+- Release channel: `pre-1.0`
+
+## Runtime-mode authority matrix
+
+Authority belongs to `(provider, runtimeMode)`, not provider identity alone. The source of truth is `src/runtime/authority-matrix.ts`.
+
+| Runtime mode | Authority class | Allowed authority | Current maturity |
+| --- | --- | --- | --- |
+| `kimi:api` | advisory API | read, review, vision, advisory tool-calling | Mature read/review path. No direct workspace write/shell/merge authority. |
+| `kimi:wire` / `kimi:cli` | OMK-controlled compatibility path | read, review, write, patch, vision, tool-calling | Compatibility authority for edits only when routed through OMK controls. Shell/merge stay separately gated. |
+| `mimo:api` | advisory API | read, review, thinking | Default model provider for advisory/thinking lanes. No direct workspace write authority. |
+| `deepseek:api` | advisory API | read, review | Opportunistic read/review/QA/research. Write, MCP, shell, merge blocked. |
+| `glm:api` | advisory API | read, review | Advisory/thinking path; broader release-gate coverage pending. |
+| `codex:cli` | bounded CLI | read, review, write, patch, shell | Workspace authority only under OMK approval/sandbox policy. Merge withheld. |
+| `opencode:cli` | bounded CLI | read, review, write, patch, shell | Compatibility path; availability depends on local CLI and auth. |
+| `commandcode:cli` | bounded CLI | read, review, write, patch, shell | Compatibility path; availability depends on local CLI and auth. |
+| `local-llm:api` | advisory API | read, review | Local preview path. API runtime rejects direct shell/tool-calling authority. |
+
+`omk provider list --json` also merges user-local provider configuration, so local output may include custom providers or changed enabled/configured flags.
+
+## Routing rules to preserve
+
+- OMK is the root orchestrator; individual providers are adapters or worker lanes.
+- Authority/write/merge routes must stay with an authority-capable provider unless a tested contract grants another provider that authority.
+- Advisory API runtimes must not be documented as direct workspace-write, shell, MCP, or merge authorities.
+- Provider setup commands store environment variable names and metadata, not raw secret values.
+- Optional provider lanes may skip or fall back depending on route criticality and failure type.
+
+## Verification commands
+
+```bash
+npm run build:clean
+node dist/cli.js provider list --json
+node dist/cli.js provider doctor kimi --json --soft
+node --test test/provider-routing.test.mjs test/runtime-router.test.mjs test/provider-tool-contracts.test.mjs
+```
+
+Run these before claiming provider-maturity changes are release-ready.

package/docs/runtime-architecture.md

@@ -0,0 +1,89 @@
+# OMK Runtime Architecture
+
+## Overview
+
+OMK CLI V2 implements a runtime pipeline that separates control-plane (OMK orchestration) from model-facing (provider prompt). The key principle: **"모델에게는 작은 NLP prompt만. 런타임에는 sidecar만. 사용자에게는 theme/NLG만."**
+
+## Pipeline
+
+```
+User Input / Slash Command
+  → CommandBus (src/runtime/command-bus.ts)
+  → IntentClassifier (src/runtime/debloat-nlp.ts: classifyIntent)
+  → CapabilitySelector (src/runtime/debloat-nlp.ts: selectCapabilities)
+  → RuntimeSidecar Builder (src/runtime/debloat-nlp.ts: compileBloatToNlp)
+  → NLP Prompt Compiler + Filtered MCP Config
+  → ProviderAdapter + Provider Runtime
+  → ProviderEventNormalizer (src/runtime/provider-event-normalizer.ts)
+  → OmkEventBus (src/runtime/contracts/command-envelope.ts)
+  → OutputRouter (src/runtime/output-router.ts)
+  → ThemeRenderer / NlpRenderer / JsonRenderer / NlgRenderer
+```
+
+## Core Modules
+
+| Module | File | Purpose |
+|--------|------|---------|
+| CommandBus | `src/runtime/command-bus.ts` | Routes slash commands to handlers |
+| IntentClassifier | `src/runtime/debloat-nlp.ts` | Classifies user intent (status/chat/code_edit/etc.) |
+| CapabilitySelector | `src/runtime/debloat-nlp.ts` | Selects required/optional MCP, skills |
+| RuntimeSidecar | `src/runtime/debloat-nlp.ts` | Builds sidecar metadata (provider/model/risk/sandbox) |
+| MCP Config Filter | `src/runtime/debloat-nlp.ts` | Per-turn MCP config filtering |
+| Provider Runtime Selector | `src/runtime/debloat-nlp.ts` | Selects kimi-event vs kimi-print |
+| ProviderEventNormalizer | `src/runtime/provider-event-normalizer.ts` | Converts raw provider events to OmkEvent |
+| OutputRouter | `src/runtime/output-router.ts` | Routes OmkEvent to appropriate renderer |
+| ThemeRenderer | `src/runtime/renderers.ts` | Rich terminal output with ThemePalette |
+| NlpRenderer | `src/runtime/renderers.ts` | Plain text bilingual output |
+| JsonRenderer | `src/runtime/renderers.ts` | Structured JSON output |
+| NlgRenderer | `src/runtime/nlg-renderer.ts` | Consent-aware NLG reports |
+| ReasoningTrace | `src/runtime/reasoning-trace.ts` | Evidence summaries, privacy redaction |
+| UI Components | `src/runtime/ui-components.ts` | statusCard, providerCard, errorBox, etc. |
+| SlashCommands | `src/runtime/slash-commands.ts` | /model, /status, /theme, /help handlers |
+
+## Key Types
+
+- `CommandEnvelope`: Normalized CLI input (kind, source, rawText, outputProfile)
+- `RequestIntent`: status|resume|memory_query|repo_read|code_edit|debug_error|web_research|plan|chat|unknown
+- `CapabilityPlan`: availableMcp[], requiredMcp[], optionalMcp[], disabledMcp[], selectedSkills[]
+- `RuntimeSidecar`: provider, model, intent, risk, sandbox, requiredMcp, optionalMcp, disabledMcp
+- `OmkEvent`: turn_started|progress|mcp_status|warning|result|error|turn_finished
+- `ReasoningTrace`: intent, plan, execution, evidence, result, privacy
+
+## Invariants
+
+- I-001: availableMcp ≠ prompt MUST activate
+- I-004: optional MCP failure = warning, not fatal
+- I-005: raw provider events not visible in stdout
+- I-006: status requiredMcp=[]
+- I-008: slash commands go through CommandBus
+- I-011: kimi-print is debug-only
+
+## Theme System
+
+- `src/cli/theme/theme-registry.ts`: ThemePalette with SemanticToken, 5 palettes (omk/minimal/mono/dark/light)
+- `src/cli/theme/theme-resolver.ts`: Resolves active theme from --theme flag → OMK_THEME env → project config → user config
+
+## i18n
+
+- `src/util/i18n.ts`: Bilingual (KO/EN) support via `t()` function
+- Keys: nlp.*, normalizer.*, ui.*, nlg.*
+
+## CLI v2
+
+- `src/cli/v2/cli-v2-skeleton.ts`: Clipanion-based commands (Chat, Run, Status, Model, Doctor, Memory, Theme)
+- `src/cli/v2/provider-commands.ts`: Provider + Model commands
+- `src/cli/v2/workflow-commands.ts`: Workflow + Consent commands
+- `src/cli/v2/chat-repl.ts`: Interactive REPL with pipeline integration
+- `src/cli/v2/persistent-memory.ts`: Section 17 memory store
+- Enable with `OMK_CLI_V2=1`
+
+## Providers
+
+- Default: mimo (mimo-v2.5-pro) via `https://api.xiaomimimo.com/v1`
+- Kimi: kimi-api (direct Moonshot HTTP), kimi-wire (kimi --wire binary)
+- Others: codex, deepseek, opencode, openrouter, qwen, local-llm
+
+## Tests
+
+- `test/v2-regression.test.mjs`: 10 tests (20.1-20.7) — all PASS
+- `test/cli-v2-gating.test.mjs`: 7 tests — all PASS

package/docs/use-cases/evidence-gated-coding-agents.md

@@ -0,0 +1,52 @@
+# Evidence-gated coding agents
+
+## Short answer
+
+Evidence-gated coding means an agent cannot simply say "done." It must produce verifiable artifacts such as diffs, command output, test results, review logs, or DAG run records before a task is treated as complete.
+
+## What does evidence-gated mean in OMK?
+
+OMK compiles a task into a DAG, assigns scoped lanes, runs provider-specific agents, collects evidence, and writes replayable artifacts under `.omk/runs/<run-id>/`. If a required evidence gate is missing, completion is blocked instead of assumed.
+
+## How OMK implements it
+
+1. The user goal becomes an input envelope.
+2. The envelope compiles into a DAG with lane-level acceptance and evidence expectations.
+3. Lanes execute with explicit read/write/shell/merge authority.
+4. Evidence is collected: command output, diff, artifact, metric, or review.
+5. A verify gate checks the evidence before completion is claimed.
+
+## Example
+
+```bash
+omk do "review this repo for release risk" --dry-run --json
+```
+
+Dry-run artifacts:
+
+```txt
+.omk/runs/<run-id>/input-envelope.json
+.omk/runs/<run-id>/dag.json
+.omk/runs/<run-id>/dag-compile-report.json
+```
+
+Executing the compiled DAG adds loop artifacts such as `loop-state.json` and `loop-decisions.jsonl`.
+
+## How do I verify it locally?
+
+```bash
+npm run verify:no-kimi
+npm run proof:check
+```
+
+Source-controlled proof bundles are listed in the [proof index](https://github.com/dmae97/open-multi-agent-kit/blob/main/proof/PROOF_INDEX.md).
+
+## What this does not claim
+
+Evidence gates do not prove a provider has write authority, do not prove a release is safe, and do not replace full CI. Safety claims are scoped to the exact adapter, command, and gate that produced them.
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [Replayable agent runs](replayable-agent-runs.md)
+- [Provider routing for AI coding](provider-routing-for-ai-coding.md)