@christang/keel 5.1.2 → 5.2.0

package/README.md

@@ -8,77 +8,64 @@
 ![Node](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen.svg)
 ![Targets](https://img.shields.io/badge/targets-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20OpenCode-blue.svg)
 
-Keel wraps [OpenSpec](https://github.com/fission-ai/openspec) with a thin, deterministic
-execution layer so a coding agent **plans, implements, verifies, reviews, and hands off**
-work inside stable, checkable boundaries — instead of drifting mid-task or losing the
-thread between sessions.
-
-Keel is **stateless by design**: every session recomputes what to do from your OpenSpec
-artifacts and Git, never from hidden chat memory, transcripts, or a saved "current task."
-That makes an agent's work resumable, auditable, and safe to hand between runtimes.
-
----
-
-## Why Keel
-
-- **Deterministic gates, not vibes.** `keel gate task-start | task-complete | change-close`
-  run local, model-free structural checks and return `pass` / `fail` / `needs-review` with
-  real exit codes. They never claim to judge whether your design is *correct* — only whether
-  the contract and evidence are present.
-- **A real write guard (Claude).** A passing `task-start` drops a one-shot manifest, and a
-  `PreToolUse` hook then *deterministically rejects* any `Edit`/`Write` outside the task's
-  declared `Touch` scope — turning "please stay in scope" from a hope into enforcement.
-- **Stateless continuity.** `keel context` reconstructs the selected task, next action, and
-  minimal read list from OpenSpec + Git every time. Survives compaction, `/clear`, and cold
-  starts. `keel/HANDOFF.md` exists only as an optional, validated override.
-- **Expectation alignment before code.** `keel-align-expectations` aligns hidden assumptions
-  *before* specs and tasks finalize — a risk-triggered deep path asks one material decision at
-  a time and writes accepted answers back into OpenSpec.
-- **Single-task goal execution.** Authorize the agent to autonomously drive *exactly one*
-  OpenSpec task — with a fingerprinted capsule, a hard stop boundary, and no hidden scheduler
-  picking the next task for you.
-- **One discipline, three runtimes.** The same protocol runs on Claude Code, Codex, and
-  OpenCode; execution skills and hooks ship as a native plugin.
-
----
-
-## How it works
-
-```mermaid
-flowchart LR
-    A[keel --init] --> B[keel context]
-    B --> C[proposal / design / specs / tasks]
-    C --> D[keel-align-expectations]
-    D --> E[/opsx:apply → pick one task/]
-    E --> F[task-start<br/>+ write guard]
-    F --> G[implement · test-first · verify]
-    G --> H[keel-review-checklist]
-    H --> I[task-complete]
-    I --> J[/opsx:sync · /opsx:archive/]
-```
+## What Keel is for
+
+[OpenSpec](https://github.com/fission-ai/openspec) gives a project a spec-driven
+workflow: proposal, design, specs, tasks, and an archive of what changed. Claude Code
+(or Codex) gives you the agent that does the work. Keel sits between them and keeps the
+agent on track while it works through an OpenSpec change.
+
+Left alone, an agent tends to drift: it edits files the task never mentioned, loses the
+thread after a context reset, or checks work off without proof. Keel adds a thin, checkable
+layer that prevents that, and it does so by building on tools you already have instead of
+replacing them.
+
+What Keel adds:
+
+- **Stateless continuity.** `keel context` recomputes the current task and next step from
+  OpenSpec and Git every session, so work survives `/clear`, compaction, and cold starts
+  without depending on chat memory.
+- **Deterministic gates.** `keel gate task-start | task-complete | change-close` run local
+  structural checks and return `pass` / `fail` / `needs-review` with real exit codes. They
+  check that the task contract and evidence are present; they do not judge whether the design
+  is correct.
+- **A write guard (Claude).** After `task-start`, a `PreToolUse` hook rejects any edit
+  outside the files the task declared it would touch.
+- **Expectation alignment.** Before specs and tasks are finalized, Keel surfaces hidden
+  assumptions and asks about the ones that actually change behavior.
+
+Keel leans on native capabilities rather than reinventing them. The spec workflow is plain
+OpenSpec. The execution skills, the SessionStart continuity hook, and the write-guard hook
+ship as an ordinary Claude Code / Codex plugin. `keel --init` writes only a small host
+surface into your repo: an `AGENTS.md` bootstrap block, the OpenSpec schema, and the
+`/opsx:*` command overlay.
 
-OpenSpec owns the durable artifacts (proposal, design, specs, tasks, archive). Keel owns the
-*execution discipline* around them: mode routing, the task capsule contract, deterministic
-gates, the write guard, continuity, review, and handoff hygiene.
+## Requirements
 
----
+Node.js `>=20.19.0` (the bundled OpenSpec CLI needs it).
 
-## Requirements
+## Install
 
-- **Node.js `>=20.19.0`** (the bundled OpenSpec CLI requires it; older Node may hit
-  `EBADENGINE`).
+Two pieces: the `keel` CLI and the `keel` plugin.
 
----
+**CLI** — one command (also installs the bundled OpenSpec CLI):
 
-## Install
+```bash
+npm install -g @christang/keel
+keel --version
+```
 
-Keel has two installable pieces: the **`keel` CLI** (context, gates, guard, schema,
-install) and the **`keel` plugin** (execution skills + runtime hooks).
+**Plugin** — the execution skills and runtime hooks:
+
+```bash
+claude plugin install keel@<marketplace>   # Claude Code
+codex plugin add keel@<marketplace>        # Codex
+```
 
-### 1. The `keel` CLI
+<details>
+<summary>Install the latest unreleased build from GitHub</summary>
 
-Pack from GitHub and install globally. This avoids conflicts during Git-dependency
-preparation and installs the bundled OpenSpec CLI.
+Pack the current `main` and install the tarball (skips the npm registry):
 
 **Windows (PowerShell):**
 
@@ -99,97 +86,84 @@ npm pack github:TanglmChris/keel --pack-destination "$tmp_dir"
 npm install -g "$tmp_dir"/christang-keel-*.tgz
 rm -rf "$tmp_dir"
 ```
+</details>
 
-Verify, and self-update later with `keel --update`:
-
-```bash
-keel --version
-keel --update            # re-pack + reinstall the global CLI
-```
-
-### 2. The `keel` plugin (skills + hooks)
+## Use
 
-Execution skills (`keel-*`) and the runtime hooks (SessionStart continuity, the PreToolUse
-write guard) ship as a native plugin — they are **not** copied into your repo by `keel --init`:
-
-```bash
-claude plugin install keel@<marketplace>   # Claude Code
-codex plugin add keel@<marketplace>        # Codex
-```
-
----
-
-## Quick start
-
-From your target project's root:
+In your project's root, set it up once:
 
 ```bash
 keel --init                 # default target: claude
-keel --init --target codex
-keel --init --target opencode
+keel --init --target codex  # or: opencode
 ```
 
-`keel --init` runs OpenSpec init/update and installs Keel's thin host surface. Then, every
-time you start or resume work:
+`keel --init` runs OpenSpec init/update and writes Keel's host surface. Then, every time you
+start or resume work:
 
 ```bash
-keel context                # or: keel context --json
+keel context                # what to do now, recomputed from OpenSpec + Git
+keel --doctor               # check everything is wired up
 ```
 
-It returns `ready` / `ambiguous` / `blocked` / `idle` with the selection, next action, and a
-minimal read list. Check full readiness anytime:
+Do the spec work through OpenSpec's commands (`/opsx:propose`, `/opsx:apply`, `/opsx:sync`,
+`/opsx:archive`). Keel's gates run at the task boundaries. The whole loop:
 
-```bash
-keel --doctor
+```
+keel --init  →  keel context  →  /opsx:apply (pick one task)
+   →  task-start (+ write guard)  →  implement & verify
+   →  task-complete  →  /opsx:sync · /opsx:archive
 ```
 
-### What `--init` writes
-
-`keel --init` / `--install` keeps a **thin host surface** — it does not copy skills or hooks
-(those come from the plugin):
-
-- `AGENTS.md` — Keel bootstrap block (all targets)
-- `CLAUDE.md` — `@AGENTS.md` import block (Claude target)
-- `openspec/config.yaml` — sets `schema: keel-spec-driven`
-- `openspec/schemas/keel-spec-driven/` — the Keel-hardened OpenSpec schema
-- plus the OpenSpec command surface (`/opsx:*`) with the Keel authoring/apply/archive overlay
+### Full vs Lite
 
----
+Use **Full mode** (the OpenSpec flow above) for new features, interface or protocol changes,
+cross-module work, or anything over ~3 files / 100 lines. Use **Lite mode** for local fixes,
+small scripts, docs, or tests with no interface change and locally provable impact; Lite does
+not write OpenSpec state.
 
-## Targets
+## How the agent uses these
 
-| Target | Init command | Command surface |
-| --- | --- | --- |
-| Claude Code | `keel --init` | `.claude/commands/opsx/*.md` + plugin hooks (SessionStart, PreToolUse guard) |
-| Codex | `keel --init --target codex` | global `CODEX_HOME/prompts/opsx-*.md` |
-| OpenCode | `keel --init --target opencode` | project-local `.opencode/commands/opsx-*.md` |
+You rarely type the commands below. The point of Keel is that the discipline runs itself:
+`keel --init` installs it into the agent's own workflow, and the agent reaches for each
+command at the right moment. Three things make that happen.
 
-Pick one target per repo and use it for every subsequent `--install` / `--check` / `--doctor`
-/ `--uninstall`. Capabilities are **probed, not assumed by target name** — unverified runtime
-behavior is reported as `manual`, not `enforced`.
+- **The protocol.** `keel --init` writes a bootstrap block into your repo's `AGENTS.md`
+  (imported by `CLAUDE.md` on Claude). It states the rules the agent follows: open every
+  session with `keel context`, pass the gates at task boundaries, and stay inside the task's
+  declared write scope. That is how the agent knows *when* to run what.
+- **The skills.** The `keel-*` execution skills and the `/opsx:*` command overlays walk the
+  agent through align → apply → review → complete, invoking the gates at each step.
+- **The hooks.** A SessionStart hook runs the continuity projection the moment a session
+  opens; a PreToolUse hook enforces the write guard on every edit. Neither needs prompting.
 
----
+So in day-to-day use you run two commands: `keel --init` once, and `keel --doctor` when you
+want to check the wiring. Everything below is the vocabulary the agent uses on your behalf.
 
-## Full vs Lite mode
+## Domain lenses
 
-**Full mode** — for new features, external interface changes, cross-module work, changes over
-3 files / 100 lines, architecture or protocol/state-machine decisions, or any hardware work
-touching signals, reset, CDC, or security boundaries. Full mode uses OpenSpec for
-proposal → design → specs → tasks → archive.
+Keel's core is pure process; it ships no domain knowledge of its own. Domain guidance lives in
+**lenses** you author under `keel/lenses/*.md` in your repo. Each lens is self-describing: it
+opens with an `Applies when:` line stating the signals that trigger it (file extensions, artifact
+shapes) and carries an `Execution and review checks` section. When a change's artifacts or Touch
+match a lens, the alignment, test, debug, and review skills load only that one lens — and nothing
+when none match. Keel stays domain-agnostic; the knowledge is yours to own and edit.
 
-**Lite mode** — local fixes, small scripts, docs, or test additions only: no interface change,
-no new dependency, no new design decision, locally provable impact. Lite does not write
-OpenSpec state by default.
+Three lenses ship as opt-in templates (`web`, `hardware`, `hardware-dsl`) under `assets/lenses/`.
+They are never installed automatically:
 
----
+```bash
+keel lenses list            # shipped templates + lenses installed in keel/lenses/
+keel lenses add web         # copy the web template into keel/lenses/web.md, then edit it
+keel lenses add web --force # overwrite an existing lens
+```
 
-## Core commands
+## Commands
 
 ```bash
 # Continuity — recompute what to do (stateless)
 keel context [--json] [--change <c> --task <t>]
 
-# Deterministic gates (schemaVersion 1 → pass | fail | needs-review)
+# Deterministic gates → pass | fail | needs-review
 keel gate task-start    --change <c> --task <t> --json
 keel gate task-complete --change <c> --task <t> [--base <git-ref>] --json
 keel gate change-close  --change <c> --action sync|archive --json
@@ -199,52 +173,34 @@ keel guard start --change <c> --task <t> --json
 keel guard status --json
 keel guard clear  --json
 
+# Domain lenses — user-authored guidance in keel/lenses/
+keel lenses list
+keel lenses add <name> [--force]
+
 # Install / maintenance
-keel --init | --install | --check | --doctor | --uninstall   [--target <t>] [--dry-run]
+keel --init | --install | --check | --doctor | --uninstall  [--target <t>] [--dry-run]
 keel --update [--dry-run]
 keel --version | --help
 ```
 
-Exit codes: `0` pass · `3` deterministic policy failure · `4` missing semantic review · `1`
-input/parse failure.
+Exit codes: `0` pass · `3` policy failure · `4` missing semantic review · `1` input error.
 
----
+Targets are probed, not assumed by name: unverified runtime behavior is reported as `manual`,
+not `enforced`. Pick one target per repo and use it for every `--install` / `--check` /
+`--doctor` / `--uninstall`.
 
 ## Development
 
-No build step. `src/skills/` is the single source of truth for portable skills; distribution
-copies under `plugins/keel/skills/` must stay byte-identical (enforced by validation). After
-editing, sync copies and run:
+No build step. `src/skills/` is the single source of truth for portable skills; the
+distribution copies under `plugins/keel/skills/` must stay byte-identical (enforced by
+validation).
 
 ```bash
-npm run validate          # baseline validation
-npm test                  # baseline + all scenarios in parallel (~25s)
-
-# single scenario
-node scripts/run_python.js scripts/validate_plugin.py --scenario core-gates
+npm test                  # baseline + all scenarios in parallel
+node scripts/bump_version.js <patch|minor|major>   # bump every version pin at once
 ```
 
-### Repository layout
-
-```text
-bin/keel.js                # cross-platform keel CLI
-src/core/                   # stateless Keel Core (context, gates, guard, goal, helper, projection)
-src/skills/                 # canonical portable skills (+ keel-align-expectations/references)
-plugins/keel/              # native plugin (.claude-plugin / .codex-plugin, hooks, skills)
-assets/bootstrap/AGENTS.md  # canonical managed bootstrap block
-assets/openspec/            # OpenSpec schema assets
-scripts/                    # install_to_repo.py, validate_plugin.py, run_python.js
-openspec/                   # this repo's own OpenSpec workspace
-keel/                      # project-local Keel state (CHANGELOG, archive)
-```
-
----
-
-## Documentation
-
-- **[中文完整手册 (Chinese full manual)](README.zh-CN.md)** — exhaustive command and workflow reference.
-- **[keel/CHANGELOG.md](keel/CHANGELOG.md)** — version history.
-
 ## License
 
-[MIT](LICENSE) © 2026 TanglmChris
+[MIT](LICENSE) © 2026 TanglmChris. See the **[中文完整手册](README.zh-CN.md)** for the full
+command and workflow reference.