kiokuko 1.0.0

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

@@ -0,0 +1,344 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# Single-purpose implementation patterns
+
+These patterns are repository- and language-agnostic contracts illustrated with TypeScript for concreteness. Translate them into the project’s language, framework, error model, persistence layer, and test tools. Reuse existing project helpers before creating substitutes.
+
+## 1. Hostile boundary, constrained private core
+
+An exported operation may accept unconstrained input when it is the real trust boundary. Validate once, create an owned value, then call a constrained helper.
+
+```ts
+interface ValidatedWindow {
+  readonly start: number;
+  readonly limit: number;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function parseWindow(value: unknown): ValidatedWindow {
+  if (!isPlainRecord(value)) throw new Error('window must be an object');
+  if (typeof value.start !== 'number' || !Number.isInteger(value.start) || value.start < 0) {
+    throw new Error('window start is invalid');
+  }
+  if (typeof value.limit !== 'number' || !Number.isInteger(value.limit)
+    || value.limit < 1 || value.limit > 100) {
+    throw new Error('window limit is invalid');
+  }
+  return { start: value.start, limit: value.limit };
+}
+
+function calculateEnd(window: ValidatedWindow): number {
+  return window.start + window.limit;
+}
+
+export function endOfWindow(value: unknown): number {
+  return calculateEnd(parseWindow(value));
+}
+```
+
+Use the project’s error type and validation library where available. Do not make `calculateEnd` accept `unknown` or repeat transport validation throughout the domain.
+
+## 2. Closed schema at a request boundary
+
+Use bounded schemas and reject unknown fields when the protocol is closed.
+
+```ts
+import * as z from 'zod/v4';
+
+const requestSchema = z.object({
+  requestId: z.string().trim().min(1).max(256),
+  paths: z.array(z.string().trim().min(1).max(1_024)).max(100),
+  limit: z.number().int().min(1).max(100).default(20),
+}).strict();
+```
+
+A schema is the boundary. Internal helpers should consume its validated output or a narrower domain value.
+
+## 3. Exact optional values
+
+Omit absent optional properties rather than assigning ambiguous placeholders.
+
+```ts
+interface Candidate {
+  readonly id: string;
+  readonly description?: string;
+}
+
+function candidate(id: string, description: string | undefined): Candidate {
+  return {
+    id,
+    ...(description === undefined ? {} : { description }),
+  };
+}
+```
+
+Use the equivalent convention in languages that distinguish missing, null, and empty values.
+
+## 4. Immutable transformation and mutation test
+
+```ts
+interface Profile {
+  readonly mode: 'build' | 'debug' | null;
+  readonly target: string | null;
+}
+
+function withTarget(profile: Profile, target: string): Profile {
+  return { ...profile, target: target.trim() };
+}
+```
+
+```ts
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+test('returns a new profile without mutating the input', () => {
+  const input = { mode: 'build' as const, target: null };
+  const before = structuredClone(input);
+
+  const result = withTarget(input, ' src/index.ts ');
+
+  assert.deepEqual(result, { mode: 'build', target: 'src/index.ts' });
+  assert.deepEqual(input, before);
+  assert.notEqual(result, input);
+});
+```
+
+## 5. Explicit variable dependencies
+
+Keep time and randomness out of pure ranking, hashing, transition, and validation functions.
+
+```ts
+interface Dependencies {
+  readonly now: () => string;
+  readonly createId: () => string;
+}
+
+interface CreatedRecord {
+  readonly id: string;
+  readonly createdAt: string;
+}
+
+function createRecord(dependencies: Dependencies): CreatedRecord {
+  return {
+    id: dependencies.createId(),
+    createdAt: dependencies.now(),
+  };
+}
+```
+
+Production composition supplies real dependencies; tests supply deterministic ones.
+
+## 6. Transaction-agnostic store, transaction-owning use case
+
+The store performs persistence. The service or use case owns the atomic operation.
+
+```ts
+interface Transaction {
+  execute(sql: string, parameters: readonly unknown[]): void;
+}
+
+interface NewItem {
+  readonly id: string;
+  readonly value: string;
+}
+
+function insertItem(transaction: Transaction, item: NewItem): void {
+  transaction.execute(
+    'INSERT INTO items (id, value) VALUES (?, ?)',
+    [item.id, item.value],
+  );
+}
+
+function createItem(
+  runTransaction: (operation: (transaction: Transaction) => void) => void,
+  item: NewItem,
+): void {
+  runTransaction((transaction) => {
+    insertItem(transaction, item);
+    transaction.execute(
+      'INSERT INTO audit_events (event_type, target_id) VALUES (?, ?)',
+      ['item_created', item.id],
+    );
+  });
+}
+```
+
+Do not let `insertItem` start its own transaction if it must compose with other writes. Do not call a provider or perform unrelated slow I/O inside the transaction.
+
+## 7. Validate stored data before domain use
+
+Driver types and generated models are not always runtime proof, especially across migrations or external storage.
+
+```ts
+interface StoredItem {
+  readonly id: string;
+  readonly revision: number;
+}
+
+function parseStoredItem(row: Record<string, unknown> | undefined): StoredItem {
+  if (row === undefined) throw new Error('Item not found');
+  if (typeof row.id !== 'string'
+    || typeof row.revision !== 'number'
+    || !Number.isInteger(row.revision)
+    || row.revision < 1) {
+    throw new Error('Stored item is invalid');
+  }
+  return { id: row.id, revision: row.revision };
+}
+```
+
+Do not include malformed row contents in a public error.
+
+## 8. Safe public error mapping
+
+Public messages should be stable. Keep only allowlisted bounded details.
+
+```ts
+interface PublicFailure {
+  readonly code: 'busy' | 'invalid' | 'internal';
+  readonly message: string;
+  readonly retryAfterSeconds?: number;
+}
+
+function publicFailure(error: unknown): PublicFailure {
+  if (isBusyFailure(error)) {
+    return {
+      code: 'busy',
+      message: 'Service is busy',
+      retryAfterSeconds: clampRetryDelay(error.retryAfterSeconds),
+    };
+  }
+  if (isValidationFailure(error)) {
+    return { code: 'invalid', message: 'Request is invalid' };
+  }
+  return { code: 'internal', message: 'Internal error' };
+}
+```
+
+Do not copy unknown exception messages, submitted values, credentials, URLs with secret query parameters, or provider bodies into public output.
+
+## 9. Preserve operation and cleanup failures
+
+When both fail, retain both failures without replacing the primary one.
+
+```ts
+async function useResource<T>(
+  open: () => Promise<{ close: () => Promise<void> }>,
+  operation: (resource: { close: () => Promise<void> }) => Promise<T>,
+): Promise<T> {
+  const resource = await open();
+  let operationFailure: unknown;
+  let result: { value: T } | undefined;
+
+  try {
+    result = { value: await operation(resource) };
+  } catch (error) {
+    operationFailure = error;
+  }
+
+  try {
+    await resource.close();
+  } catch (cleanupFailure) {
+    if (operationFailure !== undefined) {
+      throw new AggregateError(
+        [operationFailure, cleanupFailure],
+        'Resource operation and cleanup failed',
+      );
+    }
+    throw cleanupFailure;
+  }
+
+  if (operationFailure !== undefined) throw operationFailure;
+  if (result === undefined) throw new Error('Resource operation produced no result');
+  return result.value;
+}
+```
+
+Use the language’s structured multi-error or error-chaining mechanism where possible.
+
+## 10. Classify failures by structured fields
+
+Prefer error types, codes, status values, or discriminated variants over message matching.
+
+```ts
+interface RetryableFailure extends Error {
+  readonly code: 'temporarily_unavailable';
+  readonly retryAfterSeconds: number;
+}
+
+function isRetryableFailure(error: unknown): error is RetryableFailure {
+  return error instanceof Error
+    && 'code' in error
+    && error.code === 'temporarily_unavailable'
+    && 'retryAfterSeconds' in error
+    && typeof error.retryAfterSeconds === 'number';
+}
+```
+
+Do not treat an unrelated exception containing “busy” or “timeout” as retryable.
+
+## 11. Immutable replay identity
+
+Bind every field that changes the meaning of an idempotent operation.
+
+```ts
+interface BoundRequest {
+  readonly operation: string;
+  readonly subjectId: string;
+  readonly expectedRevision: number;
+  readonly mode: 'validate' | 'apply';
+}
+
+function replayMatches(left: BoundRequest, right: BoundRequest): boolean {
+  return left.operation === right.operation
+    && left.subjectId === right.subjectId
+    && left.expectedRevision === right.expectedRevision
+    && left.mode === right.mode;
+}
+```
+
+Reusing an identity with changed bound input is a conflict, not a second mutation.
+
+## 12. Compare-and-swap filesystem changes
+
+For managed files, the contract may include expected content, expected file identity, expected parent-directory identity, alternate paths that must remain absent, restrictive mode, reverse-order rollback, and explicit ambiguous-cleanup failure.
+
+Use the project’s atomic compare-and-swap helpers where available. Plain write, rename, or delete calls are insufficient when concurrent changes or independently owned files must be protected.
+
+## 13. Test secret non-echo
+
+```ts
+test('rejects invalid input without echoing it', () => {
+  const submitted = 'secret-sentinel-value';
+
+  assert.throws(
+    () => parseWindow({ start: submitted, limit: 10 }),
+    (error: unknown) => {
+      assert.ok(error instanceof Error);
+      assert.equal(error.message.includes(submitted), false);
+      return true;
+    },
+  );
+});
+```
+
+## 14. Test deterministic output
+
+For canonical order, hashes, manifests, and rankings, construct semantically equivalent inputs with different insertion order and assert identical output.
+
+## 15. Verification sequence
+
+Run commands that actually exist in the repository:
+
+1. the narrowest test covering the changed contract;
+2. relevant integration tests;
+3. type or static checks;
+4. the broader test suite when shared behavior changed;
+5. build and package checks when distribution changed.
+
+Report skipped commands and failures exactly. Do not invent a lint, formatter, build, or test command that the project does not define.

