@zyaiting/keelson 0.4.0

package/skills/keelson/references/plan.md

@@ -0,0 +1,106 @@
+# Planning
+
+`keelson new <name> --tier quick|spec [--capability a,b] [--touches globs] [--depends other]` scaffolds the change directory and records the owner, branch, and the base of every delta spec. You fill in the artifacts. Plans exist so work survives a session boundary and so a reviewer can reject a slice on its own; they are not a script.
+
+## Where a change sits
+<!-- keelson: id=plan.hierarchy | without: either every task is re-planned from scratch or a three-month file-by-file plan is written that is wrong by week two | sunset: never -->
+
+Project goal (`INTENT.md`) → current milestone (`ROADMAP.md → Now`, or the tracker) → a change with a clear boundary (`changes/<name>`) → slices that can be accepted independently (`tasks.md`). Only the last two are files Keelson creates. Near-term work is concrete; later work is a direction and its dependencies, under `ROADMAP.md → Next`. Do not turn an unexplored question into a task with made-up steps.
+
+If the project has an issue tracker (`config.yaml → refs.tasks`), it stays the authority for what is wanted and in what order. `change.md` links the issue and holds only what the tracker does not: the decisions, the acceptance mapping, and the continuation state.
+
+## change.md
+<!-- keelson: id=plan.change-md | without: the reasons for a change and its rejected alternatives live only in chat and are lost | sunset: never -->
+
+Sections, in order. Quick changes need only **Why**, **What**, and **Acceptance**.
+
+- **Why** — the problem or opportunity in 1–3 sentences. Should stand on its own without the solution.
+- **What** — bullet list of changes. A bullet that starts with **BREAKING** marks a breaking change; it needs a **Rollout** section (compatibility window, migration, rollback), and `keelson land` checks for it.
+- **How** — technical approach, the parts a reviewer would want to know. Not a task list.
+- **Alternatives** — only when a material fork actually exists. Record the strongest credible alternative and why it loses. If the project already has a clear precedent and no real fork exists, say `follows <existing pattern>` instead of inventing options to satisfy a template.
+- **Impact** — what you found by reading, not the diff file list. See `context.md`.
+- **Acceptance** — one checkbox per criterion, each with how it is checked: `— test: name`, `— check: \`cmd\``, `— manual: how`, or `— review: what`. This is the map from request to evidence. Any triggered `design-lenses.md` risk that matters to correctness becomes an acceptance/evidence case, not extra prose.
+- **Open questions** — `- question — blocks: <slice>`. Landing refuses while any remain; a question that blocks nothing is a note, not an open question.
+- **Rollout** — only for breaking changes, migrations, or production steps.
+- **Decisions** — capability-local current rationale, present tense. Working assumptions are `- (assumed) capability: …`. A surprising or expensive-to-reverse cross-cutting architecture decision belongs in the project's `refs.decisions` ADR system when present; keep ADRs short and immutable, and supersede rather than rewrite them.
+
+## Route the audit into existing artifacts
+<!-- keelson: id=plan.assumption-routing | without: clarification creates a new diary document, or critical assumptions stay only in chat and disappear across sessions | sunset: never -->
+
+The assumption audit is conversational scratch, not another permanent document. Persist only what changes future work:
+
+- an explicit outcome or non-goal → `change.md → What`;
+- a working assumption needed to proceed → `change.md → Decisions` as `(assumed)`;
+- a user-owned load-bearing gap that is still unanswered → `change.md → Open questions` with what it blocks;
+- a confirmed observable behaviour → `Acceptance` and, for spec-tier behaviour, the delta spec;
+- a stable term or engineering invariant discovered along the way → `GLOSSARY.md`, a scoped rule, or a fitness check.
+
+After landing, temporary questioning disappears with the change scaffolding. Only the current behaviour, durable decisions, rules, vocabulary, and evidence-bearing checks survive.
+
+## Delta specs (spec tier)
+<!-- keelson: id=plan.delta | without: behaviour contracts drift from code because nobody rewrites whole specs | sunset: never -->
+
+One file per affected capability at `changes/<name>/specs/<capability>/spec.md`, same capability path as the main specs. `keelson new --capability` creates it with a `base:` stamp; if the main spec changes under you, landing asks you to re-read before `--accept-drift`. Write only the delta:
+
+```markdown
+## ADDED Requirements
+### Requirement: Page size limit
+The API SHALL reject `size` above 200 with HTTP 400.
+#### Scenario: Oversized page
+- WHEN a client requests `size=500`
+- THEN the response is 400 with code `size_too_large`
+
+## MODIFIED Requirements
+### Requirement: Order listing
+(full replacement text of the requirement)
+
+## REMOVED Requirements
+### Requirement: Legacy CSV export
+```
+
+A capability is logically one behaviour contract, but it does not have to stay one physical file. When the merged contract crosses the configured spec budget, `keelson land` automatically rewrites it as a small `spec.md` index plus `requirements/*.md` and `decisions/*.md` as needed; future deltas still target the capability as one logical spec, and base hashes cover the whole logical contract. Do not manually recombine shards.
+
+A spec is a behaviour contract: observable behaviour, inputs, outputs, error conditions, external constraints. If implementation can change without changing what a client sees, it does not belong here. Architecture invariants belong in `rules/` or executable checks. Cross-cutting architecture history belongs in `refs.decisions` ADRs when present; capability-local current rationale may stay in spec decision shards. Link instead of duplicating the same explanation.
+
+## tasks.md and slices
+<!-- keelson: id=plan.tasks | without: work is executed from memory; progress, slices, and effort routing are invisible across sessions | sunset: never -->
+
+`tasks.md` is a **mutable execution plan**, not a second acceptance contract. Its checkboxes communicate progress across sessions and help route effort, but `ready` and `land` are decided by acceptance, blockers/assumptions, rollout/compatibility, and fresh verification. If implementation takes a better path, update or delete stale tasks instead of keeping the lifecycle open to satisfy an obsolete plan.
+
+Group tasks under `## Slice: <name>` with a `Delivers:` line stating what someone can observe when the slice is done. A quick change usually has one slice and can omit the heading. Each task carries an effort tier and, where possible, a verification command:
+
+```markdown
+## Slice: Create and access
+Delivers: a link can be created and opens the shared item
+- [ ] 1. Add `POST /shares` (effort: standard) — verify: `npm test -- shares.create`
+- [ ] 2. Render the share page (effort: light) — verify: `npm test -- shares.page`
+
+## Slice: Revoke and expiry
+Delivers: every access path refuses a revoked or expired link
+- [ ] 3. Decide expiry semantics and update `specs/sharing` (effort: deep)
+```
+
+Right-size: a task is the smallest unit a reviewer could reject on its own. Split where a reviewer could accept one half and reject the other. A slice is the smallest unit the owner could accept on its own.
+
+### Slices are vertical
+<!-- keelson: id=plan.tracer-bullet | without: the schema, then the backend, then the frontend are each finished before anything runs end to end, and the mismatch between them is found last | sunset: never -->
+
+A slice is one real user action carried through every layer it touches (interface, API, domain, storage, response, test), thin but complete, before the next action is started. The first slice of a feature is the narrowest path that proves the layers fit: for "create issue", the form, the endpoint, validation, the domain object, the row, the response, the rendered result, and one test. Update, delete, and comment come after it runs. `keelson validate` warns when a slice is named after a layer ("database", "backend", "UI"). A layer-shaped task inside a vertical slice is fine; a layer-shaped slice is not.
+
+### Effort tiers
+<!-- keelson: id=plan.effort | without: every task runs on the most expensive model, or the cheapest one handles design decisions | sunset: when retro shows light-tier first-pass rate above 90% for 100 dispatches, relax the light criteria -->
+
+- **light** — mechanical, clear boundary, verification is a command: follow an existing pattern, config, renames, running and reporting tests, formatting.
+- **standard** — needs context but the path is clear: most feature code, ordinary bug fixes, per-task review.
+- **deep** — ambiguity, cross-layer effects, design trade-offs, security, unknown root cause: drafting change.md and delta specs, architectural rulings, hard debugging, the final fresh-reader review.
+
+Floors from `config.yaml → effort`: reviewers are never below `standard`; planning, final verification, and any ruling are never below `deep`. A reviewer is never a lower tier than the implementer it reviews.
+
+## When requirements change mid-way
+<!-- keelson: id=plan.requirement-change | without: "ok" in chat is the only record; the plan, acceptance, and decisions still describe the old requirement | sunset: never -->
+
+Update `change.md` (What, Acceptance, Decisions), the delta spec, and the affected slice in the same turn the owner changes their mind. If the change is now a different change, `keelson cancel` the old one with a reason and start fresh.
+
+## ledger.md
+
+Start it with a one-line header. Everything else is appended during build and verify. Entries are `###` headings: `Ruling:`, `Root cause:`, `Verify:`, `Dispatch:`, `Escalate:`, `Note:`. `keelson check --record` writes `Verify:` entries for you, with the worktree fingerprint that makes staleness detectable.

