@kaydash9999/banker-plugins 0.26.0 → 0.26.1

package/skills/make-evidence/scripts/evidence.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * evidence.mjs: the helper the make-evidence skill runs. It records commands into logs, checks the numbers written
+ * in the evidence documents against those logs, gives the oracle writer a room outside the repository, runs the
+ * seeded bugs in a separate worktree, and commits only the evidence paths. Pure Node, no dependencies, no network.
+ *
+ *   node evidence.mjs precheck [--repo <dir>]
+ *   node evidence.mjs run --log <file> [--timeout <s>] [--cwd <dir>] [--shell] -- <command...>
+ *   node evidence.mjs serve --log <file> --pid <file> --ready <url> [--wait <s>] [--cwd <dir>] [--shell] -- <command...>
+ *   node evidence.mjs stop --pid <file>
+ *   node evidence.mjs check [--repo <dir>] [--tracked]
+ *   node evidence.mjs count --doc <trace.md>
+ *   node evidence.mjs room [--repo <dir>] [--req <file>]...
+ *   node evidence.mjs collect --room <dir> [--repo <dir>] [--replace]
+ *   node evidence.mjs worktree [--repo <dir>] [--link <untracked dependency folder>]... | worktree --remove <dir>
+ *   node evidence.mjs bug --worktree <dir> --name <name> [--kind <kind> --baseline <log>] [--timeout <s>] [--shell] -- <oracle command...>
+ *   node evidence.mjs commit --message <text> [--paths <p>]... [--accept <file:line>]... [--repo <dir>]
+ *
+ * - A log name may hold {ts} or @TS@; it becomes a UTC time with milliseconds. An existing log is never overwritten.
+ * - A log starts with the command line (shell-quoted, secrets masked) and `# head= dirty= at= node= os= cwd=`, holds
+ *   stdout and stderr as they come (secrets masked), and ends with `# redacted=<n>`, `exit=<code>` (or
+ *   `exit=timeout(<s>s)`, `exit=interrupted(<signal>)`) and `METRIC run.exit=` plus the test counts it recognised.
+ * - Measured numbers go into a log as `METRIC <name.with.dots>=<value>`; a document cites them in backticks on a
+ *   line that names the log, and check looks for that exact line there.
+ * - Oracle output lines are `ORACLE <constraint|objective|permission> <PASS|FAIL|ERROR> <case> [note]`.
+ *
+ * Exit status: 0 done, 1 a check failed (numbers, room, tree changed, commit refused, unknown trace status), 2
+ * usage error or a step that could not run, 3 precheck found something the user must decide, 124 run hit its
+ * time limit; run otherwise passes the command's own exit code through.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { OWN, ORACLE, Usage } from "./me-git.mjs";
+import { runLogged, serve, stop } from "./me-run.mjs";
+import { precheck } from "./me-precheck.mjs";
+import { checkDocs, countTrace } from "./me-check.mjs";
+import { addWorktree, collectRoom, makeRoom, removeWorktree, runBug } from "./me-oracle.mjs";
+import { commitEvidence } from "./me-commit.mjs";
+
+const USAGE = `make-evidence: 증거 문서용 도우미(기록 실행, 수치 대조, 판정기 방, 버그 작업 트리, 증거만 커밋)
+사용법: node evidence.mjs <precheck|run|serve|stop|check|count|room|collect|worktree|bug|commit> [인자]
+  precheck  [--repo <dir>]                          스테이징, 미커밋 변경, 이 컴퓨터 밖 주소(설정, 환경 변수). 결정할 것이 있으면 종료 3
+  run       --log <file> [--timeout <s>] [--cwd <dir>] [--shell] -- <명령...>   기본 제한 300초
+  serve     --log <file> --pid <file> --ready <url> [--wait <s>] [--cwd <dir>] [--shell] -- <명령...>
+  stop      --pid <file>
+  check     [--repo <dir>] [--tracked]              문서의 \`이름.점=값\` 을 가리킨 로그의 METRIC 줄과 대조, 손 숫자 경고
+  count     --doc <trace.md>                        trace 표의 상태 칸을 세어 METRIC 줄로 출력
+  room      [--repo <dir>] [--req <file>]...         판정기 작성용 방(요구 문서와 owner-facts 만)
+  collect   --room <dir> [--repo <dir>] [--replace]  방의 tests/oracle 을 저장소로 가져옴
+  worktree  [--repo <dir>] [--link <폴더>]... | --remove <dir>   HEAD 의 별도 작업 트리
+  bug       --worktree <dir> --name <이름> [--kind <종류> --baseline <log>] [--timeout <s>] [--shell] -- <판정기 명령...>
+  commit    --message <text> [--paths <p>]... [--accept <file:line>]... [--repo <dir>]
+로그 이름의 {ts} 는 PowerShell 에서 따옴표로 감싸거나 @TS@ 로 씀`;
+
+const FLAGS = new Set(["--shell", "--tracked", "--replace"]);
+const MULTI = new Set(["--req", "--paths", "--link", "--accept"]);
+
+export function parseArgs(argv) {
+  const a = { _: [], rest: [], multi: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--") { a.rest = argv.slice(i + 1); break; }
+    if (FLAGS.has(t)) a[t.slice(2)] = true;
+    else if (t.startsWith("--")) {
+      if (i + 1 >= argv.length) throw new Usage(`${t} 에 값이 없음`);
+      const v = argv[++i];
+      if (MULTI.has(t)) (a.multi[t.slice(2)] ||= []).push(v);
+      else a[t.slice(2)] = v;
+    } else a._.push(t);
+  }
+  return a;
+}
+
+const need = (a, k) => { if (!a[k]) throw new Usage(`--${k} 가 필요함`); return a[k]; };
+const seconds = (v, d) => { const n = v === undefined ? d : Number(v); if (!(n > 0)) throw new Usage(`시간 값이 잘못됨: ${v}`); return n; };
+const say = (xs) => { for (const x of xs) console.log(x); };
+
+async function cmdRun(a) {
+  const r = await runLogged({ log: need(a, "log"), argv: a.rest, cwd: resolve(a.cwd || "."), timeoutS: seconds(a.timeout, 300), shell: !!a.shell });
+  console.log(`run: exit=${r.exit} log=${r.file}`);
+  return r.code;
+}
+
+async function cmdServe(a) {
+  const r = await serve({ log: need(a, "log"), pidFile: resolve(need(a, "pid")), ready: need(a, "ready"), waitS: seconds(a.wait, 60), argv: a.rest, cwd: resolve(a.cwd || "."), shell: !!a.shell });
+  console.log(`serve: ${r.ready ? "ready" : `${r.why}, stopped`} pid=${r.pid} log=${r.file}`);
+  return r.ready ? 0 : 2;
+}
+
+function cmdCheck(a) {
+  const c = checkDocs(a.repo || ".", { tracked: !!a.tracked });
+  say(c.errors.map((e) => `ERROR ${e}`));
+  say(c.warnings.map((w) => `WARN ${w}`));
+  say([`METRIC check.docs=${c.docs}`, `METRIC check.values=${c.tokens}`, `METRIC check.errors=${c.errors.length}`, `METRIC check.warnings=${c.warnings.length}`]);
+  return c.errors.length || c.warnings.length ? 1 : 0;
+}
+
+function cmdCount(a) {
+  const c = countTrace(readFileSync(need(a, "doc"), "utf8"));
+  say(c.unknownRows.map((n) => `ERROR 상태를 알 수 없는 행: ${a.doc}:${n}`));
+  say(["rows", "done", "partial", "notdone", "unverified", "unknown"].map((k) => `METRIC trace.${k}=${c[k]}`));
+  return c.unknown ? 1 : 0;
+}
+
+function cmdCollect(a) {
+  const r = collectRoom(resolve(need(a, "room")), a.repo, { replace: !!a.replace });
+  say(r.problems.map((p) => `ERROR ${p}`));
+  if (r.previous && !r.problems.length) console.log(`replaced ${ORACLE} 의 이전 커밋: ${r.previous}`);
+  say(r.made.map((f) => `oracle ${ORACLE}/${f}`));
+  return r.problems.length ? 1 : 0;
+}
+
+function cmdWorktree(a) {
+  if (a.remove) { removeWorktree(resolve(a.remove)); console.log(`removed ${resolve(a.remove)}`); return 0; }
+  console.log(addWorktree(a.repo || ".", a.multi.link || []));
+  return 0;
+}
+
+async function cmdBug(a) {
+  const r = await runBug({ wt: resolve(need(a, "worktree")), name: need(a, "name"), kind: a.kind, baseline: a.baseline && resolve(a.baseline), timeoutS: seconds(a.timeout, 300), argv: a.rest, shell: !!a.shell });
+  say([`bug: log=${r.log}${r.patch ? ` patch=${r.patch}` : ""}`, ...r.toRepo.map((p) => `WARN 링크한 폴더가 원래 트리를 가리킴: ${p}`), ...r.metrics.map((m) => `METRIC ${m}`)]);
+  return r.unchanged ? 0 : 1;
+}
+
+function cmdCommit(a) {
+  const r = commitEvidence(a.repo || ".", need(a, "message"), a.multi.paths || OWN, a.multi.accept || []);
+  if (r.refused) { say(r.refused.map((x) => `ERROR ${x}`)); return 1; }
+  say([`commit: ${r.sha}`, ...r.files.map((f) => `file ${f}`), ...r.outside.map((f) => `ERROR 증거 밖의 파일이 커밋됨: ${f}`)]);
+  return r.outside.length ? 1 : 0;
+}
+
+const COMMANDS = {
+  precheck: (a) => { const r = precheck(a.repo || "."); say(r.out); return r.decide ? 3 : 0; },
+  run: cmdRun,
+  serve: cmdServe,
+  stop: (a) => { const r = stop({ pidFile: resolve(need(a, "pid")) }); console.log(`stop: pid=${r.pid} log=${r.file}`); return 0; },
+  check: cmdCheck,
+  count: cmdCount,
+  room: (a) => { const r = makeRoom(a.repo || ".", a.multi.req); say([`room: ${r.dir}`, ...r.files.map((f) => `file ${f}`)]); return 0; },
+  collect: cmdCollect,
+  worktree: cmdWorktree,
+  bug: cmdBug,
+  commit: cmdCommit,
+};
+
+export async function main(argv) {
+  const [sub, ...rest] = argv;
+  if (!sub || sub === "--help" || sub === "-h") { console.log(USAGE); return sub ? 0 : 2; }
+  const fn = COMMANDS[sub];
+  if (!fn) { console.error(`make-evidence: 모르는 명령: ${sub}\n${USAGE}`); return 2; }
+  try {
+    return await fn(parseArgs(rest));
+  } catch (e) {
+    console.error(`make-evidence: ${e.message}`);
+    return 2;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

package/skills/make-evidence/scripts/me-check.mjs

@@ -0,0 +1,125 @@
+// make-evidence: checks the numbers in the evidence documents against the run logs, and counts trace statuses.
+// Pure Node, no network.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { EVIDENCE, gitOut, lines, topOf } from "./me-git.mjs";
+
+// A cited value: `<name>=<value>` in backticks, the name with at least one dot (scale.x5.median_s), so plain
+// code such as `exit=0` is not taken for one.
+const TOKEN = /`([A-Za-z][\w-]*(?:\.[\w-]+)+)=([^`\s]+)`/g;
+const LOGREF = /(?<=^|[\s|(\[`'"])(?:docs\/evidence\/)?logs\/[^\s`|)\]>"',]+/g;
+const CHECK_LINE = /^수치 대조: (?:docs\/evidence\/)?logs\/\S+$/;
+const WRITER = /^\$ (?:echo|printf|cat|type|tee|Write-Output|Set-Content|Out-File|Add-Content)\b/i;
+const SKIP_DOCS = new Set(["owner-facts.md"]);
+
+const logPath = (top, ref) => join(top, ref.startsWith("logs/") ? join(EVIDENCE, ref) : ref);
+
+// A .log the helper wrote: `$ <command>` then `# head=`. The METRIC lines in it, or why it is not one. Other files
+// under logs/ (patches, saved prompts) are checked for being there, and hold no citable numbers.
+function readLog(cache, file) {
+  if (!cache.has(file)) {
+    let entry;
+    if (!existsSync(file)) entry = { missing: true };
+    else if (!file.endsWith(".log")) entry = { metrics: new Set(), other: true }; // a patch or a saved prompt: it only has to exist
+    else {
+      const all = readFileSync(file, "utf8").split(/\r?\n/);
+      if (!all[0]?.startsWith("$ ") || !all[1]?.startsWith("# head=")) entry = { bad: "run 이 만든 로그가 아님(첫 두 줄)" };
+      else if (WRITER.test(all[0])) entry = { bad: `글을 찍기만 하는 명령의 로그: ${all[0].slice(0, 60)}` };
+      else if (all[0].includes("METRIC ")) entry = { bad: "명령 줄에 METRIC 글이 들어 있음(상수를 찍는 명령)" };
+      else entry = { metrics: new Set(all.filter((l) => l.startsWith("METRIC ")).map((l) => l.trim())) };
+    }
+    cache.set(file, entry);
+  }
+  return cache.get(file);
+}
+
+// Numbers that are not measurements: inline code, paths and file:line (a name with an extension), hashes (with a
+// letter), dates, versions, ids (R1, F2, M-3, c1), the multiples the skill uses (1배, 5배, 10배, x5), line counts
+// (10줄), steps (3단계), section and list numbers, a row number cell. Quoted text only where requirements are
+// quoted (quotes: true, trace.md). Everything else with a digit is reported.
+export function bareNumbers(line, { quotes = false } = {}) {
+  if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) return false;
+  let rest = line.replace(/^\s*#+\s*(?:\d+(?:\.\d+)*\.\s+)?/, " ").replace(/`[^`]*`/g, " ").replace(LOGREF, " ");
+  if (quotes) rest = rest.replace(/"[^"]*"|“[^”]*”|「[^」]*」/g, " ");
+  rest = rest
+    .replace(/\b[a-z][\w+.-]*:\/\/\S+/gi, " ").replace(/(?<!\S)(?:\.{0,2}\/|~\/)\S*/g, " ")
+    .replace(/(?<!\S)[\w.-]+(?:[/\\][\w.-]+)+\.[A-Za-z][\w]*(?::\d+(?:-\d+)?)?(?=$|[\s,);])/g, " ")
+    .replace(/(?<!\S)[\w.-]+\.(?:[cm]?[jt]sx?|py|java|kt|go|rs|rb|php|cs|sql|md|json|ya?ml|toml|sh|ps1|html|css|vue|svelte):\d+(?:-\d+)?/g, " ")
+    .replace(/\b(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b/g, " ")
+    .replace(/\b\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+Z?)?\b/g, " ").replace(/\bv\d+(?:\.\d+)*\b|\b\d+\.\d+\.\d+(?:\.\d+)?\b/g, " ")
+    .replace(/\b[A-Z]{1,3}-?\d+\b|\b(?!x\d)[a-z_]+\d+\b/g, " ").replace(/(?<![\d.])(?:1|5|10)배(?=\s*(?:데이터|입력|사례))|\bx(?:1|5|10)\b/g, " ")
+    .replace(/(?<!\d)10줄|\d\s*(?:단계|번째)/g, " ").replace(/^\s*\|\s*(?:\d{1,3}|(?:1|5|10)배)\s*\|/, "|").replace(/^\s*(?:\d+\.|[-*])\s+/, " ");
+  return /\d/.test(rest);
+}
+
+function checkRefs(ctx, at, refs) {
+  for (const ref of refs) {
+    const p = logPath(ctx.top, ref);
+    const log = readLog(ctx.cache, p);
+    if (log.missing) ctx.errors.push(`${at} 로그가 없음: ${ref}`);
+    else if (log.bad) ctx.errors.push(`${at} ${log.bad}: ${ref}`);
+    else if (ctx.tracked && !ctx.tracked.has(relative(ctx.top, p).split("\\").join("/"))) ctx.errors.push(`${at} 로그가 git 에 없음: ${ref}`);
+  }
+}
+
+function checkTokens(ctx, at, refs, line) {
+  for (const m of line.matchAll(TOKEN)) {
+    ctx.tokens++;
+    const want = `METRIC ${m[1]}=${m[2]}`;
+    if (!refs.length) ctx.errors.push(`${at} \`${m[1]}=${m[2]}\` 줄에 로그 경로가 없음`);
+    else if (!refs.some((r) => readLog(ctx.cache, logPath(ctx.top, r)).metrics?.has(want))) ctx.errors.push(`${at} 가리킨 로그에 \`${want}\` 줄이 없음`);
+  }
+}
+
+function checkDoc(ctx, name) {
+  let fenced = false;
+  readFileSync(join(ctx.top, EVIDENCE, name), "utf8").split(/\r?\n/).forEach((line, i) => {
+    const at = `${EVIDENCE}/${name}:${i + 1}`;
+    if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; return; }
+    if (fenced) return;
+    const all = line.match(LOGREF) || [];
+    if (CHECK_LINE.test(line.trim())) {
+      if (all.some((r) => /\{ts\}|@TS@|[<*]/.test(r))) ctx.errors.push(`${at} 수치 대조 줄이 실제 로그가 아니라 이름 꼴을 가리킴`);
+      checkRefs(ctx, at, all);
+      return;
+    }
+    const refs = all.filter((r) => !/\{ts\}|@TS@|[<*]/.test(r)); // a name pattern in a command, not a log
+    checkRefs(ctx, at, refs);
+    checkTokens(ctx, at, refs, line);
+    if (bareNumbers(line, { quotes: name === "trace.md" })) ctx.warnings.push(`${at} \`이름=값\` 밖의 숫자: ${line.trim().slice(0, 120)}`);
+  });
+}
+
+export function checkDocs(repo, { tracked = false } = {}) {
+  const top = topOf(repo);
+  const dir = join(top, EVIDENCE);
+  const ctx = { top, cache: new Map(), errors: [], warnings: [], tokens: 0, docs: 0 };
+  if (tracked) ctx.tracked = new Set(lines(gitOut(top, ["ls-files", "--", EVIDENCE])));
+  const names = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".md") && !SKIP_DOCS.has(f)).sort() : [];
+  for (const name of names) { ctx.docs++; checkDoc(ctx, name); }
+  return ctx;
+}
+
+// ---- trace counts ---------------------------------------------------------------------------------------------
+
+const STATUS = [["완료", "done"], ["부분", "partial"], ["미구현", "notdone"], ["미검증", "unverified"]];
+const cellsOf = (line) => line.trim().replace(/^\||\|$/g, "").split(/(?<!\\)\|/).map((s) => s.trim());
+
+// Counts the 상태 column, found by its heading. No heading with 상태 is an error; rows whose status is none of
+// the four are listed.
+export function countTrace(text) {
+  const c = { rows: 0, done: 0, partial: 0, notdone: 0, unverified: 0, unknown: 0, unknownRows: [] };
+  let col = -1;
+  text.split(/\r?\n/).forEach((line, i) => {
+    if (!line.trimStart().startsWith("|") || /^\s*\|[\s:|-]+\|\s*$/.test(line)) return;
+    const cells = cellsOf(line);
+    if (col < 0) { col = cells.indexOf("상태"); return; }
+    if (cells.includes("상태")) return; // a second table's heading
+    c.rows++;
+    const hit = STATUS.find(([k]) => (cells[col] || "").startsWith(k));
+    if (hit) c[hit[1]]++;
+    else { c.unknown++; c.unknownRows.push(i + 1); }
+  });
+  if (col < 0) throw new Error("trace 표에 `상태` 칸이 있는 머리 줄이 없음");
+  return c;
+}