package/skills/kiokuko-single-purpose-functions/references/problem-shaping-and-language.md

@@ -0,0 +1,84 @@
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# `code.modeling.v1` — problem shaping and representation design
+
+Select this expert when a contract defines a public data shape, introduces
+domain vocabulary, or translates between human intent, domain values, storage,
+transport, serialization, and consumer or UI representations.
+
+Do not select it for a representation-preserving mechanical change merely
+because the work modifies code. This expert does not require Lisp syntax, a
+Lisp runtime, macros, a DSL, or a separate design document.
+
+## Contract
+
+Turn the human problem into named concepts and explicit transformations before
+letting a database schema, ORM model, framework object, wire format, or UI state
+become the accidental product contract.
+
+For a non-trivial selected contract, make these items explicit in the working
+plan or review notes, without creating a new artifact unless the user asks:
+
+1. **Intent:** identify the actor, their goal, the observable result, and data
+   that must remain hidden or out of scope.
+2. **Representation map:** list only the layers that actually exist, using this
+   shape as a guide: `human intent -> domain concept -> storage/input shape ->
+   public shape -> consumer shape`.
+3. **Consumer-first shape:** define what the external caller or next layer
+   needs before choosing how to retrieve, serialize, or display it.
+4. **Named transformations:** use names that reveal the concept and direction,
+   such as `rowToArticle`, `articleToApiResponse`, or
+   `apiResponseToArticleViewState`.
+5. **Loss and failure policy:** state what is omitted, normalized, derived,
+   rejected, or intentionally impossible to reconstruct at each boundary.
+6. **Abstraction threshold:** start with direct values and cohesive functions.
+   Extract shared vocabulary after meaningful repetition appears; introduce a
+   DSL, macro, code generator, or generic framework only when the stable pattern
+   and its benefit are evidenced.
+
+## Representation boundaries
+
+- Storage shapes serve persistence and query needs; they are not automatically
+  domain or public shapes.
+- Domain shapes name legal concepts and invariants without inheriting transport
+  or framework accidents.
+- Public API and event shapes are compatibility and disclosure contracts. Build
+  them from allowlisted fields rather than serializing internal objects.
+- Consumer and UI shapes serve rendering and interaction state. Do not force
+  components to understand database relations or transport-only nullability.
+- Use distinct shapes for distinct audiences when list, detail, administrative,
+  and public views carry different concepts or disclosure rules.
+
+Pair this expert with `code.boundary.v1` when the transformation crosses an
+untrusted or public boundary. Pair it with `code.domain.v1` when the named shape
+owns business states, invariants, or transitions. Stay within the three-expert
+limit and select only risks owned by the same cohesive contract.
+
+## Failure modes
+
+- Returning an ORM entity, database row, or framework object directly as a
+  public response.
+- Treating storage column names or relations as a stable external API by
+  accident.
+- Reusing one DTO for audiences whose visibility or interaction needs differ.
+- Mixing server response state, domain state, and UI state in one mutable type.
+- Adding wrappers that rename syntax but create no semantic contract.
+- Generalizing one instance into a DSL or metaprogramming layer before stable
+  repetition exists.
+
+## Focused verification
+
+Test the observable shape and transformation rather than the current storage or
+framework implementation:
+
+- assert the exact allowed public fields and the absence of internal or secret
+  fields;
+- cover missing, optional, normalized, derived, and rejected values;
+- verify intentional information loss or round-trip behavior where relevant;
+- prove that a storage-layout or transport-fixture change does not silently
+  redefine the public concept;
+- test audience-specific shapes independently when their contracts differ.
+
+This guidance adapts the problem-shaping philosophy described in
+<https://zenn.dev/circleback/articles/what-is-lisp>; it applies that philosophy
+across programming languages and does not reproduce the article text.

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/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.