package/skills/keelson/references/reconcile.md

@@ -0,0 +1,61 @@
+# Reconcile and compact
+
+Landing a change is not the end of it. Two passes keep the project's knowledge true and small: reconcile writes new stable facts back into current truth, and compact removes what no longer belongs there. These are normal internal Agent duties during RECONCILE, not housekeeping the owner has to request; `keelson doctor` remains a diagnostic view.
+
+## Reconcile: where does each new fact go?
+<!-- keelson: id=reconcile.route | without: the change's facts stay in change.md and chat; the specs, rules, and glossary describe last quarter's system | sunset: never -->
+
+Before `keelson land`, and again when reviewing its output, ask for each thing you learned:
+
+| The change produced | It goes to |
+|---|---|
+| A new or changed stable behaviour | the capability spec, via the delta (`land` merges it) |
+| A reason that will matter to a future maintainer | the spec's `Decisions` (`land` folds them) |
+| A new term, or a term that now means something specific | `GLOSSARY.md` |
+| A responsibility moved between modules, or a new boundary | the rules scoped to those paths; `refs.architecture` if the project keeps one |
+| A quality target with a number | the spec, as a requirement with a scenario |
+| A constraint that a command can check | `config.yaml → check` (a fitness check); then the prose rule can shrink |
+| A defect that reached verification | a regression test, plus a `Root cause:` in the ledger |
+| Work that is known but not done | the tracker, or `ROADMAP.md → Next`, with an owner |
+| Anything that only mattered during the change | nowhere; it stays in git history with the change directory |
+
+Every line above is present tense in its destination. The change directory is scaffolding and is removed; the truth files are what remain.
+
+## Current truth is rewritten, never appended
+<!-- keelson: id=reconcile.rewrite | without: specs become a chronological diary; the reader cannot tell which paragraph describes the system today | sunset: never -->
+
+A spec, a rule, or a glossary line says how the system works now. When behaviour changes, the sentence that described the old behaviour is replaced, not followed by "as of September this is now…". The sequence of changes is in git, in the archived or folded change, and in the decision line that names the rejected option. `keelson doctor` flags requirement text that reads like history.
+
+## Compact: keep what is read small
+<!-- keelson: id=reconcile.compact | without: documents grow without bound; the always-on set inflates every session and stale text is read as current | sunset: never -->
+
+`config.yaml → budgets` gives each document type a line budget (INTENT, ROADMAP, NOW, GLOSSARY, spec, rule, change, handoff, and the always-on rules as a set). The budget is a **soft compaction threshold**. Keelson automatically reorganizes structure before hot files grow without bound: large specs become a small index plus requirement/decision shards, and runtime caches are pruned. When a single semantic unit is itself too large, the Agent automatically rewrites or decomposes it during RECONCILE and re-verifies the result. Active change/handoff files are temporary scaffolding, so they stay lightweight but do not become durable knowledge stores. The owner is involved only when compaction would change product semantics, authorization, compatibility, or another owner decision.
+
+When the soft budget is crossed, run a compaction pass on that document, choosing per paragraph:
+
+- **Rewrite** it shorter, present tense.
+- **Split** by capability, scope, or bounded context, when the requirements no longer share a purpose.
+- **Delete** history that git already keeps, and facts nothing depends on.
+- **Move** a constraint to the rule scoped to its paths, or a plan item to the tracker.
+- **Automate** a checkable rule into `config.yaml → check` and shorten the prose to a pointer.
+- **Archive** a change that has stalled (`keelson cancel` with a reason) rather than leaving it half-open.
+
+`keelson doctor` also detects duplicated requirements across capabilities, idle/oversized changes, overgrown always-on rules, and stale generated docs. The Agent consumes those signals opportunistically and folds safe cleanup into the current engineering pass; it does not create owner-visible maintenance work unless semantics would change.
+
+## Automatic maintenance is invisible
+<!-- keelson: id=reconcile.automatic | without: the owner is asked to run housekeeping commands, specs become giant monoliths, or cleanup is postponed until it becomes a separate project | sunset: never -->
+
+Treat knowledge shape as infrastructure, not user work. When `keelson context` exposes internal maintenance findings, resolve them in the same engineering pass without asking the owner:
+
+- **Large specs** — do not summarize away requirements. `keelson land` automatically changes a large capability from one `spec.md` into a bounded index plus `requirements/*.md` and `decisions/*.md`. Total knowledge may grow; each frequently-read file stays small.
+- **Rules** — split by actual path/scope and update `rules/index.md`; merge duplicate rules and replace prose with a fitness check when deterministic. If a single rule remains too broad, rewrite it automatically into the smallest invariant that preserves meaning.
+- **NOW / INTENT** — never shard. Rewrite them automatically as short current-state views; history stays in git.
+- **ADRs / decisions** — one durable decision per ADR when the project uses `refs.decisions`; the directory may grow, but do not inject every ADR into every session. Capability-local decisions are automatically sharded into `decisions/*.md`.
+- **Runtime** — session pointers and evidence logs are caches. Keelson garbage-collects old entries opportunistically from normal commands.
+
+Only involve the owner when compaction would change product semantics, authorization, compatibility, or another decision they actually own. File movement, indexing, deduplication, history removal, and cache cleanup are maintenance and happen silently.
+
+## Gardening cadence
+<!-- keelson: id=reconcile.cadence | without: knowledge health is only looked at when it hurts, by which time the cleanup is a project of its own | sunset: never -->
+
+The Agent re-evaluates knowledge health during normal context/reconcile cycles and after meaningful landings. Maintenance is incremental and silent: keep each hot document readable continuously instead of scheduling cleanup days or asking the owner to manage the control plane.

