@zyaiting/keelson 0.4.0

package/registry/models.json

@@ -0,0 +1,118 @@
+{
+  "version": 1,
+  "updated": "2026-09-19",
+  "note": "Tiers map to floating aliases, never to dated model IDs. Update this file only when a platform gains or retires a model family.",
+  "tiers": [
+    "light",
+    "standard",
+    "deep"
+  ],
+  "platforms": {
+    "claude": {
+      "label": "Claude Code",
+      "rank": [
+        "haiku",
+        "sonnet",
+        "opus",
+        "fable"
+      ],
+      "tiers": {
+        "light": "haiku",
+        "standard": "sonnet",
+        "deep": "opus"
+      },
+      "subagents": true,
+      "notes": "Agent tool accepts family aliases; each alias floats to the newest model of that family. `fable` is used for deep when the host exposes it."
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "rank": [
+        "mini",
+        "default",
+        "high"
+      ],
+      "tiers": {},
+      "subagents": false,
+      "notes": "Model names vary by release. Run `keelson models rank <name> <tier>` once, or `keelson models --refresh` with OPENAI_API_KEY to infer from the provider catalogue."
+    },
+    "opencode": {
+      "label": "OpenCode",
+      "rank": [],
+      "tiers": {},
+      "subagents": true,
+      "notes": "OpenCode provides built-in subagents; model identifiers are provider-qualified and project-specific, so Keelson does not guess a tier mapping."
+    },
+    "pi": {
+      "label": "Pi coding agent",
+      "rank": [],
+      "tiers": {},
+      "subagents": false,
+      "notes": "Pi model selection depends on the configured provider. Keep effort tiers semantic unless the user supplies aliases."
+    },
+    "gemini": {
+      "label": "Gemini CLI",
+      "rank": [
+        "flash-lite",
+        "flash",
+        "pro"
+      ],
+      "tiers": {
+        "light": "flash-lite",
+        "standard": "flash",
+        "deep": "pro"
+      },
+      "subagents": false
+    },
+    "kiro": {
+      "label": "Kiro CLI",
+      "rank": [],
+      "tiers": {},
+      "subagents": true,
+      "notes": "Kiro CLI supports parallel subagents. Model availability can vary by account and release, so aliases are user-configured."
+    },
+    "codebuddy": {
+      "label": "CodeBuddy CLI",
+      "rank": [],
+      "tiers": {},
+      "subagents": true,
+      "notes": "CodeBuddy exposes an Agent subagent tool and host-specific model aliases. Keelson does not persist release-specific model IDs."
+    }
+  },
+  "providers": {
+    "anthropic": {
+      "env": "ANTHROPIC_API_KEY",
+      "catalogue": "https://api.anthropic.com/v1/models",
+      "families": [
+        "haiku",
+        "sonnet",
+        "opus",
+        "fable"
+      ]
+    },
+    "openai": {
+      "env": "OPENAI_API_KEY",
+      "catalogue": "https://api.openai.com/v1/models",
+      "families": [
+        "nano",
+        "mini",
+        "",
+        "pro"
+      ]
+    },
+    "google": {
+      "env": "GEMINI_API_KEY",
+      "catalogue": null,
+      "families": [
+        "flash-lite",
+        "flash",
+        "pro"
+      ]
+    }
+  },
+  "dated_id_patterns": [
+    "claude-[a-z0-9.-]+-\\d{8}",
+    "gpt-[a-z0-9.-]+-\\d{4}-\\d{2}-\\d{2}",
+    "gemini-[a-z0-9.-]+-\\d{3,}",
+    "o[0-9]-[a-z-]+-\\d{4}-\\d{2}-\\d{2}"
+  ]
+}

package/registry/platforms.json

