@askdkc/kiokuko 0.1.32 → 0.2.0

package/skills/kiokuko-single-purpose-functions/SKILL.md

@@ -1,288 +1,74 @@
 ---
 name: kiokuko-single-purpose-functions
-description: Use whenever writing, modifying, reviewing, debugging, or refactoring code in any language or repository. Enforce one cohesive contract per function, validation at hostile boundaries, caller-owned input immutability, narrow types, deterministic domain logic, explicit safe failures, separation of persistence and external effects, and focused runnable tests. Do not create meaningless micro-functions or rewrite unrelated code.
+description: Use whenever writing, modifying, reviewing, debugging, or refactoring code. Apply a compact universal function contract, then route each function or WorkUnit to one to three versioned expert fragments for its actual risks.
 ---
 
 <!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
 
-# Single-purpose function contracts
+# Single-purpose function router
 
-## Objective
+## Outcome
 
-Build and change software by composing functions that each fulfill one explicit, testable contract.
+Create code whose functions each own one cohesive externally observable responsibility, with explicit boundaries, effects, failures, and focused verification across languages, frameworks, and repositories.
 
-Apply this guidance across languages, frameworks, and repositories. Typed examples are intentional: adapt their contracts to the project’s type system, validation tools, error model, persistence layer, and test framework instead of treating TypeScript syntax as a requirement.
+This file is the mandatory compact index for code work. It is not a request to read every reference. Read this index completely, select the smallest sufficient expert set, and then read only those expert files.
 
-Use it for the smallest coherent surface touched by the task. Do not turn an ordinary change into a repository-wide rewrite.
+## Universal core
 
-## What “one thing” means
+Apply these invariants to every created or changed function:
 
-A function does one thing when it has:
+1. State one contract: input, success, expected failures, effects, and observable result.
+2. Give it one responsibility and one reason to change. Do not create meaningless micro-functions.
+3. Validate hostile input at the boundary; keep the private core constrained by types or validated values.
+4. Do not mutate caller-owned input unless mutation is the explicit API contract.
+5. Make domain decisions deterministic. Keep persistence, network, filesystem, process, clock, randomness, UI, and logging effects explicit.
+6. Return or throw failures intentionally. Do not silently swallow, partially succeed, or leak lower-layer accidents as the public contract.
+7. Add the smallest runnable test that proves success, the important failure, and the regression being changed.
+8. Preserve unrelated code and existing public behavior unless the task explicitly changes it.
 
-- one cohesive externally observable responsibility;
-- one primary reason to change;
-- one defined success result;
-- one explicit set of expected failures;
-- one declared effect profile.
+Small is not the objective. Cohesion is. Keep operations together when splitting them would hide sequencing, duplicate policy, or weaken a transaction.
 
-“One thing” does not mean one statement, one branch, or the shortest possible function.
+## MoE selection contract
 
-Good examples include:
+For each new or materially changed function, or for the smallest WorkUnit that owns a cohesive use case:
 
-- parse one untrusted request;
-- normalize one validated configuration value;
-- calculate one price or ranking;
-- load one record through a persistence interface;
-- render one output representation;
-- coordinate one atomic use case.
+1. classify the dominant risk;
+2. select one expert ID from the table below;
+3. add at most two more only when the same contract genuinely crosses those risks;
+4. record a concrete reason for every selection;
+5. read the selected files before implementation or review.
 
-An orchestration function may call several functions. Its single responsibility is coordinating one use case. Keep detailed policy in domain functions and external mechanics in adapters or stores.
+Do not make a new Skill per function. The function contract is the execution envelope; `expertRefs` are its mixture-of-experts dispatch. If two functions need materially different expert sets or reasons to change, split the WorkUnit or record separate function contracts inside it.
 
