avouch 0.1.22 → 0.1.24

package/README.md

@@ -30,18 +30,31 @@ Read in this order:
 
 ## Adopting Avouch
 
-Start with step 0, then do the two steps, in this order.
+Start with step 0, then do the three steps, in this order.
 
-0. At the top level of the git repository, run `npx -y avouch init`. It installs the Claude Code plugin (see "Claude Code plugin") and adds the Avouch instructions for coding agents. The instructions tell an agent to read the rules with `avouch query`, not with a text tool, and to run `avouch check` and `avouch gate docs` after a change. There are two modes: `--append` adds the instructions to `AGENTS.md` and `CLAUDE.md`, if they exist; `--print` writes them to the terminal, and you add them yourself. Without a flag, `init` asks in a terminal and prints otherwise. `--dry-run` shows what would change and writes nothing. Then run `/avouch:scan` in Claude Code, which drafts `avouch.config.json`, a first ontology and the document review ledger. See "init" in "Command line".
+0. At the top level of the git repository, run `npx -y avouch init`. It installs the plugin for Claude Code and for Codex (see "Claude Code and Codex plugin") and adds the Avouch instructions for coding agents. The instructions tell an agent to read the rules with `avouch query`, not with a text tool, and to run `avouch check` and `avouch gate docs` after a change. There are two modes: `--append` adds the instructions to `AGENTS.md` (it creates the file when it is missing) and to `CLAUDE.md` if it exists; `--print` writes them to the terminal, and you add them yourself. Without a flag, `init` asks in a terminal and prints otherwise. `--dry-run` shows what would change and writes nothing. Then run `/avouch:scan` in Claude Code (`$avouch:scan` in Codex), which drafts `avouch.config.json`, a first ontology and the document review ledger. See "init" in "Command line".
 1. Every project: keep a document review ledger, and run `avouch gate docs` in CI. See "Document review ledger (gate docs)". The gate works with any Markdown style. It guarantees that each changed section of a design document has a recorded review decision. It does not guarantee that the decision is complete: it does not check that a person read the section, that `claims` lists every claim, or that the claimed places say what the section says.
 2. For the structured checks, choose one path. The checks are: the field lists and catalogs of R2, and R3, R5, R6, R8, R9 and R10 (SPEC section 5). Each needs a fact from the project's documents (SPEC section 6). R7 needs execution evidence, which the built-in adapter does not read.
    - (a) Write the documents to the Markdown convention, `docs/markdown-convention.md`, and use the built-in adapter. `avouch facts` checks the documents without an ontology.
-   - (b) Write your own adapter: `docs/adapter-guide.md` sections 1 to 6. The grammar of the documents is then free. An AI agent writes it in a new session, not in the session that writes the ontology, with the prompt in "For AI agents" of that guide.
+   - (b) Write your own adapter: `docs/adapter-guide.md` sections 1 to 6 and 8. The grammar of the documents is then free. An AI agent writes it in a new session, not in the session that writes the ontology, with the prompt in "For AI agents" of that guide.
+3. Runtime consistency: compare the runtime with the documents. See "Runtime consistency on the command line".
+   - The project's own test harness records one `RuntimeCase` (SPEC section 9) for each command test: the action, the inputs (`bindings`, `actor`, `scope`, `now`), the `snapshot` that the decision reads, the result that the runtime reported (`reported`), and the expected result (`expected`).
+   - Take the expected result from the text of the documents. Never take it from what the code does: then the test compares the code with itself.
+   - Run `avouch reconcile`, then `avouch gate verify` with a baseline. Make the baseline with a script, from the output of `avouch gate verify --json`; do not edit it by hand. People write only the `reason` of each `exempt` entry.
+   - Do not put a known difference between the code and the documents in the baseline. Keep it as a separate test that asserts the full current behavior, and remove the test when the difference is fixed.
+   - Any language can do this: write the cases as JSONL and run the two commands. A TypeScript harness can instead call `reconcile(ontology, cases)` and `verifyCoverage(ontology, rows, baseline)` from the package root in the same process. Both paths give the same result (without `--check`). You do not need TypeScript.
 
 Avouch does not widen the built-in grammar for one project.
 
 A rule whose fact is not available is switched off in the profile, with a reason: `"rules": {"R8": {"disabled": "<reason>"}}` (in `profile` of the Markdown configuration; `docs/adapter-guide.md` section 5). The checker prints the reason. Without the switch, the rule reports `fact_missing` for the missing fact. The built-in adapter switches R3 and R9 off by itself when their facts are not set, and R7 always (`docs/adapter-guide.md` section 7).
 
