@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/_cli/cmd_settings_check.ts

@@ -50,6 +50,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as path from 'node:path';
 
 import { parse as _rtParse } from '../sync_yaml_rt.js';
+import { GIT_CONVENTION_KEYS, fileSource, readGitConventionKey } from '../_lib/git_convention.js';
 
 const DEFAULT_PATH = '.agent-settings.yml';
 
@@ -203,7 +204,8 @@ const _PRESCAN_RULES: readonly PrescanRule[] = [
 ];
 
 interface Finding {
-    line: number;
+    /** null when no single line can be named, printed as `line:-`. */
+    line: number | null;
     kind: string;
     verdict: string;
     hint: string;
@@ -254,9 +256,53 @@ function _scan_text(text: string): Finding[] {
     return findings;
 }
 
+/**
+ * The schema enum and the branch-pattern alphabet, through the same reader
+ * `git:convention show` and `sync_pr_branch` use, so a value those refuse
+ * fails here first.
+ */
+function _git_convention_findings(target: string, text: string): Finding[] {
+    const findings: Finding[] = [];
+    const lines = _splitlines(text);
+    for (const key of GIT_CONVENTION_KEYS) {
+        const reading = readGitConventionKey(key, fileSource({ developer: [target] }), {});
+        if (reading.state !== 'invalid' && reading.state !== 'malformed') continue;
+        // `malformed` is a fact about the whole file, so it is one finding, not one per key.
+        if (reading.state === 'malformed') {
+            if (!findings.some((f) => f.verdict === 'malformed')) {
+                findings.push({ line: null, kind: 'git.*', verdict: 'malformed', hint: reading.detail ?? reading.state });
+            }
+            continue;
+        }
+        findings.push({
+            line: _gitKeyLine(lines, key),
+            kind: `git.${key}`,
+            verdict: reading.state,
+            hint: reading.detail ?? reading.state,
+        });
+    }
+    return findings;
+}
+
+/**
+ * The 1-based line of `key` inside a block-style `git:` section, or null: a
+ * same-named key elsewhere is not it, and an inline `git:` value has no line
+ * of its own to name.
+ */
+function _gitKeyLine(lines: readonly string[], key: string): number | null {
+    const start = lines.findIndex((l) => /^git\s*:\s*(#.*)?$/.test(l));
+    if (start === -1) return null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i] as string;
+        if (/^\S/.test(l) && !l.startsWith('#')) return null;
+        if (new RegExp(`^\\s+${key}\\s*:`).test(l)) return i + 1;
+    }
+    return null;
+}
+
 function _format(finding: Finding): string {
     return (
-        `  ❌  line:${_ljust(String(finding.line), 4)}  ` +
+        `  ❌  line:${_ljust(finding.line === null ? '-' : String(finding.line), 4)}  ` +
         `${_ljust(finding.kind, 22)}  ${_ljust(finding.verdict, 14)}  ${finding.hint}`
     );
 }
@@ -370,7 +416,13 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
         }
     }
 
