open-multi-agent-kit 0.78.0

package/docs/2026-05-18-critical-issues-and-improvements.md

@@ -0,0 +1,441 @@
+# 2026-05-18 Critical Issues
+
+## Scope
+
+분석 범위는 현재 `open-multi-agent-kit` working tree 전체다. 병렬 subagent fan-out으로 architecture, source archaeology, security, infra/release, QA/test, docs 방향성을 분리 검토했고, 로컬에서 핵심 파일을 추가 확인했다.
+
+주의:
+
+- 이 문서는 최초 발견 사항과 이후 안정화 결과를 함께 기록한다.
+- secret 값은 출력하지 않았다.
+- “Critical/P0”는 public release 또는 기본 런타임 안전성 전에 반드시 해결해야 하는 항목이다.
+
+## Stabilization status after 2026-05-18 fixes
+
+Resolved/mitigated in source and covered by regression tests:
+
+- MCP raw permission await bypass: fixed for tool/resource/prompt paths.
+- Standard `tools/call`: now routes through governance redaction/audit before returning MCP-compatible content.
+- MCP lifecycle: request timeout, notification shape, pending close rejection, stdio close handling, streamable HTTP session/header behavior.
+- Fresh init: project-local scopes and `omk-core-verified` baseline; `--local-user` remains explicit high-trust mode.
+- Kimi CLI / `.kimi`: DAG runner honors `KIMI_BIN`; `kimi-wire` is opt-in until isolated HOME/MCP/hook parity exists; project hook commands are absolute inside isolated HOME.
+- Runtime MCP merge: project `.kimi/.omk` relative direct args and simple inline shell paths are normalized against project root.
+- Secret handling: shell/evidence/quality/state/attempt/event/checkpoint persistence paths redact secret-looking strings; runtime secret scan covers selected `.omk/.kimi` trust-boundary files.
+- Checkpoint restore: dirty worktree requires explicit force and protected patch paths are rejected.
+
+Still operationally relevant:
+
+- Existing ignored/generated `.omk/*` and `.kimi/*` artifacts can be stale relative to fixed source templates and should be checked against current scoped runtime policy before demos/releases.
+- `mcp_scope = all`, `skills_scope = all`, and `hooks_scope = all` are trusted local-user modes, not fresh-project defaults.
+- Current generated root roles include `security`; docs/prompts should list it consistently while still treating role availability as harness-scoped.
+- `team`/worktree mode remains experimental until merge handoff and verification reconstruction are consistently evidenced.
+
+## Executive summary
+
+This section is historical as of the 2026-05-18 stabilization pass. The original review found three release-blocking risk classes; current source/runtime docs now mark the first two as resolved or scoped, and the remaining items are tracked as follow-up hardening rather than active default-runtime blockers.
+
+1. **Historical: MCP trust boundary bypass.** `McpHost` raw tool/resource/prompt paths previously missed `await` on async permission checks; current source marks this fixed with regression coverage.
+2. **Historical: default runtime surface drift.** Earlier generated files described or enabled broad/full MCP behavior. Current `.omk/runtime-preset.json` is `omk-core-verified`, `.omk/config.toml` uses project scope for MCP/skills/hooks, and current project `.omk/mcp.json` / `.kimi/mcp.json` do not list secret-backed project MCP servers.
+3. **Partially mitigated: side-effect, evidence, and restore hardening.** Current source records AbortSignal propagation, redaction, runtime secret scan, and checkpoint dirty-worktree/protected-path guards; related P1/P2 follow-ups remain historical backlog items unless revalidated against current files.
+
+## P0 / Critical
+
+### P0-1. MCP host raw operations bypass permission policy
+
+**Status:** Resolved in source; regression coverage: `test/mcp-host-permissions.test.mjs`.
+
+**Severity:** Critical  
+**Area:** MCP authorization / tool trust boundary
+
+**Evidence**
+
+- `src/mcp/host.ts:370-400` — `McpHost.callTool`
+- `src/mcp/host.ts:509-536` — `McpHost.readResource`
+- `src/mcp/host.ts:559-586` — `McpHost.getPrompt`
+- `src/mcp/host.ts:591-602` — `checkPermission` is async
+
+**Problem**
+
+`checkPermission` returns `Promise<boolean>`, but raw callers use it as `if (!this.checkPermission(...))`. A Promise is truthy, so denial is never triggered on those raw paths. `governedCallTool` correctly uses `await`, but `callTool`, `readResource`, and `getPrompt` do not.
+
+**Impact**
+
+- denyServers / allowServers policy can be bypassed.
+- A connected MCP server can expose tools/resources/prompts even when host policy should block them.
+- Any higher-level code path using raw `callTool` instead of governed call inherits the bypass.
+
+**Exploit scenario**
+
+A project or user config denies a remote MCP server, but a code path calls `host.callTool(name, args, serverHint)` directly. The Promise-based permission check passes by truthiness, and the remote MCP executes.
+
+**Fix**
+
+- Add `await` in `callTool`, `readResource`, `getPrompt`.
+- Prefer routing all operations through governed variants or split raw APIs as internal-only.
+- Add tests for denied server/tool/resource/prompt access.
+
+**Acceptance tests**
+
+- Denied server cannot execute `callTool`.
+- Denied server cannot `readResource`.
+- Denied server cannot `getPrompt`.
+- Tests must fail on the current implementation and pass after adding `await`.
+
+---
+
+### P0-2. Secret-backed/full MCP runtime is active in project config and conflicts with safe baseline
+
+**Status:** Resolved for current source and current checked generated/runtime docs; still audit local ignored runtime artifacts before release/demo.
+
+**Severity:** Critical  
+**Area:** MCP startup / secret boundary / runtime default
+
+**Evidence**
+
+Historical evidence from the original review:
+
+- `.omk/config.toml` previously used `mcp_scope = "all"`, `skills_scope = "all"`, and `hooks_scope = "all"`.
+- `.omk/runtime-preset.json` / `.omk/runtime-presets.json` previously pointed at `omk-parallel-orchestrator`.
+- Project MCP files previously included or exposed broader/secret-backed surfaces.
+
+Current 2026-05-19 check:
+
+- `.omk/config.toml` uses `mcp_scope = "project"`, `skills_scope = "project"`, and `hooks_scope = "project"`.
+- `.omk/runtime-preset.json` uses `id = "omk-core-verified"`.
+- Current project `.omk/mcp.json` and `.kimi/mcp.json` list no project secret-backed MCP server entries; `omk-core-verified` keeps `omk-project` as the baseline project-local MCP hint.
+
+**Problem**
+
+The original repository state did not match the conservative `omk-core-verified` baseline described by AGENTS/docs. Current checked files now align on project-scoped MCP/skills/hooks and avoid claiming that broad MCP is fully enabled by default.
+
+**Impact**
+
+- Local, CI, Kimi, Codex, and OMK runtime surfaces can diverge.
+- Unpinned or compromised MCP packages can receive loaded credentials at startup.
+- Debugging and release evidence becomes non-reproducible because the active MCP set depends on user-local files and network-installed packages.
+
+**Exploit scenario**
+
+A malicious or compromised `npx` MCP package starts through a project-level MCP wrapper that sources user secret env files, then exfiltrates the environment during MCP startup.
+
+**Fix**
+
+- Make `omk-core-verified` the default public preset, or explicitly document `omk-parallel-orchestrator` as high-trust opt-in.
+- Keep fresh project MCP minimal: `omk-project` and possibly readonly filesystem only.
+- Move secret-backed MCP to user scope or explicit `--local-user` / `--with-mcp` setup.
+- Pin MCP package versions and prefer lockfile-backed installation.
+
+**Acceptance tests**
+
+- Fresh init does not create secret-backed remote MCP entries in project config.
+- Runtime preset default matches docs/templates.
+- `omk doctor` reports config drift between `.omk/mcp.json` and `.kimi/mcp.json` without leaking env values.
+
+---
+
+### P0-3. MCP client and stdio transport can hang indefinitely
+
+**Status:** Resolved/mitigated in source; regression coverage: `test/mcp-client-lifecycle.test.mjs`, `test/mcp-streamable-http.test.mjs`, `test/mcp-host-permissions.test.mjs`.
+
+**Severity:** Critical  
+**Area:** MCP lifecycle / reliability
+
+**Evidence**
+
+- `src/mcp/client.ts:176-188` — `sendRequest` has no timeout
+- `src/mcp/transports/stdio.ts:64-100` — `connect` resolves after spawn/stdin/stdout setup, not after protocol readiness
+- `src/mcp/transports/stdio.ts:111-130` — malformed stdout is ignored
+- `startupTimeoutMs` exists on `McpServerConfig` but is not enforced by `McpClientSession.sendRequest`.
+
+**Problem**
+
+If an MCP server starts but never responds, prints malformed stdout, or dies after a pending request is created, the request can hang. Startup timeout is represented in config but not consistently wired into request lifecycle.
+
+**Impact**
+
+- `omk mcp doctor/test`, host startup, and runtime MCP calls can stall.
+- A single bad MCP server can block orchestration.
+- CI and local test flakiness increase, especially around slow `npx` startup.
+
+**Fix**
+
+- Enforce startup timeout around `connect + initialize`.
+- Add per-request timeout in `sendRequest`.
+- Reject all pending requests on child close, not only on transport error.
+- Before initialization, treat non-JSON stdout as a startup failure with a sanitized diagnostic.
+
+**Acceptance tests**
+
+- Server that never responds fails within configured timeout.
+- Server that prints invalid stdout before initialize fails with clear diagnostic.
+- Server close rejects pending requests.
+
+---
+
+### P0-4. Executor timeout/abort does not cancel underlying runner side effects
+
+**Status:** Resolved for current TaskRunner/Kimi/provider/shell paths via `AbortSignal` propagation; keep extending this contract for new runners.
+
+**Severity:** Critical  
+**Area:** DAG executor / side-effect containment
+
+**Evidence**
+
+- `src/orchestration/executor.ts:359-385` — `nodeRunner.run(node, env)` is raced against timeout/abort promises.
+- `src/contracts/orchestration.ts` `TaskRunner` does not accept `AbortSignal`.
+
+**Problem**
+
+The executor marks a node failed when timeout/abort wins the race, but the underlying runner keeps running because it receives no cancellation signal. That runner can still mutate files, write logs, update worktrees, or produce output after the scheduler has already moved on.
+
+**Impact**
+
+- Timed-out/aborted nodes can cause late writes after failure.
+- Evidence and state can lie about what actually changed.
+- Parallel runs may merge or verify while a “failed” task is still mutating state.
+
+**Fix**
+
+- Extend `TaskRunner.run(node, env, signal)` or add cancellation hooks.
+- Wire signal to Kimi child process, provider runner, shell runner, and worktree cleanup.
+- Kill or quarantine timed-out worktrees before dependents proceed.
+
+**Acceptance tests**
+
+- A timed-out runner attempting a delayed file write cannot mutate the main workspace after timeout.
+- Abort cancels child process and no late state updates occur.
+- State records timeout reason and cleanup result.
+
+---
+
+### P0-5. Evidence and quality logs can persist secret text
+
+**Status:** Mitigated across shell/evidence/quality/state/attempt/event/checkpoint paths; runtime scan added for selected `.omk/.kimi` trust-boundary files.
+
+**Severity:** Critical  
+**Area:** secret redaction / evidence storage
+
+**Evidence**
+
+- `src/orchestration/evidence-gate.ts:504-515` stores `stdoutTail`, `stderrTail`, `evidenceText`, `message`.
+- `src/orchestration/state-persister.ts:8-27` redacts by secret-like object keys, not arbitrary secret-looking substrings.
+- `src/util/shell.ts:75-79`, `src/util/shell.ts:141-149` can write raw output to log files.
+- `src/mcp/quality-gate.ts:281-293` stores quality gate logs.
+
+**Problem**
+
+Secret redaction is key-based in state persister and not applied uniformly to command output. If a malicious or accidental command prints environment values, evidence and log artifacts can persist them.
+
+**Impact**
+
+- `.omk/runs/**/state.json`, decision traces, quality logs, and shell logs may retain sensitive output.
+- Secret-scan may pass because `.omk/` is ignored or outside the tracked scan target.
+
+**Fix**
+
+- Use the centralized `src/mcp/secret-scanner.ts` redactor for all diagnostic text before persistence.
+- Redact stdout/stderr tails before storing evidence.
+- Add runtime scan mode covering selected `.omk`/`.kimi` trust-boundary files and logs.
+
+**Acceptance tests**
+
+- A command-pass gate that prints a fake token stores only redacted text.
+- Quality gate logs redact known token patterns.
+- Runtime secret scan reports file path and finding type without printing the secret.
+
+## P1 / High
+
+### P1-1. Dynamic fallback nodes are not resume-stable
+
+**Evidence:** `src/orchestration/executor.ts:487-503`, `src/orchestration/executor.ts:523-582`
+
+Fallback nodes are pushed into `dag.nodes` at runtime. On resume, the original DAG may not contain those dynamically-added nodes or rewritten dependencies, so fallback progress can be lost or replayed incorrectly.
+
+**Fix:** persist dynamic DAG mutations or reconstruct them from saved state during resume. Add a resume regression for `fallbackRole`.
+
+---
+
+### P1-2. Streamable HTTP transport performs duplicate initialize and does not propagate headers to SSE
+
+**Evidence:** `src/mcp/transports/streamable-http.ts:24-55`, `src/mcp/client.ts`
+
+The transport sends `initialize` during `connect`, then `McpClientSession.initialize()` sends another initialize. `EventSource` is also created without custom auth headers.
+
+**Fix:** make transport connect transport-only and let `McpClientSession.initialize()` own the MCP handshake. Use a streaming implementation that supports auth headers or fail actionably.
+
+---
+
+### P1-3. PR review workflow runs PR code with write-token permissions
+
+**Evidence:** `.github/workflows/omk-review.yml:13-15`, `.github/workflows/omk-review.yml:38-61`
+
+The same job checks out PR code, builds/runs it, and has `pull-requests: write` to post comments.
+
+**Fix:** split read-only analysis from minimal-permission comment posting.
+
+---
+
+### P1-4. Secret scan excludes ignored runtime trust-boundary files
+
+**Evidence:** `.gitignore` excludes `.omk/` and `.kimi/`; `scripts/secret-scan.mjs` scans tracked + untracked non-ignored files.
+
+Runtime trust files such as `.omk/mcp.json`, `.omk/kimi.config.toml`, `.omk/hooks/**`, `.kimi/hooks/**`, `.kimi/mcp.json` can contain secret-loading commands or logs while `npm run secret:scan` still passes.
+
+**Fix:** add `secret:scan:runtime` with curated runtime paths and redacted output.
+
+---
+
+### P1-5. `runShell` inherits full environment and global `OMK_SUDO=1` can escalate package-manager commands
+
+**Evidence:** `src/util/shell.ts:45`, `src/util/shell.ts:64-67`
+
+Package scripts and quality gates can inherit cloud/provider tokens. If `OMK_SUDO=1` is set globally, allowlisted package-manager/docker operations can run under sudo unexpectedly.
+
+**Fix:** minimal env by default for untrusted scripts; explicit env passthrough; remove global sudo switch or make it per-call and never default for package managers/docker.
+
+---
+
+### P1-6. Hook drift: `.kimi` guard is weaker than `.omk` guard
+
+Infra review found `.omk/hooks/pre-shell-guard.sh` and `.kimi/hooks/pre-shell-guard.sh` checksums differ. Depending on runtime surface, the same shell command can be blocked in one context and allowed in another.
+
+**Fix:** treat `.omk/hooks` as canonical generated source and add drift tests comparing guard behavior on fixture commands.
+
+---
+
+### P1-7. Checkpoint restore can mutate a dirty worktree without a safety gate
+
+**Evidence:** `src/util/checkpoint.ts:122-178`
+
+Restore applies `git apply` or `patch` without clean worktree check or pre-restore backup.
+
+**Fix:** refuse restore unless worktree is clean or explicit `--force` is provided; create pre-restore checkpoint automatically; print affected files before applying.
+
+---
+
+### P1-8. Release tag is not checked against package version
+
+**Evidence:** `.github/workflows/release.yml:3-6`, publish job
+
+The release workflow triggers on `v*`, but publish does not assert `github.ref_name === v${package.json.version}`.
+
+**Fix:** add a pre-publish exact-match step comparing tag name to `package.json.version`.
+
+---
+
+### P1-9. Tarball audit validates local checkout for some checks instead of extracted tarball
+
+**Evidence:** `scripts/package-audit.mjs:635-669`, `scripts/package-audit.mjs:378`, `scripts/package-audit.mjs:450-471`
+
+`--tarball` mode sets file sizes/unpacked size to `0` and some checks read local files instead of extracted tarball contents.
+
+**Fix:** extract tarball to a temp directory and run all validations against extracted files.
+
+---
+
+### P1-10. CI diagnostics print environment/home metadata
+
+**Evidence:** `.github/workflows/ci.yml:26-33`
+
+CI prints env keys/values matching `omk|kimi|node|home` and lists `$HOME`.
+
+**Fix:** print only allowlisted key names and versions. Avoid env values and home directory listings.
+
+## P2 / Medium
+
+### P2-1. `protect-secrets` hook scans only `tool_input.content`
+
+Replacement-style edit tools can carry new text in fields like `new_string`, `replacement`, `old_str/new_str`, bypassing content-only scanning.
+
+**Fix:** recursively scan every string field in tool input and add post-edit diff scan.
+
+### P2-2. Worker count / “all agents” semantics are inconsistent
+
+**Evidence:** `.omk/agents/root.yaml`, `src/commands/run.ts:187-193`, `src/commands/parallel.ts:366-372`, `.omk/config.toml`
+
+The root exposes 16 aliases / 14 role files, but run/parallel hard-cap parsed worker count at `6` and project config sets `runtime.max_workers = 4`.
+
+**Fix:** document “all roles available” separately from “all roles concurrently running.” Add an explicit `--all-roles` planning mode if needed, but keep execution concurrency resource-bounded.
+
+### P2-3. CLI command contract still has many direct `process.exit` calls
+
+Search found direct `process.exit` calls in multiple command modules including `run.ts`, `parallel.ts`, `chat.ts`, `doctor.ts`, `spec.ts`, `plan.ts`, `menu.ts`, `project-index.ts`, `research.ts`, `snip.ts`, `google.ts`, `screenshot.ts`.
+
+**Fix:** move automation-critical commands to typed results and let `src/cli/main.ts` handle process exit code.
+
+### P2-4. Dist freshness policy differs between local and CI
+
+`scripts/run-tests.mjs` enforces dist freshness locally unless `OMK_SKIP_DIST_FRESHNESS=1`, while CI/smoke paths often bypass after build steps.
+
+**Fix:** make build freshness an explicit manifest/hash gate in both local and CI.
+
+### P2-5. Test coverage has blind spots
+
+No direct tests for `McpHost` permission bypass were found. Critical files such as `src/mcp/host.ts`, `src/mcp/client.ts`, MCP transports, and checkpoint restore need focused regression tests.
+
+**Priority tests**
+
+1. MCP host permission denial
+2. MCP request timeout/child close
+3. executor late side-effect cancellation
+4. fallback resume stability
+5. redacted evidence output
+6. checkpoint dirty-worktree refusal
+7. `run-tests --summary-json` path containment
+8. JSON-RPC notifications omit `id`
+
+## Critical init artifact status
+
+No critical init artifacts were missing when this file was updated.
+
+- ✅ `AGENTS.md`
+- ✅ `.kimi/AGENTS.md`
+- ✅ `.omk/config.toml`
+- ✅ `.omk/agents/root.yaml`
+- ✅ `.kimi/mcp.json`
+- ✅ `.omk/hooks/pre-shell-guard.sh`
+- ✅ `.omk/hooks/protect-secrets.sh`
+- ✅ `.omk/memory/graph-state.json`
+
+## Recommended fix order
+
+Historical fix order from the 2026-05-18 review; items 1, 2, 3, 4, 7, 8, and 9 are now marked resolved/mitigated above where current files differ. Revalidate remaining backlog items before treating them as active defects.
+
+1. Fix MCP host permission bypass and add regression tests. — resolved.
+2. Enforce MCP startup/request timeout and reject pending requests on close. — resolved/mitigated.
+3. Reset/clarify default runtime preset and MCP scope. — resolved in current docs/runtime files.
+4. Add evidence/log redaction using the central secret scanner. — mitigated.
+5. Split PR review workflow permissions. — historical backlog; revalidate.
+6. Add release tag/package version gate. — historical backlog; revalidate.
+7. Harden executor cancellation and fallback resume. — cancellation mitigated; fallback resume remains historical backlog unless revalidated.
+8. Add runtime secret scan for `.omk`/`.kimi` trust files. — resolved with `secret:scan:runtime`.
+9. Harden checkpoint restore. — resolved/mitigated.
+10. Convert tarball audit to extracted-tarball validation. — historical backlog; revalidate.
+
+## Verification snapshot for this review
+
+Commands run locally by the lead agent:
+
+- `git status --short`
+- `omx doctor --team`
+- `omx list --json`
+- `omx hud --json`
+- targeted `ctx_tree`, `ctx_read`, `ctx_search`
+- `.omk` / `.kimi` hook checksum diff
+- `npm run -s yaml:check` — passed
+- `npm run -s lint` — passed
+- `npm run -s secret:scan` — passed
+- `npm run -s check` — passed
+
+Additional subagent-reported checks:
+
+- `npm run -s yaml:check` — passed
+- `npm run -s lint` — passed
+- `npm run -s check` — passed
+- `npm run -s secret:scan` — passed
+- targeted tests passed for `run-tests-harness`, `mcp-command`, `provider-routing`, `chat-startup`, `rust-safety-harness`, `orchestration` matches, `init-mcp-secrets`, `cli-timeout-preset`, and `goal`
+
+Not complete:
+
+- Full test suite pass was not proven in this lead run.
+- Release check/native build/package audit/smoke pack were not run by the lead agent.

