kiokuko 1.0.25 → 1.0.27

package/docs/normal-workflow-acceptance.md

@@ -0,0 +1,330 @@
+# Normal-workflow acceptance
+
+G0–G2 test source and package delivery. G3 tests the real model/client. G4 verifies
+raw evidence from an independently approved producer. Local harness tests,
+synthetic transcripts, summary JSON and an artifact's own hash cannot establish
+live acceptance.
+
+## Deterministic checks
+
+```sh
+npm run test:normal-workflow
+npm run typecheck
+node scripts/run-normal-workflow-gates.mjs --output /tmp/kiokuko-normal-gates
+```
+
+Use a new or empty output directory. The gate runner records each stage separately,
+including actual argv/cwd, start/end, exit/signal and before/after commit, dirty
+state and source digest. G0 test counts are N/A. G1 uses Node lifecycle records,
+not TAP or JSON printed by test code. G4 recomputes pass/fail/skip/todo/cancelled
+from each official leaf-completion event, checks one final summary and an ended
+stream, rejects duplicate/unknown/missing IDs, and compares totals to that result. G2 builds, packs once, installs that tarball,
+checks generated Skills and restart behavior, and installs the optional runtime.
+Each stage retains stdout/stderr, argv/cwd/exit/signal/times and its corresponding
+outcome: actual npm pack metadata/sha1/inventory, installed file hashes, deployed
+Skill bytes plus public MCP selector responses, persisted verification state
+before/after MCP restart, and optional package inventory/import completion. G4
+compares these with the same actual tarball. `true`, correctly named commands
+without outcomes, missing stages and interrupted execution cannot pass.
+An optional-runtime download failure is a failure, not an approved skip. G0/G1
+retain their own results when a later stage fails.
+
+The default suite's approved inventory must be reviewed separately and frozen in
+the policy. It is not learned from the result being graded. IDs include relative
+file, runtime event location and test name. An optional skip must name the exact ID in
+that inventory; zero tests, missing IDs, unexpected skips, todo/cancelled/failed
+results and incomplete streams fail acceptance. Count changes require a newly
+reviewed inventory, not editing a report to match.
+A passing completion with a failure reason is contradictory even for an approved
+skip, and is rejected.
+
+Dirty-checkout results are local diagnostics. Source changes during a stage
+invalidate that stage. The runner never marks a local diagnostic as release proof.
+
+## Independent fixture oracle
+
+The public shipping fixture specifies free shipping at 5000 or more and a fee of
+500 below 5000. Its initial bug is exactly at 5000. Membership uses an optional
+second boolean and preserves old calls and non-members.
+
+Development replays the immutable Red tree, the same tests with only the requested
+behavior corrected, and the final Green tree. Existing tests/spec/config remain
+unchanged; only shipping source and additive tests may change. A separate behavior
+oracle checks 0, 4999, 5000 and 5001, old calls and member/non-member combinations.
+
+Fixture tests cannot run arbitrary host Node code. A trusted bridge links only
+`node:test`, `node:assert/strict` (or `node:assert`) and `../shipping.mjs` into a
+separate realm without host objects, process, credentials, filesystem,
+IPC or dynamic code generation. Intrinsics are frozen and privately bound, including collection iterator prototypes;
+replacing a writable global constructor cannot change assertion serialization. Test callbacks execute
+there; a trusted Node host registers their outcomes with the actual test runner.
+A separate parent consumes lifecycle events and writes the result file outside
+the worker's readable/writable roots. Worker stdout/stderr never supply counters.
+The bridge supports synchronous top-level tests and skip/todo, including string
+skip reasons and the native TODO status of tests without a callback. Assertions are
+performed by the real `node:assert` / `node:assert/strict` implementation, preserving
+their distinct loose/strict modes. A frozen null-prototype bridge accepts only a
+bounded primitive string and returns a primitive outcome; no fixture object or
+host exception crosses it. A tagged graph preserves undefined properties, numeric
+special values, bigint, arrays (including holes), plain/null-prototype objects,
+Sets, Maps, Dates, RegExps, sharing and cycles. Functions, symbols, typed arrays,
+custom prototypes, accessors, non-enumerable custom properties, Proxy operations and unknown assertion members are
+explicitly unsupported and produce FAIL_HARNESS even when a fixture catches the
+error. Comparison is never replaced by JSON equality. The helper supports
+equal/strictEqual, notEqual/notStrictEqual, deepEqual/deepStrictEqual,
+notDeepEqual/notDeepStrictEqual, ok and fail. Unsupported imports, async tests, empty registration and premature
+termination cannot supply acceptable proof. This is a bounded fixture runner, not
+a replacement for arbitrary repository test frameworks. VM isolation is combined
+with a separate process, Node permissions and time/output limits.
+
+Explanatory answers require an independent approved reviewer. The original answer
+is retained; the execution model is not asked to produce grading JSON. A review
+contains `schema: shipping-answer-v1`, kind, answerHash, initialHash, specHash,
+reviewer, verdict, reason and ordered criteria from `ANSWER_RUBRIC` in
+`scripts/lib/normal-workflow/answer-review.mjs`. It must assess each fact, including
+negation and contradictions, rather than word presence. The exact answer, reviewed
+fixture and rubric version are bound by hashes. PASS/FAIL/UNCERTAIN are distinct:
+a successfully collected but unreviewed answer remains WAITING_REVIEW;
+stale/unapproved/UNCERTAIN reviews yield FAIL_HARNESS; an independently
+reviewed wrong answer yields FAIL_PRODUCT. Keep reviews outside the model tree.
+Synthetic review fixtures test this contract; they do not claim human or live
+model evaluation occurred.
+
+## Freeze approval before execution
+
+Create the policy outside the model workspace from the authorized run settings,
+reviewed test inventory, approved producer and approved reviewers:
+
+```sh
+node scripts/freeze-normal-workflow-policy.mjs \
+  --approval /path/to/approved-run.json \
+  --test-manifest /path/to/reviewed-test-inventory.json \
+  --producer /path/to/approved-producer.json \
+  --reviewers /path/to/approved-reviewers.json \
+  --output /path/to/frozen-policy.json
+```
+
+The command refuses overwrite and prints the canonical policy hash. Independently
+review and retain that hash before execution. File permissions and a self-computed
+hash alone are not approval. The policy contains the exact provider/model/client
+version/reasoning, clients, all scenario IDs and natural requests, one attempt per
+scenario, all time/turn/tool/cost limits, rubric, reviewed test inventory and the
+producer's repository/workflow/ref/immutable commit. It contains no auth secrets.
+The supported cost condition remains ChatGPT subscription, USD 0 additional spend;
+paid APIs are unsupported. Approval also requires an authFile, approved=true and
+testCredentials=true. Explicit user authorization may designate the currently
+logged-in subscription account for isolated synthetic tests; do not infer this
+from the existence of credentials. The policy excludes the credential path.
+
+A producer file has `repository`, `workflow` (repository-relative workflow path),
+`ref` (branch name), and a full 40-character `commit`. Reviewer input is an array
+of approved reviewer names. Inventory entries have `id` and `optionalSkip`.
+Changing a model, version, client matrix, request, limit or rubric requires a new
+independently approved policy/run. G4 constructs the matrix from that policy;
+live summaries cannot reduce it or supply its expected hash.
+
+## Live execution and current limits
+
+```sh
+node scripts/run-normal-workflow-acceptance.mjs --offline --require-live \
+  --output /tmp/kiokuko-normal-offline
+```
+
+This must exit 1 with NOT_RUN. No model runs and offline cannot pass G3.
+
+```sh
+node scripts/run-normal-workflow-gates.mjs \
+  --policy /path/to/frozen-policy.json --policy-hash APPROVED_HASH \
+  --output /tmp/kiokuko-normal-gates
+node scripts/run-normal-workflow-acceptance.mjs --collect-only \
+  --approval /path/to/approved-run.json \
+  --policy /path/to/frozen-policy.json --policy-hash APPROVED_HASH \
+  --candidate /tmp/kiokuko-normal-gates/candidate.json \
+  --artifact /tmp/kiokuko-normal-gates/candidate.tgz \
+  --output /tmp/kiokuko-normal-live
+```
+
+The live runner checks policy before reading credentials or starting a model. It
+uses isolated HOME/CODEX_HOME/data and installer-generated AGENTS/Skills/hooks.
+Only the approved tarball from G2 is installed; its bytes/source must match.
+Workspace writes exclude the control/evidence directories and the default /tmp
+exceptions. No production memories/config are loaded; credentials and raw client
+rollouts are removed with the isolated controls. Private reasoning and credential
+contents are not archived. Secret output stops capture. No automatic retry erases
+a failed attempt.
+
+Skill evidence requires paired tools/list request/response with required schemas,
+unique call IDs within one proxy session, successful task_inspect responses for
+each required core Skill individually, unique index identities, exact canonical
+identity/body/package version, soul completion before memory-reasoning starts and
+both completions before task_prepare or memory_recall registration. Expected bodies
+come from the candidate package, not capability declarations. Every successful
+ordinary recall is checked individually; multiple recalls may reuse the same
+verified Soul and memory-reasoning reads without replacing either identity. AGENTS additionally
+requires the matching isolated client loader receipt before the natural request;
+project scenarios require actual hook observations. Duplicated reads of one Skill,
+empty discovery, late reads and another session cannot prove loading.
+
+Actual model/effort come from the isolated client's turn-context records. A
+requested model is recorded as requestedModel, not observedModel. Missing or
+unknown actual identity fails closed. Client version matches the exact approved
+version, and G4 checks actual argv, request and measured usage against policy.
+The loader accepts the observed scoped and unscoped AGENTS headings, with exact
+body matching. CLI 0.153.4 records reasoning effort in collaboration settings;
+conflicting legacy/current fields remain unobserved. Its stable Code Mode host
+stays enabled so the model can invoke registered tools; native writes still
+require the observed read-only boundary below.
+
+**Execution-bound CLI checkpoints use an exclusive fixture executor.** Native
+CLI tools run in read-only sandbox with approvals disabled. A real child-process
+write probe must receive EPERM/EACCES with no file/tree change, and the isolated
+client's actual turn-context must also show read-only/never. Configuration alone
+is insufficient. If either proof is absent, development is FAIL_HARNESS.
+The separate MCP executor owns all fixture writes through one queue. It supports
+reading fixture files, writing shipping source/additive tests, and standalone
+fixture test commands. OS access, arbitrary commands, background processes and
+protected-file edits are not execution capabilities of that server. Explanation
+requests expose only file-listing and reading tools; the controller rejects
+writes and test commands even if called directly.
+Only named tools on the two isolated stdio servers are preapproved; unknown
+tools are not exposed and native escalation remains disabled. `agents.enabled`
+is false in addition to the legacy/v2 collaboration feature flags, because separate executor instances or
+interleaved MCP sessions cannot establish exclusive ownership of the fixture.
+Installer-generated hooks are loaded from hooks.json once, without inline copies.
+The server's public initialization instructions and writer description distinguish
+its bounded controller access from native read-only tools; the command description
+states its persistence guarantee. This capability declaration contains no scenario
+answers and does not modify the installed AGENTS or Skill instructions.
+The CLI also receives the same permission boundary through `developer_instructions`
+so its native read-only policy is not mistaken for the absence of the independent
+MCP writer. This declaration contains no Skill selectors, test answers or grading
+hints. The frozen policy pins its hash, and G4 rejects substituted or duplicate
+declarations in the actual command arguments.
+Neither tool teaches expected shipping values or a scenario's test sequence.
+
+For a test command the owner holds the queue, takes a bounded immutable tree,
+runs the protected Node lifecycle supervisor on that tree, writes the command
+ID/exit/signal/tree/hash/lifecycle record, fsyncs the record and directory, and
+only then releases the queue and returns the receipt. G3/G4 match each receipt
+against the same server session and original RPC request/response. The frozen
+policy pins `executorMode: native-readonly-exclusive-fixture-v1`; development
+argv must select read-only sandbox, and the actual sandbox probe is included in
+the identity evidence. Missing or conflicting bindings fail the harness. Delayed CLI
+stdout, immediately queued edits and consecutive events cannot change saved
+Red/Green trees. Every acknowledged writer request is replayed from the original
+fixture to the final tree, including its returned operation sequence and tree hash.
+The first implementation edit must follow the qualifying Red checkpoint; an edit
+followed by a revert cannot disappear between test snapshots. Missing, reordered
+or substituted writer receipts fail closed. Both trees are independently replayed
+again. A complete trace without actual Red still fails. The plain `exec --json` adapter remains
+checkpointAuthority=unavailable when this executor and native boundary are absent;
+its events never photograph a mutable tree. This controlled fixture execution
+path is distinct from unrestricted native CLI workspace writes. The real-model
+matrix must pass on this path before claiming live G3 completion.
+
+**Desktop remains NOT_RUN.** No authoritative desktop execution/loader adapter
+is implemented. CLI success cannot replace desktop scenarios. An explicit tool
+access denial must not be bypassed with another automation path. If desktop is
+in the approved matrix it remains required. Explanation scenarios also remain
+WAITING_REVIEW after a valid collection until an approved independent review is supplied.
+
+Missing native enforcement, executor receipts, independent reviews, protected producer settings or required desktop coverage prevents live release PASS. They do not invalidate passing
+local regression or package-delivery checks.
+
+
+## Collect, independently review, then finalize
+
+`--collect-only` permits a successfully collected explanation to wait for review;
+its exit 0 indicates collection only, never G3 PASS. Other failures and NOT_RUN
+remain failures. `review-requests.json` contains the original answers and their
+answer/tree/spec hashes. Keep the execution account and process away from review
+inputs. Supply a separate JSON array of `{id, review}` for each explanation,
+using the exact ordered rubric criteria, reviewer identity and hashes. Then run:
+
+```sh
+node scripts/finalize-normal-workflow-acceptance.mjs \
+  --live /tmp/kiokuko-normal-live \
+  --policy /path/to/frozen-policy.json --policy-hash APPROVED_HASH \
+  --reviews /path/to/independent-reviews.json
+```
+
+Memory application/inapplicability, verification-definition calls, injected
+selector failures and subsequent recovery are derived from paired raw RPCs. The
+original client stream must have a complete, ordered thread/turn lifecycle;
+its last answer, tool/turn counts, runtime and loader identity must match the
+stored attempt. Replacement answers and execution-summary booleans cannot
+supply these facts. Collection, finalization and G4 share this validation.
+
+The finalizer does not rerun the model or trust previous PASS summaries. It
+reopens original execution, identity, instructions, protocol, loader and trees,
+rechecks policy and independently replays the oracle with the review. Exit 2 means
+WAITING_REVIEW; exit 1 means invalid/failed evidence; exit 0 means all required G3
+attempts passed. Valid review receipts are saved for sealing. Neither local file
+permissions nor the text of a reviewer name authenticates a human by itself.
+
+The GitHub workflow uses two separate jobs. Collection uploads
+`normal-workflow-collected` (deterministic/live/policy) and removes credentials.
+The second job waits at protected environment `normal-workflow-answer-review`.
+The independent reviewer reads that artifact, sets the environment variable
+`NORMAL_WORKFLOW_REVIEW_JSON` to the hash-bound review array, and approves that
+environment. Configure required human reviewers and prevent execution-job tokens
+from editing environment settings. Both environments require the independently
+approved `NORMAL_WORKFLOW_POLICY_HASH`. The finalizer uses `--github-review` to
+fetch the run's actual approval history and require an approved human login in
+the frozen reviewer allowlist. It finalizes, seals and uploads
+`normal-workflow-evidence`; only then can the producer workflow succeed. G4,
+after completion, independently fetches that approval history again and checks
+each answer review's identity. A bot, another environment, an unapproved name or
+execution-model review JSON does not satisfy the boundary. Environment protection
+and variable permissions are prerequisites, not automatically configured here.
+
+The positive workflow regression uses synthetic execution/checkpoint/review
+records and a real tarball to exercise collection → pending → review → finalizer
+→ sealer → G4 fixture verification. The mock-GitHub test separately exercises the
+authentication boundary. Neither is real CLI/model/CI proof.
+
+## Raw bundle and independent G4
+
+An approved supervisor can seal raw records using
+`scripts/seal-normal-workflow-evidence.mjs`. Supply deterministic/live directories,
+the frozen policy/hash, actual CI run/job IDs and an empty output directory. It
+refuses pending/failed G3 summaries rather than inventing missing records.
+Finalize reviews first; do not append review files to an already failed producer
+run and treat it as a successful workflow.
+
+The manifest binds run/producer/job, clean candidate commit/source digest, actual
+artifact and policy hashes, gate/attempt IDs and each relative raw leaf's size and
+hash. Raw records include command provenance, lifecycle counts/inventory, package
+stages, client execution/identity, protocol discovery/Skill responses, loader/hooks,
+initial/final trees, checkpoints, original answers and independent reviews. The
+verifier reopens those leaves and replays the oracle; it does not consume PASS,
+oraclePassed, instructionsVerified or releaseReady from summaries. Missing,
+mutated, duplicate, other-run, traversal and symlink evidence fails.
+
+After the producer run completes, run the verifier from the independently reviewed producer checkout (not PR-controlled code):
+
+```sh
+node scripts/verify-normal-workflow-release.mjs \
+  --artifact /path/to/candidate.tgz --evidence-root /path/to/evidence \
+  --policy /path/to/frozen-policy.json --policy-hash INDEPENDENTLY_APPROVED_HASH \
+  --trusted-run APPROVED_GITHUB_RUN_ID --trusted-artifact-id GITHUB_ARTIFACT_ID
+```
+
+G4 uses authenticated `gh api` to check the approved repository/workflow/ref/SHA,
+workflow_dispatch run, successful job and artifact identity. It downloads the
+artifact and verifies its GitHub-provided SHA256 digest before safe extraction.
+The local manifest must match that independent download and every leaf must
+match the authenticated manifest. Recomputing a local manifest does not recreate
+producer authority. Archive links/devices/traversal/duplicate entries and size
+expansion are rejected. This requires gh, Python 3 and tar; missing tooling is a
+verification failure. Synthetic verifier fixtures can pass evidence validation
+but always return releaseReady=false.
+
+The manual workflow runs only on main and requires the environment's separately
+reviewed NORMAL_WORKFLOW_POLICY_HASH. The frozen producer commit must equal the
+workflow SHA. PR source cannot set that trusted hash through a dispatch input.
+Repository configuration alone does not prove environment protection, approval,
+execution, raw receipts or artifact authenticity. G4 cannot authenticate a job's
+successful completion from inside that still-running job, so verification happens
+afterward. This change does not configure secrets/environment protections, dispatch
+CI, publish, push, merge or certify the running client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiokuko",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Model-agnostic external memory for AI coding agents",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
     "test:integration": "node scripts/run-tests.mjs tests/integration",
     "test:sqlite-vec": "node --import tsx tests/ci/sqlite-vec-package-smoke.ts",
     "test:global-install": "node tests/ci/global-install-smoke.mjs",
