@askdkc/kiokuko 0.2.1 → 0.2.3

package/README.ja.md

@@ -12,7 +12,7 @@ Kiokukoは、AIコーディングエージェント向けの外部記憶です
 
 ## すぐ使う
 
-Node.js 26.1.0以上が必要です。
+Node.js 24.16.0以上が必要です。Node.js 26.1.0以上もサポートしています。
 以下の2コマンドで楽々スタートです💕
 
 ```bash
@@ -22,21 +22,53 @@ kiokuko setup
 
 `setup`は、インストール済みの対応クライアントを検出し、SQLiteデータベースとMCP接続を自動設定します。
 対話式setupでは、監査済みcommunity Skillも参考資料として利用するか確認します。既定は「いいえ」です。
-Codex、Claude Code、OpenCodeの新規導入では、Enno-Oduno（役小角）Agent Loopも有効になります。既存の管理済み環境は`--enno-oduno on`を明示するまで変更せず、`--enno-oduno off`はEnno-Odunoが所有するhook/pluginだけを削除します。
-setupは、bundled controller Skillの`kiokuko-enno-oduno`を、`kiokuko-single-purpose-functions`および`kiokuko-ui-design-soul`と一緒に、選択した対応clientへ配置します。
-モデル向けの記憶は、capability gateを通るMCPツール `task_prepare` と
-`task_answer` からだけタスクへ渡されます。`task_prepare`はEnno-Odunoの入口でもあり、役小角が呼出元ハーネスを特定し、Akinator intakeを所有し、小角の理想像を導出してから、実行可能になった依頼を前鬼へ渡します。hookは記憶を暗黙取得せず、プランニングも迂回しません。canonical repository内で一意なpending active runだけをclient sessionへ結合して、小角、前鬼、後鬼、または最終Reviewの継続をgateします。repository単位の「最新run」は選びません。
-
-すべての`task_prepare`呼び出しは、クライアントモデルがその論理タスク用に
-ローカルの`kiokuko-soul`全文を読んだ後で`soulRead: true`を渡す必要があります。
-また、全taskで完全一致するローカル`kiokuko-soul` capabilityを要求し、欠落または
-availability不明ならintake未完了でもfail-closeします。このbooleanは明示的な
-クライアントattestationであり、モデルがSkillを理解・遵守したことのremote proofでは
-ありません。
 
 設定後、対象のAIクライアントを起動し、あとは普段どおり使うだけです。すでに起動している場合は、いったん終了してから起動し直してください。setupがCodexのStop hookを作成または更新した場合は、Codexで`/hooks`を開き、そのhookを明示的に信頼してください。
 
-### Enno-Oduno（役小角）Agent Loop
+## 使うほど賢くなる仕組み
+
+```text
+ユーザーの依頼
+      ↓
+関連する過去の記憶を検索
+      ↓
+AIが記憶を参照して作業
+      ↓
+再利用できる成果や教訓を保存
+      ↓
+次の依頼で再び検索
+```
+
+Kiokukoは、次の流れを繰り返します。
+
+1. 作業前に、現在のプロジェクトとGlobal記憶を検索する
+2. 関連性の高い記憶だけをAIへ渡す
+3. AIが作業を実行する
+4. 作業後に、再利用できる知識を記憶する
+5. 次の作業で、その記憶を再利用する
+
+つまりKiokukoは、**永続的な記憶を蓄積していくRAGシステム**です。
+
+MCPはAIクライアントとKiokukoを接続し、RAGは必要な記憶を検索してAIへ渡します。
+
+### セットアップ後に起こるAIエージェントの挙動
+
+#### AI Akinator
+
+AIエージェントに渡された依頼が漠然としていてAIに具体性が見えない時は、Akinatorが内部的な質問を行い、AIにとって必要な具体性に依頼を固めて行きます。この際に推奨される言語やフレームワークなどのSkillがあれば取得して利用可能にします。
+
+#### 役小角 (Enno-oduno)
+
+AIエージェントへの依頼を処理するLoop処理：役小角 が有効になります。
+
+依頼内容の理想系を決め、プランニングを行い、実装を小エージェントにオーケストレーションで処理させ、最後に理想に合致するかを自動でチェックしてくれます。
+
+#### 記憶の格納
+
+モデル向けの記憶は、capability gateを通るMCPツール `task_prepare` と
+`task_answer` からだけタスクへ渡されます。`task_prepare`は役小角の入口です。タスクを処理した後に内容が記録され、必要に応じてAIが使う知識へと昇華可能かを検討します。実用に耐える知識が昇格されるように自動調整されています。
+
+### Enno-Oduno（役小角）Agent Loop 詳細
 
 `build`、`debug`、`review`、`devops`では、`task_prepare`がrun-bound loopを開始して`ennoOduno`を返します。強制される役割順序は次のとおりです。
 
@@ -52,18 +84,58 @@ availability不明ならintake未完了でもfail-closeします。このboolean
   -> 前鬼がWorkUnitごとにversion付きexpertRefsを1〜3個選び、未選択fragmentは既定で読まない
   -> 前鬼がWorkPlan、WorkUnit、expert refs、Skill snapshot、検証方法を提出
   -> 必要なら役小角がユーザー確認を得る
-  -> 後鬼が承認済みWorkUnitだけをオーケストレーション
-  -> 役小角がfreshなfinal verifier証拠をReview
-       -> 成功: 役小角が受け入れ、読み取り専用の小角の瞑想へ移行
+   -> 後鬼が承認済みWorkUnitだけをオーケストレーション
+   -> enno_verify_prepareがfinal verifierを実行し、freshな証拠を保存
+   -> 証拠の準備後にだけ、親ホストがfinal-review Advisorをfan-out
+   -> enno_finishが保存済み証拠からaccept/replan/blockを決定
+        -> 成功: 役小角が受け入れ、読み取り専用の小角の瞑想へ移行
             -> 変更済み・承認済みpathから、根拠のある古いtestまたは関数を探索
             -> enno_meditation_submitが削除せずに候補を保存し、その後runを完了
        -> 失敗: 役小角がrevisionを上げ、Review結果を前鬼へ返す
-  -> 前鬼の修正plan提出と必要な確認が終わるまで後鬼は再開不可
+   -> 前鬼の修正plan提出と必要な確認が終わるまで後鬼は再開不可
 ```
 