-## Project contracts outrank generic advice
-
-Before changing code, inspect the relevant source, tests, documentation, types, error conventions, and adjacent helpers.
-
-Preserve the repository’s established contracts unless the task explicitly changes them:
-
-- public APIs and serialized formats;
-- error types, codes, and messages;
-- transaction and concurrency rules;
-- ownership and mutation conventions;
-- framework and dependency boundaries;
-- security and privacy requirements;
-- test and build commands.
-
-Reuse a project helper when it already implements the required behavior. Do not introduce a parallel result type, validation library, database wrapper, dependency container, or architecture merely because it is familiar from another project.
-
-## Function layers
-
-Classify every new or materially changed function before implementing it.
-
-### Boundary parser or validator
-
-A boundary function receives data that is not yet trusted, including network requests, command-line input, environment variables, configuration files, database rows, files, messages, provider responses, and deserialized state.
-
-It should:
-
-1. bound work before expensive processing;
-2. reject malformed shape, type, range, encoding, size, depth, count, or unknown fields when required;
-3. avoid invoking caller-controlled getters, proxies, hooks, or serialization behavior;
-4. create an owned normalized value;
-5. return that value or produce one narrow, safe expected failure.
-
-After validation, delegate to typed or otherwise constrained internal code. Do not make every internal helper revalidate the same value.
-
-### Pure domain function
-
-A pure domain function performs one decision, state transition, normalization, ranking, projection, or calculation over validated values.
-
-It must not hide reads of time, randomness, environment, locale-sensitive state, mutable globals, filesystem, database, or network. Pass variable dependencies explicitly. The same explicit inputs should produce the same output.
-
-### Persistence function
-
-A persistence function performs one storage capability.
-
-It should:
-
-- use the project’s established database or storage abstraction;
-- parameterize queries where applicable;
-- avoid transport and presentation concerns;
-- avoid network and unrelated filesystem work;
-- remain transaction-agnostic unless it explicitly owns the transaction;
-- validate stored data before treating it as domain state;
-- preserve revision, idempotency, ordering, and identity invariants.
-
-### Effect adapter
-
-An adapter wraps one external capability, such as reading a file, calling a provider, obtaining time, generating an identifier, writing a response, or opening a database.
-
-Expose the smallest capability required. Prefer a narrow function or interface over a broad service container.
-
-### Use-case orchestrator
-
-An orchestrator coordinates one application operation. It may combine validation, pure decisions, persistence, and adapters, but it should not absorb their detailed policies.
-
-## Required contract
-
-Before implementing a new function or materially changing an existing one, determine:
+In Enno-Oduno plans, `expertRefs` is required for code-changing WorkUnits and is revision-bound. Outside Enno-Oduno, keep the same mapping in the working plan or review notes:
 
 ```text
-Function:
-Layer: boundary | domain | persistence | adapter | orchestrator
-Responsibility:
-Inputs and trust level:
-Input ownership:
-Success output:
-Expected failures:
-Other propagated failures:
-External effects:
-Transaction or resource ownership:
-Idempotency or replay behavior:
-Security and privacy constraints:
-Preconditions:
-Postconditions:
+target -> responsibility -> expert IDs -> focused verifier
 ```
 
