@event4u/agent-config 13.0.0 → 14.0.0

package/src/scripts/rule_activation_census.ts

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * Rule-activation census — which rules the Claude host projection scopes, and why.
+ *
+ * `road-to-mixed-trigger-activation-cost` step 1.0. It exists because the field
+ * check that roadmap inherited from its source analysis is **refuted as a
+ * discriminator**:
+ *
+ *     grep -l '^paths:' .claude/rules/*.md | wc -l
+ *
+ * The source predicted ~25 for a pre-guard projection and ~6 for a post-guard
+ * one, so a colleague could decide in one minute whether the mixed-trigger flip
+ * was live on their machine. Run on a maintainer checkout it returns **0** —
+ * neither number — because `.claude/rules/` is a generated, gitignored artefact
+ * whose scope and freshness are unknown at read time. A reading of 0 is
+ * consistent with "the flip is live", with "this projection was generated at a
+ * different `--scope`", and with "this projection is simply stale", and the
+ * grep cannot tell those apart. A probe whose three possible causes are
+ * indistinguishable is not a probe.
+ *
+ * This census reads the **source** instead, and reads it through the emitter's
+ * own exported functions rather than a reimplementation: `_parse_frontmatter`
+ * for the frontmatter, `_has_non_path_trigger` for the mixed test, and
+ * `_claude_paths_plan` for the verdict. So "would this rule be scoped" is
+ * answered by the code that actually decides it — the method the source
+ * analysis used across two tags, applied to one tree.
+ *
+ * `_parse_frontmatter` is exported from `condense.ts` for exactly this, and it is
+ * the reason the export carries only a one-line pointer there: `condense.ts` sits
+ * far above the 1,500-line source ceiling, so every line added to it counts
+ * against the `check_source_size_budget` ratchet. The rationale lives here, in a
+ * file the ratchet does not charge, rather than in the file it does.
+ * A reimplemented parse is the divergence class that made the shipped
+ * `.claude/rules/` count unreadable as evidence in the first place.
+ *
+ * What it does NOT do, stated because the distinction is the whole point: it
+ * does not tell you what a given machine's `.claude/rules/` currently holds.
+ * That is a property of an install, not of the repo. `--projection` reads the
+ * host projection alongside the source and reports the two side by side,
+ * labelled, so a divergence is visible as a divergence instead of being averaged
+ * into one misleading number.
+ *
+ * CLI contract: exit 0 always on a successful scan — this is an instrument, not
+ * a gate. `--json` emits the machine-readable record, `--projection <dir>` adds
+ * the host-projection column, `--quiet` suppresses the human table.
+ * The gate that ratchets these numbers is `check_rule_activation_census.ts`
+ * (step 4.1); keeping measurement and enforcement in separate files is why this
+ * one has no failure exit.
+ *
+ * The filename is deliberately NOT `check_`/`lint_`-prefixed. That prefix set is
+ * what `_lib/gate_population.ts` treats as gate-shaped, and a file in the gate
+ * population owes the ledger a per-target accounting — which an instrument that
+ * cannot fail has nothing honest to report. The name carries the distinction so
+ * no `// ledger-exempt:` marker is needed here; a marker would assert an
+ * exemption from an obligation this file never incurs.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { _claude_paths_plan, _has_non_path_trigger, _parse_frontmatter } from './condense.js';
+
+const RULES_DIR = path.join('src', 'rules');
+
+/** Trigger keys that describe a file path rather than prompt text. */
+const PATH_TRIGGER_KEYS = ['file_pattern', 'path_prefix'] as const;
+
+/** Trigger keys that describe prompt text rather than a file path. */
+const TEXT_TRIGGER_KEYS = ['keyword', 'phrase'] as const;
+
+export interface RuleActivation {
+    /** Rule id — the basename without `.md`. */
+    id: string;
+    /** `always` / `auto` / `manual`, or `unknown` when the field is absent. */
+    type: string;
+    /** Declares at least one `file_pattern` or `path_prefix` trigger. */
+    has_path_trigger: boolean;
+    /** Declares at least one `keyword` or `phrase` trigger. */
+    has_text_trigger: boolean;
+    /** Both of the above — the class the mixed-triggers guard governs. */
+    mixed: boolean;
+    /** Globs the emitter would write under `paths:`. Empty means unconditional. */
+    emitted_globs: string[];
+    /** Patterns the emitter deliberately drops, with the reason it records. */
+    dropped: { pattern: string; reason: string }[];
+    /**
+     * The emitter's verdict in one word.
+     * `scoped` — loads on a path match · `unconditional` — loads every session ·
+     * `always` — an Iron-Law rule, unconditional by design and never a candidate.
+     */
+    verdict: 'scoped' | 'unconditional' | 'always';
+}
+
+function _trigger_list(meta: Record<string, unknown>): Record<string, unknown>[] {
+    const raw = meta['triggers'];
+    if (!Array.isArray(raw)) return [];
+    return raw.filter(
+        (t): t is Record<string, unknown> =>
+            t !== null && typeof t === 'object' && !Array.isArray(t),
+    );
+}
+
+function _declares(meta: Record<string, unknown>, keys: readonly string[]): boolean {
+    for (const t of _trigger_list(meta)) {
+        for (const k of keys) {
+            const v = t[k];
+            if (typeof v === 'string' && v) return true;
+        }
+    }
+    return false;
+}
+
+/** Classify one rule file through the emitter's own exported decision path. */
+export function classify_rule(id: string, content: string): RuleActivation {
+    const [meta] = _parse_frontmatter(content);
+    const plan = _claude_paths_plan(meta);
+    const has_path_trigger = _declares(meta, PATH_TRIGGER_KEYS);
+    const has_text_trigger = _declares(meta, TEXT_TRIGGER_KEYS);
+    const type = typeof meta['type'] === 'string' ? (meta['type'] as string) : 'unknown';
+    const always = Boolean(meta['alwaysApply'] || type === 'always');
+
+    // `_has_non_path_trigger` is the guard's own predicate and is deliberately
+    // narrower than `has_text_trigger` looks: it ignores `command:` triggers.
+    // Reported separately rather than conflated, because a rule that is mixed by
+    // the guard's definition is the one that flipped.
+    const mixed = has_path_trigger && _has_non_path_trigger(meta);
+
+    let verdict: RuleActivation['verdict'];
+    if (always) verdict = 'always';
+    else if (plan.globs.length > 0) verdict = 'scoped';
+    else verdict = 'unconditional';
+
+    return {
+        id,
+        type,
+        has_path_trigger,
+        has_text_trigger,
+        mixed,
+        emitted_globs: plan.globs,
+        dropped: plan.dropped.map((d) => ({ pattern: d.pattern, reason: d.reason })),
+        verdict,
+    };
+}
+
+export function census(root: string): RuleActivation[] {
+    const dir = path.join(root, RULES_DIR);
+    const files = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+        .map((e) => e.name)
+        .sort();
+    return files.map((f) =>
+        classify_rule(f.replace(/\.md$/, ''), fs.readFileSync(path.join(dir, f), 'utf8')),
+    );
+}
+
+/**
+ * Read a host projection's own `paths:` count.
+ *
+ * Reported beside the source census, never merged into it. The two answer
+ * different questions — "what would the emitter do with this tree" versus "what
+ * does this directory currently contain" — and the second carries no record of
+ * the scope or the commit it was generated at, which is exactly why the grep it
+ * replaces could not be read as evidence.
+ */
+export function projection_reading(dir: string): { files: number; with_paths: number } | null {
+    if (!fs.existsSync(dir)) return null;
+    const files = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+        .map((e) => e.name);
+    let with_paths = 0;
+    for (const f of files) {
+        const text = fs.readFileSync(path.join(dir, f), 'utf8');
+        if (/^paths:/m.test(text)) with_paths += 1;
+    }
+    return { files: files.length, with_paths };
+}
+
+export interface CensusSummary {
+    total: number;
+    path_shaped: number;
+    mixed: number;
+    path_only: number;
+    scoped: number;
+    unconditional: number;
+    always: number;
+    mixed_ids: string[];
+    path_only_ids: string[];
+    scoped_ids: string[];
+}
+
+export function summarize(rows: RuleActivation[]): CensusSummary {
+    const path_shaped = rows.filter((r) => r.has_path_trigger);
+    const mixed = path_shaped.filter((r) => r.mixed);
+    const path_only = path_shaped.filter((r) => !r.mixed);
+    return {
+        total: rows.length,
+        path_shaped: path_shaped.length,
+        mixed: mixed.length,
+        path_only: path_only.length,
+        scoped: rows.filter((r) => r.verdict === 'scoped').length,
+        unconditional: rows.filter((r) => r.verdict === 'unconditional').length,
+        always: rows.filter((r) => r.verdict === 'always').length,
+        mixed_ids: mixed.map((r) => r.id),
+        path_only_ids: path_only.map((r) => r.id),
+        scoped_ids: rows.filter((r) => r.verdict === 'scoped').map((r) => r.id),
+    };
+}
+
+function _arg(flag: string): string | null {
+    const argv = process.argv.slice(2);
+    const i = argv.indexOf(flag);
+    return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+}
+
+export function main(): number {
+    const argv = process.argv.slice(2);
+    const as_json = argv.includes('--json');
+    const quiet = argv.includes('--quiet');
+    const root = _arg('--root') ?? process.cwd();
+    const projection_dir = _arg('--projection');
+
+    const rows = census(root);
+    const sum = summarize(rows);
+    const projection = projection_dir
+        ? projection_reading(path.isAbsolute(projection_dir)
+            ? projection_dir
+            : path.join(root, projection_dir))
+        : null;
+
+    if (as_json) {
+        process.stdout.write(
+            `${JSON.stringify({ summary: sum, projection, rules: rows }, null, 2)}\n`,
+        );
+        return 0;
+    }
+    if (quiet) return 0;
+
+    process.stdout.write('Rule-activation census — source of truth is src/rules/\n\n');
+    process.stdout.write(`  rule files                     ${sum.total}\n`);
+    process.stdout.write(`  declaring a path-shaped trigger ${sum.path_shaped}\n`);
+    process.stdout.write(`    …of those, MIXED (also keyword/phrase) ${sum.mixed}\n`);
+    process.stdout.write(`    …of those, path-only                   ${sum.path_only}\n`);
+    process.stdout.write('\n  emitter verdict:\n');
+    process.stdout.write(`    scoped (loads on a path match) ${sum.scoped}\n`);
+    process.stdout.write(`    unconditional (every session)  ${sum.unconditional}\n`);
+    process.stdout.write(`    always (Iron Law, by design)   ${sum.always}\n`);
+
+    if (sum.mixed > 0) {
+        process.stdout.write(
+            `\n  the mixed set — these load every session and are the flip's cost:\n`,
+        );
+        for (const id of sum.mixed_ids) process.stdout.write(`    - ${id}\n`);
+    }
+
+    if (projection) {
+        process.stdout.write(
+            `\n  host projection at ${projection_dir} — reported SEPARATELY, not merged:\n` +
+                `    files ${projection.files} · declaring paths: ${projection.with_paths}\n`,
+        );
+        if (projection.with_paths !== sum.scoped) {
+            process.stdout.write(
+                `    ⚠️  diverges from the source verdict (${sum.scoped} scoped). A projection\n` +
+                    `        carries no record of the scope or commit it was generated at, so this\n` +
+                    `        is a reason to regenerate it — never a reading of the emitter.\n`,
+            );
+        }
+    } else if (projection_dir) {
+        // Three states, kept apart on purpose. Collapsing "you asked and the
+        // directory is not there" into "you did not ask" would reproduce, in this
+        // script's own output, the exact conflation it was written to end — and a
+        // fresh worktree has no `.claude/` at all, so this is the common case.
+        process.stdout.write(
+            `\n  host projection at ${projection_dir}: DIRECTORY ABSENT.\n` +
+                '  Not a reading of zero — there is nothing to read. A generated projection is\n' +
+                '  absent in a fresh worktree until `task generate-tools` has run.\n',
+        );
+    } else {
+        process.stdout.write(
+            '\n  no --projection given: this census describes the SOURCE only.\n' +
+                '  It deliberately makes no claim about any machine\'s .claude/rules/.\n',
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(fileURLToPath(import.meta.url)).href) {
+    const invoked = path.resolve(process.argv[1]);
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    if (invoked === self) process.exit(main());
+}

package/src/scripts/schemas/evaluator-output.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "evaluator-output.schema.json",
+  "title": "Evaluator output",
+  "description": "ONE shape for a mechanical verifier's machine-readable verdict, so a loop that optimizes against a metric is decoupled from the verifier producing it. Measured before drafting (spike s02, agents/evidence/eval-findings/metric-loop-s02.md): three existing verifiers — validate_frontmatter, lint_output_slop, check_references — were wrapped in this shape with ZERO invasive changes to the verifiers, so the contract is transplantable onto the surface that exists rather than one that would have to be built. The error semantics live in docs/contracts/evaluator-output.md; without them every caller invents its own failure handling, which is the half that makes a contract usable.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "name",
+    "pass",
+    "score"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ],
+      "description": "Pinned. Spelled as a one-member `enum` rather than `const` for the same measured reason review-findings.schema.json records: this repo's Draft-07 subset validator enforces `enum` and silently ignores `const`, so a `const` here would be a pin nothing checks."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120,
+      "description": "Stable identifier of the evaluator, not of the run. The loop register keys decisions on it, so renaming an evaluator starts a new metric series rather than continuing the old one — which is the honest behaviour, since the numbers are not comparable across a definition change."
+    },
+    "pass": {
+      "type": "boolean",
+      "description": "Did the underlying verifier accept the tree? This is the SOVEREIGN field: a keep-or-revert loop gates on `pass && score > baseline`, never on `score` alone. Measured in spike s01 — a change that improved the metric by 67 % and broke behaviour was reverted only because `pass` was false. A loop reading `score` alone keeps it."
+    },
+    "score": {
+      "type": "number",
+      "description": "HIGHER IS BETTER, always. A verifier whose natural metric is a violation count negates it (`score = -violations`), so every consumer compares with one operator and no caller has to know the direction. `direction` records which way the raw metric ran, for humans reading the register; it is never the comparison input."
+    },
+    "metric": {
+      "type": "number",
+      "description": "The raw, un-negated measurement. ABSENT — not null — when there is no number to report; `metric_state` then says why. Spelled as an optional `number` rather than `[\"number\", \"null\"]` for a measured reason, the same class as the `const`-vs-`enum` note above: this repo's Draft-07 subset validator rejects an array-typed `type` outright (`Unsupported schema type 'number,null'`), so a union here would have failed every conformant emitter. Spike s02 produced the distinction the field encodes: check_references writes its count to stderr, and a stdout-only reader reported no metric beside `pass: true` — a degraded reading indistinguishable from an evaluator that legitimately has no number."
+    },
+    "metric_state": {
+      "enum": [
+        "present",
+        "absent",
+        "unreadable"
+      ],
+      "description": "Why `metric` holds what it holds. `present` — a number was read. `absent` — this evaluator has no scalar metric by design. `unreadable` — a metric was expected and could not be parsed; the run is DEGRADED and a loop must treat it as a failed experiment rather than as a zero. Defaulting `unreadable` to `absent` is the exact silent degradation this field exists to make impossible."
+    },
+    "direction": {
+      "enum": [
+        "maximize",
+        "minimize"
+      ],
+      "description": "Which way the RAW metric runs. Documentation for a human reading the register, never a comparison input — `score` has already absorbed the direction. Recorded because a register row showing `metric: 3` is uninterpretable without it."
+    },
+    "error": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Present only when the evaluator itself failed to produce a verdict (as opposed to the verifier reporting a red tree, which is `pass: false` with no error). The two are different events for a loop: a red tree is a result to act on, an evaluator failure is a measurement that did not happen."
+    }
+  }
+}

