@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/settings_removed_keys.ts

@@ -0,0 +1,173 @@
+/**
+ * The registry of DELETED settings keys, and the once-per-run notice a leftover
+ * value gets. Extracted from `agent_settings.ts`, which sits at the 1500-line
+ * source ceiling — every retirement batch adds entries here, and here they cost
+ * no ratchet. `agent_settings.ts` re-exports `REMOVED_KEYS` so existing
+ * importers (the loader, `lint_settings_classes`) are unchanged.
+ */
+
+type SettingsDict = Record<string, unknown>;
+
+/**
+ * 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 behavior, so `off` became the hardcoded rule and
+ * the switch went. What decides instead is the user's own sentence in the chat.
+ *
+ * The 2026-10-09 batch (road-to-settings-classes-derivable-surface-stagnation
+ * Phase 2) is a fourth doctrine: `derivable` keys whose shipped default is the
+ * only behavior the package supports. Each WAS read — by code or by rule and
+ * command prose — and every reader was rewritten to state the old default as
+ * fixed behavior in the same change, so retiring the key changes no effective
+ * default; what a consumer who had set a non-default value loses is named by
+ * the reason.
+ *
+ * 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_time_toggles decides whether the rule ships'],
+    ['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'],
+    // 2026-10-09 — output and tone
+    ['personal.minimal_output', 'direct-answers Iron Law 3 mandates terse replies; there is no verbose mode'],
+    ['personal.play_by_play', 'direct-answers: no narration unless the user asks for it in the turn'],
+    ['personal.pr_comment_bot_icon', 'no-decorative-emojis-in-git-surfaces forbids the 🤖 prefix'],
+    ['verbosity.intent_announcements', 'direct-answers: act and emit the result, no "Let me…" openers'],
+    ['verbosity.preview_artifacts', 'generated content is used directly; preview-on-error and the Iron-Law gates decide when a preview shows'],
+    ['verbosity.routine_confirmations', 'the no-cheap-questions Pre-Send Self-Check; Iron-Law gates always ask'],
+    ['verbosity.post_action_reports', 'direct-answers Iron Law 3: a one-line confirmation and one end-summary'],
+    ['telegraph.speak', 'the telegraph-speak predicate in compile_time_toggles.ts; the bench verdict is package-level (ADR telegraph/0002)'],
+    ['tokens.rich_skills', "the skill's own token_budget_class: rich plus the lint_token_budget_discipline ceiling"],
+    // 2026-10-09 — reasoning protocol switches
+    ['reasoning.auto_gate', 'the RDP gate task signal plus the host self-assessment in rdp-gate.md'],
+    ['reasoning.components.orchestrator', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.notes_first', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.grounding', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.intent', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.complexity_first', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.verifier_default', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.prediction_tracking', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.decision_ledger', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    ['reasoning.components.uncertainty_budget', 'the RDP gate task and host signals decide per component; reasoning.enabled stays the hard off'],
+    // 2026-10-09 — roadmap cadence
+    ['roadmap.skip_pre_run_gate', 'the command name names the scope; only an ambiguous roadmap or an unresolvable conflict shows the gate'],
+    ['roadmap.dashboard_regen_cadence', 'a fixed cadence: every 5th closed step, every phase boundary, reply end and any file-shape touch'],
+    // 2026-10-09 — command suggestion and PR creation
+    ['commands.auto_detect', "an orchestrator's own auto_detect front-matter and the --no-auto-detect flag"],
+    ['commands.suggestion.enabled', 'the suggester match-score floor and cooldown; /command-suggestion-off silences one conversation'],
+    ['commands.suggestion.confidence_floor', "the suggester's fixed 0.6 floor; a command's own suggestion frontmatter can tighten it"],
+    ['commands.suggestion.cooldown_seconds', "the suggester's fixed 600-second cooldown; a command's own suggestion frontmatter can lengthen it"],
+    ['commands.suggestion.max_options', 'the fixed cap of 4 suggestions plus the always-present as-is option'],
+    ['commands.create_pr.api_examples', "/create-pr's grounding rule: an example only from a real source, otherwise a one-line pointer"],
+    ['commands.create_pr.ui_paths', "/create-pr's light frontend heuristic, which fails open"],
+    ['commands.create_pr.api_paths', "/create-pr's light API-endpoint heuristic, which fails open"],
+    // 2026-10-09 — memory and knowledge sharing
+    ['memory.cadence', 'a fixed cadence: the memory line renders whenever a memory type was asked; memory.visibility: off still silences it'],
+    ['memory.review_threshold', "/memory load's fixed preview threshold of 10 unreviewed intake signals"],
+    ['knowledge.global_sharing.redaction.enabled', 'the write-time redaction scan, which always runs before a card goes global'],
+    ['knowledge.global_sharing.redaction.halt_on_trigger', 'the redaction gate, which always halts on a confidential-pattern hit'],
+    ['knowledge.global_sharing.auto_promote_threshold', 'the fixed two-repo sighting count that triggers a promotion suggestion'],
+    ['knowledge.global_sharing.freshness.hypothesis_after_days', "the card's age over last_verified against the fixed 90-day lead-only window"],
+    ['knowledge.global_sharing.freshness.stale_after_days', "the card's age over last_verified against the fixed 180-day skip window"],
+    // 2026-10-09 — hooks and engine
+    ['hooks.concern_budget.max_per_event', "the concern-budget gate's own constant of 8 per (platform, event) cell"],
+    ['hooks.concern_budget.hard_fail', "the concern-budget gate's --strict argv; without it the gate warns"],
+    ['decision_engine.surface_traces', 'nothing: the per-phase decision trace stays off, the old default'],
+    ['decision_engine.on_block_fallback', 'the fail-safe: an on_block ask that times out always stops'],
+    ['explain.enable_last', 'the presence of a work-state trace; explain last always renders it'],
+    // 2026-10-09 — remaining
+    ['project.pr_template', '/create-pr, which reads .github/pull_request_template.md'],
+    ['pipelines.skill_improvement', 'the skill-improvement-trigger rule; the capture is a proposal the user confirms'],
+    ['consistency.cross_source', 'the cross-source-consistency rule, always on; batching and the no-cheap-questions floor bound the noise'],
+    ['subagents.downshift', 'the model_tier each sub-task declares; downshift is always on'],
+    ['ai_team.suppress_setup_hint', 'nothing: the one-line team-mode setup hint is always shown'],
+]);
+
+/** 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 _readDotted(root: SettingsDict, dotted: string): unknown {
+    let node: unknown = 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.
+ */
+export function warnRemovedKeys(merged: SettingsDict): void {
+    for (const [key, reason] of REMOVED_KEYS) {
+        if (_warnedRemovedKeys.has(key)) {
+            continue;
+        }
+        if (_readDotted(merged, key) === undefined) {
+            continue;
+        }
+        _warnedRemovedKeys.add(key);
+        process.stderr.write(`${key} was removed (${reason}); ignored.\n`);
+    }
+}

