kiokuko-dsh 0.1.0

package/skills/kiokuko-single-purpose-functions/references/review-checklist.md

@@ -0,0 +1,97 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# Function-contract coding and review checklist
+
+Use this checklist while implementing, debugging, refactoring, or reviewing code in any language or repository. Apply only the sections relevant to the change.
+
+## Scope
+
+- [ ] The change addresses one stated behavior.
+- [ ] No unrelated cleanup, public API redesign, migration rewrite, dependency replacement, or broad type churn was added.
+- [ ] Relevant architecture, security, data, protocol, and feature contracts were checked.
+
+## Function responsibility
+
+- [ ] Each changed function has one cohesive externally observable responsibility.
+- [ ] Boundary, domain, persistence, adapter, and orchestrator roles are not mixed without a specific reason.
+- [ ] Extraction created a meaningful operation rather than a one-line wrapper.
+- [ ] An atomic state machine, transaction, or cleanup sequence was not fragmented into an unreadable chain.
+
+## Inputs and ownership
+
+- [ ] Externally influenced values are untrusted until runtime validation.
+- [ ] Strings, collections, nesting, retries, and output are bounded.
+- [ ] Closed shapes reject unknown fields where required.
+- [ ] Hostile input cannot trigger unsafe getters, proxies, hooks, or custom serialization during validation.
+- [ ] Validated values are copied into owned data where references could escape.
+- [ ] Caller-owned input is not mutated.
+- [ ] Missing, null, empty, unknown, unavailable, and invalid states remain distinct where required.
+- [ ] No new unchecked cast, suppressed diagnostic, or type escape hatch bypasses a boundary check.
+
+## Domain behavior
+
+- [ ] Pure calculations, normalization, ranking, and state transitions have no hidden I/O.
+- [ ] Time, randomness, environment, locale, and external capabilities are explicit dependencies.
+- [ ] Canonical order and serialization are deterministic where identity or hashing depends on them.
+- [ ] Preconditions and postconditions are represented in code or tests.
+
+## Errors, privacy, and security
+
+- [ ] Expected failures use the project’s narrowest existing error or result category.
+- [ ] Public messages and details are stable, bounded, and allowlisted.
+- [ ] Invalid values, credentials, private data, provider bodies, and secret-like strings are not echoed.
+- [ ] Unknown internal failures are not exposed as raw messages.
+- [ ] Primary and cleanup failures are both preserved when both occur.
+- [ ] No catch block turns corruption, conflict, partial failure, or uncertain state into success.
+- [ ] Authorization, normalization, sanitization, and secret checks remain in the successful execution path.
+
+## Persistence, transactions, and resources
+
+- [ ] Queries are parameterized where applicable and kept out of transport or presentation code.
+- [ ] Stored data is validated before becoming domain state.
+- [ ] Low-level persistence functions remain transaction-agnostic when they compose inside a use case.
+- [ ] One clear owner controls the transaction or resource lifecycle.
+- [ ] No network, user prompt, child process, or unrelated slow work runs while holding a write transaction or scarce lock.
+- [ ] Retry classification uses structured error information instead of message text.
+- [ ] Ambiguous commit and incomplete cleanup states prevent unsafe compensation.
+
+## Idempotency and identity
+
+- [ ] Exact replay and changed-input conflict are distinguished.
+- [ ] Every meaning-bearing input participates in replay, generation, revision, or cache identity.
+- [ ] Expected-version checks happen before mutation.
+- [ ] Independently owned or newer state is not silently overwritten.
+- [ ] Partial or ambiguous cleanup is reported rather than presented as success.
+
+## External contracts
+
+- [ ] Public APIs, command output, exit status, schemas, event order, and serialized formats remain stable unless intentionally changed.
+- [ ] Protocol output is not contaminated by diagnostics or logging.
+- [ ] Authentication, authorization, origin, path, and confirmation boundaries remain intact.
+- [ ] Package manifests include required runtime files.
+- [ ] Migration history and recorded checksums are not rewritten in place.
+- [ ] Managed markers, file modes, line endings, and unrelated user content are preserved where applicable.
+
+## Tests
+
+- [ ] A regression test captures the original failure or falsifying counterexample.
+- [ ] Normal success behavior is covered.
+- [ ] Empty, minimum, maximum, and exact-boundary values are covered where relevant.
+- [ ] Wrong types, malformed shapes, unknown fields, or hostile values are covered at changed boundaries.
+- [ ] Caller-owned input immutability is asserted where plausible.
+- [ ] Secret and invalid-value non-echo is asserted where applicable.
+- [ ] Each changed expected failure category is asserted.
+- [ ] Retry bounds and non-retryable failures are covered when retry behavior changes.
+- [ ] Rollback, ambiguous commit, and dual operation/cleanup failures are covered when ownership changes.
+- [ ] Exact replay and changed-input conflict are covered when idempotency changes.
+- [ ] Integration tests exercise the real storage, filesystem, network, process, or protocol boundary when adapter behavior changes.
+- [ ] Tests assert observable contracts, not incidental private call order.
+
+## Verification report
+
+- [ ] The narrow affected test was run.
+- [ ] Relevant static or type checks were run.
+- [ ] The broader suite was run when shared behavior changed.
+- [ ] Build and package checks were run when distribution changed.
+- [ ] Every skipped command, known failure, assumption, and residual risk is stated exactly.
+- [ ] Completion is not described as perfect, crash-proof, or fully verified beyond the evidence.

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,104 @@
+---
+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 applicable Enno-Oduno control, simple code work, general code work, and interactive UI work to the bundled specialist Skills.
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-soul -->
+
+# Kiokuko SOUL router
+
+## 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 role and work.
+
+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, 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.
+
+Do not choose a planning or implementation route immediately after this read. Enter the Akinator intake gate below first. Treat every 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.
+
+## Akinator intake gate
+
+Akinator is the mandatory state machine between this SOUL read and every planning or implementation route. It applies whether or not Enno-Oduno is applicable.
+
+Open the gate once for the current logical request:
+
+1. Create one bounded opaque `requestId`. Use a new value for every new logical request, even when its text is identical. Reuse it only for an exact transport retry.
+2. Call `task_prepare` at most once with `soulRead: true`, that `requestId`, the actual task, current working directory, only profile hints grounded in the user request or repository evidence, and the complete capability catalog available in the current client.
+3. Reuse the successful result for the rest of the request. Inspect `intake.status`, the exact current `intake.question`, top-level `nextAction`, `memoryPolicy`, capability results, and `ennoOduno` when present.
+4. Retain the returned `run.runId` and `context.deliveryId` for later run-bound calls.
+
+Follow the returned intake state without inventing missing facts:
+
+- **`needs_answer`** or **`nextAction=answer_from_evidence_or_ask_user`**: Akinator controls progress. Use its hypotheses and question purpose only to understand the distinction being tested. Answer the exact current question through `task_answer` only when the value is grounded in the user request or verified repository evidence; otherwise ask the user that question. Repeat the same capability catalog and context budget, inspect the new question and state after every answer, and continue until `ready` or `exhausted`. Do not plan, implement, verify, enter the simple/code/UI routes, or call `memory_checkpoint` while unresolved. If `ennoOduno.applicable=true`, read `kiokuko-enno-oduno` now because it owns the applicable run's intake interaction, but do not start Zenki or Goki.
+- **`ready`**: obey top-level `nextAction`, capability requirements, memory policy, and any Enno-Oduno directive. Only then select the applicable routes below.
+- **`exhausted`**: no further Akinator question is available, but `intake.missingFields` may remain. Preserve that uncertainty, do not invent the missing answers or describe the intake as fully specified, and route only when top-level `nextAction` permits.
+
+If `task_prepare` is unavailable before a non-trivial build or debug request can obtain its policy, stop and report the unavailable policy. The sole exception is diagnosing or repairing Kiokuko itself after `task_prepare` fails before returning scoped context: continue only from repository evidence, and do not call `task_answer` or `memory_checkpoint` for that failed request.
+
+## Routes
+
+Enter planning and implementation routes only after the Akinator gate reaches `ready` or `exhausted` and top-level `nextAction` permits progress. Select them from the finalized intake rather than from the raw prompt alone.
+
+### 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.
+
+### Simple code work
+
+Read and apply `kiokuko-simple-work` when either condition is true:
+
+- the request is a bounded code change with a clear target and expected result, and it introduces no new architecture, dependency, data migration, public protocol, security or authorization policy, or cross-system orchestration;
+- the user explicitly requests the simplest, shortest, minimal, YAGNI, dependency-free, or Ponytail approach.
+
+This route minimizes the solution; it does not replace the code contract below or waive required understanding, boundary validation, error handling, security, accessibility, or focused verification. If the task's simplicity is unclear and the user did not explicitly request this route, use the ordinary code route without it.
+
+### 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. one Akinator `task_prepare`, followed by grounded `task_answer` calls until `ready` or `exhausted`;
+3. `kiokuko-enno-oduno` as soon as the returned state makes Enno-Oduno control applicable, including during unresolved intake;
+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.
+
+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.

