@event4u/agent-config 9.22.0 → 9.24.0

package/dist/shared/settingsClasses.js

@@ -0,0 +1,191 @@
+/**
+ * Settings A/B/C classes — the pure half.
+ *
+ * `docs/contracts/settings-classes.md` is the single source: one markdown table
+ * row per template leaf, each carrying the class that decides **who may write
+ * that key**. This module parses that table and nothing else. There is
+ * deliberately no generated JSON twin — a second machine-readable copy is a
+ * second thing to drift, and the whole point of the contract is that the fence
+ * and the prose explaining it cannot disagree.
+ *
+ * Pure module — no I/O. Consumed by the lint (`src/scripts/lint_settings_classes.ts`),
+ * the `settings set` writer, and the Fastify settings route, so all three
+ * refuse the same keys for the same reason.
+ *
+ * @see docs/contracts/settings-classes.md
+ */
+/** The closed class vocabulary. A row outside it is a defect, not a new class. */
+export const SETTINGS_CLASSES = ['A', 'B', 'C'];
+export function isSettingsClass(value) {
+    return SETTINGS_CLASSES.includes(value);
+}
+/**
+ * `| \`some.key\` | C | \`false\` | why |` → one row.
+ *
+ * The class column is what separates the key table from the prose tables above
+ * it, several of which also open with a backticked key. A second cell that is
+ * not a single bare letter is not a key row.
+ */
+const ROW_RE = /^\|\s*`([^`]+)`\s*\|\s*([^|]*?)\s*\|/;
+export function parseSettingsClassRows(markdown) {
+    const rows = [];
+    const lines = markdown.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = ROW_RE.exec(lines[i] ?? '');
+        if (m === null) {
+            continue;
+        }
+        const key = m[1] ?? '';
+        const cls = m[2] ?? '';
+        if (!/^[A-Za-z]$/.test(cls)) {
+            continue;
+        }
+        rows.push({ key, cls, line: i + 1 });
+    }
+    return rows;
+}
+/** `| A — preference | 27 |` and `| **Total** | **140** |` → the declared tallies. */
+export function parseDeclaredClassCounts(markdown) {
+    const read = (re) => {
+        const m = re.exec(markdown);
+        const raw = m?.[1];
+        return raw === undefined ? null : Number.parseInt(raw, 10);
+    };
+    return {
+        A: read(/^\|\s*A\s+—\s+preference\s*\|\s*(\d+)\s*\|/m),
+        B: read(/^\|\s*B\s+—\s+consent\s*\|\s*(\d+)\s*\|/m),
+        C: read(/^\|\s*C\s+—\s+guarded\s*\|\s*(\d+)\s*\|/m),
+        total: read(/^\|\s*\*\*Total\*\*\s*\|\s*\*\*(\d+)\*\*\s*\|/m),
+    };
+}
+/**
+ * Dotted key → class, for the rows whose class is valid.
+ *
+ * A row with an unparseable class is DROPPED rather than defaulted, so a
+ * caller asking "may I write this?" gets `undefined` — which every caller
+ * treats as refuse. A typo in the contract must never widen the fence.
+ */
+export function buildSettingsClassIndex(rows) {
+    const index = new Map();
+    for (const row of rows) {
+        if (!isSettingsClass(row.cls) || index.has(row.key)) {
+            continue;
+        }
+        index.set(row.key, row.cls);
+    }
+    return index;
+}
+/**
+ * Conservative-default test for class B (half one of the B invariant).
+ *
+ * A sparse settings file means absent = default. A B key whose default is the
+ * permissive value makes "never asked" indistinguishable from "answered yes",
+ * which turns the ask into decoration on a decision already taken in the
+ * user's name. These are the values that cannot carry a permission.
+ *
+ * Half two of the invariant — that the ask fires on the user's own request and
+ * never at a moment the agent chose — is prose in the contract, not code. No
+ * gate can read the agent's reason for picking a moment.
+ */
+export function isConservativeDefault(value) {
+    if (value === null || value === false || value === '' || value === 0) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+/**
+ * Dotted leaf paths of a parsed settings tree.
+ *
+ * A leaf is anything that is not a NON-EMPTY map. An empty map is a real
+ * configurable value with a real default (`subagents.host_capabilities: {}`),
+ * so it is a leaf — one more than the template↔schema parity walk produces.
+ * That divergence is deliberate: a key the parity walk skips is exactly the
+ * key that would otherwise reach the writer with no class.
+ */
+export function settingsLeafPaths(value, prefix = '') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return [prefix];
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return [prefix];
+    }
+    return entries.flatMap(([k, v]) => settingsLeafPaths(v, prefix === '' ? k : `${prefix}.${k}`));
+}
+/** Read one dotted path out of a parsed settings tree; `undefined` when absent. */
+export function getSettingsLeaf(root, dotted) {
+    let node = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+            return undefined;
+        }
+        node = node[part];
+    }
+    return node;
+}
+/**
+ * The class governing a dotted path, walking to the nearest classified ancestor.
+ *
+ * An exact row wins. Failing that, the longest classified prefix does: a
+ * class-C key whose value is a MAP has children that never appear in a flattened
+ * diff under the key's own name, so `subagents.host_capabilities.subagent_spawn`
+ * must inherit the C on `subagents.host_capabilities` rather than read as
+ * unclassified. Returns `undefined` when nothing on the path is classified —
+ * and every caller treats that as guarded, not as free.
+ */
+export function classOfPath(index, dotted) {
+    const exact = index.get(dotted);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const parts = dotted.split('.');
+    for (let end = parts.length - 1; end > 0; end--) {
+        const ancestor = index.get(parts.slice(0, end).join('.'));
+        if (ancestor !== undefined) {
+            return ancestor;
+        }
+    }
+    return undefined;
+}
+/** Absent / null / empty-scalar — the three spellings of "not set" in a settings file. */
+export function isUnsetSettingValue(value) {
+    return value === undefined || value === null || value === '';
+}
+/**
+ * The changed paths a human must confirm before the write lands.
+ *
+ * Extracted from the Fastify write route so the fail-closed branch is testable
+ * without booting a server around it. That branch is the one a single inverted
+ * operator turns into a fail-OPEN, and a gate whose most dangerous line has no
+ * test is a gate that passes review once and rots after.
+ *
+ * `classes === null` means the contract could not be read. Every changed key is
+ * then guarded: unverifiable is not the same as unguarded. With a contract in
+ * hand, a key is guarded when its nearest classified ancestor is C, and ALSO
+ * when nothing on its path is classified at all — the same per-key refusal the
+ * CLI writer applies.
+ *
+ * Pairs where both sides are unset are dropped first: a key written as `null`
+ * reads back as `''` through the comment-preserving merge, and a confirmation
+ * that appears on every save is one nobody reads.
+ */
+export function guardedChangedKeys(classes, changed) {
+    return changed
+        .filter((c) => !(isUnsetSettingValue(c.from) && isUnsetSettingValue(c.to)))
+        .map((c) => c.path)
+        .filter((key) => {
+        if (classes === null) {
+            return true;
+        }
+        const cls = classOfPath(classes, key);
+        return cls === 'C' || cls === undefined;
+    })
+        .sort();
+}
+//# sourceMappingURL=settingsClasses.js.map

package/dist/shared/settingsClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsClasses.js","sourceRoot":"","sources":["../../src/shared/settingsClasses.ts"],"names":[],"mappings":"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"}

package/docs/contracts/settings-classes.md

@@ -0,0 +1,342 @@
+# Settings classes — A / B / C
+
+> Every leaf key in `src/config/agent-settings.template.yml` carries exactly one
+> class. The class answers ONE question: **who may write this key.**
+>
+> `src/scripts/lint_settings_classes.ts` fails the build when a template key has
+> no row here, when a row names a key the template does not have, or when a row
+> carries a class outside `A | B | C`. The table below is the single source —
+> there is no second machine-readable copy to drift from it.
+
+Origin: Phase 1 of `road-to-zero-ceremony-settings`. It exists because the
+package is about to grow an agent-writable settings path (`settings set`), and
+an agent-writable path without a fence is an injection surface: anything that
+can reach the model's input can reach a setting, and some of these settings
+raise a spend ceiling, empty an allowlist, or switch off a gate.
+
+## The three classes
+
+| Class | Who may write it | Is the user ever asked? |
+|---|---|---|
+| **A — preference** | the agent (via `settings set`), the GUI, a hand-edit | **never.** It resolves to its default until someone states otherwise. |
+| **B — consent** | the agent, but only after ONE just-in-time ask that the user answered | **once**, then persisted with provenance. |
+| **C — guarded** | the GUI's write route or a hand-edit, by a human | never asked by the agent; **every agent write path refuses it.** |
+
+## What the fence covers — and what it does not
+
+**It governs writes, not reads.** Every class is readable by everything. A C
+class does not hide a value; it refuses to let a non-human change it.
+
+**It governs writes, not asks.** Six settings ship an `ask` value in their own
+enum (`tokens.rich_skills`, `subagents.auto`, `subagents.budget_routing`,
+`subagents.adversarial_council`, `worktrees.mode`, `decision_engine.on_block`).
+Those are C-class here, and that is not a contradiction: the class says who may
+*persist* a new value; the `ask` value says what happens *at runtime* when the
+setting is already set to `ask`. A C-class key set to `ask` still produces a
+runtime question, the answer applies to that run, and persisting it stays on the
+human path.
+
+**It is not a permission model for the user.** The user may edit anything in
+their own file with an editor. C means the *agent* does not do it for them.
+
+## Why "master flag → C" is read narrowly
+
+The roadmap's instruction is *"put every budget-raising key, allow/deny list,
+kill-switch, strict mode, and master flag in C"*. Read literally, "master flag"
+swallows every boolean named `enabled`, and a fence that contains everything
+fences nothing — it just makes the writer useless and pushes the next author to
+carve an exception.
+
+So the rule applied here is the acceptance criterion's own wording — **no key
+with an irreversible or spend-raising effect sits outside C** — expanded into
+eight tests. A key is C when it governs any of:
+
+1. money, tokens, or a quota;
+2. an allow-list or a deny-list;
+3. a gate, a confirmation, or a safety floor;
+4. the agent's own authority, autonomy, or reasoning discipline;
+5. which code runs or which artefacts project into the agent's context;
+6. egress of repository or conversation content;
+7. a credential, an executed binary, or a filesystem path;
+8. audit, observability, or a background safety check — anything that changes
+   what the user can later **see** about what the agent did.
+
+Test 8 came out of the council review below, and it is the only one that looks
+backwards. Tests 1–7 ask *what can the attacker do*; test 8 asks *what can the
+attacker hide*. A settings write that erases the trail is not less severe than
+one that raises a budget — it is the one that makes the other invisible.
+
+`commands.suggestion.enabled` is the worked counter-example: it is a master
+switch, and it is **A**, because switching it off removes no gate, no spend, no
+authority, and no audit trail — it removes a convenience.
+
+## B eligibility — the invariant
+
+```
+A KEY MAY BE CLASS B ONLY IF ITS TEMPLATE DEFAULT IS THE CONSERVATIVE VALUE,
+AND THE ASK FIRES ONLY WHEN THE USER'S OWN REQUEST NEEDS THE SETTING —
+NEVER AT A MOMENT THE AGENT CHOSE.
+```
+
+**Half one — the conservative default.** A sparse settings file means *absent =
+default*. If a B key shipped with the permissive value as its default, then
+"never asked" and "answered yes" would be indistinguishable, and the ask would
+be decoration on a decision already made in the user's name. Under this
+invariant an unanswered B key is always the safe value, and the ask is the only
+path to the permissive one. `lint_settings_classes` enforces this half
+mechanically: a B row whose template default is not `false` / `""` / `0` / `[]`
+/ `null` / `{}` fails the build.
+
+**Half two — who picks the moment.** The council review below found the hole in
+half one: an agent free to choose *when* to ask can engineer consent. Asking
+"may I learn from this session?" straight after solving something painful is
+still a just-in-time ask, and the answer is still coerced. So the trigger must
+be the user's own request arriving at a point where the setting is genuinely
+required — the user asked for an edit, so `personal.open_edited_files` is asked;
+the user ended the session, so `memory.learn_on_session_end` is asked. A
+threshold the agent watched, a moment it judged favourable, or a convenient lull
+are not triggers. This half is **prose, not lint** — no gate can read the
+agent's reason for choosing a moment, and claiming otherwise would be the
+coverage inflation this repository's gate discipline exists to refuse.
+
+That invariant is why B is small — **three keys**. It is not a placeholder for a
+larger set; it is the set that passes both halves.
+
+| Key | Why a just-in-time ask is the right shape | Conservative default |
+|---|---|---|
+| `personal.open_edited_files` | it starts running the binary named in `personal.ide` on every edit — the user should say yes once before that begins | `false` |
+| `personal.canary_name` | un-inferrable, and answering arms the session-degradation canary; one keypress to accept the prefill | `""` (canary dark) |
+| `memory.learn_on_session_end` | it turns on automatic memory writes at the end of every session — a standing write the user should authorise | `false` |
+
+## Counts
+
+| Class | Keys |
+|---|---|
+| A — preference | 27 |
+| B — consent | 3 |
+| C — guarded | 110 |
+| **Total** | **140** |
+
+The total is every leaf in the template, where *leaf* means anything that is not
+a **non-empty** map. An empty map (`subagents.host_capabilities: {}`) is a real
+configurable value with a real default, so it is a leaf here — one row more than
+the template↔schema parity test walks, deliberately, because a key with no
+class is exactly what this contract exists to prevent.
+
+`secrets.link_encryption_key` is commented out in the template and therefore has
+no row. It is a credential; were it ever uncommented it is C, and the lint would
+demand a row before the build went green.
+
+## The table
+
+Rows follow template order, so a diff against the template reads straight down.
+
+| Key | Class | Default | Why |
+|---|---|---|---|
+| `agent_config_version` | C | `""` | installer-owned pin selecting which package code executes |
+| `profile.id` | C | `developer` | master axis selecting the projected skill and command surface |
+| `projection.mode` | C | `scoped` | governs which artefacts reach the host trees at all |
+| `projection.rule_workspaces` | C | 9 workspaces | allowlist deciding which rules reach the agent |
+| `projection.rule_packs` | C | `[]` | second allowlist axis on rule projection |
+| `discipline_profile` | C | `__DISCIPLINE_PROFILE__` | master switch for the discipline rule tier |
+| `rule_loading_tier` | C | `__RULE_LOADING_TIER__` | legacy master switch for rule loading |
+| `lean_projection.mode` | C | `eager-all` | `thin` removes rule bodies from the agent's context |
+| `telegraph.speak` | C | `false` | ships a rule body; a token-cost lever in both directions |
+| `telegraph.speak_scope` | A | `"off"` | output register once that rule ships |
+| `tokens.rich_skills` | C | `"on"` | token-spend lever |
+| `cost.budgets.daily` | C | `0` | rolling spend ceiling |
+| `cost.budgets.weekly` | C | `0` | rolling spend ceiling |
+| `cost.budgets.monthly` | C | `0` | rolling spend ceiling |
+| `cost.budgets.per_tier.cheap` | C | `null` | per-tier spend ceiling |
+| `cost.budgets.per_tier.medium` | C | `null` | per-tier spend ceiling |
+| `cost.budgets.per_tier.strong` | C | `null` | per-tier spend ceiling |
+| `cost.enforcement` | C | `advisory` | decides whether a breach blocks or is merely logged |
+| `model.auto_switch` | C | `suggest` | authorises native model overrides, which is spend |
+| `personal.ide` | C | `""` | names a binary the agent would execute |
+| `personal.open_edited_files` | B | `false` | starts invoking that binary on every edit |
+| `personal.rtk_installed` | A | `false` | auto-detected machine fact |
+| `personal.minimal_output` | A | `true` | reply-shape preference |
+| `personal.play_by_play` | A | `false` | narration preference |
+| `personal.canary_name` | B | `""` | arms the session-degradation canary |
+| `personal.pr_comment_bot_icon` | A | `false` | comment cosmetics |
+| `personal.pr_progress_comments` | C | `false` | authorises unsolicited outbound comments on a PR |
+| `personal.autonomy` | C | `auto` | suppresses confirmation questions |
+| `personal.user_type` | C | `"__USER_TYPE__"` | master axis filtering the projected surface |
+| `verbosity.intent_announcements` | A | `false` | narration preference |
+| `verbosity.preview_artifacts` | C | `false` | removes pre-action review of commits, PRs, and branches |
+| `verbosity.routine_confirmations` | C | `false` | removes confirmation prompts |
+| `verbosity.offer_council_in_delivery` | A | `false` | offers a paid step; never takes it |
+| `verbosity.post_action_reports` | A | `minimal` | size of a status block |
+| `project.pr_template` | C | `.github/pull_request_template.md` | filesystem path whose contents reach an outbound PR |
+| `project.upstream_repo` | C | `""` | destination of outbound improvement PRs |
+| `project.improvement_pr_branch_prefix` | A | `improve/agent-` | branch-name cosmetics |
+| `github.pr_reply_method` | A | `create_review_comment` | picks between two endpoints of one operation |
+| `augment.rules_use_symlinks` | A | `false` | reversible install mechanics |
+| `eloquent.access_style` | A | `getters_setters` | code convention |
+| `chat_history.enabled` | C | `true` | kill-switch over a path that writes conversation content to disk |
+| `chat_history.frequency` | C | `__CHAT_HISTORY_FREQUENCY__` | capture granularity — a value that reduces what is captured erases the trail |
+| `chat_history.max_size_kb` | C | `__CHAT_HISTORY_MAX_SIZE_KB__` | cap on how much conversation lands on disk |
+| `chat_history.on_overflow` | C | `__CHAT_HISTORY_ON_OVERFLOW__` | decides what survives when the log fills; an audit-integrity choice, not a preference |
+| `chat_history.text_limits.user` | C | `0` | cap on how much user text is written to disk |
+| `chat_history.text_limits.agent` | C | `5000` | cap on how much agent text is written to disk |
+| `chat_history.text_limits.tool` | C | `200` | cap on how much tool payload is written to disk |
+| `chat_history.text_limits.phase` | C | `200` | cap on how much phase text is written to disk |
+| `pipelines.skill_improvement` | A | `true` | proposes a capture; the user still decides |
+| `reasoning.enabled` | C | `true` | master switch for the agent's own reasoning discipline |
+| `reasoning.auto_gate` | C | `true` | decides when that discipline engages |
+| `reasoning.components.orchestrator` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.notes_first` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.grounding` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.intent` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.complexity_first` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.verifier_default` | C | `true` | disabling it removes a verification step |
+| `reasoning.components.prediction_tracking` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.decision_ledger` | C | `true` | a component of the agent's own discipline |
+| `reasoning.components.uncertainty_budget` | C | `true` | a component of the agent's own discipline |
+| `roadmap.skip_pre_run_gate` | C | `true` | disables a pre-run confirmation gate |
+| `roadmap.quality_cadence` | C | `end_of_roadmap` | governs when verification runs |
+| `roadmap.dashboard_regen_cadence` | A | `every_5_steps` | beat of a derived view |
+| `roadmap.horizon_weeks` | C | `0` | a non-zero value relaxes a lint's plate-token ban |
+| `planning.challenge_on_create` | C | `true` | disables the plan-confidence gate |
+| `planning.risk_review` | C | `true` | disables the risk-register validator |
+| `planning.completion_review` | C | `true` | disables the completion-review validator |
+| `quality.local_auto_run` | C | `false` | governs whether local verification runs at all |
+| `quality.wait_for_remote_ci` | C | `false` | governs whether the authoritative gate is waited on |
+| `design.fidelity_mode` | C | `strict` | strict-mode selector, one of whose values is a Hard Floor |
+| `consistency.cross_source` | C | `"on"` | disables the cross-source discrepancy gate |
+| `screenshots.identity_allowlist` | C | `[]` | allowlist of identities that ship unredacted |
+| `screenshots.forbid_terminal_capture` | C | `true` | kill-switch over the highest-leak capture path |
+| `screenshots.data_bearing_gate` | C | `"on"` | the human-confirmation gate over a published egress |
+| `code_style.docblocks` | A | `minimal` | code convention |
+| `subagents.enabled` | C | `true` | kill-switch for the whole subagent layer |
+| `subagents.auto` | C | `"on"` | dispatches work without asking |
+| `subagents.downshift` | C | `true` | routes to another model tier, which is spend and quality |
+| `subagents.budget_routing` | C | `ask` | the budget-aware routing gate |
+| `subagents.quota_arbitrage` | C | `true` | spends from a separate quota pool |
+| `subagents.model_map.lite` | C | `""` | names an external model endpoint |
+| `subagents.model_map.medium` | C | `""` | names an external model endpoint |
+| `subagents.model_map.high` | C | `""` | names an external model endpoint |
+| `subagents.host_capabilities` | C | `{}` | overrides the host capability manifest |
+| `subagents.implementer_model` | C | `""` | names an external model endpoint |
+| `subagents.judge_model` | C | `""` | names an external model endpoint |
+| `subagents.max_parallel` | C | `3` | parallelism cap, and therefore a spend rate |
+| `subagents.adversarial_council` | C | `"off"` | governs a paid verification step |
+| `worktrees.mode` | C | `ask` | standing permission for autonomous worktree creation |
+| `ai_team.enabled` | C | `false` | authorises paid external CLI calls |
+| `ai_team.model` | C | `auto` | names an external model |
+| `ai_team.allow_delegate` | C | `false` | grants an external tool write access to the repository |
+| `ai_team.max_calls_per_day` | C | `50` | quota cap on a shared budget |
+| `ai_team.suppress_setup_hint` | A | `false` | hint cosmetics |
+| `ai_team.review_gate.managed` | C | `false` | governs an upstream review gate |
+| `ai_team.review_gate.max_consecutive_blocks` | C | `3` | circuit-breaker threshold |
+| `onboarding.onboarded` | C | `false` | flipping it bypasses the onboarding gate |
+| `commands.auto_detect` | C | `enabled` | kill-switch for orchestrator auto-detection |
+| `commands.suggestion.enabled` | A | `true` | a convenience layer; governs no gate and no spend |
+| `commands.suggestion.confidence_floor` | A | `0.6` | tuning of that convenience layer |
+| `commands.suggestion.cooldown_seconds` | A | `600` | tuning of that convenience layer |
+| `commands.suggestion.max_options` | A | `4` | tuning of that convenience layer |
+| `commands.suggestion.blocklist` | C | `[]` | a deny-list |
+| `commands.create_pr.preview_description` | C | `false` | removes pre-publish review of an outbound artefact |
+| `commands.create_pr.detail_level` | A | `min` | verbosity of a generated body |
+| `commands.create_pr.api_examples` | A | `true` | verbosity of a generated body |
+| `commands.create_pr.screenshots` | C | `false` | puts captured screenshots into a published PR body |
+| `commands.create_pr.ui_paths` | C | `[]` | glob allowlist |
+| `commands.create_pr.api_paths` | C | `[]` | glob allowlist |
+| `memory.cadence` | C | `always` | suppressing the visibility line hides what the agent learned from the user |
+| `memory.review_threshold` | A | `10` | when a review preview surfaces; governs no gate |
+| `memory.redact_patterns` | C | `[]` | deny-list of secret and PII regexes |
+| `memory.session_index` | A | `"off"` | injects a compact index at session start |
+| `memory.learn_on_session_end` | B | `false` | turns on automatic memory writes at session end |
+| `knowledge.global_sharing.enabled` | C | `true` | kill-switch over cross-project egress |
+| `knowledge.global_sharing.allowed_tiers` | C | `[public]` | allowlist for that egress |
+| `knowledge.global_sharing.redaction.enabled` | C | `true` | disabling it removes the redaction floor |
+| `knowledge.global_sharing.redaction.halt_on_trigger` | C | `true` | disabling it removes halt-and-prompt |
+| `knowledge.global_sharing.auto_promote_threshold` | C | `2` | threshold governing that egress |
+| `knowledge.global_sharing.freshness.hypothesis_after_days` | A | `90` | freshness heuristic on a card already shared |
+| `knowledge.global_sharing.freshness.stale_after_days` | A | `180` | freshness heuristic on a card already shared |
+| `hooks.concern_budget.max_per_event` | C | `8` | budget cap on hook concerns |
+| `hooks.concern_budget.tier1_concerns` | C | `[]` | allowlist of concerns permitted to fail closed |
+| `hooks.concern_budget.hard_fail` | C | `false` | weakens the budget gate to warn-only |
+| `hooks.injection_scan.enabled` | C | `false` | the prompt-injection scanner |
+| `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call |
+| `hooks.design_slop.enabled` | C | `false` | configures code that runs on every tool call |
+| `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call |
+| `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it |
+| `decision_engine.min_confidence` | C | `"off"` | the confidence gate |
+| `decision_engine.block_on_risk` | C | `"off"` | the risk-class gate |
+| `decision_engine.require_memory_hits` | C | `false` | a phase gate |
+| `decision_engine.on_block` | C | `stop` | `warn` advances past a gate that fired |
+| `decision_engine.ask_timeout_seconds` | C | `30` | how long a fired gate waits before falling back |
+| `decision_engine.on_block_fallback` | C | `stop` | fail-safe versus fail-open after that timeout |
+| `update_check.enabled` | C | `true` | a background safety check; disabling it pins the user to known-vulnerable code |
+| `explain.enable_last` | A | `true` | a read-only diagnostics surface |
+| `legal_review_prep.acknowledged` | C | `false` | the consent gate; the safety floor requires the wizard checkbox |
+| `legal_review_prep.consented_at` | C | `""` | the record of that consent |
+| `legal_review_prep.require_council` | C | `true` | a fail-closed defence-in-depth gate |
+
+## The council review of the C list (2026-08-05)
+
+The C list was reviewed by a two-member AI council (`claude-sonnet-4-5`,
+`gpt-4o`), asked one question in one direction only: **name every key
+classified A or B that should be C.** Arguing a C key down to A was explicitly
+out of scope, because over-fencing is not the failure this fence exists to
+prevent. The review ran because completeness is the property a single author is
+worst placed to certify about their own list.
+
+**Converged, and applied — five keys moved A → C:**
+
+| Key | The abuse both members named |
+|---|---|
+| `update_check.enabled` | a background safety check; switching it off pins the user to known-vulnerable code |
+| `chat_history.frequency` | reduces what is captured, so the trail thins |
+| `chat_history.on_overflow` | decides what survives when the log fills |
+| `memory.cadence` | suppresses the line that tells the user what the agent learned |
+| `decision_engine.surface_traces` | the decision engine's own black box |
+
+**Converged, and applied — a missing test.** All five share a shape the original
+seven tests could not express: they do not let an attacker *do* more, they let
+an attacker *hide* what was done. That is now test 8, and it is the one to reach
+for first when classifying a new key, because it is the one the other seven
+cannot cover by analogy.
+
+**Converged, and applied — the B invariant had a hole.** Conservative-default
+alone is satisfiable by an agent that picks a coercive moment to ask. Half two
+of the invariant above is that finding.
+
+**Split, and recorded rather than resolved:** `github.pr_reply_method`. One
+member wanted C ("redirects a communication path"); the other kept A, on the
+concrete ground that both enum values post a comment on the same PR through the
+same API — the worst outcome is a comment of the wrong type, which is visible
+and cosmetic. Kept **A** on the stronger-evidenced side. If that key ever gains
+a value that targets a different destination, it becomes C under test 6 and this
+paragraph is the reason to revisit it.
+
+**Rejected, with the reason:** `pipelines.skill_improvement`, `personal.rtk_installed`,
+`commands.create_pr.api_examples`, and `knowledge.global_sharing.freshness.*`
+were each proposed for C by one member and argued back to A by the other.
+The load-bearing distinctions: an auto-detected fact is not a control surface; a
+tuning knob inside an already-guarded flow is not a second gate; and a boolean
+that says "include examples" is bounded by the C-classed allow-list that decides
+*which* examples. `pipelines.skill_improvement` carries a stated litmus — if its
+approval ever stops being a separate mechanical step and becomes an in-turn
+"ok", it moves to C.
+
+## Adding a key
+
+1. Add it to `src/config/agent-settings.template.yml` and to
+   `src/server/schemas/settings.ts` (the parity test enforces both directions).
+2. Add a row here. The lint fails until you do — that is the point.
+3. If you reach for **B**, check the invariant above first: the template default
+   must be the conservative value.
+4. If you reach for **A**, check it against all eight C tests — test 8 first,
+   because it is the one the other seven cannot cover by analogy. If any of them
+   fires, it is C.
+
+## See also
+
+- [`settings-api.md`](settings-api.md) — the GUI's REST surface; its `PUT` route
+  is the one write path a C-class key may travel.
+- `src/scripts/lint_settings_classes.ts` — the gate.
+- `src/config/agent-settings.template.yml` — the defaults-and-schema source.
+- `tests/server/schemas/parity.test.ts` — the template↔schema parity gate this
+  contract sits beside and never relaxes.