package/docs/2026-05-18-project-direction.md

@@ -0,0 +1,223 @@
+# Project Direction — 2026-05-18
+
+## Summary
+
+open-multi-agent-kit(OMK)의 현재 방향성은 **provider-neutral verified agent runtime**이다. Kimi는 하나의 강한 adapter/provider lane일 뿐이며, OMK는 그 주변의 실행 제어면을 담당한다: DAG 실행, evidence gate, 로컬 그래프 메모리, MCP/skills/hooks 라우팅, provider fallback, run replay/inspect, HUD/cockpit 가시성, worktree 격리.
+
+핵심 문장:
+
+> Kimi writes. OMK coordinates, verifies, remembers, and guards.
+
+이 방향은 `README.md`, `ROADMAP.md`, `MATURITY.md`, init templates, `src/orchestration/*`, `src/goal/*`, `src/mcp/*`가 공통으로 지향하는 제품 축이다. 2026-05-18 안정화 이후 source/fresh-init 기준은 **project-local `omk-core-verified` baseline**으로 정렬되었고, 기존 생성 `.omk/*` artifact drift는 별도 운영 caveat로 취급한다.
+
+2026-05-24 이후 native root/runtime 알고리즘의 현재 후속 기준은
+[`native-root-runtime-hardening.md`](./native-root-runtime-hardening.md)와
+[`native-root-runtime-algorithms.md`](./native-root-runtime-algorithms.md)이다.
+이 문서는 방향성 기록으로 유지하며, ActionAtom/Novelty Guard 표현은
+구현 및 테스트가 확인된 범위와 구분한다.
+
+## Stabilization update — Kimi CLI / `.kimi`
+
+- Fresh init: project-local `.kimi/mcp.json`, project scopes, `omk-core-verified`.
+- Trusted local mode: `--local-user` 또는 `OMK_*_SCOPE=all`에서만 user/global `~/.kimi/mcp.json`, skills, hooks를 runtime에 결합한다.
+- Isolated Kimi HOME: Kimi auth는 보존하되, project hook command는 absolute path로 rewrite하여 temp HOME 상대경로 문제를 막는다.
+- DAG print runner: `KIMI_BIN`을 존중하고 `.kimi`/MCP runtime cache를 source project 기준으로 정규화한다.
+- `kimi-wire`: print runtime과 isolated HOME/MCP/hook parity가 완성될 때까지 opt-in(`OMK_ENABLE_KIMI_WIRE=1`)이다.
+- Runtime evidence: state/evidence/attempt/event/checkpoint artifacts는 secret-looking 문자열을 저장 전 redaction한다.
+
+## Current product thesis
+
+OMK는 단순 prompt pack, 범용 multi-model router, 또는 모델에게 모든 write/merge 권한을 넘기는 agent buffet가 아니다.
+
+OMK가 되어야 하는 것은 다음이다.
+
+- Kimi Code를 중심에 둔 local-first coding control plane
+- 작업을 goal / action atom / DAG / evidence / graph로 명시화하는 실행 런타임
+- 사람이 현재 실행 상태, 변경 파일, evidence, blocker, retry/fallback 이유를 볼 수 있는 운영 UI
+- remote provider와 MCP를 기본 신뢰가 아니라 **명시적 권한·증거·fallback 계약**으로 다루는 안전한 agent harness
+
+## Product pillars
+
+### 1. Stable verified Kimi core
+
+일상 사용 경로는 보수적으로 안정화해야 한다.
+
+```txt
+omk init → omk doctor → omk chat / omk plan → omk verify → omk summary / inspect
+```
+
+`MATURITY.md` 기준 stable surface는 `init`, `doctor`, `chat`, `hud`, `cockpit`, `plan`, `mode`, `runs/history`, `index`, `lsp`, `design`, `google`, `update`, `star`다. 이 경로는 public user가 매일 써도 되는 “boring reliable core”로 유지되어야 한다.
+
+### 2. IntentFrame / ActionAtom / DAG execution spine
+
+현재 런타임은 단일 prompt 실행에서 명시적 action graph로 이동 중이다.
+
+```txt
+User intent
+  → GoalSpec / IntentFrame
+  → ActionAtoms
+  → DAG nodes with routing, retries, timeout, evidence gates
+  → Executor / Scheduler
+  → Decision trace + run state
+  → Verify / Summary / Graph memory
+```
+
+관련 영역:
+
+- `src/goal/intent-frame.ts`
+- `src/goal/compiler.ts`
+- `src/orchestration/dag.ts`
+- `src/orchestration/executor.ts`
+- `src/orchestration/evidence-gate.ts`
+- `src/evidence/decision-trace.ts`
+
+v1.2 방향은 이 spine을 “있는 기능”이 아니라 “모든 자동화가 따르는 계약”으로 고정하는 것이다.
+
+### 3. Evidence-gated completion
+
+OMK의 차별점은 “done by narration”을 거부하는 것이다. 완료 판단은 다음 증거에 묶여야 한다.
+
+- 파일 존재 / diff 존재
+- command-pass 결과
+- review-pass 결과
+- run summary / report
+- provider fallback metadata
+- decision trace
+- replay/inspect artifact
+- graph edge: `Goal → Run → DagNode → EvidenceGate → Artifact`
+
+`omk verify --json`은 최소 완료 증거로 유지하고, 자동화가 소비하는 command는 stable JSON envelope를 제공해야 한다.
+
+### 4. Local-first graph memory and forensic audit
+
+그래프 메모리는 단순 요약 저장소가 아니라 audit substrate가 되어야 한다.
+
+- `.omk/memory/graph-state.json`을 project-local source of truth로 유지한다.
+- `.omk/memory/*.md`는 사람이 읽는 mirror/cache로 취급한다.
+- optional Kuzu backend는 고급 쿼리용으로 유지한다.
+- 기본 모드는 daemon/password 없는 local graph다.
+
+다음 단계는 `Run`, `Goal`, `DagNode`, `EvidenceGate`, `ProviderAttempt`, `FallbackEvent`, `Artifact`, `Decision`, `Risk` 노드를 명시하고 `verify`, `goal`, `parallel`, provider runtime이 일관된 edge를 기록하게 하는 것이다.
+
+### 5. Runtime presets as product modes
+
+프리셋은 설정 묶음이 아니라 제품 trust mode다.
+
+| Preset | Direction | Trust posture |
+|---|---|---|
+| `omk-core-verified` | everyday coding/refactor/debug baseline | conservative default |
+| `omk-parallel-orchestrator` | max parallel agent orchestration | high-trust, opt-in recommended |
+| `omk-ts-product` | strict TS/React/Next/Nest/API/UI work | product implementation lane |
+| `omk-worktree-team` | isolated parallel worktree lanes | merge/review gated |
+| `omk-release-guard` | release/security evidence gate | narrowed authority |
+| `omk-full-mcp` | all configured MCP integration | explicit high-trust mode |
+
+Source templates now generate `omk-core-verified` as the fresh-init active/default preset. 기존 repository-local `.omk/runtime*.json` 파일은 ignored/generated artifact일 수 있으므로, release/demo 전에는 `omk doctor`와 runtime secret scan으로 drift를 확인한다.
+
+권장 결정:
+
+1. public default는 `omk-core-verified`로 유지한다.
+2. `omk-parallel-orchestrator`는 “all agents / all MCP / full hooks”가 필요한 명시적 고신뢰 모드로 표시한다.
+3. full MCP와 secret-backed MCP는 release/security preset에서 자동 사용하지 않는다.
+
+### 6. Advisory provider lanes only
+
+DeepSeek 등 외부 provider는 당분간 write authority를 갖지 않는다.
+
+허용 방향:
+
+- explorer / reviewer / QA / planner / docs / research lane
+- low-risk, read-heavy, advisory output
+- Kimi fallback mandatory
+- provider attempt / fallback reason / final authority marker 기록
+
+금지 방향:
+
+- provider가 직접 merge/write authority 보유
+- provider fallback 실패가 evidence 없이 성공 처리
+- provider output이 graph/summary에 출처 없이 섞이는 것
+
+### 7. Operator visibility as core UX
+
+HUD/cockpit은 부가 기능이 아니라 OMK의 운영 면이다.
+
+보여야 하는 것:
+
+- active run / session / goal
+- worker state, role, ETA
+- changed files
+- TODOs
+- blockers
+- evidence gate status
+- provider route/fallback counts
+- MCP/skills/hooks inventory summary
+- run replay/inspect links
+
+`team`/tmux 모드는 이 가시성이 충분해질 때까지 experimental로 유지해야 한다.
+
+### 8. Resource-aware local execution
+
+OMK는 16GB/WSL/laptop에서도 안전하게 돌아가야 한다.
+
+- lite/standard/super profile 유지
+- bounded shell/wire output buffers
+- worker count는 resource profile과 명시 override가 모두 반영되도록 정리
+- all-scope MCP/skills/hooks는 high-trust opt-in으로 취급
+- default project execution은 가능한 한 project-local로 유지
+- bounded output buffers, request timeouts, abort signals는 성능 옵션이 아니라 reliability contract다.
+
+## Roadmap ordering
+
+### P0 — contract, security, runtime consistency
+
+1. MCP host permission/governance/redaction 유지
+2. MCP request/startup timeout 유지
+3. secret-backed MCP와 `mcp_scope = all`은 trusted local opt-in으로만 유지
+4. runtime preset source default는 `omk-core-verified`로 유지
+5. evidence/log/checkpoint/runtime artifact redaction 유지
+6. Kimi CLI `.kimi` isolated HOME / relative path parity 유지
+7. release tag/package version 일치 검증
+8. tarball audit를 실제 tarball extract 기준으로 유지
+
+### P1 — evidence and audit graph
+
+1. stable `CommandEnvelope<T>` / `EvidenceEnvelope` 정의
+2. graph/DAG/summary/workflow JSON 계약 확대
+3. provider fallback metadata coverage 확대
+4. `graph view`를 audit evidence surface로 승격
+5. HUD/cockpit에 provider/evidence/worker health 추가
+
+### P2 — execution depth
+
+1. executor timeout/abort cancellation을 모든 신규 runner/child process까지 계속 전파
+2. dynamic fallback node resume 재현성 확보
+3. checkpoint restore protected-path policy 확장
+4. `team` 실행 상태·pane·worktree·artifact·verification reporting 강화
+5. capability routing rationale를 summary/inspect에 표시
+
+### P3 — broader integrations
+
+1. remote MCP version pinning / provenance 정책
+2. external provider lane 확대는 read-only/advisory 품질 게이트 후 진행
+3. design/open-design bridge는 DESIGN.md token과 accessibility gate 기반으로 유지
+
+## Known limitations as of 2026-05-18
+
+- 기존 생성 `.omk/runtime*.json` artifact는 source/fresh-init default와 다를 수 있다.
+- 일부 user/global MCP runtime은 high-trust secret-backed shell wrapper와 unpinned `npx -y`/`@latest`에 의존할 수 있다.
+- `kimi-wire`는 `.kimi` isolated HOME/MCP/hook parity 전까지 opt-in이다.
+- `team`은 maturity상 experimental이며, run reconstruction이 충분하지 않다.
+- `graph view`는 유용하지만 ontology/run/evidence/provider linking이 아직 완성된 audit substrate는 아니다.
+- JSON contract는 `doctor`, `verify`, 일부 provider/screenshot/goal 경로에 있으나 graph/DAG/summary/workflow까지 완전히 균일하지 않다.
+- full test suite는 느린 MCP/init 테스트와 dist freshness 정책 차이로 로컬/CI 결과 해석에 주의가 필요하다.
+- historical docs는 trajectory 참고 자료이며, 현재 truth는 `README.md`, `ROADMAP.md`, `MATURITY.md`, `.omk/runtime*.json`, 실제 source/test 결과를 함께 봐야 한다.
+
+## Operating rule for next changes
+
+새 기능 추가보다 먼저 다음 invariant를 만족해야 한다.
+
+```txt
+safe default ≤ project-local scope ≤ evidence-gated completion ≤ reproducible run artifacts ≤ no secret leakage
+```
+
+이 invariant를 만족하지 않는 “all agents / all MCP / all hooks” 모드는 기본값이 아니라 명시적 고신뢰 모드로 다뤄야 한다.