@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/council_cli.ts

@@ -63,6 +63,8 @@ import { format_install_hints } from './ai_council/cli_hints.js';
 import {
     type AdvisorConfig,
     type CouncilConfig,
+    COUNCIL_CONFIG_ENV,
+    COUNCIL_CONFIG_USER_GLOBAL_REL,
     CouncilConfigError,
     load_council_config,
     resolve_api_key,
@@ -558,9 +560,22 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
 
     const ai = _isDict(settings) ? ((settings['ai_council'] as Dict) || {}) : {};
     if (!_pyBool(ai['enabled'])) {
+        // The file this message names is load-bearing, and it named the wrong one
+        // for months. Measured across 10 sessions in one consumer project: the
+        // agent reasoned from `.agent-settings.yml` six times, concluded no
+        // council existed, and substituted a weaker path — and one session
+        // "fixed" it by COPYING the user-global config into the project tree,
+        // because this message told it that was where the switch lived. An error
+        // from the authoritative tool is the strongest signal in the room; when
+        // it points at the wrong file it does not merely fail to help, it
+        // manufactures the wrong belief. Name the real path (ADR-104: always
+        // user-global, never project-local) and name the verb that reports it.
         throw new CouncilDisabledError(
-            'ai_council.enabled is false in .agent-settings.yml — ' +
-                'flip it on before invoking council:* commands.',
+            `enabled is false in the council config (${COUNCIL_CONFIG_USER_GLOBAL_REL} ` +
+                'under the user-global agent-config root) — flip it on before invoking ' +
+                'council:* commands. This config is NEVER project-local (ADR-104), so do ' +
+                'not look for it, or create it, in the project tree. ' +
+                '`agent-config council:status` prints the resolved path.',
         );
     }
     const members_cfg = (ai['members'] as Dict) || {};
@@ -608,7 +623,8 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             if (name in siblings) {
                 throw new CouncilDisabledError(
                     `--siblings targets member ${_pyReprStr(name)} but it is not ` +
-                        `enabled in .agent-settings.yml (ai_council.members.${name}.enabled).`,
+                        `enabled in the council config (members.${name}.enabled in ` +
+                        `${COUNCIL_CONFIG_USER_GLOBAL_REL} under the user-global root).`,
                 );
             }
             continue;
@@ -714,8 +730,10 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             );
         }
         throw new CouncilDisabledError(
-            'no council member has `enabled: true` — enable at least one in ' +
-                '.agent-settings.yml under ai_council.members.*.',
+            'no council member has `enabled: true` — enable at least one under ' +
+                `members.* in ${COUNCIL_CONFIG_USER_GLOBAL_REL} (user-global root; ` +
+                'never the project tree, ADR-104). `agent-config council:status` ' +
+                'prints the resolved path.',
         );
     }
     return members;
@@ -1855,6 +1873,95 @@ function _emit_shadow_slo_banner(): void {
     }
 }
 