@@ -0,0 +1,92 @@
+{
+  "version": 2,
+  "updated": "2026-09-20",
+  "note": "Adapters describe generated discovery paths, not a promise of live end-to-end host parity. Codex session identity has been exercised locally. Other hosts have adapter contract tests; hooks are supported only where listed. Native session identity sources include CODEX_THREAD_ID, Claude hooks, Pi environment and explicit KEELSON_SESSION_ID. No source means an honest degraded state. Default installation is lightweight; --vendor explicitly copies package guidance.",
+  "platforms": {
+    "claude": {
+      "label": "Claude Code",
+      "bin": "claude",
+      "instructions": "CLAUDE.md",
+      "skillsDir": ".claude/skills",
+      "hooks": true,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "native",
+      "sessionAdapter": "claude-hooks"
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "bin": "codex",
+      "instructions": "AGENTS.md",
+      "skillsDir": ".agents/skills",
+      "hooks": false,
+      "confidence": "verified",
+      "support": "first-class",
+      "sessionFocus": "native",
+      "sessionAdapter": "codex-thread-env"
+    },
+    "opencode": {
+      "label": "OpenCode",
+      "bin": "opencode",
+      "instructions": "AGENTS.md",
+      "skillsDir": ".agents/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "degraded"
+    },
+    "pi": {
+      "label": "Pi coding agent",
+      "bin": "pi",
+      "instructions": "AGENTS.md",
+      "skillsDir": ".agents/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "native",
+      "sessionAdapter": "pi-env"
+    },
+    "gemini": {
+      "label": "Gemini CLI",
+      "bin": "gemini",
+      "instructions": "GEMINI.md",
+      "skillsDir": ".agents/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "degraded"
+    },
+    "kiro": {
+      "label": "Kiro CLI",
+      "bin": "kiro-cli",
+      "instructions": "AGENTS.md",
+      "skillsDir": ".kiro/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "degraded"
+    },
+    "codebuddy": {
+      "label": "CodeBuddy CLI",
+      "bin": "codebuddy",
+      "instructions": "CODEBUDDY.md",
+      "skillsDir": ".codebuddy/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "first-class",
+      "sessionFocus": "native",
+      "sessionAdapter": "codebuddy-hooks"
+    },
+    "agents": {
+      "label": "Portable AGENTS.md + Agent Skills",
+      "bin": null,
+      "instructions": "AGENTS.md",
+      "skillsDir": ".agents/skills",
+      "hooks": false,
+      "confidence": "documented",
+      "support": "portable",
+      "examples": "Any host that reads AGENTS.md and/or the open Agent Skills `.agents/skills/` convention",
+      "sessionFocus": "degraded"
+    }
+  }
+}

