@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-code-review/scripts/acp-panel-client.mjs

@@ -0,0 +1,299 @@
+// ACP v1 read-only review transport. See ../references/acp-client.md.
+import { execFileSync, spawn } from "node:child_process";
+import { realpathSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import * as readline from "node:readline";
+const rawArgs = process.argv.slice(2);
+function takeFlag(name, def) {
+  const i = rawArgs.indexOf(name);
+  if (i >= 0 && i + 1 < rawArgs.length) {
+    const v = rawArgs[i + 1];
+    rawArgs.splice(i, 2);
+    return v;
+  }
+  return def;
+}
+const maxTurns = Math.max(1, parseInt(takeFlag("--max-turns", "1"), 10));
+const verdictMarker = takeFlag("--verdict", "");
+const modelArg = takeFlag("--model", "");
+const effortArg = takeFlag("--effort", "");
+const timeoutMin = Math.max(1, Number(takeFlag("--timeout-min", "60")) || 60);
+const idleArg = Number(takeFlag("--idle-min", "5"));
+const IDLE_MS = (idleArg > 0 ? idleArg : 5) * 60 * 1000;
+const [serverCmdJson, promptFile, outText, cwdArg] = rawArgs;
+if (!serverCmdJson || !promptFile || !outText) {
+  console.error(
+    "usage: node acp-panel-client.mjs <server-cmd-json> <prompt-file> <out-text> [cwd] [--max-turns N] [--verdict MARK] [--model ID] [--effort LEVEL] [--idle-min N] [--timeout-min N]",
+  );
+  process.exit(2);
+}
+const serverCmd = JSON.parse(serverCmdJson);
+const cwd = realpathSync(cwdArg || process.cwd());
+const promptText = readFileSync(promptFile, "utf8");
+const HARD_TIMEOUT_MS = timeoutMin * 60 * 1000;
+function gitStatus() {
+  try {
+    return execFileSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8" });
+  } catch {
+    return null;
+  }
+}
+const statusBefore = gitStatus();
+const child = spawn(serverCmd[0], serverCmd.slice(1), {
+  cwd,
+  env: process.env,
+  stdio: ["pipe", "pipe", "inherit"],
+});
+let nextId = 1;
+let isCodex = false;
+const pending = new Map();
+function rejectPending(error) {
+  for (const p of pending.values()) p.reject(error);
+  pending.clear();
+}
+child.on("error", rejectPending);
+child.on("exit", (code, signal) =>
+  rejectPending(new Error(`ACP server exited (${code ?? signal})`)),
+);
+const rl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+function send(msg) {
+  child.stdin.write(JSON.stringify(msg) + "\n");
+}
+function request(method, params) {
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    send({ jsonrpc: "2.0", id, method, params });
+  });
+}
+function replyOk(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+function replyErr(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+// Resolve physical targets; the client is not an OS sandbox for agent-owned tools.
+async function underCwd(path) {
+  if (typeof path !== "string" || !path) return null;
+  const lexical = resolve(cwd, path);
+  const inside = (target) => {
+    const rel = relative(cwd, target);
+    return rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel);
+  };
+  if (!inside(lexical)) return null;
+  // Same resolver as the root, so a runtime whose async and sync realpath spell a path
+  // differently cannot make an inside file look outside.
+  const physical = realpathSync(lexical);
+  if (!inside(physical) || !(await stat(physical)).isFile()) return null;
+  return physical;
+}
+async function handleServerRequest(msg) {
+  const { id, method } = msg;
+  const params = msg.params ?? {};
+  try {
+    if (method === "fs/read_text_file") {
+      const ok = await underCwd(params.path);
+      if (!ok) {
+        return replyErr(id, -32602, "path outside cwd");
+      }
+      const content = await readFile(ok, "utf8");
+      return replyOk(id, { content });
+    }
+    if (method === "fs/write_text_file") {
+      return replyErr(id, -32601, "write_text_file disabled by panel policy");
+    }
+    if (method?.startsWith("terminal/")) {
+      return replyErr(id, -32601, "terminal execution disabled by review policy");
+    }
+    if (method === "session/request_permission") {
+      const opts = params.options || [];
+      const kind = params.toolCall?.kind;
+      const reject = opts.find((o) => String(o.kind || "").startsWith("reject"));
+      console.error(`[client] rejected ${kind || "unknown"} permission request`);
+      rejections++;
+      return replyOk(
+        id,
+        reject
+          ? { outcome: { outcome: "selected", optionId: reject.optionId } }
+          : { outcome: { outcome: "cancelled" } },
+      );
+    }
+    return replyErr(id, -32601, "method not implemented by panel client: " + method);
+  } catch (e) {
+    return replyErr(id, -32603, e instanceof Error ? e.message : String(e));
+  }
+}
+let collected = "";
+let rejections = 0;
+let updateCount = 0;
+rl.on("line", (line) => {
+  if (!line.trim()) {
+    return;
+  }
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  noteActivity();
+  if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+    const p = pending.get(msg.id);
+    if (p) {
+      pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(JSON.stringify(msg.error)));
+      else p.resolve(msg.result);
+    }
+    return;
+  }
+  if (msg.id !== undefined && msg.method) {
+    handleServerRequest(msg);
+    return;
+  }
+  if (msg.method === "session/update") {
+    const u = msg.params?.update;
+    if (
+      u?.sessionUpdate === "agent_message_chunk" &&
+      u.content &&
+      typeof u.content.text === "string"
+    ) {
+      collected += u.content.text;
+    }
+    updateCount++;
+    if (updateCount % 25 === 0) {
+      console.error(`[client] ${updateCount} session updates...`);
+    }
+    return;
+  }
+});
+let lastActivity = Date.now();
+let longestGapMs = 0;
+function noteActivity() {
+  const now = Date.now();
+  longestGapMs = Math.max(longestGapMs, now - lastActivity);
+  lastActivity = now;
+}
+const gapNote = () => `longest silent gap ${Math.round(longestGapMs / 1000)}s`;
+let deadlineHit = false;
+function abort(reason) {
+  deadlineHit = true;
+  console.error(`[client] ${reason} (${gapNote()}), killing server`);
+  try {
+    if (sessionId) send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+  } catch {}
+  setTimeout(() => {
+    child.kill("SIGKILL");
+    process.exit(124);
+  }, 2000).unref();
+}
+const timer = setTimeout(() => abort("HARD TIMEOUT"), HARD_TIMEOUT_MS).unref();
+const idleCheck = setInterval(
+  () => {
+    if (Date.now() - lastActivity > IDLE_MS) {
+      clearInterval(idleCheck);
+      abort(`IDLE TIMEOUT: no server message for ${Math.round(IDLE_MS / 1000)}s`);
+    }
+  },
+  Math.min(IDLE_MS / 4, 15000),
+).unref();
+let sessionId;
+try {
+  const init = await request("initialize", {
+    protocolVersion: 1,
+    clientCapabilities: { fs: { readTextFile: true, writeTextFile: false }, terminal: false },
+    clientInfo: { name: "acp-panel-client", version: "0.2.0" },
+  });
+  if (init.protocolVersion !== 1) throw new Error("ACP protocol version 1 required");
+  const agentName = (init.agentInfo && (init.agentInfo.name || init.agentInfo.title)) || "unknown";
+  isCodex = /codex/i.test(agentName);
+  console.error(`[client] initialized, protocol=${init.protocolVersion}, agent=${agentName}`);
+  send({ jsonrpc: "2.0", method: "initialized", params: {} });
+  const s = await request("session/new", { cwd, mcpServers: [] });
+  sessionId = s.sessionId;
+  if (typeof sessionId !== "string" || !sessionId) throw new Error("Missing session identity");
+  let options = s.configOptions || [];
+  const modeRequired = isCodex || options.some((o) => o.id === "mode");
+  const required = new Map();
+  // Set responses are complete snapshots; later changes must preserve earlier bindings.
+  async function bind(ids, value, optional = false) {
+    const matches = options.filter((o) => ids.includes(o.id));
+    if (matches.length !== 1) {
+      if (optional && !matches.length) return;
+      throw new Error(`agent exposes no unique ${ids.join("/")} option; cannot bind ${value}`);
+    }
+    const option = matches[0];
+    const values = (option.options || []).flatMap((o) => o.options || [o]);
+    if (!values.some((o) => o.value === value))
+      throw new Error(`Unsupported ${option.id} value: ${value}`);
+    required.set(option.id, value);
+    const res = await request("session/set_config_option", {
+      sessionId,
+      configId: option.id,
+      value,
+    });
+    if (!Array.isArray(res?.configOptions)) throw new Error(`Missing ${option.id} confirmation`);
+    options = res.configOptions;
+    for (const [id, expected] of required) {
+      const echoed = options.filter((o) => o.id === id);
+      if (echoed.length !== 1 || echoed[0].currentValue !== expected)
+        throw new Error(`Unverified ${id} binding`);
+    }
+    console.error(`[client] ${option.id} -> ${value}`);
+  }
+  if (modelArg) await bind(["model"], modelArg);
+  if (effortArg) await bind(["effort", "reasoning_effort"], effortArg);
+  await bind(["mode"], "read-only", !modeRequired);
+  console.error(
+    `[client] session ${sessionId}, maxTurns=${maxTurns}${verdictMarker ? `, verdictMarker=${JSON.stringify(verdictMarker)}` : ""}`,
+  );
+  let stopReason;
+  for (let turn = 1; turn <= maxTurns; turn++) {
+    const text =
+      turn === 1
+        ? promptText
+        : `Continue the panel task. Your previous reply did not contain ${JSON.stringify(verdictMarker)}. Do no new setup; use only read/glob/grep on the repo, no MCP tools, and now deliver the full answer ending with ${verdictMarker} plus a value. Keep it under 30 lines.`;
+    console.error(`[client] turn ${turn}/${maxTurns}, sending prompt (${text.length} chars)...`);
+    const rejectionsBefore = rejections;
+    const res = await request("session/prompt", {
+      sessionId,
+      prompt: [{ type: "text", text }],
+    });
+    stopReason = res?.stopReason;
+    if (deadlineHit) break;
+    const hit = verdictMarker ? collected.includes(verdictMarker) : true;
+    console.error(
+      `[client] turn ${turn} finished, stopReason=${JSON.stringify(stopReason)} collected=${collected.length} chars hasVerdict=${hit}`,
+    );
+    if (hit) {
+      break;
+    }
+    const cancelledByRejection = stopReason === "cancelled" && rejections > rejectionsBefore;
+    if (stopReason && stopReason !== "end_turn" && !cancelledByRejection) {
+      break;
+    }
+  }
+  clearTimeout(timer);
+  clearInterval(idleCheck);
+  child.stdin.end();
+  setTimeout(() => child.kill(), 1000).unref();
+  const ok = verdictMarker ? collected.includes(verdictMarker) : true;
+  const changed = statusBefore !== null && gitStatus() !== statusBefore;
+  if (changed) {
+    console.error(
+      `[client] WORKSPACE CHANGED: git status in ${cwd} differs from launch; the seat wrote files`,
+    );
+  }
+  // The answer is written after the status comparison so an output path inside the review
+  // root is not mistaken for a change the seat made.
+  writeFileSync(outText, collected);
+  console.error(`[client] wrote ${collected.length} chars to ${outText}; ${gapNote()}`);
+  process.exitCode = deadlineHit ? 124 : changed ? 4 : ok ? 0 : 3;
+  setTimeout(() => process.exit(), 2500).unref();
+} catch (e) {
+  console.error("[client] FATAL: " + (e instanceof Error ? e.message : String(e)));
+  clearTimeout(timer);
+  clearInterval(idleCheck);
+  child.kill("SIGKILL");
+  process.exit(deadlineHit ? 124 : 1);
+}