package/src/scripts/schemas/review-findings.schema.json

@@ -20,6 +20,37 @@
       "type": "string",
       "description": "Version the ledger belongs to. Present on the release-findings ledger (agents/evidence/release-findings/<version>.json); absent on a bare --findings-out emission, which is why it is not required here."
     },
+    "review_independence": {
+      "enum": [
+        "cross-family",
+        "same-family",
+        "single-member",
+        "unknown"
+      ],
+      "description": "Whether the reviewer set spans more than one model family. Added because the artifact was previously silent on it: the self-review gate calls ONE Anthropic client, and the ledger it wrote was byte-indistinguishable from one backed by independent models — so a consumer read 'no findings' as acceptance either way. `unknown` is an honest value for a set that was not recorded, NOT a synonym for cross-family."
+    },
+    "acceptance_status": {
+      "enum": [
+        "accepted",
+        "provisional"
+      ],
+      "description": "What a consumer may claim this artifact establishes. DERIVED from `review_independence` (see _lib/review_independence.ts), never set independently: two fields a producer can set inconsistently reintroduce exactly the ambiguity the pair removes, and a same-family set carrying `accepted` would still read as acceptance to anyone scanning one field. Only `cross-family` yields `accepted`; `unknown` yields `provisional`, because an unrecorded member set is not evidence of independence."
+    },
+    "assurance": {
+      "enum": [
+        "unreviewed",
+        "single-pass",
+        "independent"
+      ],
+      "description": "How much INDEPENDENT evidence backs the verdict — deliberately orthogonal to how much effort the review spent. Collapsing the two is the mechanism by which a long, careful, single-model pass reads as acceptance: effort is visible in the artifact (finding count, detail, rationale) and independence is not, so a reader with only one axis substitutes the one they can see. A five-hour same-family review is `single-pass`; a terse two-family one is `independent`."
+    },
+    "reviewers": {
+      "type": "array",
+      "description": "The member names the independence verdict was derived from, recorded so the derivation is auditable rather than asserted. Provider names as `ai_council/config.ts::_VALID_PROVIDERS` spells them.",
+      "items": {
+        "type": "string"
+      }
+    },
     "findings": {
       "type": "array",
       "description": "May be empty. An empty array is an honest null, not a missing field — the distinction the Markdown track spells with its own §2.3 line. The item shape is INLINED rather than `$ref`-ed for the same measured reason: the subset validator does not resolve `$ref`, so a referenced definition would have validated nothing.",

package/src/scripts/self_review_gate.ts

@@ -35,6 +35,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { AnthropicClient, load_anthropic_key } from './ai_council/clients.js';
+import { independenceFields } from './_lib/review_independence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -458,11 +459,16 @@ export function main(argv: string[]): 0 | 2 {
         if (outIdx >= 0 && argv[outIdx + 1]) {
             // Durable ingestion input for the disposition ledger (release-truth
             // Phase 3): `check_finding_dispositions --ingest <this file>`.
+            // The independence fields are set HERE, at write time, from the
+            // actual reviewer set — which for this gate is one Anthropic client,
+            // so the artifact declares itself single-member and provisional. It
+            // previously said nothing, and silence read as acceptance.
             writeFileSync(
                 argv[outIdx + 1]!,
                 JSON.stringify(
                     {
                         schema_version: 1,
+                        ...independenceFields(['anthropic']),
                         findings: findings.map((f) => ({ finding_id: findingId(f), ...f })),
                     },
                     null,

package/src/scripts/session_register_hook.ts

@@ -67,6 +67,7 @@ import {
     ttl_seconds_for,
     write_record,
 } from './_lib/session_register.js';
+import { pruneAgedRefusalState, readSessionCounts } from './_lib/turn_end_refusals.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
 
 /** Replay-fixture runs must never mutate state (same contract as chat_history). */
@@ -323,7 +324,7 @@ export function build_record(
     started_at: string,
     now: Date = new Date(),
 ): SessionRecord {
-    return {
+    const rec: SessionRecord = {
         session_id,
         platform,
         worktree: workspace_root,
@@ -332,6 +333,20 @@ export function build_record(
         started_at,
         last_seen: iso_now(now),
     };
+    // road-to-stop-gate-honesty step 1.1 — the per-session half of the refusal
+    // counter. Only ever ADDS a field: a session with no refusals leaves the
+    // record byte-identical to what it was before this existed, so a reader that
+    // does not know the field is unaffected and a diff of two records still
+    // shows only what changed.
+    const counts = readSessionCounts(workspace_root, session_id);
+    if (counts !== null) {
+        const nonZero: Record<string, number> = {};
+        for (const [id, n] of Object.entries(counts)) {
+            if (n > 0) nonZero[id] = n;
+        }
+        if (Object.keys(nonZero).length > 0) rec.turn_end_refusals = nonZero;
+    }
+    return rec;
 }
 
 /**
@@ -590,6 +605,20 @@ export function main(): number {
                     );
                 }
             }
+            if (event === 'session_start') {
+                // road-to-stop-gate-honesty step 1.2 — the TTL the gate's own
+                // header admitted was missing. This concern is the carrier
+                // because it is already the session_start pruner: adding a
+                // second prune here costs one directory scan on a slot that
+                // fires once per session, where a new concern would cost a
+                // spawn. Never throws — evidence retention is not a reason to
+                // fail a session start.
+                try {
+                    pruneAgedRefusalState(root, { now: new Date() });
+                } catch {
+                    /* an unprunable directory keeps its files; it is not an error */
+                }
+            }
             if (event === 'session_start') {
                 const block = foreign_sessions_block(root, session_id, new Date());
                 if (block !== null) {