kiokuko 1.0.5 → 1.0.7

package/docs/interaction-memory-validation.md

@@ -0,0 +1,108 @@
+# Interaction memory validation
+
+Validated locally on 2026-09-19, macOS arm64, Node.js 26.5.0. These are source and
+isolated-install results, not a published release or an update to a running client.
+
+## Automated checks
+
+- TypeScript type checking, build, and the 1,685-test unit/integration suite pass.
+- Retrieval evaluation: 110 queries, Recall@1 0.93, Recall@5 0.99, semantic-only
+  Recall@5 0.95, zero scope leaks, zero false-negative deliveries. These use the
+  existing deterministic evaluation corpus, not a claim about model behavior.
+- Package dry-run includes migration 003, the two tools, updated Skills, templates,
+  and documentation. Isolated global installation verifies bundled Skill setup
+  across Codex, Claude Code, OpenCode, and Hermes.
+- The schema-3 sample database passes baseline and Web API checks. A separate v2
+  upgrade test verifies that old entries and revision bytes are not reclassified.
+- New tests cover standalone global operation without project state, subject
+  isolation, general preference injection, capability withholding, exact replay,
+  restarted connections, concurrent processes, operation conflicts, corrections
+  of verified memories, stale/ambiguous/protected targets, transactional failure,
+  secret rejection, purge retries, candidate edits, import, and index rebuilding.
+- Both vector backends apply explicit subject filters before their candidate
+  limit. The regression places the matching entry behind 130 unrelated vectors.
+- Project preference ranking uses `context-ranking-v7`, preventing replay of a
+  context selected under the previous ranking policy. Historical deliveries remain
+  readable; existing revision hashes are unchanged.
+
+The first sandboxed suite could not bind local HTTP ports. The passing suite ran
+with localhost access. Package installation used a temporary prefix and npm cache;
+no user client configuration was rewritten.
+
+## Live model behavior
+
+| Client | Result | Evidence / limit |
+|---|---|---|
+| Codex CLI 0.153.4 | Passed | Two fresh ephemeral conversations, real stdio MCP and a disposable SQLite database. The model chose capture, then recalled and used the preference. |
+| Claude Code 2.1.220 | Blocked before inference | The isolated `--bare` probe reported `authentication_failed` / “Not logged in”. Bare mode intentionally does not use OAuth/keychain credentials. This does not establish the login state of the normal installed profile. |
+| OpenCode 1.18.31 | Blocked before inference | The isolated config/data probe reported `ProviderAuthError`: its selected Google provider had no API key. Normal-profile authentication was not copied or inspected. |
+| Hermes Agent | Not run | No `hermes` executable on the test process PATH. No conclusion about installations elsewhere. |
+
+Codex's first natural message was:
+
+> For Japanese grammar explanations, I prefer two examples about trains before grammatical terminology.
+
+Its `memory_capture` call created a global candidate with subject
+`japanese-grammar`. The second conversation received only this new message:
+
+> Explain the difference between は and が in Japanese grammar.
+
+The model used query-only `memory_recall`. Its answer gave these two train examples
+before explaining topic and subject terminology:
+
+> 電車は来ました。 — “The train has arrived.”
+>
+> 電車が来ました。 — “A train has arrived” or “The train is here.”
+
+Both conversations read only their local copies of the bundled Skills. The second
+had no first-conversation transcript or preference in its prompt. Database checks
+confirmed zero repository locations, task runs, and intake sessions. This is live
+proof of capture and later influence in Codex under the tested setup; it does not
+prove every-turn interception or reliability in the other clients.
+
+Two earlier probes exposed real integration boundaries. First, noninteractive
+Codex denied the write tool under its approval policy. The test now preapproves
+only its disposable server's `memory_capture` operation. Second, model-generated
+labels differed (“Japanese grammar explanations” vs “Japanese grammar”), causing
+an exact-filter miss. Bundled guidance now favors short topic labels and query-only
+recall unless exact stored labels are known. The successful probe used that guidance.
+Host/client tool approval still applies; Kiokuko does not bypass it.
+
+Reproduce the Codex probe with an already-authenticated CLI:
+
+```bash
+npm run test:interaction:live
+```
+
+The script prints its temporary evidence directory, preserves protocol events and
+answers there, and fails unless capture, later recall, and the train preference in
+the second answer are observed. It uses process-only configuration, disables
+native memory injection, ignores user config, and never resumes an old conversation.
+It does not install or log into clients. For the other clients, use the same two
+natural messages in separate fresh sessions with a disposable Kiokuko database,
+then verify both tool calls and the second answer before marking them passed.
+
+Codex configuration follows the official [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
+and [noninteractive mode guide](https://learn.chatgpt.com/docs/non-interactive-mode).
+OpenCode isolation used its documented [CLI environment settings](https://opencode.ai/docs/cli/).
+
+## Measured scale
+
+The interaction benchmark seeds 10,000 synthetic global captured facts in
+**in-memory SQLite**, with embeddings disabled. It uses 10 recall/duplicate-capture
+samples and 3 snapshot samples; values below are local measurements, not an SLA.
+
+| Operation | Median | p95 |
+|---|---:|---:|
+| Query plus explicit subject recall | 27.47 ms | 35.32 ms |
+| Exact duplicate capture | 0.38 ms | 2.56 ms |
+| Existing project-context snapshot hash over 10,000 relevant entries | 1,447.14 ms | 1,469.49 ms |
+
+Seeding took 8.29 seconds. The same snapshot path rejects 10,001 entries with its
+existing integrity error. The snapshot measurement is one component of project
+preparation, not the duration of a full `task_prepare`. Disk latency, providers,
+large receipt histories, and long-running task ledgers were not benchmarked here.
+
+```bash
+npm run test:interaction:benchmark
+```

package/docs/interaction-memory.md

@@ -0,0 +1,121 @@
+# Memory from normal interaction
+
+Kiokuko can save durable preferences, facts, decisions, and corrections from normal
+conversation. The current client's model extracts concise memories and calls
+`memory_capture`; no separate model service or credentials are needed. Each memory
+is a revisioned SQLite entry. Automatic saves are **candidate / untrusted**, and
+can immediately be recalled as advisory context. A stated evidence basis is not
+proof of truth. Curator's reviewed global promotion remains a separate operation.
+
+After updating Kiokuko, run `kiokuko setup` for your selected clients and restart
+them so the new tools and bundled instructions load. Existing project work still
+uses `task_prepare` / `task_answer`. General conversation uses `memory_recall`
+without a repository, task run, or artificial intake answers.
+
+## What is saved
+
+The model is instructed to capture explicit durable preferences and corrections,
+settled decisions, verified results, and reusable troubleshooting lessons—even
+without “remember this.” It skips routine progress, temporary requests, repetition,
+unsupported assistant conclusions, sensitive personal profiling, and transcripts.
+Secret detection rejects a whole batch before it writes anything.
+
+Clearly general knowledge can be saved globally with a portability reason.
+Project-specific knowledge requires the active project run after intake permits
+progress. Uncertain scope stays local or is skipped outside a project. General
+communication preferences must be explicitly general; subject preferences retain
+their subjects. Memories never authorize actions or override current instructions.
+
+## MCP contract
+
+`memory_capture` is non-terminal. Its input includes `operationId`, optional
+`cwd` / `runId`, and one to five `memories`. Each item reuses the checkpoint fields
+(kind, title, body, scope, applicability, tags, and portability reason), with:
+
+- `body`: nonempty, at most 2,000 characters; optional summary at most 500.
+- `subjects`: one to five labels, normalized to lowercase `subject:` tags.
+- `basis`: `user_statement`, `user_correction`, or `observed_result`.
+- `generalCommunication: true`: only for an unqualified global preference;
+  omit subjects and applicability in this case.
+- `replaces: { entryId, expectedRevision }`: only with `user_correction`.
+
+For example, a model can extract this from “When explaining Japanese grammar,
+I prefer examples before terminology”:
+
+```json
+{
+  "operationId": "conversation-1-preference-1",
+  "memories": [{
+    "kind": "preference",
+    "title": "Japanese grammar explanations",
+    "body": "For Japanese grammar explanations, give examples before terminology.",
+    "scope": "global",
+    "portableReason": "Applies to Japanese grammar explanations across projects.",
+    "subjects": ["Japanese grammar"],
+    "basis": "user_statement"
+  }]
+}
+```
+
+Responses contain entry IDs, revisions, workspace, created/duplicate/corrected
+outcomes, and current/changed/superseded/unavailable availability. Reuse an
+operation ID only for an exact retry; a different payload conflicts. Exact
+normalized content across separate operations deduplicates independently of
+timestamps, client provenance, and run IDs. Similar paraphrases are not merged.
+
+Corrections require an exact current revision in the same scope. Creating the
+replacement and superseding the old entry is atomic, including for a previously
+verified entry. History remains accessible through existing review controls.
+Stale revisions, duplicate correction targets, and managed entries are rejected.
+Operation receipts contain no memory text. Retrying a purged operation acknowledges
+its unavailable entry without recreating it. A new operation ID is a new request,
+not a deletion tombstone bypass prevention mechanism.
+
+`memory_recall` takes `soulRead: true`, the complete current capability catalog,
+`query`, optional `subjects`, `limit` (default 8, maximum 20), and
+`maxContextChars` (default 4,000, range 100–12,000). Read the exact local
+`kiokuko-soul` and `memory-reasoning` Skills before advertising them. Missing SOUL
+blocks recall; missing or unknown memory-reasoning withholds ordinary memories.
+Current managed Curator projections retain the existing trusted-memory exception.
+
+Recall searches only global memory, using lexical and optional semantic retrieval.
+Explicit subjects restrict matching before result selection. Without explicit
+subjects, at most two general communication preferences may appear without query
+word overlap. Subject preferences require the subject in the query or an explicit
+subject filter. Prefer query-only recall. Pass explicit filters only for exact known stored labels,
+not guessed synonyms. Use short topic labels at capture time. Project preparation
+uses the same preference selection within its existing budget and capability gate.
+Returned records include IDs, revisions, subjects, status/trust labels, and concise
+content. The character budget includes the serialized memory items, not protocol
+or capability metadata.
+
+Save important corrections promptly; batch other captures before the final answer.
+Do not resubmit captured memories in `memory_checkpoint`, which remains terminal.
+
+## Disable capture
+
+Set the environment variable on the Kiokuko MCP server process, then restart it:
+
+```bash
+KIOKUKO_INTERACTION_MEMORY=off kiokuko mcp
+```
+
+In a client's MCP configuration, put `KIOKUKO_INTERACTION_MEMORY = "off"` in its
+server environment rather than starting a second server manually. Recall and
+existing explicit checkpoints remain available. No new management UI is needed:
+use the existing Web/CLI review, history, and deletion controls.
+
+## Storage and limits
+
+Migration `003_interaction_memory.sql` adds an indexed fingerprint projection.
+Revision hashes keep their original provenance-sensitive definition. Candidate
+edits, imports, superseding, purge, and search-index rebuilding maintain the
+projection. Existing memories are not automatically reclassified. Receipts are
+local operational metadata; workspace exports include memories, not retry history.
+
+One database represents one user. Capture is model-mediated and cannot intercept
+every turn. SQLite capacity is not a promise of unlimited project retrieval: the
+existing 10,000-entry project snapshot integrity limit remains in force.
+
+See [interaction memory validation](interaction-memory-validation.md) for automated
+checks, performance measurements, and separate live-client results.

package/migrations/003_interaction_memory.sql

@@ -0,0 +1,17 @@
+-- A rebuildable projection, not a replacement for immutable revision hashes.
+CREATE TABLE interaction_memory_fingerprints (
+    entry_id TEXT PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE,
+    workspace TEXT NOT NULL,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    fingerprint TEXT NOT NULL CHECK (length(fingerprint) = 64),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE
+);
+CREATE INDEX idx_interaction_memory_fingerprint
+    ON interaction_memory_fingerprints(workspace, fingerprint, entry_id);
+
+CREATE TRIGGER interaction_memory_invalidate
+AFTER UPDATE OF current_revision, status ON entries
+WHEN NEW.current_revision <> OLD.current_revision OR NEW.status = 'superseded'
+BEGIN
+    DELETE FROM interaction_memory_fingerprints WHERE entry_id = NEW.id;
+END;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiokuko",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Model-agnostic external memory for AI coding agents",
   "type": "module",
   "bin": {
@@ -35,6 +35,8 @@
     "test:sqlite-vec": "node --import tsx tests/ci/sqlite-vec-package-smoke.ts",
     "test:global-install": "node tests/ci/global-install-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",
     "test:benchmark": "npm run build && node scripts/run-retrieval-benchmark.mjs",
     "sampledb:generate": "node --import tsx tests/fixtures/sample-database.ts tests/sampledb/kiokuko.sqlite3",
     "test:sampledb": "npm run build && node --import tsx tests/ci/verify-sample-database.ts",
@@ -58,7 +60,9 @@
   "allowScripts": {
     "onnxruntime-node": true,
     "sharp": true,
-    "protobufjs": true
+    "protobufjs": true,
+    "esbuild@0.28.2": true,
+    "fsevents@2.3.3": true
   },
   "peerDependencies": {
     "@huggingface/hub": "2.16.1",

package/skills/kiokuko-soul/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kiokuko-soul
-description: Use before every non-trivial Kiokuko-governed task as the mandatory first-read SOUL router. Run the Akinator intake gate before planning or implementation, then route simple code work, general code work, and interactive UI work to the bundled specialist Skills.
+description: Use before every coding request, including small fixes, and every other non-trivial Kiokuko-governed task as the mandatory first-read SOUL router. Run the Akinator intake gate before planning or implementation, then route simple code work, general code work, and interactive UI work to the bundled specialist Skills.
 ---
 
 <!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-soul -->
@@ -9,7 +9,7 @@ description: Use before every non-trivial Kiokuko-governed task as the mandatory
 
 ## Outcome
 
-Start every non-trivial Kiokuko-governed task by reading one stable router, resolving the Akinator intake gate, then reading the applicable compact specialist indexes and only the expert fragments required by the current task.
+Start every coding request (including small fixes) and every other non-trivial Kiokuko-governed task by reading one stable router, resolving the Akinator intake gate, then reading the applicable compact specialist indexes and only the expert fragments required by the current task.
 
 This Skill owns the entry sequence and routes work. Akinator is the mandatory intake state machine, not a specialist route. This Skill does not duplicate specialist instructions, select another model, or authorize effects beyond the user request and current client permissions.
 
@@ -17,6 +17,40 @@ This Skill owns the entry sequence and routes work. Akinator is the mandatory in
 
 Explicit user instructions outrank these Skills' design, style, workflow, and implementation preferences. They do not override host-enforced safety, authorization, identity, state, revision, or integrity invariants. Resolve routine choices from repository evidence and existing authorization; ask only when an unresolved assumption would materially change the intended result or permitted effects.
 
+## Ordinary conversation and interaction memory
+
+For ordinary conversation that does not involve project work, use `memory_recall`
+with the current query, optional subjects, `soulRead: true`, and the complete
+capability catalog. Read `memory-reasoning` before advertising it. No repository,
+task run, or Akinator answers are needed. This route cannot replace or bypass
+intake for project work or an already-open project run.
+
+Proactively use non-terminal `memory_capture` for durable user statements and
+preferences, explicit corrections, settled decisions, and verified reusable
+results, even without “remember this.” Extract at most five concise memories per
+call with subjects and an honest basis. Use short topic labels such as “Japanese
+grammar”, not task phrases such as “Japanese grammar explanations”. Prefer
+query-only recall; pass subject filters only for exact known stored labels.
+Save important corrections promptly and
+batch other memories before the final answer. Save nothing when nothing is useful.
+Skip routine progress, temporary requests, repetition, unsupported assistant
+conclusions, sensitive personal profiling, secrets, and transcripts.
+
+Project saves require the active run with completed intake. Clearly general
+knowledge may use global scope with a portability reason. `generalCommunication`
+is only for explicitly general communication preferences, without subjects or
+applicability. Subject-specific preferences must retain their subjects. Correct
+only a known entry ID and expected revision; never guess a replacement target.
+All captures remain untrusted candidates, immediately eligible for advisory
+recall. Curator still requires approval for verified global promotion.
+
+`memory_capture` does not close the task. `memory_checkpoint` remains terminal;
+do not repeat captured memories there. Exact transport retries reuse the capture
+operation ID; changed payloads use a new operation. A purged receipt is not an
+instruction to recreate content. `KIOKUKO_INTERACTION_MEMORY=off` disables capture
+without disabling recall or explicit checkpoints. Tool use is model-mediated,
+not a guarantee of interception on every turn.
+
 ## Required entry
 
 Read this Skill before any other bundled Kiokuko Skill.
@@ -72,6 +106,14 @@ This route minimizes the solution; it does not replace the code contract below o
 
 Read and apply the `kiokuko-single-purpose-functions` index before writing, modifying, debugging, refactoring, or reviewing code, and before decomposing a code-changing plan. Select one to three `code.*` expert fragments for each cohesive function or task.
 
+### Software completion for every coding request
+
+Before code-changing planning or implementation, apply the compact
+`one-shot-software-completion/SKILL.md` core, including for small, minimal/YAGNI,
+test and UI changes. Reuse its unchanged full text already in active context;
+otherwise read it. A summary is insufficient. Load references only for concrete
+risks; this route does not require reading them all. Follow availability rules below.
+
 ### Interactive UI work
 
 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.
@@ -87,7 +129,8 @@ Use this order:
 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. `kiokuko-ui-design-soul` for interactive UI 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.
 
 Keep each route within the user-approved task scope.
 

package/skills/memory-reasoning/SKILL.md

@@ -35,6 +35,18 @@ When Kiokuko delivers ordinary memory for a build or debug task:
    evidence is enough.
 7. Prefer current verified evidence when it conflicts with recalled material.
 
+## General conversation
+
+Read this Skill before advertising it to `memory_recall`. Use retrieved
+preferences only for the matching subject. Prefer query-only recall and do not
+guess exact subject filters. The exception is explicitly general
+communication preferences. Respect the entry's status, trust level, subjects,
+and revision. Current user instructions override remembered preferences; a
+memory never grants permission. A stated evidence basis is a model claim, not
+independent verification. Check changing factual claims against current sources.
+For explicit user corrections, pass the recalled entry ID and expected revision
+to `memory_capture`; do not overwrite an ambiguous target.
+
 ## Trust and safety boundaries
 
 - Treat ordinary memory, external references, and past conclusions as advisory

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

@@ -0,0 +1,54 @@
+---
+name: one-shot-software-completion
+description: Required before planning or implementing any code change, including small fixes, tests and UI. Read this compact core; load references only for concrete risks.
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: one-shot-software-completion -->
+
+<!-- kiokuko:runtime contract -->
+# One-Shot Software Completion
+
+Deliver the user's observable result, not an isolated patch. One-shot is a
+delivery goal, not a promise of success in one turn or extra authorization.
+
+## Activation and context
+
+For every coding request, including minimal/YAGNI work, apply this entire core
+before code-changing planning or implementation. Follow `kiokuko-soul` and host
+intake, scope and permissions; this Skill grants no extra agents or continuation.
+Reuse the unchanged full core already in active context, including host-supplied
+text. Read it when absent, changed or lost to compaction; a summary or capability
+listing is insufficient. Reuse the existing plan and evidence, not extra checklists.
+
+## Completion contract
+
+1. Define the observable result. Resolve routine choices from current repository
+   evidence; ask only about consequential uncertainty in intent or authorization.
+2. Trace the real entry point, callers and effects. Include required wiring,
+   delivery steps and checks; preserve unrelated work and compatibility.
+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.
+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.
+5. Review the complete diff, including new files. Report behavior, checks/results,
+   assumptions and unverified paths. Distinguish source from deployed/runtime
+   evidence. Continue authorized work; stop only on completion or a concrete blocker.
+
+## Read only for the current risk
+
+A bounded change with clear callers and checks needs only this core. Otherwise
+read the matching reference, one at a time; never preload the set or reread merely
+because the phase changed. Select repository excerpts by relevant symbols/ranges.
+
+| Read when | Reference |
+| --- | --- |
+| Scope, callers or integration are unclear | [Discovery](references/discovery-and-scope.md) |
+| Inputs, effects, lifetime or compatibility change | [Boundaries](references/boundaries-and-lifecycle.md) |
+| Evidence or delivery is uncertain | [Verification](references/verification-and-completion.md) |
+| A check fails or progress stalls; before changing strategy | [Recovery](references/failure-recovery.md) |
+
+Never retry an unchanged failed operation. Reference deferral does not waive the
+core obligations. Follow the router's other applicable contracts without duplicating them.
+<!-- /kiokuko:runtime -->

package/skills/one-shot-software-completion/references/boundaries-and-lifecycle.md

@@ -0,0 +1,56 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: one-shot-software-completion -->
+
+# Boundaries and lifecycle
+
+Use when changing input acceptance, effects, state or a public/stored contract.
+Apply the code Skill's selected experts; this reference helps find omissions
+across the workflow rather than replacing those contracts.
+
+## Derive cases from the actual contract
+
+Select relevant boundaries; do not build an exhaustive speculative matrix.
+Each selected case needs deliberate accept/reject behavior or a demonstrated
+upstream invariant. A type assertion alone does not validate external input.
+
+| Input or boundary | Candidate cases |
+| --- | --- |
+| Text | absent, empty/whitespace, Unicode, length limit, injection-shaped content |
+| Numbers | zero, negative, bounds, fractional/non-finite values, encoded strings |
+| Collections | empty, singleton, duplicates, order, size limits |
+| Optional fields | missing, null, undefined, present but empty |
+| Identity | nonexistent, deleted, stale, another user/tenant's resource |
+| Time | zone/offset, DST, epoch zero, skew, expiry boundary |
+| Concurrent work | duplicate/out-of-order request, cancellation, partial batch |
+
+Example: pagination needs a defined limit range and integer policy, stable
+ordering, cursor behavior and tenant isolation. Whether an unknown cursor is an
+error or an empty page comes from the API contract, not this checklist.
+
+## Decide effects and failure semantics
+
+For each changed network, filesystem, database or process boundary, identify
+ownership, timeout/cancellation, public error and partial-success behavior.
+Reuse the repository policy; avoid silent catches or a success result after a
+required effect failed. Retries require an idempotent operation or a verified
+deduplication contract, bounded attempts and preserved request identity.
+
+A timeout after a write may mean the effect succeeded but its acknowledgment
+was lost. Do not resend a charge, notification or mutation merely because the
+response is absent. Reconcile uncertain state through the supported mechanism.
+
+For each resource or state holder, trace creation, access, invalidation, cleanup,
+restart/reload and test teardown. Account for subscriptions, timers, locks,
+caches and background jobs. Preserve transaction and rollback boundaries;
+cancellation of a UI is not proof that the underlying operation stopped.
+
+## Preserve consumers
+
+Identify contracts that leave this patch: JSON, database rows, queue messages,
+exports, CLI flags, config and environment variables. Preserve existing behavior
+by default. When a breaking change is requested, include its migration/version
+and downstream update strategy within authorized scope.
+
+Adding an optional field with a safe default may preserve compatibility;
+renaming, deleting, changing type or redefining defaults may not. Test old data
+and callers where they remain supported. Check readers as well as writers and
+rollout/restart ordering when old and new versions can coexist.

package/skills/one-shot-software-completion/references/discovery-and-scope.md

@@ -0,0 +1,67 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: one-shot-software-completion -->
+
+# Discovery and scope
+
+Use when the behavioral requirement, caller graph or patch boundary is unclear.
+Keep decisions in the existing plan; a separate document is not required.
+
+## Reconstruct the requirement
+
+- Express the requested result as observable input, action and output. "Add
+  pagination" needs an entry point, response shape, ordering, defaults and
+  compatibility with existing callers, not just a pagination helper.
+- Resolve unspecified choices from a working analog, project instructions and
+  conventions, then the framework idiom already used locally. Prefer the least
+  disruptive reversible choice and record material assumptions. Explicit user
+  requirements outrank inferred conventions.
+- Repository evidence cannot answer every ambiguity. Ask when competing
+  interpretations materially change the requested result, data, public contract
+  or permissions. Complete independent work while a necessary answer is pending.
+  Do not treat naming or formatting choices with established defaults as blockers.
+
+## Trace before editing
+
+Follow entry point -> target -> callees/effects -> callers/consumers. Search
+changed symbols and serialized field names; the compiler cannot find untyped
+fixtures, external consumers or dynamic registrations. Inspect tests and the
+actual check commands. Check imports, module state, exports and nearby helpers
+in contiguous reads; read the whole file when its contract depends on them.
+Avoid recursively reading every transitive dependency without a concrete risk.
+
+Use the closest maintained analog for placement, registration, errors, config,
+tests and docs. Recency alone does not make an example correct. Preserve existing
+dependency direction and use local validation, HTTP, IDs, retry and test helpers
+before adding another implementation or dependency.
+
+## Find the required accompanying changes
+
+From the actual workflow, identify relevant types, validation, serialization,
+permissions, flags, UI strings, CLI help/API docs, fixtures, exports, registration,
+migrations and generated artifacts. Logging and changelog entries are required
+only when the task or repository requires them. For setup and delivery, follow
+the artifact to its consumer and reload trigger with `veteran-programmer-skill`.
+
+Example: a new notification provider may require its client/schema, registry
+entry and configuration validation. A provider class tested only in isolation
+does not prove users can select it.
+
+## Bound and plan the patch
+
+- Include every step required to make the behavior reachable and correct. A
+  smaller diff is a tiebreaker between complete solutions.
+- Follow changed contracts through types, stored/wire data, callers, fixtures
+  and docs. Keep compatibility where consumers cannot change in this patch;
+  intentional compatibility aliases are not stale references to remove.
+- Fix an adjacent defect when the new behavior depends on it, or isolate the
+  new path so it does not spread the defect. Record the choice. Stable pagination,
+  for example, may need an ID tiebreaker in an existing shared sort.
+- Leave unrelated cleanup alone. A same-file edit or cheap refactor is not by
+  itself justification to expand scope. Preserve staged and unstaged user work.
+- Record path -> responsibility -> concrete check. Include expected outputs for
+  the main path and material failure cases. Order related edits so checks remain
+  interpretable, commonly contracts -> implementation -> wiring -> tests/docs.
+  Reassess scope if the plan grows; file count alone cannot decide correctness.
+
+Establish focused baseline results when existing failures could obscure the
+change. Inspect shared callers before choosing wider checks; preserve exact
+commands and results so new failures can be attributed rather than guessed.

package/skills/one-shot-software-completion/references/failure-recovery.md

@@ -0,0 +1,43 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: one-shot-software-completion -->
+
+# Failure recovery
+
+Read when a check fails or progress stalls. Recovery stays within the original
+scope, current host role and permissions; it is not an automatic retry policy.
+
+## Classify before editing
+
+Read the relevant complete error and causal context. Separate observations from
+hypotheses; multiple causes may coexist.
+
+| Evidence indicates | Next action |
+| --- | --- |
+| Wrong interpretation of the requirement | Revisit the observable result and material ambiguity |
+| Missed caller, helper contract or integration | Trace that dependency and correct the plan |
+| Local implementation error | Apply a focused fix and its regression check |
+| Environment/tooling failure | Verify the cause; make only an authorized, bounded repair |
+| Failure demonstrated in the baseline | Report it; investigate if it blocks or interacts with the change |
+
+If the same failure remains after two targeted fixes, stop making variants of
+the same patch. Create a minimal reproduction or focused diagnostic, revisit
+the input/contract and consider a different approach supported by repository
+evidence. Do not rerun an unchanged failed operation without new information.
+
+## Preserve the evidence
+
+Do not loosen assertions, skip tests, add broad catches/casts, suppress errors
+or increase timeouts merely to make a failure disappear. Change a check only
+when evidence shows its expectation is wrong and explain that correction.
+
+Fix tooling only when it blocks required verification and the repair is within
+scope. Prefer a targeted runnable check when broader infrastructure is missing;
+report exactly what it proves and what remains unverified. Do not rewrite CI,
+install unrelated dependencies or change external configuration to evade a
+blocker. A permission or credential gap is not a prompt to bypass controls.
+
+After a repair, rerun the failed check and all checks affected by the new diff,
+then review the final patch again. A signature repair can require caller tests,
+typecheck and runtime integration even if only one test originally failed.
+Stop when requirements are verified or progress requires unavailable evidence,
+access or a consequential user decision. State the blocker and concrete next
+action rather than claiming completion or promising unattended continuation.