@event4u/agent-config 9.27.0 → 9.28.0

package/src/scripts/measure_scope_dedup.ts

@@ -25,6 +25,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
+import { comparePair } from './_lib/carrier_divergence.js';
 import { censusRuleDir } from './preamble_byte_census.js';
 
 const REPO_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
@@ -91,17 +92,15 @@ function dedupableCount(userDir: string, sourceDir: string): { skipped: number;
  * perfect version alignment. Classifying the two apart is what turns "0/110"
  * from a puzzle into an answer: `provenanceOnly == total` means aligning
  * versions would buy exactly nothing.
+ *
+ * The three-way comparison now lives in `_lib/carrier_divergence.ts` because a
+ * second surface needs it (`report_carrier_divergence`, round-5 Phase 1.3). The
+ * DIRECTORY WALK stays here and stays anchored on `sourceDir`: this harness asks
+ * how many installed twins the dedup could skip, which is a question about the
+ * projection's own rules, not about the union of both carriers. Only the
+ * comparison is shared — that is the part that must not drift, and it is also
+ * the part `scope_dedup.test.ts` pins.
  */
-const OWNERSHIP_KEYS = ['package', 'source_path'] as const;
-
-function stripOwnershipKeys(buf: Buffer): string {
-    return buf
-        .toString('utf-8')
-        .split('\n')
-        .filter((line) => !OWNERSHIP_KEYS.some((k) => line.startsWith(`${k}:`)))
-        .join('\n');
-}
-
 interface ReachabilitySplit {
     total: number;
     identical: number;
@@ -130,9 +129,16 @@ function classifyReachability(userDir: string, sourceDir: string): ReachabilityS
             continue;
         }
         const b = fs.readFileSync(path.join(sourceDir, entry));
-        if (a.equals(b)) split.identical += 1;
-        else if (stripOwnershipKeys(a) === stripOwnershipKeys(b)) split.provenanceOnly += 1;
-        else split.bodyDiff += 1;
+        switch (comparePair(a, b)) {
+            case 'identical':
+                split.identical += 1;
+                break;
+            case 'provenance-only':
+                split.provenanceOnly += 1;
+                break;
+            default:
+                split.bodyDiff += 1;
+        }
     }
     return split;
 }

package/src/scripts/onboarding_gate_hook.ts

@@ -39,6 +39,45 @@ import { atomic_write_json } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 
 export const SETTINGS_FILE = ".agent-settings.yml";
