@event4u/agent-config 9.25.0 → 9.27.0

package/src/scripts/validate_frontmatter.ts

@@ -32,6 +32,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { KERNEL_RULE_ID_SET } from './_lib/kernel_rules.js';
+import {
+    frequency_prose_conflicts,
+    has_frequency_override,
+    is_frequency,
+} from './_lib/obligation_frequency.js';
 
 // Free-form YAML value alias. The lenient subset parser produces strings,
 // numbers, booleans, the empty string, nested objects, and arrays of those.
@@ -807,6 +813,65 @@ function pyListRepr(values: YamlValue[]): string {
     return `[${values.map((v) => pyRepr(v)).join(', ')}]`;
 }
 
+/**
+ * Rule-only checks for `obligation_frequency` — the field the coverage join
+ * reads.
+ *
+ * Two obligations, at two severities:
+ *
+ *  - **Required, as an error.** A rule with no declared period cannot be joined
+ *    against its carrier's firing frequency, so the audit reports it
+ *    `unclassified` — which is a hole in the finding, not a pass. Making it
+ *    mandatory at authoring time is the pin: a NEW rule with a per-turn
+ *    obligation and no turn-carrier is caught here rather than in a later audit.
+ *
+ *  - **Prose agreement, as a warning.** A keyword heuristic will be noisy, so it
+ *    never fails a build.
+ *
+ * The nine kernel rules are exempt, and the exemption is DERIVED from
+ * `_lib/kernel_rules.ts` — the same locked set `block_kernel_rule_writes.ts`
+ * enforces. They are not exempt because kernel rules are special; they are
+ * exempt because that guard denies the write, so requiring the field would make
+ * `task ci` unsatisfiable for any agent. Deriving it rather than hand-listing it
+ * closes the exemption automatically: the moment a rule leaves the kernel, the
+ * field becomes required with no edit here.
+ */
+export function check_obligation_frequency(
+    filePath: string,
+    text: string,
+    data: Record<string, YamlValue>,
+): SchemaError[] {
+    const id = path.basename(filePath).replace(/\.md$/, '');
+    if (KERNEL_RULE_ID_SET.has(id)) return [];
+
+    const declared = data['obligation_frequency'];
+    if (!is_frequency(declared)) {
+        return [
+            new SchemaError(
+                '$.obligation_frequency',
+                'required',
+                "Missing required property 'obligation_frequency' — how often this rule's " +
+                    'obligation comes due. Without it check_enforcement_coverage cannot join ' +
+                    "the rule against its carrier's firing frequency and reports it unclassified.",
+            ),
+        ];
+    }
+    if (has_frequency_override(text)) return [];
+
+    const conflicts = frequency_prose_conflicts(text, declared);
+    if (conflicts.length === 0) return [];
+    return [
+        new SchemaError(
+            '$.obligation_frequency',
+            'frequency-prose-drift',
+            `declared '${declared}', but the prose reads as ${conflicts.join(' / ')} — ` +
+                'either the declaration or the prose moved. Silence an audited mismatch with a ' +
+                '`# frequency-override: <reason>` comment in the frontmatter.',
+            'warning',
+        ),
+    ];
+}
+
 // --- CLI entry point -------------------------------------------------------
 
 /** Yield `[artefact_type, path]` pairs for all lintable artefacts. */
