@event4u/agent-config 7.3.0 → 7.4.0

package/src/scripts/check_token_regression.ts

@@ -0,0 +1,266 @@
+#!/usr/bin/env tsx
+/**
+ * Token-regression gate (token-saving Phase 0).
+ *
+ * Fails CI when a tracked always-loaded / projected token surface grows more
+ * than the tolerance (default 5%) over a committed baseline. This is the
+ * RELATIVE guard — distinct from `audit-tokens-budget` (absolute budgets) and
+ * from the cache-prefix byte-stability guard (Phase 5).
+ *
+ * Source of truth is `internal/bench/reports/projection-cost.json`, which is
+ * now produced with EXACT counts via the real tokenizer
+ * (`src/scripts/_lib/token_count.ts` → js-tiktoken cl100k_base). Run
+ * `task audit-tokens` first so the report reflects the working tree.
+ *
+ * Gated metrics (all `tokens_gpt`):
+ *   - eager_rule_load    — thin_projection.eager_gpt (the eager always-on load)
+ *   - thin_rule_load     — thin_projection.thin_gpt
+ *   - skill_descriptions — description_catalog.skills_core_source.tokens_gpt
+ *   - command_descriptions — description_catalog.commands_core_source.tokens_gpt
+ *   - mcp_schemas        — Σ mcp_tool_schemas[*].tokens_gpt
+ *
+ * A baseline captured under a different `token_method` (e.g. proxy → exact)
+ * is a legitimate reset, not a regression — the gate WARNS and asks for a
+ * `--update-baseline` rather than failing on the method switch alone.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/check_token_regression            # gate (read-only)
+ *   ./scripts-run src/scripts/check_token_regression --json     # machine output
+ *   ./scripts-run src/scripts/check_token_regression --tolerance 0.05
+ *   ./scripts-run src/scripts/check_token_regression --update-baseline  # record current as baseline
+ *
+ * Exit codes:
+ *   0 — within tolerance (or baseline written / warmup: no baseline yet)
+ *   1 — argument / file error
+ *   2 — regression: a metric exceeded baseline by more than the tolerance
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+// REPO_ROOT = <repo>/src/scripts/<file> → up two.
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const PROJECTION_REPORT = path.join(
+  REPO_ROOT,
+  'internal/bench/reports/projection-cost.json',
+);
+const BASELINE_FILE = path.join(
+  REPO_ROOT,
+  'internal/bench/reports/token-baseline.json',
+);
+const DEFAULT_TOLERANCE = 0.05;
+
+type Json = Record<string, unknown>;
+
+interface Metrics {
+  token_method: string;
+  metrics: Record<string, number>;
+}
+
+function _num(obj: unknown, ...keys: string[]): number {
+  let cur: unknown = obj;
+  for (const k of keys) {
+    if (cur && typeof cur === 'object' && k in (cur as Json)) {
+      cur = (cur as Json)[k];
+    } else {
+      return 0;
+    }
+  }
+  return typeof cur === 'number' ? cur : 0;
+}
+
+/** Extract the flat gated-metric map from a projection-cost report. */
+function extract_metrics(report: Json): Metrics {
+  const mcp = (report['mcp_tool_schemas'] as Json) ?? {};
+  let mcp_total = 0;
+  for (const server of Object.values(mcp)) {
+    mcp_total += _num(server, 'tokens_gpt');
+  }
+  return {
+    token_method: String(report['token_method'] ?? 'unknown'),
+    metrics: {
+      eager_rule_load: _num(report, 'thin_projection', 'eager_gpt'),
+      thin_rule_load: _num(report, 'thin_projection', 'thin_gpt'),
+      skill_descriptions: _num(
+        report,
+        'description_catalog',
+        'skills_core_source',
+        'tokens_gpt',
+      ),
+      command_descriptions: _num(
+        report,
+        'description_catalog',
+        'commands_core_source',
+        'tokens_gpt',
+      ),
+      mcp_schemas: mcp_total,
+    },
+  };
+}
+
+function _readJson(file: string): Json | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8')) as Json;
+  } catch {
+    return null;
+  }
+}
+
+interface Row {
+  id: string;
+  current: number;
+  baseline: number;
+  pct: number; // signed fraction, e.g. 0.07 = +7%
+  regressed: boolean;
+}
+
+export interface GateResult {
+  status: 'ok' | 'regression' | 'warmup' | 'method-changed';
+  tolerance: number;
+  current_method: string;
+  baseline_method: string | null;
+  rows: Row[];
+}
+
+export function evaluate(
+  current: Metrics,
+  baseline: Metrics | null,
+  tolerance: number,
+): GateResult {
+  if (baseline === null) {
+    return {
+      status: 'warmup',
+      tolerance,
+      current_method: current.token_method,
+      baseline_method: null,
+      rows: [],
+    };
+  }
+  const method_changed = baseline.token_method !== current.token_method;
+  const rows: Row[] = [];
+  for (const [id, cur] of Object.entries(current.metrics)) {
+    const base = baseline.metrics[id] ?? 0;
+    const pct = base > 0 ? (cur - base) / base : 0;
+    rows.push({
+      id,
+      current: cur,
+      baseline: base,
+      pct,
+      // A method switch is a legitimate baseline reset, not a regression.
+      regressed: !method_changed && base > 0 && pct > tolerance,
+    });
+  }
+  rows.sort((a, b) => b.pct - a.pct);
+  const anyRegressed = rows.some((r) => r.regressed);
+  const status: GateResult['status'] = anyRegressed
+    ? 'regression'
+    : method_changed
+      ? 'method-changed'
+      : 'ok';
+  return {
+    status,
+    tolerance,
+    current_method: current.token_method,
+    baseline_method: baseline.token_method,
+    rows,
+  };
+}
+
+function _fmtPct(p: number): string {
+  const sign = p >= 0 ? '+' : '';
+  return `${sign}${(p * 100).toFixed(1)}%`;
+}
+
+function main(argv: string[]): number {
+  let tolerance = DEFAULT_TOLERANCE;
+  let asJson = false;
+  let updateBaseline = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') asJson = true;
+    else if (a === '--update-baseline') updateBaseline = true;
+    else if (a === '--tolerance') {
+      const v = Number(argv[(i += 1)]);
+      if (!Number.isFinite(v) || v < 0) {
+        process.stderr.write(`error: invalid --tolerance\n`);
+        return 1;
+      }
+      tolerance = v;
+    } else if (a === '-h' || a === '--help') {
+      process.stdout.write(
+        'usage: check_token_regression [--json] [--tolerance F] [--update-baseline]\n',
+      );
+      return 0;
+    } else {
+      process.stderr.write(`error: unknown argument: ${a}\n`);
+      return 1;
+    }
+  }
+
+  const report = _readJson(PROJECTION_REPORT);
+  if (report === null) {
+    process.stderr.write(
+      `error: cannot read ${path.relative(REPO_ROOT, PROJECTION_REPORT)} — run \`task audit-tokens\` first\n`,
+    );
+    return 1;
+  }
+  const current = extract_metrics(report);
+
+  if (updateBaseline) {
+    const payload = JSON.stringify(current, null, 2) + '\n';
+    fs.writeFileSync(BASELINE_FILE, payload);
+    process.stdout.write(
+      `✅  token baseline written: ${path.relative(REPO_ROOT, BASELINE_FILE)} (method: ${current.token_method})\n`,
+    );
+    return 0;
+  }
+
+  const baselineRaw = _readJson(BASELINE_FILE);
+  const baseline: Metrics | null =
+    baselineRaw === null ? null : (baselineRaw as unknown as Metrics);
+  const result = evaluate(current, baseline, tolerance);
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (result.status === 'warmup') {
+    process.stdout.write(
+      `⚠️  no token baseline yet — run \`./scripts-run src/scripts/check_token_regression --update-baseline\` to record one.\n`,
+    );
+  } else {
+    for (const r of result.rows) {
+      const mark = r.regressed ? '❌' : '✅';
+      process.stdout.write(
+        `${mark}  ${r.id}: ${r.current} vs baseline ${r.baseline} (${_fmtPct(r.pct)})\n`,
+      );
+    }
+    if (result.status === 'method-changed') {
+      process.stdout.write(
+        `⚠️  token_method changed (${result.baseline_method} → ${result.current_method}); ` +
+          `baseline reset is legitimate — run --update-baseline to re-anchor.\n`,
+      );
+    } else if (result.status === 'regression') {
+      process.stdout.write(
+        `❌  token regression: a projection grew >${(tolerance * 100).toFixed(0)}% over baseline.\n`,
+      );
+    } else {
+      process.stdout.write(
+        `✅  token surfaces within +${(tolerance * 100).toFixed(0)}% of baseline.\n`,
+      );
+    }
+  }
+
+  return result.status === 'regression' ? 2 : 0;
+}
+
+const _IS_MAIN =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (_IS_MAIN) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { extract_metrics, main };