+Dependency boundary:
+
+- Pin an exact version of `avouch` in a test or development package, and run its local bin (for example `npm exec avouch` in that package). Step 0 runs `npx` once; the gate runs the pinned version. In a repository without a root `package.json`, `npx avouch` gets the newest version, not the pinned one.
+- Production code does not import `avouch`. When production code needs data from the ontology (for example a registry of command permissions), generate files from the ontology, and add a test that fails when a generated file is stale.
+- Upgrade `avouch` in its own pull request, and run the full gate in it.
+- `avouch check` with an adapter checks the ontology against the documents only. It is one part of the project's gate, not the whole gate. The `check` stamp of `avouch query` is `not_run` unless you give `--check` or `--adapter` (see "Query").
+
 ## Layout
 
 | Path | Content |
@@ -86,7 +99,7 @@ A project supplies an adapter and a profile. The adapter reads the project's sou
 
 ## Command line
 
-Build with `npm run build`, then run it. `avouch --help` (or `-h`) prints the usage lines of all commands; `avouch <command> --help` prints the usage of one command. Both exit with 0 and need no files, configuration or git. For example:
+Build with `npm run build`, then run it. `avouch --help` (or `-h`) prints an overview: the commands, each with a short description, and the options `-h` and `-v`. `avouch <command> --help` prints the usage of one command. `avouch --version` (or `-v`) prints the version. All three exit with 0 and need no files, configuration or git. `avouch` with no arguments prints the overview on stderr and exits with 2; an unknown command prints an error and exits with 2. For example:
 
 ```sh
 avouch check [-f <ontology.yaml>] [--config <avouch.config.json>] [--adapter <module|config.json>]
@@ -107,7 +120,7 @@ An `--adapter` path that ends in `.json` is not loaded as a module: it is the co
 avouch init [--append | --print] [--plugin | --no-plugin] [--dry-run]
 ```
 
-`avouch init` prepares a project for Avouch. Run it inside a git repository; it works on the git top level. Step 1 is the Claude Code plugin: with `--plugin`, it runs `claude plugin marketplace add githonllc/avouch` and `claude plugin install avouch@avouch` (it does not check if the plugin is already installed, and runs both commands again on each run). Without a flag, it asks in a terminal and only prints the two commands otherwise. When `claude` is not on `PATH`, it prints the two commands. `--no-plugin` skips the step. Step 2 is the instructions for coding agents (`templates/agents-block.md`). `--append` adds them, between the lines `<!-- BEGIN avouch -->` and `<!-- END avouch -->`, to `AGENTS.md` and `CLAUDE.md` at the top level. It never creates a file: when neither file exists, it prints the instructions. It replaces an earlier block in place, keeps all other bytes and the line endings (CRLF or LF) of the file, and a second run changes nothing. A file that does not have exactly one BEGIN line and then one END line is an error, and the file is not changed. It skips `CLAUDE.md` when the file has the line `@AGENTS.md` and `AGENTS.md` exists. `--print` writes the instructions to stdout. Without a flag, it asks in a terminal and prints otherwise. `--dry-run` runs no command and writes no file; it prints the commands and, for each file, `append`, `replace` or `unchanged`. Step 3 tells you to run `/avouch:scan` in Claude Code. Exit code 0 means done (also a print and a dry run); 1 means a plugin command failed or a file could not be changed; 2 means invalid arguments or no git repository.
+`avouch init` prepares a project for Avouch. Run it inside a git repository; it works on the git top level. Step 1 is the plugin, for Claude Code and then for Codex. With `--plugin`, it runs `claude plugin marketplace add githonllc/avouch` and `claude plugin install avouch@avouch`, then `codex plugin marketplace add githonllc/avouch` and `codex plugin add avouch@avouch` (it does not check if the plugin is already installed, and runs the commands again on each run). Without a flag, it asks in a terminal for each host and only prints the commands otherwise. When `claude` or `codex` is not on `PATH`, it prints the two commands of that host. Codex runs the hook only after you approve it. `--no-plugin` skips the step. Step 2 is the instructions for coding agents (`templates/agents-block.md`). `--append` adds them, between the lines `<!-- BEGIN avouch -->` and `<!-- END avouch -->`, to `AGENTS.md` and `CLAUDE.md` at the top level. It creates `AGENTS.md` when it is missing, but it never creates `CLAUDE.md`. The reason: Claude Code reads `CLAUDE.md`, and reads `AGENTS.md` only when there is no `CLAUDE.md` or through the line `@AGENTS.md` in `CLAUDE.md`; Codex reads only `AGENTS.md`. It replaces an earlier block in place, keeps all other bytes and the line endings (CRLF or LF) of the file, and a second run changes nothing. A file that does not have exactly one BEGIN line and then one END line is an error, and the file is not changed. It skips `CLAUDE.md` when the file has the line `@AGENTS.md`, because `CLAUDE.md` then imports the instructions from `AGENTS.md`. `--print` writes the instructions to stdout. Without a flag, it asks in a terminal and prints otherwise. `--dry-run` runs no command and writes no file; it prints the commands and, for each file, `create`, `append`, `replace` or `unchanged`. Step 3 tells you to run `/avouch:scan` in Claude Code. Exit code 0 means done (also a print and a dry run); 1 means a plugin command failed or a file could not be changed; 2 means invalid arguments or no git repository.
 
 ### facts
 