-The contract may remain internal for a small change, but the implementation and tests must reflect it.
-
-## Non-negotiable rules
-
-### 1. Do not mutate caller-owned input
-
-Treat parameters as immutable unless the contract explicitly transfers ownership.
-
-- Do not modify caller-provided objects, arrays, maps, sets, buffers, collections, or records.
-- Return a new value for transformations.
-- Local mutation of newly allocated, unobservable data is allowed when it improves clarity or measured performance.
-- Do not use shared mutable state for domain behavior.
-
-Add an input-snapshot test when accidental mutation is plausible.
-
-### 2. Validate values at the real trust boundary
-
-Static types, annotations, interfaces, and schemas known only to the compiler do not validate runtime data.
-
-Use the repository’s established validation approach. Validate external JSON, database rows, configuration, files, provider responses, and messages before converting them into domain values. Reject or explicitly handle unknown fields when the contract is closed.
-
-Use an unconstrained type such as `unknown`, a raw byte buffer, or a generic map only at a real boundary. Internal helpers should receive constrained values.
-
-### 3. Bound work before trust
-
-Every externally influenced collection, string, nested object, retry loop, result set, or payload needs a justified bound.
-
-Check limits before full traversal, expansion, hashing, serialization, proportional allocation, persistence, retrying, or returning data. Truncate only when the contract explicitly defines a preview or diagnostic field; otherwise reject oversized authoritative input.
-
-### 4. Produce an owned snapshot
-
-Do not retain references to hostile or caller-controlled data after validation. Copy accepted values into owned structures before canonicalization, hashing, persistence, or asynchronous use.
-
-Where the runtime permits hostile object behavior, account for accessors, proxies, cycles, malformed text, unsupported prototypes, and non-finite numbers.
-
-### 5. Use narrow types and exact states
-
-- Prefer the strongest practical static analysis and type-checking mode supported by the project.
-- Avoid escape hatches such as `any`, unchecked casts, suppressed diagnostics, or untyped dictionaries when a narrower representation is possible.
-- Use enums, literal unions, sealed variants, value objects, or equivalent exact state models.
-- Distinguish missing, null, unknown, empty, unavailable, and invalid when the protocol distinguishes them.
-- Omit absent optional values rather than inventing ambiguous placeholders.
-- Keep assertions adjacent to the runtime check that proves them.
-
-### 6. Make expected failures explicit and safe
-
-Use the project’s established error taxonomy or result convention. Choose the narrowest existing failure category.
-
-Do not use `false`, `null`, an empty string, or a swallowed exception to represent several unrelated failures. Do not catch an error merely to hide it or continue from uncertain state.
-
-At public boundaries:
-
-- map internal failures to stable public behavior;
-- keep details bounded and allowlisted;
-- never echo credentials, tokens, private data, raw request bodies, or unsafe provider responses;
-- preserve both operation and cleanup failures when both occur.
-
-### 7. Keep domain decisions deterministic
-
-Inject time, randomness, environment, current directory, locale, filesystem, database, network, and provider access. Use stable ordering and serialization when output participates in hashes, identities, manifests, caches, snapshots, or replay.
-
-### 8. Preserve transaction and resource discipline
-
-- Let one use case own the transaction or resource lifecycle.
-- Keep low-level storage functions composable inside that owner.
-- Do not perform network calls, user prompts, or unrelated slow work while holding a write transaction or scarce lock.
-- Do not add nested transaction ownership where an outer transaction already exists.
-- Treat ambiguous commit or cleanup state explicitly; do not compensate as though rollback were proven.
-
-### 9. Preserve idempotency and compare-and-swap semantics
-
-Bind every meaning-bearing input to request identities, expected revisions, generation tokens, content hashes, or cache keys.
-
-- Exact replay may reuse the recorded acknowledgement.
-- Reusing an identity with changed input is a conflict.
-- Compare the exact observed version before mutation.
-- Never silently overwrite newer or independently owned state.
-- Never present partial or ambiguous cleanup as full success.
-
-### 10. Preserve external contracts
-
-A refactor is not behavior-preserving if it accidentally changes a machine contract.
-
-Preserve applicable command output, exit status, API schema, HTTP status, protocol envelope, database migration history, file format, line ending, file mode, ownership marker, event order, and backward-compatibility behavior.
-
-### 11. Keep security checks in the success path
-
-Security validation is not optional logging. Apply required authorization, normalization, sanitization, size checks, secret detection, and path or URL restrictions before persistence or delivery.
-
-A detected secret or invalid value must not reappear in errors, logs, hashes exposed to callers, temporary diagnostics, or responses.
-
-### 12. Test the contract independently
-
-Use the repository’s existing test framework and style. Cover the applicable cases:
-
-- normal success;
-- empty, minimum, maximum, and exact boundary values;
-- wrong primitive type or malformed structure;
-- unknown fields for closed inputs;
-- each expected failure category;
-- no mutation of caller-owned input;
-- no secret or raw invalid-value echo;
-- deterministic ordering, hashing, or replay identity;
-- exact replay and changed-input conflict;
-- bounded retry and non-retryable failure;
-- operation-plus-cleanup failure;
-- integration with the real boundary when adapter behavior changes.
-
-Assert observable behavior, not private call order, unless ordering itself is a documented invariant.
-
-## Required workflow
-
-1. Read the governing repository contracts and adjacent implementation.
-2. Define the smallest coherent behavior change.
-3. Classify each changed function’s layer.
-4. Determine its input, output, failure, effect, ownership, and replay contract.
-5. Validate once at the hostile boundary and create owned data.
-6. Implement deterministic policy in the pure core.
-7. Add only the narrow external capability required.
-8. Compose the use case without mixing detailed policies into orchestration.
-9. Add a regression test for the counterexample that would disprove the contract.
-10. Run the narrowest affected tests, then the repository’s documented static, type, test, build, and package checks as applicable.
-11. Report what changed, what was verified, what was skipped, and any residual risk.
-
-Do not invent commands that are absent from the repository.
-
-## Decomposition tests
+Do not load unselected fragments “just in case.” If repository evidence exposes a new risk, update the selection explicitly before consuming that fragment.
 
