@pablozrrrr/jevguard 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,11 @@
 # JevGuard
 
 > **Semantic policy engine for coding agents.**
+>
+> JevGuard reviews every change an AI coding agent makes against the rules of your
+> repository, written in plain Markdown, and reports `PASS`, `WARN`, or `FAIL` per
+> rule. It runs in the background for OpenCode and Claude Code, never blocks the
+> agent, and never edits your code.
 
 ![JevGuard: semantic policy engine for coding agents](https://raw.githubusercontent.com/pablozr/JevGuard/main/27b864b2-3f64-4211-99dd-26764c549d03.png)
 
@@ -8,6 +13,30 @@ JevGuard checks the code an agent just changed against the policies that matter
 your repository. It uses Jev for a narrow semantic judgment per rule, then applies
 your local deterministic gate to return `PASS`, `WARN`, or `FAIL`.
 
+| Host | Package | Status |
+| --- | --- | --- |
+| [OpenCode](https://opencode.ai) | `@pablozrrrr/jevguard` | Available, targets OpenCode `1.18.32` |
+| [Claude Code](https://claude.com/claude-code) | `@pablozrrrr/jevguard-claude-code` | Available through this repository's plugin marketplace |
+| Codex | — | Planned |
+
+## Quick start
+
+```sh
+# 1. Store your Jev key in the OS credential store (shared by both hosts)
+bunx --package @pablozrrrr/jevguard jevguard login
+
+# 2a. OpenCode: register the plugin in opencode.json
+bunx --package @pablozrrrr/jevguard jevguard install
+
+# 2b. Claude Code: install from the marketplace
+claude plugin marketplace add pablozr/JevGuard
+claude plugin install jevguard@jevguard
+```
+
+Then add your rules to `.jev/rules.md` (in OpenCode, the bundled `jev-init` skill can
+bootstrap them) and keep working with your agent as usual. Details are in
+[Install](#install) and the [Claude Code guide](./docs/configuration.md#claude-code).
+
 ```text
 agent completes a turn
         ↓
@@ -27,13 +56,20 @@ specific policy, and leaves planning, code generation, and correction with the
 coding agent.
 
 > [!WARNING]
-> JevGuard is in active development. The current release targets OpenCode `1.18.32`
-> and evaluates every rule block declared in `.jev/rules.md` plus the `SCOPE-CREEP`
-> and `COMPLEXITY` built-ins. Reviews are background and observe-only: they report
-> results but never alter the agent context or block a task. When remediation is
-> enabled and a review has any `FAIL`, the plugin asks a hidden `jevguard-proposer`
-> subagent for a proposal in an isolated child session and shows a generic toast; the
-> proposer never edits code.
+> JevGuard is in active development. The OpenCode plugin targets OpenCode `2.2.x`
+> (minimum `2.2.2`, `>=2.2.2 <2.3`) through the V2 plugin API and evaluates every rule
+> block declared in `.jev/rules.md` plus the `SCOPE-CREEP` and `COMPLEXITY` built-ins.
+> Reviews are background and observe-only: they report results but never alter the
+> agent context or block a task. When remediation is enabled and a review has any
+> `FAIL`, the plugin asks for a proposal in an isolated, deny-all child session; the
+> proposal never edits code. See [OpenCode 2.2.x limitations](#opencode-22x-limitations).
+> On Claude Code and OpenCode, a user who opts in with `mode: remediate` in their own
+> `claude-code.yaml` or `opencode.yaml` gets a bounded chain of at most 3 visible
+> correction messages to the agent; see
+> [Remediation proposals](docs/configuration.md#remediation-proposals) and
+> [OpenCode `mode: remediate`](docs/configuration.md#opencode-mode-remediate-bounded-chain).
+> The Claude Code plugin is distributed through this repository's marketplace; see the
+> [Claude Code guide](./docs/configuration.md#claude-code).
 
 ## Why JevGuard
 
@@ -165,9 +201,12 @@ concurrency limit caps the plugin instance at two Jev requests in flight, counti
 built-in batch as a single request. Results join the same aggregate in a fixed order:
 rules in source order, then `SCOPE-CREEP`, then `COMPLEXITY`.
 
-Reviews run in the background. The idle event returns as soon as the serialized
-attribution step is scheduled; policy reads, Jev calls, and presentation never sit on
-the agent's critical path.
+Reviews run in the background. The unit of review is one session execution, from
+`session.execution.started` to `session.execution.succeeded`; the event handler returns
+as soon as the serialized attribution step is scheduled, so policy reads, Jev calls,
+and presentation never sit on the agent's critical path. An `interrupted` or `failed`
+execution is not reviewed: the plugin discards it and logs `JevGuard skipped ·
+interrupted|failed`.
 
 ## Safe auto-propose remediation
 
@@ -178,7 +217,7 @@ delivered entirely by the same server plugin.
 
 When `.jev/config.yaml` enables remediation (it is enabled by default) and a review
 contains any `FAIL`, the plugin, after presenting the review, sends one aggregate
-proposal request to a hidden `jevguard-proposer` subagent:
+proposal request to an isolated child session:
 
 - The request aggregates every `FAIL` finding in the review — local `error` rules and
   the `SCOPE-CREEP` built-in — together with the turn's task and its **complete, safe,
@@ -188,28 +227,33 @@ proposal request to a hidden `jevguard-proposer` subagent:
   attributed file is blocked or the patch is oversized, the plugin records no proposal
   at all — even when a rule-scoped `FAIL` exists — because there is no complete safe
   evidence to send. It never falls back to a repository or global diff.
-- The request is sent in an isolated child session parented to the source session. The
-  `jevguard-proposer` subagent has wildcard-deny permissions and wildcard-disabled
-  tools, so it cannot call a tool, edit a file, or produce a patch. It returns a
-  strategy and one manual apply instruction only.
-- `remediation.model` is optional. When set in `.jev/config.yaml`, it selects the
-  proposer model; when it is absent, the proposer inherits the host's model.
-- A generic toast reports that the proposal is ready in the child session. It carries
-  no rule, task, diff, finding, or credential.
+- The request is sent in an isolated child session parented to the source session.
+  The child session is created with wildcard-deny permissions, so it cannot call a
+  tool, edit a file, or produce a patch. It returns a strategy and one manual apply
+  instruction only. No agent is registered for it.
+- The child session always gets an explicit model: `remediation.model` from
+  `.jev/config.yaml` when set, otherwise the model of the source session. When neither
+  is known, no proposal is created and the plugin logs
+  `REMEDIATION_PROPOSAL_SKIPPED_NO_MODEL`.
+- A proposal that does not finish within 120 seconds is interrupted and logged as
+  `REMEDIATION_PROPOSAL_TIMEOUT`.
+- The server plugin has no toast or TUI channel on OpenCode `2.2.x`, so readiness is
+  reported through the structured log only. It carries no rule, task, diff, finding,
+  or credential.
 
 The plugin creates at most one proposal per evaluated turn, and the child session is
 excluded from review for the plugin lifetime, so a proposal can never recurse or
 trigger a second one. A host, model, or toast failure is contained and never changes
 the review. A contained proposal failure — an invalid model specifier, a child-session
-failure, or a prompt failure — shows a generic error toast and writes one structured
+failure, a prompt failure, or a timeout — writes one structured
 `error` log entry carrying only a typed reason code, never any task, diff, finding,
 path, or credential.
 
 The proposer is a strategy step, not an apply step: it never edits code, and nothing
 is applied automatically. You read the proposal, copy its manual apply instruction
-into your normal coding agent, and apply it there. That apply is an ordinary completed
-assistant turn, so the server plugin reviews it normally on the next idle — exactly
-like any other turn.
+into your normal coding agent, and apply it there. That apply is an ordinary
+execution, so the server plugin reviews it normally when it succeeds — exactly like any
+other turn.
 
 The proposal prompt treats the task, paths, diff, rules, and findings as untrusted
 data, and requires a separate explicit confirmation before proposing changes to tests,
@@ -219,8 +263,14 @@ or secret is logged.
 ## Install
 
 Installing `@pablozrrrr/jevguard` does **not** register it with OpenCode by itself.
-OpenCode only loads plugins listed in `plugin: [...]` in `opencode.json`, so register
-the plugin from the installed CLI:
+OpenCode `2.2.x` only loads plugins listed in `plugins: [...]` in `opencode.json`.
+
+> [!WARNING]
+> The `jevguard install` command below still writes the OpenCode `1.x` `plugin` key.
+> Until it is migrated, register the plugin on `2.2.x` with the manual `plugins`
+> entry shown after it.
+
+The installer is run from the installed CLI:
 
 ```sh
 # global config: ~/.config/opencode/opencode.json
@@ -230,10 +280,12 @@ jevguard install
 jevguard install --project
 ```
 
-The installer asks for confirmation, edits only the `plugin` array, and is
-idempotent. It only edits a `plugin` array of plain strings, so OpenCode's
-`[["pkg", { "options": {} }]]` tuple form is a known limitation: the installer leaves
-the file unchanged and prints the manual snippet instead. If `jevguard` is not on
+The installer asks for confirmation, edits only the `plugins` array, and is
+idempotent. It never writes the legacy `plugin` key, but an entry already there counts
+as installed. It only edits a `plugins` array of package strings or
+`{ "package": "..." }` objects; any other shape is left unchanged and the installer
+prints the manual snippet instead. `jevguard doctor` also checks that
+`opencode --version` is in the supported range `>=2.2.2 <2.3`. If `jevguard` is not on
 `PATH`, run it through `bunx`:
 
 ```sh
@@ -243,7 +295,7 @@ bunx --package @pablozrrrr/jevguard jevguard install
 The manual alternative is one entry in `opencode.json`:
 
 ```json
-{ "plugin": ["@pablozrrrr/jevguard"] }
+{ "plugins": ["@pablozrrrr/jevguard"] }
 ```
 
 OpenCode resolves the package from the npm registry or its cache and loads it on the
@@ -258,9 +310,9 @@ after changing the plugin list.
 ### Build the local artifact
 
 The artifact ships the plugin as a **locally packed tarball** that bundles the
-private `@jevguard/core` and `@jevguard/opencode-adapter` workspace code, so a
-clean consumer installs one tarball and never resolves a workspace link or a
-private registry package. It also packages the `jevguard-rules` and `jev-init`
+private `@jevguard/core`, `@jevguard/node-infra` and `@jevguard/opencode-adapter`
+workspace code, so a clean consumer installs one tarball and never resolves a
+workspace link or a private registry package. It also packages the `jevguard-rules` and `jev-init`
 skills and their private validators under `skills/<name>/`.
 
 Build the tarball from this repository:
@@ -282,12 +334,12 @@ does not vendor them and does not promise an offline install.
 
 ### Load the plugin
 
-OpenCode `1.18.32` resolves a **bare** `opencode.json` `plugin` entry from the npm
+OpenCode `2.2.x` resolves a **bare** `opencode.json` `plugins` entry from the npm
 registry or its cache:
 
 ```json
 {
-  "plugin": ["@pablozrrrr/jevguard"]
+  "plugins": ["@pablozrrrr/jevguard"]
 }
 ```
 
@@ -301,18 +353,36 @@ bun add /path/to/pablozrrrr-jevguard-<version>.tgz
 
 ```ts
 // .opencode/plugins/jevguard.ts
-export { JevGuardPlugin } from "@pablozrrrr/jevguard";
+export { default } from "@pablozrrrr/jevguard";
 ```
 
 OpenCode loads `.opencode/plugins/` with its bundled Bun runtime. The shim runs as
 a local plugin module and resolves `@pablozrrrr/jevguard` from
-`.opencode/node_modules`. Use either the bare `plugin` entry or the local shim, not
+`.opencode/node_modules`. Use either the bare `plugins` entry or the local shim, not
 both.
 
-Remediation is built into the same server plugin: the `config` hook registers the
-hidden `jevguard-proposer` subagent, so no second entrypoint or shim is needed. The
-server plugin reviews and reports turns, and — when remediation is enabled and a review
-fails — creates the proposal child session automatically.
+The package's default export is the V2 plugin object (`{ id: "jevguard", setup }`).
+Remediation is built into the same server plugin, so no second entrypoint or shim is
+needed: it reviews and reports executions, and — when remediation is enabled and a
+review fails — creates the proposal child session automatically. The bundled skills are
+registered through the host skill editor (`skill.transform`).
+
+### Claude Code
+
+Inside Claude Code:
+
+```text
+/plugin marketplace add pablozr/JevGuard
+/plugin install jevguard@jevguard
+```
+
+The Claude Code plugin reviews each closed unit of work in a detached background
+worker, shows the result in the session (status line, transcript line, and a toast on
+`FAIL`) without sending it to the model, and records it in the same local history.
+Remediation proposals are off by default and are enabled from your user config, never
+from the repository. It needs `node` `>=22.13.0`, `npm`, and `git` on `PATH`. See the
+[Claude Code guide](./docs/configuration.md#claude-code) for what is reviewed, the
+in-session display, and remediation.
 
 ### Author rules with the bundled skill
 
@@ -361,11 +431,36 @@ jevguard login
 
 Known limitations:
 
-- Target host is OpenCode `1.18.32`. Exact `1.18.32` runtime smoke is still
-  pending; a local `1.18.28` run worked.
+- Target host is OpenCode `2.2.x` (minimum `2.2.2`). The plugin does not load on
+  `2.1.x` or `1.x`. A real-host smoke on `2.2.2` (2026-11-02) covered observe
+  and `remediate` (FAIL review, deny-all proposer, attempt 1/2, `RESOLVED`).
+- OpenCode `2.2.2` does not install dependencies for a `file:` plugin spec. Use
+  the registry package; a local `file:` build needs its dependencies installed
+  next to it.
 - The plugin and CLI run on Bun, and the packed `jevguard` bin keeps a Bun
   shebang. Install and run the artifact with the Bun runtime.
 
+### OpenCode 2.2.x limitations
+
+- **Minimum version `2.2.2`.** The plugin declares `engines.opencode` `>=2.2.2 <2.3`
+  and is pinned to the `2.2.x` plugin API.
+- **Git-ignored files are out of scope.** The execution snapshot comes from the host's
+  working-tree diff, which leaves out files ignored by Git; a write the diff cannot
+  show makes the execution `UNAVAILABLE` (`INCOMPLETE_FILE_DIFF`) instead of reviewing
+  a partial patch.
+- **Interrupted or failed executions are not reviewed.** Their writes stay on disk and
+  count as pre-existing changes for the next execution's snapshot, so they are not
+  attributed to it.
+- **`opencode run --standalone`.** The review runs after the execution succeeds; a
+  standalone run can exit before it finishes. JevGuard reviews reliably in the TUI or
+  with `opencode serve` plus `opencode run --server`.
+- **Concurrent executions.** When two sessions run at once, or an execution starts
+  while the previous one is still being finished, the review is `UNAVAILABLE`
+  (`CONCURRENT_SESSIONS`, `BOUNDARY_RACE`) instead of mixing changes. Nested child
+  sessions count as part of their parent execution.
+- **No toast or TUI routing.** The server plugin reports through structured logs
+  written to the host's stderr capture.
+
 ## Connect Jev
 
 For local use, connect once with the installed command:
@@ -390,8 +485,8 @@ JevGuard FAIL
 pass 1 · warn 1 · fail 1 · skipped 0 · unavailable 0
 ```
 
-One toast per turn shows the aggregate outcome and the outcome counts; the
-structured log carries every rule's result, its raw violation probability or typed
+The structured log (and, on hosts with a toast channel, one toast per turn) shows
+the aggregate outcome and the outcome counts; the structured log carries every rule's result, its raw violation probability or typed
 reason, and its scoped paths. The counts include every entry, including the single
 synthetic entry a review-level failure produces.
 
@@ -427,6 +522,65 @@ The report prints aggregated counts, rule IDs, check IDs, and reason codes only
 never file paths, tasks, diffs, or credentials. A missing or empty history is a
 normal empty report, not an error.
 
+### Rule feedback
+
+Tell JevGuard whether a `FAIL` was right. The answer is stored locally and only
+feeds the calibration shown by `jevguard report`; it never changes a rule, a
+threshold, or what the model returns.
+
+```sh
+# unanswered rule FAILs, newest first, numbered
+jevguard feedback
+
+# answer one: right = a real violation, wrong = a false alarm
+jevguard feedback 1 wrong
+```
+
+Numbers stay fixed to the last listing. Built-in checks are not covered. See
+[configuration](./docs/configuration.md)
+for details.
+
+## Diagnose your setup
+
+`jevguard doctor` checks your local setup without touching the network or changing
+anything:
+
+```sh
+jevguard doctor
+jevguard doctor --json
+```
+
+It reports `OK`, `WARN` or `FAIL` for the credential source, `.jev/rules.md`,
+`.jev/config.yaml` and the OpenCode plugin registration, each with a hint when
+something is wrong. It never prints the API key or any part of it — only whether the
+key comes from the OS credential store or the `TYPESAFE_API_KEY` override. It exits
+`0` unless a check fails (warnings are fine) and `1` when one does. The project root is
+the first parent directory of the current directory that contains `.git`, or the
+current directory when there is none. It does not check Claude Code installs yet.
+
+## Check rules on demand
+
+`jevguard rules check` runs your repository rules against a diff you provide, without
+waiting for an agent turn:
+
+```sh
+git diff --cached | jevguard rules check --diff - --task "Add rate limiting to login"
+jevguard rules check --diff change.diff --rule ARCH-001 --json
+```
+
+It evaluates the repository rules over the diff with the same scope filtering,
+evidence safety, slicing and gate thresholds as a review, but runs no built-in checks,
+starts no remediation and writes nothing to the review history. The input must be
+plain `git diff` output (or a plain `---`/`+++` unified diff) with `a/` and `b/`
+prefixes; anything else is refused whole, never partly evaluated (see
+[configuration](./docs/configuration.md#cli-diagnostics-and-on-demand-rule-checks)).
+`--task` is optional; without it a neutral default task is sent. It prints each rule's outcome, probability, severity and
+scoped paths, never the task or the diff. Exit codes: `0` completed with no `FAIL` and
+no `UNAVAILABLE`; `1` at least one rule `FAIL`ed; `2` it could not check completely
+(invalid arguments, an unreadable or unsupported diff, an unknown `--rule`, or an
+`UNAVAILABLE` result). See [configuration](./docs/configuration.md#cli-diagnostics-and-on-demand-rule-checks)
+for the full contract.
+
 ## Implemented behavior
 
 The current release implements the full local review path:
@@ -466,20 +620,20 @@ The current release implements the full local review path:
   attributed patch a built-in is `SKIPPED`; blocked or oversized evidence is
   `UNAVAILABLE`; a rule, policy-load, or config failure never suppresses the batch, and
   one built-in's answer never suppresses the other.
-- Reviews run in the background. The idle event resolves as soon as the serialized
-  attribution step is scheduled, so policy reads, Jev calls, and presentation do not
-  block the agent.
+- Reviews run in the background. The `session.execution.succeeded` handler returns
+  as soon as the serialized attribution step is scheduled, so policy reads, Jev calls,
+  and presentation do not block the agent.
 - The local gate maps each rule to `PASS`, `WARN`, or `FAIL`; a rule with no
   applicable scope is `SKIPPED`, and a rule that cannot be safely evaluated is
   `UNAVAILABLE`.
-- One aggregate TUI toast and one structured log entry report the turn. The log
+- One structured log entry reports the turn (the `2.2.x` server plugin has no toast
+  channel). The log
   carries every entry's outcome, raw probability, or reason, including the built-in
   results and the synthetic review-level entry when there is one. The fixed result
   order is rules in source order, then `SCOPE-CREEP`, then `COMPLEXITY`.
 - After presentation, when remediation is enabled and the review contains any `FAIL`,
-  at most one aggregate proposal request is sent to the hidden `jevguard-proposer`
-  subagent in an isolated child session parented to the source session, and a generic
-  toast reports that the proposal is ready. The request carries every `FAIL` finding
+  at most one aggregate proposal request is sent to an isolated, deny-all child
+  session parented to the source session, with an explicit model. The request carries every `FAIL` finding
   (local `error` rules and the `SCOPE-CREEP` built-in), the task, and the complete,
   safe, full attributed patch; a blocked or oversized patch records no proposal. A
   notifier or host failure never affects the review, presentation, or later turns.
@@ -491,30 +645,25 @@ ordinary turn is reviewed normally.
 
 ## Roadmap
 
-The multi-rule, scope-creep, and complexity slices are implemented. Planned work
-beyond them:
+Implemented so far: multi-rule reviews, the `SCOPE-CREEP` and `COMPLEXITY`
+built-ins, the `jev-init` policy bootstrap, local review history with feedback and
+calibration (`jevguard report`, `jevguard feedback`), on-demand checks
+(`jevguard rules check`, `jevguard doctor`), and the Claude Code plugin. Planned work:
 
 ```text
-V0.3  Remaining built-in semantic check: test adequacy
-  ↓
-V0.4  jev-init: evidence-based policy bootstrap
-  ↓
-V0.5  On-demand evidence and explanations
-  ↓
-V0.6  Opt-in, bounded auto-remediation
-  ↓
-V0.7  Observe / enforce / remediate modes
-  ↓
-V0.8  Rule packs
-  ↓
-V0.9  Local feedback and calibration
-  ↓
-V1    Claude Code and Codex adapters
+V0.3  Remaining built-in semantic check: test adequacy        planned
+V0.4  jev-init: evidence-based policy bootstrap               done
+V0.5  On-demand evidence and explanations                     partial (rules check)
+V0.6  Opt-in, bounded auto-remediation                        planned
+V0.7  Observe / enforce / remediate modes                     planned
+V0.8  Rule packs                                              planned
+V0.9  Local feedback and calibration                          done
+V1    Claude Code and Codex adapters                          Claude Code done, Codex planned
 ```
 
 The auto-propose slice is implemented: after a review with a `FAIL`, an enabled
-configuration asks the hidden `jevguard-proposer` subagent for a strategy in an
-isolated child session, and never applies a change. The `V0.6` entry remains the
+configuration asks for a strategy in an isolated, deny-all child session, and never
+applies a change. The `V0.6` entry remains the
 future, unattended corrective loop; the proposer is a bounded, strategy-only step, not
 that loop.
 
@@ -527,17 +676,24 @@ CI and pull-request policy review come after V1, using the same versioned rules.
 
 ## Architecture
 
-JevGuard is a pnpm TypeScript monorepo. The core has no dependency on OpenCode or
-its runtime, which keeps the evaluation model portable to future adapters.
+JevGuard is a pnpm TypeScript monorepo. The core has no dependency on OpenCode,
+Claude Code, or their runtimes, which keeps the evaluation model portable across
+host adapters.
 
 ```text
 packages/
 ├── core/                 domain, policy, evaluation, gate
+├── claude-code-adapter/  Claude Code tool-attributed units, hook and review worker
+├── claude-code-plugin/   Claude Code plugin composition and artifact
+├── node-infra/           shared Node infra: credentials, Jev transport, policy, history
 ├── opencode-adapter/     OpenCode attribution and presentation
 ├── plugin/               OpenCode composition root and CLI
 └── testkit/              fixtures and contract helpers
 
-plugin → opencode-adapter → core
+plugin → opencode-adapter → node-infra → core
+plugin ────────────────────→ node-infra
+claude-code-plugin → claude-code-adapter → node-infra → core
+testkit ──────────────────────────────→ core
 ```
 
 ## Status
@@ -548,18 +704,23 @@ loads in OpenCode, attributes one completed turn, parses every rule block in
 the `SCOPE-CREEP`
 and `COMPLEXITY` built-ins over the complete attributed patch behind one shared
 concurrency limit, applies the local gate to each, and presents one aggregate result
-as a transient TUI toast and a structured log entry.
+as a structured log entry.
 
 The local, private tarball (`pnpm artifact:build`, `pnpm artifact:pack`) packages
 that slice so a clean consumer can install it without workspace links.
 
-OpenCode sees only transient toasts, structured logs, and — when remediation is
-enabled and a review has a `FAIL` — one proposal child session and a generic toast.
+OpenCode sees only structured logs and — when remediation is enabled and a review
+has a `FAIL` — one proposal child session.
 The review does not inject anything into the agent context, prompt the source session,
 add session messages, or block a task. The proposal is a separate, configurable,
 strategy-only workflow delivered by the server plugin; it never edits code and never
-applies a change. Real-host validation against exact OpenCode `1.18.32` is still
-pending.
+applies a change. A real-host smoke on OpenCode `2.2.2` passed; see
+[OpenCode 2.2.x limitations](#opencode-22x-limitations).
+
+The Claude Code plugin reuses the same core, policy files, gate, and local history. It
+reviews closed units of work in a detached worker and shows results in the session
+without sending them to the model; see the
+[Claude Code guide](./docs/configuration.md#claude-code).
 
 ## Development