@event4u/agent-config 13.0.0 → 14.1.0

package/src/scripts/sync_pr_branch.ts

@@ -0,0 +1,271 @@
+#!/usr/bin/env tsx
+/**
+ * Bring the branch up to its PR base before a push, so the PR never goes stale.
+ *
+ * `check_branch_freshness` already DETECTS "behind the base" and refuses the
+ * push. What did not exist was the other half: doing something about it. So the
+ * documented sequence — freshness → merge the base in → regenerate → verify →
+ * push (`/create-pr` § 1b-ii) — was entirely model-carried, and a step carried
+ * only by prose is a step that gets skipped under time pressure. Measured on
+ * PR #1391: the base moved three times during one run, the push was rejected
+ * twice for it, and the PR reached `CONFLICTING` before anyone noticed.
+ *
+ * Deliberately NOT wired into the pre-push hook. This MUTATES the working tree —
+ * a merge commit, possibly regenerated files — and a hook that rewrites the tree
+ * mid-push turns one rejected push into an unreviewed commit. Detection belongs
+ * in the hook (and is already there); resolution belongs to a step the agent runs
+ * with the result in front of it.
+ *
+ * A conflict is NOT auto-resolved and never will be by this script. It stops,
+ * names the conflicted paths, and says which of them are generated (regenerate,
+ * do not hand-merge) versus authored (a human decision). Auto-resolving a
+ * content conflict is how a parallel session's work disappears.
+ *
+ * Exit codes: 0 = already current, or merged cleanly · 1 = conflict, or the base
+ * could not be resolved · 2 = internal error. `scanned:` on every path.
+ */
+
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { reportScanned } from './_lib/scan_scope.js';
+
+const NETWORK_TIMEOUT_MS = 8_000;
+
+/** Paths that are GENERATED — a conflict here is regenerated, never hand-merged. */
+const GENERATED = [
+    'agents/roadmaps-progress.md',
+    'agents/index.md',
+    'docs/catalog.md',
+    'dist/agent-src/',
+    '.augment/',
+];
+
+function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {
+    const r = spawnSync(cmd, [...args], {
+        cwd,
+        encoding: 'utf-8',
+        timeout: NETWORK_TIMEOUT_MS,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim() };
+}
+
+/** True when `rel` is a generated artefact rather than an authored one. */
+export function isGenerated(rel: string): boolean {
+    const norm = rel.replace(/\\/g, '/');
+    return GENERATED.some((g) => (g.endsWith('/') ? norm.startsWith(g) : norm === g));
+}
+
+export interface Plan {
+    /** 0 = nothing to do or merged · 1 = needs a human · 2 = internal. */
+    exit: 0 | 1 | 2;
+    message: string;
+    /** Conflicted paths, split so the caller knows which to regenerate. */
+    generated: string[];
+    authored: string[];
+    scanned: number;
+}
+
+/**
+ * Classify a conflicted file list.
+ *
+ * Pure, so the split is testable without producing a real merge conflict — and
+ * the split is the useful part: a generated conflict has one correct resolution
+ * (regenerate) and an authored one has none that a script may choose.
+ */
+export function classifyConflicts(files: readonly string[]): Pick<Plan, 'generated' | 'authored'> {
+    const generated: string[] = [];
+    const authored: string[] = [];
+    for (const f of files) {
+        if (f.trim() === '') continue;
+        (isGenerated(f.trim()) ? generated : authored).push(f.trim());
+    }
+    return { generated, authored };
+}
+
+/** Resolve the base this branch will actually merge into. */
+export function resolveBase(repo: string, override: string | null): { base: string | null; how: string } {
+    if (override !== null && override.trim() !== '') {
+        return { base: override.trim(), how: 'given by --base' };
+    }
+    const branch = sh('git', ['rev-parse', '--abbrev-ref', 'HEAD'], repo).out.trim();
+    if (branch !== '' && branch !== 'HEAD') {
+        // The forge knows the REAL base, which matters for a stacked or
+        // release-line PR: measuring against the repo default would compare
+        // against a branch this PR never merges into.
+        const pr = sh('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'baseRefName', '--limit', '1'], repo);
+        if (pr.ok) {
+            try {
+                const rows = JSON.parse(pr.out || '[]') as Array<{ baseRefName?: string }>;
+                const b = rows[0]?.baseRefName;
+                if (typeof b === 'string' && b !== '') {
+                    return { base: `origin/${b}`, how: `the open PR base (${b})` };
+                }
+            } catch {
+                /* fall through to the default-branch probe */
+            }
+        }
+    }
+    const head = sh('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], repo);
+    if (head.ok && head.out.trim() !== '') {
+        return { base: head.out.trim(), how: 'the repo default branch' };
+    }
+    return { base: null, how: 'unresolvable — no open PR and no origin/HEAD' };
+}
+
+export function sync(repo: string, baseOverride: string | null, dryRun: boolean): Plan {
+    const { base, how } = resolveBase(repo, baseOverride);
+    if (base === null) {
+        return { exit: 1, message: `cannot resolve a base to update against — ${how}.`, generated: [], authored: [], scanned: 0 };
+    }
+
+    const fetched = sh('git', ['fetch', 'origin', '--prune'], repo);
+    if (!fetched.ok) {
+        // Unreachable remote is not "already current" — saying so is the whole
+        // point, since a silent pass here reproduces the staleness this closes.
+        return {
+            exit: 0,
+            message: `unverified — could not fetch origin (${fetched.err.split('\n')[0] ?? '?'}). Base freshness NOT checked.`,
+            generated: [],
+            authored: [],
+            scanned: 0,
+        };
+    }
+
+    const behind = sh('git', ['rev-list', '--count', `HEAD..${base}`], repo).out.trim();
+    if (behind === '' || behind === '0') {
+        return { exit: 0, message: `already current with ${base} (${how}).`, generated: [], authored: [], scanned: 1 };
+    }
+    if (dryRun) {
+        return {
+            exit: 0,
+            message: `${behind} commit(s) behind ${base} (${how}) — would merge it in. Dry run, nothing changed.`,
+            generated: [],
+            authored: [],
+            scanned: 1,
+        };
+    }
+
+    const merge = sh('git', ['merge', base, '--no-edit'], repo);
+    if (merge.ok) {
+        return {
+            exit: 0,
+            message:
+                `merged ${base} in (${how}, was ${behind} behind). REGENERATE derived files now — a clean ` +
+                'auto-merge of a generated file is still wrong.',
+            generated: [],
+            authored: [],
+            scanned: 1,
+        };
+    }
+
+    const conflicted = sh('git', ['diff', '--name-only', '--diff-filter=U'], repo).out.split('\n');
+    const split = classifyConflicts(conflicted);
+    return {
+        exit: 1,
+        message:
+            `merge of ${base} (${how}) hit ${String(split.generated.length + split.authored.length)} conflict(s). ` +
+            'NOT auto-resolved: a content conflict is where a parallel session\'s work disappears.',
+        ...split,
+        scanned: 1,
+    };
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let repo = process.cwd();
+    let base: string | null = null;
+    let dryRun = false;
+    let quiet = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] as string;
+        const val = (): string | null => {
+            const v = args[++i];
+            return v === undefined || v.startsWith('--') ? null : v;
+        };
+        if (a === '--repo') {
+            const v = val();
+            if (v === null) {
+                process.stderr.write('❌  sync_pr_branch: --repo requires a value\n');
+                reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'argument error' });
+                return 1;
+            }
+            repo = v;
+        } else if (a === '--base') {
+            const v = val();
+            if (v === null) {
+                process.stderr.write('❌  sync_pr_branch: --base requires a value\n');
+                reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'argument error' });
+                return 1;
+            }
+            base = v;
+        } else if (a === '--dry-run') {
+            dryRun = true;
+        } else if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                'usage: sync_pr_branch [--repo PATH] [--base REF] [--dry-run] [--quiet]\n' +
+                    '  Merges the PR base into the current branch so the PR does not go stale.\n' +
+                    '  Resolves the base from the open PR when there is one. A conflict is\n' +
+                    '  reported and never auto-resolved; generated and authored conflicts are\n' +
+                    '  listed separately because only the first has one correct resolution.\n',
+            );
+            reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'help output' });
+            return 0;
+        } else {
+            process.stderr.write(`❌  sync_pr_branch: unknown argument \`${a}\`\n`);
+            reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'argument error' });
+            return 1;
+        }
+    }
+
+    let plan: Plan;
+    try {
+        plan = sync(repo, base, dryRun);
+    } catch (exc) {
+        reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'internal error' });
+        process.stderr.write(`❌  sync_pr_branch: internal error: ${exc instanceof Error ? exc.message : String(exc)}\n`);
+        return 2;
+    }
+
+    if (plan.exit === 1) {
+        process.stdout.write(`❌  ${plan.message}\n`);
+        if (plan.generated.length > 0) {
+            process.stdout.write(
+                `\n  GENERATED (${String(plan.generated.length)}) — resolve by REGENERATING, never by mixing hunks:\n`,
+            );
+            for (const f of plan.generated) process.stdout.write(`    · ${f}\n`);
+            process.stdout.write('    → git checkout --ours <file> && task sync && task generate-tools\n');
+        }
+        if (plan.authored.length > 0) {
+            process.stdout.write(`\n  AUTHORED (${String(plan.authored.length)}) — a human decision, read both sides:\n`);
+            for (const f of plan.authored) process.stdout.write(`    · ${f}\n`);
+        }
+    } else if (plan.message.startsWith('unverified')) {
+        // Loud even under --quiet: unverified reported silently is
+        // indistinguishable from verified, which is the defect being closed.
+        process.stdout.write(`⚠️  sync_pr_branch: ${plan.message}\n`);
+    } else if (!quiet || plan.scanned > 0) {
+        process.stdout.write(`✅  ${plan.message}\n`);
+    }
+    reportScanned({
+        gate: 'sync_pr_branch',
+        scanned: plan.scanned,
+        units: 'base ref(s)',
+        roots: ['origin'],
+        ...(plan.scanned === 0 ? { allowEmpty: 'base unresolvable or remote unreachable — stated above' } : {}),
+    });
+    return plan.exit;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href || process.argv[1] === _HERE;
+}
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/test_council_qualification.ts