+Final Reviewは意図的に二段階です。`enno_verify_prepare`はdatabase
+transactionの外側でshellを無効にし、repository内に限定したcwdで承認済み
+verifierを実行し、現在のcontract revisionとmutation revisionに結び付いた
+freshな証拠を保存します。`enno_finish`はsubprocessを起動せず、保存済みの
+freshでpassingな証拠だけを受け入れます。testがpassingしただけではrunを
+受け入れません。
+Enno continuationを有効にした場合、CodexとClaude Codeは上限付きStop hook、
+OpenCodeは上限付き`session.idle` pluginを使います。Hermesはnative stdio MCPと
+bundled Skillだけを使い、Enno continuation adapterは導入しません。
+
 したがってintakeが未完了なら、返すのは役小角directiveと`answer_intake`であり、その`requiredSkills`には`kiokuko-enno-oduno`が含まれ、前鬼はまだ開始しません。準備完了したintakeは、まず`oduno_ideal`と`submit_ideal`を返します。`enno_ideal_submit`では、Akinatorが選択したdiscovery setの全Skillについて貢献を正確に一件ずつ指定する必要があり、外部Skillは引き続きuntrusted reference-onlyの指針として扱います。その後にだけ、runはrevision固定の前鬼directiveを返します。このdirectiveは、空のdraft Skill snapshotでもcompact indexである`kiokuko-single-purpose-functions`を`requiredSkills`へ含めます。前鬼はこのindexをWorkUnit選定前に使い、無意味な微小関数を作らず、code変更を凝集した関数またはユースケース契約とfocused test targetへ分割します。各code変更WorkUnitは理由付きの登録済み`expertRefs`を1〜3個選ぶ必要があり、UI WorkUnitは`code.*`と`ui.*`を少なくとも一つずつ要求します。`enno_plan_submit`は欠落、重複、未知、上限超過のmixtureを拒否し、その選択をrevisionとともに保存します。後鬼はSkillの全referenceではなく、そのfragmentだけを読みます。controller Skillはrole単位であり、WorkUnitのSkill snapshotには混ぜません。完全なプランの受理と必要な確認が成功するまで、後鬼には遷移できません。最終Review失敗時も古い後鬼WorkUnitを直接再開しません。却下したplanと検証証拠を旧revisionの履歴として保持し、`zenki_planning`へ戻して新しいplanを必須にします。Reviewを受け入れると、直接完了せず`oduno_meditation`へ移行します。`enno_meditation_submit`はrepositoryを変更せず、検査したrepository-relative pathと根拠付きの古いtestまたは関数の候補を保存してからrunを完了します。応答の`orchestrationId`を全Enno MCP操作で使い、ホスト側session identityとは分離します。推論したscope、達成条件、Skill、expert選択、検証コマンドがある場合、実装前に通常のクライアントUIへ確認を返します。`needs_confirmation`応答には、確定済み契約の決定的な表示projectionである`ennoOduno.directive.userFacingConfirmation`が含まれます。scope、除外、達成条件、表示番号付き依存を持つ作業項目、reference-only状態を含むSkill、選定理由付きの専門観点、focused/final checks、試行上限が、それぞれprovenance basis（ユーザー指定・リポジトリ検証済み・提案）付きで一度ずつ現れます。クライアントモデルはraw directive JSONや内部識別子を出さずに全項目をユーザーの言語で提示し、明示的なapprove・revise・cancelを待ちます。secretを示す表示値や64 KiBを超えるprojectionは、redactionや切り詰めではなくplan submitの拒否になります。
 
