@event4u/agent-config 9.28.0 → 9.29.0

package/src/scripts/lint_never_silent.ts

@@ -0,0 +1,276 @@
+#!/usr/bin/env tsx
+/**
+ * lint_never_silent — no shipped guidance may direct a silent re-run or the
+ * concealment of a detected miss.
+ *
+ * The hidden `attempt → critic → re-attempt` mechanism — silently re-running a
+ * turn so the user never notices the miss — was built, benchmarked and
+ * falsified (capability Δ = 0; council verdict TERMINAL, recorded in
+ * `src/skills/recursive-verification/SKILL.md`). The self-repair loop pins
+ * "correction is always visible" as a non-goal boundary. This gate keeps that
+ * boundary mechanical: a rule, skill, or command that *directs* an agent to
+ * silently re-run, or to hide a detected failure, is a CI failure — while
+ * prose that *describes* or *forbids* the falsified mechanism stays legal,
+ * because describing the failure mode is how the corpus teaches against it.
+ *
+ * The describe-vs-direct split is decided per matching line:
+ *   - a line carrying a negation / prohibition / falsification marker
+ *     ("never", "forbidden", "must not", "falsified", "violation", …) is a
+ *     DESCRIPTION and passes;
+ *   - a line carrying an explicit `<!-- never-silent-allow: <reason> -->`
+ *     marker (same line or the line above) passes;
+ *   - anything else that matches is a DIRECTIVE and fails.
+ *
+ * Exit codes: 0 = clean, 1 = violations, 2 = usage.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REAL_REPO_ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
+
+/** The shipped-guidance surfaces the ban covers, relative to the repo root. */
+export const SCAN_ROOTS = ['src/rules', 'src/skills', 'src/agent-src/commands'] as const;
+
+export const ALLOW_MARKER = 'never-silent-allow:';
+
+/**
+ * The two directive families the falsified mechanism decomposes into:
+ * re-running without telling, and concealing what was detected.
+ */
+const SILENT_RERUN_RES: readonly RegExp[] = [
+    /\bsilent(?:ly)?\s+(?:re-?run|re-?runs|re-?attempt|retry|retries|re-?execute)\b/i,
+    /\b(?:re-?run|re-?attempt|retry|re-?execute)\b[^.\n]{0,40}\bsilently\b/i,
+];
+const CONCEAL_RES: readonly RegExp[] = [
+    /\b(?:hide|conceal|paper over|cover up|suppress)\b[^.\n]{0,50}\b(?:miss(?:es)?|failure|mistake|error|defect|violation)\b/i,
+];
+
+/**
+ * A matching line that also carries one of these is prose ABOUT the mechanism —
+ * a prohibition, a description of the falsified variant, or a named failure
+ * mode — never a directive to perform it. Checked on the matching line AND the
+ * line above it: markdown wraps sentences, so the negation of a bullet like
+ * "Do NOT promise zero flake; … disguises silent retries" can sit one physical
+ * line before the phrase that matches.
+ */
+const DESCRIPTION_MARKERS =
+    /\b(?:never|niemals|no\b|kein\w*|forbidden|must not|do(?:es)? not|don'?t|won'?t|cannot|can not|falsified|benchmarked|anti-?pattern|violation|banned|prohibited|refus\w*|stays out|is the failure|non-goal|disguis\w*|mask\w*|not\b)/i;
+
+export interface Violation {
+    readonly file: string;
+    readonly line: number;
+    readonly text: string;
+    readonly family: 'silent-rerun' | 'conceal-miss';
+}
+
+function matchFamily(line: string): Violation['family'] | null {
+    if (SILENT_RERUN_RES.some((re) => re.test(line))) {
+        return 'silent-rerun';
+    }
+    if (CONCEAL_RES.some((re) => re.test(line))) {
+        return 'conceal-miss';
+    }
+    return null;
+}
+
+/** Pure per-file check — exported so the corpus behaviour is unit-testable. */
+export function checkText(file: string, text: string): Violation[] {
+    const out: Violation[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!;
+        const family = matchFamily(line);
+        if (family === null) {
+            continue;
+        }
+        const prev = i > 0 ? lines[i - 1]! : '';
+        if (DESCRIPTION_MARKERS.test(line) || DESCRIPTION_MARKERS.test(prev)) {
+            continue;
+        }
+        if (line.includes(ALLOW_MARKER) || prev.includes(ALLOW_MARKER)) {
+            continue;
+        }
+        out.push({ file, line: i + 1, text: line.trim(), family });
+    }
+    return out;
+}
+
+function collectMarkdown(root: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+            } else if (e.isFile() && e.name.endsWith('.md')) {
+                out.push(p);
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+
+function parseArgs(argv: readonly string[]): { quiet: boolean } {
+    let quiet = false;
+    for (const a of argv) {
+        if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_never_silent [--quiet]\n');
+            process.exit(0);
+        } else {
+            process.stderr.write(`lint_never_silent: unrecognized argument: ${a}\n`);
+            process.exit(2);
+        }
+    }
+    return { quiet };
+}
+
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lns-'));
+    const mk = (body: string): string => {
+        const root = fs.mkdtempSync(path.join(tmp, 'repo-'));
+        const p = path.join(root, 'src', 'rules', 'r.md');
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, `# R\n\n${body}\n`, 'utf-8');
+        return root;
+    };
+    const run = (root: string): number => {
+        process.env['LINT_NEVER_SILENT_ROOT'] = root;
+        try {
+            return runGateCli(REAL_REPO_ROOT, 'src/scripts/lint_never_silent.ts', ['--quiet'], root);
+        } finally {
+            delete process.env['LINT_NEVER_SILENT_ROOT'];
+        }
+    };
+    try {
+        return runSelfTest({
+            gate: 'lint_never_silent',
+            minCases: 3,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'a directive to silently re-run the turn is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(mk('On a detected miss, silently re-run the turn and present the corrected answer.')),
+                },
+                {
+                    name: 'a directive to conceal a detected failure is rejected',
+                    expect: 'reject',
+                    run: () => run(mk('If the gate fails, suppress the error and continue as if it passed.')),
+                },
+                {
+                    name: 'a no-prefixed word (Note:, now) does not exonerate a directive — R2 finding #1',
+                    expect: 'reject',
+                    run: () => run(mk('Note: silently re-run the suite after fixing.')),
+                },
+                {
+                    name: 'prose that FORBIDS the mechanism passes — describing is how the corpus teaches',
+                    expect: 'accept',
+                    run: () =>
+                        run(mk('NEVER silently re-run the turn — that mechanism was built and falsified.')),
+                },
+                {
+                    name: 'an explicit allow-marker passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(mk('<!-- never-silent-allow: negative example in documentation -->\nsilently re-run the turn')),
+                },
+                {
+                    name: 'a clean rule passes',
+                    expect: 'accept',
+                    run: () => run(mk('Verify with the real tool and surface the result to the user.')),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv?: readonly string[]): number {
+    const raw = argv ?? process.argv.slice(2);
+    if (raw.includes('--self-test')) {
+        return selfTest();
+    }
+    const args = parseArgs(raw);
+    const root = process.env['LINT_NEVER_SILENT_ROOT'] ?? REAL_REPO_ROOT;
+
+    const ledger = new GateLedger('lint_never_silent');
+    const violations: Violation[] = [];
+    let scanned = 0;
+    for (const rel of SCAN_ROOTS) {
+        for (const file of collectMarkdown(path.join(root, rel))) {
+            ledger.plan(file);
+            const found = checkText(path.relative(root, file), fs.readFileSync(file, 'utf-8'));
+            scanned += 1;
+            if (found.length > 0) {
+                violations.push(...found);
+                ledger.fail(file, `${String(found.length)} never-silent directive(s)`);
+            } else {
+                ledger.complete(file);
+            }
+        }
+    }
+
+    if (violations.length > 0) {
+        process.stderr.write(`❌  lint_never_silent: ${String(violations.length)} violation(s):\n`);
+        for (const v of violations) {
+            process.stderr.write(
+                `  • ${v.file}:${String(v.line)} [${v.family}] ${v.text}\n` +
+                    '    Shipped guidance must not direct a silent re-run or the concealment of a\n' +
+                    '    detected miss (the mechanism is falsified — correction is always visible).\n' +
+                    `    Describing/forbidding it is fine; mark a deliberate negative example with\n` +
+                    `    <!-- ${ALLOW_MARKER} <reason> --> on or above the line.\n`,
+            );
+        }
+    } else if (!args.quiet) {
+        process.stdout.write(`✅  never-silent clean — ${String(scanned)} shipped artefact(s).\n`);
+    }
+
+    ledger.report();
+    reportScanned({
+        gate: 'lint_never_silent',
+        scanned,
+        units: 'markdown artefact(s)',
+        roots: [...SCAN_ROOTS],
+    });
+    return violations.length > 0 ? 1 : 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+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(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/lint_no_activation_gates.ts

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * `no-activation-gates` — CI backstop for the always-on-orchestration
+ * doctrine (road-to-always-on-orchestration Phase 1).
+ *
+ * The doctrine deletes every per-layer on/off setting for subagents,
+ * council, and team: `subagents.enabled`, `subagents.auto`,
+ * `subagents.host_capabilities`, and (Step 1.3) `ai_team.enabled` are gone
+ * from the shipped template, and there is exactly ONE surviving switch —
+ * `emergency.orchestration_halt`, the audited incident-only kill switch (see
+ * `docs/contracts/settings-classes.md` § "The one exception").
+ *
+ * This gate fails the build if the template ever reintroduces a settings
+ * boolean whose only semantics is "is this orchestration layer on": any leaf
+ * matching `(subagents|ai_team|council)\.(enabled|auto)$`, except the one
+ * allowlisted exception.
+ *
+ * `ai_team.enabled` WAS allowlisted here in an earlier phase (a distinct,
+ * still-opt-in feature) and has since joined the deletion in Step 1.3:
+ * `/team`'s availability is now resolved from a codex-CLI/auth probe
+ * (`src/scripts/ai_team/availability.ts`), matching the doctrine already
+ * applied to `subagents.*`. The allowlist below now carries only the one
+ * emergency switch; the pattern stays live so a reintroduced
+ * `ai_team.enabled`, a future `ai_team.auto`-shaped key, or any
+ * `subagents.*` / `council.*` activation flag still fails the build.
+ *
+ * CLI contract: exit 0 = clean, 1 = a forbidden key exists (or the scan root
+ * is dead). `--quiet` suppresses the per-key listing on the clean path.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { load as parseYaml } from 'js-yaml';
+
+import { settingsLeafPaths } from '../shared/settingsClasses.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'lint_no_activation_gates';
+
+const QUIET = process.argv.slice(2).includes('--quiet');
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const TEMPLATE_RELATIVE = 'src/config/agent-settings.template.yml';
+
+/**
+ * The one settings boolean the always-on doctrine keeps — never activation.
+ *
+ * `emergency.orchestration_halt` is listed here as DOCUMENTATION OF INTENT,
+ * not as a live exemption: `ACTIVATION_GATE_RE` below is scoped to
+ * `(subagents|ai_team|council).(enabled|auto)`, so this key — wrong prefix
+ * (`emergency`, not one of those three) AND wrong suffix
+ * (`orchestration_halt`, not `enabled`/`auto`) — never matches it and is
+ * filtered out at the `not_applicable_kind` branch in the scan loop below,
+ * before the `ALLOWLIST.has(...)` check is ever reached for it (independent
+ * review, road-to-always-on-orchestration). Removing this line would change
+ * nothing observable; it stays so a reader asking "where is the one
+ * surviving switch accounted for in this gate" finds an answer, honestly
+ * labelled as inert rather than implied to be doing enforcement work.
+ */
+const ALLOWLIST: ReadonlySet<string> = new Set([
+    'emergency.orchestration_halt',
+    // `ai_team.enabled` was allowlisted here in an earlier phase (it gated
+    // a DIFFERENT, then still-opt-in feature — the cross-model `/team`
+    // review family — and its replacement was deferred pending a decision
+    // on whether to conflate it with Claude Code's experimental native
+    // Agent Teams flag). Step 1.3 resolved that: `/team`'s availability is
+    // now a codex-CLI/auth probe (`src/scripts/ai_team/availability.ts`),
+    // NOT the native Agent Teams flag and NOT a settings flag at all — so
+    // the key is deleted, not allowlisted. Do not re-add it here.
+]);
+
+/** `(subagents|ai_team|council).(enabled|auto)` — the activation-gate shape. */
+const ACTIVATION_GATE_RE = /^(subagents|ai_team|council)\.(enabled|auto)$/;
+
+type Yaml = string | number | boolean | null | Yaml[] | { [k: string]: Yaml };
+
+function _rootOverride(argv: readonly string[]): string | null {
+    const i = argv.indexOf('--root');
+    const value = i === -1 ? undefined : argv[i + 1];
+    return value === undefined ? null : path.resolve(value);
+}
+
+function _readFile(p: string): string | null {
+    try {
+        return fs.readFileSync(p, 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Prove, against the real CLI, that this gate still rejects what it must.
+ *
+ * The accept case is a two-key clean template; each reject case adds exactly
+ * one forbidden key, so a pass proves the specific detection and not merely
+ * that the fixture is broken.
+ */
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lnag-selftest-'));
+    const seed = (name: string, template: string): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, 'src', 'config'), { recursive: true });
+        fs.writeFileSync(path.join(root, TEMPLATE_RELATIVE), template, 'utf-8');
+        return root;
+    };
+    const run = (cwd: string): number =>
+        runGateCli(REPO_ROOT, `src/scripts/${GATE}.ts`, ['--quiet', '--root', cwd], REPO_ROOT);
+
+    const clean = 'subagents:\n  downshift: true\nemergency:\n  orchestration_halt: false\n';
+
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 6,
+            minRejectCases: 4,
+            cases: [
+                {
+                    // "allowlisted" here would overstate it — the emergency
+                    // switch passes because its shape falls outside
+                    // `ACTIVATION_GATE_RE` entirely (`not_applicable_kind`),
+                    // never because `ALLOWLIST.has(...)` fires for it. See
+                    // the `ALLOWLIST` comment above for why the entry is
+                    // documentation of intent rather than a live exemption.
+                    name: 'a clean template with only the (structurally out-of-scope) emergency switch passes',
+                    expect: 'accept',
+                    run: () => run(seed('clean', clean)),
+                },
+                {
+                    name: 'a leftover ai_team.enabled key is rejected — the allowlist no longer covers it (Step 1.3)',
+                    expect: 'reject',
+                    run: () => run(seed('ai-team-enabled', `${clean}ai_team:\n  enabled: false\n`)),
+                },
+                {
+                    name: 'subagents.enabled is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('subagents-enabled', `${clean}subagents:\n  enabled: true\n`)),
+                },
+                {
+                    name: 'subagents.auto is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('subagents-auto', `${clean}subagents:\n  auto: "on"\n`)),
+                },
+                {
+                    name: 'council.enabled is rejected (future-key protection)',
+                    expect: 'reject',
+                    run: () => run(seed('council-enabled', `${clean}council:\n  enabled: true\n`)),
+                },
+                {
+                    name: 'a NEW ai_team.auto key is rejected — no ai_team.* key is allowlisted anymore',
+                    expect: 'reject',
+                    run: () => run(seed('ai-team-auto', `${clean}ai_team:\n  auto: "on"\n`)),
+                },
+                {
+                    name: 'a missing template — a dead scan root — is rejected, not passed as "nothing to check"',
+                    expect: 'reject',
+                    run: () => run(path.join(tmp, 'dead-root-does-not-exist')),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function main(): number {
+    if (process.argv.slice(2).includes('--self-test')) {
+        return selfTest();
+    }
+    const root = _rootOverride(process.argv.slice(2)) ?? REPO_ROOT;
+    const templatePath = path.join(root, TEMPLATE_RELATIVE);
+
+    const templateText = _readFile(templatePath);
+    if (templateText === null) {
+        process.stderr.write(`❌  ${GATE}: settings template not found at ${TEMPLATE_RELATIVE} — the scan root is dead.\n`);
+        return 1;
+    }
+
+    let parsed: Yaml;
+    try {
+        parsed = parseYaml(templateText) as Yaml;
+    } catch (e) {
+        process.stderr.write(`❌  ${GATE}: ${TEMPLATE_RELATIVE} did not parse: ${String(e)}\n`);
+        return 1;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        process.stderr.write(`❌  ${GATE}: ${TEMPLATE_RELATIVE} did not parse to a map.\n`);
+        return 1;
+    }
+
+    const leaves = settingsLeafPaths(parsed);
+    try {
+        reportScanned({ gate: GATE, scanned: leaves.length, units: 'settings leaf key(s)', roots: [TEMPLATE_RELATIVE] });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
+    const ledger = new GateLedger(GATE);
+    ledger.plan(leaves);
+
+    const findings: string[] = [];
+    for (const leaf of leaves) {
+        if (!ACTIVATION_GATE_RE.test(leaf)) {
+            ledger.outOfScope(leaf, 'not_applicable_kind');
+            continue;
+        }
+        if (ALLOWLIST.has(leaf)) {
+            ledger.outOfScope(leaf, 'declared_exemption');
+            continue;
+        }
+        const finding =
+            `${TEMPLATE_RELATIVE}  \`${leaf}\` is an activation-gate-shaped setting — the ` +
+            'always-on-orchestration doctrine forbids a per-layer on/off switch. Delete it ' +
+            'and resolve the layer from a host-capability probe/registry, or add it to the ' +
+            `${GATE} allowlist with a stated reason if it is genuinely not one.`;
+        findings.push(finding);
+        ledger.fail(leaf, finding);
+    }
+
+    // Unconditional, per `GateLedger.report`'s own contract — `--quiet` mutes
+    // the verbose per-key lines this gate prints below, never the ledger's own
+    // scanned/planned/skipped summary.
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  ${f}\n`);
+        }
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(`✅  ${GATE}: no activation-gate-shaped settings key found.\n`);
+    }
+    return 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    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.exit(main());
+}
+
+export { GATE, REPO_ROOT, TEMPLATE_RELATIVE, main };

package/src/scripts/orchestration_record.ts

@@ -16,6 +16,8 @@
  *     [--route-taken primitive|subagent] [--budget-hit true|false] [--correctness-match true|false] \
  *     [--cache-hit true|false] [--origin lean-init-2026] \
  *     [--rules-carried 32] [--rules-used 5] \
+ *     [--capsule-emitted true|false] [--capsule-entries 9] \
+ *     [--watermark-step 8] [--saturation-step 4] [--trigger-arm-earlier watermark|saturation|tie] \
  *     [--dir <audit-dir>] [--dry-run]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -39,6 +41,7 @@ import {
     type LineOutcome,
     type RecordInput,
     type RouteTaken,
+    type TriggerArm,
 } from './_lib/orchestration_record.js';
 
 // Exported so other writers of the same audit-log-v1 orchestration line
@@ -141,6 +144,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         origin: str(flags, 'origin'),
         rules_carried: int(flags, 'rules-carried'),
         rules_used: int(flags, 'rules-used'),
+        capsule_emitted: bool(flags, 'capsule-emitted'),
+        capsule_entries: int(flags, 'capsule-entries'),
+        watermark_step: int(flags, 'watermark-step'),
+        saturation_step: int(flags, 'saturation-step'),
+        trigger_arm_earlier: str(flags, 'trigger-arm-earlier') as TriggerArm | undefined,
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,