@event4u/agent-config 9.8.0 → 9.10.0

package/src/config/gate-coverage.yml

@@ -0,0 +1,127 @@
+# Gate coverage manifest — the input to `check_gate_coverage.ts`.
+#
+# WHY THIS EXISTS
+# ---------------
+# On 2026-07-29 a sweep found gates that scanned a tree emptied by the ADR-051
+# flat-`src/` migration, reported success, and were wired into CI. One printed
+# `TOTAL | 0 | 0 | 0 | 0%`; another printed "All 0 auto-rule descriptions ≤ 150
+# chars"; a third "clean (0 declarer(s))". Each exited 0. A gate that inspects
+# nothing does not pass — it certifies coverage that does not exist, which is
+# worse than having no gate, because the green is believed.
+#
+# Per-case retargeting does not close this: the next migration recreates it. This
+# manifest plus the guard closes it structurally.
+#
+# THE CONTRACT (three rules, each from a real failure)
+# ----------------------------------------------------
+# 1. MACHINE-READABLE COUNT. Every listed gate emits exactly one line
+#    `scanned: <N>` (stdout or stderr), N = artefacts it actually inspected. The
+#    guard never parses a gate's human output — that would make the guard itself
+#    fragile, and a fragile guard is the thing being replaced.
+#
+# 2. CI-IDENTICAL INVOCATION. `argv` MUST match how CI/Taskfile calls the gate.
+#    A bare probe produced a false alarm during the sweep: `skill_linter` looked
+#    blind when called with no arguments, but CI passes `--all` and it scans 429
+#    artefacts. The guard must reproduce the real call or it invents defects.
+#
+# 3. BASELINE, NOT `> 0`. `min_scanned` is a floor, not a zero-check. A gate that
+#    drops from 428 artefacts to 3 is as broken as one that drops to 0, and `> 0`
+#    cannot see it. Set the floor below the true corpus (room for legitimate
+#    deletions) but far above a collapse.
+#
+# FIELDS
+#   id           script stem under src/scripts/
+#   argv         CI-identical arguments (list; empty list = bare call)
+#   min_scanned  hard floor; guard fails when the reported count is below it
+#   corpus       what the count means — so a future reader can re-derive the floor
+#   status       enforced | pending
+#                pending = not yet emitting `scanned:`. The guard REPORTS these
+#                rather than skipping silently: its own partial coverage must be
+#                visible, or it repeats the sin it exists to catch.
+gates:
+  - id: check_condensation
+    argv: []
+    min_scanned: 380
+    corpus: "src/ ↔ dist/agent-src/ .md pairs (429 at baseline: 111 rules + 318 skills)"
+    status: enforced
+
+  - id: check_augment_description_cap
+    argv: []
+    min_scanned: 80
+    corpus: "auto-type rules carrying a description (98 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree (0 -> 98). It printed
+      "All 0 auto-rule descriptions" and exited 0 in CI. Retargeting surfaced 16
+      real violations (max 189 chars); all 16 were shortened under explicit
+      operator review, with every matching term programmatically verified as
+      preserved. The cap was deliberately NOT raised to fit the violations —
+      letting a gate adapt to the as-is state is the inversion that produced three
+      blind gates in the first place.
+
+  - id: lint_load_context
+    argv: []
+    min_scanned: 180
+    corpus: "md files inspected for a load_context block: src/rules + src/agent-src/contexts + agents/settings/contexts (231 at baseline, 17 declarers)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree: 0 -> 231 files, and it
+      immediately found a real violation the blindness had hidden
+      (src/rules/model-recommendation.md declared `../contexts/…`, a disallowed
+      relative root; normalised to the canonical `contexts/…` the rule's own prose
+      already used). The count is FILES INSPECTED, not declarers — "0 declarers"
+      over 400 files is legitimate, "0 files" is blindness, and reporting declarers
+      would have hidden exactly this dead root. LEGACY_PREFIX was deliberately NOT
+      retargeted: it detects stale pre-relocation entries and must keep
+      pointing at the old form.
+
+  - id: skill_linter
+    argv: ["--all"]
+    min_scanned: 380
+    corpus: "skills + rules under artefact_roots() (429 at baseline)"
+    status: enforced
+    note: >
+      NOT blind — the manifest's regression case for rule 2. The sweep's bare
+      probe made it look blind; `--all` scans 429. Enforced precisely so that
+      changing `argv` to a bare call fails the guard instead of silently
+      reproducing the false alarm.
+
+  - id: check_no_roadmap_refs
+    argv: []
+    min_scanned: 700
+    corpus: "stable artefacts across src/{rules,skills,agent-src/*} + docs/ + agents/settings/contexts (872 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree. It had been enforcing the
+      no-roadmap-references rule for docs/ only while the rule + skill layer went
+      unscanned — 0 -> 872 artefacts. No violation had slipped through (verified),
+      so this closed a latent gap, not a live breach.
+
+  - id: check_context_paths
+    argv: []
+    min_scanned: 900
+    corpus: "reference corpus: src/{rules,skills,agent-src/commands,agent-src/contexts,domains} + agents/roadmaps (1170 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29. An empty reference corpus makes every "unreferenced
+      context" verdict vacuous, which is how the dead root stayed invisible.
+
+  - id: check_site_links
+    argv: []
+    min_scanned: 20
+    unavailable_exit: 2
+    corpus: "built HTML pages under site/dist (25 content sources at baseline)"
+    status: enforced
+    note: >
+      Registered 2026-07-30 after it was caught reporting green over a stale build —
+      6 pages against 25 content sources, every source newer than the newest page.
+      The missing-dist path already exited 2; the stale path did not, so the gate
+      could pass while inspecting a build that did not contain the pages under test.
+      It now exits 2 on stale, and the floor here catches the partial-build case the
+      guard exists for. The lesson of the find is the manifest, not the gate: the
+      guard never flagged this because the gate was never listed. A sibling
+      silent-green found in the same sweep — the per-pack lint matrix, whose path was
+      a double ADR-051 casualty and which exited 0 on an empty match across 17 CI
+      shards — is NOT listed here because it was deleted rather than repaired
+      (skill_linter --all already covers all 429 artefacts in 0.5s).
+