-3役は現在のクライアントモデルを順番に使います。Kiokukoが別モデルを呼ぶことはなく、OpenAI、Anthropic、OpenCodeのAPI keyもKiokuko側には不要です。Codex/Claude Codeは上限付きStop hook、OpenCodeは上限付き`session.idle` pluginを使います。OpenCodeでは子sessionのidleを無視し、同じ完了turnの重複配送を抑止します。`task_prepare`時にホストsessionが不明なら、最初の一致hookがpending active runが一件だけの場合に限って原子的に結合します。曖昧なら推測せず制御を返し、確定済みの結合は変更できません。Claude Codeではネイティブの8回連続block強制解除より前にKiokukoが制御をユーザーへ返します。adapter停止時は固定警告付きでfail-openします。外部Skillは引き続きuntrusted reference-onlyで、自動インストール・自動実行しません。
+### 計画開始時に環境情報が不足・変化した場合
+
+ここでいう「環境情報」は、現在のAIクライアントで利用できるSkillとMCPツールの一覧です。ホストが自動収集する内部情報であり、ユーザーが一覧の保存場所を探したり、設定データを手作業で作成したりする必要はありません。
+
+この一覧が何らかの理由で計画へ引き継がれていない、またはタスク準備時から変わっている場合、Kiokukoは安全確認を完了できないため作業を開始しません。関連するSkillの探索、3件の助言結果の計画への反映、重複実行を防ぐ受付記録の作成、計画版の更新より前に停止するため、この計画開始による新しい作業や追加のコード変更はありません。そのうえで、状況に応じて次の選択肢を表示し、ユーザーの明示回答を待ちます。
+
+各選択肢は、ラベルと推奨表示、どのような意図に適するか、選択後に何が起きるか、の順で表示されます。
+
+環境情報が引き継がれていないだけで、現在の実行をそのまま継続できる場合：
+
+- **同じ計画で続ける（推奨）**：計画内容は正しく、現在の環境情報を付け直すだけでよい場合に選びます。ホストが環境情報を自動で付け直し、現在の実行をそのまま続けます。
+- **計画を見直す**：作業範囲、作業項目、確認方法を変更してから続けたい場合に選びます。クライアントが変更内容を質問し、回答があるまで実装を開始しません。
+- **中止する**：この作業を続けない場合に選びます。現在の実行を取り消し、代わりの実行は作りません。
+
+利用できるSkillやMCPツールがタスク準備後に変わった場合：
+
+- **現在の環境で同じ計画をやり直す（推奨）**：計画内容は正しく、利用できる機能だけが変わった場合に選びます。現在の実行を先に取り消し、現在の環境と同じ確定済み計画で新しい実行を開始します。
+- **計画を見直してからやり直す**：機能の増減に合わせて作業範囲、作業項目、確認方法も変更したい場合に選びます。クライアントが変更内容を質問し、回答後に現在の実行を取り消して、現在の環境と修正済み計画で新しい実行を開始します。
+- **中止する**：この作業を続けない場合に選びます。現在の実行を取り消し、代わりの実行は作りません。
+
+旧動作によって今回の実行がすでに終了している場合：
+
+- **同じ計画で新しくやり直す（推奨）**：終了済み実行の計画内容は正しく、そのまま再利用したい場合に選びます。終了済み実行は変更せず、現在の環境と同じ確定済み計画で新しい実行を開始します。
+- **計画を見直してからやり直す**：代わりの実行を作る前に、作業範囲、作業項目、確認方法を変更したい場合に選びます。クライアントが変更内容を質問し、終了済み実行は変更せず、回答後に現在の環境と修正済み計画で新しい実行を開始します。
+- **中止する**：この作業を再開しない場合に選びます。終了済み実行は終了したままとし、新しい実行は作りません。
+
+クライアントは説明をユーザーの言語で表示し、機械用の選択値、内部の理由コード、処理名、機能一覧、識別子、計画版、表示形式の版番号、生のJSONは表示しません。どの状況でも、ユーザーが選択する前に再提出、取消、新しい実行の作成を自動で行いません。
+
+3役は現在のクライアントモデルを順番に使います。Kiokukoが別モデルを呼ぶことはなく、OpenAI、Anthropic、OpenCodeのAPI keyもKiokuko側には不要です。Codex/Claude Codeは上限付きStop hook、OpenCodeは上限付き`session.idle` pluginを使います。OpenCodeでは子sessionのidleを無視し、同じ完了turnの重複配送を抑止します。同じOSユーザーでcanonical repositoryへアクセスできるlocal processは、そのrunを再開できるものとして信頼します。PID、process ancestry、実行ファイル、code signing、継承tokenによる証明は追加しません。adapterはsessionの完全一致routeを優先し、一致がなければCodex、Claude Code、OpenCodeをまたいでcanonical repository内の一意なactive runを原子的に再ルーティングし、以前のclient versionを消去します。複数候補なら全runを変更せず制御を返します。公開応答の`clientBinding`は現在のrouteを表し、`bound`は所有者を意味しません。sessionごとのcontinuation上限到達はそのsessionの自動継続だけを止め、runとledgerは別のlocal project clientが再開できるactive状態を維持します。Claude Codeではネイティブの8回連続block強制解除より前にKiokukoが制御をユーザーへ返します。Hermesに自動continuation hookはありませんが、同じrun identityを使うMCP操作は継続できます。adapter停止時は固定警告付きでfail-openします。外部Skillは引き続きuntrusted reference-onlyで、自動インストール・自動実行しません。
 
 ```bash
 kiokuko setup --clients codex,opencode,claude --enno-oduno on
@@ -86,32 +158,6 @@ npm run test:e2e:agents
 - Claude Code
 - Hermes Agent
 
-## 使うほど賢くなる仕組み
-
-```text
-ユーザーの依頼
-      ↓
-関連する過去の記憶を検索
-      ↓
-AIが記憶を参照して作業
-      ↓
-再利用できる成果や教訓を保存
-      ↓
-次の依頼で再び検索
-```
-
-Kiokukoは、次の流れを繰り返します。
-
-1. 作業前に、現在のプロジェクトとGlobal記憶を検索する
-2. 関連性の高い記憶だけをAIへ渡す
-3. AIが作業を実行する
-4. 作業後に、再利用できる知識を記憶する
-5. 次の作業で、その記憶を再利用する
-
-つまりKiokukoは、**永続的な記憶を蓄積していくRAGシステム**です。
-
-MCPはAIクライアントとKiokukoを接続し、RAGは必要な記憶を検索してAIへ渡します。
-
 ## 記憶はプロジェクトごとに分離
 
 通常の検索では、無関係なプロジェクトの記憶を混ぜません。

package/README.ko.md

@@ -12,7 +12,7 @@ Kiokuko는 AI 코딩 에이전트를 위한 외부 메모리입니다.
 
 ## 바로 시작하기
 
-Node.js 26.1.0 이상이 필요합니다.
+Node.js 24.16.0 이상이 필요하며, Node.js 26.1.0 이상도 지원합니다.
 다음 두 명령어로 쉽게 시작할 수 있습니다 💕
 
 ```bash
@@ -22,16 +22,52 @@ kiokuko setup
 
 `setup`은 설치된 지원 클라이언트를 감지하고 SQLite 데이터베이스와 MCP 연결을 자동으로 설정합니다.
 대화형 setup은 감사된 community Skill도 참고 자료로 사용할지 묻고, 기본 응답은 아니요입니다.