@@ -0,0 +1,213 @@
+/**
+ * Executable probe for the provider-qualification exit criterion
+ * (road-to-release-review-p0 Phase 3).
+ *
+ * The roadmap states the criterion as behaviour, not as coverage: *"a
+ * deliberately broken seat yields unavailable rather than configured, and a
+ * council run against it reports short instead of printing a quorum."* This
+ * script asserts exactly that, against the real `build_members` path, with a
+ * synthetic roster and an injected environment report — no config file, no
+ * network, no provider call, no spend.
+ *
+ * It exists in addition to the vitest suites rather than instead of them. The
+ * unit tests can be green while the wiring is gone: `build_members` evaluates
+ * qualification only when a `probe_store` is supplied, so a future refactor
+ * that drops the argument at the three production call sites would leave every
+ * test passing and the repair silently inert. This probe re-asserts the
+ * end-to-end shape the roadmap names, and is the `verify:` annotation its
+ * Phase 3 steps point at.
+ *
+ * Exit 0 = the criterion holds. Exit 1 = it does not, with the failing
+ * assertion named. `--quiet` suppresses the per-assertion lines and keeps the
+ * verdict, matching the house convention for a script CI may call.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import type { EnvironmentReport } from './_lib/environment_detector.js';
+import type { ProbeStore } from './ai_council/probe_store.js';
+import type { QuorumResult } from './ai_council/quorum.js';
+import { isCountableForQuorum, qualifyMember, type MemberQualification } from './ai_council/qualification.js';
+import { build_members } from './council_cli.js';
+
+const QUIET = process.argv.includes('--quiet');
+
+const KEY_VAR = 'COUNCIL_QUALIFICATION_PROBE_KEY';
+const TODAY = new Date().toISOString().slice(0, 10);
+
+function _out(line: string): void {
+    if (!QUIET) {
+        process.stdout.write(`${line}\n`);
+    }
+}
+
+const failures: string[] = [];
+
+function check(name: string, condition: boolean, detail: string): void {
+    if (condition) {
+        _out(`  ok    ${name}`);
+        return;
+    }
+    failures.push(`${name} — ${detail}`);
+    _out(`  FAIL  ${name} — ${detail}`);
+}
+
+/** No hosts, no auth records, no keys — every rung is decided by the roster. */
+function emptyReport(): EnvironmentReport {
+    return { hosts: [], auth: [], keys: [] };
+}
+
+function rosterSettings(): Record<string, unknown> {
+    return {
+        ai_council: {
+            enabled: true,
+            mode: 'auto',
+            members: {
+                // Healthy: resolves through the key rung and has been observed.
+                anthropic: { enabled: true, model: 'model-a', api_key_ref: `env:${KEY_VAR}` },
+                // Broken: constructs identically, and its last exchange was
+                // rejected by the transport. This is the recorded codex shape —
+                // a seat that looks configured from every angle a config read
+                // can see.
+                openai: { enabled: true, model: 'model-b', api_key_ref: `env:${KEY_VAR}` },
+            },
+        },
+    };
+}
+
+function storeWith(members: ProbeStore['members']): ProbeStore {
+    return { schema: 1, members };
+}
+
+export function main(): number {
+    _out('council qualification — exit-criterion probe');
+
+    // The roster is only constructible while the key var is set; restore
+    // whatever was there so the probe leaves no environment residue.
+    const prior = process.env[KEY_VAR];
+    process.env[KEY_VAR] = 'sk-probe-key';
+    try {
+        // ── Criterion 1: a deliberately broken seat yields `unavailable`. ──
+        const broken = qualifyMember({
+            name: 'broken',
+            transport: { available: true, transport: 'api', reason: null, absentReason: null },
+            modelId: 'model-b',
+            lastProbe: { at: TODAY, outcome: 'model_unservable' },
+        });
+        check(
+            'a seat whose model the transport rejected reports unavailable',
+            broken.verdict === 'unavailable',
+            `got ${broken.verdict}`,
+        );
+        check(
+            'and it is not countable toward a quorum',
+            !isCountableForQuorum(broken.verdict),
+            'a seat nothing will answer from was counted present',
+        );
+
+        // ── Criterion 1b: "configured" alone never reads as available. ──
+        const neverObserved = qualifyMember({
+            name: 'never-observed',
+            transport: { available: true, transport: 'api', reason: null, absentReason: null },
+            modelId: 'model-a',
+            lastProbe: null,
+        });
+        check(
+            'a configured, plausible, never-observed seat reports unknown',
+            neverObserved.verdict === 'unknown',
+            `got ${neverObserved.verdict} — configuration must never read as demonstrated`,
+        );
+
+        // ── Criterion 2: the run reports SHORT rather than printing a quorum. ──
+        const quorum_out: { result: QuorumResult | null } = { result: null };
+        const qualification_out: MemberQualification[] = [];
+        build_members(rosterSettings(), {
+            environment_report: emptyReport(),
+            quorum_out,
+            qualification_out,
+            probe_store: storeWith({
+                anthropic: { at: TODAY, outcome: 'ok' },
+                openai: { at: TODAY, outcome: 'model_unservable' },
+            }),
+        });
+        const q = quorum_out.result;
+        check('the pre-run quorum was evaluated', q !== null, 'quorum_out.result stayed null');
+        if (q !== null) {
+            check(
+                'the broken seat is withheld from present',
+                q.present === 1,
+                `present=${String(q.present)}, expected 1 of a 2-seat roster`,
+            );
+            // The direction check. Shrinking `n` would lower ceil(n/2) and make
+            // a short pass EASIER to conclude — the same over-claim in the
+            // opposite arithmetic.
+            check(
+                'the roster is NOT shrunk — total stays 2',
+                q.total === 2,
+                `total=${String(q.total)}; dropping the seat from n would lower the threshold`,
+            );
+        }
+        check(
+            'qualification reached the caller',
+            qualification_out.length === 2,
+            `qualification_out has ${String(qualification_out.length)} entries — the wiring is inert`,
+        );
+        const wiredBroken = qualification_out.find((x) => x.name === 'openai');
+        check(
+            'the broken seat is reported unavailable end-to-end',
+            wiredBroken?.verdict === 'unavailable',
+            `got ${String(wiredBroken?.verdict)}`,
+        );
+
+        // ── Criterion 3: the store is consulted, not assumed. ──
+        const ungated: { result: QuorumResult | null } = { result: null };
+        build_members(rosterSettings(), { environment_report: emptyReport(), quorum_out: ungated });
+        check(
+            'omitting the store leaves presence at constructibility only',
+            ungated.result?.present === 2,
+            `present=${String(ungated.result?.present)} — the default must stay deterministic`,
+        );
+    } finally {
+        if (prior === undefined) {
+            delete process.env[KEY_VAR];
+        } else {
+            process.env[KEY_VAR] = prior;
+        }
+    }
+
+    if (failures.length > 0) {
+        process.stdout.write(
+            `council qualification: ❌ ${String(failures.length)} assertion(s) failed\n`,
+        );
+        for (const f of failures) {
+            process.stdout.write(`  - ${f}\n`);
+        }
+        return 1;
+    }
+    process.stdout.write('council qualification: ✅ exit criterion holds\n');
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}