create-agent-rig 0.7.0 → 0.8.0

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/.agents/skills/pr-ship/SKILL.md

@@ -57,13 +57,66 @@ blockers.
    confidently-wrong reviews. Everything below is scoped to this diff.
 
    Then, on the fetched ref, ask whether the branch is still the branch the run
-   took up:
+   took up. **Two paths, and you state which one — the command infers neither.**
+   A branch that is a queue item's take-up:
 
    ```sh
    node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <item-id> --base origin/<default>
    ```
 
-   It runs the existing revalidation chain against the tracked, versioned
+   Owner-directed work or a hotfix that has **no item** — the case step 4 below
+   already tells you to declare to the reviewers:
+
+   ```sh
+   node .claude/scripts/revalidate.mjs --point BEFORE_PR --owner-directed --base origin/<default>
+   ```
+
+   🔴 **The second path is not a lighter checkpoint, and it is never a skip.**
+   It runs the same `main:<path>` comparison and holds on the same exit 2; what
+   it drops is the claim comparison, because work with no item has no claim to
+   compare. It resolves no queue config, so it reaches no tracker and needs no
+   credentials. Passing both flags, or neither, is exit 1.
+
+   **Four refusals** — exit 1, nothing journalled — keep it from being the way
+   around a claim or revalidation failure. It is refused when this run carries
+   an **unresolved revalidation hold** (what the ticketed path writes when it
+   holds or answers `UNVERIFIABLE`), when this run **declares a take-up**, when
+   the branch **touches a tracked `.rig/claims/*.json`** in any direction —
+   added, modified, removed or renamed — and at `BEFORE_CLOSE`. So re-running a
+   held ticketed call in this mode does not get past it: resolve the hold with
+   `outcome` instead.
+
+   ⚠ **What those refusals do not cover**, because a governance mode is trusted
+   exactly as far as it is described:
+
+   - **With no `RIG_RUN_DIR` there is no run state to read**, so the hold and
+     take-up refusals cannot fire — and nothing is journalled. The command says
+     so on stdout and in `evidence.runState`; it is not evidence that neither
+     exists. An attended gate run is exactly this shape, so read that line.
+   - The claim refusal reads the **branch diff**, so a claim record already on
+     the default branch, or written and not committed, is not seen.
+   - **`--base` is the sole authority for the verdict here**, the claim
+     comparison that would otherwise survive a wrong base being absent. Pass
+     the fetched `origin/<default>`, not a local copy and not `HEAD`.
+   - Nothing can prove an item does not exist. The rest is your word, recorded
+     as such, with `ticket: null` and no invented id.
+
+   Pinned in the generator's `test/template/owner-directed-revalidation.test.ts`
+   (absent in a generated rig) › "refuses when this run carries an unresolved
+   revalidation hold", › "refuses when the declared run already carries a
+   take-up", › "refuses when the branch RENAMES a claim record — the case
+   --diff-filter=AM could not see" and › "says out loud that an undeclared run
+   checked neither the hold nor the take-up".
+
+   **Exit 2 here is a HOLD with the same shape as the ticketed one**, and the
+   same two-step remedy: re-read the default branch on each named path, then
+   record what the re-read concluded — `node .claude/scripts/revalidate.mjs
+   outcome --point BEFORE_PR --owner-directed --action-changed <true | false>
+   --note '…'` — and come back through step 0. The owner-directed detection
+   carries no ticket, so `--owner-directed` is how the outcome addresses it;
+   the ticketed `--ticket <item-id>` form below cannot match it and is refused.
+
+   The ticketed path runs the existing revalidation chain against the tracked, versioned
    `.rig/claims/<item-id>.json`: the content-blind `scope` fingerprint set is
    authoritative here, while `takeUps` / `updatedAt` remain evidence only. It
    also names what the default branch changed since this branch forked on paths
@@ -71,14 +124,18 @@ blockers.
    journals one `revalidation` event at `point: BEFORE_PR`; **exit code 2 is a HOLD**, with one blocker per named source: re-read the item, or the default
    branch on that path, record what the re-read concluded —
    `node .claude/scripts/revalidate.mjs outcome --point BEFORE_PR --ticket <item-id> --action-changed <true | false> --note '…'`
-   — and come back through step 0. A hold with no outcome is counted by the
-   report as a re-read the run skipped. A missing, untracked, unreadable or
+   — and come back through step 0. **That `--ticket` form is this path's, not
+   both paths'** — the owner-directed detection carries no ticket for it to
+   name, and its own `--owner-directed` outcome is written out above. A hold
+   with no outcome, in either mode, is counted by the report as a re-read the
+   run skipped. A missing, untracked, unreadable or
    unsupported claim is `UNVERIFIABLE`, exits 2, and stops automatic progress;
    so is a tracker whose adapter the command cannot READ, which means the
    question was never put rather than that the claim record is unreadable.
    Neither is ever read as a pass. Exit 1 is the command refusing (unknown
-   point, no ticket, a base that is not a revision, or a queue config that does
-   not resolve): fix the call or the config — the message says which. Its limits are its own header's; the
+   point, neither mode or both, a base that is not a revision, or a queue config
+   that does not resolve — plus, on the owner-directed path, the four refusals
+   above): fix the call or the config — the message says which. Its limits are its own header's; the
    cited-path set is a labelled assumption, not a recorded fact. Pinned in the
    generator's `test/template/revalidate.test.ts` (absent in a generated rig) ›
    "continues when only updatedAt moved and still reports the marker evidence"
@@ -182,9 +239,13 @@ blockers.
    **Whatever you launch, pass it the text of the queue item this branch
    implements.** A reviewer given only a diff cannot check the change against
    what was asked: a cold context has no way to know, and reconstructing it from
-   the PR description would mean trusting the run under review. If there is no
-   item — owner-directed work, a hotfix — say so when launching, and the
-   reviewer skips that check openly instead of guessing at it.
+   the PR description would mean trusting the run under review. When there is
+   no item — owner-directed work, a hotfix — launch every reviewer with the
+   words **`no item — owner-directed`** instead. That skips the item-contract
+   check, openly, and **nothing else**: the checks, the routing, the security,
+   code and prose/governance reviews, the coverage check and the DoD all still
+   run. It is one check narrower than a ticketed fan-out, not a cheaper gate,
+   and the same words are what step 1's `--owner-directed` call records.
 
    🔴 **The triggers below are lane-independent and may only ADD.** They read
    *what the code does*; the router reads *paths*, and a path cannot say that a

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