package/skills/keelson/references/shape.md

@@ -0,0 +1,86 @@
+# Shaping
+
+Turn a request or an idea into a shared understanding before artifacts exist. Facts first, then questions, then a write-back. Three layers need to be clear, and not all at once: the project (who it serves, what it will never do, in `INTENT.md`), the current goal (this milestone, in `ROADMAP.md` or the tracker), and this change (what behaviour changes and how anyone will know it is done).
+
+
+For interface work, load `frontend.md`; visual and interaction acceptance follow `frontend-review.md` and `frontend-delivery.md`.
+
+## Explore first
+<!-- keelson: id=shape.explore-first | without: agent asks the user for facts it could read, wasting their time and training them to skip questions | sunset: never -->
+
+Read what answers the question: the code, tests, `INTENT.md`, `ROADMAP.md`, the specs, the matched `rules/`, and the documents listed under `refs` in `config.yaml`. A decision already recorded in a spec's `Decisions` section or in `INTENT.md` is settled; do not ask it again. Only questions about intent, priorities, and trade-offs belong to the user.
+
+## Assumption audit before questions
+<!-- keelson: id=shape.assumption-audit | without: the agent solves a plausible but wrong problem, attributes invented beliefs to the owner, or asks a questionnaire before reading the repository | sunset: never -->
+
+When quick work is materially ambiguous, and for every spec change, do a compact audit after reading the repository and before implementation. Do not narrate private chain-of-thought; report only decision-relevant results:
+
+1. **Established** — facts the owner or repository actually states.
+2. **Required assumptions** — what the proposed path would need to be true but nobody has confirmed. Phrase it as "this plan would require X", never "you assume X".
+3. **Missing** — information that cannot be learned from the repository; rank it by how much the answer could change the outcome, boundary, acceptance, or an expensive-to-reverse choice.
+4. **Failure if wrong** — name one likely failure pattern for this class of work: wrong problem, scope creep, compatibility break, unmeasured optimisation, unsafe migration, or another concrete risk.
+
+Keep the audit internal except for the facts/assumptions needed in the short write-back. If no missing item is load-bearing, proceed under project authorizations/defaults. If one is load-bearing and user-owned, route it through `interview.md`, ask the single highest-value question, update the write-back, then reassess. Do not expose an audit checklist to the owner.
+
+## Write back your understanding
+<!-- keelson: id=shape.write-back | without: agent builds its own interpretation; mismatches surface after code exists | sunset: never -->
+
+For every non-trivial change, before creating anything, state in 3–6 lines: the outcome, the boundaries (what is explicitly out), the constraints you found, and the success check. Separate what the user said from what you assumed. Proceed after the write-back unless the matching `confirm.quick|spec` setting is `wait` or a real owner-owned decision remains unresolved. High-risk actions still follow `INTENT.md → Authorizations`.
+
+> Understood as: add offset pagination to `/orders` (`page`, `size`, default 20) using the shared response envelope from `rules/api.md`; table gets a pager, no infinite scroll. Assumed: sort stays by `created_at desc`. Done when `npm test -- orders` passes and the pager renders.
+
+## Four states for what you know
+<!-- keelson: id=shape.decision-states | without: a recommendation the agent made is later treated as something the owner chose, and nobody can tell which | sunset: never -->
+
+Keep these apart, in the conversation and in `change.md`:
+
+- **Suggestion** — what you recommend, with its consequences. Not in effect until the owner picks it.
+- **Confirmed** — what the owner chose. A plain line under `## Decisions`.
+- **Authorized** — what `INTENT.md → Authorizations` lets you decide alone. Decide, record it as confirmed, move on.
+- **Open** — what still needs an answer. A line under `## Open questions` with `— blocks: <slice>`.
+
+When you must proceed without an answer, write the working assumption as `- (assumed) capability: …` under `## Decisions`. `keelson land` refuses to fold assumed lines until the owner passes `--confirm-assumptions`.
+
+## Stop asking when the next slice is deliverable
+<!-- keelson: id=shape.stop-rule | without: agent either exhausts the owner with questions about later slices, or starts building on a slice whose acceptance is undefined | sunset: never -->
+
+The bar is not "no unknowns in the project". It is: the next slice has a clear outcome, a boundary, and an acceptance check. Unresolved questions about later slices go under `## Open questions` with what they block, and the work they do not block continues. Example: download permissions undecided, link management list can be built, public download must not be defaulted on.
+
+## Interview (only when the decision frontier requires it)
+<!-- keelson: id=shape.interview | without: architectural ambiguity is silently guessed, or every spec change turns into a mandatory questionnaire | sunset: never -->
+
+Use `interview.md` for the interaction protocol. A spec-sized change does **not** automatically require user questions: first resolve repository-owned facts and reversible engineering choices yourself. If the work touches data, security, concurrency, compatibility, error handling/resource lifetime, operations, performance, UI/accessibility, or AI behavior, inspect only the triggered rows in `design-lenses.md` and turn them into decisions or evidence obligations. For failure-path changes, follow its pre-implementation regression step.
+
+Run the assumption check internally. Do not open with an abstract "what are we assuming?" question unless the owner truly owns that uncertainty; translate it into the concrete user-visible or risk consequence instead. Explicit "stress-test this" requests continue through the relevant decision tree; ordinary work stops as soon as the next safe slice is ready.
+
+## Authorization
+<!-- keelson: id=shape.authorization | without: either every step waits for approval or the agent decides product questions and production actions by itself | sunset: never -->
+
+| Situation | Default |
+|---|---|
+| Local implementation choice inside a confirmed scope, following project conventions | Decide, verify, move on |
+| Intent still vague; the choice changes experience, scope, or a long-term commitment | Recommend with consequences; the owner chooses |
+| Irreversible data operation, production change, permission widening, breaking compatibility | Confirm explicitly, per `INTENT.md → Authorizations` |
+| Unrelated optimisation, extra feature, broad refactor | Suggest; do not widen the change |
+| Environment missing, key acceptance cannot run | Mark blocked or partially verified; never fake a pass |
+
+Stronger models widen the first row, never the third.
+
+## When nobody can answer
+<!-- keelson: id=shape.unattended | without: an unattended session either blocks forever on a question or silently lands a change nobody approved | sunset: never -->
+
+In a scripted or unattended session there is no one to confirm a write-back or approve a plan. Do not stall, and do not skip the artifacts: write the understanding and the plan, mark assumptions `(assumed)`, build and verify under them, and stop before landing. Say in `NOW.md` that the change awaits review. The reviewer then sees the plan and the diff together and lands with `--confirm-assumptions` or rejects.
+
+## Exploring (the user is thinking, not asking)
+<!-- keelson: id=shape.explore-stance | without: agent forces a proposal on someone who wanted a thinking partner | sunset: never -->
+
+If the user is weighing options rather than requesting work, take the thinking-partner stance: read-only, surface multiple directions, sketch trade-offs, offer a grounded recommendation, and let them pick. Keep decisions in the conversation; do not create a change until they say so.
+
+## Sizing rules of thumb
+<!-- keelson: id=shape.sizing | without: agent runs ceremony on trivia or skips planning on contract changes | sunset: when 50 consecutive changes needed no tier override from the user -->
+
+- Would the owner want to read a plan before code exists? → spec.
+- Does any `Requirement:` in the specs change, appear, or disappear? → spec.
+- Migration, external dependency, or work that will cross sessions? → spec.
+- Are you abandoning the obvious approach for a hidden constraint? → spec, and record the alternative.
+- Otherwise several files with clear intent → quick. One file, no behaviour change → trivial.