package/docs/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md

@@ -6,7 +6,22 @@ _Origin: migrated from `src/rules/artifact-drafting-protocol.md` per the P4 patt
 
 ## Phase A — Understand
 
-Ask up to **5** clarifying questions (numbered options, each with a
+**Question zero, asked first: should this artifact exist at all?**
+
+Before the five below, put the extend-versus-create question to the user —
+*is there an existing artifact this belongs in?* It used to live in Phase B,
+after the research, and it was measured moving: one source found that the same
+stop placed after work had begun was passed straight through, because mid-build
+momentum beats restraint. A stop that only fires once you are invested is a stop
+that does not fire.
+
+Asking it first costs one question and is answerable without the research: the
+user usually knows whether they are extending something. Phase B still runs the
+overlap scan — that is what turns a guess into a verdict — but it now *confirms
+or overturns* an answer already on the record rather than raising the question
+for the first time at the point where a draft is half-formed.
+
+Ask up to **5** further clarifying questions (numbered options, each with a
 *"skip / I don't know yet"* escape):
 
 1. **Problem** — what does this solve that no existing artifact solves?
@@ -26,13 +41,19 @@ Run the **search protocol** from
 grep with **solution-words AND problem-words**, scan sub-directory
 taxonomies, then **open and skim** the 3 nearest matches. A negative grep
 alone is not proof of no overlap. Report the top 3-5 most-similar
-artifacts and ask (numbered options):
+artifacts and ask (numbered options) — this **confirms or overturns** the
+question-zero answer from Phase A with evidence, rather than raising it for the
+first time:
 
 - Extend an existing one?
 - Create a new one — gap is real?
 - Show overlap first?
 - Promote via `learning-to-rule-or-skill` instead?
 
+A Phase-B verdict that contradicts the Phase-A answer is the useful outcome, not
+an embarrassment: it is the research doing its job. Surface the contradiction
+and let the user re-decide.
+
 Carry the summary into the commit message (*"Reviewed before drafting:
 X, Y"*).