-Split or redesign a function when one or more are true:
+## Expert index
 
-1. Its responsibility requires “and then” to join unrelated observable outcomes.
-2. It validates transport data, decides policy, performs persistence, and formats a response in one body.
-3. It directly uses more than one unrelated external subsystem.
-4. It returns a value while mutating external state not required by its contract.
-5. It owns a transaction while performing network or unrelated slow work.
-6. Its pure decision can be tested only by booting unrelated infrastructure.
-7. A boolean flag switches between unrelated modes.
-8. Error mapping or validation policy is duplicated across layers.
-9. Security, replay, or cleanup state is implicit instead of represented.
+| Expert ID | Select when the contract owns | Read |
+| --- | --- | --- |
+| `code.boundary.v1` | parsing, validation, authorization, ownership, untrusted input | [boundaries-and-ownership.md](references/boundaries-and-ownership.md) |
+| `code.domain.v1` | domain rules, state transitions, narrow types, deterministic decisions | [domain-and-types.md](references/domain-and-types.md) |
+| `code.effects.v1` | database, filesystem, network, process, transaction, resource lifetime | [effects-and-data.md](references/effects-and-data.md) |
+| `code.protocol.v1` | retry, idempotency, concurrency, revisions, external/public protocols | [protocols-and-idempotency.md](references/protocols-and-idempotency.md) |
+| `code.verification.v1` | regression repair, test design, review, compatibility or failure evidence | [verification.md](references/verification.md) |
 
-Do not split when extraction would create a meaningless one-line wrapper, scatter one atomic state machine, or obscure resource ownership.
+Typical selections:
 
-## Prohibited shortcuts
+- pure calculation: `code.domain.v1`;
+- request parser: `code.boundary.v1` + `code.verification.v1`;
+- transactional write: `code.effects.v1` + `code.protocol.v1`;
+- public API repair: `code.boundary.v1` + `code.protocol.v1` + `code.verification.v1`.
 
-Do not:
+## Escalation references
 
-- claim static types prove external input is valid;
-- cast external data directly into a domain type;
-- weaken types merely to satisfy one inconvenient call site;
-- mutate input because copying is inconvenient;
-- swallow corruption, conflict, partial failure, or uncertain state;
-- echo invalid or secret-like values in public failures;
-- retry by matching error-message text when structured classification exists;
-- run external work inside a write transaction without a documented reason;
-- bypass revision, idempotency, identity, authorization, or ownership checks;
-- overwrite independently owned state;
-- create dozens of trivial wrappers to satisfy a function-count or line-count target;
-- change public contracts as incidental cleanup;
-- declare completion without naming the verification actually run.
+Read [kiokuko-patterns.md](references/kiokuko-patterns.md) only when a selected fragment needs a fuller TypeScript example. Read [review-checklist.md](references/review-checklist.md) for comprehensive code review or final verification, not for every function edit.
 
-## Completion gate
+## Completion report
 
-Before declaring completion, use `references/review-checklist.md`. Read `references/kiokuko-patterns.md` when examples would help; despite the historical filename, its guidance applies across languages and repositories.
+Report the function or WorkUnit contracts changed, selected expert IDs, focused verifier results, and anything not verified. A build alone does not prove boundary, failure, or interaction behavior.

package/skills/kiokuko-single-purpose-functions/references/boundaries-and-ownership.md