+    "test:agenticreplay": "npm run build && node tests/ci/agenticreplay-smoke.mjs",
     "test:evaluation": "npm run build && node scripts/run-retrieval-evaluation.mjs",
     "test:interaction:live": "npm run build && node scripts/run-interaction-memory-smoke.mjs",
     "test:interaction:benchmark": "npm run build && node scripts/run-interaction-memory-benchmark.mjs",
@@ -45,6 +46,9 @@
     "test:evaluation:akinator": "npm run build && node scripts/run-akinator-memory-evaluation.mjs",
     "test:benchmark:akinator": "npm run build && node scripts/run-akinator-memory-benchmark.mjs",
     "test:memory-assurance:live": "npm run build && node scripts/run-memory-assurance-live.mjs",
+    "test:normal-workflow": "node scripts/run-tests.mjs tests/acceptance/normal-workflow",
+    "test:normal-workflow:gates": "node scripts/run-normal-workflow-gates.mjs",
+    "test:normal-workflow:live": "node scripts/run-normal-workflow-acceptance.mjs --require-live",
     "test:memory-index:evaluation": "node --import tsx --test --test-name-pattern=\"fixed bilingual index evaluation\" tests/integration/memory-index.test.ts",
     "test:chatgpt:tunnel": "node scripts/run-tunnel-smoke.mjs"
   },

