@event4u/agent-config 9.25.0 → 9.27.0

package/src/shared/settingsCarveOut.ts

@@ -0,0 +1,143 @@
+/**
+ * The always-written carve-out set for the sparse settings file.
+ *
+ * `road-to-zero-ceremony-settings` Phase 3. The user's global settings file
+ * becomes a sparse record of decisions actually made, which is safe only while
+ * *key absent* resolves exactly like *key set to the template default*.
+ *
+ * An audit of every reader found that is NOT universally true. For the keys
+ * below a reader deliberately resolves an absent key to something other than
+ * the template's default, so omitting them from a fresh install's file would
+ * silently change behaviour. They are written explicitly instead, with their
+ * template value, and stamped `package-default` in the provenance sidecar so
+ * the file never claims the user decided them.
+ *
+ * This is the blocker's "carved out" branch. The alternative branch — "fixed at
+ * its reader" — was rejected for the `projection.*` family because the
+ * divergence there is the documented upgrade-safety contract
+ * (`agent-settings.template.yml`: *"a missing key also still means legacy-all,
+ * so only fresh installs get the scoped default"*). Changing those readers
+ * would flip existing 5.x installs from `legacy-all` to `scoped`, which is the
+ * silent narrowing the contract exists to prevent.
+ *
+ * Pure module — no I/O. The VALUES are not duplicated here; only the key paths
+ * and the reason. The emitter reads each value out of the template, so this
+ * list cannot drift from the defaults it is protecting.
+ *
+ * @see docs/contracts/settings-classes.md
+ */
+
+/** One key whose absence is not equivalent to its template default. */
+export interface CarveOutKey {
+    /** Dotted path into the settings tree. */
+    key: string;
+    /** The reader that diverges, as `file:line`, so the claim is checkable. */
+    reader: string;
+    /** What an ABSENT key resolves to at that reader. */
+    absentResolvesTo: string;
+    /** Why it is carved out rather than fixed at the reader. */
+    reason: string;
+}
+
+export const SETTINGS_CARVE_OUT: readonly CarveOutKey[] = [
+    {
+        key: 'projection.mode',
+        reader: 'src/scripts/install.ts:3409 _resolve_scoped_projection',
+        absentResolvesTo: 'legacy-all',
+        reason:
+            'The template fallback applies only when NO global settings file exists. '
+            + 'Once a file exists, an absent key means legacy-all by documented contract, '
+            + 'so an existing install is never silently narrowed on upgrade.',
+    },
+    {
+        key: 'projection.rule_workspaces',
+        reader: 'src/install/rule_scope.ts:96 ruleScopeFromSettings',
+        absentResolvesTo: 'null — LEGACY_ALL, i.e. every rule ships including maintainer-only ones',
+        reason:
+            'Same upgrade contract as projection.mode, and the failure is louder: '
+            + 'an absent list widens the projection instead of narrowing it.',
+    },
+    {
+        key: 'subagents.auto',
+        reader: 'src/scripts/routing_doctor.ts:206',
+        absentResolvesTo: 'ask',
+        reason:
+            'The reader falls back to `ask` while the template ships `on`. Carved out '
+            + 'rather than fixed at the reader because the doctor reports what the '
+            + 'RESOLVED configuration is; changing its fallback would make the report '
+            + 'disagree with what the other readers actually do.',
+    },
+    {
+        key: 'discipline_profile',
+        reader: 'work_engine/_lib/agent_settings.ts:1263',
+        absentResolvesTo: 'essential, unconditionally',
+        reason:
+            'The template ships `auto`, which resolves to `off` on any measured-null model, '
+            + 'any non-Claude host, and any host exposing no model id. Absent skips that '
+            + 'resolution entirely and loads the essential tier everywhere.',
+    },
+    {
+        key: 'chat_history.frequency',
+        reader: 'src/scripts/chat_history.ts:1140',
+        absentResolvesTo: 'per_phase',
+        reason:
+            'Canonical substitution is `per_turn`. Absent gives coarser capture than the '
+            + 'shipped default — an audit-thinning change, which the class contract\'s own '
+            + 'test 8 (what can the attacker HIDE) names as the severe direction.',
+    },
+    {
+        key: 'profile.id',
+        reader: 'src/scripts/config/profiles.ts:221 resolve_profile',
+        absentResolvesTo:
+            'the id `developer`, but a DEGRADED profile — packs: [], personas: [], hints: []',
+        reason:
+            'Exactly the projection.mode shape: the template default is honoured only when '
+            + 'no settings file exists. With a file present the id resolves but its profile '
+            + 'body does not load, so the install silently loses every pack and persona.',
+    },
+    {
+        key: 'quality.local_auto_run',
+        reader: 'src/scripts/lint_roadmap_ci_steps.ts:106',
+        absentResolvesTo: 'true — which DISABLES the CI-step gate',
+        reason:
+            'Inverted polarity, and the most dangerous row in the set: the template ships '
+            + '`false`, which ARMS the gate. Omitting the key would disarm a quality gate '
+            + 'for every fresh install while the reference page says it is on.',
+    },
+    {
+        key: 'onboarding.onboarded',
+        reader: 'src/scripts/onboarding_gate_hook.ts:99',
+        absentResolvesTo: 'gate skipped, as if onboarding had already completed',
+        reason:
+            'Absent behaves like `onboarded: true`, not like the template default `false`. '
+            + 'Omitting it would skip the onboarding gate on precisely the fresh installs '
+            + 'the gate exists for.',
+    },
+    {
+        key: 'chat_history.enabled',
+        reader: 'src/scripts/chat_history.ts:1025 _read_chat_history_enabled',
+        absentResolvesTo: 'false',
+        reason:
+            'The reader falls back to false while the template ships true. This one is '
+            + 'privacy-shaped: fixing the reader would start recording history for every '
+            + 'install whose file lacks the key. Writing it explicitly keeps the decision '
+            + 'visible in the file the user can read.',
+    },
+];
+
+/** Just the paths — the emitter iterates these against the template. */
+export function carveOutKeys(): readonly string[] {
+    return SETTINGS_CARVE_OUT.map((c) => c.key);
+}
+
+/**
+ * `projection.*` is additionally stripped from the user-global layer by
+ * `load_agent_settings`'s `MERGEABLE_KEYS` whitelist, so `_globalRuleScope`
+ * (`src/server/routes/install.ts:234`) resolves LEGACY_ALL whether or not the
+ * key is written. That is a pre-existing defect, independent of sparseness —
+ * widening the whitelist requires an ADR, per its own comment — and the
+ * carve-out neither causes nor fixes it. Recorded so the next reader of this
+ * module does not mistake the carve-out for a fix.
+ */
+export const KNOWN_UNFIXED_BY_CARVE_OUT =
+    'src/server/routes/install.ts:234 _globalRuleScope — MERGEABLE_KEYS strips projection.*; needs an ADR.';