package/skills/kiokuko-ui-design-soul/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: kiokuko-ui-design-soul
+description: Prevent common UI and UX failures when designing, implementing, or reviewing interactive interfaces. Apply a compact universal interaction contract, then route each UI WorkUnit to one to three versioned expert fragments.
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# UI design soul router
+
+## Outcome
+
+Make every interactive action discoverable, operable, perceivable, recoverable, accessible, and coherent across supported sizes and input methods.
+
+Use this Skill for Web, desktop, mobile, touch, keyboard, screen-reader, form, navigation, async, destructive, permission, or other user-facing interaction work. Do not use it for backend-only work.
+
+This file is the mandatory compact UI index. Read it completely, then read only the expert fragments selected for the current component, flow, design decision, or WorkUnit.
+
+## Universal core
+
+A UI action is complete only when the user can:
+
+1. discover and understand it;
+2. activate it comfortably;
+3. perceive immediate acknowledgement;
+4. understand processing, success, and failure;
+5. recover without losing work or context;
+6. continue through keyboard, touch, pointer, and assistive technology as applicable.
+
+Invisible work is a UI failure. Every reachable state needs defined behavior:
+
+```text
+idle -> pressed -> processing -> success | failure | cancelled
+```
+
+Add offline, permission-denied, empty, stale, and recovered states when reachable. Preserve input, selection, focus, scroll, navigation, and completed work through failure and rerender. Prevent duplicate and stale actions. Prefer native or semantic controls and the existing product design system. Respect Reduced Motion. Do not imitate Apple visuals; apply platform conventions, Apple HIG decision principles, and WCAG 2.2 accessibility requirements where relevant.
+
+When requirements compete, prioritize safety and data preservation, accessibility, interaction correctness, user context, platform familiarity, performance, visual refinement, then decoration.
+
+## MoE selection contract
+
+Select one dominant expert for each UI component or cohesive user flow. Add at most two more only when the same WorkUnit genuinely crosses those risks. Record a concrete reason for each selection.
+
+In Enno-Oduno plans, declare the `ui` route locally on each interactive
+WorkUnit. That route requires at least one `ui.*` expert and one `code.*` expert
+because UI behavior is also code behavior; it must not infect sibling test,
+docs, or operations units with UI/code requirements. Goki reads the indexes and
+only the approved fragment files by default.
+
+Do not read every UI reference “for completeness.” If implementation exposes a new risk, return the WorkUnit for an explicit selection or update the non-Enno working plan before reading the additional fragment.
+
+## Expert index
+
+| Expert ID | Select for | Read |
+| --- | --- | --- |
+| `ui.interaction.v1` | controls, feedback, targets, success, perceived responsiveness | [interaction-feedback.md](references/interaction-feedback.md) |
+| `ui.async.v1` | loading, progress, retry, cancellation, concurrency, offline | [async-recovery.md](references/async-recovery.md) |
+| `ui.forms.v1` | forms, validation, uploads, labels, disabled or empty states | [forms-and-controls.md](references/forms-and-controls.md) |
+| `ui.accessibility.v1` | keyboard, focus, semantics, screen readers, contrast, motion | [accessibility-and-navigation.md](references/accessibility-and-navigation.md) |
+| `ui.layout.v1` | responsive layout, zoom, content growth, platform adaptation | [responsive-and-platform.md](references/responsive-and-platform.md) |
+| `ui.safety.v1` | destructive actions, permissions, user-work preservation, severity review | [safety-and-review.md](references/safety-and-review.md) |
+
+Typical selections:
+
+- async Save button: `ui.interaction.v1` + `ui.async.v1`;
+- validated settings form: `ui.forms.v1` + `ui.accessibility.v1`;
+- responsive navigation: `ui.layout.v1` + `ui.accessibility.v1`;
+- delete flow: `ui.safety.v1` + `ui.interaction.v1`.
+
+## Verification
+
+Do not review screenshots alone. Trace actual activation, processing, success, failure, recovery, focus, and responsive behavior. Read [ui-checklist.md](references/ui-checklist.md) only for detailed implementation review or final verification.
+
+Report what was exercised in a running interface, what was inferred from source, and what remains unverified. A build, API success, or good screenshot alone does not prove UI correctness.