+/**
+ * `council:status` — answer "is a council configured, and from where" without
+ * spending anything, so no caller has to infer it from a filename.
+ *
+ * WHY THIS EXISTS. Measured 2026-08-08: an agent working in a consumer project
+ * announced "Kein Council konfiguriert (keine `.agent-settings.yml`)" and
+ * substituted a weaker subagent fan-out. The council was configured the whole
+ * time, user-globally. The inference was wrong twice over — the council config
+ * has not lived in `.agent-settings.yml` since the Phase-0 migration, and per
+ * ADR-104 the project tree is **never** searched, so the presence or absence of
+ * any project file says nothing at all about council availability.
+ *
+ * The guidance was not missing: `/council default` states this emphatically in
+ * four places. But a command file only loads when the command is invoked, and
+ * the agent was deciding *whether a capability existed* — a question it reached
+ * before invoking anything. The always-loaded layer says "when the council is
+ * enabled" and never says how to find out.
+ *
+ * So the fix is not more prose. It is a check that costs nothing to run and
+ * leaves nothing to infer. Exit is always 0 — this reports a state, it does not
+ * gate — and the verdict line is machine-greppable in both directions.
+ */
+export function cmd_status(args: Args, opts: { env?: Record<string, string | undefined> } = {}): number {
+    const env = opts.env ?? process.env;
+    const override = env[COUNCIL_CONFIG_ENV];
+    const path_ = resolve_config_path(REPO_ROOT, { env: env as never });
+    const exists = fs.existsSync(String(path_));
+    const provenance = override ? `${COUNCIL_CONFIG_ENV} override` : 'user-global';
+
+    let cfg: CouncilConfig | null = null;
+    let parse_error: string | null = null;
+    if (exists) {
+        try {
+            cfg = load_council_config(path_);
+        } catch (exc) {
+            parse_error = exc instanceof Error ? exc.message : String(exc);
+        }
+    }
+
+    const enabledMembers = cfg === null ? [] : [...cfg.members.entries()].filter(([, m]) => m.enabled);
+    // "Configured" deliberately means: a readable file whose `enabled` is true and
+    // which has at least one enabled member. A file that parses but enables
+    // nothing is the case a caller most needs told apart from a missing file,
+    // because only one of the two is fixed by writing a config.
+    const configured = cfg !== null && cfg.enabled && enabledMembers.length > 0;
+
+    if (_getattr(args, 'json', false)) {
+        _stdout(
+            `${JSON.stringify({
+                configured,
+                path: String(path_),
+                exists,
+                provenance,
+                enabled: cfg?.enabled ?? null,
+                members_total: cfg === null ? null : cfg.members.size,
+                members_enabled: cfg === null ? null : enabledMembers.length,
+                member_names: enabledMembers.map(([n]) => n),
+                parse_error,
+                project_tree_consulted: false,
+            })}\n`,
+        );
+        return 0;
+    }
+
+    _stdout(`council:status · ${configured ? 'CONFIGURED' : 'NOT CONFIGURED'}\n`);
+    _stdout(`  config path      ${String(path_)}\n`);
+    _stdout(`  resolved by      ${provenance}\n`);
+    _stdout(`  file exists      ${exists ? 'yes' : 'no'}\n`);
+    if (parse_error !== null) {
+        _stdout(`  parse error      ${parse_error}\n`);
+    }
+    if (cfg !== null) {
+        _stdout(`  enabled          ${cfg.enabled ? 'yes' : 'no'}\n`);
+        _stdout(`  members          ${enabledMembers.length} enabled of ${cfg.members.size}\n`);
+        if (enabledMembers.length > 0) {
+            _stdout(`                   ${enabledMembers.map(([n]) => n).join(', ')}\n`);
+        }
+    }
+    _stdout('\n');
+    _stdout('  The project tree is NEVER consulted (ADR-104). No project file —\n');
+    _stdout('  `.agent-settings.yml` included — indicates council availability in\n');
+    _stdout('  either direction. Do not infer it from one; run this instead.\n');
+    if (!configured) {
+        _stdout(`\n  To configure: write ${COUNCIL_CONFIG_USER_GLOBAL_REL} under the user-global\n`);
+        _stdout('  agent-config root, with `enabled: true` and at least one enabled member.\n');
+    }
+    return 0;
+}
+
 function _apply_solo_dispatch(members: ExternalAIClient[]): [ExternalAIClient[], string | null] {
     let cfg: CouncilConfig;
     try {
@@ -2826,13 +2933,15 @@ interface Args {
     // shadow-report
     log: string | null;
     window_days: number;
+    // status
+    json: boolean;
 }
 
-const _SUBCOMMANDS = ['estimate', 'run', 'debate', 'render', 'replay', 'quota', 'shadow-report'];
+const _SUBCOMMANDS = ['estimate', 'run', 'debate', 'render', 'replay', 'quota', 'shadow-report', 'status'];
 
 const _TOP_USAGE =
     `usage: ${_PROG} [-h]\n` +
-    `                            {estimate,run,debate,render,replay,quota,shadow-report}\n` +
+    `                            {estimate,run,debate,render,replay,quota,shadow-report,status}\n` +
     `                            ...\n`;
 
 function _topError(message: string): never {
@@ -2886,6 +2995,7 @@ function _defaultArgs(): Args {
         reset: null,
         log: null,
         window_days: 7,
+        json: false,
     };
 }
 
@@ -3009,6 +3119,12 @@ function _specsFor(cmd: string): { positionals: string[]; opts: OptSpec[]; requi
                 ],
                 requiredOpts: [],
             };
+        case 'status':
+            return {
+                positionals: [],
+                opts: [{ flag: '--json', takesValue: false, apply: (o) => (o.json = true) }],
+                requiredOpts: [],
+            };
         default:
             return { positionals: [], opts: [], requiredOpts: [] };
     }