-    if (findings.length === 0) {
+    // A parser finding already reports a file that does not parse; a `malformed`
+    // git reading would only repeat it. A pre-scan finding is not a parse
+    // failure, so it hides nothing.
+    const unparsed = findings.some((f) => f.kind === 'parser');
+    const git = _git_convention_findings(target, text).filter((f) => !(unparsed && f.verdict === 'malformed'));
+
+    if (findings.length === 0 && git.length === 0) {
         if (!opts.quiet) {
             _print(
                 out,
@@ -380,12 +432,18 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
         }
         return 0;
     }
-    _print(err, `❌  ${target}: ${findings.length} finding(s) outside the supported subset.`);
-    for (const finding of findings) {
-        _print(err, _format(finding));
+    if (findings.length > 0) {
+        _print(err, `❌  ${target}: ${findings.length} finding(s) outside the supported subset.`);
+        for (const finding of findings) _print(err, _format(finding));
+        _print(err, '');
+        _print(err, '    Contract: docs/contracts/settings-sync-yaml-subset.md');
+    }
+    if (git.length > 0) {
+        _print(err, `❌  ${target}: ${git.length} git.* value(s) the convention refuses.`);
+        for (const finding of git) _print(err, _format(finding));
+        _print(err, '');
+        _print(err, '    Contract: docs/decisions/ADR-283-git-convention-carrier.md (the git section of agent-settings.schema.json)');
     }
-    _print(err, '');
-    _print(err, '    Contract: docs/contracts/settings-sync-yaml-subset.md');
     return 1;
 }
 

package/src/scripts/_cli/cmd_settings_get.ts

@@ -48,6 +48,7 @@ import {
     iter_setting_overrides,
     load_agent_settings,
     MERGEABLE_KEYS,
+    settings_layer_states,
     user_global_settings_paths,
     USER_GLOBAL_FILENAME,
 } from '../_lib/agent_settings.js';
@@ -179,7 +180,7 @@ export function missionResolutionFor(
  * file the user actually edited — telling somebody their value was dropped
  * without telling them which file it was dropped from is half an answer.
  */
-export function userGlobalDrop(key: string): { dropped: boolean; file: string } {
+export function userGlobalDrop(key: string, templateDefault?: unknown): { dropped: boolean; file: string } {
     // Probe EVERY user-global layer the loader reads, not just the flat file.
     // `user_global_settings_paths()` returns the flat `agent-settings.yml` AND
     // the canonical `settings/.agent-settings.yml` the setup wizard writes, and
@@ -200,7 +201,13 @@ export function userGlobalDrop(key: string): { dropped: boolean; file: string }
         } catch {
             continue;
         }
-        if (getSettingsLeaf(raw, key) !== undefined) return { dropped: true, file: candidate };
+        const value = getSettingsLeaf(raw, key);
+        if (value === undefined) continue;
+        // `upgrade` inserts template defaults into the user-global file, so a
+        // dropped default is not something the user set and loses nothing. A
+        // lower layer can still hold a value the user did set.
+        if (templateDefault !== undefined && JSON.stringify(value) === JSON.stringify(templateDefault)) continue;
+        return { dropped: true, file: candidate };
     }
     return { dropped: false, file };
 }
@@ -234,8 +241,16 @@ export function runSettingsGet(opts: SettingsGetOptions): SettingsGetResult {
     const cls = _classFor(opts.packageRoot, opts.key);
     const fallback = templateDefault(opts.packageRoot, opts.key);
     const carveOut = carveOutFor(opts.key);
-    const drop = userGlobalDrop(opts.key);
+    const drop = userGlobalDrop(opts.key, fallback);
     const mission = missionResolutionFor(opts.key, merged);
+    // The loader reads a layer that does not parse as absent, so "not set" can
+    // be false; the exit code stays 0 because the read itself still answered.
+    const malformed = settings_layer_states({ cwd: opts.cwd }).filter((l) => l.state === 'malformed');
+    if (malformed.length > 0) {
+        err.push(
+            `⚠️  settings:get: ${malformed.map((l) => l.path).join(', ')} does not parse; every value it sets is read as absent.`,
+        );
+    }
 
     if (opts.json) {
         out.push(

package/src/scripts/_cli/doctor_execution.ts

@@ -19,6 +19,7 @@ import {
     resolveExecutionPosture,
 } from '../../shared/missionExecution.js';
 import {
+    UNREAD_FORGE,
     forgeProtectionRows,
     protectionActions,
     type ForgeReading,
@@ -81,7 +82,11 @@ export function executionJson(overrides: () => OverrideStream): Dict {
  * `actions` carries the human ACTION lines — the step's own words are that a
  * missing row is a blocker entry and NOT a halt, so this reports and returns.
  */
-export function forgeProtectionJson(reading: ForgeReading, repo: string | null = null): Dict {
+export function forgeProtectionJson(
+    reading: ForgeReading,
+    repo: string | null = null,
+    not_checked: NotCheckedReason = null,
+): Dict {
     const rows = forgeProtectionRows(reading);
     const readFromForge = rows.some((r) => r.state !== 'unread');
     // **The slug is reported only when something was actually read, and that
@@ -107,6 +112,11 @@ export function forgeProtectionJson(reading: ForgeReading, repo: string | null =
         })),
         actions: protectionActions(rows).map(name),
         read_from_forge: readFromForge,
+        // Present on every run, `null` when the read happened. A key that
+        // appeared only on the skipped path would make its absence carry the
+        // meaning, and absence is exactly what a schema-validating consumer
+        // reads as "this build does not report it".
+        not_checked,
     };
 }
 
@@ -147,6 +157,64 @@ export interface ForgeDeps {
     readonly env?: Readonly<Record<string, string | undefined>>;
     /** The subprocess runner for both `git` and `gh`. */
     readonly run?: Runner;
+    /**
+     * Skip the read before anything spawns. The block keeps its shape: five
+     * `unread` rows, exactly what a failed read produces.
+     */
+    readonly offline?: boolean;
+    /**
+     * WHY the read was skipped, or `null` when it happened.
+     *
+     * Five `unread` rows and no failures is what "everything is fine" looks
+     * like to a consumer summing row states, so `read_from_forge: false` alone
+     * did not carry the distinction. This names it, which is the condition the
+     * council attached to making offline the default.
+     */
+    readonly not_checked?: NotCheckedReason;
+}
+
+/**
+ * Why a `doctor` run did not read the forge. `null` means it did.
+ *
+ * Three reasons rather than a boolean, because the repairs differ: pass
+ * `--online`, drop `--no-forge`, or run without `--check`.
+ */
+export type NotCheckedReason = 'online_not_requested' | 'offline_flag' | 'single_check' | null;
+
+/**
+ * Whether a `doctor` run reads the forge — and why not, when it does not.
+ *
+ * **OFFLINE IS THE DEFAULT since 2026-10-09.** Blocker
+ * `doctor-network-default` of `road-to-findings-that-get-a-disposition`,
+ * option (a): AI council 2026-10-07 (anthropic + openai, 2/2), adopted
+ * 2026-10-08 under the owner's delegation of council-decidable questions. The
+ * recorded reasoning is that a health command reaching the network on every
+ * run — including a single-check run — is the surprising default, and that
+ * `--online` costs one word to anyone who wants the read.
+ *
+ * Phase 3.1 shipped the opt-OUT and this function's earlier header said the
+ * default "is an owner decision, so this function does not decide it". That is
+ * now decided, and the header says so rather than leaving the next reader to
+ * infer it from the expression.
+ *
+ * Precedence is narrowest-first, so the reason names the repair: a `--check`
+ * run reads no forge row at all, an explicit `--no-forge` beats `--online`
+ * because it is the more specific instruction, and the bare default is last.
+ */
+export function forgeDepsFor(opts: {
+    readonly online?: boolean;
+    readonly no_forge?: boolean;
+    readonly check: string | null;
+}): ForgeDeps {
+    const not_checked: NotCheckedReason =
+        opts.check !== null
+            ? 'single_check'
+            : opts.no_forge === true
+              ? 'offline_flag'
+              : opts.online === true
+                ? null
+                : 'online_not_requested';
+    return { offline: not_checked !== null, not_checked };
 }
 
 export function forgeProtectionJsonFor(root: string, deps: ForgeDeps = {}): Dict {
@@ -155,6 +223,9 @@ export function forgeProtectionJsonFor(root: string, deps: ForgeDeps = {}): Dict
     // binding were asserted one layer down against fakes while a regression in
     // the real wiring stayed invisible. `deps` is that seam; production passes
     // nothing and gets `process.env` plus the real spawn.
+    if (deps.offline === true) {
+        return forgeProtectionJson(UNREAD_FORGE, null, deps.not_checked ?? null);
+    }
     const env = deps.env ?? process.env;
     const run = deps.run;
     const remaining = budgetOf(FORGE_TOTAL_BUDGET_MS);

package/src/scripts/_dispatch.bash

@@ -283,6 +283,36 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   settings:get               Read one setting: its value, the file it came from, its
                              class, and whether "absent" differs from the default.
                              Usage: settings:get <key> [--json]
+  git:convention             The git convention (git.commit_format, git.branch_pattern,
+                             git.update_strategy): value in force, source and state
+                             (valid|absent|malformed|invalid|discarded|unresolvable),
+                             read from a committed .git-convention.yml over the
+                             settings files; this checkout's differing value is shown
+                             as a candidate, and any repository commit-message
+                             validator that also runs at commit. Exit 1 when a key in
+                             force is malformed, invalid, discarded or unresolvable;
+                             a candidate in one of these states is a warning, exit 0.
+                             --key limits show to the named keys (repeatable).
+                             update_strategy is read at --base, else the default
+                             branch: a pull request passes --base origin/<its base>.
+                             subject checks subjects on stdin against the convention in
+                             force; ticket reads the ticket out of a branch name; branch
+                             renders a name from git.branch_pattern; measure proposes
+                             a convention from the history (subject family, branch
+                             pattern, observed update style) and writes nothing;
+                             init --yes creates .git-convention.yml once on the
+                             user's yes (never over one, never committed);
+                             show and subject print "no convention established" when
+                             no declaration, approved card or commitlint config exists; sync brings the
+                             branch up to --base (else the default branch) per
+                             git.update_strategy (exit 1 base unresolved, 3 behind
+                             under rebase, 4 strategy unreadable).
+                             Usage: git:convention show [--json] [--base REF] [--key K]
+                                    git:convention subject [--format F|--family F]
+                                    git:convention ticket [BRANCH] [--keys K]
+                                    git:convention branch --slug S [--type T] [--ticket K]
+                                    git:convention measure [--limit N] [--family F]
+                                    git:convention sync [--base REF] [--dry-run]
   settings:set               Set one setting in the global file. Refuses every class-C
                              (guarded) key from docs/contracts/settings-classes.md, and
                              refuses everything when that contract is unreadable.
@@ -362,9 +392,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
                              Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/
   onboarding-gate:hook       Hook entry point (drains stdin)
-                             Writes .augment/state/onboarding-gate.json from .agent-settings.yml
+                             Writes agents/state/onboarding-gate.json from .agent-settings.yml
   context-hygiene:hook       PostToolUse hook entry point (read JSON from stdin)
-                             Maintains .augment/state/context-hygiene.json (turn count, loop, freshness)
+                             Maintains agents/state/context-hygiene.json (turn count, loop, freshness)
   dispatch:hook              Universal hook dispatcher (Phase 7, hook-architecture-v1.md)
                              Usage: dispatch:hook --platform <name> --event <event> [--native-event <native>]
                              Reads scripts/hook_manifest.yaml and runs the resolved concern chain.
@@ -796,6 +826,10 @@ cmd_settings_get() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_settings_get.ts" "$@"
 }
 
+cmd_git_convention() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_git_convention.ts" "$@"
+}
+
 cmd_mcp_available() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_mcp_available.ts" "$@"
 }
@@ -1561,6 +1595,7 @@ main() {
     session:recycle)         cmd_session_recycle "$@" ;;
     packs:active)            cmd_packs_active "$@" ;;
     settings:get)            cmd_settings_get "$@" ;;
+    git:convention)          cmd_git_convention "$@" ;;
     mcp:available)           cmd_mcp_available "$@" ;;
     brand:status)            cmd_brand_status "$@" ;;
     roadmap:context)         cmd_roadmap_context "$@" ;;