package/src/scripts/hook_manifest.yaml

@@ -64,6 +64,18 @@ concerns:
     script: src/scripts/hooks/block_no_verify.ts
     args: []
     fail_closed: true
+  # token-saving Phase 3 — PreToolUse RTK-wrap nudge. DETERMINISTIC: keys off a
+  # live `which rtk` probe (not the self-reported flag). When rtk is installed
+  # and the agent is about to run a single verbose CLI command that is NOT
+  # completeness-critical, warns "re-run wrapped with rtk" (60–90% fewer output
+  # tokens). Warn only — never blocks (the v1 contract has no transparent
+  # rewrite); never fires when rtk is absent (silent plain-command fallback).
+  # Default-OFF (hooks.rtk_wrap.enabled). fail_closed: false — never break a
+  # command for a token optimization.
+  rtk-wrap:
+    script: src/scripts/hooks/rtk_wrap_hook.ts
+    args: []
+    fail_closed: false
   # Phase 2 of road-to-hooks-actually-fire-in-consumers — session_start
   # gate that surfaces the marketplace-install-but-unscaffolded shape.
   # Writes .augment/.first-run-action-needed.md + one stderr line so
@@ -96,7 +108,7 @@ platforms:
     session_start:    [chat-history, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
-    pre_tool_use:     [block-no-verify]
+    pre_tool_use:     [block-no-verify, rtk-wrap]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
 
   claude:
@@ -104,7 +116,7 @@ platforms:
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    pre_tool_use:     [block-no-verify]
+    pre_tool_use:     [block-no-verify, rtk-wrap]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
@@ -126,7 +138,7 @@ platforms:
     session_end:      [chat-history]
     stop:             [chat-history, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    pre_tool_use:     [block-no-verify]
+    pre_tool_use:     [block-no-verify, rtk-wrap]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
 
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse RTK-wrap nudge — deterministic, warn-in-context
+ * (token-saving Phase 3).
+ *
+ * Converts RTK from advisory to DETERMINISTIC: instead of trusting a
+ * self-reported flag, this hook keys off a live `which rtk` probe. When rtk is
+ * actually installed AND the agent is about to run a single verbose CLI command
+ * that is NOT completeness-critical, it surfaces (warn) "re-run wrapped with
+ * rtk" so the 60–90% output-token saving is captured. It NEVER blocks (the v1
+ * dispatcher contract is allow/block/warn — there is no transparent
+ * `updatedInput` rewrite — and, like `injection_scan_hook`, warn preserves
+ * agency). It NEVER fires when rtk is absent (silent plain-command fallback,
+ * no nag).
+ *
+ * Default-OFF. Fires only when `hooks.rtk_wrap.enabled: true` in
+ * `.agent-settings.yml`. Disabled / missing / rtk-absent → no-op exit 0.
+ * fail_closed: false — any parse/probe error returns allow (never break a
+ * command for a token optimization).
+ *
+ * Denylist (never nudged — completeness-critical or already-handled):
+ *   - `git diff` / `rtk read` (silent truncation risk — see the rtk skill)
+ *   - already `rtk …` wrapped, or piped / compound (`|`, `&&`, `||`, `;`)
+ *   - any program not in the verbose-CLI allowlist
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ JSON reason on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  shlexSplit,
+  ShlexError,
+  _split_subcommands,
+  _is_env_assignment,
+} from "./block_no_verify.js";
+
+const SETTINGS_FILE = ".agent-settings.yml";
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+// Verbose-CLI programs worth wrapping — mirrors the cli-output-handling rule
+// triggers + the rtk skill's "✅ Always" table. Kept in sync with
+// src/rules/cli-output-handling.md.
+const _RTK_PROGRAMS: ReadonlySet<string> = new Set([
+  "git", "phpstan", "rector", "phpunit", "composer",
+  "npm", "pnpm", "yarn", "eslint", "tsc", "vitest", "jest",
+  "pytest", "ruff", "mypy", "pyright", "cargo", "go",
+  "golangci-lint", "docker", "kubectl", "terraform",
+]);
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** `hooks.rtk_wrap.enabled: true` mini-parser (mirrors injection_scan_hook). */
+function _enabled(root: string): boolean {
+  const f = path.join(root, SETTINGS_FILE);
+  try {
+    if (!fs.statSync(f).isFile()) return false;
+  } catch {
+    return false;
+  }
+  let text: string;
+  try {
+    text = fs.readFileSync(f, "utf-8");
+  } catch {
+    return false;
+  }
+  let in_hooks = false;
+  let in_rw = false;
+  const lines = text.split(/\r\n|\r|\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || line.replace(/^\s+/, "").startsWith("#")) continue;
+    if (!(line.startsWith(" ") || line.startsWith("\t"))) {
+      in_hooks = /^hooks\s*:\s*$/.test(line);
+      in_rw = false;
+      continue;
+    }
+    if (in_hooks) {
+      if (/^\s+rtk_wrap\s*:\s*$/.test(line)) {
+        in_rw = true;
+        continue;
+      }
+      if (in_rw && /^\s{0,3}\S/.test(line)) in_rw = false;
+    }
+    if (in_rw && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+  }
+  return false;
+}
+
+/** Live `which rtk` — scan PATH for an executable `rtk` (cross-platform). */
+export function rtk_available(env: NodeJS.ProcessEnv = process.env): boolean {
+  const pathVar = env.PATH ?? env.Path ?? "";
+  if (!pathVar) return false;
+  const dirs = pathVar.split(path.delimiter).filter(Boolean);
+  // On Windows the launcher is rtk.exe / rtk.cmd / rtk.bat.
+  const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `rtk${ext}`);
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile()) {
+          // POSIX: require an executable bit; Windows: extension is enough.
+          if (process.platform === "win32" || (st.mode & 0o111) !== 0) return true;
+        }
+      } catch {
+        /* not here — keep scanning */
+      }
+    }
+  }
+  return false;
+}
+
+function _extract_command(envelope: JsonObject): string | null {
+  const payload = (_isObject(envelope["payload"]) ? envelope["payload"] : {}) as JsonObject;
+  const tool_input = (_isObject(payload["tool_input"]) ? payload["tool_input"] : {}) as JsonObject;
+  for (const src of [tool_input["command"], payload["command"], envelope["command"]]) {
+    if (typeof src === "string") return src;
+  }
+  return null;
+}
+
+export interface Eligibility {
+  eligible: boolean;
+  program?: string;
+  reason_skip?: string;
+}
+
+/**
+ * A command is eligible for an rtk-wrap nudge iff it is a SINGLE simple command
+ * (no pipe / compound separators), whose program is a known verbose CLI, and is
+ * not a completeness-critical / already-wrapped case.
+ */
+export function classify(command: string): Eligibility {
+  const cmd = command.trim();
+  if (!cmd) return { eligible: false, reason_skip: "empty" };
+
+  let tokens: string[];
+  try {
+    tokens = shlexSplit(cmd);
+  } catch (e) {
+    if (e instanceof ShlexError) return { eligible: false, reason_skip: "parse-error" };
+    throw e;
+  }
+
+  // Compound / piped → don't wrap (rtk wraps a single command). `_split_subcommands`
+  // splits on && || ; | — more than one group means a pipeline/chain.
+  const groups = _split_subcommands(tokens);
+  if (groups.length !== 1) return { eligible: false, reason_skip: "compound-or-piped" };
+
+  const sub = groups[0] as string[];
+  let i = 0;
+  while (i < sub.length && _is_env_assignment(sub[i] as string)) i += 1;
+  const program = sub[i];
+  if (!program) return { eligible: false, reason_skip: "no-program" };
+  if (program === "rtk") return { eligible: false, reason_skip: "already-rtk" };
+  if (!_RTK_PROGRAMS.has(program)) return { eligible: false, program, reason_skip: "not-verbose-cli" };
+  // `git diff` is completeness-critical (silent truncation) — never wrap.
+  if (program === "git" && sub[i + 1] === "diff") {
+    return { eligible: false, program, reason_skip: "git-diff-denylisted" };
+  }
+  return { eligible: true, program };
+}
+
+function _readStdin(): string {
+  try {
+    if (process.stdin.isTTY) return "";
+    return fs.readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function _jsonReason(reason: string): string {
+  return JSON.stringify({ decision: "warn", reason });
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = _readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // never break a command on a malformed envelope
+  }
+  if (!_isObject(envelope)) return EXIT_ALLOW;
+
+  const cwd = envelope["cwd"];
+  const projectRoot = envelope["workspace_root"] ?? envelope["project_root"];
+  const root =
+    typeof cwd === "string" && cwd
+      ? cwd
+      : typeof projectRoot === "string" && projectRoot
+        ? projectRoot
+        : ".";
+  if (!_enabled(root)) return EXIT_ALLOW;
+
+  // Deterministic gate: the live probe, NOT a self-reported flag.
+  if (!rtk_available()) return EXIT_ALLOW;
+
+  const command = _extract_command(envelope);
+  if (!command) return EXIT_ALLOW;
+
+  const verdict = classify(command);
+  if (!verdict.eligible) return EXIT_ALLOW;
+
+  const reason =
+    `rtk is installed and wraps verbose CLI output (60–90% fewer output tokens). ` +
+    `Re-run wrapped: \`rtk ${command.trim()}\`. ` +
+    `(Skip for completeness-critical output like \`git diff\`.)`;
+  process.stdout.write(`${_jsonReason(reason)}\n`);
+  return EXIT_WARN;
+}
+
+const _isCliEntry =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+  process.exit(main());
+}

