kiokuko-dsh 0.1.0

package/dist/web/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../src/web/ui.ts"],"names":[],"mappings":"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"}

package/docs/README.ja.md

@@ -0,0 +1,14 @@
+# Kiokuko ドキュメント
+
+目的別に参照してください。
+
+- [導入ガイド](getting-started.ja.md) — インストール、Codex/OpenCode/Claude/Hermes設定、再起動、Web UI。
+- [基本概念](concepts.ja.md) — RAG、記憶のライフサイクル、Project/Ecosystem/Global、Akinator。
+- [役小角(enno-oduno)](enno-oduno.ja.md) — Agent Loop、確認、回復、継続、検証、Advisory Round。
+- [Semantic retrieval](semantic-retrieval.ja.md) — embedding runtime、運用、offline、fallback。
+- [Security and trust](security-and-trust.ja.md) — secret拒否、記憶の境界、External Skills、公開エラー。
+- [CLI contract](cli-contract.md) — 安定したコマンドとレスポンス。
+
+実装者向けは[architecture](architecture.md)、[database](database.md)、[execution ledger](execution-ledger.md)、
+[client compatibility](client-compatibility.md)、[retrieval evaluation](retrieval-evaluation.md)を参照してください。
+英語目次は[こちら](README.md)です。

package/docs/README.md

@@ -0,0 +1,16 @@
+# Kiokuko documentation
+
+Choose a guide by what you need to do:
+
+- [Getting started](getting-started.md) — install, configure Codex/OpenCode/Claude/Hermes, restart clients, and use the Web UI.
+- [Concepts](concepts.md) — RAG, memory lifecycle, Project/Ecosystem/Global scopes, and Akinator.
+- [役小角(enno-oduno)](enno-oduno.md) — the agent loop, confirmation, recovery, continuation, verification, and Advisory Round.
+- [Semantic retrieval](semantic-retrieval.md) — embedding runtime setup, operation, offline mode, and fallback.
+- [Security and trust](security-and-trust.md) — secret rejection, memory boundaries, External Skills, and public errors.
+- [CLI contract](cli-contract.md) — stable command and response details.
+
+Implementation references: [architecture](architecture.md), [database](database.md),
+[execution ledger](execution-ledger.md), [client compatibility](client-compatibility.md),
+and [retrieval evaluation](retrieval-evaluation.md).
+
+The Japanese user guides are available from the [日本語目次](README.ja.md).

package/docs/agent-file.md

