@pablozrrrr/jevguard 0.1.0 → 0.2.2

package/README.md

@@ -27,10 +27,13 @@ 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.31`,
-> evaluates every rule block declared in `.jev/rules.md` plus the `SCOPE-CREEP` and
-> `COMPLEXITY` built-ins, and runs in observe mode only: it reports results but never
-> alters the agent context or blocks a task.
+> 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.
 
 ## Why JevGuard
 
@@ -122,7 +125,7 @@ malformed answer fails only its own check.
 `SCOPE-CREEP` asks whether the change contains material functional, behavioral,
 architectural, dependency, configuration, documentation, or refactoring work the task
 did not request and that is not reasonably necessary to complete it. It uses fixed
-`error` thresholds (`40%`/`70%`), independent of `.jev/config.yaml`.
+`error` thresholds (`65%`/`90%`), independent of `.jev/config.yaml`.
 
 `COMPLEXITY` asks whether the change introduces material complexity disproportionate
 to, or not reasonably necessary for, completing the task, such as unnecessary
@@ -140,32 +143,99 @@ 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.
 
+## Safe auto-propose remediation
+
+Reviews are observe-only by default: a review never injects feedback into the agent
+context, adds a session message, prompts a session, blocks a turn, or changes your
+code. A separate, configurable path can turn a review result into a proposal, and it is
+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:
+
+- 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,
+  full attributed patch**. `COMPLEXITY` is advisory and never fails, and `warning`
+  rules never fail.
+- The full attributed patch must pass the same safety policy as the review. If any
+  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 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
+`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.
+
+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,
+configuration, or dependencies. No secret is ever carried, and no payload, task, diff,
+or secret is logged.
+
 ## Install
 
-Once `@pablozrrrr/jevguard` is published to npm, the intended install is one line in
-`opencode.json`:
+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:
+
+```sh
+# global config: ~/.config/opencode/opencode.json
+jevguard install
+
+# project config: ./opencode.json
+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
+`PATH`, run it through `bunx`:
+
+```sh
+bunx --package @pablozrrrr/jevguard jevguard install
+```
+
+The manual alternative is one entry in `opencode.json`:
 
 ```json
 { "plugin": ["@pablozrrrr/jevguard"] }
 ```
 
-OpenCode then resolves the package from the npm registry or its cache and loads it
-on the next start. Adding the entry only loads the plugin; it does **not** put the
-`jevguard` CLI on `PATH` (see [Install the CLI](#install-the-cli)). Restart
-OpenCode after changing the plugin list.
+OpenCode resolves the package from the npm registry or its cache and loads it on the
+next start. Adding the entry only loads the plugin; it does **not** put the
+`jevguard` CLI on `PATH` (see [Install the CLI](#install-the-cli)). Restart OpenCode
+after changing the plugin list.
 
 > [!IMPORTANT]
-> `@pablozrrrr/jevguard` is **not published to npm yet**. The one-line entry above is
-> future behavior and will not resolve until the package is released. Before
-> publication, load the plugin as a local artifact plugin instead.
+> A bare plugin entry resolves only from the npm registry. To run an unreleased
+> local build, load the packed tarball as a local artifact plugin instead.
 
 ### 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` skill and its
-private rule validator under `skills/jevguard-rules/`.
+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:
 
@@ -184,12 +254,19 @@ The packed manifest depends only on public runtime packages
 the tarball therefore needs npm registry access for those packages; the artifact
 does not vendor them and does not promise an offline install.
 
-### Load the local plugin before publication
+### Load the plugin
 
-OpenCode `1.18.31` resolves a **bare** `opencode.json` `plugin` entry from the npm
-registry or its cache, not from the consumer's `node_modules`. Until the package is
-published, install the tarball into the project's `.opencode` directory and load it
-through a local plugin shim:
+OpenCode `1.18.32` resolves a **bare** `opencode.json` `plugin` entry from the npm
+registry or its cache:
+
+```json
+{
+  "plugin": ["@pablozrrrr/jevguard"]
+}
+```
+
+To run an unreleased local build instead, install the packed tarball into the
+project's `.opencode` directory and load it through a local plugin shim:
 
 ```sh
 cd /path/to/consumer/.opencode
@@ -203,16 +280,28 @@ export { JevGuardPlugin } 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`. Do **not** add `@pablozrrrr/jevguard` to the `opencode.json`
-`plugin` list before publication; that bare entry does not resolve locally.
+`.opencode/node_modules`. Use either the bare `plugin` 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.
 
 ### Author rules with the bundled skill
 