@@ -0,0 +1,50 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.boundary.v1` — boundaries and ownership
+
+Select this expert when a function receives data or authority from a caller, user, file, database, environment, network, parser, plugin, or another process.
+
+## Contract
+
+The public boundary accepts broad input only long enough to validate and normalize it into a narrow internal value. Reject malformed, ambiguous, oversized, unauthorized, or out-of-scope input before domain work or effects begin.
+
+Define explicitly:
+
+- what input representations are accepted;
+- whether normalization changes identity or only representation;
+- which limits prevent resource abuse;
+- which caller or principal is authorized;
+- which errors are public and stable;
+- who owns mutable collections, buffers, streams, or objects after the call.
+
+Validation must match the actual threat boundary. A TypeScript type annotation does not validate JSON. A UI constraint does not validate an HTTP request. A prior parser does not authorize the current operation.
+
+## Ownership rules
+
+- Treat caller-owned inputs as immutable by default. Copy before sorting, filtering in place, deleting keys, or retaining a mutable reference.
+- Do not return internal mutable state directly when callers could corrupt invariants.
+- Make transfer of ownership explicit for streams, handles, transactions, and buffers.
+- Avoid aliases where one layer can mutate data another layer assumes is stable.
+- Preserve original user data through validation failures unless destructive normalization is the explicit contract.
+
+## Boundary shape
+
+Prefer a thin public function that performs hostile-boundary work and then calls a constrained private core:
+
+```ts
+function parseCreateRequest(input: unknown): CreateRequest {
+  const parsed = createRequestSchema.safeParse(input);
+  if (!parsed.success) throw new PublicError('invalid_request');
+  return parsed.data;
+}
+
+function decideCreate(request: CreateRequest): CreateDecision {
+  // No unknown input remains here.
+}
+```
+
+Do not scatter the same validation across several deeper functions. Centralize public error mapping so transport, database, or parser details do not accidentally become the API.
+
+## Focused verification
+
+Test at least one valid input, each materially different rejection class, caller-input immutability, and the absence of effects after rejection. For authorization boundaries, include a counterexample that has valid shape but insufficient authority.

package/skills/kiokuko-single-purpose-functions/references/domain-and-types.md

@@ -0,0 +1,48 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.domain.v1` — domain rules and narrow types
+
+Select this expert when the function decides business rules, computes values, classifies states, or moves an entity through a state machine.
+
+## Contract
+
+Domain logic should be deterministic for the same validated input. Keep clocks, randomness, persistence, network calls, environment reads, and logging outside the decision or inject their values explicitly.
+
+Model legal states and transitions directly. Prefer narrow unions, enums, tagged results, value objects, and exhaustive branches over booleans or loosely related nullable fields whose combinations can become invalid.
+
+Define:
+
+- the valid input state;
+- the exact transition or result;
+- invariants preserved before and after;
+- expected domain rejections;
+- whether the operation is total or intentionally partial.
+
+## Cohesion rules
+
+- A function may contain several steps when they implement one rule and change for the same reason.
+- Split unrelated policy decisions even if they currently share a caller.
+- Do not extract trivial wrappers that merely rename an expression without creating a useful contract.
+- Do not mix “decide what should happen” with “persist or publish it” when the decision can be represented as data.
+
+Example:
+
+```ts
+type Transition =
+  | { kind: 'advance'; next: State }
+  | { kind: 'reject'; code: 'stale_revision' | 'terminal' };
+
+function decideAdvance(current: State, expectedRevision: number): Transition {
+  if (current.revision !== expectedRevision) return { kind: 'reject', code: 'stale_revision' };
+  if (current.status === 'completed') return { kind: 'reject', code: 'terminal' };
+  return { kind: 'advance', next: { ...current, revision: current.revision + 1 } };
+}
+```
+
+## Failure behavior
+
+Expected domain failure is part of the result contract, not an accident to catch broadly. Use one explicit representation consistently. Reserve unexpected exceptions for integrity failures or defects that the current function cannot safely classify.
+
+## Focused verification
+
+Test representative valid states, every legal transition family, forbidden transitions, boundary values, and determinism. When a state space is finite, test exhaustiveness or generate a transition table rather than relying only on happy-path examples.

package/skills/kiokuko-single-purpose-functions/references/effects-and-data.md