package/src/scripts/probe_host_compliance.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env tsx
+/**
+ * Host-compliance probe for thin projection (token-saving Phase 0).
+ *
+ * Thin projection is a CONTRACT WITH THE HOST: a non-kernel rule body is
+ * demoted to a router pointer, and the host is trusted to load the body only
+ * on trigger-match. On a host that reconstructs rule bodies internally (e.g. a
+ * plugin loader that re-inlines everything), thin projection is a silent no-op
+ * — so it must be falsified per host before the thin flip ships.
+ *
+ * This probe has two halves:
+ *
+ *   MECHANICAL (here, automated): run the real thin projector (`thin_entry`)
+ *   on a canary rule fixture and assert the body is replaced by a pointer that
+ *   still carries the trigger hint (so the router can select it). This proves
+ *   the projector demotes correctly — the prerequisite for any host test.
+ *
+ *   LIVE (operator gate): install the thin-projected canary into each host,
+ *   invoke its keyword, and confirm the host shows the POINTER, not the body.
+ *   This is a human-run step (live trigger-eval is a human gate) — the probe
+ *   prints the checklist + a results table to fill in.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/probe_host_compliance           # mechanical check + checklist
+ *   ./scripts-run src/scripts/probe_host_compliance --json
+ *
+ * Exit codes: 0 demotion verified · 1 file error · 2 projector failed to demote.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { thin_entry } from './project_thin_rules.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const CANARY = path.join(
+  REPO_ROOT,
+  'tests/fixtures/host-compliance/host-compliance-canary.md',
+);
+const CANARY_ID = 'host-compliance-canary';
+const SENTINEL = 'CANARY_BODY_SENTINEL_DO_NOT_INLINE';
+const KEYWORD = 'xyzzy-canary-probe';
+const POINTER_MARKER = 'Routed rule — load the body on trigger-match';
+
+// The supported hosts whose live thin-compliance must be falsified.
+const HOSTS = ['claude-code', 'cursor', 'augment'];
+
+export interface DemotionResult {
+  ok: boolean;
+  pointer_present: boolean;
+  body_removed: boolean;
+  trigger_hint_preserved: boolean;
+  link_present: boolean;
+}
+
+/** Assert a thinned canary is a valid pointer (body gone, still selectable). */
+export function evaluate_demotion(
+  thinned: string,
+  opts: { sentinel: string; keyword: string } = { sentinel: SENTINEL, keyword: KEYWORD },
+): DemotionResult {
+  const pointer_present = thinned.includes(POINTER_MARKER);
+  const body_removed = !thinned.includes(opts.sentinel);
+  const trigger_hint_preserved = thinned.includes(opts.keyword);
+  const link_present = /Body: \[`[^`]+`\]\(/.test(thinned);
+  return {
+    ok: pointer_present && body_removed && trigger_hint_preserved && link_present,
+    pointer_present,
+    body_removed,
+    trigger_hint_preserved,
+    link_present,
+  };
+}
+
+function operator_checklist(): string {
+  const rows = HOSTS.map(
+    (h) => `  - [ ] ${h}: fires on \`${KEYWORD}\` AND shows the pointer, NOT the body sentinel`,
+  ).join('\n');
+  return (
+    'LIVE host-compliance step (operator gate — live trigger-eval is human-run):\n' +
+    '  1. Set `lean_projection.mode: thin` and run `task generate-tools && task sync`.\n' +
+    '  2. Install the projected canary into each host.\n' +
+    `  3. Invoke the keyword \`${KEYWORD}\` in a session on each host.\n` +
+    '  4. PASS = the rule fires AND the host surfaces the router pointer;\n' +
+    `     FAIL = the host surfaces the body sentinel (\`${SENTINEL}\`) → thin\n` +
+    '     projection is a no-op there; escalate to the host vendor.\n' +
+    'Results:\n' +
+    rows +
+    '\n'
+  );
+}
+
+function main(argv: string[]): number {
+  const asJson = argv.includes('--json');
+  for (const a of argv) {
+    if (!['--json', '-h', '--help'].includes(a)) {
+      process.stderr.write(`error: unknown argument: ${a}\n`);
+      return 1;
+    }
+    if (a === '-h' || a === '--help') {
+      process.stdout.write('usage: probe_host_compliance [--json]\n');
+      return 0;
+    }
+  }
+
+  let text: string;
+  try {
+    text = fs.readFileSync(CANARY, 'utf-8');
+  } catch {
+    process.stderr.write(`error: cannot read canary fixture ${path.relative(REPO_ROOT, CANARY)}\n`);
+    return 1;
+  }
+  const thinned = thin_entry(CANARY_ID, text);
+  const result = evaluate_demotion(thinned);
+
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify({ ...result, hosts: HOSTS, keyword: KEYWORD, sentinel: SENTINEL }, null, 2) + '\n',
+    );
+    return result.ok ? 0 : 2;
+  }
+
+  process.stdout.write(
+    `${result.ok ? '✅' : '❌'}  mechanical demotion: ` +
+      `pointer=${result.pointer_present} body-removed=${result.body_removed} ` +
+      `hint=${result.trigger_hint_preserved} link=${result.link_present}\n`,
+  );
+  if (!result.ok) {
+    process.stdout.write('❌  the thin projector did NOT demote the canary correctly.\n');
+    return 2;
+  }
+  process.stdout.write('\n' + operator_checklist());
+  return 0;
+}
+
+const _IS_MAIN =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (_IS_MAIN) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { main };