package/src/scripts/_lib/skill_origin.ts

@@ -0,0 +1,254 @@
+/**
+ * Who put a ranked skill on disk, and whether its body has been looked at.
+ *
+ * SPLIT OUT OF `neighbour_census.ts` FOR ONE CONCRETE REASON. The ranker
+ * (`skill_tools/score_skill_relevance`) needs these primitives, and the ranker
+ * runs inside the shared hook bundle on `user_prompt_submit`. The census module
+ * reaches the host-hook merger, the secret detector and the install-ownership
+ * reader; every byte of that would be inlined into one bundle that every concern
+ * loads on every dispatch, under a ceiling `check_hook_bundle_composition` holds.
+ * So the primitives live here, importing only the manifest reader, and the census
+ * re-exports them — one definition, two call sites, no second module graph.
+ *
+ * ORIGIN IS READ FROM A CLAIM RECORD, NEVER INFERRED FROM A ROOT. The temptation
+ * is to call `~/.claude/skills` foreign and the workspace ours. That is wrong in
+ * both directions: `agent-config install` writes this package's own skills into
+ * the host-global root, and a consumer's hand-written skills sit in the project
+ * root. The one artifact that records what this package actually wrote is the
+ * installed-tools manifest, so the manifest is the authority and the root is only
+ * a tie-break between the two NON-package labels.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { manifest_path } from './installed_tools.js';
+
+/**
+ * Where a RANKED skill came from — a question about AUTHORSHIP.
+ *
+ * Deliberately not the census's `origin` id segment, which is WHERE a file was
+ * found (`project`, `user`, `cursor`, …). Location does not answer authorship in
+ * either direction, which is the whole reason this type exists beside that one.
+ *
+ * `home` is spelled `home` rather than the census's `user` because this value is
+ * printed on a ROUTE LINE beside a skill name, where it has to read as a place a
+ * reader can go and look.
+ */
+export type SkillOrigin = 'package' | 'project' | 'home';
+
+/** One `compat` label per neighbour skill. Order decided in {@link classifyCompat}. */
+export type Compat = 'shadowed' | 'overlapping' | 'unscanned' | 'unclassified';
+
+/** The authored source tree, relative to a maintainer checkout's root. */
+export const AUTHORED_SKILL_ROOT = path.join('src', 'skills');
+
+/** Where the scan verdicts the ranker reads are written, relative to the root. */
+export const SCAN_CACHE_RELATIVE = path.join('agents', 'reports', 'neighbour-scan.json');
+
+/** Default scan-cache path for a project root. */
+export function scanCachePath(projectRoot: string): string {
+    return path.join(projectRoot, SCAN_CACHE_RELATIVE);
+}
+
+/**
+ * What a route line prints: bare for ours, `origin:name` for a neighbour.
+ *
+ * One function, so the ranker, the census and every report agree on the
+ * spelling. Two spellings of one name is how a collision stops being visible,
+ * which is the defect this whole step exists to close.
+ */
+export function qualifiedSkillName(name: string, origin: SkillOrigin): string {
+    return origin === 'package' ? name : `${origin}:${name}`;
+}
+
+/** Split a qualified name back apart. A bare name resolves to `package`. */
+export function splitQualifiedName(qualified: string): { origin: SkillOrigin; name: string } {
+    const m = /^(project|home):([\s\S]*)$/.exec(qualified);
+    if (m) return { origin: m[1] as SkillOrigin, name: m[2] as string };
+    return { origin: 'package', name: qualified };
+}
+
+/**
+ * Every absolute path this package's installed-tools manifest claims, or `null`
+ * when there is no manifest to claim anything.
+ *
+ * `null` and an empty set are different answers and callers must keep them
+ * apart. An empty set means the manifest was read and claims nothing; `null`
+ * means nothing recorded a claim at all, which is a tree that has never run an
+ * install — this repository, for one.
+ *
+ * WHY THIS PARSES THE MANIFEST ITSELF, which is a thing to justify rather than
+ * do quietly. Three readers of this file already exist and none answers this
+ * question at a cost this path can pay. `installed_tools.read_manifest` drops
+ * the nested `tools[].files[]` rows by design — its own header says so, and
+ * those rows are the entire input here. `install_drift.collect_drift` and
+ * `recordedOwnership.readRecordedHashes` both parse the YAML directly FOR THAT
+ * REASON, so parsing it directly is the established answer rather than a new
+ * idea; what is new is the fourth question — the PATHS only, with no sha, no
+ * tool grouping and no hash map. `readRecordedHashes` would have answered it
+ * and was measured costing 1,706 bytes of the shared hook bundle, which is the
+ * budget this whole module was split out to protect. The `~` expansion below is
+ * the same one all three use.
+ */
+export function packageClaimedPaths(projectRoot: string): ReadonlySet<string> | null {
+    const manifest = manifest_path(projectRoot);
+    let doc: unknown;
+    try {
+        doc = parseYaml(fs.readFileSync(manifest, 'utf-8'), { version: '1.1' });
+    } catch {
+        // Unreadable and absent are the same answer: nothing recorded a claim.
+        return null;
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return null;
+    const tools = (doc as Record<string, unknown>)['tools'];
+    const out = new Set<string>();
+    if (!Array.isArray(tools)) return out;
+    for (const tool of tools) {
+        if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) continue;
+        const files = (tool as Record<string, unknown>)['files'];
+        if (!Array.isArray(files)) continue;
+        for (const entry of files) {
+            if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+            const raw = (entry as Record<string, unknown>)['path'];
+            if (typeof raw !== 'string' || raw === '') continue;
+            out.add(path.resolve(projectRoot, _expanduser(raw)));
+        }
+    }
+    return out;
+}
+
+/** Expand a leading `~`, matching the three sibling manifest readers. */
+function _expanduser(p: string): string {
+    if (p === '~') return os.homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+
+export interface SkillOriginOptions {
+    /** Pre-read claim set, to avoid a second manifest read. `null` = no manifest. */
+    claims?: ReadonlySet<string> | null;
+    /** Maintainer checkout root whose `src/skills` is the authored tree. */
+    packageRoot?: string;
+}
+
+/**
+ * Resolve one `SKILL.md` path to the origin of the skill it defines.
+ *
+ * NO CLAIM RECORD MEANS NO QUALIFIER. With no manifest, nothing on disk carries
+ * evidence that any skill is foreign, so everything resolves to `package`, the
+ * ranker qualifies nothing, and its output is exactly what it was before this
+ * function existed. That is deliberate rather than a gap being tolerated: a
+ * `home:` prefix asserted without a claim record is a guess printed in the shape
+ * of a fact, and a reader cannot tell the two apart. The cost is stated rather
+ * than hidden — where no manifest exists a foreign skill is invisible here, and
+ * the thing that fixes it is running an install, not loosening this rule.
+ *
+ * The authored tree is the one exception, and it is a construction rather than a
+ * guess: `<root>/src/skills` exists only in a maintainer checkout of THIS
+ * package and holds its source of truth, so nothing foreign can be under it.
+ */
+export function makeSkillOriginResolver(
+    projectRoot: string,
+    opts: SkillOriginOptions = {},
+): (skillMdPath: string) => SkillOrigin {
+    const claims = opts.claims !== undefined ? opts.claims : packageClaimedPaths(projectRoot);
+    const root = path.resolve(projectRoot);
+    const authored = path.join(path.resolve(opts.packageRoot ?? projectRoot), AUTHORED_SKILL_ROOT);
+    const under = (abs: string, dir: string): boolean =>
+        abs === dir || abs.startsWith(dir + path.sep);
+    return (skillMdPath: string): SkillOrigin => {
+        const abs = path.resolve(skillMdPath);
+        if (under(abs, authored)) return 'package';
+        if (claims === null) return 'package';
+        if (claims.has(abs)) return 'package';
+        return under(abs, root) ? 'project' : 'home';
+    };
+}
+
+/**
+ * The one label, and the order it is decided in.
+ *
+ *   `unscanned`    — the shape scan refused the body. FIRST, because an overlap
+ *                    score is derived FROM a body this census declined to read,
+ *                    and publishing it would be the refusal cancelling itself.
+ *   `shadowed`     — one of ours carries the same bare name. Name-derived, so it
+ *                    stays true under `unscanned`; it loses the slot only
+ *                    because `unscanned` is the stronger call to action.
+ *   `overlapping`  — content similarity against one of ours at or above the
+ *                    threshold `audit_skill_overlap` already calibrates.
+ *   `unclassified` — none of the above fired. Not a clearance.
+ */
+export function classifyCompat(args: {
+    unscanned: string | null;
+    shadows: readonly string[];
+    overlaps: readonly string[];
+}): Compat {
+    if (args.unscanned !== null) return 'unscanned';
+    if (args.shadows.length > 0) return 'shadowed';
+    if (args.overlaps.length > 0) return 'overlapping';
+    return 'unclassified';
+}
+
+/** One recorded scan verdict. `unscanned` is `null` when every shape passed. */
+export interface ScanRecord {
+    qualified: string;
+    digest: string;
+    unscanned: string | null;
+}
+
+export interface ScanCache {
+    schema_version: 1;
+    entries: ScanRecord[];
+}
+
+/** Read the scan cache, or `null` when it is absent or unreadable. */
+export function readScanCache(file: string): ScanCache | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    const entries = (parsed as Record<string, unknown>)['entries'];
+    if (!Array.isArray(entries)) return null;
+    return { schema_version: 1, entries: entries as ScanRecord[] };
+}
+
+/** sha256 of a file's bytes, or `null` when it cannot be read. */
+export function fileDigest(file: string): string | null {
+    try {
+        return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Whether a neighbour body may be indexed, and why not when it may not.
+ *
+ * THREE REFUSALS, REPORTED SEPARATELY, because they ask the maintainer for three
+ * different things: run the census, re-run it, or read the finding. A missing
+ * record is a refusal and not a pass — a gate that passes on missing evidence is
+ * satisfied by deleting the evidence, which is the opposite of a floor. The
+ * digest compare is what "a changed digest rescans first" means from the reading
+ * side: a body edited after its scan is unscanned again until the census runs.
+ */
+export function scanVerdict(
+    cache: ScanCache | null,
+    qualified: string,
+    digest: string | null,
+): { ok: true } | { ok: false; kind: string } {
+    if (cache === null) return { ok: false, kind: 'no-scan-record' };
+    const rec = cache.entries.find((e) => e.qualified === qualified);
+    if (rec === undefined) return { ok: false, kind: 'no-scan-record' };
+    if (digest === null || rec.digest !== digest) return { ok: false, kind: 'digest-changed' };
+    if (rec.unscanned !== null) return { ok: false, kind: rec.unscanned };
+    return { ok: true };
+}

package/src/scripts/_lib/structured_ask.ts

@@ -15,45 +15,74 @@
  *
  * What is observed, and what is a shape guess — the line is drawn explicitly.
  *
- * `STRUCTURED_ASK_SHAPES` is **empty**. No host in this repository's registry
- * carries an observed structured-ask tool, so there is no per-host tool name to
- * match on, and inventing one from a vendor's documentation is exactly what
- * `host-capability-manifest.md` § Observation protocol forbids.
+ * `STRUCTURED_ASK_SHAPES` carries **one** row, for `claude`, written from an
+ * observation under `host-capability-manifest.md` § Observation protocol —
+ * 48 `AskUserQuestion` `tool_use` blocks across host versions 2.1.252 to
+ * 2.1.284, 2026-09-01 to 2026-10-02. Artifact:
+ * `agents/evidence/analysis/structured-ask-host-observation-2026-10.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artifact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ * Every other host has no row, which is "never looked", and inventing one from
+ * a vendor's documentation is exactly what that protocol forbids.
  *
- * `STRUCTURED_ASK_TOOL_NAME_RE` is therefore a **name-shape pattern, not a host
- * fact**. It exists so that if such a tool ever appears in a transcript, the
- * probe MEASURES it rather than missing it — and so the number it reports today
- * (zero) is a measurement rather than an absence of instrumentation. A reader
- * must not read a match as evidence that a named host ships that tool; the only
- * thing that establishes that is an observation written into
+ * `STRUCTURED_ASK_TOOL_NAME_RE` is a **name-shape pattern, not a host fact**,
+ * and stays one even now that a host fact exists beside it: the pattern is what
+ * every caller passing no host id still matches on. It exists so that a picker
+ * appearing in a transcript is MEASURED rather than missed. A reader must not
+ * read a match as evidence that a named host ships that tool; the only thing
+ * that establishes that is an observation written into
  * `STRUCTURED_ASK_SHAPES` with the protocol's four-part citation.
  *
- * Consequence, stated rather than discovered later: `native` is expected to be
- * **0** on every corpus this repo can scan today. That is the honest reading of
- * a capability nobody has observed, not a broken detector.
+ * Consequence, stated rather than discovered later: `native` is **0** on every
+ * corpus this repo can scan today — and the 2026-10 observation does NOT change
+ * that, which is worth stating because it looks like it should.
+ * `probe_unblocked_ask` partitions hand-back ask turns, and a picker call is
+ * answered by a `tool_result` rather than by a free user turn, so it was never
+ * in that probe's denominator. The zero means "no prose hand-back used a picker
+ * instead"; it never meant "no picker exists".
+ *
+ * That makes the zero DEFINITIONAL for this probe, not a measurement of
+ * scarcity, and the earlier wording claimed the opposite on both halves: it
+ * called the zero a measurement, and attributed it to the capability being
+ * unobserved. The capability is observed and the zero is unchanged, which is
+ * the cleanest available proof that the two were never connected.
  */
 
 /** The per-host shape of a structured-ask tool, once one has been OBSERVED. */
 export interface StructuredAskShape {
     /** The tool name as it appears in a transcript's `tool_use` block. */
     readonly tool: string;
-    /** How many questions one call may carry. `1` is the shape this repo wants. */
+    /**
+     * The largest question count OBSERVED in one call, never a host ceiling the
+     * host was asked for and refused. `1` is also the shape this repo wants.
+     */
     readonly max_questions: number;
-    /** How many options one question may offer. */
+    /** The largest option count OBSERVED on one question — same caveat. */
     readonly max_options_per_question: number;
-    /** Whether the host's picker admits a free-text answer alongside the options. */
+    /**
+     * Whether the host's picker admits a free-text answer alongside the options.
+     * The WEAKEST of the four to establish, because it is read by negation — an
+     * answer carrying none of the offered labels. A cancelled ask looks the same
+     * from the outside, so a `true` here is "observed at least once", never a
+     * count. The citing artifact carries the per-row basis.
+     */
     readonly free_text: boolean;
 }
 
 /**
  * Observed per-host structured-ask shapes.
  *
- * EMPTY, deliberately. A row is written only from an observation in a real
- * session under `contexts/execution/host-capability-manifest.md` § Observation
- * protocol — host · host version · transcript reference · date. Never from a
- * host's documentation, and never by analogy to another host.
+ * A row is written only from an observation in a real session under
+ * `contexts/execution/host-capability-manifest.md` § Observation protocol —
+ * host · host version · transcript reference · date. Never from a host's
+ * documentation, and never by analogy to another host.
+ *
+ * `claude`'s row is the first, and the two numeric fields are **observed
+ * maxima over 48 calls, not host ceilings**: no call carried two questions, so
+ * the host was never asked to accept two. The guard's threshold does not rest
+ * on them — one question per call is this repo's own rule either way.
  */
-export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {};
+export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {
+    claude: { tool: 'AskUserQuestion', max_questions: 1, max_options_per_question: 4, free_text: true },
+};
 
 /** The observed shape for `hostId`, or `undefined` when none has been observed. */
 export function structuredAskShape(
@@ -77,6 +106,20 @@ export const STRUCTURED_ASK_TOOL_NAME_RE = /^(ask[_-]?user[_-]?question|user[_-]
  * An observed per-host shape wins outright — that is a fact about the host. The
  * name-shape pattern is the fallback, and it is why the probe can report a
  * measured zero instead of nothing at all.
+ *
+ * KNOWN ASYMMETRY, named rather than left for the next reader to hit. With a
+ * row present, this returns `name === shape.tool`: ONE observed name becomes an
+ * exclusive allowlist, so every other picker name is answered `false` on that
+ * host — a universal negative from a single positive observation, which is the
+ * shape of inference the observation protocol refuses elsewhere. It is left as
+ * it is because the alternative (union of the row and the pattern) would make
+ * an observed row buy nothing, and because no caller is affected today. There
+ * are TWO production callers, both host-blind, enumerated rather than recalled:
+ * `hooks/one_question_per_ask_hook.ts:103` and `probe_unblocked_ask.ts:184`,
+ * each calling `isStructuredAskTool(name)` with no second argument. A caller
+ * that does start passing one inherits the asymmetry, and
+ * `tests/scripts/ask_surface.test.ts` pins it so the inheritance is visible
+ * rather than silent.
  */
 export function isStructuredAskTool(name: string, hostId?: string | null): boolean {
     const shape = structuredAskShape(hostId);

package/src/scripts/_lib/test_red_state.ts

@@ -10,6 +10,11 @@
  * This module is that emission, so the registry entry moves in the same change
  * rather than being left describing a gap that closed.
  *
+ * DATED 2026-10-06. The emission exists and is tested, but nothing calls it:
+ * this writer has no production caller, so the registry row was corrected back
+ * to `degraded` the same day. The caller belongs to the stub that owns it —
+ * whoever lands it sets the row back to `available`.
+ *
  * WHAT IT IS NOT. It is not a test runner, and it does not decide whether a
  * failure is a legitimate RED. The failure CLASSES belong to the TDD skill
  * (`src/skills/test-driven-development/SKILL.md`, Test-Red row) and this module