+
+/**
+ * Project-relative settings locations, canonical first.
+ *
+ * The canonical project settings file is `agents/settings/.agent-settings.yml`;
+ * the repo-root file is a documented legacy fallback
+ * (`agent_settings.ts::project_settings_path`). This hook read ONLY the legacy
+ * path, so on a canonically installed consumer the file was always "missing" and
+ * the gate resolved to `settings_file_missing` → do not block. An Iron-Law gate
+ * that cannot fire on a correct install is not a gate.
+ *
+ * Inlined rather than imported: this module is deliberately dependency-free so
+ * it can run as a hook on every platform. The list is two entries and its source
+ * of truth is named above.
+ */
+export const SETTINGS_CANDIDATES: readonly string[] = [
+  path.join("agents", "settings", SETTINGS_FILE),
+  SETTINGS_FILE,
+];
+
+/**
+ * First existing settings file under `consumer_root`, canonical before legacy.
+ *
+ * Falls back to the CANONICAL path when neither exists, so the "missing" branch
+ * reports the file a consumer should create rather than the one they should not.
+ */
+export function resolve_settings_path(consumer_root: string): string {
+  for (const rel of SETTINGS_CANDIDATES) {
+    const candidate = path.join(consumer_root, rel);
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return path.join(consumer_root, SETTINGS_CANDIDATES[0] as string);
+}
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — this is a latent
 // docstring/code divergence in the retired Python implementation (ADR-200 § replicate
@@ -141,7 +180,7 @@ export function run(options: {
 }): number {
   const { consumer_root } = options;
   const verbose = options.verbose ?? false;
-  const settings_path = path.join(consumer_root, SETTINGS_FILE);
+  const settings_path = resolve_settings_path(consumer_root);
   let settings_present = false;
   try {
     settings_present = fs.statSync(settings_path).isFile();

package/src/scripts/orchestration_record.ts

@@ -41,7 +41,10 @@ import {
     type RouteTaken,
 } from './_lib/orchestration_record.js';
 
-const DEFAULT_DIR = 'agents/runtime/state/audit';
+// Exported so other writers of the same audit-log-v1 orchestration line
+// (e.g. orchestration_record_hook.ts, the deterministic PostToolUse capture)
+// target the exact same directory instead of duplicating the literal.
+export const DEFAULT_DIR = 'agents/runtime/state/audit';
 
 type Flags = Record<string, string | boolean>;
 

package/src/scripts/preamble_byte_census.ts

@@ -44,6 +44,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as YAML from 'yaml';
 
 import { resolveGlobalProfilePath } from './_lib/agent_user_profile.js';
+import { censusRuleDir, type RuleDirCensus } from './_lib/carrier_divergence.js';
 import { DEFAULT_PROJECTS_ROOT, scanTranscripts } from './_lib/cc_transcript.js';
 import { censusDuplicateScope } from './_lib/duplicate_scope_census.js';
 import { computeColdStarts } from './cache_realization_report.js';
@@ -71,26 +72,14 @@ function readCharsIfExists(p: string): number {
 
 // ── source 1/2: rule directories ────────────────────────────────────────
 
-export interface RuleDirCensus {
-    files: number;
-    chars: number;
-}
-
-export function censusRuleDir(dir: string): RuleDirCensus {
-    if (!fs.existsSync(dir)) return { files: 0, chars: 0 };
-    let files = 0;
-    let chars = 0;
-    for (const name of fs.readdirSync(dir)) {
-        if (!name.endsWith('.md')) continue;
-        try {
-            chars += fs.statSync(path.join(dir, name)).size;
-            files += 1;
-        } catch {
-            // Unreadable entry — skip rather than fail the whole census.
-        }
-    }
-    return { files, chars };
-}
+// Moved to `_lib/carrier_divergence.ts` when `conformance_scan` needed the same
+// count (round-6 Phase 4.3): that module is on a bundled CLI path and this one
+// pulls `yaml` plus the cold-start report, so importing this file to reach fifteen
+// lines of `statSync` was the wrong direction. Re-exported so every existing
+// caller keeps its import and there is still one definition. Imported as well as
+// re-exported: a bare `export … from` does not bind the name in this module's own
+// scope, and this file uses both below.
+export { censusRuleDir, type RuleDirCensus };
 
 export interface PerRuleCost {
     file: string;

package/src/scripts/report_carrier_divergence.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env tsx
+/**
+ * report_carrier_divergence.ts — which rules the two carriers deliver
+ * differently, BY NAME.
+ *
+ * Executes round-5 Phase 1.3, landed under round-6 Phase 4.1. Advisory: **it
+ * gates on nothing** and must not acquire a threshold, for the reason
+ * `report_skill_activation` and `report_imperative_density` must not — plus one
+ * specific to this surface, below.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The suite installs machine-globally (`~/.claude/rules/`) and the package's own
+ * checkout also projects per-project (`dist/agent-src/rules/`, which every
+ * project-scope tree symlinks). A machine that has both loads the shared rules
+ * twice, and nothing said whether the two copies agree. Round 5 measured the
+ * condition once and named the dangerous case: its global copy of
+ * `git-history-discipline` asserted an unqualified "deterministically blocked by
+ * the `block-no-verify` PreToolUse guard" while the shipped copy carried the
+ * host-scoped retraction of exactly that claim. The agent held both, with no
+ * precedence marker.
+ *
+ * A one-off measurement cannot own that condition, because the condition is
+ * **transient and maintainer-dependent**: it appears when the checkout moves
+ * ahead of the installed release and disappears the next time the maintainer
+ * reinstalls. Verified both directions — see § THE 2026-08-08 RE-MEASUREMENT.
+ * So the deliverable is a report anyone can re-run, not a number in a roadmap.
+ *
+ * WHY IT MUST NOT BECOME A GATE
+ * -----------------------------
+ * A maintainer developing the package is *legitimately* ahead of their own
+ * global install — `condense.ts` says so where it explains why the byte-keyed
+ * dedup is inert in that state. A gate here would fail on the normal
+ * development condition, and a gate that fires on sanctioned behaviour gets
+ * ignored, which is the failure `check-rule-invariants` already paid for once.
+ * The point is that the condition becomes VISIBLE, not that it becomes illegal.
+ *
+ * THE THREE CLASSES, AND WHICH ONE A READER MUST ACT ON
+ * ----------------------------------------------------
+ *   body-diff        the two carriers deliver different TEXT. This is the class
+ *                    round 5's contradiction lived in, and the only one that
+ *                    needs a decision. Precedence when it appears: the project
+ *                    projection is generated from `src/` at the current commit,
+ *                    so it is the newer copy and it wins; the global install is
+ *                    a release snapshot. Printed with the report so the
+ *                    precedence is read at the moment it matters rather than
+ *                    looked up.
+ *   provenance-only  identical after removing the two installer ownership keys.
+ *                    Structural, expected, and decided against closing —
+ *                    `agents/settings/contexts/dedup-reachability-refusal.md`.
+ *                    Reported as a count with that pointer, never as a finding,
+ *                    or the real class drowns in it.
+ *   one-carrier-only a rule present at exactly one scope. Not a contradiction:
+ *                    project-only is a rule newer than the installed release,
+ *                    global-only is a rule the release still carries. Named
+ *                    because asymmetric reach is what makes a project-scope
+ *                    measurement non-transferable to another machine.
+ *
+ * NOT IN SCOPE. Skills, commands and contexts have the same two-carrier shape
+ * and are not compared here; this executes the rule-scoped step that was
+ * specified. Nor does it compare `~/.claude/CLAUDE.md` against the project's
+ * `CLAUDE.md` — a different mechanism with a different precedence story.
+ *
+ * Exit: 0 always, except a usage error (1). Deliberate — see above.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { comparePair, type PairVerdict } from './_lib/carrier_divergence.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/**
+ * The project carrier — the tree the host actually reads at project scope, NOT
+ * `dist/agent-src/rules/`.
+ *
+ * The distinction is load-bearing and was found by measuring: the global
+ * installer delivers the five ADR-004 `type: manual` rules while the project
+ * projection deliberately omits them, so anchoring on `dist` (which holds all
+ * 115) reports those five as *shared* when in fact only one carrier delivers
+ * them. Two writers, different filters — exactly the asymmetry this report
+ * exists to name. `dist` is still read, as the reference for what COULD be
+ * projected, which is what makes the manual class attributable rather than a
+ * bare absence.
+ */
+export const PROJECT_RULES = path.join('.claude', 'rules');
+/** What the project projection is generated from — the reference set. */
+export const PROJECTION_SOURCE = path.join('dist', 'agent-src', 'rules');
+/** The machine-global carrier, relative to the user's home. */
+export const GLOBAL_RULES = path.join('.claude', 'rules');
+
+export interface CarrierDivergence {
+    projectDir: string;
+    globalDir: string;
+    /** `false` when the global carrier is absent — every count is then 0. */
+    globalPresent: boolean;
+    /** `false` when the project tree has not been generated in this checkout. */
+    projectPresent: boolean;
+    shared: number;
+    identical: string[];
+    provenanceOnly: string[];
+    bodyDiff: string[];
+    projectOnly: string[];
+    globalOnly: string[];
+    /**
+     * Shared names whose copies could not both be read (a dangling symlink from a
+     * half-finished install). Counted rather than dropped: a pair that silently
+     * leaves `shared` makes every other number in the report unaccounted for.
+     */
+    unreadable: string[];
+    /**
+     * Rules the projection source carries, the global carrier delivers, and the
+     * project projection omits by design (`type: manual`). A subset of
+     * `globalOnly`, separated so the expected half does not read as drift.
+     */
+    manualOnlyGlobal: string[];
+}
+
+function _listRules(dir: string): string[] {
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.md'))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+/** `type:` from a rule's frontmatter, or `''` when unreadable / absent. */
+function _ruleType(file: string): string {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return '';
+    }
+    if (!text.startsWith('---')) return '';
+    const end = text.indexOf('\n---', 3);
+    const fm = end === -1 ? text : text.slice(0, end);
+    const m = /^type:\s*"?([a-z]+)"?/m.exec(fm);
+    return m === null ? '' : (m[1] as string);
+}
+
+/**
+ * Compare the two carriers over the UNION of their rule names.
+ *
+ * The union is the point: anchoring on either side alone hides one direction of
+ * asymmetric reach, and it was the hidden direction — rules the global install
+ * carries and the project does not — that made round 5's cross-project
+ * comparison hard to interpret.
+ *
+ * `sourceDir` is the projection source, read only to attribute a global-only
+ * rule to the ADR-004 manual filter rather than to drift. Absent → the manual
+ * split is simply empty, never a guess.
+ */
+export function compareCarriers(
+    projectDir: string,
+    globalDir: string,
+    sourceDir?: string,
+): CarrierDivergence {
+    const out: CarrierDivergence = {
+        projectDir,
+        globalDir,
+        globalPresent: fs.existsSync(globalDir),
+        projectPresent: fs.existsSync(projectDir),
+        shared: 0,
+        identical: [],
+        provenanceOnly: [],
+        bodyDiff: [],
+        projectOnly: [],
+        globalOnly: [],
+        unreadable: [],
+        manualOnlyGlobal: [],
+    };
+    const project = new Set(_listRules(projectDir));
+    const global = new Set(_listRules(globalDir));
+
+    for (const rule of [...new Set([...project, ...global])].sort()) {
+        const inP = project.has(rule);
+        const inG = global.has(rule);
+        if (inP && !inG) {
+            out.projectOnly.push(rule);
+            continue;
+        }
+        if (!inP && inG) {
+            out.globalOnly.push(rule);
+            if (sourceDir !== undefined && _ruleType(path.join(sourceDir, rule)) === 'manual') {
+                out.manualOnlyGlobal.push(rule);
+            }
+            continue;
+        }
+        out.shared += 1;
+        let verdict: PairVerdict;
+        try {
+            verdict = comparePair(
+                fs.readFileSync(path.join(projectDir, rule)),
+                fs.readFileSync(path.join(globalDir, rule)),
+            );
+        } catch {
+            // An unreadable copy is not a body difference and must not be
+            // reported as one — a permission error would otherwise manufacture
+            // the only class this report asks a reader to act on. It is still
+            // NAMED: a pair that just disappears from `shared` leaves the ledger
+            // short with nothing saying why.
+            out.shared -= 1;
+            out.unreadable.push(rule);
+            continue;
+        }
+        if (verdict === 'identical') out.identical.push(rule);
+        else if (verdict === 'provenance-only') out.provenanceOnly.push(rule);
+        else out.bodyDiff.push(rule);
+    }
+    return out;
+}
+
+export function render(d: CarrierDivergence): string {
+    const lines: string[] = [];
+    lines.push('cross-carrier rule divergence — advisory, gates on nothing');
+    lines.push(`  project carrier: ${d.projectDir}`);
+    lines.push(`  global carrier:  ${d.globalDir}`);
+    lines.push('');
+
+    if (!d.globalPresent) {
+        lines.push('  The global carrier is absent — this machine loads the project projection');
+        lines.push('  only, so there is no second copy to diverge from. Nothing to report, and');
+        lines.push('  that is a real answer rather than a skipped check.');
+        return lines.join('\n');
+    }
+    if (!d.projectPresent) {
+        lines.push('  The project rule tree does not exist in this checkout — it is generated and');
+        lines.push('  gitignored, so a fresh clone has none, and `agents/.agent-tools.yml` may');
+        lines.push('  select zero tools deliberately. Run `task generate-tools` and re-run this');
+        lines.push('  report. Reported rather than silently substituted with the projection');
+        lines.push('  source: dist/ holds rules the project tree omits by design, so reading it');
+        lines.push('  as the project carrier would answer a different question than the one asked.');
+        return lines.join('\n');
+    }
+
+    lines.push(`  shared rule names                    ${d.shared}`);
+    lines.push(`    byte-identical                     ${d.identical.length}`);
+    lines.push(`    differ ONLY in the install stamp   ${d.provenanceOnly.length}`);
+    lines.push(`    differ in BODY                     ${d.bodyDiff.length}`);
+    if (d.unreadable.length > 0) {
+        lines.push(`    unreadable on one side             ${d.unreadable.length}  (${d.unreadable.join(', ')})`);
+        lines.push('      Not counted as shared and NOT a body difference — a dangling entry is');
+        lines.push('      a broken install, not a disagreement about content.');
+    }
+    lines.push(`  present at project scope only        ${d.projectOnly.length}`);
+    lines.push(`  present at global scope only         ${d.globalOnly.length}`);
+    lines.push('');
+
+    if (d.bodyDiff.length > 0) {
+        lines.push('  BODY DIVERGENCE — the two carriers deliver different text for these rules.');
+        lines.push('  Both copies reach the model, with no precedence marker between them, so a');
+        lines.push('  claim one copy retracts can be re-asserted by the other. PRECEDENCE: the');
+        lines.push('  project projection is generated from src/ at this commit and wins; the');
+        lines.push('  global install is a release snapshot. Close it by reinstalling the global');
+        lines.push('  copy, or by reading the project copy as authoritative.');
+        for (const r of d.bodyDiff) lines.push(`    - ${r}`);
+        lines.push('');
+    }
+
+    if (d.provenanceOnly.length > 0) {
+        lines.push(`  ${String(d.provenanceOnly.length)} pair(s) differ only by the installer's package:/source_path: stamp.`);
+        lines.push('  Not a content difference and NOT a defect: install.ts stamps every installed');
+        lines.push('  rule, the in-repo projection stamps nothing. Closing it was decided against');
+        lines.push('  on 2026-07-31 — agents/settings/contexts/dedup-reachability-refusal.md holds');
+        lines.push('  the analysis and the five reopen conditions. Reported as a count on purpose:');
+        lines.push('  naming every expected pair would bury the class above.');
+        lines.push('');
+    }
+
+    if (d.projectOnly.length > 0) {
+        lines.push(`  project-scope only (${String(d.projectOnly.length)}) — newer than the installed release:`);
+        lines.push(`    ${d.projectOnly.join(', ')}`);
+    }
+    const driftGlobalOnly = d.globalOnly.filter((r) => !d.manualOnlyGlobal.includes(r));
+    if (driftGlobalOnly.length > 0) {
+        lines.push(`  global-scope only (${String(driftGlobalOnly.length)}) — the release carries these, this checkout does not project them:`);
+        lines.push(`    ${driftGlobalOnly.join(', ')}`);
+    }
+    if (d.manualOnlyGlobal.length > 0) {
+        lines.push(
+            `  delivered by the global carrier ONLY, by design (${String(d.manualOnlyGlobal.length)}, ADR-004 \`type: manual\`):`,
+        );
+        lines.push(`    ${d.manualOnlyGlobal.join(', ')}`);
+        lines.push('    The project projection filters these out and the global installer does not.');
+        lines.push('    Two writers, different filters — so on a machine with both carriers these');
+        lines.push('    rules reach the model, and on a project-only machine they do not. Expected,');
+        lines.push('    and worth knowing before citing any project-scope reach figure.');
+    }
+    if (d.projectOnly.length > 0 || d.globalOnly.length > 0) {
+        lines.push('');
+        lines.push('  Asymmetric reach is why a project-scope conformance figure does not transfer');
+        lines.push('  to another machine: the rule set the model was told differs by carrier.');
+    }
+
+    if (d.bodyDiff.length === 0) {
+        lines.push('');
+        lines.push('  No body divergence. The condition is transient — it returns whenever the');
+        lines.push('  checkout moves ahead of the installed release — so this is a reading of');
+        lines.push('  right now, not a property of the repo. Re-run it, do not cite it.');
+    }
+    return lines.join('\n');
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let projectDir = path.join(REPO_ROOT, PROJECT_RULES);
+    let globalDir = path.join(os.homedir(), GLOBAL_RULES);
+    let sourceDir = path.join(REPO_ROOT, PROJECTION_SOURCE);
+    // A value must not itself be a flag. `--project --global /x` otherwise
+    // resolves a directory literally named `--global` and silently drops `/x`,
+    // reporting "tree does not exist" instead of a usage error — the flag-VALUE
+    // half of the hole this file's own test closes on the flag-NAME half.
+    const value = (i: number): string | null => {
+        const v = args[i + 1];
+        return v === undefined || v.startsWith('-') ? null : v;
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === '--project' || a === '--global' || a === '--source') {
+            const v = value(i);
+            if (v === null) {
+                process.stderr.write(`report_carrier_divergence: ${a} needs a directory\n`);
+                return 1;
+            }
+            const resolved = path.resolve(v);
+            if (a === '--project') projectDir = resolved;
+            else if (a === '--global') globalDir = resolved;
+            else sourceDir = resolved;
+            i += 1;
+        } else if (a === '--help' || a === '-h') {
+            process.stdout.write(
+                'usage: report_carrier_divergence [--project DIR] [--global DIR] [--source DIR]\n',
+            );
+            return 0;
+        } else if (a !== undefined && a.startsWith('--') && a !== '--quiet') {
+            process.stderr.write(`report_carrier_divergence: unknown flag ${a}\n`);
+            return 1;
+        }
+    }
+    process.stdout.write(`${render(compareCarriers(projectDir, globalDir, sourceDir))}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}