@@ -931,6 +996,9 @@ export function _main(argv: string[]): number {
             // (road-to-abstraction-reduction.md Phase 1).
             apply_schema_defaults(data, schema);
             const errors = validate(data, schema);
+            if (artefactType === 'rule') {
+                errors.push(...check_obligation_frequency(p, text, data));
+            }
             const fatal = errors.filter((e) => e.severity === 'error');
             const warnings = errors.filter((e) => e.severity === 'warning');
             if (fatal.length > 0) {

package/src/server/io/yamlIO.ts

@@ -130,6 +130,93 @@ export function mergeIntoTemplate(templateBody: string, newValues: Record<string
     return body;
 }
 
+/**
+ * Placeholders the shipped template carries, and the value each resolves to
+ * when nothing has substituted it. The installer fills these from the chosen
+ * profile preset; anything reading the template directly must substitute them
+ * too, or it writes a literal `__PLACEHOLDER__` into the user's file.
+ */
+export const TEMPLATE_PLACEHOLDER_DEFAULTS: Readonly<Record<string, string>> = {
+    __RULE_LOADING_TIER__: 'balanced',
+    // Successor knob (ADR-110). P2-verdict council 2026-07-07: the
+    // balanced-heritage default is `auto` — lift only where measured
+    // (vendor-granular unknown_defaults in src/config/host-capabilities.yml).
+    __DISCIPLINE_PROFILE__: 'auto',
+    __USER_TYPE__: '',
+    __CHAT_HISTORY_FREQUENCY__: 'per_turn',
+    __CHAT_HISTORY_MAX_SIZE_KB__: '2048',
+    __CHAT_HISTORY_ON_OVERFLOW__: 'rotate',
+};
+
+/** Replace every known template placeholder with its default value. */
+export function substituteTemplatePlaceholders(body: string): string {
+    let rendered = body;
+    for (const [placeholder, value] of Object.entries(TEMPLATE_PLACEHOLDER_DEFAULTS)) {
+        rendered = rendered.replaceAll(placeholder, value);
+    }
+    return rendered;
+}
+
+/** Read one dotted path out of a parsed settings tree. `undefined` when absent. */
+export function readPath(root: Record<string, unknown>, dotted: string): unknown {
+    let node: unknown = root;
+    for (const segment of dotted.split('.')) {
+        if (node === null || typeof node !== 'object' || Array.isArray(node)) return undefined;
+        node = (node as Record<string, unknown>)[segment];
+    }
+    return node;
+}
+
+/** Write one dotted path into a settings tree, creating intermediate objects. */
+export function writePath(root: Record<string, unknown>, dotted: string, value: unknown): void {
+    const segments = dotted.split('.');
+    const leaf = segments.pop();
+    if (leaf === undefined) return;
+    let node = root;
+    for (const segment of segments) {
+        const next = node[segment];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+            const created: Record<string, unknown> = {};
+            node[segment] = created;
+            node = created;
+        } else {
+            node = next as Record<string, unknown>;
+        }
+    }
+    node[leaf] = value;
+}
+
+/**
+ * Render a SPARSE settings document — the decisions actually made, and nothing
+ * else (`road-to-zero-ceremony-settings` Phase 3).
+ *
+ * The counterpart to `mergeIntoTemplate`, which returns the whole 1,233-line
+ * template with the answers patched in. Here the template is consulted only as
+ * the value source for the carve-out keys; it is never copied into the output.
+ *
+ * Comment preservation is not a concern in this direction, because there are no
+ * template comments to preserve — the long-form explanation those comments used
+ * to carry now lives in the generated `docs/settings-reference.md`, which the
+ * header points at.
+ */
+export function renderSparseSettings(values: Record<string, unknown>): string {
+    const header = [
+        '# Your settings — a record of decisions, not a copy of the defaults.',
+        '#',
+        '# Every key absent from this file resolves to its documented default.',
+        '# The full key list, with defaults and explanations, is generated at',
+        '# docs/settings-reference.md — this file stays small on purpose.',
+        '#',
+        '# How each entry was decided is recorded beside it in',
+        '# `.agent-settings.provenance.json`.',
+        '',
+    ].join('\n');
+    const body = Object.keys(values).length === 0
+        ? ''
+        : yamlDump(values, { lineWidth: -1, sortKeys: true });
+    return `${header}${body}`;
+}
+
 export function diffValues(
     before: Record<string, unknown>,
     after: Record<string, unknown>,

package/src/shared/interactiveContext.ts

@@ -0,0 +1,98 @@
+/**
+ * Is there a human at the other end of this execution?
+ *
+ * Phase 4 of `road-to-zero-ceremony-settings`: *"Skip cleanly in non-TTY, CI,
+ * and headless contexts: no file, defaults, no questions, ever."* A settings
+ * question posed where nobody can answer it is not a question — it is either a
+ * hang or a silently-taken default wearing a prompt's clothes.
+ *
+ * WHY THIS MODULE EXISTS RATHER THAN A FOURTH INLINE CHECK. The tree already
+ * carries several CI-detection shapes that disagree:
+ *
+ * - `set && !== '0'` — `src/cli/firstRunNotice.ts`, `src/cli/initRouting.ts`
+ * - truthy only — `src/scripts/install.ts`, `src/scripts/release.ts`
+ * - exact match — `src/scripts/_lib/exec_evidence.ts` (`'true' | '1'`)
+ * - widest, three variables — `src/scripts/reach_doctor.ts`
+ *   (`CI`, `GITHUB_ACTIONS`, `AGENT_CONFIG_CI`)
+ *
+ * This module takes the **widest** shape, because the failure modes are
+ * asymmetric: a false "interactive" hangs an automated run or fabricates a
+ * consent, while a false "non-interactive" merely declines to ask and takes a
+ * conservative default — which is the documented behaviour anyway.
+ *
+ * It deliberately does NOT rewrite those four call sites. Their behaviour is
+ * correct for what they gate (a printed notice, a browser launch), and
+ * converting them here would be a drive-by change to code this concern does not
+ * own. The divergence is recorded rather than repaired — see the roadmap note on
+ * Phase 4 step 3.
+ *
+ * Pure — the environment and the TTY flags are arguments, never read from
+ * `process` inside the predicate, so a test never depends on the machine it
+ * runs on.
+ */
+
+/** Why an execution cannot host a question. `null` means it can. */
+export type NonInteractiveReason =
+    | 'ci'
+    | 'no-ui-requested'
+    | 'not-a-tty'
+    | 'headless';
+
+export interface SessionProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /** `process.stdin.isTTY === true`. */
+    stdinTty: boolean;
+    /** `process.stdout.isTTY === true`. */
+    stdoutTty: boolean;
+    /**
+     * A display-less environment (SSH without forwarding, Linux without
+     * `DISPLAY`). Supplied by the caller because probing it is platform work,
+     * and `src/cli/commands/uiServe.ts` already owns that probe.
+     */
+    headless?: boolean;
+}
+
+/**
+ * The CI variables this predicate honours, widest-first.
+ *
+ * A variable counts as set when it is present and not the literal `0` — the
+ * `set && !== '0'` convention already used by the first-run notice, kept so a
+ * consumer who exports `CI=0` to mean "not CI" is believed.
+ */
+const CI_ENV_KEYS = ['CI', 'GITHUB_ACTIONS', 'AGENT_CONFIG_CI'] as const;
+
+function _flagSet(env: NodeJS.ProcessEnv, key: string): boolean {
+    const raw = (env[key] ?? '').trim();
+    return raw !== '' && raw !== '0';
+}
+
+/**
+ * The reason this execution may not ask, or `null` when a human is reachable.
+ *
+ * Order is deliberate and is the order a reader should think in: an explicit
+ * request not to be asked outranks a capability probe, and CI outranks
+ * everything because a CI run that asks is a CI run that hangs.
+ */
+export function nonInteractiveReason(probe: SessionProbe): NonInteractiveReason | null {
+    for (const key of CI_ENV_KEYS) {
+        if (_flagSet(probe.env, key)) {
+            return 'ci';
+        }
+    }
+    if (_flagSet(probe.env, 'AGENT_CONFIG_NO_UI')) {
+        return 'no-ui-requested';
+    }
+    if (!probe.stdinTty || !probe.stdoutTty) {
+        return 'not-a-tty';
+    }
+    if (probe.headless === true) {
+        return 'headless';
+    }
+    return null;
+}
+
+/** Convenience inverse — `true` when a question is answerable. */
+export function isInteractiveSession(probe: SessionProbe): boolean {
+    return nonInteractiveReason(probe) === null;
+}

package/src/shared/nicknamePrefill.ts

@@ -0,0 +1,96 @@
+/**
+ * What to put in the nickname field before the user types anything.
+ *
+ * Phase 4 step 2 of `road-to-zero-ceremony-settings`: *"Ask the nickname once,
+ * prefilled from git user name then `$USER`, so accepting is one keypress."*
+ * `src/rules/settings-ask-protocol.md` states the chain and closes it with a
+ * negation — **"Never `$USER` alone."**
+ *
+ * WHY THIS MODULE EXISTS. The rule shipped that chain; the one surface that
+ * actually prefills shipped a different one. `src/server/routes/ping.ts` read
+ * `userInfo().username` and nothing else — precisely the `$USER`-alone shape the
+ * rule forbids. A rule and the code it describes disagreeing is drift, not a
+ * preference, so the chain now has exactly one implementation and both the
+ * server route and the tests read it from here.
+ *
+ * WHY GIT COMES FIRST. `$USER` is a login handle (`mathiasberg`); `git config
+ * user.name` is the name the human chose to be called by (`Mathias Berg`). The
+ * whole point of the prefill is that accepting costs one keypress, and that only
+ * holds when the prefilled value is the one they would have typed. Note the
+ * lookup is deliberately NOT `--local`: the merged config includes
+ * `~/.gitconfig`, so the wizard still finds a name when it runs outside a repo.
+ *
+ * Pure: the git lookup is injected, so the resolver is a function of its probe
+ * alone and a test never depends on the machine it runs on — the same shape as
+ * `interactiveContext.ts` and `settingsConsent.ts`. The Node-side half (running
+ * git, falling back to `userInfo()`) lives in `src/server/nicknameResolver.ts`,
+ * because `src/shared/**` may not import Node built-ins and the lint enforces it.
+ *
+ * @see src/server/nicknameResolver.ts — the impure half
+ * @see src/rules/settings-ask-protocol.md § Worked example — the nickname
+ * @see docs/contracts/settings-classes.md
+ */
+
+/**
+ * Where a candidate name came from, so a caller can say so.
+ *
+ * `os-account` is the `userInfo()` floor, and it is a distinct member rather
+ * than a reuse of `env-user` on purpose: the whole claim of the floor is that
+ * its RANK changed (last, not first), and a rank nothing can observe is not a
+ * rank. A caller reporting provenance would otherwise name the wrong rung on
+ * exactly the path the floor exists to serve.
+ *
+ * `none` is a real outcome, not an error: a machine with no git identity, no
+ * `USER` and no resolvable account is unusual but legal, and the ask still
+ * works — it just starts empty.
+ */
+export type NicknameSource =
+    | 'git-user-name'
+    | 'env-user'
+    | 'env-username'
+    | 'os-account'
+    | 'none';
+
+export interface NicknamePrefill {
+    /** The prefill value, or `''` when nothing resolved. */
+    name: string;
+    source: NicknameSource;
+}
+
+export interface NicknameProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * `git config user.name`, or `undefined` when git is absent, unconfigured,
+     * or too slow. Injected so the resolver stays pure.
+     */
+    gitUserName?: string | undefined;
+}
+
+/** Trim, and treat a whitespace-only value as absent. */
+function _clean(value: string | undefined): string {
+    return (value ?? '').trim();
+}
+
+/**
+ * The prefill for the nickname ask, following the documented chain.
+ *
+ * Order is the rule's, and the negation at the end of it is the load-bearing
+ * part: `$USER` is a fallback, never the first answer.
+ */
+export function nicknamePrefill(probe: NicknameProbe): NicknamePrefill {
+    const git = _clean(probe.gitUserName);
+    if (git !== '') {
+        return { name: git, source: 'git-user-name' };
+    }
+    const user = _clean(probe.env['USER']);
+    if (user !== '') {
+        return { name: user, source: 'env-user' };
+    }
+    // Windows spells it differently; the rule names it explicitly.
+    const username = _clean(probe.env['USERNAME']);
+    if (username !== '') {
+        return { name: username, source: 'env-username' };
+    }
+    return { name: '', source: 'none' };
+}