@@ -0,0 +1,43 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.effects.v1` — effects, data, and resource lifetime
+
+Select this expert when a contract touches a database, filesystem, network, subprocess, cache, message bus, clock, random source, UI runtime, or long-lived resource.
+
+## Contract
+
+Make the effect profile visible at the function boundary. A function that appears pure but reads global state, mutates a cache, logs sensitive data, or launches background work has a misleading contract.
+
+Separate four concerns when practical:
+
+1. validate and authorize the request;
+2. decide the domain change;
+3. apply effects under an explicit atomicity policy;
+4. translate infrastructure outcomes into the public result.
+
+Do not split a transaction merely to make functions shorter. Operations that must commit or roll back together belong under one transaction owner. Conversely, do not hide unrelated writes inside a function whose name promises only a read or calculation.
+
+## Data integrity
+
+- State which writes are atomic and which partial outcomes are possible.
+- Use compare-and-set, revision checks, unique constraints, or locks where concurrent writers can violate invariants.
+- Check affected-row counts when they prove the intended state transition occurred.
+- Never claim persistence before durable completion.
+- Keep schema or serialization compatibility explicit at stored-data boundaries.
+- Do not swallow a failed cleanup, rollback, or close when it changes correctness.
+
+## External effects
+
+- Bound time, output, memory, and retries.
+- Define cancellation semantics: cancelling the UI is not the same as cancelling the work.
+- Close files, streams, transactions, child processes, and subscriptions on success and failure.
+- Avoid fire-and-forget work unless ownership, failure reporting, and process lifetime are deliberately defined.
+- Sanitize logs and previews; do not leak secrets or private payloads through diagnostic output.
+
+## Testing seam
+
+Inject the narrow effect capability needed by the contract rather than an entire ambient service container. A focused fake should let tests observe calls, order, arguments, cleanup, and failure mapping without reproducing the infrastructure implementation.
+
+## Focused verification
+
+Test successful effect order, failure before mutation, failure during mutation, rollback or cleanup, timeout/cancellation, and concurrent or stale writes when applicable. Integration-test the real adapter separately from deterministic domain tests.

package/skills/kiokuko-single-purpose-functions/references/protocols-and-idempotency.md

@@ -0,0 +1,42 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.protocol.v1` — protocols, concurrency, and idempotency
+
+Select this expert when callers retry, messages can be duplicated, state is revisioned, several actors race, or a public/API/storage protocol must remain compatible.
+
+## Contract
+
+Identity, ordering, and state transition rules are public behavior. Do not infer them from error text, timestamps, repository-wide “latest” records, or other ambiguous signals.
+
+Define:
+
+- the stable operation or request identity;
+- which input fields are bound to that identity;
+- the exact legal source states;
+- the expected revision or version;
+- retry and replay behavior;
+- what a duplicate with identical input returns;
+- what a duplicate identity with changed input returns;
+- which actor owns each transition.
+
+## Idempotency
+
+A safe idempotent operation distinguishes exact replay from conflicting reuse. Persist or derive a digest from the complete bound input. Return the stored result for an exact replay; reject changed input under the same key.
+
+Do not generate a new identity for a transport retry. Do generate a new identity for a new logical operation, even when the visible task text happens to match.
+
+## Concurrency
+
+- Check revision and allowed source state in the same atomic mutation.
+- Make ambiguous candidates fail closed or remain unbound; never guess.
+- Treat zero or multiple affected rows as evidence that the expected transition did not occur.
+- Prevent stale completion, retry, or callback results from overwriting newer state.
+- Keep terminal states terminal unless the protocol explicitly defines a new revision or recovery transition.
+
+## Compatibility
+
+For versioned APIs or stored structures, accept an older representation only when the compatibility policy is explicit and tested. Do not create silent fallback paths that bypass a new safety invariant. Prefer a clean break when old data cannot satisfy the current contract safely.
+
+## Focused verification
+
+Test first execution, exact replay, conflicting reuse, stale revision, wrong source state, concurrent claim, terminal-state behavior, and response compatibility. A text-match test is insufficient when the protocol exposes structured codes or exact identities.

package/skills/kiokuko-single-purpose-functions/references/verification.md

