create-agent-rig 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -9,7 +9,85 @@ Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/pack
 
 Numbering is ordinary semver — **additive is a minor, a fix is a patch** — so
 that "I only take minors" remains a usable policy; 0.3.2 shipped additive
-content as a patch by the owner's call and stays recorded as one.
+content as a patch by the owner's call and stays recorded as one. 0.8.0 is the
+second recorded departure; its own entry states the direction and the reason,
+and this paragraph deliberately does not restate them — a numbering rule with
+two copies of its exceptions is the shape 0.8.0 exists to remove.
+
+## 0.8.0
+
+**Three stale second copies, spread over three payload files a rig obeys,
+described the mechanisms behind them wrongly — and each fix is a deletion.** A
+count and a path list, both in `.claude/rules/autonomy.md`, and a paraphrase of
+that same path list in `loop/SKILL.md`, which ships in both harnesses' copies.
+Every one of them was a second writing of a fact the code owns, and every one
+had drifted from its source while the suite stayed green.
+
+**The `templates/agent-os/` payload gains no file and loses none**, measured
+tarball to tarball — `npm pack create-agent-rig@0.7.1` unpacked, against this
+release's own `npm pack`. That payload is the same 95 files either way, and
+exactly three of them differ in content. ⚠ The tarball as a whole is **not**
+unchanged: it grows by eleven files, and the section below names which and why.
+
+**Numbered a minor by the owner's call, not by this file's rule.** The rule at
+the top — additive is a minor, a fix is a patch — makes this delta a patch,
+because nothing is added to what a project installs. It ships as `0.8.0`
+because the owner's milestone of that name closes here and the number was fixed
+before the delta was measured. Recorded rather than reconciled, the way `0.3.2`
+is recorded above: a consumer on "I only take minors" receives three corrected
+documents and no new capability.
+
+### Fixed
+
+- **`.claude/rules/autonomy.md` stated a blind-spot count `guard-secret-file`
+  had outgrown.** The Never bullet said the guard's header "states the four
+  blind spots"; the header had been raised past four in `51402e99`, and the
+  stale copy shipped in 0.6.1, 0.6.2, 0.7.0 and 0.7.1 — a security rule
+  describing its own mechanism wrongly for four releases. The fix is not a
+  corrected number, which would only restart the same clock: the prose states
+  no count and points at the header, and `README.md` moved with it for the same
+  reason. Pinned in the generator's `test/template/guard-secret-file.test.ts`
+  (absent in a generated rig) › "no live rulebook document restates the guard’s
+  limit count" and › "the rule and the README still send the reader to the
+  guard’s own header".
+
+- **The same file re-listed the paths `guard-rulebook` protects, and its list
+  was incomplete.** The enumeration of trees an unattended run may not edit
+  omitted `.claude/doctor-exemptions.json`, which the guard does refuse. It is
+  replaced by a pointer to `RULEBOOK_PREFIXES` in
+  `.claude/scripts/unattended-flag.mjs` — the set the guard judges an edit
+  against — so there is one spelling of it rather than two. One fact that
+  pointer cannot carry is stated beside it, because it does not follow from the
+  set: the checkout board selector is refused **even when an item's allow-list
+  names it**.
+
+- **`loop/SKILL.md` paraphrased that set too, in both harnesses' copies.** The
+  step where a session composes an allow-list summarised the protected rulebook
+  in prose, so the one moment the set is read in anger was the moment it was
+  read from a summary that had already drifted. It now names
+  `RULEBOOK_PREFIXES` and says to open it. Both copies carry the change — the
+  Claude skill at `.claude/skills/loop/SKILL.md` and its Codex projection at
+  `.agents/skills/loop/SKILL.md`.
+
+### Inside the generator, and not inside a rig
+
+`packages/cli/src/policy/` is new — a typed policy declaration, a registry, a
+decision-record schema and one adapter per harness. Its compiled output adds
+eleven files to the published tarball, 245 → 256. **No command imports it**, so nothing a
+project scaffolded from this release does comes from it. What such a project
+does get from this release is the three corrected documents above — and an
+installed 0.7.1 rig still needs `create-agent-rig upgrade` to receive them —
+which is a necessary condition and not a sufficient one, because a rig whose
+owner has edited one of those three files is handed a conflict to merge rather
+than an overwrite.
+This module is named here only because a reader diffing the two tarballs sees
+eleven new files and is owed the reason they are not part of that answer.
+
+`templates/release-ledger.json` carries `0.7.1` at `52e879b6`, the commit it was
+published from, read from `npm view create-agent-rig@0.7.1 gitHead` and verified
+an ancestor of `master`. `templates/hash-history.json` is regenerated from it and
+now covers eleven releases, `0.2.0` through `0.7.1`, so `upgrade` can tell an
+untouched file from an edited one in a rig installed from 0.7.1.
 
 ## 0.7.1
 

package/README.md

@@ -116,7 +116,7 @@ wired by both `.claude/settings.json` and `.codex/hooks.json`:
   carries a credential VALUE. Both arms read one vocabulary,
   `.claude/scripts/lib/secrets.mjs`, and a refusal names the pattern and the line
   and **never the matched value** — printing it would leak the secret in the act