@@ -299,9 +312,9 @@ Exit code 2, with one line on stderr, means:
 
 The gate does not check that a person read a unit, that `claims` lists every claim of the unit, or that the claimed places say what the unit says. Review the ledger diff in the pull request, next to the document diff. Known limit: two changes to adjacent ledger lines (for example two units of one document that follow each other) can still give a merge conflict in git.
 
-## Claude Code plugin
+## Claude Code and Codex plugin
 
-This repository is also a Claude Code plugin marketplace. Install the plugin:
+This repository is also a plugin marketplace for Claude Code and for Codex. Install the plugin in Claude Code:
 
 ```sh
 claude plugin marketplace add githonllc/avouch
@@ -310,6 +323,15 @@ claude plugin install avouch@avouch
 
 Inside a Claude Code session, the same two steps are `/plugin marketplace add githonllc/avouch` and `/plugin install avouch@avouch`.
 
+Install the plugin in Codex (the same marketplace file is used):
+
+```sh
+codex plugin marketplace add githonllc/avouch
+codex plugin add avouch@avouch
+```
+
+In Codex, call the skills as `$avouch:scan` and `$avouch:cli`. Codex runs the hook only after you approve it.
+
 The plugin has two skills and one hook. The skills:
 - `cli` (`/avouch:cli`): checks an ontology and runs `avouch query`.
 - `scan` (`/avouch:scan [project-dir]`): drafts or updates a project's ontology from its design documents, and records the review decision of each document section in the ledger (`avouch gate docs` must pass). It uses the adapter that the project has configured and never writes an adapter. The result is a candidate. `avouch check` must exit 0, and each source gap is listed with a proposed fix to the document. When most objects have no documented field list, it also writes `avouch/doc-patch.md`: field lists, foreign keys and store names derived from the code, for a human to review and merge into the documents. It never drafts states, permissions or rules from code.
@@ -322,18 +344,21 @@ The skills run the CLI with `npx -y avouch@<version>`, pinned to the version of
 
 ## Publishing
 
-The npm package is `avouch`, and its command is `avouch`. Versions 0.1.0 to 0.1.21 were published as `@githonllc/avouch`, which is deprecated. A library user changes imports from `@githonllc/avouch` to `avouch`. Versions 1.0.1 to 1.0.7 of `avouch` are an unrelated earlier package from 2020 by another author. The name was transferred to Githon LLC in 2026. Those versions sort higher than 0.x, so `release.yml` publishes with `--tag latest`.
+The npm package is `avouch`, and its command is `avouch`. Versions 0.1.0 to 0.1.21 were published only as `@githonllc/avouch`. Version 0.1.22 was published only as `avouch`. From 0.1.23, each release publishes the same files as `avouch` and as `@githonllc/avouch`; the docs use `avouch`. The name `avouch` was transferred to Githon LLC in 2026, and the earlier, unrelated versions 1.0.0 to 1.0.7 were unpublished. The two packages declare the same command `avouch`, so a project installs one of them, not both.
+
+`avouch-cli` is a separate package in `alias/avouch-cli/`. It only forwards to `avouch`, so that `npx -y avouch-cli` does not run a stranger's package. It is published by hand and depends on `"avouch": "*"`. It needs a new version only when the forwarding code changes.
 
 `package.json` has `"private": true` in the repository, so an accidental `npm publish` from a working copy is refused. The release workflow removes that line only in its own checkout.
 
 A release needs the explicit approval of the project owner. Releases are published by the GitHub Actions workflow `.github/workflows/release.yml` through npm trusted publishing: no npm token is stored, and npm adds provenance. Do these steps in this sequence:
 
 1. Set the new `0.x` version in `package.json`, `.claude-plugin/plugin.json` and the `npx -y avouch@<version>` pins in `skills/*/SKILL.md`, merge it to `main`, and wait for CI to pass. Check the file list that the CI step `npm pack --dry-run` prints.
-2. Tag the merge commit `v<version>` (the same version as `package.json`) and push the tag. The workflow checks that the tag matches the version, runs `npm ci`, the type check and the tests, removes `"private"`, and publishes with `--access public --tag latest`.
+2. Tag the merge commit `v<version>` (the same version as `package.json`) and push the tag. The workflow checks that the tag matches the version, runs `npm ci`, the type check and the tests, removes `"private"`, and publishes as `avouch` and then as `@githonllc/avouch`, with `--access public --tag latest`. A name that already has the version is skipped, so a re-run of a failed release publishes only the missing name.
 3. The job waits in the `npm` environment until the owner approves it in GitHub. The owner's approval is the release approval.
 4. Make sure that the release works:
-   - `npm view avouch version` shows the new version (a new version can take a few minutes to become available);
-   - in an empty directory, `npx -y avouch@<version>` (no arguments) prints the usage lines and exits with code 2.
+   - `npm view avouch version` and `npm view @githonllc/avouch version` show the new version (a new version can take a few minutes to become available);
+   - in an empty directory, `npx -y avouch@<version>` (no arguments) prints the help and exits with code 2;
+   - `npx -y avouch@<version> --version` prints the version.
 
 Version 0.1.0 was published by hand, because npm accepts a trusted publisher only for a package that exists.
 

package/dist/cli/avouch.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { resolveProject, runCheck } from "./check.js";
-import { FACTS_USAGE, runFacts } from "./facts.js";
-import { INIT_USAGE, runInit } from "./init.js";
-import { GATE_DOCS_USAGE, GATE_USAGE, runGate } from "./gate.js";
-import { QUERY_USAGE, runQuery } from "./query.js";
-import { expectPositionals, parseOptions, RECONCILE_USAGE, runReconcile, wantsHelp } from "./reconcile.js";
+import { runFacts } from "./facts.js";
+import { runInit } from "./init.js";
+import { runGate } from "./gate.js";
+import { runQuery } from "./query.js";
+import { expectPositionals, parseOptions, runReconcile, wantsHelp } from "./reconcile.js";
 const CHECK_USAGE = "usage: avouch check [-f <ontology.yaml>] [--config <avouch.config.json>] [--adapter <module|config.json>]";
 async function check(args) {
     if (wantsHelp(args, ["-f", "--config", "--adapter"])) {
@@ -35,12 +36,34 @@ async function check(args) {
     console.log(`${ok ? "PASS" : "FAIL"}: ${errors.length} schema error(s), ${report.violations.length} violation(s), ${report.waived.length} waived`);
     return ok ? 0 : 1;
 }
-const USAGES = [CHECK_USAGE, QUERY_USAGE, RECONCILE_USAGE, GATE_USAGE, GATE_DOCS_USAGE, FACTS_USAGE, INIT_USAGE];
+const HELP = `usage: avouch <command> [options]
+
+Check and query an Avouch ontology: a spec whose every claim cites its source.
+
+Commands:
+  init          Set up a repository: agent plugin, agent instructions
+  check         Check an ontology against the schema, rules and documents
+  query         Read a rule: an action, object, property or citation
+  facts         Show what the Markdown adapter reads from design documents
+  gate docs     Require a recorded review decision for each document change
+  gate verify   Require a verified case for each decision row
+  reconcile     Compare runtime results with the evaluator and expectations
+
+Options:
+  -h, --help     Show this help, or the help of a command
+  -v, --version  Show the version
+
+Run "avouch <command> --help" for the options of a command.
+Docs: https://avouch.dev
+`;
 async function main() {
     const args = process.argv.slice(2);
     if (args[0] === "--help" || args[0] === "-h") {
-        for (const usage of USAGES)
-            console.log(usage);
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args[0] === "--version" || args[0] === "-v") {
+        console.log(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version);
         return 0;
     }
     if (args[0] === "check")
@@ -55,8 +78,10 @@ async function main() {
         return runFacts(args.slice(1));
     if (args[0] === "init")
         return runInit(args.slice(1));
-    for (const usage of USAGES)
-        console.error(usage);
+    if (args.length > 0)
+        console.error(`avouch: unknown command "${args[0]}"\nRun "avouch --help" for the commands.`);
+    else
+        process.stderr.write(HELP);
     return 2;
 }
 try {

package/dist/cli/init.d.ts

@@ -9,10 +9,10 @@ export declare function createAsker(input: NodeJS.ReadableStream, output: NodeJS
     close: () => void;
 };
 /**
- * How to run `claude` with fixed arguments. On Windows `claude` is usually `claude.cmd`, which only a shell can run; the
- * arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
+ * How to run a host (`claude` or `codex`) with fixed arguments. On Windows the host is usually `<host>.cmd`, which only a shell
+ * can run; the arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
  */
