diff --git a/README.md b/README.md index ddab7e9..b916f37 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,9 @@
-

context-report: signed evidence that an agent plugin works. Reachability, fault behaviour, cost and efficacy for plugins, hooks, skills and MCP servers, as rows anyone can re-derive.

+

context-report wordmark and mark on a dusk-blue background.

-
Text version - # Teach your AI agent what not to do. Open-source guardrails for AI coding agents: rules the agent reads, checks that run as it writes, and gates at commit and in CI. context-report is the evidence arm: an open, signed report of whether an agent plugin, hook, skill or `AGENTS.md` actually works. @@ -16,11 +14,6 @@ Open-source guardrails for AI coding agents: rules the agent reads, checks that `context-report` is an open, signed report format for one question: **does this agent context artifact actually work?** A plugin, hook, skill, `AGENTS.md` or MCP server gets one row per measured fact, each row declaring whether it is recomputable by anyone or only claimed by the author, and never a single pass or fail for the artifact as a whole: the consumer sets its own thresholds. Free and open source (Apache-2.0). -
- -

Nine areas Chock checks, application security first, each with the policies that cover it and whether they enforce at commit, in the agent, or only advise.

-
Text version - ## Application security for the code your agents write A guard is only a guard if it starts. Chock's checks refuse known classes of flaw as the agent writes, at commit and in CI; many of them ship as agent plugins and hooks, and nobody records whether such an artifact reaches the agent at all, how it fails when it cannot run, or what it costs. context-report is the evidence for that: a predicate an author's CI produces and a catalog verifies at submission. A rule an agent reads is advice; a hook that exits non-zero is a control; context-report measures which one you actually have. The findings are under What it stops, below. @@ -39,8 +32,6 @@ A guard is only a guard if it starts. Chock's checks refuse known classes of fla **No LLM, no tokens in the producer.** `context-report produce` (reachability, cost and fault rows) runs the subject's own hook command on recorded payloads; nothing under `src/context_report/produce` imports a networking or model module (`grep -rln "urllib\|anthropic\|http.client\|socket\|requests" src/context_report/produce`, empty at `5fbef7b`). Only the efficacy path, `context-report run`, calls the subject and judge models you configure. Chock adds no new place your code goes, and a report is a set of hashes and measurements. -
- ## Install chock is on PyPI, but the release there (0.15.2, 30 Sep 2026) is older than the engine this page describes. Install the frozen engine from its commit (Python 3.11 or newer): @@ -49,9 +40,6 @@ chock is on PyPI, but the release there (0.15.2, 30 Sep 2026) is older than the pip install "chock @ git+https://github.com/open-coder-ai/chock@992711af4cf8d4fd9c4c861f10ef6e53374d75d7" ``` -

Two adoption routes: in your repository with chock init, chock add and chock sync, or in your coding agent as plugins.

-
Text version - ### Two ways to adopt it 1. **In your repository, for teams.** Run `chock init .`, then `chock add --ref --verify-sha --skip-compile` for each policy, then `chock sync --repo . --ci`. Commit the result. Every clone runs `chock sync --repo .` once, because git never clones hooks. The commit gates are enforced at commit and in CI. @@ -144,11 +132,6 @@ tasks — and `context-report compare` puts every run of that manifest side by s [`docs/cli.md`](docs/cli.md) for the manifest schema, `--dry-run`/`--n`/`--resume`, and which model providers a manifest can reach. -
- -

The stack: evidence on top, then your agents, plugins, the chock-catalog policies, chock, agentseam and the templates, one layer each.

-
Text version - ## How it works | Layer | What it is | @@ -161,7 +144,6 @@ model providers a manifest can reach. | agentseam | The primitives: one handler API over each agent's hooks, instruction files, plugin packaging and config. | | Templates | chock-quickstart is what `chock init` leaves behind. chock-example is a working adoption. | - A producer runs the artifact's own hook command against recorded per-target payloads and writes one row per fact. A verifier recomputes each `re-derivable` row from the subject and checks the statement is well-formed and bound to the artifact by digest. Trimmed from a committed statement over a real public plugin @@ -298,17 +280,10 @@ oracle where one is on file (none yet for `codex_cli` — see | `copilot` | reachability · cost · fault (malformedOutput measured; scriptMissing/interpreterMissing/timeout `NotAvailable`, oracle on file) | `com.github.copilot/hooks/hooks.json` | | `cursor` | reachability · cost · fault (malformedOutput measured; scriptMissing/interpreterMissing/timeout `NotAvailable`, oracle on file) | `hooks/hooks.json` | -
- -

Guardrails, not guarantees: the three tiers, no matrix cell graded enforced, and no OWASP Agentic risk fully covered.

-
Text version - ## Guardrails, not guarantees Tiers: `commit` is a git hook or CI gate that exits non-zero. `in-agent` is the agent's pre-tool hook: best-effort, and it fails open. `advisory` is rule text the agent reads. No agent reaches `enforced` today. OWASP mappings are partial and the engine is frozen at the commit above. Chock does not stop every attack, and context-report does not stop any: it closes common, known entry points before they ship and makes a guard's failure visible. -
- ## FAQ for people and agents **Does context-report use an LLM?** The producer for reachability, cost and fault rows does not: it makes no model call. Efficacy rows use the subject and judge models you configure in a manifest; without one the row says `NotAvailable`. @@ -334,9 +309,6 @@ Tiers: `commit` is a git hook or CI gate that exits non-zero. `in-agent` is the - [`registry.yaml`](https://github.com/open-coder-ai/chock-catalog/blob/main/registry.yaml) and [`docs/coverage.md`](https://github.com/open-coder-ai/chock-catalog/blob/main/docs/coverage.md): the catalog's policies and coverage. - [`.claude-plugin/marketplace.json`](https://github.com/open-coder-ai/chock-claude-plugins/blob/main/.claude-plugin/marketplace.json): the Claude plugin marketplace. -

The 13 public repositories of open-coder-ai: core, policies, evidence, plugins, templates and community files.

-
Text version - ## Part of open-coder-ai The 13 public repositories: @@ -383,4 +355,3 @@ merge either way. Apache-2.0. See [LICENSE](LICENSE). -