package/skills/keelson/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: keelson
+description: Engineering control plane for coding work in repositories with a .keelson/ directory. Use for exploring an idea, changing code, fixing/debugging, frontend design and UX review, continuing prior work, or improving recurring engineering failures. Keeps conversation sessions separate from durable work items so users can keep asking questions without having to announce when a task starts or ends.
+---
+
+# Keelson
+
+Read the installed workflow with `keelson guide workflow`; load each named reference with `keelson guide <name>` (omit `.md`). Keelson constrains **state transitions and evidence**, not implementation taste. User and project instructions win.
+
+## Classify the conversation, not the lifecycle
+
+| Intent | Typical request | Start with |
+|---|---|---|
+| **Explore** | compare, explain, “what should we do?”, “stress-test this” | `discover.md` + `interview.md`; read-only until a modification is requested |
+| **Change** | build, add, refactor, migrate, “also change…” | `shape.md` → `context.md`; load `model.md` for boundary/language questions, `engineer.md` for non-obvious technical choices, `design-lenses.md` only for triggered risks; spec-sized work adds `plan.md` |
+| **Fix** | bug, failing test, unexpected behavior | `debug.md`, then `verify.md` |
+| **Resume** | continue, pick this back up | `keelson focus --auto` + current context; use `handoff.md` only when a real ownership/machine transfer exists |
+| **Improve** | repeated mistake, harness/rule/process problem, retro | `harness.md` + `reconcile.md` |
+
+Completion is **not** an intent and never depends on the user saying “done”. It is a state transition: when the focused change has satisfied acceptance, no blocking questions/assumptions, required rollout, and fresh verification on the current tree, it becomes `ready`. Run the Finish path (`verify.md` → `land.md` → `reconcile.md`) automatically before claiming completion.
+
+- For interface design, review, interaction or responsive work, load `frontend.md`; use `keelson design` for focused action briefs. Keep browser observations distinct from code checks.
+
+## Operating rules
+
+- A conversation/session is only a focus pointer. Ending a window, going idle, or continuing to ask questions MUST NOT mark a change complete.
+- `keelson new` binds the new change to the current session when session identity is available. Same-goal follow-ups stay on that change; an independent requested outcome gets a new change and focus moves.
+- On Resume, use `keelson focus --auto`; branch match or a sole active change may be suggested. Never silently bind an ambiguous session.
+- If `NOW.md` says “First contact”, infer and confirm `INTENT.md`; do not inventory the whole repository into specs/rules.
+- Non-trivial modifying work starts from current context; shared modules get `keelson impact <files>`.
+- Ask only at the decision frontier. Run the triggered blindspot pass, then use `interview.md`: up to three independent ready owner-owned decisions per round, skipping settled answers, concrete scenario/options, recommended default, and `not sure` as a valid route. Never ask what repo evidence, an experiment, or agent engineering judgment can settle.
+- Route non-obvious mechanisms/architecture through `engineer.md`: reduce to facts, outcome, constraints, and invariants; state a falsifiable hypothesis; use the cheapest experiment/ablation that can discriminate; complexity must earn its keep with evidence.
+- Size only the work: trivial = direct edit; quick = lightweight change; spec = acceptance + behavior delta + plan within existing user authorization; clarify only unresolved owner choices.
+- Artifacts are information containers, not ceremony. Do not create empty roadmap/glossary/rule/task/ledger/handoff/spec files.
+- `tasks.md` is an execution plan, not completion authority. Unchecked plan items never override satisfied acceptance + fresh evidence; reconcile or remove stale tasks when the implementation path changes.
+- Knowledge maintenance is internal. During RECONCILE, automatically rewrite/split/dedupe pressured durable docs and let `land` auto-shard large specs; never ask the owner to maintain Keelson unless a product-semantic decision is required.
+- Keep **code reality**, **confirmed truth**, and **planned change** distinct. Open questions block only dependent slices.
+- Fresh structured `keelson check --record` evidence (review commands and use `--trust` on first execution) is required for completion claims. Never weaken acceptance to make a check pass.
+- A `ready` change should be landed without waiting for a special user phrase. If landing still needs an owner decision, stop on that decision only.
+- `handoff.md` is for real transfer across people/machines or deliberate ownership change; ordinary session continuity comes from durable change artifacts plus private per-machine session state.
+- Repeated failures graduate to the narrowest durable control: spec → scoped rule → executable fitness check; remove redundant prose afterward.
+- Use `light | standard | deep`; never persist dated model IDs.
+
+Users normally need only `init`, `status`, `doctor`, `update`, and `uninstall`; the agent uses the rest.

package/skills/keelson/references/build.md

