@kaydash9999/banker-plugins 0.21.0 → 0.23.0

package/skills/ultraqa/references/uqa-run.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * uqa-run: the run folder and the machine checks of banker's ultraqa (Claude Code only). The model plans, fixes and
+ * writes; this program keeps the state as data and says when COMPLETE may be claimed.
+ *
+ *   node uqa-run.mjs init --repo <repo> --gates <a,b,...> [--resume]
+ *        a new run folder (run-folder.mjs) with state.md, or with --resume the unfinished run of the same repo (by real
+ *        path) whose HEAD and work tree fingerprint are still the same
+ *   node uqa-run.mjs row --dir <d>            one scenario row (JSON on stdin) into matrix.md, by its id
+ *   node uqa-run.mjs status --dir <d>         same-failure, max-cycles, matrix-incomplete, stale-evidence, gates
+ *   node uqa-run.mjs finish --dir <d> --end complete|max-cycles|same-failure|blocked|error [--why <text>]
+ *        the end line; complete only when status allows it, max-cycles and same-failure only when status says so
+ *   node uqa-run.mjs report --dir <d>         the report skeleton (markdown): observed and reported apart
+ *   node uqa-run.mjs cleanup --dir <d>        that run folder alone; paths the matrix names outside it are reported only
+ *
+ * The gate commands run through gate-evidence.mjs (`run --iter <cycle>`), in the same folder. Out: JSON on stdout
+ * (report: markdown); exit 0 done, 1 a check that does not hold, 2 usage or internal error, 3 a stop.
+ */
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLASSES, gateConjunct, readEvidence, repeatedFailures } from "./gate-evidence.mjs";
+import { Stop, bases, makeRunFolder, removeRunFolder, requireGitTree, runFolder, snapshot } from "./run-folder.mjs";
+
+const KIND = ["ultraqa"];
+export const MAX_CYCLES = 5;
+const STATUSES = ["pass", "fail", "blocked", "excluded"];
+const ROW_KEYS = ["id", "class", "intent", "model", "setup", "command", "expected", "status", "evidenceRef", "excludeReason", "cleanup"];
+const END_LINES = {
+  complete: (n) => `ULTRAQA COMPLETE: Goal met after ${n} cycles`,
+  "max-cycles": () => "ULTRAQA STOPPED: Max cycles",
+  "same-failure": () => "ULTRAQA STOPPED: Same failure detected 3 times",
+  blocked: (_n, why) => `ULTRAQA BLOCKED: ${why}`,
+  error: (_n, why) => `ULTRAQA ERROR: ${why}`,
+};
+
+class Usage extends Error {}
+const readJson = (p, fallback) => {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return fallback;
+  }
+};
+const readState = (d) => {
+  const s = readJson(join(d, "state.md"), null);
+  if (!s) throw new Stop("no-state", `state.md 가 없거나 읽을 수 없다: ${d}`);
+  return s;
+};
+const writeState = (d, s) => writeFileSync(join(d, "state.md"), `${JSON.stringify(s, null, 2)}\n`, { mode: 0o600 });
+export function readMatrix(d) {
+  let text = "";
+  try {
+    text = readFileSync(join(d, "matrix.md"), "utf8");
+  } catch {
+    return [];
+  }
+  return text.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+const realRepo = (repo) => {
+  try {
+    return realpathSync.native(resolve(repo));
+  } catch {
+    throw new Stop("no-repo", `저장소 폴더가 없다: ${repo}`);
+  }
+};
+const gatesOf = (v) => String(v || "").split(",").map((g) => g.trim()).filter(Boolean);
+
+// ---- the checks (pure)
+
+// A passed row rests on a scenario record of this cycle that passed and is that scenario's last record of the cycle:
+// observed, its id scenario-*, verdict pass. A goal gate's record, a failed one, one of an earlier cycle or a pass a
+// rerun of the same scenario has since failed is no ground for it (staleCheck adds the tree).
+function restsOn(r, observed, cycle) {
+  const rec = Number.isInteger(r.evidenceRef) ? observed.find((x) => x.seq === r.evidenceRef) : null;
+  if (!rec || !String(rec.id).startsWith("scenario-") || rec.verdict !== "pass" || rec.iter !== cycle) return false;
+  return observed.filter((x) => x.id === rec.id && x.iter === cycle).pop() === rec;
+}
+
+// The record numbers two or more passed rows cite: one scenario run covers one row, never several classes at once.
+const sharedRefs = (rows) => {
+  const seen = new Map();
+  for (const r of rows.filter((x) => x.status === "pass")) seen.set(r.evidenceRef, (seen.get(r.evidenceRef) || 0) + 1);
+  return new Set([...seen].filter(([, n]) => n > 1).map(([ref]) => ref));
+};
+
+// The matrix: every class has a row or is excluded with a reason; a row's status is one of four; a passed row names
+// the passing scenario record of this cycle it rests on, a record no other passed row cites; a failed or blocked row
+// is still open.
+export function matrixCheck(rows, evidence = [], cycle = 0) {
+  const observed = evidence.filter((r) => r?.kind === "observed");
+  const missing = CLASSES.map(([id]) => id).filter((c) => !rows.some((r) => r.class === c && (r.status !== "excluded" || String(r.excludeReason || "").trim())));
+  const shared = sharedRefs(rows);
+  const bad = rows.filter((r) => !STATUSES.includes(r.status) || (r.status === "pass" && (shared.has(r.evidenceRef) || !restsOn(r, observed, cycle)))).map((r) => r.id);
+  const open = rows.filter((r) => r.status === "fail" || r.status === "blocked").map((r) => r.id);
+  return { ok: rows.length > 0 && !missing.length && !bad.length && !open.length, missing, bad, open };
+}
+
+// Each goal gate's last observed record, and each record a passed row rests on, was made on the tree as it is now.
+export function staleCheck(evidence, gates, rows, fingerprint) {
+  const observed = evidence.filter((r) => r.kind === "observed");
+  const last = gates.map((g) => observed.filter((r) => r.id === g).pop()).filter(Boolean);
+  const cited = rows.filter((r) => r.status === "pass").map((r) => observed.find((x) => x.seq === r.evidenceRef) || { seq: r.evidenceRef, fingerprint: null });
+  const stale = [...last, ...cited].filter((r) => r.fingerprint !== fingerprint).map((r) => r.seq);
+  return { ok: stale.length === 0 && last.length === gates.length, stale, unrun: gates.filter((g) => !observed.some((r) => r.id === g)) };
+}
+
+// The goal gates as records: `interactive` is the drive scripts' scenario-* records (references/tmux-drive.md), as
+// ralph-qa's `scenarios` is; with none it stays `interactive` (never run).
+export function goalGates(gates, evidence) {
+  const scenarios = [...new Set(evidence.filter((r) => r?.kind === "observed" && String(r.id).startsWith("scenario-")).map((r) => r.id))];
+  return gates.flatMap((g) => (g !== "interactive" ? [g] : scenarios.length ? scenarios : [g]));
+}
+
+export function statusOf({ evidence, rows, gates, fingerprint }) {
+  const observed = evidence.filter((r) => r.kind === "observed");
+  const cycle = Math.max(0, ...observed.map((r) => r.iter));
+  const same = repeatedFailures(evidence);
+  const goal = goalGates(gates, evidence);
+  const checks = {
+    sameFailure: { ok: same.length === 0, signatures: same },
+    maxCycles: { ok: cycle <= MAX_CYCLES, cycle, max: MAX_CYCLES },
+    matrix: matrixCheck(rows, evidence, cycle),
+    staleEvidence: staleCheck(evidence, goal, rows, fingerprint),
+    gates: gateConjunct(evidence, goal, fingerprint, cycle),
+  };
+  const complete = Object.values(checks).every((c) => c.ok);
+  return { complete, cycle, checks, next: nextLine(complete, checks, cycle) };
+}
+
+function nextLine(complete, checks, cycle) {
+  if (complete) return END_LINES.complete(cycle);
+  if (!checks.sameFailure.ok) return END_LINES["same-failure"]();
+  return cycle >= MAX_CYCLES ? END_LINES["max-cycles"]() : null;
+}
+
+// Whether `end` may be claimed with this status: COMPLETE only when every check holds; the two STOPPED lines only
+// when status says so; BLOCKED and ERROR need a reason.
+const needsWhy = (_st, why) => (String(why || "").trim() ? null : "--why 가 필요하다");
+const END_RULES = {
+  complete: (st) => (st.complete ? null : `COMPLETE 를 거부한다: ${Object.entries(st.checks).filter(([, c]) => !c.ok).map(([k]) => k).join(", ")}`),
+  "same-failure": (st) => (st.checks.sameFailure.ok ? "같은 실패 3회가 기록에 없다" : null),
+  "max-cycles": (st) => (st.cycle >= MAX_CYCLES ? null : `순환이 ${st.cycle} 번이라 아직 한도가 아니다`),
+  blocked: needsWhy,
+  error: needsWhy,
+};
+export function endAllowed(end, st, why) {
+  return Object.prototype.hasOwnProperty.call(END_RULES, end) ? END_RULES[end](st, why) : `모르는 종료다: ${end}`;
+}
+
+// ---- commands
+
+async function current(d, ctx) {
+  const state = readState(d);
+  const evidence = readEvidence(d);
+  const snap = await snapshot(state.repo, ctx.env);
+  return { state, evidence, rows: readMatrix(d), fingerprint: snap.fingerprint, head: snap.head };
+}
+
+async function init(o, ctx) {
+  const repo = realRepo(o.repo);
+  const gates = gatesOf(o.gates);
+  if (!gates.length) throw new Usage("--gates 에 목표 게이트를 하나 이상 준다(tests, build, lint, typecheck, custom, interactive)");
+  requireGitTree(repo, ctx.env, "--repo");
+  if (o.resume) return resume(repo, ctx);
+  const snap = await snapshot(repo, ctx.env);
+  const { dir } = makeRunFolder(ctx, "ultraqa");
+  const state = { repo, gates, head: snap.head, fingerprint: snap.fingerprint, startedAt: new Date().toISOString(), finished: null };
+  writeState(dir, state);
+  writeFileSync(join(dir, "matrix.md"), "", { mode: 0o600 });
+  return [{ ok: true, dir, resumed: false, ...state }, 0];
+}
+
+// The unfinished runs of this repo under the known bases, newest first.
+function unfinished(repo, ctx) {
+  const found = [];
+  for (const base of bases(ctx).known) {
+    let names = [];
+    try {
+      names = readdirSync(base).filter((n) => /^ultraqa\.[A-Za-z0-9]+$/.test(n));
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      try {
+        const { d } = runFolder(join(base, n), ctx, KIND);
+        const s = readState(d);
+        if (s.repo === repo && !s.finished) found.push({ d, s, at: statSync(join(d, "state.md")).mtimeMs });
+      } catch {
+        /* not a run folder of this account, or no state */
+      }
+    }
+  }
+  return found.sort((a, b) => b.at - a.at);
+}
+
+// Resumed only when the repo's HEAD and work tree are what the run last saw (its last observed record, else init).
+async function resume(repo, ctx) {
+  const runs = unfinished(repo, ctx);
+  if (!runs.length) throw new Stop("no-resume", `이어 갈 끝나지 않은 실행이 없다: ${repo}`);
+  const { d, s } = runs[0];
+  const snap = await snapshot(repo, ctx.env);
+  const lastSeen = readEvidence(d).filter((r) => r.kind === "observed").pop()?.fingerprint || s.fingerprint;
+  if (snap.head !== s.head || snap.fingerprint !== lastSeen) {
+    throw new Stop("no-resume", `HEAD 나 작업 트리가 그 실행이 마지막에 본 것과 다르다. 새로 시작한다: ${d}`);
+  }
+  const st = statusOf({ evidence: readEvidence(d), rows: readMatrix(d), gates: s.gates, fingerprint: snap.fingerprint });
+  return [{ ok: true, dir: d, resumed: true, cycle: st.cycle, nextCycle: st.cycle + 1, ...s }, 0];
+}
+
+function row(o, ctx) {
+  const { d } = runFolder(o.dir, ctx, KIND);
+  const r = JSON.parse(String(ctx.stdin()).trim() || "null");
+  if (!r || typeof r !== "object" || !/^[A-Za-z0-9._-]{1,64}$/.test(String(r.id))) throw new Usage("행은 id(영숫자, . _ - 64자까지)가 있는 JSON 객체다");
+  if (!CLASSES.some(([c]) => c === r.class) && r.class !== "normal") throw new Usage(`class 는 9분류의 id 나 normal 이다: ${String(r.class).slice(0, 40)}`);
+  if (!STATUSES.includes(r.status)) throw new Usage(`status 는 ${STATUSES.join(", ")} 가운데 하나다`);
+  const clean = Object.fromEntries(ROW_KEYS.filter((k) => k in r).map((k) => [k, r[k]]));
+  const rows = readMatrix(d).filter((x) => x.id !== clean.id).concat(clean);
+  writeFileSync(join(d, "matrix.md"), rows.map((x) => JSON.stringify(x)).join("\n") + "\n", { mode: 0o600 });
+  return [{ ok: true, rows: rows.length, row: clean }, 0];
+}
+
+async function status(o, ctx) {
+  const { d } = runFolder(o.dir, ctx, KIND);
+  const c = await current(d, ctx);
+  const st = statusOf({ evidence: c.evidence, rows: c.rows, gates: c.state.gates, fingerprint: c.fingerprint });
+  return [{ ok: true, ...st, finished: c.state.finished }, st.complete ? 0 : 1];
+}
+
+async function finish(o, ctx) {
+  const { d } = runFolder(o.dir, ctx, KIND);
+  const c = await current(d, ctx);
+  const st = statusOf({ evidence: c.evidence, rows: c.rows, gates: c.state.gates, fingerprint: c.fingerprint });
+  const refused = endAllowed(o.end, st, o.why);
+  if (refused) return [{ ok: false, refused, next: st.next, checks: st.checks }, 1];
+  const line = END_LINES[o.end](st.cycle, String(o.why || "").trim());
+  writeState(d, { ...c.state, finished: { end: o.end, line, at: new Date().toISOString() } });
+  return [{ ok: true, line }, 0];
+}
+
+const cell = (v) => String(v ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ").slice(0, 200);
+
+// The report skeleton: the parts the program knows are filled, the rest the model writes. Observed and reported apart.
+export function reportOf({ state, evidence, rows, st }) {
+  const observed = evidence.filter((r) => r.kind === "observed");
+  const reported = evidence.filter((r) => r.kind === "reported");
+  return [
+    "# UltraQA 보고서", "", "## 목표와 성공 기준", `- 목표 게이트: ${state.gates.join(", ")}`, "- 성공 기준: (모델이 씀)", "- 종료 조건: COMPLETE, 순환 5회, 같은 실패 3회, 안전 경계, 환경 오류",
+    "- 적용한 안전 경계: (모델이 씀)", "", "## 시나리오 행렬",
+    "| ID | 분류 | 사용자/공격자 모델 | 시나리오 | 명령/하네스 | 기대 신호 | 상태 | 증거(기록 번호) | 정리 |", "|---|---|---|---|---|---|---|---|---|",
+    ...rows.map((r) => `| ${[r.id, r.class, r.model, r.intent, r.command, r.expected, r.status, r.evidenceRef ?? cell(r.excludeReason), r.cleanup].map(cell).join(" | ")} |`),
+    "", "## 실행한 명령(관측)", ...observed.map((r) => `- [${r.exit ?? r.signal ?? "-"}] \`${cell(r.cmd)}\` 순환 ${r.iter}, ${r.secs}s/${r.timeout}s, ${r.verdict}${r.why ? `(${r.why})` : ""}, 출력 sha256 ${String(r.outputSha256).slice(0, 12)}`),
+    "", "## 신고(판정에 쓰지 않음)", ...(reported.length ? reported.map((r) => `- ${r.id} 순환 ${r.iter}: ${cell(r.text)}`) : ["- 없음"]),
+    "", "## 찾은 실패", "- (모델이 씀: 시나리오 ID, 실패 신호, 근본 원인, 사용자 영향, 안전 영향)", "", "## 적용한 고침", "- (모델이 씀: 바꾼 파일, 까닭, 연결된 시나리오, 회귀 증거)",
+    "", "## 정리와 되돌림", "- (cleanup 결과와 작업 트리 전후)", "", "## 남은 위험", ...rows.filter((r) => r.status !== "pass").map((r) => `- ${r.id}: ${r.status} ${cell(r.excludeReason)}`),
+    "", "## 기계 판정", `- 순환 ${st.cycle}/${MAX_CYCLES}, COMPLETE ${st.complete ? "허용" : "거부"}${st.next ? `, 다음 줄: ${st.next}` : ""}`,
+    ...Object.entries(st.checks).map(([k, c]) => `- ${k}: ${c.ok ? "통과" : "실패"}`), "",
+  ].join("\n");
+}
+
+async function report(o, ctx) {
+  const { d } = runFolder(o.dir, ctx, KIND);
+  const c = await current(d, ctx);
+  const st = statusOf({ evidence: c.evidence, rows: c.rows, gates: c.state.gates, fingerprint: c.fingerprint });
+  return [{ markdown: reportOf({ ...c, st }) }, 0];
+}
+
+// The run folder alone. A path a row's cleanup names outside it is reported, never removed.
+function cleanup(o, ctx) {
+  const { d } = runFolder(o.dir, ctx, KIND);
+  const outside = readMatrix(d).map((r) => r.cleanup).filter((p) => typeof p === "string" && p.trim() && !resolve(d, p).startsWith(d + sep));
+  const done = removeRunFolder(d, ctx, KIND);
+  return [{ ok: true, ...done, outside }, 0];
+}
+
+const FLAGS = { init: ["repo", "gates", "resume!"], row: ["dir"], status: ["dir"], finish: ["dir", "end", "why"], report: ["dir"], cleanup: ["dir"] };
+const REQUIRED = { init: ["repo", "gates"], row: ["dir"], status: ["dir"], finish: ["dir", "end"], report: ["dir"], cleanup: ["dir"] };
+
+function readFlag(spec, rest, i, o) {
+  const m = /^--([a-z]+)(?:=([\s\S]*))?$/.exec(rest[i]);
+  const flag = m && spec.find((f) => f.replace(/!$/, "") === m[1]);
+  if (!flag) throw new Usage(`모르는 인자다: ${String(rest[i]).slice(0, 80)}`);
+  if (m[1] in o) throw new Usage(`--${m[1]} 를 두 번 줬다`);
+  if (flag.endsWith("!")) return (o[m[1]] = true) && i + 1;
+  const value = m[2] !== undefined ? m[2] : rest[i + 1];
+  if (value === undefined) throw new Usage(`--${m[1]} 에 값이 없다`);
+  o[m[1]] = value;
+  return m[2] !== undefined ? i + 1 : i + 2;
+}
+
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (!Object.prototype.hasOwnProperty.call(FLAGS, command)) throw new Usage(`모르는 명령이다: ${command ?? "(없음)"}`);
+  const o = {};
+  for (let i = 0; i < rest.length; ) i = readFlag(FLAGS[command], rest, i, o);
+  for (const r of REQUIRED[command]) if (!(r in o)) throw new Usage(`--${r} 가 필요하다`);
+  return { command, o };
+}
+
+const COMMANDS = { init, row, status, finish, report, cleanup };
+
+// A stop as JSON: what it is, its line, its paths, and for not-a-git-tree the folder it checked.
+const stopJson = (e) => ({ ok: false, stop: e.code, message: `ultraqa: ${e.message}`, detail: e.detail, ...(e.checked ? { checked: e.checked } : {}) });
+
+function failure(e, out, err) {
+  if (e instanceof Stop) {
+    out.write(`${JSON.stringify(stopJson(e), null, 2)}\n`);
+    return 3;
+  }
+  err.write(e instanceof Usage || e instanceof SyntaxError ? `ultraqa: ${e.message}\n` : `ultraqa: 내부 오류(${e?.code || e?.name || "error"}): ${String(e?.message || e).split("\n")[0]}\n`);
+  return 2;
+}
+
+export async function main(argv, io = {}) {
+  const ctx = { env: io.env || process.env, platform: io.platform || process.platform, stdin: io.stdin || (() => readFileSync(0, "utf8")) };
+  const out = io.stdout || process.stdout;
+  try {
+    const { command, o } = parseArgs(argv);
+    const [result, code] = await COMMANDS[command](o, ctx);
+    out.write(command === "report" ? result.markdown : `${JSON.stringify({ command, ...result }, null, 2)}\n`);
+    return code;
+  } catch (e) {
+    return failure(e, out, io.stderr || process.stderr);
+  }
+}
+
+const invokedDirectly = () => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+
+if (invokedDirectly()) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/skills/update-banker/SKILL.md

@@ -13,8 +13,10 @@ banker 는 서로 다른 메커니즘의 채널 3개로 설치되고, 그 채널
 **런타임:** 축은 OS 가 아니라 **채널**이다. banker 는 dependencies 0 이고 설치가 파일 복사라 OS 분기가 사실상 없다.
 
 - **Claude Code**: 플러그인 채널이 있다. 갱신 동사는 `claude plugin update`, 관측 지점은 `~/.claude/plugins/installed_plugins.json`.
-- **Codex CLI**: `codex plugin` 에 update 동사가 **없다.** 유일한 경로는 npm 갱신 후 `banker setup --codex` 이고, 이건 파괴적이다.
-- **양쪽 공통**: npm 전역 CLI 채널. 이게 Codex 채널의 **상류**라 언제나 먼저다.
+- **Codex CLI**: 설치 길이 둘이다. 갱신 방법이 다르다.
+  - npm 길(`banker setup --codex`, 스킬 `$banker-<이름>`): npm 갱신 후 `banker setup --codex` 를 다시 돌린다. 이건 파괴적이다.
+  - 플러그인 길(`codex plugin add banker@banker-plugins`, 스킬 `$banker:<이름>`): `codex plugin` 에 update 동사는 없지만 `codex plugin marketplace upgrade banker-plugins` 가 GitHub 의 새 판을 받아 설치된 플러그인도 바꾼다. Codex 는 세션을 시작할 때도 스스로 올린다(0.144.5 실측). 파괴적이지 않고 npm 과 무관하다.
+- **양쪽 공통**: npm 전역 CLI 채널. 이게 Codex npm 길의 **상류**라 언제나 먼저다. Codex 플러그인 길의 상류는 GitHub 저장소라 npm 게이트를 받지 않는다.
 - 이 스킬은 `target: both` 다. Codex 런타임에 `claude` 가 없거나 Claude 런타임에 `codex` 가 없는 것은 **정상 경로**다. 채널 부재는 스킵이지 에러가 아니다.
 - **"채널 부재" 는 두 가지다.** (a) 런타임이 없다(`command -v claude` 실패), (b) 런타임은 있는데 **banker 플러그인이 설치돼 있지 않다.** `command -v` 는 (a) 만 잡는다. Codex 주력 + Claude Code 설치됨 + banker 플러그인 미설치인 머신이 실재하고, 거기서 (b) 를 스킵으로 처리하지 않으면 프로브가 예외로 죽는다. 둘 다 스킵이다.
 
@@ -26,7 +28,7 @@ banker 는 서로 다른 메커니즘의 채널 3개로 설치되고, 그 채널
 
 ## When NOT to use
 - **최초 설치**. 그건 `banker setup` 또는 `/banker:setup` 소관이다.
-- **OMC/OMX 갱신**. `setup-omc` 소관이다. banker 는 그 버전을 대신 고정하지 않는다.
+- **OMC/OMX 갱신**. `setup-omc`(Codex 는 `setup-omx`) 소관이다. banker 는 그 버전을 대신 고정하지 않는다.
 - **깨진 설치 되살리기**. 갱신이 아니다. 아래 "복구" 절을 보고, 확인을 받고 진행한다.
 - 스킬 하나만 고치고 싶을 때. 갱신 단위는 채널 전체다.
 - 3채널이 아닌 경로(로컬 clone 을 직접 가리키는 개발 설치 등). 그건 이 스킬의 모델 밖이다.
@@ -37,7 +39,10 @@ banker 는 서로 다른 메커니즘의 채널 3개로 설치되고, 그 채널
 |---|---|---|---|
 | Claude 플러그인 | 마켓플레이스 등록 후 플러그인 설치 | `claude plugin update banker@banker-plugins` | `~/.claude/plugins/installed_plugins.json` |
 | npm 전역 CLI | npm 레지스트리에서 전역 prefix 로 설치 | `npm i -g @kaydash9999/banker-plugins@latest` | `banker --version` |
-| Codex | npm 패키지에서 `~/.codex/skills` **와 `~/.codex/prompts`** 로 복사 | `banker setup --codex` | `ls ~/.codex/skills` **와** `ls ~/.codex/prompts` |
+| Codex (npm 길) | npm 패키지에서 `~/.codex/skills` **와 `~/.codex/prompts`** 로 복사 | `banker setup --codex` | `ls ~/.codex/skills` **와** `ls ~/.codex/prompts` |
+| Codex (플러그인 길) | GitHub 마켓플레이스 스냅샷을 `~/.codex/plugins/cache/banker-plugins/banker/<판>/` 에 둠 | `codex plugin marketplace upgrade banker-plugins` | `ls ~/.codex/plugins/cache/banker-plugins/banker/` |
+
+`CODEX_HOME` 이 있으면 `~/.codex` 대신 그 폴더다. Codex 의 두 길을 함께 두면 스킬이 `$banker-<이름>` 과 `$banker:<이름>` 으로 겹치고 훅도 두 번 돈다. 둘 다 보이면 보고에 적고 하나만 두라고 안내한다(npm 길 빼기 `banker uninstall --codex`, 플러그인 빼기 `codex plugin remove banker@banker-plugins`). 이 스킬이 대신 지우지는 않는다.
 
 세 채널은 다른 갱신 동사를 쓰고 각자의 값을 가진다. 한 채널을 갱신해도 나머지는 그대로다. 실제로 세 값이 모두 다른 상태가 관측된다.
 
@@ -75,6 +80,7 @@ in15 sh -c 'cd ~ && exec npm ping --fetch-retries=0 --fetch-timeout=10000 --no-u
 command -v claude >/dev/null && echo "claude: present" || echo "claude: absent (Claude 채널 스킵)"
 command -v codex  >/dev/null && echo "codex: present"  || echo "codex: absent (Codex 채널 스킵)"
 command -v banker >/dev/null && banker --version || echo "banker: absent"
+command -v codex  >/dev/null && in15 codex plugin list 2>/dev/null | grep -E '^banker@[^ ]+ +installed, enabled' || echo "codex plugin: absent (플러그인 길 스킵)"   # 켜진 banker@<마켓플레이스>와 판
 [ "$P" = 0 ] && (cd ~ && npm view @kaydash9999/banker-plugins version --fetch-retries=0 --fetch-timeout=10000)
 ```
 
@@ -162,6 +168,18 @@ banker setup --codex --dry-run | grep -E '→ [0-9]+ skills'
 - `--scope project` 는 `./.codex` 를 대상으로 한다. 기본은 `user`(`~/.codex`).
 - 스킬은 `~/.codex/skills/banker-<name>/` 으로, 커맨드는 `~/.codex/prompts/banker-<name>.md` 로 설치된다. 스킬은 프론트매터 name 이 디렉터리명과 일치하도록 재작성된다. `~/.codex/AGENTS.md` 는 건드리지 않는다.
 
+### 3b. Codex 플러그인 길
+`codex plugin: absent` 면 스킵이다. 0단계가 보인 `banker@<마켓플레이스>` 의 마켓플레이스 이름을 아래 `banker-plugins` 자리에 쓴다. 이 길은 npm 게이트를 받지 않는다(상류가 GitHub 다). 지우고 다시 복사하지 않으므로 dry-run 단계가 없다.
+
+```bash
+codex plugin marketplace upgrade banker-plugins
+ls "${CODEX_HOME:-$HOME/.codex}/plugins/cache/banker-plugins/banker/"
+```
+
+- 설치된 플러그인 폴더가 새 판 이름으로 바뀌면 전진이다(옛 판 폴더는 Codex 가 지운다). 반영은 Codex 를 다시 연 뒤다.
+- 마켓플레이스 이름이 다르면(`codex plugin marketplace list` 로 확인) 그 이름을 쓴다.
+- 훅 신뢰는 명령 글에 묶여 있어 판이 바뀌어도 대개 그대로다. `/hooks` 에 banker 훅이 신뢰 필요로 보이면 그 사실만 보고한다.
+
 ### 4. 검증 (보고 의무)
 **exit code 로 판정하지 마라.** `claude plugin install` 이 아무것도 안 하고 exit 0 을 주는 것이 정확히 그 이유다.
 판정은 0단계와 **동일한 3-프로브를 재실행**해 before/after 를 비교하는 것으로만 한다.
@@ -195,9 +213,15 @@ console.log('manifest skills:',n('skill'));console.log('manifest commands:',n('c
 
 보조로 `banker doctor` 가 디스크 카운트와 매니페스트 카운트를 나란히 찍어준다. **다만 프롬프트 카운트가 없어 프로브 3 을 대체하지 못한다.** 스킬 축의 교차 확인용으로만 쓴다.
 
+프로브 4, Codex 플러그인 길(판 폴더 이름이 설치된 판이다):
+```bash
+ls "${CODEX_HOME:-$HOME/.codex}/plugins/cache/banker-plugins/banker/" 2>/dev/null || echo "absent (플러그인 길 미설치 -> 스킵)"
+```
+
 보조 프로브(디스크 상태가 아니라 런타임이 실제로 발견한 표면을 본다. 인증 불필요):
 ```bash
-codex debug prompt-input </dev/null | grep -oE 'banker-[a-z0-9_-]+' | sort -u | wc -l
+codex debug prompt-input </dev/null | grep -oE 'banker-[a-z0-9_-]+' | sort -u | wc -l   # npm 길
+codex debug prompt-input </dev/null | grep -oE 'banker:[a-z0-9_-]+' | sort -u | wc -l   # 플러그인 길
 ```
 
 보고 형식(채널별 before 에서 after 로. 아래는 예시):
@@ -206,6 +230,7 @@ Claude 플러그인 : 0.6.0 -> 0.7.0             전진
 npm 전역 CLI    : 0.2.0 -> 0.7.0             전진
 Codex skills    : 41 -> 48 (매니페스트 48)   전진
 Codex prompts   : 2 -> 2   (매니페스트 2)    유지
+Codex 플러그인  : 0.6.0 -> 0.7.0             전진
 ```
 
 - **Codex 는 skills 와 prompts 를 반드시 두 줄로 적는다.** 한 줄로 뭉개면 프롬프트 소실이 보고에서 사라진다.
@@ -248,5 +273,5 @@ Codex prompts   : 2 -> 2   (매니페스트 2)    유지
 
 ARGUMENTS: [--check] [--claude|--npm|--codex] (없으면 3채널 전부: 관측 → npm 게이트 → 나머지 채널 → 3-프로브 검증)
 - `--check`: 아무것도 변경하지 않는다. 0단계 관측 + 4단계 프로브만 돌려 채널별 드리프트를 보고한다.
-- `--claude` / `--npm` / `--codex`: 해당 채널만 갱신한다.
-- 단 `--codex` 단독이어도 1단계 게이트(`banker --version` == `npm view ...`)는 **반드시** 확인한다. 불일치면 npm 갱신을 먼저 제안하고 확인받는다. 게이트 없는 `--codex` 는 없다.
+- `--claude` / `--npm` / `--codex`: 해당 채널만 갱신한다. `--codex` 는 Codex 의 두 길 중 설치된 것을 모두 갱신한다.
+- 단 `--codex` 단독이어도 npm 길을 갱신하기 전에는 1단계 게이트(`banker --version` == `npm view ...`)를 **반드시** 확인한다. 불일치면 npm 갱신을 먼저 제안하고 확인받는다. 게이트 없는 npm 길 갱신은 없다. 플러그인 길만 설치돼 있으면 게이트 없이 3b 만 한다.

package/skills/vertical-pptx/SKILL.md

@@ -215,7 +215,7 @@ macOS 와 Linux 에서는 대체 폰트로 치환되고, 치환되면 글자 폭
 
 ```
 --font <이름>  →  BANKER_PPTX_FONT  →  meta.font  →
-Noto Sans CJK KR  →  Malgun Gothic  →  Apple SD Gothic Neo  →  NanumGothic  →  시스템 한국어 sans
+Noto Sans CJK KR  →  Noto Sans KR  →  Malgun Gothic  →  Apple SD Gothic Neo  →  AppleGothic  →  NanumGothic  →  시스템 한국어 sans
 ```
 
 명시한 이름(`--font`·환경변수·`meta.font`)이 해석되지 않으면 `FONT_NOT_FOUND` 경고를 남기고 다음으로 내려간다. 조용히 바꾸지 않는다.

package/skills/vertical-pptx/build_a4p.js

@@ -542,14 +542,22 @@ function fontWeightRank(flat) {
   return 1;
 }
 
+// 파일명 탐색에 쓰는 조각. 힌트 표에 없는 이름(constructor 처럼 Object 가 물려받은 이름 포함)은 정리한 이름 하나.
+function fontHints(name) {
+  const key = String(name).toLowerCase();
+  return (Object.prototype.hasOwnProperty.call(FONT_FILE_HINTS, key) ? FONT_FILE_HINTS[key] : [normName(name)]).filter(Boolean);
+}
+
 function globFontFile(name) {
-  const hints = FONT_FILE_HINTS[String(name).toLowerCase()] || [normName(name)];
+  const hints = fontHints(name);
+  if (!hints.length) return null;
   let budget = 20000;
   const found = [];
   const walk = (dir, depth) => {
     if (depth > 6 || budget <= 0) return;
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)); // 어느 OS 에서나 이름순
     const subdirs = [];
     for (const ent of entries) {
       budget -= 1;
@@ -581,6 +589,13 @@ function globFontFile(name) {
  */
 function findFontFile(name) {
   const want = normName(name);
+  if (!want) {
+    // ASCII 글자가 없는 이름(예: 나눔고딕)은 정리한 형태로 대조할 수 없다. 빈 문자열은 어떤 family 에나 들어 있다.
+    // fc-match 가 돌려준 family 원문과 정확히 같을 때만 찾은 것으로 본다. 파일명 탐색은 하지 않는다.
+    const exact = String(name).trim().toLowerCase();
+    const hit = fcMatch(escFc(name));
+    return hit && hit.families.some((f) => f.toLowerCase() === exact) && fs.existsSync(hit.file) ? hit.file : null;
+  }
   // 한 방향(family 가 요청 이름을 품는가)만 본다. 반대 방향까지 허용하면
   // "Noto Sans CJK KR" 을 요청했는데 "Noto Sans" 가 통과해 한글 없는 폰트에 그 이름이 붙는다.
   const hit = fcMatch(escFc(name));
@@ -785,7 +800,8 @@ const USAGE = [
   '                     사람이 읽는 표와 상태 JSON 은 stderr 로 간다(리다이렉트 안전).',
   '  --out <경로>       .pptx 출력 경로 (--emit-json 과 함께 쓰면 deck JSON 출력 경로)',
   '  --font <이름>      폰트 이름을 직접 지정. 체인: --font → BANKER_PPTX_FONT → meta.font',
-  '                     → Noto Sans CJK KR → Malgun Gothic → Apple SD Gothic Neo → NanumGothic → 시스템 한국어 sans',
+  '                     → Noto Sans CJK KR → Noto Sans KR → Malgun Gothic → Apple SD Gothic Neo → AppleGothic',
+  '                     → NanumGothic → 시스템 한국어 sans',
   '  -h, --help         이 도움말',
   '',
   '종료 코드: 0 통과 · 1 검증 실패 · 2 환경 미비(pptxgenjs 없음) · 3 사용법 오류',
@@ -920,4 +936,6 @@ module.exports = {
   BULLET_PREFIX,
   FONT_CHAIN,
   FONT_FILE_HINTS,
+  fontHints,
+  sanitizeFontName,
 };