@@ -0,0 +1,41 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.verification.v1` — focused evidence and review
+
+Select this expert for regression repair, behavior review, compatibility changes, or any function whose correctness claim depends on evidence beyond ordinary local reasoning.
+
+## Evidence contract
+
+Verification must exercise the same boundary and pipeline as the reported or intended behavior. A build does not replace a typecheck. A unit test of a helper does not replace the HTTP, CLI, hook, database, browser, or packaging path that failed.
+
+Before editing, state a falsifiable invariant and at least one counterexample. After editing, run the smallest focused verifier that proves the change, then the broader verifier proportional to regression risk.
+
+## Test shape
+
+For each changed contract cover:
+
+- representative success;
+- important expected failure;
+- the reported regression or a concrete counterexample;
+- absence of forbidden effects after rejection;
+- ownership or immutability when mutable input is possible;
+- concurrency, retry, cancellation, or cleanup when the selected experts require them.
+
+Prefer observable behavior over private implementation details. Use deterministic inputs and narrow fakes. Keep test names specific enough to identify the contract and failure class.
+
+## Review method
+
+Trace caller to boundary to domain decision to effects to public result. Check generated instructions, stored representations, migrations, packaging manifests, and runtime adapters when they are part of delivery; source code alone may not be the shipped behavior.
+
+Classify uncertainty honestly:
+
+- verified by a matching runnable test;
+- inspected from source only;
+- blocked by environment or unavailable dependency;
+- not checked.
+
+Do not convert a sandbox, listener, DNS, registry, or permission restriction into a product defect without a matching permitted rerun. Do not repeatedly run an unchanged blocked verifier.
+
+## Completion
+
+Report exact verifier commands or test names, their result, changed contract scope, and remaining gaps. If only a subset ran, do not claim the full suite passed.

package/skills/kiokuko-soul/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: kiokuko-soul
+description: Use before every non-trivial Kiokuko-governed task as the mandatory first-read SOUL router. Route applicable Enno-Oduno control, code work, and interactive UI work to the bundled specialist Skills without replacing their contracts.
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-soul -->
+
+# Kiokuko SOUL router
+
+## Outcome
+
+Start every non-trivial Kiokuko-governed task from one stable routing decision, then read the applicable compact specialist indexes and only the expert fragments required by the current role and work.
+
+This Skill routes work. It does not duplicate specialist instructions, invent an Enno-Oduno run, select another model, or authorize effects beyond the user request and current client permissions.
+
+## Required entry
+
+Read this Skill before any other bundled Kiokuko Skill.
+
+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,
+false attestation, missing availability, unknown availability, aliases,
+namespaced copies, and fetched references fail closed. The attestation is an
+explicit client claim; it is not remote proof of model cognition.
+
+Then inspect the current user request, repository evidence, `task_prepare` or `task_answer` result when present, and any revision-bound Enno-Oduno directive. Treat a returned `nextAction`, role, required-Skill list, and stop condition as authoritative for that run.
+
+Read the complete `SKILL.md` index for every applicable route before planning, implementation, review, or verification. Each specialist index defines versioned expert fragments. Read only fragments selected by the approved WorkUnit or concrete task risk; do not load every reference by default. Do not substitute this router's summary for a specialist core contract.
+
+## Routes
+
+### Enno-Oduno control
+
+Read and apply `kiokuko-enno-oduno` only when its activation boundary is satisfied:
+
+- `task_prepare` or `task_answer` returned `ennoOduno.applicable=true` for the current `enno-oduno` role;
+- a continuation directive resumes that role for an existing run; or
+- the user explicitly asks to inspect or operate an Enno-Oduno run.
+
+Do not invent a run, role, revision, WorkUnit, or state transition merely because Kiokuko is present.
+
+### Code work
+
+Read and apply the `kiokuko-single-purpose-functions` index before writing, modifying, debugging, refactoring, or reviewing code, and before decomposing a code-changing WorkPlan. Select one to three `code.*` expert fragments for each cohesive function or WorkUnit.
+
+### 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.
+
+### 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.
+
+Use this order:
+
+1. `kiokuko-soul`;
+2. `kiokuko-enno-oduno` when the current role requires Enno-Oduno control;
+3. `kiokuko-single-purpose-functions` for code planning or code work;
+4. `kiokuko-ui-design-soul` for interactive UI work.
+
+The current revision-bound directive may narrow which routes the active role performs. Do not let a later route cross a role boundary or expand an approved WorkUnit.
+
+## Availability and trust
+
+When a current directive or capability recommendation marks a routed Skill as required, stop on `required_capability_unavailable`, a blocked Enno-Oduno state, or equivalent unavailable-required-Skill result.
+
+Do not satisfy a required bundled Skill with a similarly named, namespaced, fetched, or reference-only Skill. Never install or execute external Skill content automatically.
+
+Skill availability alone is not evidence that its contract was applied. The
+mandatory `soulRead: true` attestation makes that claim explicit but does not
+turn it into cryptographic or remote proof.