kiokuko 1.0.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "kiokuko",
+  "version": "1.0.0",
+  "description": "Model-agnostic external memory for AI coding agents",
+  "type": "module",
+  "bin": {
+    "kiokuko": "dist/bin/kiokuko.js"
+  },
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "migrations/",
+    "skills/",
+    "docs/",
+    "templates/",
+    "README.md",
+    "README.ja.md",
+    "README.zh-CN.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean:dist": "node --input-type=module --eval \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\"",
+    "set-bin-permissions": "node --input-type=module --eval \"import { chmodSync } from 'node:fs'; chmodSync('dist/bin/kiokuko.js', 0o755);\"",
+    "build": "npm run clean:dist && tsc -p tsconfig.build.json && npm run set-bin-permissions",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node scripts/run-tests.mjs tests",
+    "test:unit": "node scripts/run-tests.mjs tests/unit",
+    "test:integration": "node scripts/run-tests.mjs tests/integration",
+    "test:sqlite-vec": "node --import tsx tests/ci/sqlite-vec-package-smoke.ts",
+    "test:global-install": "node tests/ci/global-install-smoke.mjs",
+    "test:evaluation": "npm run build && node scripts/run-retrieval-evaluation.mjs",
+    "test:benchmark": "npm run build && node scripts/run-retrieval-benchmark.mjs",
+    "sampledb:generate": "node --import tsx tests/fixtures/sample-database.ts tests/sampledb/kiokuko.sqlite3",
+    "test:sampledb": "npm run build && node --import tsx tests/ci/verify-sample-database.ts",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run pack:check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "^14.0.1",
+    "jsonc-parser": "^3.3.1",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "overrides": {
+    "adm-zip": "0.6.0",
+    "sharp": "0.35.4"
+  },
+  "peerDependencies": {
+    "@huggingface/hub": "2.16.1",
+    "@huggingface/transformers": "4.2.0",
+    "sqlite-vec": "0.1.9"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/hub": {
+      "optional": true
+    },
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "sqlite-vec": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@huggingface/hub": "2.16.1",
+    "@huggingface/transformers": "4.2.0",
+    "@types/node": "^24.0.0",
+    "@types/semver": "^7.8.0",
+    "sqlite-vec": "0.1.9",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2"
+  }
+}

package/skills/kiokuko-simple-work/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: kiokuko-simple-work
+description: Use for bounded, low-risk coding work with a clear target, or when the user explicitly asks for the simplest, shortest, minimal, YAGNI, or dependency-free solution. Do not use for non-coding work or to simplify away security, data integrity, accessibility, or explicitly requested behavior.
+license: MIT
+metadata:
+  argument-hint: "[lite|full|ultra]"
+  aka: Ponytail
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-simple-work -->
+
+# Kiokuko Simple Work
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+Active only for the current logical user request. Re-evaluate activation
+through `kiokuko-soul` for every new request. Default: **full**. Switch the
+current request with `/ponytail lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path (`# ponytail: global lock, per-account locks if throughput matters`).
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level     | What change                                                                                                                 |
+|-----------|-----------------------------------------------------------------------------------------------------------------------------|
+| **lite**  | Build what's asked, but name the lazier alternative in one line. User picks.                                                |
+| **full**  | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default.                                 |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lazy.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert for the current request.
+The level never carries into a new logical request without fresh SOUL routing.
+
+The shortest path to done is the right path.

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

@@ -0,0 +1,81 @@
+---
+name: kiokuko-single-purpose-functions
+description: Use whenever writing, modifying, reviewing, debugging, or refactoring code. Apply compact function and problem-shaping contracts, then route each function or task to one to three versioned expert fragments for its actual risks.
+---
+
+<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
+
+# Single-purpose function router
+
+## Outcome
+
+Create code whose functions each own one cohesive externally observable responsibility, with explicit concepts, representation boundaries, effects, failures, and focused verification across languages, frameworks, and repositories.
+
+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.
+
+## Universal core
+
+Apply these invariants to every created or changed function:
+
+1. State one contract: input, success, expected failures, effects, and observable result.
+2. Before choosing a storage, framework, transport, or UI representation, name the user-visible or domain concept, its input and output, and information that must remain private. Keep this proportional; representation-preserving mechanical changes do not need a separate design artifact.
+3. Give it one responsibility and one reason to change. Do not create meaningless micro-functions.
+4. Validate hostile input at the boundary; keep the private core constrained by types or validated values.
+5. Do not mutate caller-owned input unless mutation is the explicit API contract.
+6. Make domain decisions deterministic. Keep persistence, network, filesystem, process, clock, randomness, UI, and logging effects explicit.
+7. Return or throw failures intentionally. Do not silently swallow, partially succeed, or leak lower-layer accidents as the public contract.
+8. Add the smallest runnable test that proves success, the important failure, and the regression being changed.
+9. Preserve unrelated code and existing public behavior unless the task explicitly changes it.
+
+Small is not the objective. Cohesion is. Keep operations together when splitting them would hide sequencing, duplicate policy, or weaken a transaction.
+
+## MoE selection contract
+
+For each new or materially changed function, or for the smallest task that owns a cohesive 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.
+
+Do not make a new Skill per function. The function contract is the execution envelope; expert references identify the selected guidance. If two functions need materially different expert sets or reasons to change, record separate function contracts.
+
+For each task, record its code, UI, test, documentation, or operations scope.
+Code work requires code experts; interactive UI work requires code and UI
+experts. Select expertise from the actual risk, and record it in working plan
+or review notes:
+
+```text
+target -> responsibility -> expert IDs -> focused verifier
+```
+
+Do not load unselected fragments “just in case.” If repository evidence exposes a new risk, update the selection explicitly before consuming that fragment.
+
+## Expert index
+
+| 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) |
+| `code.modeling.v1` | problem shaping, public data design, domain vocabulary, or translation between storage, API, serialization, and UI representations | [problem-shaping-and-language.md](references/problem-shaping-and-language.md) |
+
+Typical selections:
+
+- pure calculation: `code.domain.v1`;
+- public response, DTO, or ViewModel design: `code.modeling.v1` + `code.boundary.v1`;
+- domain concept or state representation: `code.modeling.v1` + `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`.
+
+## Escalation references
+
+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 report
+
+Report the function or task 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.