package/skills/make-evidence/scripts/me-commit.mjs

@@ -0,0 +1,48 @@
+// make-evidence: commits only the evidence paths. Ignored files are forced in only for the run logs and patches
+// under docs/evidence/logs; .env files, big files and text that still looks like a secret stop the commit.
+// Commit hooks run. Pure Node, no network.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { EVIDENCE, OWN, git, gitOut, headOf, lines, topOf } from "./me-git.mjs";
+import { secretLines } from "./me-run.mjs";
+
+const MAX_FILE = 5 * 1024 * 1024;
+const FORCE = new RegExp(`^${EVIDENCE}/logs/[^/]+\\.(log|patch|md)$`);
+const NEVER = /(^|\/)(\.env[^/]*|node_modules|__pycache__|\.venv)(\/|$)/;
+const under = (f, paths) => paths.some((p) => f === p || f.startsWith(`${p}/`));
+
+function candidates(top, paths) {
+  const normal = lines(gitOut(top, ["ls-files", "--modified", "--others", "--deleted", "--exclude-standard", "--", ...paths]));
+  const ignored = lines(gitOut(top, ["ls-files", "--others", "--ignored", "--exclude-standard", "--", ...paths]));
+  return { normal: [...new Set(normal)], forced: ignored.filter((f) => FORCE.test(f)) };
+}
+
+// accept: exact file:line places the user confirmed are not secrets.
+function refusals(top, files, accept = []) {
+  const out = [];
+  for (const f of files) {
+    if (NEVER.test(f)) { out.push(`넣지 않는 파일: ${f}`); continue; }
+    let st;
+    try { st = statSync(join(top, f)); } catch { continue; } // a deletion
+    if (st.size > MAX_FILE) { out.push(`5MB 넘는 파일: ${f}`); continue; }
+    const hits = secretLines(readFileSync(join(top, f), "utf8")).filter((n) => !accept.includes(`${f}:${n}`));
+    for (const n of hits.slice(0, 5)) out.push(`비밀값 꼴이 남음: ${f}:${n} (값을 가리거나, 비밀값이 아니면 --accept ${f}:${n})`);
+  }
+  return out;
+}
+
+export function commitEvidence(repo, message, paths = OWN, accept = []) {
+  const top = topOf(repo);
+  const foreign = lines(gitOut(top, ["diff", "--cached", "--name-only"])).filter((f) => !under(f, paths));
+  if (foreign.length) return { refused: [`증거 밖의 스테이징된 변경이 있음: ${foreign.join(", ")}`] };
+  const { normal, forced } = candidates(top, paths);
+  if (!normal.length && !forced.length) return { refused: [`커밋할 것이 없음: ${paths.join(", ")}`] };
+  const refused = refusals(top, [...normal, ...forced], accept);
+  if (refused.length) return { refused };
+  if (normal.length) gitOut(top, ["add", "-A", "--", ...normal]);
+  if (forced.length) gitOut(top, ["add", "-f", "--", ...forced]);
+  const r = git(top, ["commit", "-m", message, "--", ...new Set([...normal, ...forced])]);
+  if (r.status !== 0) return { refused: [`git commit 실패(훅은 우회하지 않음): ${String(r.stdout + r.stderr).trim().split("\n").slice(-3).join(" / ")}`] };
+  const files = lines(gitOut(top, ["show", "--name-only", "--format=", "HEAD"]));
+  return { sha: headOf(top), files, outside: files.filter((f) => !under(f, paths)) };
+}