-Codex, Claude Code, OpenCode를 새로 설정할 때는 Enno-Oduno 에이전트 루프도 활성화됩니다. 기존 관리 환경은 `--enno-oduno on`을 명시적으로 선택할 때까지 유지되며, `--enno-oduno off`는 Enno-Oduno가 소유한 hook 또는 plugin만 제거합니다.
-setup은 번들된 `kiokuko-enno-oduno` controller Skill을 `kiokuko-single-purpose-functions`, `kiokuko-ui-design-soul`과 함께 선택한 모든 지원 클라이언트에 설치합니다.
-모델용 메모리는 capability gate를 거치는 MCP 도구 `task_prepare`와
-`task_answer`를 통해서만 작업에 전달됩니다. `task_prepare`는 Enno-Oduno의 진입점이기도 합니다. Enno-Oduno는 호출한 harness를 식별하고 Akinator intake를 소유하며, 실행 가능한 요청을 Zenki에 넘기기 전에 Oduno 이상 상태를 도출합니다. hook은 메모리를 암묵적으로 불러오거나 계획을 우회하지 않습니다. canonical repository에서 모호하지 않은 단 하나의 pending active run만 client session에 바인딩한 뒤 Oduno, Zenki, Goki 또는 최종 review의 계속 여부를 gate합니다. repository 전체의 최신 run을 선택하지 않습니다.
-
-모든 `task_prepare` 호출은 클라이언트 모델이 해당 논리 요청을 위해 로컬 `kiokuko-soul` Skill 전체를 읽은 후 `soulRead: true`를 전달해야 합니다. 또한 모든 작업에서 정확히 일치하는 로컬 `kiokuko-soul` capability가 필요하며, 누락되었거나 availability를 알 수 없으면 intake가 완료되지 않았더라도 fail-close합니다. 이 boolean은 클라이언트의 명시적 attestation이며, 모델이 Skill을 이해하고 준수했다는 remote proof는 아닙니다.
 
 설정 후 대상 AI 클라이언트를 실행하고 평소처럼 사용하면 됩니다. 이미 실행 중이라면 한 번 종료한 후 다시 시작하십시오. setup이 Codex Stop hook을 생성하거나 업데이트했다면 Codex에서 `/hooks`를 열고 해당 hook을 명시적으로 신뢰하십시오.
 
-### Enno-Oduno 에이전트 루프
+## 사용할수록 똑똑해지는 구조
+
+```text
+사용자 요청
+      ↓
+관련 과거 메모리 검색
+      ↓
+AI가 메모리를 참고해 작업
+      ↓
+재사용 가능한 결과나 교훈 저장
+      ↓
+다음 요청에서 다시 검색
+```
+
+Kiokuko는 다음 흐름을 반복합니다.
+
+1. 작업 전에 현재 프로젝트와 Global 메모리를 검색합니다
+2. 관련성이 높은 메모리만 AI에 전달합니다
+3. AI가 작업을 수행합니다
+4. 작업 후 재사용할 수 있는 지식을 메모리로 저장합니다
+5. 다음 작업에서 그 메모리를 재사용합니다
+
+즉, Kiokuko는 **영구 메모리를 축적하는 RAG 시스템**입니다.
+
+MCP는 AI 클라이언트와 Kiokuko를 연결하고, RAG는 필요한 메모리를 검색해 AI에 전달합니다.
+
+### 설정 후 AI 에이전트의 동작
+
+#### AI Akinator
+
+AI 에이전트에게 전달된 요청이 너무 모호해 AI가 구체적인 작업을 파악하기 어려우면, Akinator가 내부 질문을 통해 AI에 필요한 수준까지 요청을 구체화합니다. 관련 언어나 프레임워크 등의 Skill이 있으면 사용할 수 있도록 준비합니다.
+
+#### Enno-Oduno (役小角)
+
+AI 에이전트의 요청을 처리하는 Enno-Oduno 루프가 활성화됩니다.
+
+요청의 이상적인 결과를 정하고, 작업을 계획하고, 작은 에이전트들에게 구현을 orchestration한 뒤, 마지막으로 결과가 이상적인 상태에 맞는지 자동으로 확인합니다.
+
+#### 메모리 저장
+
+모델용 메모리는 capability gate를 거치는 MCP 도구 `task_prepare`와 `task_answer`를 통해서만 작업에 전달됩니다. `task_prepare`는 Enno-Oduno의 진입점입니다. 작업이 끝나면 내용을 기록하고 AI가 재사용할 지식으로 승격할 수 있는지 검토합니다. 실제로 유용한 지식이 승격되도록 자동 조정됩니다.
+
+### Enno-Oduno 에이전트 루프 상세
 
 `build`, `debug`, `review`, `devops` 작업에서는 `task_prepare`가 run-bound loop를 시작하고 `ennoOduno`를 반환합니다. 강제되는 역할 순서는 다음과 같습니다.
 
@@ -47,18 +83,55 @@ setup은 번들된 `kiokuko-enno-oduno` controller Skill을 `kiokuko-single-purp
   -> Zenki가 WorkUnit마다 version이 지정된 expertRefs 1~3개를 선택하며 기본적으로 선택하지 않은 fragment는 읽지 않음
   -> Zenki가 WorkPlan, WorkUnit, expert refs, Skill snapshot 및 verifier를 제출
   -> Enno-Oduno가 필요한 사용자 확인을 받음
-  -> Goki가 승인된 WorkUnit만 orchestration
-  -> Enno-Oduno가 새로운 final-verifier 증거를 review
-       -> 성공: Enno-Oduno가 수락하고 읽기 전용 Oduno meditation으로 전환
+   -> Goki가 승인된 WorkUnit만 orchestration
+   -> enno_verify_prepare가 final verifier를 실행하고 새로운 증거를 저장
+   -> 증거 준비 후에만 parent host가 final-review Advisor를 fan-out
+   -> enno_finish가 저장된 증거에서 accept/replan/block을 결정
+        -> 성공: Enno-Oduno가 수락하고 읽기 전용 Oduno meditation으로 전환
             -> 변경되었거나 승인된 path에서 근거가 있는 오래된 test 또는 함수를 탐색
             -> enno_meditation_submit이 삭제하지 않고 후보를 저장한 뒤 run을 완료
        -> 실패: Enno-Oduno가 revision을 올리고 feedback을 Zenki에 반환
-  -> Zenki가 수정된 plan을 제출하고 확인이 성공한 뒤에만 Goki를 재개할 수 있음
+   -> Zenki가 수정된 plan을 제출하고 확인이 성공한 뒤에만 Goki를 재개할 수 있음
 ```
 