@@ -0,0 +1,61 @@
+# Building
+
+Execute `tasks.md` slice by slice. You choose how; these notes cover the parts that are easy to get wrong.
+
+## Rulings, not stalls
+<!-- keelson: id=build.rulings | without: agent parks the session on questions the plan already answers; or decides silently and the reasoning is lost | sunset: never -->
+
+The plan is the argument; the specs and `INTENT.md` are the authority; your judgment settles what neither answers, within `INTENT.md → Authorizations`. When you hit ambiguity or a plan defect inside your authorization, decide, record it, and keep going:
+
+```markdown
+### Ruling: ack semantics
+At-least-once with idempotent consumers. Exactly-once would need a broker feature we do not run. Cost if wrong: duplicate side effects in `notify`, bounded by the idempotency key.
+```
+
+Outside your authorization, it is an open question: add it to `change.md → Open questions` with what it blocks, and build the slices it does not block. Four things stop you outright: an irreversible or destructive operation; a security-sensitive action; a side effect outside the working tree that convention says to ask about (merge, push to a shared branch, publish, external calls); a plan so broken every path forward is a guess.
+
+## Subagents by effort tier
+<!-- keelson: id=build.dispatch | without: one context does everything, quality drops as it fills, and cost is flat regardless of task difficulty | sunset: when the host has no subagent tool, this section is inert -->
+
+When tasks are mostly independent and the host offers subagents, dispatch a fresh subagent per task with the model resolved from its effort tier: `keelson models --resolve <tier>` prints the alias for this platform (or map tiers onto the aliases your subagent tool exposes, in ascending capability order). Give the subagent the task text, the matched rules, the relevant spec, and the verification command. Never hand it your whole conversation.
+
+More agents are not a linear throughput multiplier. When tasks share mutable state or the same contract, or need constant synchronization, coordination and merge cost can exceed the parallelism benefit; keep them sequential. Parallelize only when boundaries are clear, outputs are independently verifiable, and the merge contract is explicit. Do not try to rescue tightly coupled work by simply adding agents.
+
+After each task, a reviewer subagent (tier ≥ `standard`, never below the implementer) checks the diff against the spec and the rules. Record both in the ledger:
+
+```markdown
+### Dispatch: task 2 → standard (sonnet)
+Result: pass
+Implemented paged query; reviewer accepted. Verify `npm test -- orders.repo` exit 0.
+```
+
+The first line of a `Dispatch:` body is `Result: pass` or `Result: fail`; `keelson retro` counts only that line, never words in the prose.
+
+If the task's verification fails twice at a tier, escalate one tier and re-dispatch; log it:
+
+```markdown
+### Escalate: task 2 light → standard
+Two failures on boundary handling; light-tier output ignored the empty-page case.
+```
+
+Escalation is for work that came back wrong. It is not for dispatches that never ran: a rate limit, a timeout, or a tool error is retried once at the same tier after a short pause, then the task is done inline by you and noted (`### Note: task 3 inline after two dispatch errors`). `deep` is the top tier; nothing escalates above it, and a `deep` verification failure stops and asks. Tightly coupled tasks, or no subagent tool: run inline yourself, still one task at a time, still ledgered.
+
+## Parallel work
+<!-- keelson: id=build.parallel | without: two writers on one branch overwrite each other, or two changes implement the same contract two ways | sunset: never -->
+
+When more than one writer (person or agent) works at once, each change gets its own branch or worktree (`keelson new --worktree`). Shared interfaces are aligned before either side implements them: agree the contract in the delta spec, land or reference it, then build. `keelson status` warns when two active changes touch the same capability or the same declared paths; treat that as "talk first", not as a lock. A file on disk is not a distributed lock and a branch does not remove semantic conflicts; cross-machine claiming and merge control belong to the tracker, pull requests, and CI. After integrating someone else's change into yours, re-run verification; the old evidence is stale by definition.
+
+When the other owner cannot be reached (an unattended run, a colleague offline), do not wait and do not pretend the overlap is absent: keep your delta to the shared requirement as small as the change allows, record the overlap as a `### Note:` in your ledger and a line in `NOW.md`, and say it in your write-back and completion report. `keelson land` names the overlapping changes when you land; their landing will stop at the drift gate until their owner re-reads the merged spec.
+
+## Keep the artifacts true while you work
+<!-- keelson: id=build.update-artifacts | without: tasks.md and change.md describe the plan, not what happened; the next session trusts stale text | sunset: never -->
+
+Tick tasks as they are verified, not as they are written. Tick acceptance items when their check has run. When the design changes mid-build, edit `change.md` and, if behaviour changed, the delta spec. Nothing is locked; the only rule is that the files reflect reality at every commit. If you stop before the change is done, `keelson handoff <name>` and fill it in (see `handoff.md`).
+
+<!-- guided -->
+## Test-first when behaviour is specified
+Where a scenario exists in the delta spec, write the failing test from the scenario first, watch it fail, implement, watch it pass. Where no scenario exists, judge whether a test is the cheapest evidence. Visual exploration and unknown APIs may start with a small prototype instead.
+
+## Narration
+Between tool calls, at most one short line. The ledger and tool output carry the record.
+<!-- /guided -->

package/skills/keelson/references/context.md