package/skills/kiokuko-ui-design-soul/references/accessibility-and-navigation.md

@@ -0,0 +1,31 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.accessibility.v1` — accessibility, focus, and navigation
+
+Select this expert when a flow depends on keyboard order, focus, screen-reader semantics, dynamic status, contrast, motion, dialogs, menus, or navigation continuity.
+
+## Keyboard and focus
+
+Primary functionality must be keyboard-operable where the platform supports it. Verify logical order, visible focus, expected activation keys, Escape behavior, no traps, and sensible focus restoration after dialogs, menus, sheets, or popovers close.
+
+Do not remove focus outlines without an equally visible replacement. Do not move focus merely because content changed; move it only when that helps the next task.
+
+## Semantics and announcements
+
+Prefer native HTML or platform controls. Every interactive element needs a programmatic role and accessible name. Expose values, checked or selected states, expanded state, validation errors, progress, busy state, and material status changes.
+
+Use ARIA only when native semantics are insufficient. Avoid redundant or contradictory attributes. Dynamic announcements must be timely without repeating every incidental update.
+
+## Perception
+
+For Web UI, target WCAG 2.2 AA or the project's stricter standard. Normal text generally needs 4.5:1 contrast, large text 3:1, and meaningful component boundaries or state indicators 3:1 where the criterion applies.
+
+Do not communicate meaning through color, sound, motion, or shape alone. Respect Reduced Motion while preserving equivalent state information. Test zoom, increased text, long values, translated strings, and multiline labels.
+
+## Navigation continuity
+
+Back, browser history, deep links, tabs, modal dismissal, and async completion must preserve a coherent mental model. Closing transient UI should return focus appropriately. Data refresh must not unexpectedly navigate or reset the current item.
+
+## Focused verification
+
+Complete the primary flow keyboard-only, inspect visible focus and focus restoration, check names/roles/status with a screen reader, verify contrast and non-color cues, test 200% text resizing where WCAG applies, and exercise Reduced Motion.

package/skills/kiokuko-ui-design-soul/references/async-recovery.md

@@ -0,0 +1,49 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.async.v1` — asynchronous state and recovery
+
+Select this expert for save, submit, upload, download, import, export, search, AI generation, OCR, sync, authentication, or any user-triggered delayed work.
+
+## State machine
+
+List reachable states before implementation:
+
+```text
+idle -> pressed -> processing -> success | failure | cancelled
+                         \-> offline | permission-denied | stalled
+```
+
+Define how each state is entered, rendered, announced, exited, retried, and cleaned up. Loading, empty, and failure must be distinguishable.
+
+## Processing
+
+- Acknowledge activation immediately; do not wait for the server.
+- Use determinate progress only when it measures real progress. Never fake a percentage.
+- Keep completed user work visible.
+- Prevent accidental duplicate execution while leaving unrelated controls usable.
+- For long work, update expectations and offer cancellation only when it truly stops or safely abandons the operation.
+- State whether work continues in the background and provide completion feedback if users may leave the view.
+
+## Concurrency and lifetime
+
+Guard against double clicks, overlapping requests, stale responses, navigation, unmount, retry while active, and out-of-order completion. When only the newest result is valid, older results must not overwrite it.
+
+Cancellation semantics must be exact. Hiding a dialog or ignoring a result is not cancellation of backend work unless communicated as such.
+
+## Failure and recovery
+
+On failure:
+
+1. stop the busy state;
+2. preserve input and completed work;
+3. explain the affected action in user language;
+4. place the message in the task context;
+5. offer the next real action: Retry, Reconnect, Back, fix a field, choose another file, or save locally.
+
+Do not represent failure only in logs, a rejected promise, a stopped spinner, or “Something went wrong” when a useful cause is known.
+
+Offline queueing may be promised only when work is actually persisted. Permission denial should not cause repeated prompts; explain the limitation and recovery route.
+
+## Focused verification
+
+Test slow success, server failure, timeout, offline, cancellation, repeated activation, stale completion, unmount/navigation, recovery, and accessible status announcements.