package/skills/keelson/references/verify.md

@@ -0,0 +1,64 @@
+# Verifying
+
+Readiness/completion is a lifecycle state backed by evidence, and evidence has two properties that fail independently: the record can be invalid (never ran, ran on older code, ran partially) and the content can be invalid (ran, passed, and still did not check what the owner asked for). This reference covers both. It does not get thinner as models improve, because it is about the world, not about judgment.
+
+
+For interface work, load `frontend.md`; visual and interaction acceptance follow `frontend-review.md` and `frontend-delivery.md`.
+
+## Record validity: `keelson check --record`
+<!-- keelson: id=verify.fresh | without: "should pass" and "looks right" replace running the command; evidence from before the last edit is presented as current | sunset: never -->
+
+Before claiming completion, review the configured commands and run `keelson check --trust --record "<claim>"` on first execution. Later identical commands need no new trust flag. The CLI writes signed `ledger.jsonl` envelopes and `evidence/<digest>.log` under the active change. `ledger.md` is a readable summary only; hand-written `Verify:` text cannot authorize landing.
+
+The record binds both the full worktree and contracts, including acceptance and decisions. `status` and `land` reject stale, failed, incomplete or untrusted records. A command supplied explicitly is partial unless it exactly covers the configured suite. Complete acceptance before the final check; editing it afterwards invalidates the evidence. If all gates pass, land within the existing authorization. Local signatures do not protect against a process with access to the same user account or prove model attribution.
+
+If a check cannot run (environment missing, service down), say so in the ledger as a `Note:` and in `NOW.md → Blocked / uncertain`. Partial verification is reported as partial; it is never rounded up.
+
+Checks in `config.yaml → check` may be plain strings or `{name, command, kind}` entries; `kind` is one of `test`, `lint`, `typecheck`, `build`, `fitness`, or `check`. A `fitness` check is an architecture or quality constraint turned into a command (dependency direction, interface compatibility, a latency budget). Mechanical evidence is this whole set passing on the current tree. It is necessary and never sufficient.
+
+## Content validity: does the evidence cover the request?
+<!-- keelson: id=verify.content | without: tests pass and the requirement is still unmet; the implementer's summary is reviewed instead of the owner's request | sunset: never -->
+
+Go back to `change.md → Acceptance` and to the original request, not to your own summary of it. For each acceptance item, name the test, command, manual check, or review that covers it, and tick it only when that check has actually run. For each requirement or scenario in the delta spec, name the covering check. Anything uncovered is either checked now or written down as a gap under `NOW.md → Blocked / uncertain`. Then read the diff against the matched rules and the affected specs; a rule violation is a defect even when every test is green.
+
+For a bug fix, keep the negative check: with the fix reverted, the regression test must fail. A test that passes both ways proves nothing.
+
+For each risk lens that actually triggered during shaping, verify the corresponding obligation rather than re-running a generic checklist: security needs the relevant negative/abuse case, concurrency needs duplicate/order/failure behavior, compatibility needs old-consumer or migration coverage, accessibility needs the affected interaction check, and performance needs a measured target/baseline. If the repository already proves it, reuse that evidence; do not duplicate it.
+
+For changes to error handling, cleanup or resource lifecycles, trace the complete entry-to-return path, including finalizers and notifications after cleanup. Inject failures at more than one phase together: an early error must not hide a later required action, and a late error must not silently replace earlier failures. Check which actions ran, which errors escaped, and the state visible both to final observers and to the caller, including pre-existing outer state. Assert error identity/count and any ordering the contract requires; a callback count alone does not establish correct propagation or restoration. Keep additional robustness probes distinct from the owner's stated acceptance criteria.
+
+## Counterfactual evidence for mechanisms that claim a benefit
+<!-- keelson: id=verify.counterfactual | without: the selected design passes its tests, but nobody verifies that the new cache, queue, retry layer, abstraction, model stage, or reviewer actually causes the benefit used to justify its complexity | sunset: never -->
+
+Routine product behavior does not need an ablation. Use this only when the rationale for a mechanism is empirical: performance, reliability, cost, quality, safety margin, or another measurable response.
+
+Verify the claim against the baseline from `engineer.md`: same representative workload/environment, candidate enabled, candidate disabled or simplified, and the predeclared response/threshold. For reliability mechanisms, inject the failure they claim to handle; for AI/Agent stages, compare the same eval cases with and without the stage.
+
+If removing the mechanism does not materially worsen the target, its necessity is unsupported: remove it or record the result as inconclusive rather than preserving complexity because “everything is green.” If two mechanisms may interact, test the smallest useful combinations instead of trusting one-at-a-time removal.
+
+Promote stable response thresholds to a fitness check when practical; keep noisy exploratory runs as evidence/ledger notes rather than permanent gates.
+
+## Tests may change; they may not be quietly weakened
+<!-- keelson: id=verify.no-silent-weakening | without: "all green" is achieved by deleting an assertion or skipping a case, and the weakening is invisible in the completion report | sunset: never -->
+
+Editing a test is normal when the requirement changed. Deleting an assertion, skipping a case, widening a tolerance, or replacing a real check with a mock is a change to the acceptance criteria: it needs the owner's decision (or an explicit authorization), and it goes into the ledger as a `Ruling:` that names what was weakened and why. A completion report that hides it is wrong.
+
+## Fresh-reader review (spec tier)
+<!-- keelson: id=verify.fresh-reader | without: the author reviews their own work; the same blind spot passes twice | sunset: when 50 consecutive fresh-reader reviews found nothing the per-task reviews missed -->
+
+Dispatch a reviewer that has not seen the conversation (tier ≥ `deep` for spec changes), with the original request, `change.md`, the delta specs, and the diff. Ask for: acceptance items without real coverage, requirement gaps, rule violations, risky assumptions, anything a maintainer would object to. Address or ledger each finding. Agreement from a second agent is a signal, not a proof; the acceptance list is what is checked.
+
+## Completion report
+
+Tell the user what was done, what the evidence is, and what is left. Shape:
+
+```
+Done: offset pagination on /orders, pager in the table.
+Evidence: `npm test -- orders` exit 0 (14 passed); `npm run lint` exit 0 · tree 5bcb829dae. Acceptance 3/3.
+Open: none. `keelson land add-pagination` succeeded; durable behavior/decisions were folded.
+```
+
+<!-- guided -->
+## Words that mean you have not verified
+"should", "probably", "seems to", "I believe it works". If you are about to write one of these about a status, run the command instead.
+<!-- /guided -->