@@ -0,0 +1,34 @@
+# Context and impact
+
+Project material grows with the project; what you read per task must not grow with the whole history. Know where to look first, then open only what this change needs.
+
+## Three layers
+<!-- keelson: id=context.layers | without: every session reads everything or nothing; conventions are either flooded or missed | sunset: never -->
+
+1. **Stable entry** — the resident block, `INTENT.md`, `ROADMAP.md → Now`, and the rules routed by `**`. Always read; kept short on purpose.
+2. **Task material** — the active `change.md`, the specs of the capabilities it names, the rules matched by the paths you will touch, the tests that cover them, and any `refs` document the spec links to. `keelson context --paths <files>` prints most of this.
+3. **On demand** — callers, other entry points, neighbouring modules, past changes in git history. Open when a question arises, not up front.
+
+Never demote an always-on constraint because it is rarely relevant. Security and compatibility rules under `**` are read every time; that is the point of `**`.
+
+## Impact is analysed, not looked up
+<!-- keelson: id=context.impact | without: the agent treats the rules index and the diff as the whole blast radius and misses the caller outside the directory | sunset: never -->
+
+`keelson impact <files>` lists importers by name, specs whose text or path matches, rules that apply, and active changes that declare the same paths or capabilities. That is navigation. Before you edit a shared module, answer by reading:
+
+- Who calls this, including dynamic entry points the grep cannot see: CLI commands, jobs, routes, event handlers, templates?
+- Is there another way in to the same behaviour (a download API next to the page, a batch job next to the request handler)?
+- Which data constraints, permission rules, or compatibility promises depend on it? Check the spec's `Decisions`.
+- Does an active change of someone else touch the same contract? `keelson status` shows shared contracts.
+
+Write the answer into `change.md → Impact`. An Impact section that only lists the files in the diff is not an analysis.
+
+## Budget
+<!-- keelson: id=context.budget | without: when context runs short the agent silently drops constraints it already read, or guesses instead of reading | sunset: never -->
+
+When the material for a change does not fit, do not summarise constraints into something looser. Narrow the slice, or keep reading on demand and say what you have not checked. `NOW.md → Blocked / uncertain` is the place for "not yet checked: …".
+
+<!-- guided -->
+## Reading order for a spec change
+`INTENT.md` → `ROADMAP.md → Now` → `change.md` → the capability specs it names → matched rules → tests for those capabilities → `keelson impact` on the files you will touch → the callers it found → anything a spec links under `refs`.
+<!-- /guided -->

package/skills/keelson/references/debug.md

@@ -0,0 +1,46 @@
+# Debugging
+
+A fix without a known cause is a guess that happened to pass. This reference exists so the cause is found, named, and fed back into the project.
+
+
+For interface work, load `frontend.md`; visual and interaction acceptance follow `frontend-review.md` and `frontend-delivery.md`.
+
+## Reproduce, then locate, then fix
+<!-- keelson: id=debug.reproduce-first | without: agent edits code on a hypothesis; symptom moves, cause stays, the bug returns under another name | sunset: when retro shows guessed-fix = 0 across the last 20 root-cause entries -->
+
+1. Read the full error and stack. It usually names the line.
+2. Reproduce deterministically: a failing test, a script, or exact steps. If you cannot reproduce it, you cannot know it is fixed.
+3. Locate: where does observed behaviour first diverge from expected? Add logging or assertions at the boundaries rather than reading everything.
+4. Form one hypothesis, test it with the smallest change, and only then write the fix.
+5. Run the reproduction again; it must pass. Keep the negative check: with the fix reverted, the regression test fails. Then `keelson check --record`.
+
+If three hypotheses in a row fail, stop and re-read the problem from the top; you are probably in the wrong layer.
+
+## Name the root cause
+<!-- keelson: id=debug.category | without: bugs are fixed one at a time and the pattern behind them is never seen | sunset: never -->
+
+Append to the ledger of the active change (or create a quick change for the fix):
+
+```markdown
+### Root cause: implicit-assumption
+Callback handler assumed exactly one delivery; broker guarantees at-least-once.
+Fix: idempotency key on `notify`. Prevention: rule in `rules/services.md`.
+```
+
+Categories, one per entry:
+
+| category | meaning |
+|---|---|
+| `missing-rule` | no convention said how to do this |
+| `cross-layer` | the contract between two layers was unclear |
+| `propagation` | one place changed, dependants were missed |
+| `test-gap` | units passed, integration failed |
+| `implicit-assumption` | code relied on something undocumented |
+| `guessed-fix` | an earlier fix addressed the symptom, not the cause |
+
+If the category is `missing-rule` or `cross-layer`, propose the rule or the spec requirement that would have prevented it, and add it while the context is fresh.
+
+<!-- guided -->
+## When the fix is not obvious
+Ask what changed recently (`git log -p` on the failing area), what the data looked like, and whether the failure is in your code or in an assumption about a dependency. Each of these is a distinct layer; pick the layer before the line.
+<!-- /guided -->