package/skills/kiokuko-ui-design-soul/references/forms-and-controls.md

@@ -0,0 +1,35 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.forms.v1` — forms, validation, and control states
+
+Select this expert for data entry, validation, uploads, searchable controls, disabled behavior, and empty states.
+
+## Form state
+
+Define:
+
+```text
+pristine -> editing -> invalid | submitting -> submitted | failed
+```
+
+Use visible labels rather than placeholder-only labels. Make required state understandable without color alone. Validation must identify the affected field and tell users how to fix it without reporting errors prematurely.
+
+Preserve entered values after validation or server failure. After failed submission, guide focus without stealing it unexpectedly. Keyboard submit behavior must be predictable; multiline input must not submit when a newline is expected.
+
+## Submission and uploads
+
+Submitting needs immediate acknowledgement and duplicate prevention. Success must be observable. Failure must retain the form and provide a recovery path.
+
+For uploads show the chosen file, current state, measurable progress, failure and retry, and accurate cancellation semantics. Keep successful uploads when another file fails unless the product contract explicitly makes the batch atomic.
+
+## Disabled and unavailable
+
+A disabled control must look unavailable. If the reason is not obvious, make it discoverable. Do not use low opacity when it makes text illegible, and do not make silent refusal the only explanation. Hiding an action without context is often worse than exposing the requirement near it.
+
+## Empty and loading states
+
+An empty state should say what is absent, why when useful, and the next real action. Loading must not look like empty or broken content. Prefer local placeholders and layout stability over blocking the whole screen for one region.
+
+## Focused verification
+
+Test pristine, partially entered, invalid, keyboard submission, slow submission, server failure, preserved values, focus after error, success, disabled explanation, empty state, and upload retry/cancellation where applicable.

package/skills/kiokuko-ui-design-soul/references/interaction-feedback.md

@@ -0,0 +1,34 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.interaction.v1` — controls and perceivable feedback
+
+Select this expert when users activate buttons, links, menus, tabs, toolbars, gestures, list rows, or other controls.
+
+## Interaction contract
+
+Every activation must produce immediate perceivable acknowledgement before slow work completes. A network request or callback beginning in the background is not feedback.
+
+Use the lightest truthful signal:
+
+- pressed or active state for immediate actions;
+- changed label, local spinner, status, or optimistic state for perceptible delay;
+- visible navigation or content change when the result is self-evident;
+- accessible status text when visual change alone is ambiguous.
+
+Do not force a second click merely to discover whether the first worked. Clear busy and disabled states after success or failure. Avoid noisy success toasts when the result itself is obvious.
+
+## Controls and targets
+
+Prefer native or semantic controls. Labels should predict the action: “Save changes” or “Delete project” is stronger than “OK.”
+
+Judge the effective hit target, not icon artwork. Use platform defaults first. On touch-oriented Web UI, aim around 44×44 CSS px when practical; WCAG 2.2's 24×24 criterion is a floor with exceptions, not the general design target. On Apple platforms prefer standard control sizes; do not shrink ordinary controls to the minimum.
+
+For icon-only controls provide an accessible name, enough context, an expanded target, and pointer discoverability such as a tooltip when useful. Essential actions must not depend on hover or a precision gesture.
+
+## Locality and context
+
+Keep feedback near the initiating control or affected content. Block duplicates of the same operation without disabling unrelated areas. Preserve selection, focus, scroll, cursor, filters, and current item through local updates.
+
+## Focused verification
+
+Exercise pointer, keyboard, and touch when supported. Verify visible focus, immediate acknowledgement, target size and spacing, duplicate activation, success visibility, and the user's retained context after rerender.