package/skills/make-evidence/scripts/me-git.mjs

@@ -0,0 +1,63 @@
+// make-evidence: git calls, the evidence paths and a fingerprint of the user's work tree. Pure Node, no network.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const EVIDENCE = "docs/evidence";
+export const ORACLE = "tests/oracle";
+export const OWN = [EVIDENCE, ORACLE];
+export const EXCLUDE = OWN.map((p) => `:(exclude)${p}`);
+export const KINDS = ["constraint", "objective", "permission"];
+export const MAX_TEXT = 4 * 1024 * 1024;
+
+export class Usage extends Error {}
+
+// Programs start from the home folder (Windows looks for a program in the working folder first); git gets the
+// folder through -C.
+export const runDir = () => (existsSync(homedir()) ? homedir() : tmpdir());
+
+export function git(cwd, args, extra = {}) {
+  const r = spawnSync("git", ["-C", resolve(cwd), ...args], { cwd: runDir(), encoding: "utf8", maxBuffer: 256 * 1024 * 1024, windowsHide: true, ...extra });
+  if (r.error) throw new Error(`git 을 실행하지 못함: ${r.error.message}`);
+  return r;
+}
+
+export function gitOut(cwd, args) {
+  const r = git(cwd, args);
+  if (r.status !== 0) throw new Error(`git ${args.filter((a) => !a.startsWith(":(")).join(" ")} 실패: ${String(r.stderr).trim().split("\n").pop()}`);
+  return r.stdout;
+}
+
+export const lines = (s) => String(s).split(/\r?\n/).filter(Boolean);
+export const topOf = (dir) => gitOut(dir, ["rev-parse", "--show-toplevel"]).trim();
+export const headOf = (dir) => gitOut(dir, ["rev-parse", "HEAD"]).trim();
+
+// What git sees changed outside the evidence paths (tracked and untracked).
+export const otherStatus = (repo) => gitOut(repo, ["--no-optional-locks", "status", "--porcelain", "--untracked-files=all", "--", ".", ...EXCLUDE]);
+
+export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+
+function fileHash(file) {
+  try {
+    const st = lstatSync(file);
+    return st.isFile() ? sha256(readFileSync(file)) : `${st.isSymbolicLink() ? "link" : "other"}`;
+  } catch {
+    return "gone";
+  }
+}
+
+// The user's work tree outside the evidence paths: the status lines, the content of tracked changes and of every
+// untracked file. Two equal prints mean nothing there changed (ignored files are not covered).
+export function treePrint(top) {
+  const status = otherStatus(top);
+  const diff = gitOut(top, ["--no-optional-locks", "diff", "HEAD", "--binary", "--", ".", ...EXCLUDE]);
+  const untracked = lines(gitOut(top, ["ls-files", "--others", "--exclude-standard", "--", ".", ...EXCLUDE]));
+  return sha256(`${status}\0${diff}\0${untracked.map((f) => `${f}:${fileHash(join(top, f))}`).join("\n")}`);
+}
+
+export function stamp(d = new Date()) {
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}-${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}-${p(d.getUTCMilliseconds(), 3)}Z`;
+}

package/skills/make-evidence/scripts/me-oracle.mjs

@@ -0,0 +1,244 @@
+// make-evidence: the oracle writer's room, and the seeded bugs run in a separate worktree of HEAD. The user's work
+// tree is never written. Pure Node, no network.
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { EVIDENCE, EXCLUDE, KINDS, ORACLE, Usage, git, gitOut, headOf, lines, sha256, topOf, treePrint } from "./me-git.mjs";
+import { claimLog, runLogged } from "./me-run.mjs";
+
+// Inside means below, not equal; a path on another Windows drive is outside (relative() returns it absolute).
+export const inside = (top, p) => { const r = relative(top, p); return r !== "" && !r.startsWith("..") && !isAbsolute(r); };
+const slash = (p) => p.split("\\").join("/");
+
+function walk(dir, base = dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p, base));
+    else out.push(slash(relative(base, p)));
+  }
+  return out;
+}
+
+// ---- room -----------------------------------------------------------------------------------------------------
+
+// The room is <base>/room; its note (the repository path and the input list) is <base>/room.json, outside the
+// room, so the oracle writer does not learn where the repository is.
+const noteOf = (roomDir) => join(dirname(roomDir), "room.json");
+
+export function makeRoom(repo, req = ["README.md"]) {
+  const top = topOf(repo);
+  const files = [...req, `${EVIDENCE}/owner-facts.md`];
+  const dir = join(mkdtempSync(join(tmpdir(), "make-evidence-room-")), "room");
+  if (inside(top, dir)) throw new Error(`임시 폴더가 저장소 안에 있음: ${dir}`);
+  mkdirSync(dir);
+  for (const f of files) {
+    const src = join(top, f);
+    if (!existsSync(src) || !lstatSync(src).isFile()) throw new Error(`방에 넣을 파일이 없음: ${f}`);
+    mkdirSync(dirname(join(dir, f)), { recursive: true });
+    cpSync(src, join(dir, f));
+  }
+  mkdirSync(join(dir, ORACLE), { recursive: true });
+  writeFileSync(noteOf(dir), JSON.stringify({ repo: top, files }, null, 2));
+  return { dir, files };
+}
+
+// What the room holds beside the oracle: only the input files, unchanged.
+function roomProblems(roomDir, top, files) {
+  const problems = [];
+  for (const f of walk(roomDir)) {
+    if (f.startsWith(`${ORACLE}/`)) continue;
+    if (!files.includes(f)) problems.push(`방에 허용하지 않은 파일: ${f}`);
+    else if (!readFileSync(join(roomDir, f)).equals(readFileSync(join(top, f)))) problems.push(`입력 파일이 바뀜: ${f}`);
+  }
+  return problems;
+}
+
+const isFilled = (dir) => existsSync(dir) && readdirSync(dir).length > 0;
+
+export function collectRoom(roomDir, repo, { replace = false } = {}) {
+  const note = JSON.parse(readFileSync(noteOf(roomDir), "utf8"));
+  const top = repo ? topOf(repo) : note.repo;
+  const problems = roomProblems(roomDir, top, note.files);
+  const made = existsSync(join(roomDir, ORACLE)) ? walk(join(roomDir, ORACLE)) : [];
+  if (!made.length) problems.push(`${ORACLE}/ 에 파일이 없음`);
+  const dest = join(top, ORACLE);
+  if (!replace && isFilled(dest)) problems.push(`${ORACLE}/ 가 이미 있음(판정기 빈틈을 고친 새 판정기일 때만 --replace)`);
+  const previous = lines(gitOut(top, ["log", "-1", "--format=%h %ad %s", "--date=iso", "--", ORACLE]))[0] || null;
+  if (problems.length) return { problems, made, previous };
+  rmSync(dest, { recursive: true, force: true });
+  cpSync(join(roomDir, ORACLE), dest, { recursive: true });
+  return { problems, made, previous };
+}
+
+// ---- worktree and links ---------------------------------------------------------------------------------------
+
+const META = "meta.json";
+const BUILD_DIR = /^(dist|build|out|target|\.next|\.nuxt|\.output|bin|obj|coverage|lib)$/i;
+const metaOf = (wt) => JSON.parse(readFileSync(join(dirname(wt), META), "utf8"));
+
+function checkLink(top, p) {
+  const src = resolve(top, p);
+  const rel = relative(top, src);
+  if (!inside(top, src)) throw new Usage(`--link 는 저장소 안의 경로만: ${p}`);
+  if (!existsSync(src)) throw new Usage(`--link 경로가 없음: ${p}`);
+  if (BUILD_DIR.test(basename(src))) throw new Usage(`--link 로 빌드 결과를 잇지 않음(버그를 넣은 빌드가 사용자 폴더에 써짐): ${p}. 작업 트리 안에서 새로 빌드함`);
+  if (/^\.env/i.test(basename(src))) throw new Usage(`--link 로 .env 를 잇지 않음: ${p}`);
+  if (lines(gitOut(top, ["ls-files", "--", rel])).length) throw new Usage(`--link 는 추적되지 않는 폴더만(추적되는 파일은 작업 트리에 이미 있음): ${p}`);
+  return rel;
+}
+
+// A linked folder's print (files, bytes, latest change) and the links in it that lead back into the main tree:
+// symbolic links resolving there (workspace packages), .pth and egg-link files naming it (editable installs).
+export function scanLinked(top, root) {
+  const s = { files: 0, bytes: 0, mtime: 0, toRepo: [] };
+  const real = realpathSync(top);
+  const visit = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      const st = lstatSync(p);
+      s.files++; s.bytes += st.size; s.mtime = Math.max(s.mtime, st.mtimeMs);
+      if (e.isSymbolicLink()) {
+        let to; try { to = realpathSync(p); } catch { to = resolve(dir, readlinkSync(p)); }
+        if (inside(real, to) && !inside(realpathSync(root), to)) s.toRepo.push(slash(relative(top, p)));
+      } else if (e.isDirectory()) visit(p);
+      else if (/\.(pth|egg-link)$|^__editable__/.test(e.name) && st.size < 65536 && readFileSync(p, "utf8").includes(real)) s.toRepo.push(slash(relative(top, p)));
+    }
+  };
+  visit(root);
+  return s;
+}
+
+export function addWorktree(repo, links = []) {
+  const top = topOf(repo);
+  const rels = links.map((p) => checkLink(top, p));
+  const base = mkdtempSync(join(tmpdir(), "make-evidence-wt-"));
+  const wt = join(base, "wt");
+  gitOut(top, ["worktree", "add", "--detach", wt, "HEAD"]);
+  writeFileSync(join(base, META), JSON.stringify({ repo: top, links: rels }));
+  // The oracle and the evidence scripts as they are now, committed or not, so the run uses them.
+  for (const p of [ORACLE, `${EVIDENCE}/scripts`]) {
+    if (!existsSync(join(top, p))) continue;
+    rmSync(join(wt, p), { recursive: true, force: true });
+    cpSync(join(top, p), join(wt, p), { recursive: true });
+  }
+  for (const rel of rels) {
+    mkdirSync(dirname(join(wt, rel)), { recursive: true });
+    symlinkSync(join(top, rel), join(wt, rel), "junction");
+  }
+  return wt;
+}
+
+export function removeWorktree(wt) {
+  const { repo, links } = metaOf(wt);
+  for (const rel of links) {
+    const at = join(wt, rel);
+    try { if (lstatSync(at).isSymbolicLink()) rmSync(at); } catch { /* not there */ } // the link, never its target
+  }
+  git(repo, ["worktree", "remove", "--force", wt]);
+  git(repo, ["worktree", "prune"]);
+  rmSync(dirname(wt), { recursive: true, force: true });
+}
+
+// ---- oracle lines and the verdict -----------------------------------------------------------------------------
+
+const ORACLE_LINE = /^ORACLE (constraint|objective|permission) (PASS|FAIL|ERROR)\s+(\S+)/;
+
+export function oracleResults(text) {
+  const r = Object.fromEntries(KINDS.map((k) => [k, { pass: new Set(), fail: new Set(), error: new Set() }]));
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.trim().match(ORACLE_LINE);
+    if (m) r[m[1]][m[2].toLowerCase()].add(m[3]);
+  }
+  return r;
+}
+
+const casesOf = (r) => new Set(KINDS.flatMap((k) => [...r[k].pass, ...r[k].fail, ...r[k].error].map((c) => `${k}:${c}`)));
+const sameSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+
+// caught: a FAIL of the bug's kind the baseline did not have, in a run that judged the same cases as the baseline
+// and gave no ERROR. Anything that does not show the oracle judging the implementation is undecidable.
+export function judge(text, kind, baseText, timedOut) {
+  const cur = oracleResults(text), base = oracleResults(baseText);
+  const collateral = KINDS.filter((k) => k !== kind).reduce((n, k) => n + [...cur[k].fail].filter((c) => !base[k].fail.has(c)).length, 0);
+  const undecided = (reason) => ({ result: "undecidable", reason, collateral });
+  if (timedOut) return undecided("timeout");
+  if (KINDS.some((k) => cur[k].error.size)) return undecided("oracle-error");
+  if (!base[kind].pass.size) return undecided("baseline-no-pass");
+  if (!sameSet(casesOf(cur), casesOf(base))) return undecided("cases-differ");
+  const caught = [...cur[kind].fail].some((c) => !base[kind].fail.has(c));
+  return { result: caught ? "caught" : "missed", reason: caught ? "new-fail" : "no-new-fail", collateral };
+}
+
+export function oracleSha(wt) {
+  const dir = join(wt, ORACLE);
+  return existsSync(dir) ? sha256(walk(dir).sort().map((f) => `${f}:${sha256(readFileSync(join(dir, f)))}`).join("\n")).slice(0, 16) : "none";
+}
+
+// ---- the bug run ----------------------------------------------------------------------------------------------
+
+const metricOf = (text, name) => (text.match(new RegExp(`^METRIC ${name.replace(/\./g, "\\.")}=(\\S+)$`, "m")) || [])[1];
+
+function checkBugArgs(name, kind, baseline) {
+  if (!/^[\w-]+$/.test(name || "")) throw new Usage("--name 은 영문, 숫자, - 와 _ 만");
+  if (name === "baseline") return;
+  if (!KINDS.includes(kind)) throw new Usage(`--kind 는 ${KINDS.join(", ")} 가운데 하나`);
+  if (!baseline || !existsSync(baseline)) throw new Usage("--baseline <기준선 로그> 가 필요함(먼저 --name baseline 으로 돌림)");
+}
+
+// The baseline must be of this HEAD and this oracle.
+function checkBaseline(wt, baseText) {
+  const head = (baseText.match(/^# head=(\S+)/m) || [])[1];
+  if (head !== headOf(wt)) throw new Usage(`기준선의 HEAD(${head})가 지금 HEAD 와 다름. 기준선을 다시 돌림`);
+  const sha = metricOf(baseText, "bug.baseline.oracle_sha");
+  if (sha !== oracleSha(wt)) throw new Usage("기준선의 판정기가 지금 판정기와 다름. 기준선을 다시 돌림");
+}
+
+function verdictMetrics(name, kind, run, text, baseText, linked) {
+  const m = [`bug.${name}.exit=${run.exit}`];
+  if (name === "baseline") {
+    const r = oracleResults(text);
+    for (const k of KINDS) m.push(`baseline.${k}.pass=${r[k].pass.size}`, `baseline.${k}.fail=${r[k].fail.size}`, `baseline.${k}.error=${r[k].error.size}`);
+    return m;
+  }
+  let v = judge(text, kind, baseText, run.code === 124);
+  if (linked.toRepo.length) v = { ...v, result: "undecidable", reason: "link-to-main" };
+  m.push(`bug.${name}.kind=${kind}`, `bug.${name}.result=${v.result}`, `bug.${name}.reason=${v.reason}`, `bug.${name}.collateral=${v.collateral}`);
+  return m;
+}
+
+function linkedPrints(top, links) {
+  const all = links.map((rel) => scanLinked(top, join(top, rel)));
+  return { key: JSON.stringify(all.map((s) => [s.files, s.bytes, s.mtime])), toRepo: all.flatMap((s) => s.toRepo) };
+}
+
+async function bugBody({ wt, name, kind, baseText, timeoutS, argv, shell }) {
+  const { repo: top, links } = metaOf(wt);
+  const logs = join(top, EVIDENCE, "logs");
+  const diff = gitOut(wt, ["diff", "--", ".", ...EXCLUDE]);
+  if (name === "baseline" ? diff.trim() : !diff.trim()) throw new Error(name === "baseline" ? "기준선인데 작업 트리에 바뀐 것이 있음" : "작업 트리에 넣은 버그가 없음(추적되는 파일을 고침)");
+  if (name !== "baseline") checkBaseline(wt, baseText);
+  const before = { tree: treePrint(top), linked: linkedPrints(top, links) };
+  const patch = name === "baseline" ? null : claimLog(join(logs, `verify-bug-${name}-{ts}.patch`));
+  if (patch) writeFileSync(patch, diff);
+  const run = await runLogged({ log: join(logs, `verify-bug-${name}-{ts}.log`), argv, cwd: wt, timeoutS, shell });
+  const metrics = verdictMetrics(name, kind, run, readFileSync(run.file, "utf8"), baseText, before.linked);
+  metrics.push(`bug.${name}.oracle_sha=${oracleSha(wt)}`, `bug.${name}.links_to_repo=${before.linked.toRepo.length}`);
+  return { top, links, run, patch, metrics, before };
+}
+
+export async function runBug({ wt, name, kind, baseline, timeoutS = 300, argv, shell = false }) {
+  checkBugArgs(name, kind, baseline);
+  if (!argv.length) throw new Usage("판정기 명령이 없음(-- 뒤에 씀)");
+  let r;
+  try {
+    r = await bugBody({ wt, name, kind, baseText: baseline ? readFileSync(baseline, "utf8") : "", timeoutS, argv, shell });
+  } finally {
+    removeWorktree(wt);
+  }
+  const treeSame = treePrint(r.top) === r.before.tree;
+  const linkedSame = linkedPrints(r.top, r.links).key === r.before.linked.key;
+  r.metrics.push(`bug.${name}.tree_unchanged=${treeSame ? "yes" : "no"}`, `bug.${name}.links_unchanged=${linkedSame ? "yes" : "no"}`);
+  writeFileSync(r.run.file, `${readFileSync(r.run.file, "utf8")}${r.metrics.map((m) => `METRIC ${m}`).join("\n")}\n`);
+  return { log: r.run.file, patch: r.patch, metrics: r.metrics, unchanged: treeSame && linkedSame, toRepo: r.before.linked.toRepo };
+}