package/src/config/hook-latency-budget.json

@@ -0,0 +1,20 @@
+{
+    "_comment": "Pre-registered hook-latency budget (road-to-credible-install Phase 1). Committed BEFORE the first optimization landed, per the roadmap's pre-registration discipline: the numbers below are the acceptance bar the precompile + single-process work is measured against, not a post-hoc fit. Consumed by the bench harness (scripts/bench_hook_latency) and its CI gate. Every budget carries an owner and a review date per the Phase-6 budget-ownership lint.",
+    "schema_version": 1,
+    "registered_at": "2026-07-27",
+    "owner": "maintainer",
+    "review_by": "2027-07-27",
+    "hardware_reference": {
+        "ci": "GitHub-hosted ubuntu-latest runner (the numbers the gate enforces)",
+        "floor": "1 vCPU reference container (documented ceiling, not CI-enforced)"
+    },
+    "budgets_ms": {
+        "pre_tool_use": { "p95_ci": 150, "p95_1vcpu": 400 },
+        "any_hook_event": { "p95_ci": 250 }
+    },
+    "regression_gate": {
+        "max_regression_pct": 200,
+        "_comment": "Pathology net only — the ABSOLUTE budgets above are the binding gate for wall-clock. The original 20% window was falsified by measured GitHub-runner variance: two CI runs of IDENTICAL code measured p95 77-89 ms and 92-103 ms (+23% run-to-run, 2026-07-27, runs 30303438480 / round-2 tests.yml). Same rationale as the regression_pct 200 override on the evaluator timing budgets: a tight creep rule on shared-runner wall-clock flaps; sizes/counts keep tight windows, timings get absolute caps."
+    },
+    "honest_null_consequence": "If the budget is missed after precompile + single-process + lazy I/O, hooks ship default-off with an explicit opt-in flag and the measured numbers published under a 'known cost' heading. A resident-dispatcher daemon is NOT improvised as a rescue (council 2026-07-26)."
+}

package/src/config/preamble-payload-budget.json