package/skills/keelson/references/design-lenses.md

@@ -0,0 +1,78 @@
+# Risk-triggered design lenses
+
+These are **internal engineering lenses, not an architecture questionnaire**. Apply only the lenses triggered by the current change. Read the repository and existing contracts first; route what you find into defaults, experiments, acceptance, checks, or a single owner decision.
+
+
+For interface work, load `frontend.md`; visual and interaction acceptance follow `frontend-review.md` and `frontend-delivery.md`.
+
+## Trigger, inspect, route
+<!-- keelson: id=lenses.triggered | without: every feature gets a giant checklist, while important cross-domain risks still slip through because the list is treated mechanically | sunset: never -->
+
+| Lens | Trigger examples | Inspect before asking | Prefer to produce |
+|---|---|---|---|
+| User + domain | new workflow, ambiguous nouns, multiple actors | actor/job, current workflow, vocabulary, ownership boundary | scenario/non-goal; glossary only if load-bearing |
+| Data + integrity | persisted state, schema, import/export, delete, money | source of truth, invariants, lifecycle, retention, migration, audit/reconciliation | requirement + migration/rollback/reconciliation evidence |
+| Security + privacy | auth, permissions, secrets, PII, uploads, untrusted input/tools | assets, trust boundaries, least privilege, abuse paths, validation | negative acceptance + security check |
+| Concurrency + async | queues, webhooks, workers, realtime, multi-writer | duplicates, ordering, idempotency, retry, timeout, cancellation, partial failure | duplicate/out-of-order/retry/failure tests |
+| API + compatibility | public API, event/schema/config/storage format | consumers, versioning, breaking definition, deprecation, rollout/rollback | compatibility contract + rollout evidence |
+| Reliability + operations | error handling, cleanup/resource lifetime, critical path, background process, external dependency | full failure path, recovery, observer-visible state, observability, safe degradation | adversarial regression + recovery check; operational pointer when relevant |
+| Performance + cost | explicit latency/throughput/volume/cost target, measured hot path | workload, SLO, baseline, growth assumption, resource ceiling | measurement/load/cost check; no speculative cache |
+| Interface + accessibility | UI, form, navigation, interactive workflow | primary task, error/recovery, keyboard/focus, comprehension, destructive action | usability/accessibility acceptance |
+| AI + nondeterminism | LLM, agent, RAG, model/tool call | eval cases, fallback, data boundary, prompt/tool injection, authorization, reproducibility | eval set + safety/fallback acceptance |
+
+A trigger means “inspect this dimension”, **not** “ask every question in this row”.
+
+## Make failure contracts executable before the fix
+<!-- keelson: id=lenses.failure-contract | without: an error-handling fix covers the first failure but a later finalizer or observer still discards errors or exposes corrupted state | sunset: never -->
+
+For error-handling or resource-lifetime changes, trace the entire call path before editing, including nested cleanup, finalizers, notifications, and the final caller. In the existing plan or test notes, briefly map each phase to: what can fail, what must still run, what state observers must see, and which errors must reach the caller. Derive these obligations from the request and existing contracts; distinguish an explicit requirement from an additional robustness probe.
+
+Turn the highest-risk combination into a failing regression **before** the implementation: inject distinct errors into multiple phases of one execution, including the last applicable observer, and exercise a nested or already-active resource when supported. Assert the required final state and the propagated errors' identities, multiplicity, and order when contractual; assert observer-visible state at the time the observer runs. A passing single-error test does not establish the combined-failure contract. Keep this focused on the affected lifetime rather than inventing a generic framework or an exhaustive fault matrix.
+
+## Prefer simple, reversible architecture
+<!-- keelson: id=lenses.simplicity | without: the agent designs for hypothetical scale, introduces abstractions before pressure exists, or treats every future possibility as a current requirement | sunset: never -->
+
+Use the simplest design that satisfies the current contract and leaves a credible path to change. Before adding a new service, queue, cache, abstraction layer, database, framework, or protocol, name the concrete pressure that requires it now.
+
+Treat speculative future scale/features as a hypothesis, not a requirement. If the pressure is cheap to test, run a spike/measurement. If the design can be changed locally later, prefer the reversible choice and keep moving. Deep modules and narrow interfaces are preferred over many shallow wrappers that merely mirror implementation.
+
+## Turn risk into evidence, not prose
+<!-- keelson: id=lenses.evidence | without: design review produces impressive documentation but important properties are not protected when the code changes | sunset: never -->
+
+Each triggered lens must end as one or more of:
+
+- **already guaranteed** by an existing spec/rule/test → reuse it;
+- **owner-owned decision** → ask at the decision frontier;
+- **engineering default** → decide and record only if future work needs the rationale;
+- **cheap uncertainty** → spike, prototype, measurement, or inspect telemetry;
+- **stable invariant** → scoped rule, preferably an executable fitness/check;
+- **acceptance/evidence obligation** → add the failure/compatibility/security/performance/migration/accessibility case;
+- **explicitly out of scope** → name it once when omission would otherwise look accidental.
+
+Do not create a generic NFR document or architecture checklist artifact.
+
+## Protect architecture with fitness functions
+<!-- keelson: id=lenses.fitness | without: architecture quality depends on reviewers remembering prose rules and gradually decays as the project evolves | sunset: never -->
+
+When a durable architecture characteristic can be measured mechanically, convert it into `config.yaml → check` instead of repeatedly explaining it:
+
+- forbidden dependency direction;
+- public schema/API compatibility;
+- latency or bundle-size ceiling;
+- migration reversibility check;
+- security/static-analysis policy;
+- accessibility test;
+- deterministic contract/eval suite.
+
+Keep only enough prose to explain **why** the guard exists and where it applies. Repeated review comments are evidence that a fitness check or narrower rule should replace prose.
+
+## Prioritize irreversible risk
+<!-- keelson: id=lenses.priority | without: reversible taste gets debated while data loss, permissions, compatibility, migrations, or failure semantics are silently guessed | sunset: never -->
+
+Resolve roughly in this order:
+
+**irreversible data/security/production effects → public compatibility/migration/expensive commitments → failure/concurrency correctness → user-visible behavior/accessibility → measured reliability/performance/cost → reversible implementation taste**
+
+For security use a compact loop internally: **what are we protecting → what can go wrong → what control prevents/detects it → what evidence proves the control works?**
+
+For performance and scale, measure before adding machinery. For distributed work, assume retries and partial failure exist unless the transport contract proves otherwise. For destructive behavior, make recovery/rollback explicit.