@@ -0,0 +1,72 @@
+# Agent file management
+
+`kiokuko setup` creates or updates Codex/OpenCode global `AGENTS.md` files and
+Claude Code's global `CLAUDE.md` with a Kiokuko global-memory block. `kiokuko
+use` optionally creates or updates the repository's `AGENTS.md` with a
+project-specific block.
+
+If setup creates a missing project binding for a registered project, it also
+adds `.kiokuko.json` to that project's root `.gitignore` when neither the plain
+nor root-anchored entry is already present. This setup-only addition participates
+in the same compare-and-swap and rollback boundary as the binding and project
+agent file.
+
+Existing bytes outside the block are preserved, including the human-authored
+header/footer, line-ending style, and file mode. Missing markers are appended;
+imbalanced, duplicated, nested, or reversed markers cause a validation error
+and are not repaired automatically. Symlinks are rejected.
+
+Repeated `setup` or `use` with unchanged content does not rewrite its target
+files. `setup --dry-run` validates all target content without creating the
+database, config, or instruction files.
+
+When `kiokuko use --agent-file` changes an existing repository binding, the
+new target is installed and only the exact marked block is removed from the
+old target. Human bytes and file mode outside that block are preserved; a file
+is deleted only when the managed block was its entire content. Malformed
+markers, symlinks, concurrent file changes, or a later database-registration
+failure abort the transition and conditionally restore every Kiokuko-owned
+file mutation. Cleanup and restoration failures are reported rather than
+ignored.
+
+The generated instructions describe the high-level `task_prepare`,
+`task_answer`, Curator, and `memory_checkpoint` MCP lifecycle. The first two are
+the only model-facing task-memory entry points. Human/operator CLI and Web
+inspection remain management-only and are not a fallback for a client that
+cannot satisfy the task capability gate. When Enno-Oduno is enabled, setup may
+install a bounded Codex or Claude Code Stop hook, or an OpenCode
+`session.idle` plugin. Hermes receives no continuation adapter. These adapters
+only gate the existing run-bound continuation; they do not recall memory,
+launch advisors, bypass planning or confirmation, or select a latest run. A
+client session is routing metadata, not authorization ownership. Continuation
+prefers the exact short-lived opaque resume token bound to the route epoch;
+otherwise the adapter may atomically reroute
+the single unambiguous active run in the canonical repository across Codex,
+Claude Code, and OpenCode. Rerouting increments the epoch and invalidates old
+tokens. An active WorkUnit execution lease blocks rerouting and only its holder
+may report. Multiple candidates remain unchanged. Exhausting one
+session's continuation budget leaves the run and ledger active for another
+local project client.
+
+Template version 20 also documents bounded `ENNO_INPUT_INVALID` diagnostics,
+the explicit advisory lifecycle and dynamic report schema, WorkUnit-local
+`code`/`ui`/`test`/`docs`/`operations` routes, repository-relative verifier
+directories, continuation-pausing plan recovery, pre-persistence sanitization,
+crash-recoverable receipts, and repository-state-bound Final Review evidence.
+
+The instructions require one new bounded opaque `requestId` per logical user
+request and permit reusing it only for an exact transport retry. Identical task
+text in a later request still gets a new ID. Reusing an ID with changed bound
+input conflicts, and `client.sessionId` is not accepted as a substitute.
+The normalized context budget is also bound at preparation and must be repeated
+unchanged by `task_answer`.
+
+Default setup installs the exact local `memory-reasoning` Skill, but installation
+is not proof that a model loaded or followed it. For actionable build/debug
+memory, generated instructions treat catalog
+availability as only the gate, not proof of compliance. The client must read the
+available local `memory-reasoning` Skill before modifying code and convert
+recalled claims that affect the task into verified premises, falsifiable
+invariants, concrete counterexamples, and regression tests. Missing or unknown
+availability is explicit in `memoryPolicy.contextWithheld` and
+`memoryPolicy.withheldReason`; `nextAction` remains `proceed`.

package/docs/agent-gateway.md

@@ -0,0 +1,104 @@
+# Agent Event Gateway HTTP/JSON v1
+
+Kiokuko exposes a client-neutral local control-plane API. Coding agents send run lifecycle and normalized events to Kiokuko; Kiokuko commits sanitized records to SQLite and returns bounded, untrusted memory context plus deterministic recommendations.
+
+The v1 gateway is **not** an OpenAI/Anthropic provider reverse proxy. It never requires provider credentials and does not claim to observe events that a client cannot report.
+
+## Runtime and discovery
+
+Start the foreground service with:
+
+```bash
+kiokuko serve [--host 127.0.0.1] [--port 0] [--json]
+kiokuko server status --json
+```
+
+`kiokuko web` is the compatibility entry point for the same server composition. The service accepts loopback hosts only. On startup it creates a same-user runtime descriptor containing protocol version, PID, base URL, database fingerprint, instance ID, start time, and a random capability token. The descriptor is mode `0600`; the token must not appear in stdout, argv, `AGENTS.md`, events, logs, or error responses.
+
+All `/api/v1/*` endpoints require `Authorization: Bearer <capability-token>`. `GET /health/live` exposes only liveness; `GET /health/ready` is authenticated. CORS is not permissive.
+
+## Write protocol
+
+Every write requires:
+
+- `Content-Type: application/json`
+- `apiVersion: "1"`
+- `Idempotency-Key: <opaque non-empty key>`
+- strict unknown-field rejection
+- request body at most 2 MiB
+
+A key is scoped to the operation/run. Replaying the same key with the same canonical request returns the stored atomic mutation acknowledgement and does not repeat the mutation. Reusing it with different content returns `409 CONFLICT`. For operations that add capability-gated context, gating and retrieval happen after that mutation boundary and are re-evaluated against the current retrievable revisions and feedback. The full enriched JSON may therefore change on an exact retry even though the acknowledged mutation does not. Freezing the earlier enriched context would bypass current retrieval eligibility. Event batches are all-or-nothing and contain at most 200 events; one sanitized payload is at most 64 KiB.
+
+Success envelope:
+
+```json
+{"apiVersion":"1","ok":true,"operation":"agent.checkpoint","data":{},"meta":{}}
+```
+
+Failure envelope:
+
+```json
+{"apiVersion":"1","ok":false,"operation":"agent.checkpoint","error":{"code":"VALIDATION_ERROR","message":"...","details":{}}}
+```
+
+The server never includes an auth token, matched secret, raw request, hidden reasoning, or internal stack in an error. Queue saturation returns `429` with `Retry-After`; unavailable storage returns `503`; validation returns `400`; authentication returns `401`; not found returns `404`; idempotency/source-ID conflict returns `409`.
+
+## Lifecycle endpoints
+
+### Open
+
+`POST /api/v1/agent/runs`
+
+Creates a ledger run, an Akinator intake session, and their one-to-one `run_intakes` link in one application transaction. Workspace is fixed here and is immutable for the rest of the run. Client-supplied coverage is stored exactly; Kiokuko does not upgrade it.
+
+If intake needs an answer, the run remains `intake`, the response includes only the current question and no memory context. A client must present that question to the user without inventing an answer. A finalized `ready` or bounded `exhausted` intake moves the run to `active` and permits initial context delivery.
+
+### Answer intake
+
+`POST /api/v1/agent/runs/:runId/intake/answers`
+
+Accepts only the currently outstanding question ID. The answer, intake transition, lifecycle event, and run status transition are atomic. Exact retry replays that mutation acknowledgement without repeating the answer; any post-commit capability gate and context retrieval are evaluated again under the bound catalog and current retrieval eligibility. A finalized profile is immutable; later task-understanding changes are appended as `task_profile.revised` events.
+
+### Append events
+
+`POST /api/v1/agent/runs/:runId/events`
+
+The server preserves source event IDs/sequences and assigns a contiguous local sequence. The canonical event type and optional client `sourceType` are both stored. Non-intake events are rejected while the run is `intake`. Terminal runs reject new events except exact idempotent replay.
+
+### Checkpoint
+
+`POST /api/v1/agent/runs/:runId/checkpoints`
+
+Atomically appends the included events, then projects state through the committed cursor. The response includes the authoritative finalized intake status (`ready` or `exhausted`). The request must include the exact complete `capabilities` catalog bound when the run opened; the server validates that binding before mutation and removes the catalog before strict checkpoint parsing. Retrieval happens after the write transaction and outside the bounded write queue. The broker ranks once, evaluates the capability gate against that fixed snapshot, and persists only that same snapshot after approval; it never previews and then re-queries. Inside the delivery transaction, every selected exact revision is revalidated as current and retrievable, including the active managed-external mapping and source identity. A concurrent revision, disable, stale, or refresh transition returns a conflict with no delivery instead of silently reranking. Every request requires the exact local `kiokuko-soul` Skill in the bound catalog; missing or unknown availability returns `nextAction: required_capability_unavailable`, `context: null`, and no persisted delivery, including while intake still needs an answer. Actionable ordinary build/debug memory from `ready` intake is returned only when the bound catalog also contains the local `memory-reasoning` Skill. Missing or unknown `memory-reasoning` alone sets `memoryPolicy.contextWithheld: true`, reports `memory_reasoning_missing` or `memory_reasoning_unknown` in `memoryPolicy.withheldReason`, and withholds that ordinary memory while leaving `nextAction: proceed`; the ready-only memory policy does not apply to bounded `exhausted` intake. After this gate, the response may contain one persisted v1 advisory nudge selected from the final recommendations; the nudge is never selected or persisted before capability gating.
+
+### Close, feedback, promotion
+
+- `POST /api/v1/agent/runs/:runId/close`
+- `POST /api/v1/agent/runs/:runId/feedback`
+- `POST /api/v1/agent/runs/:runId/promotions`
+
+Close records a terminal status, final events/evidence, unresolved items, outcome, and explicit memory proposals. Feedback records context, recommendation, intake-question/profile, and run outcomes without automatically changing entry trust/status or the active intake policy. Promotion creates only an existing-memory `candidate` entry and records run/event/delivery/intake provenance; it never auto-promotes to `verified`.
+
+The former unbound `POST /api/v1/context/query` route was removed. A request without a run cannot prove which capability catalog governs the returned memory, so the server does not provide an ungated compatibility fallback.
+
+## Read protocol
+
+Cursor-paginated read endpoints are:
+
+- `GET /api/v1/agent/runs?workspace=&client=&status=&cursor=&limit=`
+- `GET /api/v1/agent/runs/:runId`
+- `GET /api/v1/agent/runs/:runId/intake`
+- `GET /api/v1/agent/runs/:runId/events?after=&limit=&type=`
+
+List pages are capped at 100 records. Event content returned to agents is marked
+`untrusted: true` and must be checked against the current repository/runtime.
+Workspace and memory inspection belongs to the human/operator CLI and Web
+management surfaces; the Agent API does not expose ungated read aliases.
+
+The former context-delivery listing route was removed because a GET request has no complete capability-catalog channel. Context deliveries are returned only by the capability-gated open, answer, and checkpoint operations that create them.
+
+## Coverage
+
+Each category is one of `complete`, `best_effort`, `declared`, or `unavailable`. `complete` is reserved for a versioned bridge with a clean-room contract test. Generic CLI runs normally use `declared` or `unavailable`. UI and recommendations must display incomplete coverage rather than call the ledger a complete transcript.
+
+The Enno-Oduno user-confirmation and plan-start recovery display contracts are delivered only through the MCP boundary. A decided contract returns the `userFacingConfirmation` projection. Missing or changed environment information persists only a continuation pause and returns a projection containing a general explanation, the absence of new work from that plan-start attempt, a remedy, and bounded choices. Each choice supplies a label and recommendation followed by the user intent it fits and the exact result of choosing it; clients translate all four parts and hide machine actions, reason codes, internal fields, catalogs, identifiers, revisions, presentation versions, and raw JSON. A legacy attempt already ended by proven environment-information loss returns a restart projection without reopening or cancelling the terminal attempt. The client waits for the user's explicit response and performs no retry, cancellation, or replacement creation before it; it never asks the user to locate the internal capability catalog. A same-run plan retry carries the selected recovery action. `enno_answer` receives explicit confirmation or cancellation, including cancellation from active planning before a user-selected restart. The Agent Event Gateway does not expose, replicate, or continue Enno runs, and no gateway endpoint substitutes for explicit user input.

package/docs/architecture.md

@@ -0,0 +1,12 @@
+# Embedding architecture
+
+Semantic retrieval is an optional lane beside lexical, exact-signal, tag, and
+trust-aware retrieval. The local provider reads a verified model directory and
+never sends memory or query text to Hugging Face. SQLite stores settings,
+profile identity, installation metadata, jobs, and rebuildable vector rows.
+
+Setup downloads allowlisted files into private staging, verifies size and
+SHA-256, runs an offline probe, and atomically installs the revision. Database
+activation and model I/O are separate phases. A profile identity includes the
+model revision, artifact manifest, runtime version, dtype, pooling,
+normalization, token limit, dimensions, and E5 input contract.

package/docs/cli-contract.md

@@ -0,0 +1,39 @@
+# Embedding CLI contract
+
+After npm publication, the default global installation is intentionally lightweight:
+
+```bash
+npm install --global kiokuko-dsh
+kiokuko setup
+```
+
+This keeps lexical retrieval and the normal setup flow available without the
+optional local semantic runtime. To opt into local semantic retrieval, run the
+following command. It installs the pinned optional dependencies when needed,
+then applies the same client configuration flow as `kiokuko setup`: managed
+MCP blocks are updated and registered-project instructions are refreshed.
+Unmanaged MCP identities require interactive confirmation before replacement;
+non-interactive or `--dry-run --json` runs fail closed without changing them.
+
+```bash
+kiokuko embeddings setup
+```
+
+`boolean@3.2.0` is an upstream transitive dependency of the Transformers.js
+runtime. It is not a Kiokuko dependency and is not present in the lightweight
+install. On Linux, the first automatic dependency installation uses sudo
+through npm. On macOS it installs into Kiokuko's package-local `node_modules`
+instead of the shared npm global prefix; other platforms invoke npm directly.
+Do not persist npm script permissions or use `--dangerously-allow-all-scripts`.
+
+`kiokuko embeddings setup` installs the pinned `local-small` preset without a
+separate confirmation flag. Automation uses:
+
+```bash
+kiokuko embeddings setup --preset local-small --json
+```
+
+`--dry-run` performs no download, model load, database write, or filesystem
+mutation. `--offline` uses only an existing verified installation. `--replace`
+allows switching profiles. `status --json` reports bounded coverage and model
+state; `repair` restores the same pinned artifact without destructive cleanup.

package/docs/client-compatibility.md

@@ -0,0 +1,299 @@
+# Client compatibility policy
+
+Status: global MCP integration for Codex, OpenCode, Claude Code, and profile-scoped Hermes Agent. Enno-Oduno continuation adapters are bounded and available for Codex, OpenCode, and Claude Code; Hermes has no Enno continuation adapter.
+
+| Client | Global MCP registration | Global instructions | Managed standard skills | Hooks/plugins |
+|---|---|---|---|---|
+| Codex | managed table in `~/.codex/config.toml` (or `$CODEX_HOME`) | managed block in global `AGENTS.md` | `~/.agents/skills/{memory-reasoning,kiokuko-soul,kiokuko-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded Stop hook when Enno-Oduno is enabled |
+| OpenCode | managed `mcp.kiokuko` property in global `opencode.json`/`opencode.jsonc` | managed block in global `AGENTS.md` | global config `skills/{memory-reasoning,kiokuko-soul,kiokuko-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded `session.idle` plugin when Enno-Oduno is enabled |
+| Claude Code | managed `mcpServers.kiokuko` property in `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`) | managed block in global `CLAUDE.md` | Claude config `skills/{memory-reasoning,kiokuko-soul,kiokuko-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | bounded Stop hook when Enno-Oduno is enabled |
+| Hermes Agent | managed `mcp_servers.kiokuko` in the effective profile `config.yaml` | none | effective profile `skills/{memory-reasoning,kiokuko-soul,kiokuko-enno-oduno,kiokuko-single-purpose-functions,kiokuko-ui-design-soul}` | none |
+| DeepSeek Harness | profile-scoped plugin manager entry for `kiokuko-dsh/dsh` | host-managed | package-bundled six standard Skills | bounded Cordis `agent/turn-stopping` and lifecycle seams |
+| Other MCP clients | manual `kiokuko mcp` stdio registration | client-specific | not installed | none |
+
+OpenCode global configuration follows XDG paths on every platform:
+`$XDG_CONFIG_HOME/opencode`, or `~/.config/opencode` when unset. On Windows,
+`~` resolves from `%USERPROFILE%`, falling back to `%HOME%`; `%APPDATA%` and
+`%LOCALAPPDATA%` are not OpenCode global configuration roots.
+
+Codex's current official documentation supports stdio MCP servers and global
+configuration. OpenCode's current official documentation supports local MCP
+commands and global rules. Claude Code supports user-scoped stdio MCP servers,
+global `CLAUDE.md`, and auto-discovered skills. `kiokuko setup` uses the MCP and
+instruction surfaces and installs the bundled `memory-reasoning`, `kiokuko-soul`, `kiokuko-enno-oduno`,
+`kiokuko-single-purpose-functions`, and `kiokuko-ui-design-soul` skills in the selected supported clients by
+default. The skills are copied from a fixed package manifest and never downloaded
+during setup. `--no-standard-skills`
+skips placement without deleting an existing copy.
+
+Hermes Agent v0.20.4 uses a profile-scoped native stdio MCP client. Kiokuko writes
+only the effective profile's `config.yaml` entry:
+
+```yaml
+mcp_servers:
+  # Managed by `kiokuko setup`.
+  kiokuko:
+    command: kiokuko
+    args: [mcp]
+    env:
+      KIOKUKO_SKILL_DISCOVERY: official
+```
+
+It does not create a global instruction file, Hermes plugin, or Hermes hook.
+Hermes's built-in memory and Kiokuko's bundled skills remain separate capabilities.
+Use `kiokuko setup --clients hermes`, then restart Hermes Agent or start a new
+session; `/reload-mcp` only reloads MCP registration. Smoke-test with
+`hermes mcp test kiokuko`.
+
+- [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp)
+- [Codex skills](https://developers.openai.com/codex/skills)
+- [OpenCode MCP servers](https://opencode.ai/docs/mcp-servers/)
+- [OpenCode rules](https://opencode.ai/docs/rules/)
+- [OpenCode skills](https://opencode.ai/docs/skills)
+- [Claude Code MCP servers](https://code.claude.com/docs/en/mcp)
+- [Claude Code memory and CLAUDE.md](https://code.claude.com/docs/en/memory)
+- [Claude Code skills](https://code.claude.com/docs/en/skills)
+- [Hermes skills](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/work-with-skills.md)
+
+## Guarantees and non-guarantees
+
+Setup guarantees safe, repeatable configuration merging and makes the Kiokuko MCP
+tools available in each configured client scope after that client reloads its
+configuration and makes the bundled standard skills discoverable after a client
+restart or new session. Global instructions request `task_prepare` before non-trivial work, grounded
+`task_answer` calls when intake fields are missing, and checkpointing after
+substantial verified work.
+
+No supported client guarantees that a model will call an available tool for every
+prompt. Therefore “automatic” means no per-repository install and no manual CLI
+lifecycle after one-time setup; it does not mean Kiokuko intercepts every prompt
+or response. For Hermes specifically, automatic/model use is best effort from
+MCP tool descriptions.
+
+The `kiokuko-soul` standard skill is the canonical first-read router. Managed
+instruction surfaces require it before another bundled Kiokuko skill. Every
+`task_prepare` call requires `soulRead: true` as an explicit claim that the
+complete local Skill was read for that logical request, and the capability gate
+requires an exact local `kiokuko-soul` descriptor for every task. Omission or
+false attestation is invalid; missing or unknown capability availability returns
+`required_capability_unavailable` even while intake needs an answer. A
+namespaced, fetched, or reference-only skill does not satisfy the required
+master SOUL. The boolean attestation is enforceable protocol evidence, not
+remote proof that a model understood or followed the Skill.
+
+The `memory-reasoning` standard skill is installed by default, but filesystem
+placement is not proof that the current model loaded or followed it. For ready
+build/debug tasks, clients advertise the exact local capability only when it is
+actually available. If it is missing or availability is unknown, Kiokuko sets
+`memoryPolicy.contextWithheld=true`, reports `memory_reasoning_missing` or
+`memory_reasoning_unknown` in `memoryPolicy.withheldReason`, returns no actionable
+ordinary memory, and leaves `nextAction=proceed`. An unmanaged same-name file
+causes setup to fail closed; move or remove that file manually before rerunning
+setup if Kiokuko should own the destination.
+
+The UI standard skill is intended for explicit UI, UX, frontend, screen, SwiftUI,
+accessibility, and equivalent Japanese-language tasks. `task_prepare` treats it
+as a first-party recommendation only for such concrete terms; generic `design`,
+backend-only work, and image-only generation do not trigger it.
+
+The UI and function standard Skills use progressive disclosure. Their short
+`SKILL.md` files are mandatory indexes, while versioned expert fragments are
+selected for the concrete component, function, design decision, or WorkUnit.
+Normal execution reads one to three fragments rather than every reference.
+
+The single-purpose-functions standard skill applies to writing, modifying,
+reviewing, debugging, and refactoring code across languages and repositories.
+Its examples use typed TypeScript for concreteness, but the contracts explicitly
+adapt to the target project's language, error model, persistence layer, and test
+framework. `task_prepare` treats it as a first-party recommendation for concrete
+coding terms in English or Japanese. Explicit no-code, documentation-only, and
+image-only work do not trigger it. Kiokuko does not claim that availability alone
+forces model use.
+
+The Enno-Oduno standard skill is the role-level controller contract. Every
+Enno-Oduno directive and WorkUnit retains `kiokuko-soul` first. Enno-Oduno
+directives then require `kiokuko-enno-oduno` during intake, Oduno ideal
+derivation, confirmation, final review, and Oduno meditation. A ready intake
+enters `oduno_ideal`: `enno_ideal_submit` derives the optimal target from the
+structured `task_prepare` handoff plus exactly one contribution per
+Akinator-discovered Skill before Zenki can plan. After accepted final
+verification, `oduno_meditation` inspects changed and approved paths for
+evidence-backed obsolete test or function candidates without deleting them;
+`enno_meditation_submit` persists that reflection and completes the run. The
+controller skill itself is not inserted into Zenki's WorkUnit
+Skill snapshot; Zenki continues to require the single-purpose-functions skill
+for every code-changing plan. Every code-changing WorkUnit persists one to
+three registered `expertRefs`; UI WorkUnits include at least one `code.*` and
+one `ui.*` expert. Unknown, duplicate, missing, or oversized expert mixtures
+are rejected before Skill discovery or repository mutation.
+
+A `needs_confirmation` response carries
+`ennoOduno.directive.userFacingConfirmation`, a deterministic display
+projection of the decided contract. It presents scope paths, exclusions,
+completion criteria, work items with display-number dependencies, skills with
+their reference-only status, expertise with selection reasons, focused and
+final checks (executable, arguments, directory, and timeout kept separate, never
+joined into a shell command), and the attempt limit, each labeled with its
+provenance basis (`user`, `repository`, or `proposal` for inferred fields). The
+directive also carries a fixed confirmation report schema and objective, so the
+client model presents every item in the user's language, translating headings
+only, without raw directive JSON, internal field names, WorkUnit IDs, expert
+IDs, or verifier IDs, and then waits for an explicit approve, revise, or cancel
+through `enno_answer` at the confirmed contract revision. Projection content
+that resembles a secret or exceeds the 64 KiB display bound rejects the plan
+submit instead of being redacted or truncated. `needs_confirmation` stays
+outside the Codex Stop hook, Claude Code Stop hook, and OpenCode
+`session.idle` continuation candidates, so no client auto-continues through a
+user confirmation.
+
+Final Review is two-phase. `enno_verify_prepare` runs the approved final
+verifiers outside database transactions with shell disabled and a
+repository-relative cwd, stores evidence bound to contract/mutation revision,
+verifier specification, and complete repository state, and only then permits
+the final-review advisory fanout. `enno_finish` rechecks that state, decides
+accept/replan/block from the complete stored context, never spawns a subprocess,
+and rejects unready evidence as a conflict. Passing tests alone do not accept a
+run; Enno-Oduno must accept the current contract.
+
+All supported clients consume the same bounded `ENNO_INPUT_INVALID` validation
+envelope and the same WorkUnit-local route contract. New verifier cwd values are
+repository-relative. Continuation adapters transport opaque resume tokens and
+route epochs; Goki transports the returned execution lease. Old tokens become
+invalid after rerouting, and an active lease prevents another client from
+rerouting or reporting the same WorkUnit.
+
+If the environment information needed to start a plan is absent or no longer
+matches the task-preparation binding, the MCP result instead contains a
+non-mutating `userFacingRecovery` projection. Clients translate and present
+only its what-happened, work-state, resolution, and choices. Every choice is
+shown as its translated label and recommendation, followed by its translated
+`whenToChoose` intent and exact `whatHappens` result. The machine `action`,
+internal tool and field names, catalog, hashes, run identity, revisions,
+presentation version, reason codes, and raw JSON remain hidden. The client must
+not retry, cancel, or create a replacement automatically.
+
+For missing information, continuing attaches the complete catalog retained by
+the host and reuses the same attempt; reviewing asks the user for changes and
+starts no implementation before the answer; cancelling ends the current attempt
+without a replacement. For changed environment information, restarting first
+cancels the active planning attempt and then opens a new task with the current
+environment and agreed plan. Review-before-restart asks for changes first, then
+cancels and replaces the active attempt only after the answer. If a legacy
+attempt already ended because the catalog was provably lost during plan
+submission, both restart choices leave that terminal attempt unchanged and open
+a replacement only after the user chooses and, for review, answers. Cancelling
+an already-ended attempt creates nothing.
+
+For new Codex, OpenCode, and Claude Code setup, Enno-Oduno continuation is
+enabled by default; existing managed installations remain unchanged until
+`--enno-oduno on` is selected. Setup installs only the bounded native adapter
+for each of those clients: a Codex or Claude Code Stop hook, or an OpenCode
+`session.idle` plugin. Hermes receives no Enno continuation adapter. During an
+adapter continuation, `client_session_id` is routing metadata rather than
+authorization ownership. A valid short-lived resume token wins; otherwise the current
+local Codex, Claude Code, or OpenCode session may atomically reroute the single
+unambiguous active run in the canonical repository, including across client
+kinds. Rerouting increments the route epoch and invalidates old tokens; an
+active WorkUnit execution lease blocks it. Multiple active candidates remain
+unchanged. A per-session continuation limit stops only that session and leaves
+the run and ledger active for another local project client. Hermes has no
+automatic hook but may continue the same run through MCP with its exact run
+identity. The public `clientBinding` field reports this current route; its
+`bound` state does not grant ownership.
+upgrade, `--enno-oduno off` removes only the exact Enno-owned adapter, while
+setup also removes only the byte-exact retired OpenCode guard and the one exact
+retired Claude prompt handler. A modified, duplicate, relocated, or partial
+legacy identity is `CONFLICT` and requires manual review; unrelated client
+settings are preserved.
+
+`task_prepare` can accept an ephemeral catalog of skill and MCP-tool names from
+the calling client. Kiokuko matches Akinator policy recommendations and task
+terms against that catalog, but cannot enumerate another MCP server or a
+client's private skill registry by itself. A result therefore distinguishes
+`available`, `missing`, and `unknown`; it never treats a fetched `SKILL.md` as
+installed or executable. External skill discovery is controlled independently
+by `KIOKUKO_SKILL_DISCOVERY=off|official|community` and defaults to `official`.
+When enabled, Kiokuko compares the project fingerprint with relevant client
+skills rather than checking whether the catalog is globally empty. An omitted
+catalog is treated as unknown availability; official reference-only discovery
+may still proceed, but fetched skills are never treated as installed or
+executable. Akinator discovery and `kiokuko skills find` share the same
+provider-backed `findSkills` operation. There is no legacy fixed-source sync or
+guessed-source fallback; bounded exact verification of a reviewed,
+catalog-pinned source remains.
+
+`task_prepare` also requires a bounded opaque `requestId`. Clients create a new
+ID for every logical user request, including a later request with identical task
+text, and reuse an ID only for an exact transport retry. Reusing an ID with
+changed bound intake input is `CONFLICT`; `client.sessionId` is not a turn or
+request identity. The raw request ID is not stored.
+The normalized context budget is part of the bound request and every
+`task_answer` must repeat it; a changed budget conflicts before intake mutation.
+
+The legacy ungated `guide context` path was removed. Task-aware context must use
+`task_prepare` / `task_answer` or the generic Agent bridge so the same
+`kiokuko-soul` hard gate applies. External Skill discovery belongs to
+`task_prepare` or the explicit `skills find` / `skills import` commands.
+
+Every `task_answer` request must include the exact `run.runId`, capability
+catalog, and context budget supplied to `task_prepare`; clients must not fall
+back to session-only run lookup or replace those bindings between answers. Inspect
+`nextAction` and `memoryPolicy` after every `task_prepare` and `task_answer` response. Every task
+requires the exact local `kiokuko-soul`; missing or unknown availability returns
+`required_capability_unavailable`, even while intake needs an answer. For a ready
+build/debug task with actionable ordinary memory, missing or unknown
+`memory-reasoning` alone sets `memoryPolicy.contextWithheld=true`, reports
+`memory_reasoning_missing` or `memory_reasoning_unknown` in
+`memoryPolicy.withheldReason`, withholds that memory, and leaves `nextAction=proceed` so
+the client can continue from repository evidence. When it is available, the
+client must read the local `memory-reasoning` Skill before modifying code and
+convert recalled claims that affect the task into verified premises, falsifiable
+invariants, concrete counterexamples, and regression tests. Catalog availability
+alone does not satisfy this execution contract.
+`context: null` with `memoryPolicy.contextWithheld=true` is the explicit
+withholding state and persists no delivery. A non-null empty context with a null
+delivery ID means there was no actionable candidate; clients must not collapse
+these states.
+If the client cannot obtain the Kiokuko policy for a non-trivial build/debug
+request, it must also stop and report that boundary. Repository-only
+continuation for such a request is allowed only after the policy establishes
+that no Kiokuko memory was delivered or used.
+
+The latest returned `intake.question` is authoritative for every answer. If
+`question.options` is non-null, submit exactly one returned option as `value`.
+If `options` is null, submit grounded non-empty free text. Repeat the loop until
+`intake.status` is `ready` or `exhausted`; `target` and `expected` require
+grounded text and are not one-word enums.
+
+Run-bound `memory_checkpoint` has the same intake precondition across MCP,
+scoped memory, and the Agent Gateway: only `active` runs may be closed by a
+successful checkpoint. If `task_prepare` or `task_answer` returns
+`needs_answer` with `nextAction=answer_from_evidence_or_ask_user`, the client
+must finish every required `task_answer` question before retrying. The MCP
+tool returns `isError=true` with fixed text and structured fields
+`code=CHECKPOINT_RUN_NOT_ACTIVE`, `reason`, `runStatus`, `nextAction`, and
+`retryableAfterStateChange`; arbitrary internal messages and details are never
+forwarded. A terminal run returns `reason=run_terminal` and `nextAction=stop`.
+
+The MCP checkpoint payload is closed and has two forms. A standalone
+checkpoint contains at least one memory and omits `runId`, `outcome`,
+`deliveryId`, `feedback`, and `evidence`. A run-bound checkpoint requires an
+active exact `runId`, an explicit terminal `outcome`, and at least one
+non-empty `memories`, `feedback`, or `evidence` lane. Outcome-only, empty
+evidence, empty feedback, and invented evidence fields such as `checks` are
+invalid. Evidence fields are limited to `changedPaths`, `errorSignatures`,
+`commands`, `tests`, and `verification`; feedback items are limited to
+`entryId`, `entryRevision`, `verdict`, and `comment`.
+
+## Scope boundary
+
+The stdio MCP server calls Kiokuko's memory services only through
+`task_prepare`, `task_answer`, and lifecycle tools. It never exposes the SQLite
+file or a direct recall tool. Human/operator CLI and Web inspection remains
+management-only. Task context is limited to the resolved current repository
+and/or the reserved global workspace; it never searches unrelated project
+workspaces. Writes are candidate-only, untrusted, bounded, content-hash
+idempotent, audited, and passed through secret detection.
+
+The generic Agent Gateway remains available for explicit execution-ledger
+workflows and applies the same task capability gate.

package/docs/concepts.ja.md

@@ -0,0 +1,25 @@
+# 基本概念
+
+## RAGと記憶のライフサイクル
+
+KiokukoはRAG（retrieval-augmented generation）を使います。作業前にMCP serverが保存済みentryを検索し、関係する文脈だけを渡します。
+作業後は決定、結果、教訓をcheckpointできます。記憶は参考情報なので、現在のリポジトリと実行結果が常に優先されます。
+
+entryはcapture、validation、retrieval、review、必要ならpromotionを経ます。secretらしい内容は拒否され、checkpointは正しさの証明ではありません。
+
+## スコープ
+
+- **Project**: 1つのrepository専用。
+- **Ecosystem**: 言語、framework、database、runtimeの条件が一致する場合に再利用。
+- **Global**: 特定projectに依存しないと明示的に一般化した知識。
+
+tagだけでProject記憶が別projectへ漏れることはありません。Curatorの確認後にGlobalへ昇格できます。
+
+## Akinator
+
+Akinatorはintake gateです。依頼が曖昧なとき、候補を分ける最小の質問をします。回答が必要な間はplan、編集、検証、checkpointを開始しません。
+intakeがreadyまたはexhaustedになってから通常ルートへ進み、発見されたSkillは参照専用です。
+
+## Semantic retrieval
+
+基本はlexical検索です。任意のlocal embeddingがsemantic signalを追加します。詳細は[Semantic retrieval](semantic-retrieval.ja.md)を参照してください。