package/src/shared/settingsAsks.ts

@@ -0,0 +1,176 @@
+/**
+ * The one-question budget, as a function rather than as a promise.
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`. The rule
+ * `src/rules/settings-ask-protocol.md` states the budget — at most ONE settings
+ * question per command execution, every further undecided key taking its
+ * conservative default silently and being named in the end-summary. Prose is
+ * where that obligation has to live, because no gate can count the questions in
+ * a chat turn.
+ *
+ * But the *split* is not a judgement call: given the keys an execution needs
+ * decided, which one is asked and what the others resolve to is fully
+ * determined. Leaving that determined part in prose too would mean the roadmap's
+ * own exit criterion — "a planted fixture needing three B decisions asks once,
+ * assumes two conservatively, and lists both in the summary" — had nothing to
+ * run against. So the split is computed here and the rule points at it.
+ *
+ * What this module does NOT do, stated so nobody mistakes it for the fence:
+ * it does not ask, it does not write, and it cannot stop an agent that ignores
+ * it. The write fence is one layer down and is real —
+ * `src/scripts/_cli/cmd_settings_set.ts` and the Fastify settings route both
+ * refuse every C-class key and fail closed on an unreadable class contract.
+ *
+ * Pure — no I/O, no clock, no environment.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+
+import { classOfPath, isConservativeDefault, type SettingsClass } from './settingsClasses.js';
+
+/** A key this execution resolved without asking, and how to change it later. */
+export interface SilentDefault {
+    key: string;
+    /** The value taken — the template default, which for B is conservative. */
+    value: unknown;
+    /** The exact command that changes it, for the end-summary line. */
+    command: string;
+}
+
+/** A key that never reaches the ask path, and the reason it does not. */
+export interface SkippedKey {
+    key: string;
+    reason:
+        | 'class-a-never-asked'
+        | 'class-c-guarded'
+        | 'unclassified'
+        | 'already-decided'
+        | 'non-conservative-default';
+}
+
+export interface AskPlan {
+    /** The single key that gets this execution's question, or `null` for none. */
+    ask: string | null;
+    /** Undecided keys that took their default silently, in the order given. */
+    silent: SilentDefault[];
+    /** Keys excluded from the ask path entirely, with the reason. */
+    skipped: SkippedKey[];
+}
+
+/**
+ * The end-summary line for a silently defaulted key.
+ *
+ * `--source manual` and not `jit-answer`: the user did not answer a question, so
+ * stamping the write as a just-in-time answer would record a consent nobody
+ * gave. The provenance vocabulary exists to keep exactly that distinction.
+ */
+export function changeCommand(key: string): string {
+    return `agent-config settings:set ${key} <value> --source manual`;
+}
+
+/**
+ * Plan one execution's settings asks.
+ *
+ * `needed` is the keys this execution genuinely cannot proceed without, in the
+ * order they became needed — the caller's own ordering is respected because the
+ * first key to actually block the run is the one that earned the question.
+ *
+ * `decided` is every key already settled on any resolution layer. A decided key
+ * is not a candidate: re-asking a settled question is the cheap question the
+ * ask-discipline rules forbid, and it is the single most likely way this budget
+ * gets spent on nothing.
+ *
+ * `defaultOf` supplies the template default. It returns `undefined` for a key
+ * the template does not carry, which is treated as unclassified rather than as
+ * a default of `undefined` — a missing template entry is a defect, not a value.
+ */
+export function planSettingsAsks(
+    needed: readonly string[],
+    classes: ReadonlyMap<string, SettingsClass>,
+    defaultOf: (key: string) => unknown,
+    decided: ReadonlySet<string> = new Set(),
+    options: { interactive?: boolean } = {},
+): AskPlan {
+    const plan: AskPlan = { ask: null, silent: [], skipped: [] };
+    const seen = new Set<string>();
+    // Non-TTY / CI / headless: nobody can answer, so the budget is ZERO rather
+    // than one. Every candidate takes its conservative default and the plan
+    // carries no ask — "no questions, ever", as a computed fact rather than as a
+    // promise the caller has to remember. Nothing is written either: this
+    // function never persists, and with no ask there is no `jit-answer` write.
+    const interactive = options.interactive ?? true;
+
+    for (const key of needed) {
+        // A duplicate in the caller's list must not consume the budget twice.
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+
+        if (decided.has(key)) {
+            plan.skipped.push({ key, reason: 'already-decided' });
+            continue;
+        }
+
+        const cls = classOfPath(classes, key);
+        if (cls === undefined) {
+            // Unclassified is guarded everywhere else in this system; it is
+            // guarded here too. Never fall back to "probably fine".
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+        if (cls === 'A') {
+            plan.skipped.push({ key, reason: 'class-a-never-asked' });
+            continue;
+        }
+        if (cls === 'C') {
+            // A C key set to `ask` still produces a RUNTIME question, but that
+            // answer lasts one run and is never persisted, so it is not this
+            // budget's business. Persisting it stays on the human path.
+            plan.skipped.push({ key, reason: 'class-c-guarded' });
+            continue;
+        }
+
+        const fallback = defaultOf(key);
+        if (fallback === undefined) {
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+
+        if (interactive && plan.ask === null) {
+            plan.ask = key;
+            continue;
+        }
+
+        if (!isConservativeDefault(fallback)) {
+            // Taking a permissive value silently would be a decision made in
+            // the user's name — the one outcome the Iron Law names outright.
+            // Surfacing it as skipped forces the caller to deal with it instead
+            // of inheriting a permission nobody granted.
+            plan.skipped.push({ key, reason: 'non-conservative-default' });
+            continue;
+        }
+
+        plan.silent.push({ key, value: fallback, command: changeCommand(key) });
+    }
+
+    return plan;
+}
+
+/**
+ * The end-summary block for a plan, or `null` when nothing was defaulted.
+ *
+ * `null` rather than an empty string so a caller cannot append a heading with no
+ * rows under it. This text rides INSIDE the single end-summary that
+ * `direct-answers` already requires — it is never a second summary.
+ */
+export function silentDefaultsSummary(plan: AskPlan): string | null {
+    if (plan.silent.length === 0) {
+        return null;
+    }
+    const lines = plan.silent.map(
+        (s) => `- \`${s.key}\` → ${JSON.stringify(s.value)} (default) · change: \`${s.command}\``,
+    );
+    return `Settings resolved without asking this run:\n${lines.join('\n')}`;
+}