package/skills/coding-ideal-routine-skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: coding-ideal-routine-skill
+description: バグ修正・機能追加・挙動に関わる設定や配布物の変更で、調査→失敗するテスト→実装→実利用経路の受け入れ検証→事実に基づく報告を行う。部品単体は動くのに通常利用で失敗する抜けを防ぐ。単なる質問・説明・計画には実装手順を強制しない。
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: coding-ideal-routine-skill -->
+
+# Coding Ideal Routine
+
+目的は、変更箇所のテストを通すだけでなく、ユーザーが普段行う操作で要求を満たすこと。既存の作業規約とユーザーの目的・環境・権限を守り、変更リスクに見合う最小限の検証で根拠を積み上げる。
+
+## 1. 作業の種類と完了条件を決める
+
+- 質問・調査・計画だけなら、その回答を完成させる。依頼のない編集やテスト追加、記憶の読み直しを始めない。
+- 修正・機能追加なら、現状の実装、関連テスト、利用手順、実行可能な環境を確認する。コードを書く前に「誰が、どの入口から、何をして、何が観測できれば成功か」を短く定義する。
+- 挙動を変えない文章修正やリファクタリングでは、変更に適した検証を選ぶ。Red が不要な理由を明記し、無意味な失敗を作らない。文章・設定でも利用手順や実行結果が変わるなら挙動変更として扱う。
+- 不明点は既存の仕様と利用実態から解消する。結果や権限を左右する曖昧さだけ確認し、勝手な機能拡張をしない。
+
+## 2. 部品ではなく、つながった利用経路を見る
+
+変更に関連する通常の操作を、入口から観測可能な結果までたどる。該当する場合は、配布・インストール → 読み込まれる指示／設定 → 公開ツールや UI → 実処理 → ユーザーの成果物までを対象にする。
+
+- 各部品の成功を、連結した経路の成功に置き換えない。生産側が実際に出す値を、消費側がそのまま受け取れるか確かめる。
+- 例: インストールされた指示が出す alias と prefix を組み合わせた参照が、実際の読み取りツールで解決できること。alias 単独、prefix 単独のテストだけでは不足する。
+- 配布物や導入処理が関係する変更では、隔離した環境へ正規の方法で導入した成果物を境界テストに使う。ソース直読みや内部関数の直接呼び出しだけで代替しない。
+- 本番相当の入力は、公開された利用契約や実際の成果物から得る。テスト側で canonical 名へ書き換える、欠けた設定を注入する、製品の不具合を補正するなどの救済をしない。
+- AI が操作する製品では、被試験 AI に修正箇所・正解・特別な操作順を教え込まない。通常配布される指示と自然な依頼で試す。評価側だけが正解を保持する。
+
+## 3. 挙動変更は Red → Green
+
+1. 要求・仕様から期待値を先に決め、最小の回帰テストまたは受け入れテストを書く。新機能は未実装時に要求を満たさないことを表す。
+2. 修正前のコードで実行し、意図した挙動の不一致で失敗することを確認する。構文エラー、依存不足、認証失敗は Red の証拠に数えない。
+3. 原因を直す最小限の変更を行い、同じテストが通ることを確認する。テストを削除・弱体化したり、実装の出力を正解にして通したりしない。
+4. 必要な整理を行い、関連する既存テストと経路の受け入れ検証を再実行する。
+
+修正前の状態を実行できないなど、正当な制約で Red を確認できない場合は、その理由と代替証拠を残す。可能なら隔離した旧版で再現する。Red を観測していないのに「再現済み」「TDD 完了」と報告しない。
+
+## 4. 独立した正しさと、必要な範囲を検証する
+
+- 期待値は要求・仕様・手計算・独立した fixture などから得る。被試験コードと同じ変換関数を使って期待値を計算しない。AI の「成功しました」やログの文字列だけを正解判定にしない。
+- 影響する境界値、条件の組み合わせ、失敗後の復旧を選ぶ。個々の成功例だけでなく、今回壊れ得る接続部分を含める。
+- 復旧が関係する変更では「一度失敗 → 許可された修正／再試行 → 正しい最終状態」を確認する。成功した最後の一回だけでなく、不要な副作用・重複・失敗状態の残留も確認する。
+- 高速で決定的な回帰テストを基本にする。関連する公開境界のテストを加え、モックで確認できない実サービス固有の挙動がある場合だけ、目的と終了条件を決めて live 検証する。
+- 毎回の全ホスト・全モデル・全 API の高額な総当たりは行わない。変更が触れる接続とリスクに応じて選び、未検証の範囲を残す。実サービスへの送信、費用、認証、外部変更は既存の許可範囲に従う。
+
+## 5. 障害と権限を混同しない
+
+- ツール引数・構文・依存関係・テスト環境の問題は、原因を特定し、許可された範囲で修復して再実行する。最初の失敗だけで作業を打ち切らない。
+- 明示的なアクセス拒否・承認不足は別扱い。別ツール、別アカウント、別経路で迂回しない。必要な操作・対象・不足する許可を報告し、その操作を止める。
+- 再試行は原因に対する変更と観測可能な進展がある場合に行う。同じ条件で無限に繰り返さない。解消不能な制約や追加判断が必要なら、独立して進められる作業を終え、ブロッカーを明示する。
+
+## 6. 最終版の証拠で完了を判定する
+
+- 最後の変更を含む revision／作業ツリーで検証する。ビルド・配布物が必要なら再生成し、それを使う。検証後に内容を変えた場合は影響する検証をやり直す。
+- 実行した対象、検証数、終了状態、assertion、成果物を確認する。skip、空 suite、no-op、終了コード 0 だけ、古い成果物、自己申告を成功の代わりにしない。無関係な既存 skip がある場合も、必要な受け入れ条件まで通ったことを別に確かめる。
+- 差分に無関係な変更やテスト専用の抜け道がないことを確認する。未検証の経路は「未検証」、環境障害は「検証不能」と区別し、全体成功に混ぜない。
+- ユーザーには、変更内容、確認できた通常利用、実行した検証と結果、残る制約を簡潔に報告する。再現・実装・ローカル検証・公開／本番反映は別々の事実として扱う。許可のない公開やデプロイを完了条件に追加しない。
+
+この Skill は実行時の判断を支援する手順であり、ホストによる毎回の呼び出しや不具合の完全防止を保証する仕組みではない。