package/skills/kiokuko-ui-design-soul/references/responsive-and-platform.md

@@ -0,0 +1,38 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.layout.v1` — responsive behavior and platform adaptation
+
+Select this expert for breakpoints, multi-pane collapse, viewport overlays, safe areas, touch/pointer adaptation, content growth, or cross-platform behavior.
+
+## Functional responsiveness
+
+Responsive design must preserve capability, not merely eliminate horizontal overflow. At each supported size verify:
+
+- the primary action remains visible or readily reachable;
+- navigation remains understandable;
+- important information is not silently removed;
+- controls remain discoverable and comfortable;
+- overlays fit the viewport;
+- fixed bars do not cover content;
+- safe areas are respected;
+- current selection and navigation context survive layout changes.
+
+If a desktop multi-pane layout collapses to one pane, preserve the current item and provide a clear route back. Do not simply remove desktop functionality on mobile without an intentional replacement.
+
+## Content growth
+
+Test increased text, browser zoom, long data, translations, dynamic content, and multiline labels. Avoid fixed heights that clip required content. Truncation must not hide information needed to complete the task.
+
+## Platform conventions
+
+Use the existing product design system and adapt interaction to the target platform:
+
+- Apple platforms: native controls, standard navigation, accessibility behavior, keyboard/pointer conventions, and normal control sizes;
+- Web: semantic HTML, browser behavior, WCAG 2.2, responsive URL-aware navigation, pointer, touch, and keyboard;
+- cross-platform: preserve product identity without forcing identical behavior where platform expectations differ.
+
+HIG principles are decision filters, not a request for iOS styling on the Web.
+
+## Focused verification
+
+Exercise the narrowest and widest supported layouts with real and long content, touch and pointer when applicable, zoom or dynamic type, overlays near viewport edges, orientation or pane changes, and context preservation across breakpoint transitions.

package/skills/kiokuko-ui-design-soul/references/safety-and-review.md

@@ -0,0 +1,39 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# `ui.safety.v1` — destructive actions, permissions, and review severity
+
+Select this expert when an interaction can lose data, change permissions, expose privacy-sensitive information, interrupt unsaved work, or block a primary flow.
+
+## User-work preservation
+
+Preserve form values, edits, generated content, selection, cursor, scroll, filters, and completed work through failure, refresh, navigation, and recovery. A technically successful action that loses the user's place is still defective.
+
+Warn about unsaved work only when loss is real. Prefer persistence or recovery over repeated confirmation friction.
+
+## Destructive actions
+
+Prefer Undo for safely reversible operations. Use explicit confirmation when harm is material, recovery is unavailable, or scope may surprise users. Name the action, count or scope, consequence, and destructive button:
+
+```text
+Delete 14 documents?
+This permanently removes them from this workspace.
+[Cancel] [Delete 14 documents]
+```
+
+Do not use vague “Are you sure?” dialogs or place destructive actions where common actions are easy to hit accidentally. Do not add confirmation to harmless actions by habit.
+
+## Permissions and privacy
+
+Request permission in context and explain why it is needed. After denial, do not repeatedly trigger the system prompt; explain the unavailable capability and provide a safe Settings route or alternative when one exists. Never imply permission, persistence, encryption, background continuation, or cancellation that the system does not provide.
+
+## Review severity
+
+- **BLOCKER:** data loss, irreversible unintended action, inaccessible or impossible primary flow, privacy/security harm, or indefinite ambiguity about an important action.
+- **MAJOR:** invisible async work, duplicate submission, missing recovery, lost input/context, tiny primary target, inaccessible primary operation, hidden mobile functionality, or unprotected destructive behavior.
+- **MINOR:** non-critical copy, spacing, motion, or secondary discoverability that does not block or mislead.
+
+Review actual interaction behavior, not screenshots alone. Trace discovery, activation, processing, duplicate/stale execution, success, failure, recovery, preserved work, focus, and supported layouts.
+
+## Focused verification
+
+Test destructive scope and cancellation, Undo or recovery, failed save after editing, navigation with unsaved work, permission denial and repeat entry, privacy-sensitive output, and the complete primary flow. Do not approve with a known blocker.

package/skills/kiokuko-ui-design-soul/references/ui-checklist.md

@@ -0,0 +1,71 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
+
+# UI design and review checklist
+
+Last reviewed against the official sources: 2026-08-22.
+
+This checklist paraphrases decision principles. It does not reproduce Apple text or require Apple-styled visuals.
+
+## Eight-principle map
+
+| Principle | Practical question |
+| --- | --- |
+| Purpose | Does every important element help the user complete the primary task? |
+| Agency | Can the user understand, initiate, interrupt where safe, and recover from actions? |
+| Responsibility | Does the interface protect privacy, attention, safety, and user-created work? |
+| Familiarity | Do labels, controls, navigation, and feedback follow the target platform's conventions? |
+| Flexibility | Does the flow adapt to ability, input method, device, content size, and context? |
+| Simplicity | Is the next meaningful action clear without hiding necessary information or control? |
+| Craft | Are states, spacing, copy, timing, focus, and edge cases implemented consistently? |
+| Delight | Does successful, calm, recoverable use feel better because the details work together? |
+
+## State coverage
+
+For each primary action, verify the applicable states:
+
+- **Actionable:** the label predicts the result; enabled and disabled states are distinguishable without color alone.
+- **Pressed and focused:** feedback is immediate; keyboard focus is visible; focus order follows the task.
+- **Processing:** status remains near the initiating control; duplicate submission is prevented without trapping the user.
+- **Progress:** measurable work uses a determinate value; unmeasurable work uses an indeterminate indicator and an accessible status message.
+- **Long or stalled work:** expectations are updated; a reason and next step are shown; cancellation is available only when it is safe and real.
+- **Success:** completion is perceivable visually and programmatically; the interface moves focus only when that helps the next task.
+- **Empty:** the state explains what is absent and offers a relevant next action rather than presenting a dead end.
+- **Failure:** input and completed work are retained; the message says what happened in actionable language; retry, undo, or back is available where meaningful.
+- **Offline:** unavailable behavior is explicit; queued or local work is not implied unless it is actually preserved.
+- **Permission denied:** explain the missing capability and provide a safe route to settings, an alternative, or back.
+- **Destructive:** communicate scope and consequence; prefer undo for reversible actions and use explicit confirmation for material irreversible harm.
+- **Recovered:** clear stale errors and busy states; restore a coherent focus position; avoid re-running the action unexpectedly.
+
+## Accessibility and adaptation
+
+- Use semantic HTML or native controls before recreating their behavior.
+- Verify the full primary flow with keyboard only, including visible focus and escape from overlays.
+- Verify names, roles, values, errors, progress, and status announcements with a screen reader.
+- Test touch, pointer, keyboard, and relevant alternate input; do not require hover, precise pointing, or a single gesture.
+- Test narrow and wide layouts, zoom or text resizing, longer translated copy, and dynamic content.
+- Do not encode meaning with color, motion, shape, or sound alone.
+- Respect Reduced Motion and provide equivalent state information without animation.
+- Keep time limits adjustable or avoid them unless the task itself requires one.
+- On the web, apply the existing design system and WCAG 2.2; do not imitate iOS merely because these principles originated in Apple HIG.
+
+## Async-action spot check
+
+For a save, upload, generation, import, or other asynchronous action, confirm:
+
+1. Press or focus feedback is immediate.
+2. The busy state names the ongoing action and blocks accidental duplicates.
+3. Progress type matches what the system can measure.
+4. Cancellation has defined semantics and leaves data consistent.
+5. Success and failure are announced in the same task context.
+6. A failure keeps user input and provides a tested recovery path.
+
+## Official sources
+
+- Apple Human Interface Guidelines — Design principles: https://developer.apple.com/design/human-interface-guidelines/design-principles
+- Apple Human Interface Guidelines — Buttons: https://developer.apple.com/design/human-interface-guidelines/buttons
+- Apple Human Interface Guidelines — Loading: https://developer.apple.com/design/human-interface-guidelines/loading
+- Apple Human Interface Guidelines — Progress indicators: https://developer.apple.com/design/human-interface-guidelines/progress-indicators
+- Apple Human Interface Guidelines — Feedback: https://developer.apple.com/design/human-interface-guidelines/feedback
+- Apple Human Interface Guidelines — Motion: https://developer.apple.com/design/human-interface-guidelines/motion
+- Apple Human Interface Guidelines — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility
+- W3C Web Content Accessibility Guidelines 2.2: https://www.w3.org/TR/WCAG22/