+Final Review는 의도적으로 두 단계입니다. `enno_verify_prepare`는 database
+transaction 밖에서 shell을 비활성화하고 repository로 제한된 cwd에서 승인된
+verifier를 실행한 뒤 현재 contract revision과 mutation revision에 연결된 새로운
+증거를 저장합니다. `enno_finish`는 subprocess를 실행하지 않고 저장된 최신 통과
+증거만으로 수락합니다. 테스트 통과만으로는 run을 수락하지 않습니다.
+Enno continuation을 활성화하면 Codex와 Claude Code는 제한된 Stop hook을 사용하고,
+OpenCode는 제한된 `session.idle` plugin을 사용합니다. Hermes는 native stdio MCP와
+번들 Skill만 사용하며 Enno continuation adapter를 설치하지 않습니다.
+
 따라서 intake가 완료되지 않으면 Enno-Oduno directive와 `answer_intake`를 반환하며, `requiredSkills`에는 `kiokuko-enno-oduno`가 포함되고 Zenki는 아직 시작되지 않습니다. 준비된 intake는 먼저 `oduno_ideal`과 `submit_ideal`을 반환합니다. `enno_ideal_submit`은 Akinator가 선택한 discovery set의 모든 Skill에 대해 정확히 하나의 기여를 요구하며, 외부 Skill은 신뢰할 수 없는 reference-only 지침으로 유지됩니다. 그 후에만 run은 revision-bound Zenki directive를 반환합니다. 이 directive의 `requiredSkills`에는 draft Skill snapshot이 비어 있어도 compact index인 `kiokuko-single-purpose-functions`가 포함됩니다. Zenki는 WorkUnit을 선택하기 전에 이 index를 사용해 의미 없는 micro-function을 만들지 않고 code 변경을 응집된 함수 또는 유스케이스 계약과 focused test target으로 나눕니다. code를 변경하는 각 WorkUnit은 이유와 함께 등록된 `expertRefs`를 1~3개 선택해야 하며, UI WorkUnit은 `code.*`와 `ui.*` expert를 각각 하나 이상 요구합니다. `enno_plan_submit`은 누락, 중복, 알 수 없음 또는 제한을 초과한 조합을 거부하고 정확한 선택을 revision과 함께 저장합니다. Goki는 모든 Skill reference가 아니라 해당 fragment만 읽습니다. controller Skill은 role 수준이며 WorkUnit Skill snapshot에 삽입되지 않습니다. Zenki의 전체 plan이 승인되고 필요한 확인이 성공하기 전에는 Goki로 전환할 수 없습니다. 최종 review가 실패해도 이전 Goki WorkUnit을 직접 재개하지 않습니다. 거부된 plan과 verifier 증거를 이전 revision의 기록으로 보존하고 `zenki_planning`으로 이동해 새로운 revision-bound plan을 요구합니다. 승인된 review는 직접 완료되지 않고 `oduno_meditation`으로 이동합니다. `enno_meditation_submit`은 repository를 변경하지 않고 검사한 repository-relative path와 근거가 있는 오래된 test 또는 함수 후보를 저장한 뒤 run을 완료합니다. 응답의 `orchestrationId`는 모든 Enno MCP 작업에서 사용되며 host session identity와 분리됩니다. 추론한 scope, acceptance criteria, Skill, expert 선택 또는 verifier command가 있으면 구현 전에 일반 클라이언트 UI로 확인을 반환합니다. `needs_confirmation` 응답에는 확정된 계약의 결정적 표시 projection인 `ennoOduno.directive.userFacingConfirmation`이 포함됩니다. scope, 제외 항목, 완료 조건, 표시 번호 의존성을 가진 작업 항목, reference-only 상태를 포함한 Skill, 선택 이유가 있는 전문 관점, focused/final checks, 시도 상한이 각각 provenance basis(사용자 지정, 저장소 검증, 제안) 라벨과 함께 한 번씩 나타납니다. 클라이언트 모델은 raw directive JSON이나 내부 식별자를 노출하지 않고 모든 항목을 사용자 언어로 제시한 뒤 명시적인 approve, revise, cancel을 기다립니다. 기밀처럼 보이는 표시 값이나 64 KiB를 초과하는 projection은 가리거나 잘라내는 대신 plan 제출을 거부합니다.
 