package/skills/kiokuko-soul/SKILL.md

@@ -81,6 +81,15 @@ before advertising it. Use `task_inspect` for all bounded preparation reads and
 bundled Skills, including `natural-japanese-output`; do not use shell commands
 to read Skills before preparation and memory decisions permit ordinary tools.
 
+Bundled Skill selectors are package identities, not installed client paths.
+Use the exact public Skill name (including its Codex alias) or
+`skill-name/SKILL.md`; references use `skill-name/references/file.md`.
+The optional `skills/` prefix and slash or backslash separators are supported.
+Empty segments, dot/parent traversal, URL decoding and guessed aliases are not.
+An absolute installed client path is not a bundled selector. After a selector
+error, change to a documented selector or omit path for this router. The error
+does not authorize external reads or remove the current intake/review gate.
+
 For every `task_prepare` call, set `soulRead: true` only after reading this
 complete local `SKILL.md` for the current logical request. `task_prepare` also
 requires the exact local `kiokuko-soul` capability for every task. Omission,
@@ -151,6 +160,25 @@ Enter planning and implementation routes only after the Akinator gate reaches `r
 
 Read and apply `veteran-programmer-skill` before and after implementation when changes span setup, delivery, persisted state, or runtime handoffs. Check that the requested behavior reaches its actual consumer. An isolated edit needs no additional audit.
 
+### Workflow repair
+
+Read and apply `repair-user-workflow` before planning or implementing fixes for
+installation, updates, build, registration, generated configuration, shortcuts,
+plugins, services, or caller-to-runtime handoffs when the next ordinary launch,
+use, restart, or exit fails after upstream success, source/helper checks pass but
+the installed artifact, current profile, or actual consumer fails, or a previous
+fix still needs manual rescue. Judge these conditions from the reported workflow,
+including Japanese reports such as 「更新は成功したが起動しない」; do not depend on
+keyword matches or `catalog_similarity` recommendations. Resolve this route after intake and memory
+review permit progress. Read the complete skill index; load its scenario reference
+only for an ambiguity or skill review.
+
+Do not select this route for explanation-only requests, commit-message drafting,
+or isolated logic fixes without a workflow boundary.
+Use it alongside the coding routine and applicable code/UI skills, and stop if the
+required local skill is unavailable. The repair must reach the ordinary consumer;
+skill selection alone does not establish that the workflow works.
+
 ### Simple code work
 
 Read and apply `kiokuko-simple-work` when either condition is true:
@@ -176,6 +204,17 @@ risks; this route does not require reading them all. Follow availability rules b
 
 Read and apply the `kiokuko-ui-design-soul` index before designing, implementing, modifying, debugging, or reviewing an interactive interface. Select one to three `ui.*` expert fragments for the actual interaction risks. If UI work changes code, apply both the code and UI indexes.
 
+### Coding delivery routine
+
+For coding requests, read and apply `coding-ideal-routine-skill` after intake and
+before changing code, tests, or behavior-affecting configuration or distribution.
+It connects investigation, meaningful Red/Green evidence, the user's ordinary
+usage path, independent verification, and factual completion reporting.
+Apply its relevant checks to behavior-preserving refactoring or writing;
+explanation-only requests do not require implementation or Red/Green tests.
+This route complements the code and completion contracts and never replaces
+intake, memory review, permissions, or required verification.
+
 ### Combined work
 
 Routes compose. Read every applicable specialist index; never choose only one when the task spans multiple contracts. Fragment selection remains narrow inside those routes.
@@ -185,10 +224,12 @@ Use this order:
 1. `kiokuko-soul`;
 2. one Akinator `task_prepare`, followed by grounded `task_answer` calls until `ready` or `exhausted`;
 3. `veteran-programmer-skill` when the change crosses workflow stages;
-4. `kiokuko-simple-work` when the finalized intake satisfies the simple-code activation boundary;
-5. `kiokuko-single-purpose-functions` for code planning or code work;
-6. `one-shot-software-completion` for every coding request, including simple code and UI code changes;
-7. `kiokuko-ui-design-soul` for interactive UI work.
+4. `repair-user-workflow` for the workflow defect repairs defined above;
+5. `kiokuko-simple-work` when the finalized intake satisfies the simple-code activation boundary;
+6. `kiokuko-single-purpose-functions` for code planning or code work;
+7. `one-shot-software-completion` for every coding request, including simple code and UI code changes;
+8. `coding-ideal-routine-skill` for coding requests;
+9. `kiokuko-ui-design-soul` for interactive UI work.
 
 Keep each route within the user-approved task scope.
 

package/skills/one-shot-software-completion/SKILL.md

@@ -29,6 +29,14 @@ listing is insufficient. Reuse the existing plan and evidence, not extra checkli
 3. Make the smallest complete change. Handle relevant boundaries, errors,
    security and resource ownership. Define expected results before implementation;
    add regression coverage for material behavior, reuse adequate existing checks.
+   For a bug fix or new behavior, add a focused failing test before changing the
+   implementation and run it on the original code. The failure must expose the
+   requested behavior, not a syntax error or missing dependency. Then make the
+   implementation pass it and the existing tests. Preserve Red and Green results
+   and the source state each tested. Never weaken or skip a test to obtain Green.
+   Explanation-only requests need no edits or implementation tests; apply only
+   verification relevant to the actual request. If execution is unavailable,
+   report the missing evidence rather than declaring verified completion.
 4. Run required checks and focused verification through the changed entry point.
    Broaden for shared contracts; rerun checks invalidated by edits. A helper test
    alone does not prove delivery. Never weaken checks to hide failure.

package/skills/repair-user-workflow/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: repair-user-workflow
+description: "Fix defects across installation, updates, generated configuration, shortcuts, plugins, services, or caller-to-runtime handoffs. Use when an operation succeeds but the user's next ordinary action fails, or a previous fix worked only with manual rescue steps. Verify the existing-user path and actual consumer. Do not activate for explanation-only requests or isolated logic edits without a workflow boundary."
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: repair-user-workflow -->
+
+# Repair the user workflow
+
+Complete the user's ordinary action through its actual consumer. A successful
+installer, build, renamed file, internal function, or visible startup screen proves
+only that stage. Keep the user's product, terminology, supported deployment mode,
+and current authorization intact. This Skill specializes workflow integration;
+reuse the project's existing coding and verification routine.
+
+## Establish the path before choosing the fix
+
+Treat the reported runtime failure as evidence. Inspect the selected executable,
+installed artifact/version, generated or persisted state, and runtime resolver.
+Keep source, built output, installed copies, running processes, staged changes,
+and committed/CI revisions distinct. Read the index when the request concerns
+staged files or commit messages; an unstaged deletion does not remove a staged file.
+
+Trace only the affected path:
+
+`ordinary user action → producer → saved/generated state → resolver → consumer → observable result`
+
+Name the owner of each handoff and the first violated contract. Determine which
+configuration, profile, interpreter, environment, working directory, and restart
+boundary the consumer actually uses. “Installed successfully” must not be
+reinterpreted as “needs another installation.” A caller can lose the location of
+an already installed runtime.
+
+Define success from the user's requested workflow before editing. Resolve routine
+choices from current evidence; ask only when missing information changes the
+result or authorization. Apply a correction immediately to the active work.
+
+## Repair the owner of the broken handoff
+
+- If the supported install/update operation owns a generated shortcut, service
+  definition, cache, or registration, make that operation refresh existing managed
+  state after an accepted successful update. A separate repair/register command
+  is not completion when the ordinary operation is expected to do this itself.
+- Cover both first creation and an existing installation. Include the state that
+  survives the previous version, even when the filename is already current. Make
+  repeat updates idempotent and preserve explicit user overrides, original state
+  defaults, custom commands, and unowned files.
+- Resolve runtime identity and location at the boundary that knows them. Store
+  required stable, non-secret defaults in the artifact its consumer actually
+  reads. Editing a shell startup file does not update an already running shell;
+  the checkout directory is not necessarily the caller's project directory.
+  Validate the runtime identity/entry and quote paths for the target interpreter.
+- Preserve the chosen deployment model. A plugin in its host, a local runtime,
+  and a global standalone executable are different contracts. Do not add a global
+  installation, environment variable injection, manual file edit, or manual
+  registration merely to compensate for a broken handoff.
+- Follow an explicit retirement/rename decision through generated references,
+  package metadata, update/restart logic, and staged content. Migrate references
+  to the supported entry instead of recreating a forbidden old file. Preserve
+  external identifiers and intentional historical fixtures under their own contracts.
+
+For a genuinely required user action such as authentication or a documented
+restart, verify that contract and state it. Do not invent an automatic guarantee
+or silently convert a workaround into a prerequisite.
+
+## Verify without rescuing the product
+
+Use the normal producer and the pre-existing consumer, with representative saved
+state. Reuse existing verifiers or a temporary isolated acceptance probe. Add a
+permanent test only within the user's scope; a ban on test additions still permits
+authorized verification. Use an existing artifact or an authorized temporary build
+when sufficient. Create a new package artifact only when necessary and authorized,
+and distinguish a verification fixture from a requested release deliverable.
+Do not publish, reinstall a live profile, stage, commit, or expand the task merely
+to obtain convenient evidence; those effects remain within the user's chosen scope.
+
+The acceptance sequence must exercise the broken handoff, not call an internal
+helper in its place. For example: normal update → existing shortcut → operation
+from the caller's project. Remove test-only PATH entries, injected runtime roots,
+hand-edited references, or manual registration that the user would not have.
+Retain legitimate prerequisites and overrides from the actual supported contract.
+
+Observe the intended behavior, not just status 0 or a success message. Select
+relevant failure cases: old saved state, current filename with missing runtime
+metadata, repeated updates, rejected updates, explicit overrides, or foreign files.
+Exercise a reported startup problem through real startup, not only help/version.
+
+When lifecycle behavior is affected, continue through the user's exit/cancel
+action. Check the exit result, a bounded deadline, and owned resources/descendants.
+Keep the termination fallback able to run while asynchronous cleanup is pending;
+if forced termination is necessary, verify process ownership and identity and
+preserve unrelated processes. Explaining an exit code or rendering a screen does
+not satisfy a request for working termination.
+
+## Check the final contract and report its limits
+
+Run the affected existing checks under their actual CI/runtime conditions,
+including production mode or the relevant shard when that changes behavior.
+Keep legitimate changes to diagnostics, schemas, names, and expected tests/docs
+consistent; do not weaken assertions to hide a failure. Recheck affected evidence
+after a material change, without repeating unrelated suites.
+
+Distinguish product failures, environment restrictions, malformed paths/tool
+arguments, and authorization denials. Correct a demonstrably malformed operation
+within the authorized scope; do not replay an unchanged failure, bypass a denial,
+or ask again for permission already granted. Report any remaining blocked action
+with its specific cause. A memory checkpoint or an approval bookkeeping result
+is not product execution evidence.
+
+Finish with the changed owner, the ordinary workflow actually exercised, its
+observable outcome, and any unverified deployment/CI/live state. Separate a source
+proposal, a temporary overlay, an applied patch, an installed artifact, and a
+published release. Say a Skill/memory was saved only after a successful write;
+availability and automatic-selection eligibility do not prove future application.
+
+For ambiguous triggering or review of this Skill, read
+[scenario checks](references/scenarios.md). Evaluate decisions and outcomes,
+not whether an answer repeats these headings.