@@ -3213,6 +3329,9 @@ function main(argv: string[] | null = null): number {
         if (args.cmd === 'shadow-report') {
             return cmd_shadow_report(args);
         }
+        if (args.cmd === 'status') {
+            return cmd_status(args);
+        }
     } catch (exc) {
         if (exc instanceof CouncilDisabledError) {
             _stderr(`❌  council:${args.cmd}: ${exc.message}\n`);

package/src/scripts/generate_settings_reference.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Generate the human-readable settings reference page.
+ *
+ * `road-to-zero-ceremony-settings` Phase 3 step 3. The user's global settings
+ * file is becoming sparse, so the long-form explanation that used to ride along
+ * as template comments has to survive somewhere the user can still read it.
+ *
+ * The page is derived from TWO sources that already exist, and from nothing
+ * else — the point is that there is no third surface to keep in sync:
+ *
+ *   1. the zod settings schema (`src/server/schemas/settings.ts`), flattened
+ *      through the same `flattenSurface` the installer uses for its upgrade
+ *      delta, so type / default / enum / description come from one place;
+ *   2. the A/B/C class table (`docs/contracts/settings-classes.md`), parsed by
+ *      the same `parseSettingsClassRows` the lint and the writer use, so the
+ *      page cannot claim a class the fence does not enforce.
+ *
+ * The package VERSION is deliberately absent from the output. Rendering it
+ * would make this page drift on every release bump and red `--check` for a
+ * change nobody made — the page describes the schema's shape, not the release
+ * that shipped it.
+ *
+ * Produces: docs/settings-reference.md
+ *
+ * Modes:
+ *   --check      Regenerate to memory and diff against the committed page.
+ *   (default)    Regenerate in place; exit 0 on success.
+ *
+ * Exit codes: 0 = ok, 1 = drift (--check), 2 = bad usage, 3 = internal.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { settingsSchema } from '../server/schemas/settings.js';
+import {
+    buildSettingsClassIndex,
+    parseSettingsClassRows,
+    type SettingsClass,
+} from '../shared/settingsClasses.js';
+import { flattenSurface, type SurfaceEntry } from '../shared/settingsSurface.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+export const ROOT = path.resolve(_HERE, '..', '..');
+
+export const CONTRACT_REL = path.join('docs', 'contracts', 'settings-classes.md');
+export const OUTPUT_REL = path.join('docs', 'settings-reference.md');
+
+/** What each class means for the reader. Mirrors the contract's own table. */
+const CLASS_BLURB: Record<SettingsClass, string> = {
+    A: 'preference — the agent may set it; you are never asked',
+    B: 'consent — the agent asks once, then persists your answer',
+    C: 'guarded — only you (GUI or hand-edit) may change it',
+};
+
+/** A key with no row in the contract. The lint fails on these separately. */
+const UNCLASSIFIED = '—';
+
+export interface ReferenceRow {
+    key: string;
+    cls: SettingsClass | null;
+    entry: SurfaceEntry;
+}
+
+/**
+ * Group by top-level segment so the page reads like the template did.
+ * Leaves with no dot (e.g. `discipline_profile`) group under `(root)`.
+ */
+export function groupRows(rows: readonly ReferenceRow[]): Map<string, ReferenceRow[]> {
+    const groups = new Map<string, ReferenceRow[]>();
+    for (const row of rows) {
+        const dot = row.key.indexOf('.');
+        const section = dot === -1 ? '(root)' : row.key.slice(0, dot);
+        const bucket = groups.get(section);
+        if (bucket === undefined) groups.set(section, [row]);
+        else bucket.push(row);
+    }
+    return groups;
+}
+
+/** Render a value for a markdown table cell — never let it break the row. */
+export function renderCell(value: unknown): string {
+    if (value === undefined) return '';
+    const json = JSON.stringify(value);
+    if (json === undefined) return '';
+    return `\`${json.replace(/\|/g, '\\|')}\``;
+}
+
+/** Descriptions are free prose; pipes and newlines would break the table. */
+export function renderProse(value: string | undefined): string {
+    if (value === undefined || value === '') return '';
+    return value.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+}
+
+export function buildRows(contractMarkdown: string): ReferenceRow[] {
+    const jsonSchema = zodToJsonSchema(settingsSchema, {
+        name: 'AgentSettings',
+        $refStrategy: 'none',
+        target: 'jsonSchema7',
+    }) as Parameters<typeof flattenSurface>[0];
+    // The version is a required parameter of the shared flattener and is
+    // discarded here on purpose — see the module header.
+    const surface = flattenSurface(jsonSchema, 'unversioned');
+    const classIndex = buildSettingsClassIndex(parseSettingsClassRows(contractMarkdown));
+
+    return Object.keys(surface.entries)
+        .sort()
+        .map((key) => ({
+            key,
+            cls: classIndex.get(key) ?? null,
+            entry: surface.entries[key] as SurfaceEntry,
+        }));
+}
+
+export function renderPage(rows: readonly ReferenceRow[]): string {
+    const out: string[] = [];
+    out.push('# Settings reference — every key, its class, and its default');
+    out.push('');
+    out.push('> **Generated** by `src/scripts/generate_settings_reference.ts` — do NOT');
+    out.push('> hand-edit. Derived from the zod settings schema plus the A/B/C class');
+    out.push('> table in [`settings-classes`](contracts/settings-classes.md).');
+    out.push('> Drift-checked in CI (`--check`).');
+    out.push('');
+    out.push('Your global settings file is **sparse**: it records the decisions you');
+    out.push('actually made, not every key that exists. A key absent from the file');
+    out.push('resolves to the default listed here. This page is where the long-form');
+    out.push('explanation lives now that the file no longer carries it as comments.');
+    out.push('');
+    out.push('**Class** answers one question — *who may write this key.*');
+    out.push('');
+    for (const cls of ['A', 'B', 'C'] as const) {
+        out.push(`- **${cls}** — ${CLASS_BLURB[cls]}`);
+    }
+    out.push('');
+
+    const groups = groupRows(rows);
+    for (const section of [...groups.keys()].sort()) {
+        const bucket = groups.get(section) as ReferenceRow[];
+        out.push(`## ${section}`);
+        out.push('');
+        out.push('| Key | Class | Type | Default | Allowed values | What it does |');
+        out.push('|---|---|---|---|---|---|');
+        for (const row of bucket) {
+            const allowed = row.entry.enum === undefined
+                ? ''
+                : row.entry.enum.map((v) => `\`${String(v)}\``).join(' · ');
+            out.push(
+                `| \`${row.key}\` | ${row.cls ?? UNCLASSIFIED} | ${row.entry.type} | `
+                + `${renderCell(row.entry.default)} | ${allowed} | ${renderProse(row.entry.description)} |`,
+            );
+        }
+        out.push('');
+    }
+
+    out.push('## See also');
+    out.push('');
+    out.push('- [`settings-classes`](contracts/settings-classes.md) — the class contract this page reads.');
+    out.push('- [`settings-api`](contracts/settings-api.md) — the read/write surface.');
+    out.push('');
+    return out.join('\n');
+}
+
+export function generate(root: string): string {
+    const contract = fs.readFileSync(path.join(root, CONTRACT_REL), 'utf-8');
+    return renderPage(buildRows(contract));
+}
+
+interface Args {
+    check: boolean;
+}
+
+export function parse_args(argv: readonly string[]): Args {
+    const args: Args = { check: false };
+    for (const a of argv) {
+        if (a === '--check') {
+            args.check = true;
+            continue;
+        }
+        process.stderr.write(`generate_settings_reference: unknown argument: ${a}\n`);
+        process.exit(2);
+    }
+    return args;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    const out_path = path.join(ROOT, OUTPUT_REL);
+
+    let rendered: string;
+    try {
+        rendered = generate(ROOT);
+    } catch (err) {
+        process.stderr.write(`generate_settings_reference: ${String(err)}\n`);
+        return 3;
+    }
+
+    if (args.check) {
+        let committed: string | null = null;
+        try {
+            committed = fs.readFileSync(out_path, 'utf-8');
+        } catch {
+            committed = null;
+        }
+        if (committed !== rendered) {
+            process.stderr.write(
+                `❌  ${OUTPUT_REL} is out of date.\n`
+                + '    Regenerate: ./scripts-run src/scripts/generate_settings_reference\n',
+            );
+            return 1;
+        }
+        process.stdout.write(`✅  ${OUTPUT_REL} is up to date.\n`);
+        return 0;
+    }
+
+    fs.mkdirSync(path.dirname(out_path), { recursive: true });
+    fs.writeFileSync(out_path, rendered, 'utf-8');
+    process.stdout.write(`✅  wrote ${OUTPUT_REL}\n`);
+    return 0;
+}
+
+function _invoked_directly(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    return import.meta.url === argvUrl;
+}
+
+if (_invoked_directly()) {
+    process.exitCode = main();
+}