package/skills/keelson/templates/GLOSSARY.md

@@ -0,0 +1,5 @@
+# Glossary
+
+Shared vocabulary for this project: one line per term, the meaning that code, specs, and conversation all use. Add a term when two words start meaning the same thing, or one word starts meaning two things. When a term means something different in another part of the system, name that part and keep both definitions.
+
+- … — …

package/skills/keelson/templates/INTENT.md

@@ -0,0 +1,22 @@
+# {{project}}
+
+## Why this exists
+One paragraph. The problem this project solves and for whom. If this paragraph is wrong, everything built on it is wrong.
+
+## Boundaries
+- In scope: …
+- Explicitly not: … (write the tempting things you have decided not to do)
+
+## Hard constraints
+- … (runtime, compatibility, performance, security, licensing)
+
+## Authorizations
+What the agent may decide alone, and what it must bring back with a recommendation.
+- Decides alone: local implementation choices inside a confirmed scope; test structure; naming that follows existing patterns.
+- Recommends, owner decides: anything that changes user-visible behaviour, scope, or a long-term commitment; new dependencies; public interface changes.
+- Always confirms: irreversible data operations, production changes, permission widening, breaking compatibility.
+
+## Working defaults
+- Change sizing: auto (the agent decides; override per request with "treat as spec" / "just do it")
+- Quick changes: proceed after write-back
+- Spec changes: wait for approval