@@ -0,0 +1,44 @@
+{
+    "_comment": "Per-spawn preamble payload ceiling (road-to-cache-economy Phase 3), unblocked by C-3 measuring 38.0% against a 15% bar. This is a RATCHET, not the roadmap's literal candidate numbers: those (median 40k / p95 50k) were anchored to an upstream ~37k baseline, while this package's own deterministic in-repo payload is ~102.5k tokens — a hard 40k gate would be red on the day it lands and would teach the reader to ignore it. The ratchet fails on GROWTH instead, so the number can only walk down, and the 40k/50k target stays recorded as the destination. Only the deterministic, in-repo buckets are gated: user-scope rules depend on what the developer happens to have installed globally and are therefore not CI-checkable.",
+    "schema_version": 1,
+    "registered_at": "2026-07-30",
+    "owner": "maintainer",
+    "review_by": "2027-07-30",
+    "metric": {
+        "basis": "chars/4 token estimate over the projected tree, produced by src/scripts/preamble_byte_census.ts",
+        "gated_buckets": [
+            "project-scope rules (dist/agent-src/rules/*.md)",
+            "preloaded skills catalog (name + description, dist/agent-src/skills)",
+            "CLAUDE.md hierarchy (project + project-local)"
+        ],
+        "excluded_buckets": [
+            "user-scope rules (~/.claude/rules/*.md) — machine-dependent, not CI-checkable",
+            "tool definitions + dispatch prompt — no local source carries the request payload; the census reports it as an explicit residual"
+        ]
+    },
+    "baseline_tokens": 102520,
+    "baseline_history": [
+        {
+            "tokens": 102599,
+            "at": "2026-07-30",
+            "why": "registered with the gate"
+        },
+        {
+            "tokens": 102520,
+            "at": "2026-07-31",
+            "why": "free tightening: the measured tree came in 79 tok under the registered baseline, so the ratchet walks down to meet it. Not a claimed reduction — nothing was optimised; the point of a ratchet is that a lower measurement becomes the new ceiling instead of becoming unused headroom."
+        }
+    ],
+    "headroom_pct": 5,
+    "target_tokens": {
+        "median": 40000,
+        "p95": 50000,
+        "_comment": "The roadmap's candidate numbers, kept as the destination. Reaching them needs reductions this package has not built yet; scope-dedup (C-3) removes a redundant COPY at the consumer, it does not shrink the suite itself."
+    },
+    "reference_measurements": {
+        "measured_cold_start_median_tokens": 230930,
+        "c3_scope_dedup_reduction_pct": 38,
+        "c3_condition": "FIXTURE-ONLY as of 2026-07-31: the 38% was measured on a byte-identical two-scope fixture, and that condition is currently unreachable for every consumer because install.ts:2723/2725 stamp package:/source_path: into every installed rule while the in-repo projection stamps nothing. Aligning versions yields 0/110 twins, not 110/110. The figure is the mechanism's ceiling, NOT a realised saving, and this baseline therefore assumes no dedup. Reachability is the subject of road-to-dedup-reachability; run measure_scope_dedup for the live split.",
+        "_comment": "The measured median comes from Claude Code transcripts (deduped by message.id + requestId) and is context for the ratchet, never the gated number — it moves with the developer's own session history."
+    }
+}

package/src/install/agentSwitchDetection.ts

