@event4u/agent-config 7.2.0 → 7.4.0

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 };

package/src/scripts/run_skill_evals.ts

@@ -97,6 +97,39 @@ export function _spawn_subagent(
     );
 }
 
+/**
+ * Count "findings" in an eval output for the `finding_floor` assertion
+ * (roadmap `road-to-operator-runtime-harvest`, Phase 1). With an explicit
+ * `pattern`, counts non-overlapping global regex matches; without one, counts
+ * markdown list-item lines (the default shape a skill's findings take).
+ *
+ * Deterministic on purpose: this only *counts*. The substantive judgement —
+ * is each match a real finding, and what should `n` be per host — is the
+ * calibration layer (Phase 1 gold set + per-host floor), which is gated on the
+ * P0 cross-model distributions and therefore NOT wired here yet. So
+ * `finding_floor` is available as a mechanism and exercised by fixtures, but is
+ * not an enforcing CI gate until calibrated.
+ */
+export function _count_findings(output: string, pattern?: string): number {
+    if (pattern !== undefined && pattern !== '') {
+        let re: RegExp;
+        try {
+            re = new RegExp(pattern, 'g');
+        } catch {
+            return 0;
+        }
+        const m = output.match(re);
+        return m ? m.length : 0;
+    }
+    let count = 0;
+    for (const line of output.split('\n')) {
+        if (/^\s*(?:[-*+]|\d+[.)])\s+\S/.test(line)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+
 export function _grade_assertions(
     output: string,
     run_dir: string,
@@ -119,6 +152,11 @@ export function _grade_assertions(
                 pass: null,
                 note: 'rubric grading requires sub-agent — fill in manually or via grader',
             });
+        } else if (kind === 'finding_floor') {
+            const n = (a['n'] as number | undefined) ?? 1;
+            const pattern = a['pattern'] as string | undefined;
+            const count = _count_findings(output, pattern);
+            results.push({ kind, n, count, pass: count >= n });
         } else {
             results.push({ kind: kind ?? null, pass: false, note: `unknown assertion kind ${_pyRepr(kind)}` });
         }

package/src/scripts/skill_linter.ts

@@ -1667,7 +1667,7 @@ export function validate_evals_json(skillPath: string): Issue[] {
         );
         return issues;
     }
-    const validKinds = ['contains', 'file_exists', 'rubric'];
+    const validKinds = ['contains', 'file_exists', 'rubric', 'finding_floor'];
     const validKindsSet = new Set(validKinds);
     scenarios.forEach((scenario, idx) => {
         const loc = `scenarios[${idx}]`;
@@ -1709,15 +1709,31 @@ export function validate_evals_json(skillPath: string): Issue[] {
                 );
                 return;
             }
-            const requiredField = { contains: 'value', file_exists: 'path', rubric: 'criterion' }[kind] as string;
-            if (!(requiredField in a) || typeof a[requiredField] !== 'string') {
-                issues.push(
-                    new Issue(
-                        'warning',
-                        'evals_json_assertion_missing_field',
-                        `${aLoc} (kind=${kind}) missing required string field '${requiredField}'`,
-                    ),
-                );
+            if (kind === 'finding_floor') {
+                // finding_floor (run_skill_evals): `n` (number; runtime-defaults to
+                // 1) and `pattern` (regex string) are both OPTIONAL — validate type
+                // only when present, require neither.
+                if ('n' in a && typeof a.n !== 'number') {
+                    issues.push(
+                        new Issue('warning', 'evals_json_assertion_field_type', `${aLoc} (kind=finding_floor) 'n' must be a number`),
+                    );
+                }
+                if ('pattern' in a && typeof a.pattern !== 'string') {
+                    issues.push(
+                        new Issue('warning', 'evals_json_assertion_field_type', `${aLoc} (kind=finding_floor) 'pattern' must be a string`),
+                    );
+                }
+            } else {
+                const requiredField = { contains: 'value', file_exists: 'path', rubric: 'criterion' }[kind] as string;
+                if (!(requiredField in a) || typeof a[requiredField] !== 'string') {
+                    issues.push(
+                        new Issue(
+                            'warning',
+                            'evals_json_assertion_missing_field',
+                            `${aLoc} (kind=${kind}) missing required string field '${requiredField}'`,
+                        ),
+                    );
+                }
             }
         });
     });