package/skills/keelson/templates/NOW.md

@@ -0,0 +1,9 @@
+# Now
+
+Nothing in flight.
+
+## Blocked / uncertain
+None.
+
+## Next
+…

package/skills/keelson/templates/README.md

@@ -0,0 +1,60 @@
+<!-- Generated by Keelson; refreshed by `keelson update`. Keep project facts in their owning files, not in this map. -->
+# Keelson project map — {{project}}
+
+`.keelson/` holds project facts, contracts, decisions, and change evidence. It grows only when the project has information worth keeping. Agent guidance comes from the installed Keelson package.
+
+## Start here
+
+People normally need only two files:
+- **What is happening now?** → `NOW.md`
+- **Why does this project exist / what are its boundaries?** → `INTENT.md`
+
+Agents start with `keelson guide workflow` and `keelson guide`, then load individual references as needed. Everything else is maintained on demand; nobody needs to manage Keelson folders as part of normal development.
+
+## Always present after init
+
+| Path | Purpose |
+|---|---|
+| `README.md` | This map |
+| `INTENT.md` | Project purpose, boundaries, hard constraints, agent authority |
+| `NOW.md` | Current state, blockers, next concrete step |
+| `config.yaml` | User-controlled Keelson configuration |
+| `manifest.json` | Package-owned install manifest: generated host surfaces Keelson owns |
+
+## Appears only when useful
+
+| Path | Created when |
+|---|---|
+| `ROADMAP.md` | The project has a milestone/direction that is not already clear from its tracker |
+| `GLOSSARY.md` | Shared vocabulary becomes load-bearing or ambiguous |
+| `specs/<capability>/spec.md` | A capability has observable behavior worth treating as a contract; it stays a small index when the contract auto-shards |
+| `specs/<capability>/requirements/*.md` | Automatically appears when one capability contract outgrows a single readable file |
+| `specs/<capability>/decisions/*.md` | Automatically appears when capability-local durable decisions grow; one small durable decision file per item |
+| `rules/index.md` + `rules/*.md` | A stable engineering invariant applies to a path and is not better expressed as a check |
+| `changes/<name>/change.md` | Non-trivial work needs a reviewable boundary |
+| `changes/<name>/tasks.md` | The work needs an explicit multi-step / multi-slice plan |
+| `changes/<name>/ledger.md` | A ruling, failure cause, dispatch, or verification event actually happened |
+| `changes/<name>/handoff.md` | Work ownership moves across people/machines or needs an explicit transfer package |
+| `changes/<name>/specs/**` | A spec-sized change modifies behavior contracts |
+| `changes/<name>/decisions.json` | Structured choices and their resolution history are needed |
+| `changes/<name>/ledger.jsonl` + `evidence/` | Signed check records, public signing keys, and content-addressed output are created |
+| `workflow.md` + `skill/` | The owner explicitly selects `--vendor` to copy package guidance |
+
+Private keys, command trust, locks, and session focus live outside this directory: in Git's private `keelson-runtime` directory, or a user cache for non-Git projects. Hooks execute from the installed package. Initialization does not edit `.gitignore`; review check logs before sharing them.
+
+## What survives a completed change
+
+A completed change should leave **less scaffolding and more truth**:
+
+- observable behavior → main specs;
+- durable constraints → scoped rules or executable checks;
+- durable vocabulary → glossary;
+- ordinary session continuation → durable change state + local session focus;
+- explicit ownership transfer → handoff;
+- chronology → git history.
+
+Temporary change files fold or archive when work lands. Empty optional artifacts should be deleted rather than kept “just in case”.
+
+## Human reading rule
+
+Prefer present-tense current truth. Keelson keeps high-frequency files bounded, auto-shards large specs, and routes internal compaction work to the agent. A person should not need to run housekeeping commands or understand the storage layout to keep working.