-세 역할은 현재 클라이언트 모델을 사용합니다. Kiokuko는 별도의 모델을 호출하지 않으며 OpenAI, Anthropic 또는 OpenCode API credential을 요구하지 않습니다. Codex와 Claude Code는 횟수가 제한된 Stop hook을 사용하고 OpenCode는 횟수가 제한된 `session.idle` plugin을 사용합니다. OpenCode는 child-session idle event를 무시하고 같은 완료 turn의 반복 delivery를 deduplicate합니다. `task_prepare`에서 host session을 사용할 수 없었다면 최초의 일치 hook은 pending active run이 정확히 하나일 때만 원자적으로 바인딩합니다. 모호하면 추측하지 않고 제어를 반환하며 완료된 binding은 변경할 수 없습니다. Kiokuko는 Claude Code의 기본 8회 연속 Stop-block override보다 먼저 제어를 반환합니다. adapter 실패 시 고정 warning과 함께 클라이언트가 중지될 수 있습니다. 외부 Skill은 신뢰할 수 없는 reference-only 자료이며 자동으로 설치되거나 실행되지 않습니다.
+### 계획 시작 환경 정보가 누락되거나 변경된 경우
+
+여기서 환경 정보는 현재 AI 클라이언트에서 사용할 수 있는 Skill과 MCP tool 목록입니다. host가 자동으로 수집하므로 사용자가 catalog 위치를 찾거나 JSON을 만들 필요가 없습니다. 이 정보가 계획에 전달되지 않았거나 작업 준비 후 변경되면 Kiokuko는 Skill discovery, advisory 소비, receipt 생성 또는 계약 revision 변경 전에 중지합니다. 따라서 이번 계획 시작으로 새 작업이나 추가 code 변경은 발생하지 않습니다.
+
+각 선택지는 label과 추천 여부, 어떤 사용자 의도에 맞는지, 선택 후 정확히 무엇이 일어나는지의 순서로 표시됩니다.
+
+환경 정보만 누락되어 현재 시도를 계속할 수 있는 경우:
+
+- **같은 계획으로 계속(권장)** — 계획은 여전히 올바르고 현재 환경 정보만 다시 붙이면 될 때 선택합니다. host가 정보를 자동으로 붙이고 같은 시도를 계속합니다.
+- **계획 검토** — 계속하기 전에 범위, 작업 항목 또는 검증 방법을 바꾸고 싶을 때 선택합니다. 클라이언트가 변경 내용을 묻고 답변 전에는 구현을 시작하지 않습니다.
+- **취소** — 작업을 계속하지 않을 때 선택합니다. 현재 시도를 취소하며 대체 시도를 만들지 않습니다.
+
+작업 준비 후 사용할 수 있는 기능이 변경된 경우:
+
+- **현재 환경에서 같은 계획 다시 시작(권장)** — 계획은 올바르고 사용할 수 있는 기능만 바뀌었을 때 선택합니다. 현재 시도를 먼저 취소한 뒤 현재 환경과 같은 합의된 계획으로 새 시도를 시작합니다.
+- **계획을 검토한 뒤 다시 시작** — 기능 변경에 맞춰 범위, 작업 항목 또는 검증 방법도 바꾸고 싶을 때 선택합니다. 클라이언트가 변경 내용을 묻고, 답변 후 현재 시도를 취소한 다음 현재 환경과 수정된 계획으로 새 시도를 시작합니다.
+- **취소** — 작업을 계속하지 않을 때 선택합니다. 현재 시도를 취소하며 대체 시도를 만들지 않습니다.
+
+이전 동작으로 해당 시도가 이미 종료된 경우:
+
+- **같은 계획으로 다시 시작(권장)** — 종료된 시도의 계획이 여전히 올바르고 재사용하려는 경우 선택합니다. 종료된 시도는 그대로 두고 현재 환경과 같은 합의된 계획으로 새 시도를 시작합니다.
+- **계획을 검토한 뒤 다시 시작** — 대체 시도를 만들기 전에 범위, 작업 항목 또는 검증 방법을 바꾸려는 경우 선택합니다. 클라이언트가 변경 내용을 묻고 종료된 시도는 그대로 두며, 답변 후 현재 환경과 수정된 계획으로 새 시도를 시작합니다.
+- **취소** — 작업을 다시 시작하지 않을 때 선택합니다. 종료된 시도는 종료 상태로 유지되고 새 시도는 만들어지지 않습니다.
+
+클라이언트는 안내를 사용자 언어로 번역하고 기계용 action, 내부 reason code와 tool/field 이름, capability catalog, 식별자, revision, 표시 형식 version 또는 raw JSON을 표시하지 않습니다. 사용자가 명시적으로 선택하기 전에는 재시도, 취소 또는 대체 시도 생성을 자동으로 수행하지 않습니다.
+
+세 역할은 현재 클라이언트 모델을 사용합니다. Kiokuko는 별도의 모델을 호출하지 않으며 OpenAI, Anthropic 또는 OpenCode API credential을 요구하지 않습니다. Codex와 Claude Code는 횟수가 제한된 Stop hook을 사용하고 OpenCode는 횟수가 제한된 `session.idle` plugin을 사용합니다. OpenCode는 child-session idle event를 무시하고 같은 완료 turn의 반복 delivery를 deduplicate합니다. 같은 OS 사용자로 canonical repository에 접근할 수 있는 local process는 해당 run을 재개할 수 있다고 신뢰합니다. PID, process ancestry, executable, code signing 또는 inherited token 증명은 추가하지 않습니다. adapter는 정확한 session route를 우선하고, 일치하는 route가 없으면 Codex, Claude Code, OpenCode 사이에서 canonical repository의 모호하지 않은 단 하나의 active run을 원자적으로 reroute하고 이전 client version을 지웁니다. 후보가 여러 개면 어떤 run도 변경하지 않고 제어를 반환합니다. 공개 응답의 `clientBinding`은 현재 route를 나타내며 `bound`는 소유자를 뜻하지 않습니다. session별 continuation 한도에 도달하면 그 session의 자동 계속만 중지하며 run과 ledger는 다른 local project client가 재개할 수 있도록 active 상태를 유지합니다. Kiokuko는 Claude Code의 기본 8회 연속 Stop-block override보다 먼저 제어를 반환합니다. Hermes에는 자동 continuation hook이 없지만 같은 run identity를 사용하는 MCP 작업은 계속할 수 있습니다. adapter 실패 시 고정 warning과 함께 클라이언트가 중지될 수 있습니다. 외부 Skill은 신뢰할 수 없는 reference-only 자료이며 자동으로 설치되거나 실행되지 않습니다.
 
 ```bash
 kiokuko setup --clients codex,opencode,claude --enno-oduno on
@@ -81,32 +154,6 @@ npm run test:e2e:agents
 - Claude Code
 - Hermes Agent
 
-## 사용할수록 똑똑해지는 구조
-
-```text
-사용자 요청
-      ↓
-관련 과거 메모리 검색
-      ↓
-AI가 메모리를 참고해 작업
-      ↓
-재사용 가능한 결과나 교훈 저장
-      ↓
-다음 요청에서 다시 검색
-```
-
-Kiokuko는 다음 흐름을 반복합니다.
-
-1. 작업 전에 현재 프로젝트와 Global 메모리를 검색합니다
-2. 관련성이 높은 메모리만 AI에 전달합니다
-3. AI가 작업을 수행합니다
-4. 작업 후 재사용할 수 있는 지식을 메모리로 저장합니다
-5. 다음 작업에서 그 메모리를 재사용합니다
-
-즉, Kiokuko는 **영구 메모리를 축적하는 RAG 시스템**입니다.
-
-MCP는 AI 클라이언트와 Kiokuko를 연결하고, RAG는 필요한 메모리를 검색해 AI에 전달합니다.
-
 ## 메모리는 프로젝트별로 분리됩니다
 
 일반 검색에서는 관련 없는 프로젝트의 메모리를 섞지 않습니다.

package/README.md

@@ -12,7 +12,7 @@ Users do not need to paste past context into every prompt or search for memories
 
 ## Get started quickly
 
-Node.js 26.1.0 or newer is required.
+Node.js 24.16.0 or newer is required; Node.js 26.1.0 or newer is also supported.
 Get started easily with these two commands 💕
 
 ```bash
@@ -22,21 +22,52 @@ kiokuko setup
 
 `setup` detects supported clients that are installed and automatically configures the SQLite database and MCP connection.
 Interactive setup asks whether audited community Skills may also be used as reference material; the default answer is no.
