@event4u/agent-config 8.9.0 → 8.11.0

package/src/scripts/trigger_eval_rotation.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env tsx
+/**
+ * trigger_eval_rotation — weekly live trigger-eval pass-rate rotation (ADR-118 §4).
+ *
+ * The ONE measure→adjust loop closure from `road-to-loop-engineering`: the
+ * weekly cross-model canary runs the live trigger eval over a deterministic
+ * rotating subset of the skills that carry `evals/triggers.json`, enforcing
+ * the shared per-domain precision/recall floors
+ * (`_lib/trigger_eval_floors.ts`). A floor breach fails the SCHEDULED job —
+ * the failure is the maintainer notification; PRs are never blocked by live
+ * results.
+ *
+ * Boundaries (deliberate):
+ * - The local interactive `skill_trigger_eval` CLI and its /dev/tty
+ *   confirmation gate are untouched — this script is the CI-only path, and
+ *   its live authorization derives exclusively from the key file the canary
+ *   workflow materializes from repo secrets (same pattern as
+ *   `cross_model_smoke.ts`). No env-var key fallback, no local bypass.
+ * - `--dry-run` (MockRouter, no key, no spend) exercises the plumbing only;
+ *   floors are REPORTED but never fail the run — mock routing says nothing
+ *   about real trigger accuracy.
+ * - Rotation is a pure function of (week index, batch size, sorted suite
+ *   list): ~batch suites per week, wrapping so every suite is visited on a
+ *   fixed cadence regardless of suite-count drift.
+ *
+ * Exit codes: 0 pass (always, in --dry-run) · 1 live floor breach ·
+ * 2 usage / IO error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    DEFAULT_MODEL,
+    MockRouter,
+    Query,
+    compute_metrics,
+    load_skill_metas,
+    write_result,
+    type EvalResult,
+    type SkillMeta,
+    type TriggerRouter,
+} from './skill_trigger_eval.js';
+import { AnthropicFetchRouter, loadKeyFromFile } from './_lib/trigger_routers.js';
+import { floor_for } from './_lib/trigger_eval_floors.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const SKILLS_DIR = path.join(REPO_ROOT, 'src', 'skills');
+const DEFAULT_OUT_DIR = path.join(REPO_ROOT, 'internal', 'evals', 'results', 'rotation');
+const DEFAULT_BATCH = 5;
+
+/** Router that may expose an async route (fetch-based live routers). */
+type AsyncCapableRouter = TriggerRouter & {
+    routeAsync?: (query: string, skills: SkillMeta[]) => Promise<[string[], number, number]>;
+};
+
+/** UTC week index since epoch — monotonic, deterministic rotation key. */
+export function week_index(d: Date): number {
+    const utcDays = Math.floor(
+        Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 86_400_000,
+    );
+    return Math.floor(utcDays / 7);
+}
+
+/**
+ * Deterministic rotation: batch consecutive suites starting at
+ * `(week * batch) mod total`, wrapping. Every suite is visited within
+ * ceil(total / batch) weeks; adding/removing suites shifts but never
+ * starves the cycle.
+ */
+export function pick_rotation<T>(suites: readonly T[], week: number, batch: number): T[] {
+    if (suites.length === 0 || batch <= 0) {
+        return [];
+    }
+    const n = Math.min(batch, suites.length);
+    const total = suites.length;
+    const start = ((((week * batch) % total) + total) % total);
+    const picked: T[] = [];
+    for (let i = 0; i < n; i += 1) {
+        picked.push(suites[(start + i) % total] as T);
+    }
+    return picked;
+}
+
+/** Enumerate skills carrying `evals/triggers.json`, sorted for determinism. */
+export function list_trigger_suites(skillsDir: string = SKILLS_DIR): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(skillsDir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((name) => {
+            try {
+                return fs.statSync(path.join(skillsDir, name, 'evals', 'triggers.json')).isFile();
+            } catch {
+                return false;
+            }
+        })
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * Load a triggers.json in EITHER supported shape (mirrors
+ * `check_trigger_evals.ts`): a `queries` list of {q, trigger:bool}, or split
+ * `should_trigger` / `should_not_trigger` lists whose items are query strings
+ * or {q} objects. `load_triggers` from the pinned CLI only reads the first
+ * shape, so the rotation normalizes here instead of touching the pinned code.
+ */
+export function load_triggers_any(p: string, fallbackSkill: string): [string, Query[]] {
+    const data = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+    const skill = typeof data['skill'] === 'string' && data['skill'] ? (data['skill'] as string) : fallbackSkill;
+    const queries: Query[] = [];
+    if (Array.isArray(data['queries'])) {
+        for (const item of data['queries'] as Array<{ q?: unknown; trigger?: unknown }>) {
+            if (typeof item?.q === 'string' && item.q.trim()) {
+                queries.push(Query(item.q, Boolean(item.trigger)));
+            }
+        }
+    } else {
+        for (const [key, trigger] of [
+            ['should_trigger', true],
+            ['should_not_trigger', false],
+        ] as const) {
+            const items = data[key];
+            if (!Array.isArray(items)) continue;
+            for (const it of items) {
+                const q = typeof it === 'string' ? it : (it as { q?: unknown } | null)?.q;
+                if (typeof q === 'string' && q.trim()) {
+                    queries.push(Query(q, trigger));
+                }
+            }
+        }
+    }
+    if (queries.length === 0) {
+        throw new Error(`${p}: no usable queries in either supported shape`);
+    }
+    return [skill, queries];
+}
+
+/** run_eval, but awaiting routeAsync when the router provides it. */
+export async function run_eval_async(
+    skill_name: string,
+    queries: Query[],
+    router: AsyncCapableRouter,
+    skills: SkillMeta[],
+    model: string,
+): Promise<EvalResult> {
+    const result: EvalResult = {
+        skill: skill_name,
+        model,
+        timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, '+00:00'),
+        router: router.name,
+        queries: [],
+        metrics: compute_metrics([]),
+        input_tokens: 0,
+        output_tokens: 0,
+        cost_usd_estimate: 0.0,
+    };
+    for (const q of queries) {
+        const [loaded, inTok, outTok] =
+            typeof router.routeAsync === 'function'
+                ? await router.routeAsync(q.q, skills)
+                : router.route(q.q, skills);
+        const observed = loaded.includes(skill_name);
+        result.queries.push({
+            q: q.q,
+            expected: q.trigger,
+            observed,
+            loaded_skills: [...loaded].sort(),
+            passed: observed === q.trigger,
+        });
+        result.input_tokens += inTok;
+        result.output_tokens += outTok;
+    }
+    result.metrics = compute_metrics(result.queries);
+    return result;
+}
+
+export interface RotationOptions {
+    week?: number;
+    batch?: number;
+    dryRun?: boolean;
+    outDir?: string;
+    model?: string;
+    /** Injectable router (tests). Default: MockRouter (dry) / AnthropicFetchRouter (live). */
+    router?: AsyncCapableRouter;
+    skillsDir?: string;
+}
+
+export interface RotationSuiteOutcome {
+    skill: string;
+    precision: number;
+    recall: number;
+    minPrecision: number;
+    minRecall: number;
+    passed: boolean;
+    resultPath: string;
+}
+
+export interface RotationSummary {
+    week: number;
+    batch: number;
+    total_suites: number;
+    dry_run: boolean;
+    outcomes: RotationSuiteOutcome[];
+    breaches: number;
+}
+
+export async function run_rotation(opts: RotationOptions = {}): Promise<RotationSummary> {
+    const dryRun = opts.dryRun ?? false;
+    const batch = opts.batch ?? DEFAULT_BATCH;
+    const week = opts.week ?? week_index(new Date());
+    const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
+    const model = opts.model ?? DEFAULT_MODEL;
+    const skillsDir = opts.skillsDir ?? SKILLS_DIR;
+
+    const suites = list_trigger_suites(skillsDir);
+    const picked = pick_rotation(suites, week, batch);
+    const catalogue = load_skill_metas();
+
+    const router: AsyncCapableRouter =
+        opts.router ??
+        (dryRun
+            ? new MockRouter((q, skills) =>
+                  skills.filter((s) => q.toLowerCase().includes(s.name)).map((s) => s.name),
+              )
+            : (new AnthropicFetchRouter({
+                  apiKey: loadKeyFromFile('anthropic.key'),
+              }) as AsyncCapableRouter));
+
+    fs.mkdirSync(outDir, { recursive: true });
+
+    const outcomes: RotationSuiteOutcome[] = [];
+    for (const skill of picked) {
+        const triggersPath = path.join(skillsDir, skill, 'evals', 'triggers.json');
+        const [skillName, queries] = load_triggers_any(triggersPath, skill);
+        const result = await run_eval_async(skillName, queries, router, catalogue, model);
+        const floor = floor_for(skillName);
+        const passed =
+            result.metrics.precision >= floor.minPrecision &&
+            result.metrics.recall >= floor.minRecall;
+        const resultPath = path.join(outDir, `${skillName}.json`);
+        write_result(result, resultPath);
+        outcomes.push({
+            skill: skillName,
+            precision: result.metrics.precision,
+            recall: result.metrics.recall,
+            minPrecision: floor.minPrecision,
+            minRecall: floor.minRecall,
+            passed,
+            resultPath,
+        });
+    }
+
+    return {
+        week,
+        batch,
+        total_suites: suites.length,
+        dry_run: dryRun,
+        outcomes,
+        breaches: outcomes.filter((o) => !o.passed).length,
+    };
+}
+
+function parse_args(argv: string[]): RotationOptions & { help?: boolean } {
+    const out: RotationOptions & { help?: boolean } = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        const take = (): string => {
+            const v = argv[++i];
+            if (v === undefined) {
+                process.stderr.write(`trigger_eval_rotation: error: argument ${a}: expected one argument\n`);
+                process.exit(2);
+            }
+            return v as string;
+        };
+        if (a === '--week') out.week = Number(take());
+        else if (a === '--batch') out.batch = Number(take());
+        else if (a === '--dry-run') out.dryRun = true;
+        else if (a === '--out-dir') out.outDir = path.resolve(take());
+        else if (a === '--model') out.model = take();
+        else if (a === '-h' || a === '--help') out.help = true;
+        else {
+            process.stderr.write(`trigger_eval_rotation: error: unrecognized arguments: ${a}\n`);
+            process.exit(2);
+        }
+    }
+    if (out.week !== undefined && !Number.isInteger(out.week)) {
+        process.stderr.write('trigger_eval_rotation: error: --week must be an integer\n');
+        process.exit(2);
+    }
+    if (out.batch !== undefined && (!Number.isInteger(out.batch) || out.batch <= 0)) {
+        process.stderr.write('trigger_eval_rotation: error: --batch must be a positive integer\n');
+        process.exit(2);
+    }
+    return out;
+}
+
+export async function main(argv?: string[]): Promise<number> {
+    const opts = parse_args(argv ?? process.argv.slice(2));
+    if (opts.help) {
+        process.stdout.write(
+            'usage: trigger_eval_rotation [--week N] [--batch N] [--dry-run]\n' +
+                '                             [--out-dir DIR] [--model MODEL]\n',
+        );
+        return 0;
+    }
+    let summary: RotationSummary;
+    try {
+        summary = await run_rotation(opts);
+    } catch (err) {
+        process.stderr.write(`❌  trigger_eval_rotation: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+    process.stdout.write(
+        `trigger-eval rotation · week=${summary.week} · batch=${summary.batch} · ` +
+            `${summary.outcomes.length}/${summary.total_suites} suites this run` +
+            `${summary.dry_run ? ' · DRY-RUN (floors advisory)' : ''}\n`,
+    );
+    for (const o of summary.outcomes) {
+        const mark = o.passed ? '✅' : '❌';
+        process.stdout.write(
+            `  ${mark} ${o.skill} · precision ${o.precision} (floor ${o.minPrecision}) · ` +
+                `recall ${o.recall} (floor ${o.minRecall}) · ${o.resultPath}\n`,
+        );
+    }
+    if (summary.breaches > 0 && !summary.dry_run) {
+        process.stderr.write(
+            `❌  ${summary.breaches} suite(s) below floor — see result JSONs. ` +
+                'Demotion revisit-if: ADR-118 (advisory if >~10% spurious over 50+ runs).\n',
+        );
+        return 1;
+    }
+    process.stdout.write('✅  rotation complete\n');
+    return 0;
+}
+
+const argvUrl = process.argv[1] === undefined ? '' : pathToFileURL(path.resolve(process.argv[1])).href;
+if (import.meta.url === argvUrl) {
+    main().then((code) => process.exit(code));
+}

package/src/scripts/update_counts.ts

@@ -158,26 +158,14 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
     [
         'README.md',
         [
-            // Browse-content line: `… [all NNN commands](…)`. Raw file
-            // count (the hero `Commands-N` badge carries the *active*
-            // count and is owned by check_command_count_messaging.py).
-            ['(\\[all )(\\d+)( commands\\])', 'commands'],
-            // Hero badges: shields.io URLs `Skills-NNN-<color>` etc.
+            // Counts live only in the hero badges — shields.io URLs
+            // `Skills-NNN-<color>` etc. Prose counts were removed from the
+            // README on purpose (the badges carry the numbers); the Commands
+            // badge is owned by check_command_count_messaging.
             ['(/badge/Skills-)(\\d+)(-)', 'skills'],
             ['(/badge/Rules-)(\\d+)(-)', 'rules'],
             ['(/badge/Guidelines-)(\\d+)(-)', 'guidelines'],
             ['(/badge/Personas-)(\\d+)(-)', 'personas'],
-            // Hero prose sentence: `**N skills, N commands, N governed rules**`
-            // (road-to-truth-and-reference-hygiene Phase 1: prose counts are
-            // generated, never hand-typed).
-            ['(\\*\\*)(\\d+)( skills, )', 'skills'],
-            ['( skills, )(\\d+)( commands, )', 'commands'],
-            ['( commands, )(\\d+)( governed rules\\*\\*)', 'rules'],
-            // Feature-list line: `— N skills + N commands, with a capability router`
-            ['(— )(\\d+)( skills \\+ )', 'skills'],
-            ['( skills \\+ )(\\d+)( commands,)', 'commands'],
-            // Work-journey line: `You don't memorize N commands`
-            ['(memorize )(\\d+)( commands)', 'commands'],
         ],
     ],
     [
@@ -186,7 +174,7 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             // The three count claims — their numbers are generated from the
             // same source the gate checks, closing the ledger's own
             // "count-source binding" debt (B1.2).
-            ['(- claim: )(\\d+)( skills \\(README hero)', 'skills'],
+            ['(- claim: )(\\d+)( skills\\.)', 'skills'],
             ['(- claim: )(\\d+)( commands\\.)', 'commands'],
             ['(- claim: )(\\d+)( governed rules\\.)', 'rules'],
         ],

package/src/scripts/worktree_cleanup_check.ts

@@ -0,0 +1,263 @@
+#!/usr/bin/env tsx
+/**
+ * Deterministic core of the /worktree cleanup + verify gates
+ * (road-to-fable-feedback-5 Phase 5; extracted from the prose in
+ * src/domains/engineering-base/worktree/cleanup/command.md so the refusal
+ * semantics are testable — the command doc calls this instead of ad-hoc
+ * shell).
+ *
+ * Modes:
+ *   check <worktree-path>   Cleanup gates for ONE worktree, in order:
+ *                             1. detached HEAD            → refuse
+ *                             2. dirty (incl. untracked)  → refuse
+ *                             3. commits unique to branch → refuse
+ *                           Refusal is the SUCCESS path of the safety gate;
+ *                           this tool never removes anything.
+ *   scope-overlap           Scan every worktree's .worktree-scope.md and
+ *                           report pairwise `owns:` overlaps (the hazard
+ *                           /worktree status + verify must surface).
+ *
+ * Reachability counts ALL other refs — local branches, remotes, AND tags
+ * (a branch whose only other ref is a tag is still reachable elsewhere).
+ * Exit codes: 0 = allowed / no overlap, 1 = refused / overlap found,
+ * 2 = usage error, 3 = internal error.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export interface CheckResult {
+    allowed: boolean;
+    reasons: string[];
+}
+
+export interface ScopeOverlap {
+    a: { worktree: string; own: string };
+    b: { worktree: string; own: string };
+}
+
+function git(cwd: string, args: string[]): string {
+    return execFileSync('git', ['-C', cwd, ...args], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+
+function tryGit(cwd: string, args: string[]): string | null {
+    try {
+        return git(cwd, args);
+    } catch {
+        return null;
+    }
+}
+
+/** Refs (heads + remotes + tags) EXCLUDING the given branch's own head ref. */
+function otherRefs(cwd: string, branch: string): string[] {
+    const out = git(cwd, ['for-each-ref', '--format=%(refname)']);
+    return out
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && l !== `refs/heads/${branch}`);
+}
+
+export function checkWorktree(worktreePath: string): CheckResult {
+    const reasons: string[] = [];
+    if (!fs.existsSync(worktreePath)) {
+        return { allowed: false, reasons: [`worktree path does not exist: ${worktreePath}`] };
+    }
+
+    const headRef = tryGit(worktreePath, ['symbolic-ref', '-q', 'HEAD']);
+    if (headRef === null) {
+        reasons.push(
+            'detached HEAD — no branch to judge reachability for; resolve the state manually before cleanup',
+        );
+        return { allowed: false, reasons };
+    }
+    const branch = headRef.trim().replace(/^refs\/heads\//, '');
+
+    const status = git(worktreePath, ['status', '--porcelain']);
+    if (status.trim().length > 0) {
+        const files = status
+            .trimEnd()
+            .split('\n')
+            .map((l) => `    ${l}`)
+            .join('\n');
+        reasons.push(`unsaved work (dirty or untracked files count as work):\n${files}`);
+    }
+
+    const others = otherRefs(worktreePath, branch);
+    const revListArgs = ['rev-list', '--oneline', branch, '--not', ...others];
+    const unique = git(worktreePath, revListArgs).trimEnd();
+    if (unique.length > 0) {
+        const commits = unique
+            .split('\n')
+            .map((l) => `    ${l}`)
+            .join('\n');
+        reasons.push(
+            `commits on '${branch}' reachable from NO other ref (branch, remote, or tag):\n${commits}`,
+        );
+    }
+
+    return { allowed: reasons.length === 0, reasons };
+}
+
+interface WorktreeEntry {
+    path: string;
+    branch: string | null;
+}
+
+export function listWorktrees(repoPath: string): WorktreeEntry[] {
+    const out = git(repoPath, ['worktree', 'list', '--porcelain']);
+    const entries: WorktreeEntry[] = [];
+    let current: Partial<WorktreeEntry> = {};
+    for (const line of out.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (current.path !== undefined) {
+                entries.push({ path: current.path, branch: current.branch ?? null });
+            }
+            current = { path: line.slice('worktree '.length) };
+        } else if (line.startsWith('branch ')) {
+            current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        } else if (line === 'detached') {
+            current.branch = null;
+        }
+    }
+    if (current.path !== undefined) {
+        entries.push({ path: current.path, branch: current.branch ?? null });
+    }
+    return entries;
+}
+
+/** Non-glob prefix of an `owns:` entry (`src/middleware/**` → `src/middleware/`). */
+function globPrefix(own: string): string {
+    const starIdx = own.indexOf('*');
+    const prefix = starIdx === -1 ? own : own.slice(0, starIdx);
+    return prefix.replace(/\/+$/, '') + '/';
+}
+
+/** Two owns entries overlap when one's non-glob prefix contains the other's. */
+export function ownsOverlap(a: string, b: string): boolean {
+    const pa = globPrefix(a);
+    const pb = globPrefix(b);
+    return pa.startsWith(pb) || pb.startsWith(pa);
+}
+
+function readOwns(worktreePath: string): string[] {
+    const p = path.join(worktreePath, '.worktree-scope.md');
+    if (!fs.existsSync(p)) return [];
+    const text = fs.readFileSync(p, 'utf-8');
+    // owns: entries are a YAML list under an `owns:` key (see
+    // worktree-lifecycle § Scope lock). Tolerant line parser — the scope
+    // note is hand-written, often inside a fenced block.
+    const owns: string[] = [];
+    let inOwns = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (/^-?\s*owns:\s*$/.test(line)) {
+            inOwns = true;
+            continue;
+        }
+        if (inOwns) {
+            const m = line.match(/^-\s+(.+)$/);
+            if (m) {
+                owns.push(m[1]!.trim());
+            } else if (line.length > 0 && !line.startsWith('#')) {
+                inOwns = false;
+            }
+        }
+    }
+    return owns;
+}
+
+export function findScopeOverlaps(repoPath: string): ScopeOverlap[] {
+    const entries = listWorktrees(repoPath).filter((e) => fs.existsSync(e.path));
+    const scoped = entries
+        .map((e) => ({ worktree: e.path, owns: readOwns(e.path) }))
+        .filter((e) => e.owns.length > 0);
+    const overlaps: ScopeOverlap[] = [];
+    for (let i = 0; i < scoped.length; i++) {
+        for (let j = i + 1; j < scoped.length; j++) {
+            for (const a of scoped[i]!.owns) {
+                for (const b of scoped[j]!.owns) {
+                    if (ownsOverlap(a, b)) {
+                        overlaps.push({
+                            a: { worktree: scoped[i]!.worktree, own: a },
+                            b: { worktree: scoped[j]!.worktree, own: b },
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return overlaps;
+}
+
+function usage(): never {
+    process.stderr.write(
+        'usage: worktree_cleanup_check check <worktree-path> | scope-overlap [repo-path]\n',
+    );
+    process.exit(2);
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const mode = argv[0];
+    if (mode === 'check') {
+        const p = argv[1];
+        if (p === undefined) usage();
+        const r = checkWorktree(path.resolve(p));
+        if (r.allowed) {
+            process.stdout.write(`✅  cleanup allowed: ${p}\n`);
+            return 0;
+        }
+        process.stdout.write(`⛔  cleanup refused: ${p}\n`);
+        for (const reason of r.reasons) {
+            process.stdout.write(`  - ${reason}\n`);
+        }
+        process.stdout.write(
+            '\nRefusal is the safety gate working — commit/stash the work or merge/preserve ' +
+                'the unique commits, then re-run. Never bypass with --force or branch -D.\n',
+        );
+        return 1;
+    }
+    if (mode === 'scope-overlap') {
+        const repo = path.resolve(argv[1] ?? '.');
+        const overlaps = findScopeOverlaps(repo);
+        if (overlaps.length === 0) {
+            process.stdout.write('✅  no scope-lock overlaps across live worktrees.\n');
+            return 0;
+        }
+        process.stdout.write(`⚠️  ${overlaps.length} scope-lock overlap(s):\n`);
+        for (const o of overlaps) {
+            process.stdout.write(
+                `  - ${o.a.worktree} owns '${o.a.own}'  ×  ${o.b.worktree} owns '${o.b.own}'\n`,
+            );
+        }
+        return 1;
+    }
+    usage();
+}
+
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    try {
+        process.exit(main());
+    } catch (e) {
+        process.stderr.write(`Internal error: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(3);
+    }
+}

package/src/server/schemas/settings.ts

@@ -208,6 +208,11 @@ export const settingsSchema = z.object({
             'Whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak + thin-projector trimming), consumed by the token-budget-discipline rule. on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask once per session before loading.',
         ),
     }).default({ rich_skills: 'on' }),
+    code_style: z.object({
+        docblocks: z.enum(['minimal', 'full']).default('minimal').describe(
+            'Consumed by the code-comment-discipline rule. minimal (default) = no signature-mirroring docblocks; docblocks only for machine-relevant precision (generics, array shapes) or genuine why-context. full = the exported public surface of a library package may carry one-line summary docblocks; the redundancy ban still holds.',
+        ),
+    }).default({ docblocks: 'minimal' }),
     reasoning: z.object({
         enabled: z.boolean().default(true).describe(
             'Master switch for the Reasoning Discipline Protocol (RDP). false = the whole layer is inert (zero overhead).',
@@ -331,10 +336,10 @@ export const settingsSchema = z.object({
     }),
     knowledge: z.object({
         global_sharing: z.object({
-            enabled: z.boolean().default(false).describe(
-                'Master switch for the file-first global knowledge-card store (ADR-100, default-off per ADR-101 / Evidence v2 Phase 0 until cross-project reuse is measured). User-global setting — keep in ~/.event4u/agent-config/agent-settings.yml. false fully no-ops the layer; project-local cards (v1) are unaffected.',
+            enabled: z.boolean().default(true).describe(
+                'Master switch for the file-first global knowledge-card store (ADR-100; default-ON per ADR-119, the validated bounded-downside flip superseding ADR-103 — write-time redaction incl. hidden-unicode hardening, narrowest tier default, pre-registered demotion trigger). User-global setting — keep in ~/.event4u/agent-config/agent-settings.yml. false fully no-ops the layer (single-key revert); project-local cards (v1) are unaffected.',
             ),
-            allowed_tiers: z.array(z.string()).default(['public', 'vendor']).describe(
+            allowed_tiers: z.array(z.string()).default(['public']).describe(
                 'Origin tiers auto-eligible to cross a project boundary. proprietary is manual-only regardless (the gate hard-codes it), so an in-house schema never auto-shares.',
             ),
             redaction: z.object({