package/skills/keelson/templates/ROADMAP.md

@@ -0,0 +1,12 @@
+# Roadmap
+
+The current milestone and the direction after it. Near-term work is concrete; later work is direction and dependencies only. If the project has an issue tracker, link it here and keep the authoritative list there.
+
+## Now
+- … (the milestone in progress and what "done" looks like)
+
+## Next
+- … (direction and known dependencies, not tasks)
+
+## Later
+- …

package/skills/keelson/templates/change-quick.md

@@ -0,0 +1,16 @@
+---
+tier: quick
+created: {{date}}
+status: in-progress
+---
+
+# {{title}}
+
+## Why
+…
+
+## What
+- …
+
+## Acceptance
+- [ ] … — check: `…`

package/skills/keelson/templates/change.md

@@ -0,0 +1,32 @@
+---
+tier: {{tier}}
+created: {{date}}
+status: clarifying
+---
+
+# {{title}}
+
+## Why
+…
+
+## What
+- Outcome: …
+- Non-goal: …
+- … (a bullet that starts with the word BREAKING in bold marks a breaking change and needs a Rollout section)
+
+## How
+…
+
+## Impact
+- … (callers, other entry points, data, permissions, compatibility; `keelson impact <files>` gives hints, reading gives the answer)
+
+## Acceptance
+- [ ] … — test: `…`
+- [ ] … — manual: …
+
+## Open questions
+- … — blocks: <slice or task it blocks>
+
+## Decisions
+- {{capability}}: … (present tense; durable rationale only when it will matter later)
+- (assumed) {{capability}}: … (your working assumption; the owner confirms it before landing)

package/skills/keelson/templates/delta-spec.md

@@ -0,0 +1,12 @@
+# {{capability}} — delta
+
+## ADDED Requirements
+### Requirement: …
+The system SHALL …
+#### Scenario: …
+- WHEN …
+- THEN …
+
+## MODIFIED Requirements
+
+## REMOVED Requirements

package/skills/keelson/templates/handoff.md

@@ -0,0 +1,27 @@
+---
+at: {{sha}}
+updated: {{date}}
+by: {{by}}
+---
+
+# Handoff — {{name}}
+
+A current-state summary for whoever continues, human or agent. Overwrite it; do not append a diary.
+
+## Goal and confirmed decisions
+…
+
+## Done
+- … (slices or tasks that are complete and verified)
+
+## Open and blocked
+- … (what is unresolved, and which slice it blocks)
+
+## Ruled out
+- … (assumptions or approaches rejected, with the evidence)
+
+## Next step
+…
+
+## Verification
+- last `Verify:` … (command, exit code, tree); what has not been checked yet

