@kaydash9999/banker-plugins 0.25.1 → 0.26.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.25.1"
+    "version": "0.26.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.26.0] - 2026-11-05
+
+### Added
+- 새 스킬 `make-evidence`: 구현한 서비스의 증거 문서 여섯을 실제 실행으로 만들어 `docs/evidence/` 에 커밋한다. 수치는 실행 로그에서만 옮기고, 문서마다 실행 명령과 로그 경로를 적고, 다 쓴 뒤 문서의 수를 로그와 대조한다. push 는 하지 않는다.
+  - `optimize.md`: 목적 함수, 제약, 알고리즘 이름, 핵심 함수의 `파일:줄`, 의사코드 10줄
+  - `verify.md`: 구현을 보지 않은 새 맥락 하위 에이전트가 README 와 담당자 사실만 읽고 `tests/oracle/` 에 판정기와 시험을 쓰고, 판정기를 먼저 커밋한다. 일부러 넣은 버그 셋(제약 위반, 목적값 오계산, 권한 우회)을 패치로 넣어 돌리고 되돌린 기록을 남긴다
+  - `flow.md`: 화면, API, 최적화, DB, 내보내기 순서와 단계별 `파일:줄`, `{host}:{port}` 서버에 실제 요청을 보내는 종단 시험 로그. 서버에 닿지 못하면 미검증으로 적는다
+  - `scale.md`: 데이터 1배, 5배, 10배를 스크립트로 만들어 시간과 목적값을 재고, 작은 사례 다섯을 완전 탐색 정해와 비교한 차이(%)
+  - `decisions.md`: 결정마다 고른 것, 버린 것, 이유, 확인하는 시험 이름
+  - `trace.md`: README 요구마다 번호, 상태(완료, 부분, 미구현과 이유), 시험 이름, 로그 경로
+
 ## [0.25.1] - 2026-11-03
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 [빠른 시작](#빠른-시작) · [워크플로 예시](#워크플로-사용-예시) · [구성](#구성) · [설치 상세](#설치-상세-npm--codex) · [설정 변경 지점](#설정-변경-지점-claude-code--codex) · [요구사항](#요구사항) · [업데이트 / 제거](#업데이트--제거) · [업데이트 확인](#업데이트-확인-및-사용량-카운팅) · [오프라인](#오프라인에서-쓰기) · [라이선스 / 서드파티](#라이선스--서드파티)
 
 □ banker는 다음을 포함하는 Claude Code 및 Codex CLI 플러그인입니다.
-- QA·보안 감사·문서·아키텍처·위키·미디어 작업과 의존성·개발환경(OS별) 설치를 아우르는 **스킬 71개 + 커맨드 2개**(총 73개 구성요소. Codex 는 Claude Code 전용 `ultraqa` 를 뺀 스킬 70개와 Codex 전용 스킬 3개)
+- QA·보안 감사·문서·아키텍처·위키·미디어 작업과 의존성·개발환경(OS별) 설치를 아우르는 **스킬 72개 + 커맨드 2개**(총 74개 구성요소. Codex 는 Claude Code 전용 `ultraqa` 를 뺀 스킬 71개와 Codex 전용 스킬 3개)
 - Claude Code 즉시 명령 `/graceful-pause`, `/progress`
 
 □ 설치하면 스킬과 커맨드가 `/banker:<이름>` 네임스페이스로 노출됩니다.
@@ -158,6 +158,7 @@ Claude Code 2.1.296 은 Claude 5 모델(Opus 5.5 등)에 작업 목록 도구(Ta
 | `smart-compact` | 컨텍스트 임계 초과 시 위키·resume 저장 게이트 자동 무장 |
 | `deep-research` | 다중 소스 팬아웃 + 적대적 검증 인용 리서치 |
 | `lfm` | learn from master. 그 분야 최고 전문가 그룹이 일하는 방식을 1차 자료로 조사해 계획 적용 항목으로 정리(ultra-interview, ultra-chain, deep-research, rfp-author 의 리서치에서도 씀) |
+| `make-evidence` | 구현한 서비스의 증거 문서 여섯(optimize, verify, flow, scale, decisions, trace)을 실제 실행으로 만들어 `docs/evidence/` 에 커밋. 수치는 실행 로그에서만 옮기고 문서마다 명령과 로그 경로를 적음. 판정기는 구현을 보지 않은 새 맥락 하위 에이전트가 쓰고, 일부러 넣은 버그 셋을 잡는지 돌린 뒤 되돌림. 미구현은 숨기지 않음, push 는 안 함 |
 | `ultra-interview` | 리서치 선행으로 사람 질문 최소화, 모호성 3% 이하까지 인터뷰 |
 | `interval-report` | 장기 수행 중간 보고를 `docs/intermission.md` 로 갱신(경과·잔여·단일 표) |
 | `summary-wiki` | 위키를 `docs/` 단일 파일 개조식으로 요약(지식 동기화 검토용, 읽기 전용) |
@@ -232,14 +233,14 @@ banker uninstall        # 제거
 
 - `--scope project` 로 프로젝트 로컬(`./.codex`)에 설치하고, `--dry-run` 으로 미리 볼 수 있습니다.
 - non-root 전용입니다(전역 sudo 설치 시 root 소유 파일을 방지). postinstall이 없으므로 `banker setup` 을 직접 실행합니다.
-- Codex에는 스킬 70개와 Codex 전용 스킬 3개(`graceful-pause`, `progress`, `teamwork`)가 `~/.codex/skills/banker-<name>/` 에, 커맨드 2개가 `~/.codex/prompts/banker-<name>.md` 에 설치됩니다(`codex/manifest.json`). \
+- Codex에는 스킬 71개와 Codex 전용 스킬 3개(`graceful-pause`, `progress`, `teamwork`)가 `~/.codex/skills/banker-<name>/` 에, 커맨드 2개가 `~/.codex/prompts/banker-<name>.md` 에 설치됩니다(`codex/manifest.json`). \
   `CODEX_HOME` 을 설정했으면 `~/.codex` 대신 그 폴더에 설치합니다(Codex 가 읽는 곳). \
   `lineage`, `progress`, 사용량 카운팅은 Codex 의 대화 기록(rollout)을 읽습니다. Codex 는 이 형식을 공개 약속으로 내놓지 않아 업데이트로 바뀔 수 있습니다. \
   Codex 를 업데이트한 뒤에는 `banker doctor` 로 형식을 점검합니다. 읽지 못하면 lineage 는 빈 페이지 대신 오류로 멈추고, progress 는 경고 줄을 보이며, 카운팅은 다음 세션 시작 때 경고를 한 번 보입니다. \
   Codex 0.144 이상에는 사용자 프롬프트가 없으므로 커맨드 2개는 스킬로도 설치되어 `$banker-front-qa`, `$banker-setup` 으로 부릅니다. \
   디렉터리명과 일치하도록 프론트매터 `name:` 이 `banker-<name>` 으로 재작성되어 Codex가 `banker-<name>` 으로 인식합니다.
 - Codex 플러그인 설치(`codex plugin add banker@banker-plugins`)는 저장소를 `~/.codex/plugins/cache/banker-plugins/banker/<판>/` 에 두고 `.codex-plugin/plugin.json` 을 읽습니다. \
-  스킬 70개, Codex 전용 스킬 3개, 커맨드 2개(스킬로)가 `$banker:<name>` 으로 보이고, 업데이트 알림과 사용량 카운팅 훅은 `codex/hooks.json` 에서 옵니다. \
+  스킬 71개, Codex 전용 스킬 3개, 커맨드 2개(스킬로)가 `$banker:<name>` 으로 보이고, 업데이트 알림과 사용량 카운팅 훅은 `codex/hooks.json` 에서 옵니다. \
   Codex 는 세션을 시작할 때 마켓플레이스를 스스로 올려 새 판을 설치합니다. 훅 명령 앞에는 훅이 실행하는 파일의 해시가 붙어 있어, 훅 코드가 바뀐 판에서는 `/hooks` 가 다시 신뢰를 묻고 신뢰하기 전에는 훅이 돌지 않습니다. 훅 코드가 그대로인 판은 신뢰도 그대로입니다. 스킬 파일은 신뢰 확인 없이 새 판으로 바뀝니다. \
   obsidizer 훅은 npm 설치와 같이 `obsidizer --enable` 할 때만 사용자 범위에 설치됩니다(셸 호출마다 node 를 띄우므로). \
   훅은 Codex 샌드박스 밖에서 돌므로, PATH 의 node 가 임시 폴더나 작업 폴더 안에 있으면(샌드박스가 바꿀 수 있는 곳) 아무것도 돌리지 않고 그 이유를 세션 시작 알림으로 보입니다. 작업 폴더가 홈 폴더 자체이면 홈 아래의 node(nvm 등)는 그대로 씁니다. 훅 스크립트, 플러그인 폴더, node 가 `config.toml` 의 `[sandbox_workspace_write] writable_roots` 아래(그 항목 맨 위 `.codex` 제외)면 훅은 다른 일을 하지 않고 그 이유를 한 줄로 알립니다. 이 검사는 훅 파일 안에서 하므로, 샌드박스가 이미 그 파일을 고친 뒤에는 막지 못합니다. writable_roots 에 Codex 홈이나 node 가 든 폴더를 넣지 마십시오. \

package/codex/manifest.json

@@ -80,6 +80,7 @@
     { "name": "git-init",             "type": "skill",   "target": "both",        "reason": "makes the first commit of a folder that is not a git repository yet, so worktrees and other parallel work can start from it: writes a .gitignore that keeps secrets and local state out, scans the files to track for secrets by name and content (payload-scan.mjs, file:line:kind only, never the value), then runs git init, git add . and git commit -m init; a hit stops it before any .git exists; pure Node, no deps, no network", "supportingFiles": ["scripts/git-init.mjs","scripts/marker-block.mjs","scripts/payload-scan.mjs"], "caveat": "needs git on PATH (before git 2.28 the first branch is set with git symbolic-ref) and a commit identity (user.name and user.email, or --local-identity, written to .git/config only); an existing .gitignore keeps its bytes and gets one marked block at its end, the first original kept in .gitignore.git-init.bak, which the block itself ignores; a .gitignore symbolic link is refused unless --follow-symlink; key file names cannot be accepted, a content hit only by its exact file:line:kind with --accept; commit hooks are not skipped; it never adds a remote or pushes; on Codex run asks for sandbox_permissions require_escalated, since the default sandbox may block writes to .git" },
     { "name": "build-testbox",        "type": "skill",   "target": "both",        "reason": "a test environment this machine builds from its own resources: a browser matrix (Playwright Chromium and WebKit, desktop and mobile device emulation) against a loopback URL and container OSes (Rocky Linux 8, 9; macOS only as a Tart VM on Apple Silicon) run in parallel, every requested cell kept as a pass, fail, unverified or unsupported row with a reason, results.json and summary.md; detect, run, setup; pure Node, no deps", "supportingFiles": ["scripts/testbox.mjs","scripts/args.mjs","scripts/detect.mjs","scripts/browsers.mjs","scripts/browser-cell.mjs","scripts/containers.mjs","scripts/setup.mjs","scripts/report.mjs","scripts/proc.mjs"], "caveat": "Playwright (a global install, or the project's with --playwright-from-project) and docker or podman are optional; a missing one leaves its cells unverified with the reason; run downloads nothing (a missing image or browser build is unverified, never pulled); setup only lists what it would fetch and its rough size, and fetches after the user confirms and it runs again with --yes (exit 4 and network needed when the sources are unreachable); macOS runs only as a Tart VM on an Apple Silicon host (other hosts are unsupported under the Apple SLA), and the skill never downloads or starts the VM; on Codex detect and run ask for sandbox_permissions require_escalated for the container engine and the headless browsers, the server under test on a 127.0.0.1 port is the user's own (approved where it is started), and setup --yes, or a container command that uses the network, asks for network access (--network host lifts that cell's isolation, and the user is told)" },
     { "name": "tune-tmux",            "type": "skill",   "target": "both",        "reason": "adds or removes one marked block in the tmux or psmux config file so mouse drag copies to the OS clipboard and PageUp/PageDown scroll inside tmux, without taking keys or the mouse from full-screen apps; status shows the chosen file, the lines and why any are left out, conflicts in other files tmux reads, and per-app behavior (Claude Code, Codex); first original kept, off removes only the block, --reload applies it to a running server; pure Node, no deps, no network", "supportingFiles": ["scripts/tune-tmux.mjs","scripts/tmux-config.mjs","scripts/app-notes.mjs","scripts/marker-block.mjs","scripts/psmux-caps.json"], "caveat": "needs tmux or psmux (install with setup-tmux; status alone works without them); it writes the user's config file outside the workspace (~/.tmux.conf or the XDG tmux.conf, ~/.psmux.conf for psmux), keeping the first original as <conf>.tune-tmux.bak, so on Codex on, off and --reload ask for sandbox_permissions require_escalated (no --add-dir); a config file that is a symbolic link is refused unless --follow-symlink; psmux gets a block of zero lines today (its defaults give mouse, set-clipboard and wheel copy-mode; drag to the Windows clipboard and PageUp/PageDown inside full-screen apps are unverified; outside apps PageUp needs the prefix, PageDown does not leave copy-mode at the bottom and #{alternate_on} is always 0), so on reports the unverified and broken counts with exit 0 and only takes out an old tune-tmux block left in that file; inside full-screen apps (Claude Code fullscreen, Codex Fullscreen) the app keeps PageUp/PageDown and the mouse, and tmux copy-mode cannot scroll Codex history, a limit tmux config cannot fix; it never changes Claude Code or Codex settings" },
+    { "name": "make-evidence",        "type": "skill",   "target": "both",        "reason": "writes six evidence documents for a built service from real runs and commits them under docs/evidence/ (optimize: objective, constraints, algorithm, file:line, pseudocode; verify: an oracle in tests/oracle/ written by a fresh-context sub-agent that reads only the README and the owner facts, committed first, and three seeded bugs (constraint, objective, authorization) applied as patches, run and reverted; flow: screen, API, optimization, DB, export with file:line and an end-to-end run against {host}:{port}; scale: 1x, 5x, 10x data by script with time and objective, five small cases against exhaustive search with the gap in percent; decisions: chosen, rejected, reason, the test that checks it; trace: every README requirement with done, partial or not done and why, test name and log path); numbers only from run logs, each document names its commands and log paths, a number check against the logs at the end; no push", "supportingFiles": [], "caveat": "procedure only (no script): the project supplies the server, its tests and the tools; a server that cannot be reached is written as unverified, never filled from unit tests; on Codex the commit may ask for sandbox_permissions require_escalated and a run against a non-local server asks for network access" },
 
     { "name": "front-qa",             "type": "command", "target": "both",        "reason": "ralplan->ralph frontend-QA pipeline; Claude=OMC, Codex=OMX", "supportingFiles": [] },
     { "name": "setup",                "type": "command", "target": "both",        "reason": "installer orchestrator; Claude AskUserQuestion multi-select, Codex prompt-based selection", "supportingFiles": [], "codexDescription": "구성요소와 의존성을 여러 개 골라 설치하는 오케스트레이터. 런타임(Node, Python, Java), LSP, tmux, MCP, 샌드박스, OMX, Playwright 등. 권한 확인 끄기는 따로 묻고 기본으로 고르지 않으며, 골라도 실행하지 않고 직접 입력할 명령만 안내." },

package/codex/transform-matrix.md

@@ -54,6 +54,7 @@ The generator (`banker setup --codex`) applies the rules below for `target: both
 - `init-dir` — the same procedure in both runtimes; the engine is `scripts/init-dir.mjs` (Codex npm install: `~/.codex/skills/banker-init-dir/scripts/init-dir.mjs`; plugin install: `~/.codex/plugins/cache/<marketplace>/banker/<version>/skills/init-dir/scripts/init-dir.mjs`), run with `--runtime claude|codex`. It writes one marked block (`<!-- banker:init-dir:start -->` to `<!-- banker:init-dir:end -->`) into whichever of `AGENTS.md` and `CLAUDE.md` exist (Codex with neither: `AGENTS.md`), the `AGENTS.md` block inside its own `USER:OMX:POLICY` pair; `AGENTS.override.md` is never written, only warned about when it has content of its own. The block editor `scripts/marker-block.mjs` is the source of truth for its future copies (`scripts/sync-adapter.js`). Pure Node with no network. On Codex a `--root` outside the workspace, or starting a generated service that must outlive the session, asks for `sandbox_permissions: "require_escalated"`.
 - `motion-sites` — the same procedure in both runtimes; the engine is `scripts/motion-sites.mjs` (Codex npm install: `~/.codex/skills/banker-motion-sites/scripts/motion-sites.mjs`; plugin install: `~/.codex/plugins/cache/<marketplace>/banker/<version>/skills/motion-sites/scripts/motion-sites.mjs`). `status --runtime codex` finds the original plugin through `config.toml` (`[plugins."motionsites-web-builder@motionsites"]`) and `plugins/cache/motionsites/`; `setup --runtime codex` runs `codex plugin marketplace add Motionsites-AI/claude-skill` and `codex plugin add motionsites-web-builder@motionsites` where Claude Code runs `claude plugin marketplace add` and `claude plugin install`. The hand-over is `$motionsites-web-builder:motionsites-web-builder` once the plugin shows in the session, else the original `SKILL.md` read and followed. `setup` needs the network and asks for `sandbox_permissions: "require_escalated"`.
 - `git-init` — the same procedure in both runtimes; the engine is `scripts/git-init.mjs` (Codex npm install: `~/.codex/skills/banker-git-init/scripts/git-init.mjs`; plugin install: `~/.codex/plugins/cache/<marketplace>/banker/<version>/skills/git-init/scripts/git-init.mjs`). `check` (the default) writes nothing; `run` writes the `.gitignore` block (`# banker:git-init:start` to `# banker:git-init:end`, through `scripts/marker-block.mjs`, a byte-identical copy of init-dir's), scans the files to track with `scripts/payload-scan.mjs` (a byte-identical copy of ralph-qa's; both kept by `scripts/sync-adapter.js`) and only then runs `git init`, `git add .` and `git commit -m "init"`. Needs `git`; no network, no remote, no push. On Codex `run` asks for `sandbox_permissions: "require_escalated"`, as the default sandbox may block writes to `.git`.
+- `make-evidence` — the same procedure in both runtimes, with no script of its own. The oracle is written by a fresh-context sub-agent: Claude Code uses the Agent tool as `general-purpose` with no `model`; Codex uses `spawn_agent` with no `agent_type` or `model` and without the author's conversation (`fork_turns="none"` on multi-agent v2, no `fork_context` on v1). It reads only `README.md` and `docs/evidence/owner-facts.md`. On Codex the commits may ask for `sandbox_permissions: "require_escalated"`, as the default sandbox may block writes to `.git`. The end-to-end run against a server that is not local asks for network access.
 - `build-testbox` — the same procedure in both runtimes; the engine is `scripts/testbox.mjs` (Codex npm install: `~/.codex/skills/banker-build-testbox/scripts/testbox.mjs`; plugin install: `~/.codex/plugins/cache/<marketplace>/banker/<version>/skills/build-testbox/scripts/testbox.mjs`) with `detect`, `run` and `setup`; `scripts/browser-cell.mjs` is copied into the Playwright image and runs there alone for `--browser-in-container`. Playwright and docker or podman are optional: a missing one leaves its cells `unverified` with the reason. `run` downloads nothing; `setup` without `--yes` only lists what it would fetch, and the skill confirms with the user (Claude Code `AskUserQuestion`, Codex `request_user_input`) before running it again with `--yes`. macOS runs only as a Tart VM on an Apple Silicon host; other hosts get `unsupported(apple-sla)`. On Codex `detect` and `run` ask for `sandbox_permissions: "require_escalated"` (container engine, headless browsers, copies under the OS temp folder), `setup --yes` and container commands that use the network ask for network access, and the server under test is the user's own on a 127.0.0.1 port; a cell stopped by a permission error is `unverified(sandbox)`.
 - `tune-tmux` — the same procedure in both runtimes; the engine is `scripts/tune-tmux.mjs` (Codex npm install: `~/.codex/skills/banker-tune-tmux/scripts/tune-tmux.mjs`; plugin install: `~/.codex/plugins/cache/<marketplace>/banker/<version>/skills/tune-tmux/scripts/tune-tmux.mjs`) with `status` (the default), `on` and `off`. It writes one marked block (`# banker:tune-tmux:start` to `# banker:tune-tmux:end`) through `scripts/marker-block.mjs`, a byte-identical copy of init-dir's kept by `scripts/sync-adapter.js`, into the user's tmux config (`~/.tmux.conf` or the XDG `tmux.conf`) or psmux config (`~/.psmux.conf` and the rest of psmux's order); psmux gets zero lines today, as `scripts/psmux-caps.json` verifies nothing beyond its defaults. The conditional `#{||:}` is probed on a private `tmux -L` server, never the user's. A symbolic-link config is refused unless `--follow-symlink`. No network. On Codex `on`, `off` and `--reload` ask for `sandbox_permissions: "require_escalated"`, as the config file and the tmux socket are outside the workspace; Claude Code and Codex settings are never changed, and Codex Fullscreen history cannot be scrolled by tmux copy-mode (only the user's `--no-alt-screen` or `tui.alternate_screen = "never"` changes that).
 - `/graceful-pause` — in Claude Code a function-hooks command (`hooks/register.mjs`, 2.1.289+, not a manifest surface) registered `immediate`, so it runs mid-turn; it appends one hidden user row the running turn reads at its next model request. In Codex the `codex-only` skill `graceful-pause` (`$banker-graceful-pause`): a message sent with Enter while a turn runs is held as "Messages to be submitted after next tool call" and put into the same turn when the running tool call ends, so the session stops after the current step (Codex 0.144.5: verified with `sleep 40` in a real TUI).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/make-evidence/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: make-evidence
+description: "구현한 서비스의 증거 문서 여섯(optimize, verify, flow, scale, decisions, trace)을 실제 실행으로 만들어 docs/evidence/ 에 커밋. 수치는 실행 로그에서만 옮기고, 문서마다 실행 명령과 로그 경로를 적음. 판정기는 구현을 보지 않은 새 맥락 하위 에이전트가 씀. 미구현은 숨기지 않음. 'make-evidence'/'증거 문서'/'evidence 만들어'/'검증 근거 문서' 시 사용."
+argument-hint: "[--host <host>] [--port <port>] [--only <문서,...>] [--no-commit]"
+---
+
+# make-evidence: 실행으로 만드는 증거 문서 여섯
+
+구현한 서비스가 README 의 요구를 지키는지, 실제로 실행한 결과로 보이는 문서 여섯을 만든다.
+문서는 `docs/evidence/` 에 쓰고 커밋한다. 답변은 한글.
+
+## 원칙
+
+- **수치는 손으로 쓰지 않는다.** 시간, 목적값, 차이(%), 통과 수, 건수는 실행 로그에서만 옮긴다. 로그에 없는 수는 문서에 쓰지 않는다.
+- **문서마다 실행 명령과 로그 경로를 적는다.** 읽는 사람이 같은 명령을 다시 돌려 같은 로그를 얻을 수 있어야 한다.
+- **실행하지 못한 것은 실행하지 못했다고 쓴다.** 서버가 안 뜨거나 도구가 없으면 그 칸은 `미검증` 과 까닭이다. 추정값이나 예상값으로 채우지 않는다.
+- **미구현을 숨기지 않는다.** README 요구 가운데 구현하지 않은 것은 `trace.md` 에 `미구현` 과 이유로 남긴다.
+- 문서에 비밀값을 넣지 않는다. 로그에 토큰, 비밀번호, 키가 찍혔으면 커밋 전에 값을 `***` 로 가리고, 가렸다는 사실을 그 문서에 적는다.
+
+## 인자
+
+- `--host <host>`, `--port <port>`: `flow.md` 의 종단 시험이 요청을 보낼 서버. 없으면 README, `.env.example`, 서비스 시작 스크립트에서 찾고, 그래도 없으면 사용자에게 묻는다. 찾은 값과 그 출처를 `flow.md` 에 적는다.
+- `--only <문서,...>`: 일부만 만든다(예: `--only scale,trace`). 이름은 `optimize`, `verify`, `flow`, `scale`, `decisions`, `trace`.
+- `--no-commit`: 파일만 쓰고 커밋하지 않는다.
+
+## 폴더
+
+```
+docs/evidence/
+  optimize.md  verify.md  flow.md  scale.md  decisions.md  trace.md
+  logs/        실행 로그. 문서는 이 파일들을 경로로 가리킨다
+  scripts/     데이터 생성, 측정, 완전 탐색처럼 증거를 만드는 데 쓴 스크립트
+tests/oracle/  판정기와 그 시험 (verify.md)
+```
+
+- 로그 이름은 `<문서>-<무엇>-<YYYYMMDD-HHMMSS>.log` 다. 같은 시험을 다시 돌리면 새 파일을 만들고, 문서는 마지막 로그를 가리킨다.
+- 로그는 명령의 표준 출력과 표준 오류를 함께 담고, 첫 줄에 실행한 명령, 마지막 줄에 종료 코드를 남긴다.
+
+```bash
+run_log() {  # run_log <로그 경로> <명령...>
+  mkdir -p "$(dirname "$1")"; f=$1; shift
+  { echo "\$ $*"; "$@"; echo "exit=$?"; } > "$f" 2>&1
+}
+```
+
+## 진행
+
+먼저 저장소를 읽는다: README, 시작 스크립트, 시험 실행 방법, 최적화 코드, DB 스키마, 내보내기 코드.
+문서 여섯은 아래 순서로 만든다. `verify.md` 의 판정기는 다른 문서보다 먼저 쓴다.
+
+### 1. optimize.md
+
+| 항목 | 내용 |
+|---|---|
+| 목적 함수 | 최소화 또는 최대화하는 값과 식 |
+| 제약 | 제약마다 한 줄. 강한 제약과 약한 제약(벌점)을 나눔 |
+| 알고리즘 이름 | 쓴 알고리즘의 이름(예: 정수 계획법, 담금질, 탐욕 + 지역 탐색). 라이브러리를 쓰면 그 이름과 판 |
+| 핵심 함수 | `파일:줄` 로. 목적값 계산, 제약 검사, 탐색 본체를 각각 |
+| 의사코드 | 10줄 |
+
+- `파일:줄` 은 지금 커밋에서 실제로 그 줄을 열어 확인한 것만 쓴다. 문서 끝에 확인한 커밋 해시를 적는다.
+- 이 문서에는 실행 수치가 없다. 실행 명령 칸에는 줄 번호를 확인한 명령(예: `grep -n 'def objective' src/opt.py`)과 그 출력 로그를 적는다.
+
+### 2. verify.md
+
+판정기(oracle)는 구현을 보지 않은 하위 에이전트가 쓴다. 구현을 본 맥락이 판정기를 쓰면 구현의 실수를 판정기도 따라 한다.
+
+1. **담당자 사실을 모은다.** 담당자(사용자)가 준 업무 규칙, 수치 기준, 권한 규칙을 `docs/evidence/owner-facts.md` 에 그대로 옮긴다. 담당자 사실이 없으면 사용자에게 묻는다. 그래도 없으면 README 만으로 진행하고 그 사실을 `verify.md` 에 적는다.
+2. **새 맥락 하위 에이전트를 띄운다.** 이 대화를 넘기지 않는다.
+   - Claude Code: Agent 도구를 `general-purpose` 로, `model` 없이 부른다.
+   - Codex: `spawn_agent` 를 `agent_type` 과 `model` 없이 부르고 대화를 넘기지 않는다(multi-agent v2 는 `fork_turns="none"`, v1 은 `fork_context` 를 주지 않음).
+   - 지시에 들어갈 것:
+     - 읽어도 되는 것은 `README.md` 와 `docs/evidence/owner-facts.md` 둘뿐이다.
+     - 구현 폴더와 기존 시험은 열지 않는다.
+     - 쓸 곳은 `tests/oracle/` 다.
+     - 판정기는 입력과 출력만 보고 세 가지를 판정한다.
+       - 제약을 모두 지키는가
+       - 보고된 목적값이 입력과 출력으로 다시 계산한 값과 같은가
+       - 권한 규칙을 지키는가
+     - 시험은 판정기를 쓴다.
+     - 끝에 읽은 파일 목록을 보고한다.
+3. **읽은 파일 목록을 확인한다.** 목록에 두 파일 밖의 경로가 있으면 그 판정기는 버리고 다시 띄운다. 목록은 `verify.md` 에 옮긴다.
+4. **판정기를 구현보다 먼저 커밋한다.** 커밋 메시지는 `test(oracle): ...` 다. 구현이 아직 없으면 이 커밋이 구현 커밋보다 앞선다. 구현이 이미 있으면 그 사실과 두 커밋의 순서(`git log --format='%h %ad %s' --date=iso -- tests/oracle <구현 경로>`)를 그대로 적는다. 순서를 꾸미지 않는다.
+5. **판정기를 지금 구현에 돌린다.** 명령과 로그 경로, 통과와 실패 수를 로그에서 옮긴다.
+6. **일부러 넣은 버그 셋을 판정기가 잡는지 본다.**
+
+   | 버그 | 넣는 방법의 예 |
+   |---|---|
+   | 제약 위반 | 제약 검사 한 줄을 건너뛰게 바꿈 |
+   | 목적값 오계산 | 목적값 합산에서 항 하나를 빼거나 부호를 바꿈 |
+   | 권한 우회 | 권한 확인을 늘 통과하게 바꿈 |
+
+   - 버그마다 차례로 진행한다.
+     1. 바꾼 것을 패치 파일로 남긴다: `docs/evidence/logs/verify-bug-<이름>.patch`
+     2. `git apply` 로 넣는다.
+     3. 판정기를 돌려 로그를 남긴다.
+     4. `git apply -R` 로 되돌린다.
+     5. `git status --short` 와 `git diff --stat` 이 빈 것을 로그로 남긴다.
+   - 표에는 버그마다 다섯 가지를 적는다: 패치 경로, 넣은 뒤 결과(잡음 또는 놓침), 로그 경로, 되돌린 명령, 되돌린 뒤 판정기 결과.
+   - 놓친 버그는 놓쳤다고 쓰고, 판정기의 빈틈을 한 줄로 적는다. 놓친 것을 잡게 하려고 판정기를 고치면 그 커밋과 재실행 로그를 더한다.
+   - 되돌리기가 실패하면 멈추고 사용자에게 알린다. 작업 트리를 지우거나 덮어쓰지 않는다.
+
+### 3. flow.md
+
+- 순서는 화면, API, 최적화, DB, 내보내기다.
+- 단계마다 그 단계를 처리하는 `파일:줄` 을 적는다. 화면은 요청을 보내는 코드, API 는 라우트와 처리 함수, 최적화는 호출 지점, DB 는 쓰기와 읽기 쿼리, 내보내기는 파일을 만드는 함수다.
+- **종단 시험**: `{host}:{port}` 에 떠 있는 서버에 실제 요청을 보내 다섯 단계를 끝까지 지난다.
+  - 스크립트는 `docs/evidence/scripts/e2e-flow.*` 다.
+  - 서버가 떠 있지 않으면 저장소의 시작 방법으로 띄운다. 띄운 명령과 그 로그를 적는다.
+  - 화면 단계는 브라우저 도구(Playwright 등)가 있으면 실제로 누르고, 없으면 화면 URL 의 응답과 화면이 부르는 API 요청을 그대로 보낸다. 어느 쪽인지 적는다.
+  - 단계마다 다섯 가지를 로그에 남긴다: 요청, 응답 코드, 걸린 시간, DB 에 생긴 행의 확인 쿼리 결과, 내보낸 파일의 이름과 크기.
+- 서버에 닿지 못하면 종단 시험 칸은 `미검증` 과 오류 문구다. 단위 시험으로 대신하지 않는다.
+- 운영 서버나 남의 서버에는 보내지 않는다. 대상이 로컬이나 개발 서버가 아니면 사용자에게 먼저 확인한다.
+
+### 4. scale.md
+
+- **데이터 1배, 5배, 10배**: 기준 데이터(README 의 예시나 시험 고정물)를 늘리는 스크립트 `docs/evidence/scripts/gen-scale.*` 로 만든다. 같은 시드로 다시 만들 수 있게 시드를 고정하고 적는다.
+- 배수마다 최적화를 돌려 걸린 시간과 목적값을 잰다. 한 배수를 3회 돌려 각 값과 중앙값을 로그에 남긴다.
+- **작은 사례 다섯**: 완전 탐색이 끝나는 크기로 다섯 개를 만들고, 완전 탐색 스크립트 `docs/evidence/scripts/brute-force.*` 로 정해를 구한다.
+  - 사례마다 구현의 목적값과 정해를 적는다.
+  - 차이(%)는 `|구현 - 정해| / |정해| x 100` 이다. 정해가 0 이면 차이 대신 두 값을 그대로 적는다.
+  - 차이도 스크립트가 계산해 로그에 찍는다.
+- 표의 칸마다 로그 경로를 단다. 시간 제한에 걸린 배수는 `시간 초과(제한 N초)` 로 적는다.
+
+### 5. decisions.md
+
+결정마다 한 행이다.
+
+| 결정 | 고른 것 | 버린 것 | 이유 | 확인하는 시험 |
+|---|---|---|---|---|
+
+- 결정은 코드와 커밋 기록, README, ADR 이 있으면 ADR 에서 찾는다. 찾은 곳을 적는다.
+- 확인하는 시험은 실제로 있는 시험의 이름이다. 이름마다 통과 로그 경로를 단다. 그 결정을 확인하는 시험이 없으면 `없음` 으로 적는다. 이름을 지어내지 않는다.
+
+### 6. trace.md
+
+README 의 요구마다 한 행이다.
+
+| 번호 | 요구 | 상태 | 시험 이름 | 로그 경로 |
+|---|---|---|---|---|
+
+- 번호는 README 에 나온 순서로 `R1`, `R2` 다. 요구 칸에는 README 문장을 줄이지 않고 옮긴다.
+- 상태는 셋 가운데 하나다.
+  - `완료`: 그 요구를 확인하는 시험이 있고 통과함
+  - `부분`: 일부만 구현했거나 시험이 일부만 확인함. 빠진 부분을 적음
+  - `미구현`: 이유를 적음
+- 시험이 실패하면 `완료` 로 쓰지 않는다. 시험이 없으면 `완료` 가 아니라 `부분` 이고, 시험이 없다고 적는다.
+- 마지막에 상태별 개수를 적는다. 개수도 표에서 센 것이다.
+
+## 수치 대조
+
+문서를 다 쓴 뒤, 문서에 적은 수마다 그 칸이 가리키는 로그에 같은 수가 있는지 확인한다.
+
+- 문서의 숫자(시간, 목적값, 차이, 개수)를 하나씩 뽑아 가리킨 로그에서 찾는다(`grep -F`).
+- 로그에서 찾지 못한 수는 지우거나, 그 수를 찍는 명령을 다시 돌려 로그를 만든다.
+- 대조 결과(확인한 수의 개수, 못 찾은 수)를 각 문서 끝의 `수치 대조` 줄에 적는다.
+
+## 커밋
+
+- 커밋 대상은 `docs/evidence/` 와 `tests/oracle/` 뿐이다. 다른 경로는 넣지 않는다.
+  - 증거를 만들다 구현을 고쳤다면 그 수정은 따로 커밋하고 사용자에게 알린다.
+  - 판정기 커밋은 2번의 4단계에서 이미 했다.
+- 커밋 전에 비밀값을 찾는다. 걸린 값은 가린다. 커밋 메시지는 `docs(evidence): ...` 다.
+- push 하지 않는다. 사용자가 요청할 때만 한다.
+- `--no-commit` 이면 쓸 파일 목록만 보이고 커밋하지 않는다.
+
+## 런타임
+
+- Claude Code: `/banker:make-evidence`. 하위 에이전트는 Agent 도구다.
+- Codex: npm 길 `$banker-make-evidence`, 플러그인 길 `$banker:make-evidence`. 하위 에이전트는 `spawn_agent` 다.
+  - 기본 샌드박스가 `.git` 쓰기를 막으면 커밋 명령에 `sandbox_permissions: "require_escalated"` 를 청한다.
+  - 로컬이 아닌 서버에 보내는 종단 시험은 네트워크 승인이 필요하다.
+
+## 보고
+
+끝나면 표 하나로 알린다.
+
+| 문서 | 상태 | 로그 수 | 미검증이나 미구현 |
+|---|---|---|---|
+
+- 상태는 `작성`, `일부 미검증`, `작성 안 함(까닭)` 가운데 하나다.
+- 커밋 해시를 적는다. push 는 하지 않았다고 적는다.