package/skills/hr-code-review/scripts/check-receipts.mjs

@@ -0,0 +1,263 @@
+// Checks the file:line citations in a panel's output against the repository.
+// See ../references/panel-adjudication.md.
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const EXT =
+  "(?:tsx?|jsx?|mjs|cjs|vue|svelte|css|scss|html|md|json|py|sh|yaml|yml|toml|go|rs|rb|java|kt|swift|php|cs|cpp|c|h)";
+const STRICT_RE = new RegExp(
+  "`([^`\\n]{1,80})`\\s*\\(\\s*([\\w./\\\\-]+\\." +
+    EXT +
+    ")\\s*:\\s*(\\d+)(?:\\s*-\\s*(\\d+))?\\s*\\)",
+  "g",
+);
+const BARE_RE = new RegExp("([\\w./\\\\-]+\\." + EXT + "):(\\d+)(?:-(\\d+))?", "g");
+
+// Panel logs are either plain text or JSON lines whose text parts hold the reply.
+export function extractPanelText(raw) {
+  const texts = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) {
+      continue;
+    }
+    try {
+      walk(JSON.parse(trimmed), texts);
+    } catch {
+      // Not JSON; ignore the line.
+    }
+  }
+  // A plain reply may contain a JSON example line; with no text parts, keep the raw text.
+  return texts.length === 0 ? raw : texts.join("");
+}
+
+function walk(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      walk(item, out);
+    }
+    return;
+  }
+  if (node && typeof node === "object") {
+    const { type, text } = node;
+    if ((type === "text" || type === "text-delta") && typeof text === "string") {
+      out.push(text);
+    }
+    for (const value of Object.values(node)) {
+      walk(value, out);
+    }
+  }
+}
+
+export function findCitations(text) {
+  const found = [];
+  const strictSpans = [];
+  for (const match of text.matchAll(STRICT_RE)) {
+    strictSpans.push([match.index, match.index + match[0].length]);
+    found.push({
+      ident: match[1],
+      file: match[2],
+      start: Number(match[3]),
+      end: Number(match[4] ?? match[3]),
+      strict: true,
+    });
+  }
+  for (const match of text.matchAll(BARE_RE)) {
+    const at = match.index;
+    if (strictSpans.some(([from, to]) => at >= from && at < to)) {
+      continue;
+    }
+    found.push({
+      ident: null,
+      file: match[1],
+      start: Number(match[2]),
+      end: Number(match[3] ?? match[2]),
+      strict: false,
+    });
+  }
+  return found;
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage"]);
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+const indexCache = new Map();
+
+// Models cite basenames (`util.ts:97`) or subpaths (`src/util.ts:97`). Resolve those against
+// the repository tree: one match wins, none fails as unreadable, several fail as ambiguous.
+function resolveByBasename(cited, repoRoot) {
+  if (!indexCache.has(repoRoot)) {
+    const index = [];
+    const walkDir = (dir) => {
+      let entries;
+      try {
+        entries = readdirSync(dir);
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry)) {
+          continue;
+        }
+        const full = join(dir, entry);
+        let stat;
+        try {
+          stat = statSync(full);
+        } catch {
+          continue;
+        }
+        if (stat.isDirectory()) {
+          walkDir(full);
+        } else if (stat.isFile()) {
+          index.push(full);
+        }
+      }
+    };
+    walkDir(repoRoot);
+    indexCache.set(repoRoot, index);
+  }
+  const normalized = cited.split(/[\\/]/).join("/");
+  const suffix = `/${normalized}`;
+  const matches = indexCache
+    .get(repoRoot)
+    .filter((path) => basename(path) === normalized || path.split(sep).join("/").endsWith(suffix));
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  return matches.length > 1 ? matches : null;
+}
+
+export function checkCitation(citation, repoRoot) {
+  const direct = isAbsolute(citation.file) ? citation.file : resolve(repoRoot, citation.file);
+  const path = isFile(direct) ? direct : resolveByBasename(citation.file, repoRoot);
+  if (path === null) {
+    return { ...citation, path: direct, status: "fail", reason: "unreadable: ENOENT" };
+  }
+  // Compare real paths so a symlink inside the repository cannot lead outside it.
+  let checkedPath = path;
+  if (typeof path === "string") {
+    try {
+      checkedPath = realpathSync(path);
+      const away = relative(realpathSync(repoRoot), checkedPath);
+      if (away === ".." || away.startsWith(`..${sep}`) || isAbsolute(away)) {
+        return { ...citation, path, status: "fail", reason: "outside the repository" };
+      }
+    } catch (error) {
+      return {
+        ...citation,
+        path,
+        status: "fail",
+        reason: `unreadable: ${error.code ?? String(error)}`,
+      };
+    }
+  }
+  if (Array.isArray(path)) {
+    return {
+      ...citation,
+      path: direct,
+      status: "fail",
+      reason: `ambiguous: ${path.length} matches`,
+    };
+  }
+  let lines;
+  try {
+    lines = readFileSync(checkedPath, "utf8").split("\n");
+    // A final newline ends the last line; it does not start another.
+    if (lines.length > 1 && lines.at(-1) === "") {
+      lines.pop();
+    }
+  } catch (error) {
+    return {
+      ...citation,
+      path,
+      status: "fail",
+      reason: `unreadable: ${error.code ?? String(error)}`,
+    };
+  }
+  if (!(citation.start >= 1) || citation.end < citation.start) {
+    return { ...citation, path, status: "fail", reason: "bad line range" };
+  }
+  if (citation.end > lines.length) {
+    return {
+      ...citation,
+      path,
+      status: "fail",
+      reason: `line ${citation.end} past EOF (${lines.length} lines)`,
+    };
+  }
+  if (citation.ident === null) {
+    return { ...citation, path, status: "pass", reason: "exists" };
+  }
+  const window = lines.slice(citation.start - 1, citation.end).join("\n");
+  if (!window.includes(citation.ident)) {
+    const range =
+      citation.end === citation.start ? `${citation.start}` : `${citation.start}-${citation.end}`;
+    return {
+      ...citation,
+      path,
+      status: "fail",
+      reason: `line ${range} lacks '${citation.ident}'`,
+    };
+  }
+  return { ...citation, path, status: "pass", reason: "cited" };
+}
+
+export function checkLogs(files, repoRoot) {
+  const results = [];
+  for (const file of files) {
+    const text = extractPanelText(readFileSync(file, "utf8"));
+    for (const citation of findCitations(text)) {
+      results.push({ log: file, ...checkCitation(citation, repoRoot) });
+    }
+  }
+  return results;
+}
+
+function main(argv) {
+  const json = argv.includes("--json");
+  const repoFlag = argv.indexOf("--repo");
+  const repoRoot = repoFlag >= 0 ? resolve(argv[repoFlag + 1] ?? ".") : process.cwd();
+  const files = argv.filter(
+    (arg, i) => arg !== "--json" && arg !== "--repo" && argv[i - 1] !== "--repo",
+  );
+  if (files.length === 0) {
+    console.error("Usage: check-receipts.mjs [--repo <dir>] [--json] <panel-log> [more...]");
+    return 2;
+  }
+  let results;
+  try {
+    results = checkLogs(files, repoRoot);
+  } catch (error) {
+    console.error(`Cannot read a panel log: ${error.message}`);
+    return 2;
+  }
+  if (results.length === 0) {
+    console.error("No citations found.");
+    return 2;
+  }
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    for (const row of results) {
+      const label = row.strict
+        ? `\`${row.ident}\` (${row.file}:${row.start})`
+        : `${row.file}:${row.start}`;
+      console.log(`${row.status === "pass" ? "PASS" : "FAIL"} ${label} - ${row.reason}`);
+    }
+    const failed = results.filter((row) => row.status === "fail").length;
+    console.log(`${results.length - failed}/${results.length} citations verified.`);
+  }
+  return results.some((row) => row.status === "fail") ? 1 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/skills/hr-code-review/scripts/panel-plan.mjs