package/src/scripts/_lib/agent_settings.ts

@@ -49,11 +49,13 @@ import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { resolvePackageRoot } from './package_root.js';
 
 import * as user_global_paths from './user_global_paths.js';
 import { carveOutKeys } from '../../shared/settingsCarveOut.js';
 import { applyRenamedKeys } from './settings_renamed_keys.js';
+import { warnRemovedKeys } from './settings_removed_keys.js';
+export { REMOVED_KEYS } from './settings_removed_keys.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -264,13 +266,13 @@ function _resolve_user_global_file(): string {
  * the user-global file. Adding a key requires an ADR.
  */
 export const MERGEABLE_KEYS: readonly string[] = [
-    // `name`, `ide` and `personal.bot_icon` are the PRE-MIGRATION spellings.
-    // `install.ts` migrates `ide` → `personal.ide` and `pr_comment_bot_icon`
-    // into its `personal.` home, and this list was never moved with them — so
-    // the whitelist named keys the template does not have while the keys it
-    // does have were filtered out silently. A user setting either preference
-    // user-globally got no error, no warning, and no effect
-    // (road-to-capability-answerability 4.3, ADR-219).
+    // `name` and `ide` are the PRE-MIGRATION spellings. `install.ts` migrates
+    // `ide` → `personal.ide`, and this list was never moved with it — so the
+    // whitelist named a key the template does not have while the key it does
+    // have was filtered out silently (road-to-capability-answerability 4.3,
+    // ADR-219). `personal.bot_icon` / `personal.pr_comment_bot_icon` left with
+    // the key itself (2026-10-09): a whitelisted key nothing reads would carry a
+    // user-global value into a tree that ignores it.
     //
     // Both spellings are listed rather than replaced: a legacy file that still
     // uses the old name keeps working, and nothing that resolved before
@@ -280,20 +282,12 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'ide',
     'personal.ide',
     'rule_loading_tier',
-    'memory.cadence',
-    'personal.bot_icon',
-    'personal.pr_comment_bot_icon',
     'personal.autonomy',
     // Knowledge-card global cross-project sharing is a USER-GLOBAL setting
     // (ADR-100 / road-to-structure-grounding-v2). Whitelisted so the
     // ~/.event4u/agent-config/agent-settings.yml values are honoured.
     'knowledge.global_sharing.enabled',
     'knowledge.global_sharing.allowed_tiers',
-    'knowledge.global_sharing.redaction.enabled',
-    'knowledge.global_sharing.redaction.halt_on_trigger',
-    'knowledge.global_sharing.auto_promote_threshold',
-    'knowledge.global_sharing.freshness.hypothesis_after_days',
-    'knowledge.global_sharing.freshness.stale_after_days',
     // `design.fidelity_mode` is a per-DEVELOPER working preference, not a
     // per-project one: whether an agent may deviate from a handed-over design
     // is a property of how that person works, and a designer who sets it once
@@ -322,11 +316,11 @@ export const MERGEABLE_KEYS: readonly string[] = [
 const TEMPLATE_RELATIVE = path.join('src', 'config', 'agent-settings.template.yml');
 
 /**
- * Package root: `src/scripts/_lib/agent_settings.ts` → three levels up.
- * Same idiom as `cli_wrapper.ts:28`, and it holds in an installed consumer
- * too because `src/config/` ships (`package.json` `files[]`).
+ * Package root, anchored on the package marker rather than on hop counts: this
+ * module is also inlined into `dist/cli-delegate/`, two levels below the root,
+ * where three hops land outside the package and every default is lost.
  */
-const _PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const _PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 /** Default template path — overridable per call for tests. */
 export function default_template_path(): string {
@@ -975,114 +969,11 @@ export function load_agent_settings(
             _deep_merge(merged, layer);
         }
     }
-    _warn_removed_always_on_keys(merged);
+    warnRemovedKeys(merged);
     return merged;
 }
 
 
-/**
- * Settings keys this package has DELETED. A leftover value from an older
- * install is ignored — never applied by any reader — and surfaced with ONE
- * deprecation line per key per process run (stderr; the exit code never
- * changes).
- *
- * The map carries a per-key REASON rather than one shared sentence, because
- * the list now spans more than one deletion doctrine and a single blanket
- * phrase would mis-attribute every future entry. A reader who hits the line
- * should learn why the key went, not just that it did.
- *
- * `subagents.*` — the always-on-orchestration doctrine
- * (road-to-always-on-orchestration Phase 1): the layer has no per-layer
- * on/off setting any more. `ai_team.enabled` joined in Step 1.3 — the
- * `/team` family's availability is a codex-CLI/auth FACT
- * (`src/scripts/ai_team/availability.ts`), not a flag; the `ai_team` config
- * loader (`src/scripts/ai_team/config.ts`) separately accepts a leftover
- * `enabled` key without failing closed, so this warning is the only surfaced
- * signal of that deletion.
- *
- * `hooks.turn_end_gate.*` — the turn-end gate is always armed (2026-08-12).
- * A default-off safety gate cannot soak, so the switch protecting the soak
- * made the soak impossible; whether the gate fires is now decided by each
- * detector's own trigger conditions. See `turn_end_gate_hook.ts` § "Always
- * armed".
- *
- * The five `derivable` leaves below (2026-08-12, road-to-zero-settings Phase
- * 2.1) are a different case from every entry above them, and the difference is
- * the whole safety argument: no code path ever *consulted* them. Each appeared
- * in the template, the schema and the reference page, and several in the setup
- * wizard, while the decision they looked like they governed was taken
- * elsewhere. A key nothing reads cannot change a default by leaving — so this
- * is the one deletion batch that needs no replacement mechanism, only the
- * per-key statement of what already decides.
- *
- * A sixth unread key, `screenshots.data_bearing_gate`, was found in the same
- * pass and deliberately NOT deleted — it is `consent`, and the open question is
- * whether the repair is to build its missing reader or to delete a promise a
- * Hard Floor can never honour. See `settings-classes.md` § The six unread keys.
- *
- * `worktrees.mode` (2026-08-13, ADR-229) is a third doctrine again: not
- * always-on, not unread. It WAS read, and the reader honoured all three values —
- * the deletion says the decision was never the agent's to make. `ask` bought a
- * round trip per spawn, `on` let the agent start parallel work unprompted, and
- * `off` described the wanted behaviour, so `off` became the hardcoded rule and
- * the switch went. What decides instead is the user's own sentence in the chat.
- *
- * Every reason string must name what decides INSTEAD, never just "removed".
- * Exported so `lint_settings_classes` can check the deletion side of the
- * surface: a reason that names no replacement, or an entry whose key is live in
- * the template again, is a contradiction the loader itself cannot notice.
- */
-export const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
-    ['subagents.enabled', 'always-on orchestration'],
-    ['subagents.auto', 'always-on orchestration'],
-    ['subagents.host_capabilities', 'always-on orchestration'],
-    ['subagents.budget_routing', 'always-on orchestration'],
-    ['ai_team.enabled', 'always-on orchestration'],
-    ['hooks.turn_end_gate.enabled', 'the turn-end gate is always armed'],
-    ['hooks.turn_end_gate.promissory', 'the turn-end gate is always armed'],
-    ['hooks.turn_end_gate.language', 'the turn-end gate is always armed'],
-    ['hooks.turn_end_gate.verification', 'the turn-end gate is always armed'],
-    ['telegraph.speak_scope', 'the rule body states its own scope; compile_router gates on telegraph.speak alone'],
-    ['chat_history.max_size_kb', 'the rotate command takes --max-kb from argv; session-count pruning bounds the file'],
-    ['chat_history.on_overflow', 'the overflow mode comes from the rotate command --mode argv'],
-    ['quality.wait_for_remote_ci', 'whether to poll follows from the push plus a detectable remote pipeline'],
-    ['legal_review_prep.consented_at', 'the provenance sidecar settings:set writes and consentVerdict reads'],
-    ['worktrees.mode', 'the user asking for a worktree in the chat; creation is instruction-only and hardcoded'],
-]);
-
-/** Keys already warned about in THIS process — the "once per run" dedupe. */
-const _warnedRemovedKeys = new Set<string>();
-
-/** Read one dotted path out of a merged settings tree; `undefined` when absent. */
-function _readDottedSettingsPath(root: SettingsDict, dotted: string): SettingsValue {
-    let node: SettingsValue = root;
-    for (const part of dotted.split('.')) {
-        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
-            return undefined;
-        }
-        node = (node as SettingsDict)[part];
-    }
-    return node;
-}
-
-/**
- * Warn once per process, on stderr, for every {@link REMOVED_KEYS} entry still
- * present in a resolved settings tree. Never throws, never changes what the
- * caller does with `merged` — a pure notification side effect.
- */
-function _warn_removed_always_on_keys(merged: SettingsDict): void {
-    for (const [key, reason] of REMOVED_KEYS) {
-        if (_warnedRemovedKeys.has(key)) {
-            continue;
-        }
-        if (_readDottedSettingsPath(merged, key) === undefined) {
-            continue;
-        }
-        _warnedRemovedKeys.add(key);
-        process.stderr.write(`${key} was removed (${reason}); ignored.\n`);
-    }
-}
-
 /**
  * Return the merged `modules:` configuration with defaults applied.
  *

package/src/scripts/_lib/blocked_by_marker.ts

@@ -50,7 +50,7 @@ export interface BlockedByMarker {
  * unreadable, which is a migration, not a fix.
  */
 export const BLOCKED_BY_MARKER_RE =