package/skills/keelson/references/discover.md

@@ -0,0 +1,70 @@
+# Discovering what is wanted
+
+The user often cannot describe the whole requirement in the first sentence, and they should not need to know which engineering choice matters. Discovery finds the problem behind the request before anyone picks a database. Use `interview.md` for owner-owned uncertainty; load `design-lenses.md` only when the work triggers a real cross-domain risk.
+
+## Scenario before technology
+<!-- keelson: id=discover.scenario-first | without: the first question is a technology choice the owner cannot answer, and the product is shaped by whatever they guessed | sunset: never -->
+
+When a request is a product idea ("a team knowledge base", "add collaboration"), do not ask about storage, frameworks, or schemas. Ask which use is at the centre, with concrete alternatives that differ in what the user would do:
+
+> Which of these is closest to the first thing people will do with it?
+> A. Several people edit the same documents.
+> B. Company material is collected and searched.
+> C. Material is handed to an assistant that answers questions.
+> D. All of them eventually; a first version should pick one.
+> For a first version I suggest picking one: permissions, search, assistant, and co-editing each add their own complexity, and together they stall the project.
+
+Keep each question small: one concrete decision, enough scenario to understand it, and a recommended default with the one trade-off that matters. Options are a tool, not a required format. When the owner says "I don't know", route through `interview.md`: investigate, choose a reversible default, or make the consequence visible with a tiny example/experiment. Never repeat the term louder.
+
+## Which unknowns to raise
+<!-- keelson: id=discover.frontier | without: either every unknown becomes a question and nothing starts, or the agent settles product questions by itself | sunset: never -->
+
+Sort each unknown before asking:
+
+| Unknown | Handling |
+|---|---|
+| Answerable from the code, tests, or docs | Read it; never ask |
+| The project already has a convention | Follow it; mention it in the write-back |
+| Low risk and easy to reverse | Decide, record it as confirmed under your authorization |
+| Technical, and the owner has no reason to care | Pick a sensible default; say so in one line |
+| Changes what the product does for its users | Ask, with a recommendation |
+| Changes long-term architecture, cost, or a public commitment | Explain, then confirm |
+| Destroys data, widens permissions, touches production | Confirm explicitly, always |
+
+Only questions whose answer would change the result reach the owner. Everything else is a default or a `(assumed)` decision that surfaces before landing.
+
+## Ask at the decision frontier
+<!-- keelson: id=discover.decision-frontier | without: the agent either interrupts for facts it could investigate, invents user-owned intent, or asks low-value questions whose answers do not change the work | sunset: never -->
+
+Before asking, classify the gap by who can resolve it:
+
+| Gap | Action |
+|---|---|
+| Already established in repository/context | Use it; cite the source in the write-back |
+| Reality-owned (code behaviour, API contract, measurement, dependency capability) | Investigate or run a small experiment |
+| User-owned and load-bearing (goal, scope, acceptance, risk tolerance, public commitment) | Ask one question |
+| Non-load-bearing or cheap to reverse | Decide under authorization, or leave unresolved for a later slice |
+| Evidence exhausted | Mark it UNKNOWN; do not convert uncertainty into a user belief |
+
+Choose the gap with the highest practical value of information: the answer most likely to change the next slice, weighted by the cost of being wrong. Before asking, apply the `interview.md` question protocol. After the answer, update the write-back and reassess the frontier. "Exactly one question" is a bottleneck for **blocking uncertainty**, not a ritual: when no user-owned load-bearing gap exists, ask nothing and proceed.
+
+## Scope guard
+<!-- keelson: id=discover.scope-guard | without: a first request asks for five independent domains at once, and integration risk, debugging cost, and requirement churn compound | sunset: never -->
+
+When a request bundles several domains (identity, payments, real-time collaboration, an assistant, plugins, mobile), name them as separate domains and propose an order: the domain that the others depend on first, the rest as later milestones in `ROADMAP.md → Next`. The reason is not that the code cannot be written; it is that each added domain multiplies the ways the first ones can be wrong, and nothing has been verified yet. Say that in plain words.
+
+## Explore before committing
+<!-- keelson: id=discover.explore | without: an abstract decision is forced when a cheap experiment would settle it with evidence | sunset: never -->
+
+When a choice is reversible and the owner is unsure, do not press for a decision. Offer a spike, a prototype, a mock, or a measurement, sized to answer one question: two small UI variants to pick between; a measurement before adding a cache; a spike before adopting a library. Record the result as evidence in the ledger (`### Note:`) and the decision it produced under `## Decisions`.
+
+## Guided mode adds teaching, not usability
+<!-- keelson: id=discover.guided | without: accessible questioning is incorrectly gated behind a beginner setting, or teaching content becomes permanent project ceremony | sunset: never -->
+
+Scenario-first language, sensible defaults, and understandable questions are always on. `guide: true` adds only pedagogy:
+
+- briefly name the engineering idea after the plain-language decision is understood;
+- explain why a rule/constraint exists when applying it;
+- after a spec change lands, add a short teaching note: key decision, why, the engineering idea, and when to revisit it.
+
+The teaching note stays in conversation. Guided mode never changes artifacts, gates, or who owns a decision.