@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/release.ts

@@ -700,13 +700,84 @@ export function _failed_checks_report(names: readonly string[]): string {
     return lines.join('\n');
 }
 
+/** Rounds of re-watching before an absent required check is called absent. */
+const _NO_CHECKS_ROUNDS = 10;
+/** Delay between those rounds — 10 × 60 s ≈ 10 minutes of tolerance. */
+const _NO_CHECKS_DELAY_MS = 60_000;
+
 /**
- * Watch PR checks and tolerate the 'no checks' case.
+ * Required status-check contexts for a branch, parsed from
+ * `gh api repos/{owner}/{repo}/rules/branches/{branch}`.
+ *
+ * That endpoint is the one that answers the question here: this repo protects
+ * `main` with a RULESET, and the classic `/branches/main/protection` API
+ * answers "Branch not protected" for it — so a check built on the classic
+ * endpoint would conclude "no required checks" and wave everything through.
+ *
+ * Any parse or shape surprise yields [] — the caller then behaves exactly as
+ * it did before this function existed.
+ */
+export function _required_contexts_from_rules(json: string): string[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(json);
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed)) return [];
+    const out: string[] = [];
+    for (const rule of parsed) {
+        const r = rule as { type?: unknown; parameters?: { required_status_checks?: unknown } };
+        if (r.type !== 'required_status_checks') continue;
+        const checks = r.parameters?.required_status_checks;
+        if (!Array.isArray(checks)) continue;
+        for (const c of checks) {
+            const ctx = (c as { context?: unknown }).context;
+            if (typeof ctx === 'string' && ctx !== '') out.push(ctx);
+        }
+    }
+    return out;
+}
+
+export type NoChecksAction = 'retry' | 'accept' | 'die';
+
+/**
+ * What to do when `gh pr checks` reports no checks at all.
+ *
+ * The old code had one answer — accept — for two situations it could not tell
+ * apart: a repo that configures no required checks (nothing will ever arrive,
+ * accepting is correct) and a repo whose checks have simply not been
+ * dispatched yet (accepting merges, tags and publishes unvalidated).
+ *
+ * The branch's own protection rules separate them. Required contexts declared
+ * ⇒ something IS expected, so absence means not-yet, and the answer is to wait
+ * and finally to refuse. None declared ⇒ the pre-existing tolerance stands.
+ */
+export function _no_checks_action(
+    required: readonly string[],
+    round: number,
+    maxRounds: number = _NO_CHECKS_ROUNDS,
+): NoChecksAction {
+    if (required.length === 0) return 'accept';
+    return round < maxRounds ? 'retry' : 'die';
+}
+
+/**
+ * Watch PR checks and tolerate the 'no checks' case ONLY where it is tolerable.
  *
  * `gh pr checks --watch` exits 1 both on real failures and when no checks are
- * reported at all (no workflow triggered, no required checks configured in
- * branch protection). The latter must not block the release — we warn and
- * continue. Real failures still die.
+ * reported at all. Real failures still die.
+ *
+ * Measured 2026-08-06/07: during a critical GitHub Actions incident
+ * (15:22–02:04 UTC, webhook triggers throttled from 20:34) `pull_request`
+ * events were delivered 15–30 minutes late. The five-second grace period below
+ * expires long before that, so the old unconditional accept would have tagged
+ * `main` and published to npm without a single check having run. It did not
+ * only because `main` happened to be independently green.
+ *
+ * So the tolerance is now conditional on the branch declaring no required
+ * checks. Where it declares some, absence is treated as latency: re-watch, and
+ * refuse rather than release blind.
  *
  * A short grace period gives GitHub time to register workflow runs on a
  * freshly-pushed branch.
@@ -721,41 +792,76 @@ function watch_pr_checks(branch: string): void {
             // busy-wait stand-in for time.sleep(5) without an event-loop yield.
         }
     }
-    // The branch is passed explicitly — `gh` inferring the PR from HEAD
-    // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
-    // whole release died on "no pull requests found for branch main".
-    const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
-        check: false,
-        capture: true,
-    });
-    const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
-    const returncode = proc.returncode;
-    if (returncode === 0) {
+    // Rounds exist only for the no-checks-yet case below; every other outcome
+    // returns or dies on the first pass, exactly as before.
+    for (let round = 0; ; round++) {
+        // The branch is passed explicitly — `gh` inferring the PR from HEAD
+        // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
+        // whole release died on "no pull requests found for branch main".
+        const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
+            check: false,
+            capture: true,
+        });
+        const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
+        const returncode = proc.returncode;
+        if (returncode === 0) {
+            if (output) {
+                process.stdout.write(output + '\n');
+            }
+            return;
+        }
+        if (output.toLowerCase().includes('no checks reported')) {
+            const rules = run(
+                ['gh', 'api', `repos/{owner}/{repo}/rules/branches/${MAIN_BRANCH}`],
+                { check: false, capture: true },
+            );
+            const required = _required_contexts_from_rules(rules.stdout ?? '');
+            const action = _no_checks_action(required, round, _NO_CHECKS_ROUNDS);
+
+            if (action === 'accept') {
+                process.stdout.write(`⚠️  ${output}\n`);
+                process.stdout.write(
+                    '   Continuing without check validation — configure required ' +
+                        'checks in branch protection to enforce this gate.\n',
+                );
+                return;
+            }
+            if (action === 'retry') {
+                process.stdout.write(
+                    `⏳  no checks reported yet, but ${MAIN_BRANCH} requires ` +
+                        `${String(required.length)} (${required.join(', ')}) — ` +
+                        `waiting (${String(round + 1)}/${String(_NO_CHECKS_ROUNDS)})\n`,
+                );
+                if (_exec_override === null) {
+                    const until = Date.now() + _NO_CHECKS_DELAY_MS;
+                    while (Date.now() < until) {
+                        // blocking wait, same shape as the grace period above
+                    }
+                }
+                continue;
+            }
+            die(
+                `no checks reported for ${branch} after ` +
+                    `${String(_NO_CHECKS_ROUNDS)} rounds, but ${MAIN_BRANCH} requires ` +
+                    `${required.join(', ')}. Refusing to merge, tag and publish ` +
+                    'unvalidated — GitHub may be delaying event delivery (check ' +
+                    'githubstatus.com). Re-run with `task release -- --resume --yes` ' +
+                    'once the checks appear.',
+            );
+        }
         if (output) {
-            process.stdout.write(output + '\n');
+            process.stderr.write(output + '\n');
         }
-        return;
-    }
-    if (output.toLowerCase().includes('no checks reported')) {
-        process.stdout.write(`⚠️  ${output}\n`);
-        process.stdout.write(
-            '   Continuing without check validation — configure required ' +
-                'checks in branch protection to enforce this gate.\n',
-        );
-        return;
-    }
-    if (output) {
-        process.stderr.write(output + '\n');
-    }
-    const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
-        check: false,
-        capture: true,
-    });
-    const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
-    if (report) {
-        process.stderr.write(report + '\n');
+        const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
+            check: false,
+            capture: true,
+        });
+        const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
+        if (report) {
+            process.stderr.write(report + '\n');
+        }
+        die(`PR checks failed (exit ${returncode})`);
     }
-    die(`PR checks failed (exit ${returncode})`);
 }
 
 /**

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());
+}