package/src/shared/settingsConsent.ts

@@ -0,0 +1,136 @@
+/**
+ * Is a permissive B-class value a RECORDED CONSENT, or just a value?
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`, and the answer to that
+ * roadmap's Risk 3 — *"the provenance stamp becomes decoration; an unread stamp
+ * is cost with no return"*. Before this module the sidecar
+ * `settings/.agent-settings.provenance.json` was written by `settings:set` and
+ * read by exactly one caller, the GUI, to **display** it. Nothing decided
+ * anything on it. This is the reader that makes it load-bearing.
+ *
+ * The distinction it draws, which a bare value cannot: `true` that a human chose
+ * and `true` that the machine inferred are the same byte and are not the same
+ * permission. `auto-detected` is the provenance a machine writes about itself —
+ * a locale, an installed binary, a detected host. Letting it grant a consent
+ * would mean the agent could arrive at its own permission by observing the
+ * world, which is the confused-deputy shape in miniature.
+ *
+ * Modelled on `src/scripts/hooks/block_unauthorized_git.ts`: answer from a
+ * recorded fact rather than from the model's recollection, and treat a missing
+ * record as NOT granted rather than as probably-fine.
+ *
+ * WHAT THIS IS NOT. It is not a hook and it does not intercept anything. No
+ * B-class key currently gates an action through a guard — the two that gate
+ * behaviour at all (`personal.open_edited_files`, `memory.learn_on_session_end`)
+ * are read as values by the installer, the wizard and one session_end concern,
+ * and the *action* they govern is prose. So the enforcement gradient is honest
+ * and steep: this function is deterministic, the obligation to call it is
+ * model-carried, and on a prose-only host ask-once can degrade to ask-never.
+ *
+ * Pure — no I/O. Callers supply the value and the sidecar entry.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+
+import { isConservativeDefault, type SettingsClass } from './settingsClasses.js';
+
+/** The provenance vocabulary `settings:set` writes. Mirrors its own enum. */
+export type ConsentSource = 'auto-detected' | 'jit-answer' | 'manual' | 'gui';
+
+/**
+ * The sources that can carry a human decision.
+ *
+ * `jit-answer` is a question the user answered. `gui` is a human at the settings
+ * editor. `manual` is a hand-edit or an explicit CLI write on the user's
+ * instruction. `auto-detected` is excluded on purpose — see the module header.
+ */
+const HUMAN_SOURCES: readonly ConsentSource[] = ['jit-answer', 'gui', 'manual'];
+
+export type ConsentVerdict =
+    /** A human decided, and the value permits the action. */
+    | 'granted'
+    /** The value is the conservative default — absent and no are the same thing. */
+    | 'withheld-default'
+    /** Permissive, but nothing records who decided it. Fail closed. */
+    | 'withheld-unrecorded'
+    /** Permissive and recorded, but recorded as a machine inference. */
+    | 'withheld-machine-inferred'
+    /** Not a consent question at all: A needs none, C is human-only. */
+    | 'not-a-consent-key';
+
+export interface ConsentQuery {
+    /** The key's class, from the contract — `undefined` means unclassified. */
+    cls: SettingsClass | undefined;
+    /** The effective value after normal resolution. */
+    value: unknown;
+    /**
+     * The sidecar entry for this key, or `undefined` when none exists.
+     *
+     * `undefined` covers both "the sidecar has no row" and "there is no sidecar",
+     * which are the same fact from here: nothing records a decision.
+     */
+    source?: ConsentSource | undefined;
+    /**
+     * `true` when the value came from a file only a human can write — a
+     * project-local `.agent-settings.yml` or a hand-edited user file.
+     *
+     * The class contract is explicit that *"the user may edit anything in their
+     * own file with an editor"*, so a hand-edit IS the consent even though it
+     * carries no stamp. Without this the check would refuse the one path the
+     * contract guarantees, which is how a fence becomes a bug.
+     */
+    handEdited?: boolean;
+}
+
+/**
+ * The verdict for one consent-gated action.
+ *
+ * Order matters: class first (a C key never reaches a consent question at all),
+ * then the value (conservative means no, regardless of provenance), then the
+ * record.
+ */
+export function consentVerdict(query: ConsentQuery): ConsentVerdict {
+    if (query.cls !== 'B') {
+        return 'not-a-consent-key';
+    }
+    if (isConservativeDefault(query.value)) {
+        return 'withheld-default';
+    }
+    if (query.handEdited === true) {
+        return 'granted';
+    }
+    if (query.source === undefined) {
+        return 'withheld-unrecorded';
+    }
+    if (!HUMAN_SOURCES.includes(query.source)) {
+        return 'withheld-machine-inferred';
+    }
+    return 'granted';
+}
+
+/** `true` only for `granted` — every other verdict withholds. */
+export function consentGranted(query: ConsentQuery): boolean {
+    return consentVerdict(query) === 'granted';
+}
+
+/**
+ * One line explaining a withheld verdict, for the surface that refused.
+ *
+ * `null` for `granted`, so a caller cannot accidentally print a refusal reason
+ * on the allow path.
+ */
+export function withheldReason(verdict: ConsentVerdict, key: string): string | null {
+    switch (verdict) {
+        case 'granted':
+            return null;
+        case 'withheld-default':
+            return `${key} is at its conservative default — absent and no are the same answer.`;
+        case 'withheld-unrecorded':
+            return `${key} permits this, but nothing records who decided it. Ask, or set it via the GUI.`;
+        case 'withheld-machine-inferred':
+            return `${key} was auto-detected, not decided. A machine inference is not a consent.`;
+        case 'not-a-consent-key':
+            return `${key} is not a class-B consent key — this gate does not apply to it.`;
+    }
+}

package/src/shared/settingsSurface.ts

@@ -84,7 +84,13 @@ function unwrapRef(root: JsonSchemaNode): JsonSchemaNode {
 export function flattenSurface(schema: JsonSchemaNode, version: string): SettingsSurface {
     const entries: Record<string, SurfaceEntry> = {};
     const walk = (node: JsonSchemaNode, prefix: string): void => {
-        if (node.type === 'object' && node.properties !== undefined) {
+        // `properties: {}` — a free-form map such as `z.object({}).passthrough()` —
+        // is a LEAF, per this function's own contract above. Recursing on the
+        // mere presence of the key walked zero children and emitted nothing, so
+        // the key vanished from the surface: `subagents.host_capabilities` was
+        // classified in the settings contract, present in the template, and
+        // absent from every snapshot and upgrade delta.
+        if (node.type === 'object' && node.properties !== undefined && Object.keys(node.properties).length > 0) {
             for (const key of Object.keys(node.properties).sort()) {
                 const child = node.properties[key] as JsonSchemaNode;
                 walk(child, prefix === '' ? key : `${prefix}.${key}`);