@@ -0,0 +1,69 @@
+// Prints the panel a set of preferences resolves to, before any model is called.
+// See ../references/panel-plan.md.
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { formatPanelPlan, resolvePanel } from "./panel-preferences.mjs";
+
+function readJson(path, label) {
+  const file = resolve(path);
+  if (!lstatSync(file).isFile())
+    throw new Error(`${label} must be a regular file, not a symlink or directory`);
+  const text = readFileSync(file, "utf8");
+  try {
+    return { value: JSON.parse(text), revision: createHash("sha256").update(text).digest("hex") };
+  } catch {
+    throw new Error(`invalid JSON in ${label}`);
+  }
+}
+
+function main(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      config: { type: "string" },
+      bindings: { type: "string" },
+      project: { type: "string" },
+      "approve-project": { type: "string" },
+      task: { type: "string" },
+      "author-family": { type: "string", multiple: true },
+      "approve-metered": { type: "string", multiple: true },
+      json: { type: "boolean" },
+    },
+  });
+  if (values.bindings === undefined) throw new Error("--bindings <json> is required");
+  const config = readJson(
+    values.config ??
+      join(
+        process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+        "house-rules/house-rules.json",
+      ),
+    "configuration",
+  );
+  if (config.value.panel === undefined) throw new Error("configuration has no panel section");
+  const project =
+    values.project === undefined ? undefined : readJson(values.project, "project preferences");
+  const request = {
+    user: config.value.panel,
+    project: project?.value,
+    task: values.task === undefined ? undefined : readJson(values.task, "task preferences").value,
+    bindings: readJson(values.bindings, "bindings").value,
+    authorFamilies: values["author-family"] ?? [],
+    approvals: {
+      project: project !== undefined && values["approve-project"] === project.revision,
+      metered: values["approve-metered"] ?? [],
+    },
+  };
+  const plan = resolvePanel(request);
+  console.log(values.json ? JSON.stringify(plan, null, 2) : formatPanelPlan(plan));
+  return plan.ok ? 0 : 1;
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 2;
+}