-export declare function pluginSpawn(args: string[], platform?: NodeJS.Platform): {
+export declare function pluginSpawn(args: string[], platform?: NodeJS.Platform, host?: string): {
     command: string;
     args: string[];
     options: SpawnSyncOptions;

package/dist/cli/init.js

@@ -7,15 +7,17 @@ import { gitTop } from "./check.js";
 import { expectPositionals, parseOptions, wantsHelp } from "./reconcile.js";
 export const INIT_USAGE = "usage: avouch init [--append | --print] [--plugin | --no-plugin] [--dry-run]";
 const FLAGS = ["--append", "--print", "--plugin", "--no-plugin", "--dry-run"];
-const PLUGIN_COMMANDS = [
-    ["plugin", "marketplace", "add", "githonllc/avouch"],
-    ["plugin", "install", "avouch@avouch"],
+// The hosts of the plugin, in the order that init handles them, and the commands that install it into each.
+const HOSTS = [
+    { name: "claude", label: "Claude Code", suffix: "", commands: [["plugin", "marketplace", "add", "githonllc/avouch"], ["plugin", "install", "avouch@avouch"]] },
+    { name: "codex", label: "Codex", suffix: " for Codex", commands: [["plugin", "marketplace", "add", "githonllc/avouch"], ["plugin", "add", "avouch@avouch"]] },
 ];
+const CODEX_HOOK_NOTE = "In Codex, the hook runs only after you approve it: approve the avouch hook when Codex asks.";
 const BEGIN = "<!-- BEGIN avouch -->";
 const END = "<!-- END avouch -->";
 const TARGETS = ["AGENTS.md", "CLAUDE.md"];
 const isTty = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
-const commandLine = (args) => `claude ${args.join(" ")}`;
+const commandLine = (host, args) => `${host} ${args.join(" ")}`;
 /**
  * Yes/no questions on one readline interface, made at the first question. Lines that arrive before a question is asked
  * (typed ahead) are queued and answer the next questions in order; at the end of input a question gets no (an empty answer).
@@ -57,21 +59,21 @@ export function createAsker(input, output) {
 let asker = createAsker(process.stdin, process.stdout);
 const ask = (question) => asker.ask(question);
 /**
- * How to run `claude` with fixed arguments. On Windows `claude` is usually `claude.cmd`, which only a shell can run; the
- * arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
+ * How to run a host (`claude` or `codex`) with fixed arguments. On Windows the host is usually `<host>.cmd`, which only a shell
+ * can run; the arguments are constants, so the command line is safe for the shell. Elsewhere no shell.
  */
-export function pluginSpawn(args, platform = process.platform) {
+export function pluginSpawn(args, platform = process.platform, host = "claude") {
     return platform === "win32"
-        ? { command: commandLine(args), args: [], options: { stdio: "inherit", shell: true } }
-        : { command: "claude", args, options: { stdio: "inherit" } };
+        ? { command: commandLine(host, args), args: [], options: { stdio: "inherit", shell: true } }
+        : { command: host, args, options: { stdio: "inherit" } };
 }
-// True when an executable file named `claude` is in a PATH directory.
-function claudeOnPath() {
+// True when an executable file named `name` is in a PATH directory.
+function onPath(name) {
     for (const dir of (process.env.PATH ?? "").split(delimiter)) {
         if (dir === "")
             continue;
-        for (const name of process.platform === "win32" ? ["claude.exe", "claude.cmd", "claude"] : ["claude"]) {
-            const path = join(dir, name);
+        for (const file of process.platform === "win32" ? [`${name}.exe`, `${name}.cmd`, name] : [name]) {
+            const path = join(dir, file);
             try {
                 if (!statSync(path).isFile())
                     continue;
@@ -130,27 +132,22 @@ function printBlock() {
     process.stdout.write(wrappedBlock("\n"));
     console.log("-----8<----- end of the Avouch agent instructions -----8<-----");
 }
-/** Step 1: the Claude Code plugin. Returns false when a plugin command failed. */
-async function plugin(opts, dryRun) {
-    console.log("Step 1: the Avouch plugin for Claude Code (a hook that blocks text reads of an ontology, and the skills /avouch:scan and /avouch:cli).");
-    if (opts.has("--no-plugin")) {
-        console.log("Skipped (--no-plugin).");
-        return true;
-    }
+/** Step 1, one host: install the plugin or print the commands. Returns false when a plugin command failed. */
+async function pluginFor(host, opts, dryRun) {
     const printCommands = (why) => {
-        console.log(`${why} To install the plugin, run:`);
-        for (const c of PLUGIN_COMMANDS)
-            console.log(`  ${commandLine(c)}`);
+        console.log(`${why} To install the plugin${host.suffix}, run:`);
+        for (const c of host.commands)
+            console.log(`  ${commandLine(host.name, c)}`);
     };
-    if (!claudeOnPath()) {
-        printCommands("No `claude` executable is on PATH.");
+    if (!onPath(host.name)) {
+        printCommands(`No \`${host.name}\` executable is on PATH.`);
         return true;
     }
     if (dryRun) {
         if (opts.has("--plugin")) {
             console.log("Dry run. These commands would run:");
-            for (const c of PLUGIN_COMMANDS)
-                console.log(`  ${commandLine(c)}`);
+            for (const c of host.commands)
+                console.log(`  ${commandLine(host.name, c)}`);
         }
         else
             printCommands(`Dry run. Without --plugin, init would ${isTty() ? "ask before it runs these commands" : "only print these commands"}.`);
@@ -162,7 +159,7 @@ async function plugin(opts, dryRun) {
             printCommands("No terminal, so init does not run the commands.");
             return true;
         }
-        run = await ask("Install the Avouch plugin for Claude Code (user scope)?");
+        run = await ask(`Install the Avouch plugin for ${host.label} (user scope)?`);
         if (!run) {
             printCommands("Not installed.");
             return true;
@@ -170,60 +167,74 @@ async function plugin(opts, dryRun) {
     }
     let ok = true;
     // Both commands run even when the first fails: adding a marketplace that is already added can fail while the install still works.
-    for (const c of PLUGIN_COMMANDS) {
-        console.log(`Running: ${commandLine(c)}`);
-        const s = pluginSpawn(c);
+    for (const c of host.commands) {
+        console.log(`Running: ${commandLine(host.name, c)}`);
+        const s = pluginSpawn(c, process.platform, host.name);
         const r = spawnSync(s.command, s.args, s.options);
         if (r.error !== undefined || r.status !== 0) {
             ok = false;
-            console.error(`FAIL: ${commandLine(c)}: ${r.error !== undefined ? r.error.message : r.status !== null ? `exit ${r.status}` : `signal ${r.signal}`}`);
+            console.error(`FAIL: ${commandLine(host.name, c)}: ${r.error !== undefined ? r.error.message : r.status !== null ? `exit ${r.status}` : `signal ${r.signal}`}`);
         }
     }
     return ok;
 }
+/** Step 1: the plugin for Claude Code and Codex. Returns false when a plugin command failed. */
+async function plugin(opts, dryRun) {
+    console.log("Step 1: the Avouch plugin for Claude Code and Codex (a hook that blocks text reads of an ontology, and the skills avouch:scan and avouch:cli).");
+    if (opts.has("--no-plugin")) {
+        console.log("Skipped (--no-plugin).");
+        return true;
+    }
+    let ok = true;
+    for (const host of HOSTS) {
+        const hostOk = await pluginFor(host, opts, dryRun);
+        ok = hostOk && ok;
+        if (host.name === "codex" && hostOk)
+            console.log(CODEX_HOOK_NOTE);
+    }
+    return ok;
+}
 /** Step 2: the agent instructions. Returns false when a file could not be written. */
 async function instructions(top, opts, dryRun) {
     console.log("Step 2: the Avouch instructions for coding agents (AGENTS.md, CLAUDE.md).");
     const exists = (name) => existsSync(join(top, name)) && statSync(join(top, name)).isFile();
+    // AGENTS.md is always a target and is created when it is missing (Codex reads only AGENTS.md); CLAUDE.md is never created.
     const files = [];
     for (const name of TARGETS) {
-        if (!exists(name))
+        if (name === "CLAUDE.md" && !exists(name))
             continue;
-        if (name === "CLAUDE.md" && exists("AGENTS.md") && readFileSync(join(top, name), "utf8").split(/\r?\n/).some((l) => l.trim() === "@AGENTS.md")) {
+        if (name === "CLAUDE.md" && readFileSync(join(top, name), "utf8").split(/\r?\n/).some((l) => l.trim() === "@AGENTS.md")) {
             console.log("CLAUDE.md is skipped: it has the line `@AGENTS.md`, so it imports the instructions from AGENTS.md.");
             continue;
         }
         files.push(name);
     }
+    const label = (name) => (exists(name) ? name : `${name} (new file)`);
     let append = opts.has("--append");
-    if (!append && !opts.has("--print") && files.length > 0) {
+    if (!append && !opts.has("--print")) {
         if (dryRun) {
             console.log("Dry run without --append or --print: this is the plan for --append (init asks in a terminal and prints otherwise).");
             append = true;
         }
         else if (isTty())
-            append = await ask(`Append the Avouch instructions to ${files.join(", ")}?`);
+            append = await ask(`Append the Avouch instructions to ${files.map(label).join(", ")}?`);
     }
     if (!append) {
         printBlock();
         return true;
     }
-    if (files.length === 0) {
-        console.log(`No file to append to: AGENTS.md and CLAUDE.md do not exist at ${top}, and init never creates a file.`);
-        printBlock();
-        return true;
-    }
     let ok = true;
     for (const name of files) {
         const path = join(top, name);
-        const plan = planFile(name, readFileSync(path));
+        const created = !exists(name);
+        const plan = planFile(name, created ? Buffer.alloc(0) : readFileSync(path));
         if ("error" in plan) {
             ok = false;
             console.error(`FAIL: ${plan.error}`);
             continue;
         }
         if (dryRun) {
-            console.log(`Dry run: ${name}: ${plan.action === "unchanged" ? "unchanged" : `would ${plan.action === "append" ? "append the block" : "replace the block"}`}`);
+            console.log(`Dry run: ${name}: ${created ? "would create the file with the block" : plan.action === "unchanged" ? "unchanged" : `would ${plan.action === "append" ? "append the block" : "replace the block"}`}`);
             continue;
         }
         if (plan.action === "unchanged") {
@@ -232,7 +243,7 @@ async function instructions(top, opts, dryRun) {
         }
         try {
             writeFileSync(path, plan.bytes);
-            console.log(`${name}: ${plan.action === "append" ? "appended the block" : "replaced the block"}`);
+            console.log(`${name}: ${created ? "created the file with the block" : plan.action === "append" ? "appended the block" : "replaced the block"}`);
         }
         catch (error) {
             ok = false;

package/docs/adapter-guide.md

@@ -185,3 +185,14 @@ Without `--check` and without `--adapter`, the check stamp of `avouch query` sta
 - the generic adapter also reports R6 `fact_missing facts.evidence`.
 
 The R3 and R9 findings are the same, because the configuration sets `facts.stateMachines`, `facts.transitionTriggers` and `facts.scenarios`. So the generic adapter does not catch three mutations: `lib-r6-none-but-written`, `lib-r7-effect-unwitnessed` and `lib-r7-undeclared-store`. It catches the other 25, `lib-r3-transition-binding`, `lib-r6-link-sweep-missing` and `lib-r9-unknown-scenario` included. With the evidence ids kept, the clean toy fails with three violations: R1 for each of the two evidence ids, and R6 `fact_missing`.
+
+## 8. Test your adapter with mutations
+
+A clean PASS can prove nothing. An adapter that returns too few facts, or a rule that never fires, also gives PASS. A mutation test shows that each check can fail.
+
+- For each rule that you turn on, keep a few mutated copies of the ontology or of the documents. Each copy changes one thing, and must fail with exactly its expected rule: that rule, and no other rule.
+- Pin the result in a snapshot, so that a change in the adapter or in Avouch that changes a finding shows in the diff.
+- Give each waiver (`knownSourceGaps`: `conflict` and `proposed`) and each disabled rule (`{ disabled: "<reason>" }`) a reason.
+- Where the documents decide, track that no `unknown` or `unspecified` is left in the ontology: for example `permission: unknown` (R10 `permission_unknown`) or a condition without an expression (R12 `condition_unspecified`). Do not waive these when the text gives the answer; write the value. `avouch query list gaps` lists the waivers.
+
+The model is the toy library: each file in `examples/library/mutations/` is a JSON-pointer patch of the ontology (`src/patch.ts`) with `expect: R<n>`, and `test/library.test.ts` checks that the clean ontology passes and that each mutation fails with exactly its expected rule. Mutations of the documents follow the same pattern: change one source text, run the adapter, and expect one rule.

package/docs/markdown-convention.md

@@ -3,7 +3,7 @@
 This document is the grammar of the built-in Markdown adapter (`src/markdown.ts`). The adapter reads facts only in the form that this document describes. A project has two ways to use Avouch with Markdown documents:
 
 1. Write the documents to this convention. Then `avouch check` runs the built-in adapter, with a JSON configuration (`docs/adapter-guide.md` section 7).
-2. Write an own adapter. Then the grammar of the documents is free. See `docs/adapter-guide.md` sections 1 to 6; an AI agent uses the prompt in "For AI agents" of that guide.
+2. Write an own adapter. Then the grammar of the documents is free. See `docs/adapter-guide.md` sections 1 to 6 and 8; an AI agent uses the prompt in "For AI agents" of that guide.
 
 An AI that reformats documents can use this document as the target form. Write each fact as one block, as the templates in sections 3 to 10 show.
 

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "avouch",
-  "version": "0.1.22",
+  "version": "0.1.24",
+  "description": "Avouch: an ontology spec whose every claim cites its source, with a checker and a CLI.",
   "license": "Apache-2.0",
+  "author": "Githon LLC",
+  "keywords": [
+    "avouch",
+    "ontology",
+    "specification",
+    "design-docs",
+    "ai-agents",
+    "claude-code",
+    "checker",
+    "cli"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/githonllc/avouch.git"

package/templates/agents-block.md

@@ -7,6 +7,6 @@ The business rules of this project are in an Avouch ontology (`*.ontology.yaml`,
 - Do not read the ontology file with grep, cat, sed or a script. Comments and neighbouring entries in the text look like rules, but the checker does not read them.
 - If the rule is `unspecified` or is in `knownSourceGaps`, the documents do not decide it. Do not invent the behavior: tell your user, and say so in the pull request.
 - If the ontology, the documents and the code disagree, do not decide in code. Tell your user which texts disagree.
-- To change a rule, change the design document first, or ask your user to. Then update the ontology so that each claim quotes the new text: in Claude Code with `/avouch:scan`, otherwise with the writing rules in https://avouch.dev/llms.txt. Do not add a rule that no document states.
+- To change a rule, change the design document first, or ask your user to. Then update the ontology so that each claim quotes the new text: in Claude Code with `/avouch:scan`, in Codex with `$avouch:scan`, otherwise with the writing rules in https://avouch.dev/llms.txt. Do not add a rule that no document states.
 - After you change the ontology or a cited document section, run `npx -y avouch check`, and `npx -y avouch gate docs` if the project has a ledger (`avouch.ledger.jsonl`). Both must exit 0. `check` covers the format rules only; it does not replace the project's tests.
 - Do not edit the ledger to make the gate pass without reading the changed section.