package/skills/keelson/templates/ledger.md

@@ -0,0 +1,3 @@
+# Ledger — {{name}}
+
+Append-only. Entries are `###` headings: `Ruling:`, `Root cause:`, `Verify:`, `Dispatch:`, `Escalate:`, `Note:`. A `Dispatch:` body starts with `Result: pass|fail`; a `Verify:` body names a `command` and `exit N`.

package/skills/keelson/templates/resident-block.md

@@ -0,0 +1,7 @@
+<!-- keelson:start -->
+## Keelson
+
+This project is managed by Keelson. Before non-trivial work, run `keelson guide` and follow it.
+For a routed topic, run `keelson guide <reference>`. Use `keelson init --vendor` only when the project needs a checked-in guidance copy.
+Files outside `.keelson/` are discovery adapters only; do not duplicate Keelson guidance here.
+<!-- keelson:end -->

package/skills/keelson/templates/rules-general.md

@@ -0,0 +1,10 @@
+# General conventions
+
+Rules are feedforward controls. Keep each one or two lines, scoped, and checkable. State what must remain true, not a preferred implementation recipe. If a command can enforce the invariant, put it in `config.yaml → check` and keep the prose as a pointer.
+
+## Before editing
+- Match the surrounding style; do not reformat files you are not otherwise changing.
+- Keep unrelated cleanup out of the current change; record it separately unless it blocks the requested work.
+
+## Checks
+- Run the cheapest relevant check while editing; before completion or landing, `keelson check --record` must pass on the current tree.

package/skills/keelson/templates/rules-index.md

@@ -0,0 +1,5 @@
+# Rules index
+
+One line per scope: a path glob, an arrow, and the rule file in this directory. The agent reads only the rules whose glob matches the files it is about to touch. Use `**` for rules that always apply.
+
+- `**` → general.md — applies to every change

package/skills/keelson/templates/spec.md

@@ -0,0 +1,14 @@
+# {{capability}}
+
+## Purpose
+What this capability is for, in one or two sentences.
+
+## Requirement: {{name}}
+The system SHALL …
+
+### Scenario: {{scenario}}
+- WHEN …
+- THEN …
+
+## Decisions
+- {{capability}}: … (one line per durable decision, present tense, naming the rejected alternative)

package/skills/keelson/templates/tasks.md

@@ -0,0 +1,9 @@
+# Tasks
+
+One checkbox per task, each with an effort tier and, where possible, a verification command. This file is a mutable execution plan: checkboxes communicate progress, but they do not determine whether the change is complete or landable. Group into slices when the work has more than one independently deliverable part; each slice states what someone can observe when it is done.
+
+## Slice: …
+Delivers: …
+
+- [ ] 1. … (effort: light) — verify: `…`
+- [ ] 2. … (effort: standard) — verify: `…`

package/skills/keelson/templates/workflow.md

@@ -0,0 +1,18 @@
+# Keelson workflow
+
+Project truth and durable work live under `.keelson/`. Machine-local focus, trust and keys live in Git’s private runtime directory; durable signed records and logs stay with each change. A **session is not a task**: it only points at the work item this conversation is currently about.
+
+Every non-trivial modifying request follows **ORIENT → BOUND → BUILD → SENSE → RECONCILE**.
+
+- **ORIENT** — inspect the worktree and current session focus. Same-goal follow-ups keep the focused change. For “continue”, run `keelson focus --auto`; never bind an ambiguous session silently.
+- **BOUND** — read before asking. Resolve repository facts and reversible engineering choices yourself; ask up to three independent, ready owner decisions at the decision frontier, only when they materially affect the result. Trivial: edit directly; quick: smallest useful change; spec: acceptance + behavior delta + plan. Inspect only risk lenses actually triggered by the work.
+- **BUILD** — one vertical slice at a time. A new independent requested outcome gets a new change; continuing questions about the same outcome do not.
+- **SENSE** — cheap checks early; completion requires fresh `keelson check --record` evidence on the current tree. Task checkboxes describe the current plan; they never decide completion.
+- **RECONCILE** — evaluate lifecycle after each modifying pass from acceptance, blockers, rollout/compatibility, and fresh verification. Before landing, silently perform any internal knowledge maintenance surfaced by context: rewrite singleton current-state docs, split/dedupe rules, and let `land` auto-shard large specs. If gates are satisfied, status becomes `ready` and the agent lands automatically; do not wait for the user to say “done” or expose maintenance ceremony.
+- Ending a session, going idle, compaction, or closing the window changes only session runtime state. It never completes, cancels, or lands durable work.
+- `handoff.md` is reserved for real transfer across people/machines or deliberate ownership change. Normal new sessions reconstruct from change/task/ledger state and optional session focus.
+- Create artifacts lazily. Empty documents are not progress.
+- Repeated failure classes become scoped rules or executable fitness checks; shrink prose after automation carries the invariant.
+- First contact derives `INTENT.md` from repository evidence; ask the owner only if an unresolved project boundary is load-bearing for current work. Specs/rules grow only when real work exposes durable truth.
+
+The package router is `keelson guide`. It classifies conversation intent; lifecycle transitions are derived from work state, not user phrasing. A project may vendor it only with `keelson init --vendor`.