-For new Codex, Claude Code, and OpenCode installations, setup also enables the Enno-Oduno agent loop. Existing managed installations are preserved until `--enno-oduno on` is explicitly selected; `--enno-oduno off` removes only Enno-Oduno-owned hooks or plugins.
-Setup installs the bundled `kiokuko-enno-oduno` controller Skill alongside `kiokuko-single-purpose-functions` and `kiokuko-ui-design-soul` in every selected supported client.
-Model-facing memory enters a task only through the capability-gated `task_prepare`
-and `task_answer` MCP tools. `task_prepare` is also the Enno-Oduno entry point: Enno-Oduno identifies the calling harness, owns Akinator intake, and derives the Oduno ideal before it hands an actionable request to Zenki. Hooks do not recall memory or bypass planning; they bind only the single unambiguous pending active run in the canonical repository, then gate Oduno, Zenki, Goki, or final-review continuation. They never select a repository-wide latest run.
-
-Every `task_prepare` call requires `soulRead: true` after the client model reads
-the complete local `kiokuko-soul` Skill for that logical request. It also
-requires the exact local `kiokuko-soul` capability for every task; missing or
-unknown availability fails closed even during incomplete intake. The boolean is
-an explicit client attestation, not remote proof that the model understood or
-followed the Skill.
 
 After setup, launch the target AI client and use it as usual. If it is already running, quit it once and restart it. When setup creates or updates the Codex Stop hook, open `/hooks` in Codex and explicitly trust that hook.
 
-### Enno-Oduno agent loop
+## How it gets smarter with use
+
+```text
+User request
+      ↓
+Search relevant past memories
+      ↓
+AI uses the memories to do the work
+      ↓
+Store reusable results and lessons
+      ↓
+Search again in the next request
+```
+
+Kiokuko repeats the following flow.
+
+1. Before work, search the current project and Global memory
+2. Pass only highly relevant memories to the AI
+3. The AI performs the work
+4. After the work, store reusable knowledge as memory
+5. Reuse that memory in the next task
+
+In other words, Kiokuko is a **RAG system that accumulates persistent memory**.
+
+MCP connects the AI client to Kiokuko, while RAG searches for the memories needed and passes them to the AI.
+
+### What the AI agent does after setup
+
+#### AI Akinator
+
+When a request is too vague for the AI to act on, Akinator asks internal questions and narrows it into the concrete details the AI needs. If relevant Skills are available, such as language or framework guidance, it makes them available for use.
+
+#### Enno-Oduno (役小角)
+
+Enno-Oduno enables a loop for processing requests sent to the AI agent.
+
+It defines the ideal outcome, plans the work, delegates implementation to smaller agents through orchestration, and finally checks whether the result matches that ideal.
+
+#### Memory storage
+
+Model-facing memory enters a task only through the capability-gated `task_prepare` and `task_answer` MCP tools. `task_prepare` is the Enno-Oduno entry point. After the task, its contents are recorded and considered for promotion into reusable AI knowledge. The system is tuned to promote knowledge that is useful in practice.
+
+### Enno-Oduno agent loop details
 
 For `build`, `debug`, `review`, and `devops` tasks, `task_prepare` starts the run-bound loop and returns `ennoOduno`. The enforced role order is:
 
@@ -52,18 +83,55 @@ User request
   -> Zenki selects 1-3 versioned expertRefs per WorkUnit and reads no unselected fragments by default
   -> Zenki submits the WorkPlan, WorkUnits, expert refs, Skill snapshot, and verifiers
   -> Enno-Oduno obtains any required user confirmation
-  -> Goki orchestrates only the approved WorkUnits
-  -> Enno-Oduno reviews fresh final-verifier evidence
-       -> pass: Enno-Oduno accepts and enters read-only Oduno meditation
+   -> Goki orchestrates only the approved WorkUnits
+   -> enno_verify_prepare runs the final verifiers and stores fresh evidence
+   -> after evidence preparation, the parent host may fan out the final-review Advisors
+   -> enno_finish decides accept/replan/block from the stored evidence
+        -> pass: Enno-Oduno accepts and enters read-only Oduno meditation
             -> inspect changed and approved paths for evidence-backed obsolete tests or functions
             -> enno_meditation_submit persists candidates without deleting them, then completes the run
        -> fail: Enno-Oduno increments the revision and returns feedback to Zenki