-The package ships a `jevguard-rules` OpenCode skill beside the plugin. On startup
-the plugin's `config` hook appends the installed skill directory to the host's
-`skills.paths`, so the skill is discovered without a manual `opencode.json` entry.
-Skill discovery is read at OpenCode startup: restart OpenCode after installing or
-updating the package so the skill appears.
+The package ships two OpenCode skills beside the plugin: `jevguard-rules` to author
+rules, and `jev-init` to bootstrap a policy where none exists. On startup the plugin's
+`config` hook appends the installed skill directories to the host's `skills.paths`, so
+the skills are discovered without a manual `opencode.json` entry. Skill discovery is
+read at OpenCode startup: restart OpenCode after installing or updating the package so
+the skills appear.
+
+`jev-init` runs only when neither `.jev/rules.md` nor `.jev/config.yaml` exists. It
+reads a bounded inventory of the repository, keeps rules only from the user's explicit
+constraints and strongly evidenced local conventions, records provenance in a preamble,
+and previews both candidate files before requiring explicit confirmation naming both
+exact paths. Once a policy exists, every rule change belongs to `jevguard-rules`.
 
 Policy content is different. `.jev/rules.md` and `.jev/config.yaml` are read once
 per attributed turn, so editing rule text takes effect on the next reviewed turn
@@ -223,8 +312,8 @@ Jev.
 
 ### Install the CLI
 
-Loading the plugin does not expose the `jevguard` binary on `PATH`. Once the
-package is published, run the login command without a global install:
+Loading the plugin does not expose the `jevguard` binary on `PATH`. Run the login
+command without a global install:
 
 ```sh
 bunx --package @pablozrrrr/jevguard jevguard login
@@ -237,7 +326,7 @@ bun install --global @pablozrrrr/jevguard
 jevguard login
 ```
 
-Until the package is published, install the local tarball globally instead:
+To run an unreleased local build, install the packed tarball globally instead:
 
 ```sh
 bun install --global /path/to/pablozrrrr-jevguard-<version>.tgz
@@ -246,9 +335,7 @@ jevguard login
 
 Known limitations:
 
-- `@pablozrrrr/jevguard` has no registry release yet, so the one-line `opencode.json`
-  plugin entry does not resolve until the package is published.
-- Target host is OpenCode `1.18.31`. Exact `1.18.31` runtime smoke is still
+- Target host is OpenCode `1.18.32`. Exact `1.18.32` runtime smoke is still
   pending; a local `1.18.28` run worked.
 - 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.
@@ -288,7 +375,7 @@ safely or completely evaluate that rule.
 
 ## Implemented behavior
 
-The current release implements the full local, observe-only path:
+The current release implements the full local review path:
 
 - OpenCode V1 plugin loads.
 - A completed assistant response is detected.
@@ -330,9 +417,18 @@ The current release implements the full local, observe-only path:
   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`.
-
-No feedback is injected into the agent session. No remediation is attempted. No
-task is blocked.
+- 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
+  (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.
+
+The review itself injects no feedback into the agent session, prompts no session, and
+blocks no task. The proposal above is a strategy only; nothing is applied, and
+the user copies its manual apply instruction into their normal coding agent, whose
+ordinary turn is reviewed normally.
 
 ## Roadmap
 
@@ -357,6 +453,17 @@ V0.9  Local feedback and calibration
 V1    Claude Code and Codex adapters
 ```
 
+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
+future, unattended corrective loop; the proposer is a bounded, strategy-only step, not
+that loop.
+
+The `V0.4` `jev-init` skill is implemented: when no policy exists it bootstraps
+`.jev/rules.md` and `.jev/config.yaml` from the user's explicit constraints and
+strongly evidenced local conventions, records each rule's provenance, and writes both
+files only after validating the confirmed candidates.
+
 CI and pull-request policy review come after V1, using the same versioned rules.
 
 ## Architecture
@@ -376,9 +483,10 @@ plugin → opencode-adapter → core
 
 ## Status
 
-The multi-rule, multi-built-in, observe-only review is implemented. It loads in
-OpenCode, attributes one completed turn, parses every rule block in `.jev/rules.md`,
-asks Jev once per applicable rule and once per built-in batch, runs the `SCOPE-CREEP`
+The multi-rule, multi-built-in, background and observe-only review is implemented. It
+loads in OpenCode, attributes one completed turn, parses every rule block in
+`.jev/rules.md`, asks Jev once per applicable rule and once per built-in batch, runs
+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.
@@ -386,9 +494,13 @@ as a transient TUI toast and 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 and structured logs. JevGuard does not inject
-anything into the agent context, does not add session messages, and does not block
-a task. Real-host validation against exact OpenCode `1.18.31` is still pending.
+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.
+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.
 
 ## Development