-  of refusing it. Its four blind spots are in its own header, each naming the
+  of refusing it. Its blind spots are in its own header, each naming the
   test that pins it or saying plainly that none does — and those tests live in
   this generator, not in the rig;
 - **`block-no-verify`** — refuses bypassing pre-commit checks (and knows the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

package/packages/cli/dist/policy/core/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * The contract a harness adapter satisfies (RP-76).
+ *
+ * The core knows that a harness exists and has a hook-wiring surface; it does
+ * not know any harness's name, event vocabulary, tool names or paths. Those
+ * belong to the adapter, one module per harness under `../harness/`, and
+ * adding a harness means adding one such module and registering it — pinned in
+ * `test/template/policy-declaration.test.ts` under "adding a harness touches
+ * adapters only", whose two tests name exactly the files that may mention each
+ * harness. Their names carry the harness words this file may not, which is why
+ * the describe is cited here rather than either test.
+ *
+ * An adapter is a mapping, not a compiler: given a declaration it names the
+ * event, matcher and hook path the harness wires for it. The correspondence
+ * between that answer and the snapshot the rig actually ships is a test, in
+ * both directions, in the same file.
+ */
+export {};

package/packages/cli/dist/policy/core/decision-record.js

@@ -0,0 +1,201 @@
+/**
+ * The decision-record schema (RP-76): what one verdict of one policy on one
+ * harness must carry to be audited later, and the validator that refuses a
+ * record which would read as more than it is.
+ *
+ * Emitting these at runtime is a separate task; this file is the shape and the
+ * rules. The rules that go beyond "the field is in its vocabulary":
+ *
+ * - the policy must be registered and the version compatible with it, so the
+ *   record names semantics a reader can look up;
+ * - the operation must be one the policy declares;
+ * - a qualifier (`UNVERIFIABLE`, `UNMEASURED`) must carry a reason;
+ * - a capability state of `UNSUPPORTED` or `INTEGRATION-FAILED` must qualify
+ *   the verdict `UNVERIFIABLE` — an unenforceable policy never yields a silent
+ *   pass (`./vocabulary.ts`, `CAPABILITY_STATES`);
+ * - every evidence kind the policy requires must be present;
+ * - a policy that redacts must not be recorded with unredacted diagnostics;
+ * - the timestamp is supplied by the caller and must be an ISO-8601 date-time
+ *   with seconds and an explicit zone (`ISO_8601` below; a bare date is
+ *   refused) — no clock here.
+ *
+ * Each rule is one test in `packages/cli/test/policy-declaration.test.ts`
+ * under "validating a decision record".
+ *
+ * ⚠ `diagnostics.redacted` is the emitter's claim, and this validator enforces
+ * the claim's presence, not the property: a record marked redacted whose
+ * `diagnostics.text`, `observedFacts[].value` or `evidence[].value` still
+ * carries a matched value is accepted here. Scanning content would pull the
+ * secret vocabulary into the core, which the dependency-direction test
+ * forbids — so the emitting task owns that scan, over those three fields,
+ * before it persists a record.
+ */
+import { compatibilityOf, findPolicy } from './registry.js';
+import { CAPABILITY_STATES, DECISION_OUTCOMES, EVIDENCE_KINDS, OPERATIONS, VERDICT_QUALIFIERS, } from './vocabulary.js';
+import { isRecord, member, nonEmptyString, unknownKeys } from './validation.js';
+export const DECISION_RECORD_SCHEMA_VERSION = 1;
+const KEYS = [
+    'schemaVersion',
+    'policyId',
+    'policyVersion',
+    'harness',
+    'operation',
+    'capabilityState',
+    'observedFacts',
+    'verdict',
+    'evidence',
+    'artifactVersion',
+    'diagnostics',
+    'recordedAt',
+];
+const NEVER_SILENT_PASS = ['UNSUPPORTED', 'INTEGRATION-FAILED'];
+/** Date, `T`, time to the second (fractions allowed), and an explicit zone. */
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const namedPairs = (problems, field, value, keys) => {
+    if (!Array.isArray(value)) {
+        problems.push({ field, message: 'must be a list' });
+        return;
+    }
+    value.forEach((entry, index) => {
+        if (!isRecord(entry)) {
+            problems.push({ field: `${field}[${index}]`, message: 'must be an object' });
+            return;
+        }
+        unknownKeys(problems, entry, keys, `${field}[${index}]`);
+        for (const key of keys)
+            nonEmptyString(problems, `${field}[${index}].${key}`, entry[key]);
+    });
+};
+const checkVerdict = (problems, value, capabilityState) => {
+    if (!isRecord(value)) {
+        problems.push({ field: 'verdict', message: 'must be an object' });
+        return;
+    }
+    unknownKeys(problems, value, ['outcome', 'qualifier', 'reason'], 'verdict');
+    member(problems, 'verdict.outcome', value.outcome, DECISION_OUTCOMES);
+    const qualified = 'qualifier' in value;
+    if (qualified) {
+        member(problems, 'verdict.qualifier', value.qualifier, VERDICT_QUALIFIERS);
+        if (typeof value.reason !== 'string' || value.reason.trim() === '') {
+            problems.push({
+                field: 'verdict.reason',
+                message: `a ${String(value.qualifier)} verdict must say why`,
+            });
+        }
+    }
+    else if ('reason' in value && typeof value.reason !== 'string') {
+        problems.push({ field: 'verdict.reason', message: 'must be a string when present' });
+    }
+    if (capabilityState !== null && NEVER_SILENT_PASS.includes(capabilityState)) {
+        if (value.qualifier !== 'UNVERIFIABLE') {
+            problems.push({
+                field: 'verdict.qualifier',
+                message: `capabilityState ${capabilityState} never yields a silent pass: ` +
+                    'the verdict must be qualified UNVERIFIABLE with a reason',
+            });
+        }
+    }
+};
+const checkEvidence = (problems, value, required) => {
+    if (!Array.isArray(value)) {
+        problems.push({ field: 'evidence', message: 'must be a list' });
+        return;
+    }
+    const present = new Set();
+    value.forEach((entry, index) => {
+        if (!isRecord(entry)) {
+            problems.push({ field: `evidence[${index}]`, message: 'must be an object' });
+            return;
+        }
+        unknownKeys(problems, entry, ['kind', 'value'], `evidence[${index}]`);
+        if (member(problems, `evidence[${index}].kind`, entry.kind, EVIDENCE_KINDS)) {
+            present.add(entry.kind);
+        }
+        nonEmptyString(problems, `evidence[${index}].value`, entry.value);
+    });
+    for (const kind of required) {
+        if (!present.has(kind)) {
+            problems.push({ field: 'evidence', message: `the policy requires ${kind} evidence` });
+        }
+    }
+};
+const checkDiagnostics = (problems, value, mustRedact) => {
+    if (!isRecord(value)) {
+        problems.push({ field: 'diagnostics', message: 'must be an object' });
+        return;
+    }
+    unknownKeys(problems, value, ['redacted', 'text'], 'diagnostics');
+    if (typeof value.redacted !== 'boolean') {
+        problems.push({ field: 'diagnostics.redacted', message: 'must be a boolean' });
+    }
+    else if (mustRedact && !value.redacted) {
+        problems.push({
+            field: 'diagnostics.redacted',
+            message: 'the policy redacts matched values, so its diagnostics must be recorded redacted',
+        });
+    }
+    if (typeof value.text !== 'string') {
+        problems.push({ field: 'diagnostics.text', message: 'must be a string' });
+    }
+};
+/** Validate an unknown value as a decision record, reporting every problem at once. */
+export function validateDecisionRecord(input) {
+    if (!isRecord(input)) {
+        return { ok: false, problems: [{ field: '', message: 'a decision record is an object' }] };
+    }
+    const problems = [];
+    unknownKeys(problems, input, KEYS);
+    if (input.schemaVersion !== DECISION_RECORD_SCHEMA_VERSION) {
+        problems.push({
+            field: 'schemaVersion',
+            message: `must be ${DECISION_RECORD_SCHEMA_VERSION}, got ${String(input.schemaVersion)}`,
+        });
+    }
+    const policy = typeof input.policyId === 'string' ? findPolicy(input.policyId) : null;
+    if (policy === null) {
+        problems.push({
+            field: 'policyId',
+            message: `${JSON.stringify(input.policyId)} is not a registered policy`,
+        });
+    }
+    else if (typeof input.policyVersion === 'string') {
+        const compatibility = compatibilityOf(policy.policyId, input.policyVersion);
+        if (compatibility !== 'compatible') {
+            problems.push({
+                field: 'policyVersion',
+                message: `${JSON.stringify(input.policyVersion)} is ${compatibility} with ${policy.policyId} ${policy.policyVersion}`,
+            });
+        }
+    }
+    else {
+        nonEmptyString(problems, 'policyVersion', input.policyVersion);
+    }
+    nonEmptyString(problems, 'harness', input.harness);
+    if (member(problems, 'operation', input.operation, OPERATIONS) && policy !== null) {
+        if (!policy.operations.includes(input.operation)) {
+            problems.push({
+                field: 'operation',
+                message: `${policy.policyId} does not apply to ${input.operation}`,
+            });
+        }
+    }
+    const capabilityState = member(problems, 'capabilityState', input.capabilityState, CAPABILITY_STATES)
+        ? input.capabilityState
+        : null;
+    namedPairs(problems, 'observedFacts', input.observedFacts, ['name', 'value']);
+    checkVerdict(problems, input.verdict, capabilityState);
+    checkEvidence(problems, input.evidence, policy?.requiredEvidence ?? []);
+    nonEmptyString(problems, 'artifactVersion', input.artifactVersion);
+    checkDiagnostics(problems, input.diagnostics, policy !== null && policy.redaction !== 'none');
+    if (typeof input.recordedAt !== 'string' ||
+        !ISO_8601.test(input.recordedAt) ||
+        Number.isNaN(Date.parse(input.recordedAt))) {
+        problems.push({
+            field: 'recordedAt',
+            message: `must be an ISO-8601 date-time with seconds and an explicit zone, got ${JSON.stringify(input.recordedAt)}`,
+        });
+    }
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return { ok: true, value: input };
+}

package/packages/cli/dist/policy/core/declaration.js

@@ -0,0 +1,86 @@
+/**
+ * The typed policy declaration (RP-76).
+ *
+ * A declaration is the semantic source of one policy: what the invariant is,
+ * where it applies, what the mechanism can answer, how it fails, what a
+ * verdict must carry as evidence, and which version of those semantics a
+ * decision record is talking about. It is data plus a validator — not a policy
+ * language, not an interpreter, not a compiler: a harness adapter reads a
+ * declaration and names its own native surface for it (`./adapter.ts`), and
+ * that is the whole of the transformation.
+ *
+ * The shape is closed: a field this interface does not name is refused, so a
+ * field added by mistake cannot travel unnoticed into a record somebody later
+ * audits. Every enumerated field draws from `./vocabulary.ts`.
+ */
+import { AUTONOMY_TIERS, DECISION_OUTCOMES, ENFORCEMENT_TIMINGS, EVIDENCE_KINDS, FAILURE_SEMANTICS, HARNESS_CAPABILITIES, LIFECYCLE_STATES, OPERATIONS, REDACTION_RULES, } from './vocabulary.js';
+import { isRecord, matching, member, members, nonEmptyString, unknownKeys } from './validation.js';
+const KEYS = [
+    'policyId',
+    'policyVersion',
+    'lifecycle',
+    'invariant',
+    'tier',
+    'operations',
+    'timing',
+    'requiredCapability',
+    'mechanism',
+    'outcomes',
+    'onInternalError',
+    'onUnreadableInput',
+    'requiredEvidence',
+    'redaction',
+    'statedIn',
+];
+export const KEBAB_CASE = /^[a-z][a-z0-9-]*$/;
+export const POLICY_VERSION = /^\d+\.\d+$/;
+/** Validate an unknown value as a declaration, reporting every problem at once. */
+export function validateDeclaration(input) {
+    if (!isRecord(input)) {
+        return { ok: false, problems: [{ field: '', message: 'a declaration is an object' }] };
+    }
+    const problems = [];
+    unknownKeys(problems, input, KEYS);
+    matching(problems, 'policyId', input.policyId, KEBAB_CASE, 'kebab-case');
+    matching(problems, 'policyVersion', input.policyVersion, POLICY_VERSION, 'MAJOR.MINOR');
+    member(problems, 'lifecycle', input.lifecycle, LIFECYCLE_STATES);
+    nonEmptyString(problems, 'invariant', input.invariant);
+    member(problems, 'tier', input.tier, AUTONOMY_TIERS);
+    members(problems, 'operations', input.operations, OPERATIONS, { nonEmpty: true });
+    member(problems, 'timing', input.timing, ENFORCEMENT_TIMINGS);
+    member(problems, 'requiredCapability', input.requiredCapability, HARNESS_CAPABILITIES);
+    matching(problems, 'mechanism', input.mechanism, KEBAB_CASE, 'kebab-case');
+    members(problems, 'outcomes', input.outcomes, DECISION_OUTCOMES, { nonEmpty: true });
+    member(problems, 'onInternalError', input.onInternalError, FAILURE_SEMANTICS);
+    member(problems, 'onUnreadableInput', input.onUnreadableInput, FAILURE_SEMANTICS);
+    members(problems, 'requiredEvidence', input.requiredEvidence, EVIDENCE_KINDS, {
+        nonEmpty: false,
+    });
+    member(problems, 'redaction', input.redaction, REDACTION_RULES);
+    nonEmptyString(problems, 'statedIn', input.statedIn);
+    if (problems.length > 0)
+        return { ok: false, problems };
+    // Every field above was checked against the shape, so the narrowing is earned
+    // rather than asserted: the cast is to the type the checks just established.
+    return { ok: true, value: input };
+}
+/**
+ * Define a policy: validate it and hand back a frozen copy. Throws an Error
+ * whose message lists every problem as `field: message`, so a registry that
+ * loads at import time fails with the whole list rather than one line at a
+ * time.
+ */
+export function definePolicy(input) {
+    const result = validateDeclaration(input);
+    if (!result.ok) {
+        const lines = result.problems.map(({ field, message }) => `${field}: ${message}`);
+        throw new Error(`invalid policy declaration:\n  ${lines.join('\n  ')}`);
+    }
+    const policy = result.value;
+    return Object.freeze({
+        ...policy,
+        operations: Object.freeze([...policy.operations]),
+        outcomes: Object.freeze([...policy.outcomes]),
+        requiredEvidence: Object.freeze([...policy.requiredEvidence]),
+    });
+}

package/packages/cli/dist/policy/core/registry.js

@@ -0,0 +1,115 @@
+/**
+ * The policy registry (RP-76): the declarations of the policies this rig
+ * enforces, and the compatibility rule a decision record is read against.
+ *
+ * The three entries are the guards the rulebook already ships; declaring them
+ * changes nothing about how they run. Each field below was read off the
+ * guard's own header and its tests rather than inferred from its name, and the
+ * correspondence between a declaration and the hook wiring both harnesses
+ * carry is pinned in `test/template/policy-declaration.test.ts` › "every
+ * registered policy is wired in the %s snapshot under its event, matcher and
+ * hook path". Which hook file a mechanism name resolves to is the adapter's
+ * business (`../harness/`), not this file's.
+ */
+import { definePolicy } from './declaration.js';
+import { POLICY_VERSION } from './declaration.js';
+const NEVER_TIER = 'rules/autonomy.md#never';
+/**
+ * What the three share, stated once: each is a pre-operation hook of the
+ * Never tier that can allow, block, or refuse to inspect; each fails open on
+ * its own error and closed on input it can see but cannot read
+ * (`rules/invariants.md`, "Fail closed on a match, fail open on an error" and
+ * "Refusing to inspect is a third outcome"). The one evidence every outcome
+ * carries is the exit code; a refusal also prints a diagnostic line, an allow
+ * prints nothing, so `diagnostic-text` is not required of every record.
+ */
+const guard = (declaration) => definePolicy({
+    policyVersion: '1.0',
+    lifecycle: 'active',
+    tier: 'never',
+    timing: 'before-operation',
+    requiredCapability: 'pre-operation-hook',
+    outcomes: ['allow', 'block', 'refuse-to-inspect'],
+    onInternalError: 'fail-open',
+    onUnreadableInput: 'fail-closed',
+    requiredEvidence: ['exit-code'],
+    statedIn: NEVER_TIER,
+    ...declaration,
+});
+/**
+ * Secret-write refusal. The guard refuses an edit that names a credential file
+ * or carries a credential value; the value arm never prints what it matched —
+ * `test/template/guard-secret-file.test.ts` › "never prints the credential it
+ * found, nor a fragment of it" — which is what `omit-matched-values` records.
+ */
+const secretWriteRefusal = guard({
+    policyId: 'secret-write-refusal',
+    invariant: 'A credential never enters the repository through an edit.',
+    operations: ['file-edit'],
+    mechanism: 'guard-secret-file',
+    redaction: 'omit-matched-values',
+});
+/**
+ * No-verify refusal. The guard refuses a shell command that bypasses the
+ * pre-commit gate — `test/template/shell-tools.test.ts` › "refuses a
+ * pre-commit bypass through %s" pins the block on every shell tool. The
+ * refuse-to-inspect outcome and the fail-open on an unparseable payload are
+ * `test/template/hook-command-shape.test.ts` › "%s does not tell the caller to
+ * split and retry" and › "allows a malformed payload it cannot parse at all".
+ * ⚠ One limit of `onInternalError: 'fail-open'` for this guard: it has no
+ * try/catch, so an internal throw exits 1, which the harness reads as allow —
+ * a property of the harness that no test here pins.
+ */
+const noVerifyRefusal = guard({
+    policyId: 'no-verify-refusal',
+    invariant: 'The pre-commit gate is never bypassed.',
+    operations: ['shell-command'],
+    mechanism: 'block-no-verify',
+    redaction: 'none',
+});
+/**
+ * Rulebook-mutation restriction. In an unattended run the guard refuses an
+ * edit under a rulebook prefix outside the current item's allow-list; in an
+ * attended session it does nothing — `test/template/guard-rulebook.test.ts` ›
+ * "blocks an edit to a rulebook path the allow-list does not name" and ›
+ * "allows a hook edit when no unattended flag exists".
+ */
+const rulebookMutationRestriction = guard({
+    policyId: 'rulebook-mutation-restriction',
+    invariant: "In an unattended run, the rulebook is never edited outside the current item's allow-list.",
+    operations: ['file-edit'],
+    mechanism: 'guard-rulebook',
+    redaction: 'none',
+});
+/** Every declared policy, in declaration order. */
+export const POLICIES = Object.freeze([
+    secretWriteRefusal,
+    noVerifyRefusal,
+    rulebookMutationRestriction,
+]);
+export function findPolicy(policyId) {
+    return POLICIES.find((policy) => policy.policyId === policyId) ?? null;
+}
+export function policyIds() {
+    return POLICIES.map((policy) => policy.policyId);
+}
+/** The policies the registry still offers — everything not retired. */
+export function activePolicies() {
+    return POLICIES.filter((policy) => policy.lifecycle !== 'retired');
+}
+const majorOf = (version) => Number(version.split('.')[0]);
+/**
+ * Can a decision record naming `policyVersion` be read against the registered
+ * policy? Same MAJOR: yes, whatever the MINOR — a MINOR bump is additive.
+ * Different MAJOR: no, the semantics that produced the verdict are not these.
+ * A version that is not `MAJOR.MINOR` is refused as malformed rather than
+ * parsed for a MAJOR it might have meant.
+ */
+export function compatibilityOf(policyId, policyVersion) {
+    const policy = findPolicy(policyId);
+    if (policy === null)
+        return 'unknown-policy';
+    if (!POLICY_VERSION.test(policyVersion))
+        return 'malformed-version';
+    return majorOf(policyVersion) === majorOf(policy.policyVersion) ? 'compatible' : 'incompatible';
+}

package/packages/cli/dist/policy/core/validation.js

@@ -0,0 +1,82 @@
+/**
+ * The small set of checks the declaration and the decision record share.
+ *
+ * Every check appends to a problem list instead of throwing, so a caller sees
+ * every defect of a record at once — `validateDeclaration` › "reports every
+ * problem at once rather than stopping at the first" in
+ * `packages/cli/test/policy-declaration.test.ts`. Each message that refuses an
+ * enumerated value quotes the value, because a refusal that names the field
+ * and not the word leaves the caller guessing which of two spellings it sent.
+ */
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const quote = (value) => {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+const list = (vocabulary) => vocabulary.map(quote).join(', ');
+/**
+ * Refuse a key the shape does not declare — the shape is closed on purpose.
+ * A nested shape passes its own field name as `prefix`, so the problem names
+ * `verdict.severity` rather than a bare `severity` the caller cannot place.
+ */
+export const unknownKeys = (problems, input, known, prefix = '') => {
+    for (const key of Object.keys(input)) {
+        if (!known.includes(key)) {
+            problems.push({ field: prefix === '' ? key : `${prefix}.${key}`, message: 'unknown field' });
+        }
+    }
+};
+/** Refuse a string that is absent, not a string, or empty. */
+export const nonEmptyString = (problems, field, value) => {
+    if (typeof value !== 'string' || value === '') {
+        problems.push({ field, message: `must be a non-empty string, got ${quote(value)}` });
+        return false;
+    }
+    return true;
+};
+/** Refuse a string outside a closed vocabulary, quoting the offending value. */
+export const member = (problems, field, value, vocabulary) => {
+    if (typeof value === 'string' && vocabulary.includes(value))
+        return true;
+    problems.push({ field, message: `${quote(value)} is not one of ${list(vocabulary)}` });
+    return false;
+};
+/**
+ * Refuse a list that is not an array, carries a value outside the vocabulary,
+ * repeats one, or — when `nonEmpty` — is empty.
+ */
+export const members = (problems, field, value, vocabulary, { nonEmpty }) => {
+    if (!Array.isArray(value)) {
+        problems.push({ field, message: `must be a list, got ${quote(value)}` });
+        return false;
+    }
+    let clean = true;
+    if (nonEmpty && value.length === 0) {
+        problems.push({ field, message: 'must not be empty' });
+        clean = false;
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        if (!member(problems, field, entry, vocabulary)) {
+            clean = false;
+            continue;
+        }
+        if (seen.has(entry)) {
+            problems.push({ field, message: `${quote(entry)} is listed twice` });
+            clean = false;
+        }
+        seen.add(entry);
+    }
+    return clean;
+};
+/** Refuse a string that does not match the pattern, saying what shape was expected. */
+export const matching = (problems, field, value, pattern, expected) => {
+    if (typeof value === 'string' && pattern.test(value))
+        return true;
+    problems.push({ field, message: `must be ${expected}, got ${quote(value)}` });
+    return false;
+};

package/packages/cli/dist/policy/core/vocabulary.js

@@ -0,0 +1,56 @@
+/**
+ * The closed vocabularies of the policy declaration (RP-76).
+ *
+ * Every value a declaration or a decision record may carry in an enumerated
+ * field is listed here and nowhere else. Adding a value is a schema edit — a
+ * change to this file plus the test that pins the list — never a string a
+ * caller invents at runtime. That is what makes a record auditable: an unknown
+ * word is refused rather than read as something close to a known one.
+ *
+ * Harness-neutral by construction: nothing here names a harness, a vendor, a
+ * native tool or a native path. The per-harness spellings live in
+ * `../harness/`, and `test/template/policy-declaration.test.ts` › "no file
+ * under src/policy/core mentions a harness, a vendor, a native tool or a native
+ * path" is what keeps them out of here.
+ */
+const closed = (values) => Object.freeze(values);
+/**
+ * Whether a declared policy can actually be enforced on a given harness
+ * surface. `UNSUPPORTED` and `INTEGRATION-FAILED` never yield a silent pass:
+ * a decision record carrying either must qualify its verdict `UNVERIFIABLE`
+ * (`./decision-record.ts`). The four states are defined here.
+ */
+export const CAPABILITY_STATES = closed([
+    'SUPPORTED',
+    'DEGRADED',
+    'UNSUPPORTED',
+    'INTEGRATION-FAILED',
+]);
+/** The autonomy tiers of `rules/autonomy.md`; `never` is the tier the guards enforce. */
+export const AUTONOMY_TIERS = closed(['tier-0', 'tier-1', 'tier-2', 'never']);
+/** The operations a policy can apply to, named by what the agent does, not by a tool. */
+export const OPERATIONS = closed(['file-edit', 'shell-command']);
+/** When the mechanism decides, relative to the operation it judges. */
+export const ENFORCEMENT_TIMINGS = closed(['before-operation']);
+/** What a harness must provide for the mechanism to run at all. */
+export const HARNESS_CAPABILITIES = closed(['pre-operation-hook']);
+/**
+ * The three outcomes a guard can reach: allow, block, or refuse to inspect —
+ * the third being neither a match nor an error (`rules/invariants.md`,
+ * "Refusing to inspect is a third outcome").
+ */
+export const DECISION_OUTCOMES = closed(['allow', 'block', 'refuse-to-inspect']);
+/** What a mechanism does when it cannot decide: let the operation through, or stop it. */
+export const FAILURE_SEMANTICS = closed(['fail-open', 'fail-closed']);
+/** The kinds of evidence a decision record may carry, and a policy may require. */
+export const EVIDENCE_KINDS = closed(['exit-code', 'diagnostic-text', 'test-pointer']);
+/** How a mechanism treats what it matched when it reports: verbatim, or omitted. */
+export const REDACTION_RULES = closed(['none', 'omit-matched-values']);
+/** Where a policy is in its life; a `retired` policy is no longer offered by the registry. */
+export const LIFECYCLE_STATES = closed(['active', 'deprecated', 'retired']);
+/**
+ * The two ways a verdict can say "this word is weaker than it looks": the
+ * question could not be put (`UNVERIFIABLE`), or nothing backs the answer
+ * (`UNMEASURED`). Either one must carry a reason.
+ */
+export const VERDICT_QUALIFIERS = closed(['UNVERIFIABLE', 'UNMEASURED']);

package/packages/cli/dist/policy/harness/claude.js

@@ -0,0 +1,39 @@
+/**
+ * The Claude Code adapter: a declaration → the native hook surface Claude Code
+ * wires for it. The authoring surface of this rulebook is Claude-shaped
+ * (`CLAUDE.md`, "One operating system, two harnesses"), so the hook files
+ * themselves live in the historical directory `./shared-hooks.ts` names and are
+ * shared by every harness.
+ *
+ * What is native here and nowhere in the core: the `PreToolUse` event, the
+ * tool names in the matchers, and the snapshot path. The matcher strings are
+ * the ones `.claude/settings.json` carries, and the correspondence test holds
+ * the two to the SAME tool set, not a subset: a tool dropped here or gained
+ * there is reported for this adapter —
+ * `test/template/policy-declaration.test.ts` › "reports the no-verify policy
+ * on %s when the shell matcher loses PowerShell (mutation: matcher)", › "reports
+ * the no-verify policy on %s when the snapshot gains a tool the adapter does
+ * not name (mutation: widened snapshot)" and › "reports a policy on %s whose
+ * adapter matcher drops a tool the snapshot still wires (mutation: narrowed
+ * adapter)". The shell matcher's tool set is owned by `shell-tools.mjs` in the
+ * shipped scripts, and `test/template/shell-tools.test.ts` holds that
+ * correspondence.
+ */
+import { SHARED_HOOKS_DIR } from './shared-hooks.js';
+const EVENT_OF = {
+    'before-operation': 'PreToolUse',
+};
+const MATCHER_OF = {
+    'file-edit': 'Write|Edit|MultiEdit|NotebookEdit|apply_patch',
+    'shell-command': 'Bash|PowerShell',
+};
+export const nativeSurfaceOf = (policy) => ({
+    event: EVENT_OF[policy.timing],
+    matcher: policy.operations.map((operation) => MATCHER_OF[operation]).join('|'),
+    hookPath: `${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs`,
+});
+export const claudeAdapter = Object.freeze({
+    harness: 'claude',
+    surfaceFile: '.claude/settings.json',
+    nativeSurfaceOf,
+});

package/packages/cli/dist/policy/harness/codex.js

@@ -0,0 +1,40 @@
+/**
+ * The Codex adapter: a declaration → the native hook surface Codex wires for
+ * it. Codex's hook wiring (`.codex/hooks.json`) is DERIVED from the authoring
+ * harness's snapshot by `scripts/sync-codex-adapter.mjs`
+ * (`docs/decisions/codex-adapter.md`): it keeps the authoring harness's matcher
+ * spellings, adds the canonical edit tool `apply_patch`, and runs the same hook
+ * files from the shared hooks directory. So the strings below coincide with the
+ * other adapter's today — by derivation, not by accident — and each adapter
+ * still owns its own spelling. The correspondence test holds this adapter's
+ * matcher and the derived snapshot's to the SAME tool set, so a tool the
+ * snapshot gains or loses, or one this adapter drops, is reported for this
+ * adapter alone — `test/template/policy-declaration.test.ts` › "reports the
+ * no-verify policy on %s when the shell matcher loses PowerShell (mutation:
+ * matcher)", › "reports the no-verify policy on %s when the snapshot gains a
+ * tool the adapter does not name (mutation: widened snapshot)" and › "reports
+ * a policy on %s whose adapter matcher drops a tool the snapshot still wires
+ * (mutation: narrowed adapter)".
+ *
+ * The shared hooks directory is imported from `./shared-hooks.ts` rather than
+ * restated, for the same reason the snapshot is derived rather than
+ * hand-written: one spelling of one fact.
+ */
+import { SHARED_HOOKS_DIR } from './shared-hooks.js';
+const EVENT_OF = {
+    'before-operation': 'PreToolUse',
+};
+const MATCHER_OF = {
+    'file-edit': 'Write|Edit|MultiEdit|NotebookEdit|apply_patch',
+    'shell-command': 'Bash|PowerShell',
+};
+export const nativeSurfaceOf = (policy) => ({
+    event: EVENT_OF[policy.timing],
+    matcher: policy.operations.map((operation) => MATCHER_OF[operation]).join('|'),
+    hookPath: `${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs`,
+});
+export const codexAdapter = Object.freeze({
+    harness: 'codex',
+    surfaceFile: '.codex/hooks.json',
+    nativeSurfaceOf,
+});

package/packages/cli/dist/policy/harness/index.js

@@ -0,0 +1,15 @@
+/**
+ * The harness adapters this generator knows. Adding a harness is one new
+ * module beside these two and one entry in the list below — nothing in
+ * `../core/` changes, which `test/template/policy-declaration.test.ts` ›
+ * "codex is named only by its own adapter and the adapter index" pins by
+ * naming exactly the files that may mention each harness.
+ */
+import { claudeAdapter } from './claude.js';
+import { codexAdapter } from './codex.js';
+export { claudeAdapter, codexAdapter };
+export { SHARED_HOOKS_DIR } from './shared-hooks.js';
+export const HARNESS_ADAPTERS = Object.freeze([
+    claudeAdapter,
+    codexAdapter,
+]);

package/packages/cli/dist/policy/harness/shared-hooks.js

@@ -0,0 +1,10 @@
+/**
+ * The one directory every harness runs its hook files from. The rulebook's
+ * `.claude/` directory keeps its historical name but holds the shared rules,
+ * hooks, scripts and agent specifications for both harnesses (`CLAUDE.md`,
+ * "One operating system, two harnesses"), so a hook path is the same string
+ * whichever adapter names it. Stated once, here, and imported by each adapter
+ * — one spelling of one fact (`rules/invariants.md`, "One mechanism, one
+ * implementation").
+ */
+export const SHARED_HOOKS_DIR = '.claude/hooks';

package/packages/cli/dist/policy/index.js

@@ -0,0 +1,10 @@
+/**
+ * The policy declaration, registry, decision-record schema and harness
+ * adapters (RP-76). Library surface only — nothing here is reached by the CLI
+ * commands yet; emitting decision records at runtime is a separate task.
+ */
+export * from './core/vocabulary.js';
+export * from './core/declaration.js';
+export * from './core/registry.js';
+export * from './core/decision-record.js';
+export * from './harness/index.js';

package/templates/agent-os/universal/.agents/skills/loop/SKILL.md

@@ -153,9 +153,13 @@ node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run
 
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
 on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
-rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
-scripts, queue config and integrity manifest — is refused unless its
-path starts with an allowed prefix; the board selector is the one always-refused
+rulebook is refused unless its
+path starts with an allowed prefix. 🔴 **Which paths that covers is
+`RULEBOOK_PREFIXES` in `.claude/scripts/unattended-flag.mjs`** — read it before
+composing an allow-list, rather than working from a summary here. A summary is a
+second copy, and the one that used to sit in this sentence had gone stale against
+the set it described. One fact the set cannot carry, so it is stated: the board
+selector is the one always-refused
 exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
 item that needs a rulebook path names it here — a decision made at claim
 time, never a default — and the stop step below turns the flag off. Pinned in

package/templates/agent-os/universal/.claude/rules/autonomy.md

@@ -99,7 +99,7 @@ own cost figures are read next to the lane they do not cover.
   `MultiEdit`, `NotebookEdit`, or `apply_patch` that names a credential file or carries a credential value,
   reading its vocabulary from `.claude/scripts/lib/secrets.mjs`. ⚠ **Only that
   part.** The hook sees what an agent writes through those five tools and
-  nothing else — its own header states the four blind spots — so whether a
+  nothing else — its own header states its blind spots — so whether a
   credential typed by a human, or committed from disk, is also refused depends
   on whether this project has a commit-time check. Look at `.husky/` and the CI
   workflow; this file cannot tell you, and a
@@ -108,15 +108,25 @@ own cost figures are read next to the lane they do not cover.
   at runtime instead of writing it out, or the check reports its own test data as
   a leak.
 - touch production data outside a reviewed migration
-- edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it.
-  The rulebook is both harnesses' instruction, agent, skill, script and hook
-  trees (`CLAUDE.md`, `AGENTS.md`, `.claude/{agents,hooks,rules,scripts,skills}`,
-  `.agents/`, `.codex/`), plus `.claude/settings.json`, the queue config and its
-  always-refused board selector, and the integrity manifest. Mechanical:
+- edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it,
+  and the checkout board selector is refused **even when the item's allow-list
+  names it**; that one carve-out does not follow from the set below.
+  The rulebook is both harnesses' instruction, rule, agent, skill, script and
+  hook trees, plus the settings, queue, exemption and integrity files that decide
+  what a session may do. **Which paths exactly is not restated here**: the
+  mechanism reads them from `RULEBOOK_PREFIXES` in
+  `.claude/scripts/unattended-flag.mjs`, and so should you — the guard judges an
+  edit against it, and the flag writer refuses an allow entry that *widens* it.
+  Which entries those are is `isWidening`'s answer in that same module, not a
+  paraphrase here: pinned in the generator's `unattended-flag.test.ts` — absent
+  in a generated rig — › "explains exact protected-prefix refusal separately
+  from proper-prefix widening". An entry
+  outside the set — ordinary source — is not widening and is accepted. A second
+  copy in prose is a copy that goes stale, and this one did. Mechanical:
   the hook refuses the edit while the unattended flag the `loop` skill writes
   at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), and does
   nothing in an attended session. ⚠ It sees edit tool calls only — a
-  shell redirect into `.claude/settings.json` is not one — and the flag, not
+  shell redirect into a protected file is not one — and the flag, not
   the run, is what arms it; its header states the rest of its limits.
 
 ## Stop rules — by work-state, not by feelings

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -153,9 +153,13 @@ node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run
 
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
 on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
-rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
-scripts, queue config and integrity manifest — is refused unless its
-path starts with an allowed prefix; the board selector is the one always-refused
+rulebook is refused unless its
+path starts with an allowed prefix. 🔴 **Which paths that covers is
+`RULEBOOK_PREFIXES` in `.claude/scripts/unattended-flag.mjs`** — read it before
+composing an allow-list, rather than working from a summary here. A summary is a
+second copy, and the one that used to sit in this sentence had gone stale against
+the set it described. One fact the set cannot carry, so it is stated: the board
+selector is the one always-refused
 exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
 item that needs a rulebook path names it here — a decision made at claim
 time, never a default — and the stop step below turns the flag off. Pinned in

package/templates/hash-history.json

@@ -9,7 +9,8 @@
     "0.6.0",
     "0.6.1",
     "0.6.2",
-    "0.7.0"
+    "0.7.0",
+    "0.7.1"
   ],
   "files": {
     ".agents/skills/check-premises/SKILL.md": {
@@ -59,7 +60,8 @@
       "hashes": [
         "a2fb0d03c65701af9d2d69cbcb2582ae573f097b1e1071eb2916e5e4f7832b37",
         "9616e4767942b2021e34ab7bb76eec9a5c280cc608a0756abb02743741d5fc8a",
-        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8"
+        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8",
+        "dc1d9c02879e383448f2336ae6433f960f86e8f8efb4ab8ccf9a17a5f7f524c3"
       ]
     },
     ".agents/skills/ro-debug/SKILL.md": {
@@ -438,7 +440,8 @@
       "hashes": [
         "32f847a2a3a5136cabcb42f6447da9f8cf98e2d20512212ee5201461128d7798",
         "b62348a27bcaa1d62a0e4ddd53873fab6cb75f9af8e8c69d24f6ce81c592c4e3",
-        "b151045e8083c398e94571b35dc9568dfa0102abcb847cdf764f6f694914d53e"
+        "b151045e8083c398e94571b35dc9568dfa0102abcb847cdf764f6f694914d53e",
+        "f756b7ccc2a4459e58b2125408de1f91372cd6093bf6f4ed14e26dc2eb4190fc"
       ]
     },
     ".claude/scripts/revalidation-report.mjs": {
@@ -550,7 +553,8 @@
         "75adb84414a330db621ff4f1363b3926f537133199236a9e25bb9880b935e02e",
         "a2fb0d03c65701af9d2d69cbcb2582ae573f097b1e1071eb2916e5e4f7832b37",
         "9616e4767942b2021e34ab7bb76eec9a5c280cc608a0756abb02743741d5fc8a",
-        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8"
+        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8",
+        "dc1d9c02879e383448f2336ae6433f960f86e8f8efb4ab8ccf9a17a5f7f524c3"
       ]
     },
     ".claude/skills/ro-debug/SKILL.md": {

package/templates/release-ledger.json

@@ -9,5 +9,6 @@
   "0.6.0": "29ca0543368e922349945e52541a92b46ddcc5bd",
   "0.6.1": "f1d1e3dbd2161545d77ee5e7f90fa8e74b8a9f3e",
   "0.6.2": "2a1fc8e10cd2b65deb5c95d937fd7de39f2c92a2",
-  "0.7.0": "6589db36e1daa63a99ec595191db1cccf7373196"
+  "0.7.0": "6589db36e1daa63a99ec595191db1cccf7373196",
+  "0.7.1": "52e879b6c103f6ba70493007b6a6466c57ea9824"
 }