@mrciphersmith/keryx 0.3.6 → 0.3.8

package/README.md

@@ -129,6 +129,11 @@ with [Onboarding](docs/docs/onboarding.md) for the complete first-run
 walkthrough. `keryx help` groups every command by task; the same table is a
 generated reference page, [Commands by task](docs/docs/commands-by-task.md).
 Run `keryx <command> --help` for the live flag surface of any command.
+Delivery orchestrators can also ask Jev to flag rule-breaking edits and triage
+failed CI jobs — see [Jev in the delivery loop](docs/docs/guides/jev-in-the-delivery-loop.md).
+The review orchestrator can ask Jev to triage CI and pick which reviewers to
+dispatch — see [Jev in review](docs/docs/jev-in-review.md) for what was
+measured and what was not.
 
 ## Why keryx
 
@@ -754,6 +759,47 @@ The seams exist for the model-backed variants when they ship.
 Tree-sitter grammars for the symbol/call graph are downloadable and optional; the
 graph falls back to its deterministic resolver when a grammar is absent.
 
+## Jev EDIT GUARD (opt-in)
+
+A Claude Code `PostToolUse` hook that checks every `Edit`/`Write`/`MultiEdit` a
+coding agent makes against your project's own written rules, using Jev, and
+feeds violations straight back to the agent through the hook's
+`additionalContext` channel — before the code ever reaches a human reviewer.
+It never blocks the tool call: on any error, timeout, or missing credential
+it fails open silently and always exits `0`.
+
+Measured on a real project (10 tasks × 2 runs, a large production
+React/MobX frontend):
+
+| | violations reaching first review | review rounds | Jev cost |
+|---|---|---|---|
+| without the guard | 27 | 31 | — |
+| with the guard (threshold 0.5) | **10 (−63%)** | **24** | $0.04 for 40 runs |
+
+The agent acted on 79% of the flags at threshold 0.5. At threshold 0.2 the
+guard flagged almost every edit, the agent learned to ignore it, and it had
+no measurable effect — so **precision matters more than recall here**, and
+`0.5` is the default for exactly that reason. Raise it if the guard still
+flags too much for your rule set; lower it only if you have evidence the
+agent is actually acting on the extra flags.
+
+```bash
+keryx review jev-edit-guard install   # merge-safe: writes .claude/settings.json
+```
+
+Then opt in per project — the hook is installed but stays silent until this is set:
+
+```json
+// .metaproject/tasks.config.json
+{ "review": { "jev": { "edit_guard": true, "edit_guard_threshold": 0.5 } } }
+```
+
+`keryx review jev-edit-guard status` shows whether it is on, the threshold,
+and today's calls/flags/cost. The TUI's `/editguard` shows the same, plus the
+most recent flags, with a one-key toggle. `keryx review jev-edit-guard
+uninstall` removes only this hook's entry, leaving every other hook
+untouched.
+
 ## Current limitations
 
 | Limitation | Impact | Alternative |
@@ -823,6 +869,7 @@ Full documentation site: **<https://mrciphersmith.github.io/keryx/>**
 - **[Architecture](docs/docs/architecture.md)** — the four-layer pattern, invariants, cross-module data flows.
 - **[Module reference](docs/docs/modules.md)** — one section per module: purpose, CLI surface, mechanics, data paths.
 - **[CLI reference](docs/docs/cli-reference.md)** — the command surface: subcommands, flags and exit codes.
+- **[Jev in review](docs/docs/jev-in-review.md)** — what we measured putting Jev in the review domain: CI triage (proven), three CLI-engine reviewers (measured weaker than a strong model), and reviewer selection (unmeasured, most promising).
 - **[Workspace & lifecycle](docs/docs/workspace-and-lifecycle.md)** — the `.metaproject/` contract and `init`/`update` lifecycle.
 - **[Limitations](docs/docs/limitations.md)** — known gaps, platform caveats, and what to do instead.
 - **[Shared Agent Context](docs/docs/guides/shared-agent-context.md)** *(experimental)* — local-first work-context layer: FWK overview, proposals, runtime policy guard.