@@ -0,0 +1,90 @@
+/**
+ * agent-switch detection — passive wizard recommendation (S0.1 honest-null
+ * council verdict, 2026-07-28: PASSIVE ROW ONLY, never a proactive card).
+ *
+ * agent-switch (https://github.com/event4u-app/agent-switch,
+ * `@event4u/agent-switch` on npm) isolates multiple agent accounts into
+ * per-account profiles (`CLAUDE_CONFIG_DIR`) so switching accounts never
+ * requires a re-login. Unlike rtk, the install command is npm-global and
+ * identical on every OS — no per-OS command map, no name collision to
+ * disambiguate.
+ *
+ * Two independent installed-signals, either is sufficient:
+ *   - the `agent-switch` binary is resolvable on PATH (the documented
+ *     npm-global install), OR
+ *   - `~/.agent-switch/` exists — a user who installed it another way must
+ *     never be told to install it again.
+ *
+ * Version is only probed when the binary is on PATH (the directory-only
+ * signal carries no version information — reported as `null`). There is
+ * deliberately NO version-currency check and NO network call here — the
+ * wizard only ever answers "installed or not", never "up to date" (roadmap
+ * acceptance criterion: this module does not report on agent-switch's
+ * version currency).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveBinaryOnPath } from './rtkDetection.js';
+
+export const AGENT_SWITCH_REPO = 'event4u-app/agent-switch';
+export const AGENT_SWITCH_NPM = '@event4u/agent-switch';
+export const AGENT_SWITCH_INSTALL_COMMAND = 'npm install -g @event4u/agent-switch';
+
+export interface AgentSwitchDetection {
+    installed: boolean;
+    version: string | null;
+}
+
+export interface DetectAgentSwitchOptions {
+    /** Override the home directory (tests). */
+    home?: string;
+    /** Override PATH (tests). */
+    pathEnv?: string;
+    /** Override the version probe (tests). Receives the resolved binary path. */
+    probeVersion?: (bin: string) => string | null;
+}
+
+const PROBE_TIMEOUT_MS = 2000;
+
+/** First dotted-number token in `output`, or `null` when none is present. */
+export function parseVersionOutput(output: string): string | null {
+    const m = /(\d+\.\d+(?:\.\d+)?)/.exec(output);
+    return m?.[1] ?? null;
+}
+
+function defaultProbeVersion(bin: string): string | null {
+    try {
+        const res = spawnSync(bin, ['--version'], {
+            timeout: PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (res.error !== undefined || res.signal !== null) return null;
+        return parseVersionOutput(`${res.stdout ?? ''}\n${res.stderr ?? ''}`);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Detect agent-switch installation. Never throws — every failure mode
+ * (spawn error, timeout, unparsable output) collapses to `version: null`.
+ */
+export function detectAgentSwitch(options: DetectAgentSwitchOptions = {}): AgentSwitchDetection {
+    const binPath = resolveBinaryOnPath('agent-switch', options.pathEnv);
+    if (binPath !== null) {
+        const probe = options.probeVersion ?? defaultProbeVersion;
+        let version: string | null;
+        try {
+            version = probe(binPath);
+        } catch {
+            version = null;
+        }
+        return { installed: true, version };
+    }
+    const home = options.home ?? homedir();
+    const dirInstalled = existsSync(join(home, '.agent-switch'));
+    return { installed: dirInstalled, version: null };
+}

package/src/install/agentSwitchProfile.ts

@@ -0,0 +1,131 @@
+/**
+ * Detect whether AC is currently running under an agent-switch (AS)
+ * profile (`road-to-reciprocal-ecosystem.md` Phase 2 — correctness
+ * work, not the Phase 1 promotion card).
+ *
+ * Pure and injectable: reads only the supplied environment map, no
+ * filesystem I/O. Detection is deliberately topology-free — it never
+ * needs to understand AS's on-disk share model (that lives in
+ * `sharedWriteCheck.ts`, which DOES touch disk via `lstat`).
+ *
+ * AS root resolution mirrors `agent-switch/src/profiles.ts:11`:
+ * `AGENT_SWITCH_HOME` env override, else `~/.agent-switch`. Profile
+ * config dirs live at `<ROOT>/<provider>/<name>/config` (profiles.ts
+ * :143-145). Provider env vars mirror `agent-switch/src/providers.ts`:
+ * claude → `CLAUDE_CONFIG_DIR`, codex → `CODEX_HOME`. `HOME`
+ * (antigravity's provider var) is deliberately NOT checked here — it
+ * is set on every process, so treating it as an AS signal would
+ * false-positive constantly; antigravity profile detection is left to
+ * a future, more specific probe.
+ */
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+
+export interface AgentSwitchProfile {
+    active: boolean;
+    provider: string | null;
+    profile: string | null;
+}
+
+const INACTIVE: AgentSwitchProfile = { active: false, provider: null, profile: null };
+
+/** Provider env vars checked, in priority order (claude wins on a tie). */
+const PROVIDER_ENV_VARS: readonly string[] = ['CLAUDE_CONFIG_DIR', 'CODEX_HOME'];
+
+interface AgentSwitchMatch {
+    /** The resolved AS root implied by the matching env var. */
+    root: string;
+    /** Path segments below `root` (e.g. `[provider, profile, 'config']`). */
+    afterRoot: string[];
+}
+
+/** Expand a leading `~` the way a shell would, for env values set programmatically. */
+function expandTilde(p: string): string {
+    if (p === '~') return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return path.join(homedir(), p.slice(2));
+    }
+    return p;
+}
+
+function normalize(p: string): string {
+    return path.resolve(expandTilde(p));
+}
+
+function nonEmpty(v: string | undefined): v is string {
+    return typeof v === 'string' && v.trim() !== '';
+}
+
+/**
+ * Find the first provider env var whose (normalized) value lies
+ * inside the AS root, and return the root + the path segments below
+ * it. Shared by `detectAgentSwitchProfile` and `resolveAgentSwitchRoot`
+ * so both stay in lockstep with a single matching rule.
+ */
+function resolveMatch(env: NodeJS.ProcessEnv): AgentSwitchMatch | null {
+    const overrideRaw = env['AGENT_SWITCH_HOME'];
+    const overrideRoot = nonEmpty(overrideRaw) ? normalize(overrideRaw) : null;
+
+    for (const varName of PROVIDER_ENV_VARS) {
+        const raw = env[varName];
+        if (!nonEmpty(raw)) continue;
+        const candidate = normalize(raw);
+
+        let root: string | null = null;
+        if (overrideRoot !== null) {
+            if (candidate === overrideRoot || candidate.startsWith(overrideRoot + path.sep)) {
+                root = overrideRoot;
+            }
+        } else {
+            const bareMarker = `${path.sep}.agent-switch`;
+            const nestedMarker = `${bareMarker}${path.sep}`;
+            if (candidate.endsWith(bareMarker)) {
+                root = candidate;
+            } else {
+                const idx = candidate.indexOf(nestedMarker);
+                if (idx !== -1) root = candidate.slice(0, idx + bareMarker.length);
+            }
+        }
+        if (root === null) continue;
+
+        const rest = candidate === root ? '' : candidate.slice(root.length + 1);
+        const afterRoot = rest === '' ? [] : rest.split(path.sep).filter((s) => s.length > 0);
+        return { root, afterRoot };
+    }
+    return null;
+}
+
+/**
+ * Detect the active AS profile (if any) from the current environment.
+ *
+ * - Not inside `.agent-switch` at all → `{ active: false, ... }`.
+ * - Inside the AS root, but the env var points AT the root itself
+ *   (no `<provider>/<profile>` segments below it) → treated as
+ *   inactive; an env var pointing at the bare root is not a profile
+ *   directory.
+ * - Inside the AS root with only one segment below it (a provider dir
+ *   with no profile name) → active, but unparseable (`provider`/
+ *   `profile` both `null`).
+ * - Inside the AS root with `<provider>/<profile>/...` below it →
+ *   active, with `provider`/`profile` parsed from the first two
+ *   segments.
+ */
+export function detectAgentSwitchProfile(env: NodeJS.ProcessEnv = process.env): AgentSwitchProfile {
+    const match = resolveMatch(env);
+    if (match === null) return INACTIVE;
+    if (match.afterRoot.length === 0) return INACTIVE;
+    if (match.afterRoot.length < 2) return { active: true, provider: null, profile: null };
+    // `length >= 2` guaranteed above — `??` only satisfies noUncheckedIndexedAccess.
+    return { active: true, provider: match.afterRoot[0] ?? null, profile: match.afterRoot[1] ?? null };
+}
+
+/**
+ * Resolve the AS root directory implied by the environment (the same
+ * matching rule `detectAgentSwitchProfile` uses), for callers that
+ * need a boundary to stop an upward filesystem walk at — see
+ * `sharedWriteCheck.ts`. Returns `null` when no provider env var
+ * resolves inside an AS tree.
+ */
+export function resolveAgentSwitchRoot(env: NodeJS.ProcessEnv = process.env): string | null {
+    return resolveMatch(env)?.root ?? null;
+}

package/src/install/atomic.ts

@@ -2,7 +2,7 @@
  * Atomic file writer — Phase A4 primitive.
  *
  * 1:1 port of the `tempfile.mkstemp` + `os.replace` pattern used across
- * `scripts/install.py` (see `_write_consumer_bridge_marker` ~line 3036).
+ * the retired Python installer's `_write_consumer_bridge_marker` (ADR-200).
  *
  * Contract:
  *   1. Open a sibling `.tmp.<rand>` file in the destination directory

package/src/install/detect.ts

@@ -26,7 +26,7 @@ import type { InstallTarget } from './types.js';
 /**
  * Settings-file name used as the strongest project-scope signal.
  *
- * Matches `SETTINGS_FILE` in `scripts/install.py`. Presence in `cwd`
+ * Matches `SETTINGS_FILE` in the retired Python installer (ADR-200). Presence in `cwd`
  * short-circuits scope detection to `'project'` without consulting
  * the manifest / AI-tool lists.
  */