-  -> Goki can resume only after Zenki submits the revised plan and confirmation succeeds
+   -> Goki can resume only after Zenki submits the revised plan and confirmation succeeds
 ```
 
+Final Review is deliberately two-phase. `enno_verify_prepare` runs approved
+verifiers outside database transactions with shell disabled and a
+repository-bounded cwd, then binds the fresh evidence to the current contract
+and mutation revisions. `enno_finish` never launches a subprocess and accepts
+only stored fresh passing evidence. Passing tests alone do not accept a run.
+Codex and Claude Code use bounded Stop hooks and OpenCode uses a bounded
+`session.idle` plugin when Enno continuation is enabled. Hermes uses native
+stdio MCP and bundled Skills only; it has no Enno continuation adapter.
+
 Incomplete intake therefore returns an Enno-Oduno directive and `answer_intake`; its `requiredSkills` contains `kiokuko-enno-oduno`, and Zenki is not started yet. A ready intake first returns `oduno_ideal` and `submit_ideal`. `enno_ideal_submit` requires exactly one contribution for every Skill in Akinator's selected discovery set; external Skills remain untrusted reference-only guidance. Only then does the run return a revision-bound Zenki directive whose `requiredSkills` includes the compact `kiokuko-single-purpose-functions` index even while the draft Skill snapshot is empty. Before choosing WorkUnits, Zenki uses that index to divide code changes into cohesive function or use-case contracts with focused test targets, without meaningless micro-functions. Each code-changing WorkUnit must select one to three registered `expertRefs` with reasons; UI WorkUnits require both a `code.*` and a `ui.*` expert. `enno_plan_submit` rejects missing, duplicate, unknown, or oversized mixtures and then persists the exact selection with the revision. Goki reads those fragments rather than every Skill reference. The controller Skill is role-level and is not inserted into WorkUnit Skill snapshots. Goki cannot be entered until Zenki's complete plan has been accepted and required confirmation has succeeded. A failed final review never reactivates an old Goki WorkUnit. It preserves the rejected plan and verifier evidence under their old revision, advances to `zenki_planning`, and requires a new revision-bound plan. An accepted review advances to `oduno_meditation`, not directly to completion. `enno_meditation_submit` persists the inspected repository-relative paths and evidence-backed obsolete test or function candidates without mutating the repository, then completes the run. The response's `orchestrationId` is used by every Enno MCP operation and is separate from the host session identity. Inferred scope, acceptance criteria, Skills, expert selections, or verifier commands are returned for normal user confirmation before execution. A `needs_confirmation` response carries `ennoOduno.directive.userFacingConfirmation`, a deterministic display projection of the decided contract: scope, exclusions, completion criteria, work items with display-number dependencies, skills with their reference-only status, expertise with selection reasons, focused and final checks, and the attempt limit, each labeled with its provenance basis (user-specified, repository-verified, or proposed). The client model presents every item in the user's language without raw directive JSON or internal identifiers, then waits for an explicit approve, revise, or cancel; secret-shaped display values or a projection above 64 KiB reject the plan submit instead of being redacted or truncated.
 
-The three roles use the current client model; Kiokuko does not call a second model or require OpenAI, Anthropic, or OpenCode API credentials. Codex and Claude Code use bounded Stop hooks, while OpenCode uses a bounded `session.idle` plugin. OpenCode ignores child-session idle events and deduplicates repeated delivery of the same completed turn. If the host session was unavailable at `task_prepare`, the first matching hook atomically binds it only when exactly one pending active run matches; ambiguity returns control without guessing. A completed binding is immutable. Kiokuko returns control before Claude Code's native eighth consecutive Stop-block override. Adapter failure allows the client to stop with a fixed warning. External Skills remain untrusted reference-only and are never installed or executed automatically.
+### Recovering when plan-start environment information is missing or changed
+
+The environment information used here is the list of Skills and MCP tools available to the current AI client. The host collects it automatically; the user never needs to find a catalog or construct JSON. If it is missing from the plan or has changed since task preparation, Kiokuko stops before Skill discovery, advisory consumption, receipt creation, or contract revision. This plan-start attempt therefore begins no new work and makes no additional code changes.
+
+Every recovery choice is displayed in the same order: its label and recommendation, when the choice fits the user's intent, and exactly what happens after selection. The three situations are:
+
+Missing environment information while the current attempt can continue:
+
+- **Continue with the same plan (Recommended)** — Choose this when the plan is still correct and only the current environment information needs to be attached. The host attaches it automatically and continues the same attempt.
+- **Review the plan** — Choose this when the scope, work items, or verification should change. The client asks what to change and starts no implementation until the user answers.
+- **Cancel** — Choose this when the work should not continue. The current attempt is cancelled and no replacement is created.
+
+Available features changed after task preparation:
+
+- **Restart the same plan in the current environment (Recommended)** — Choose this when the plan is still correct and only the available features changed. The current attempt is cancelled, then a new attempt starts with the current environment and the same agreed plan.
+- **Review the plan before restarting** — Choose this when the changed features should alter the scope, work items, or verification. The client asks what to change; after the user answers, the current attempt is cancelled and a new attempt starts with the current environment and revised plan.
+- **Cancel** — Choose this when the work should not continue. The current attempt is cancelled and no replacement is created.
+
+The earlier attempt already ended under the legacy behavior:
+
+- **Restart with the same plan (Recommended)** — Choose this when the ended attempt's plan is still correct. The ended attempt stays unchanged, and a new attempt starts with the current environment and the same agreed plan.
+- **Review the plan before restarting** — Choose this when the scope, work items, or verification should change before creating a replacement. The client asks what to change; the ended attempt stays unchanged, and a new attempt starts with the current environment and revised plan only after the user answers.
+- **Cancel** — Choose this when the work should not restart. The ended attempt remains ended and no new attempt is created.
+
+The client translates this guidance into the user's language. It never displays machine actions, reason codes, internal tool or field names, the capability catalog, identifiers, revisions, presentation versions, or raw JSON. No retry, cancellation, or replacement task occurs before the user's explicit choice.
+
+The three roles use the current client model; Kiokuko does not call a second model or require OpenAI, Anthropic, or OpenCode API credentials. Codex and Claude Code use bounded Stop hooks, while OpenCode uses a bounded `session.idle` plugin. OpenCode ignores child-session idle events and deduplicates repeated delivery of the same completed turn. Local processes running as the same OS user with access to the canonical repository are trusted to resume its run without PID, process-ancestry, executable, signing, or inherited-token proof. The adapter prefers an exact session route; when no exact route exists, it may atomically reroute the single unambiguous active run across Codex, Claude Code, and OpenCode, clearing the previous client version. Ambiguity returns control without mutation. The public `clientBinding` response field reports the current route; `bound` does not mean owner. Reaching one session's continuation limit stops only that session and leaves the run and ledger active for another local project client. Kiokuko returns control before Claude Code's native eighth consecutive Stop-block override. Hermes has no automatic continuation hook, but can continue through MCP with the same run identity. Adapter failure allows the client to stop with a fixed warning. External Skills remain untrusted reference-only and are never installed or executed automatically.
 
 ```bash
 kiokuko setup --clients codex,opencode,claude --enno-oduno on
@@ -86,32 +154,6 @@ Supported clients:
 - Claude Code
 - Hermes Agent
 
-## How it gets smarter with use
-
-```text
-User request
-      ↓
-Search relevant past memories
-      ↓
-AI uses the memories to do the work
-      ↓
-Store reusable results and lessons
-      ↓
-Search again in the next request
-```
-
-Kiokuko repeats the following flow.
-
-1. Before work, search the current project and Global memory
-2. Pass only highly relevant memories to the AI
-3. The AI performs the work
-4. After the work, store reusable knowledge as memory
-5. Reuse that memory in the next task
-
-In other words, Kiokuko is a **RAG system that accumulates persistent memory**.
-
-MCP connects the AI client to Kiokuko, while RAG searches for the memories needed and passes them to the AI.
-
 ## Memory is separated by project
 
 Ordinary searches do not mix in memories from unrelated projects.