-    /<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[—-][ \t]*([^>]*?))?[ \t]*)?-->/i;
+    /<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+(?:#[a-z0-9-]+)?)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[—-][ \t]*([^>]*?))?[ \t]*)?-->/i;
 
 /** Parse one marker, or `null` when the text carries none. */
 export function parseBlockedByMarker(text: string): BlockedByMarker | null {

package/src/scripts/_lib/compile_time_toggles.ts

@@ -14,8 +14,8 @@
  * as "project instructions", never having consulted the router.
  *
  * Two surfaces, one switch. Sharing the definition is what lets the projector honour
- * it, so `speak: false` means what the ADR assumed instead of the ADR being weakened
- * to match a partial implementation.
+ * it, so dormancy means what the ADR assumed instead of the ADR being weakened to
+ * match a partial implementation.
  */
 
 /**
@@ -51,25 +51,16 @@ export type ToggleSettings = Record<string, unknown>;
 /** rule-id → predicate. A rule is emitted (router AND projection) only when its
  * predicate returns true. A rule absent from this map is always emitted. */
 export const COMPILE_TIME_TOGGLES: Record<string, (s: ToggleSettings) => boolean> = {
-    // `speak` defaults FALSE (dormant) per docs/adrs/telegraph/0002 — the absent-key
-    // fallback used to be `true`, which silently contradicted ADR 0001 (accepted,
-    // "default off until bench"). Measured basis: median vs_terse −9.27% (API) /
-    // −5.47% (exact cl100k_base) — telegraph emits MORE than a plain "be terse".
-    // Opt back in with an explicit `telegraph.speak: true` once an output-side bench
-    // clears the kill-criterion bar. `enabled` keeps its true default: it is the
-    // family master switch, and flipping it would silence sibling telegraph settings
-    // that were never measured negative.
-    //
-    // The predicate gates on `telegraph.speak` because that is the only lever that
-    // removes the rule's ~982-token body from the router and the projection. A knob
-    // that merely narrowed the grammar at runtime would leave the token cost in place
-    // — the trap the measurement exposed.
-    'telegraph-speak': (s: ToggleSettings): boolean => {
-        const tg = (s['telegraph'] as ToggleSettings | undefined) ?? {};
-        const enabled = tg['enabled'] === undefined ? true : tg['enabled'];
-        const speak = tg['speak'] === undefined ? false : tg['speak'];
-        return Boolean(enabled) && Boolean(speak);
-    },
+    // DORMANT, unconditionally. `speak` defaulted FALSE per docs/adrs/telegraph/0002
+    // (measured basis: median vs_terse −9.27% API / −5.47% exact cl100k_base —
+    // telegraph emits MORE than a plain "be terse"), and on 2026-10-09 the
+    // `telegraph.speak` key was retired with that default as the fixed value
+    // (road-to-settings-classes-derivable-surface-stagnation Phase 2.1). Whether
+    // the rule ships is the kill-criterion bench verdict, a package-level decision
+    // rather than a per-install one, so re-enabling it is a change to this
+    // predicate, made when an output-side bench clears the bar — never a setting.
+    // A leftover `telegraph.speak: true` is warned about by the loader and ignored.
+    'telegraph-speak': (): boolean => false,
 };
 
 /** True when the rule may be emitted. Unknown ids are always emitted — the map is an