@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/cli-review-dispatch-command.js

@@ -0,0 +1,338 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const fs = require('node:fs');
+const path = require('node:path');
+// 표식 확인용 가벼운 모듈. review-dispatch 그래프는 끌어오지 않는다(lazy require 계약).
+const frontmatter = require("./frontmatter");
+const schema = require("./schema");
+const cliFlags = require("./cli-flags");
+const { parseFlags, argvRequestsHelp } = cliFlags;
+// validate-sections는 ./paths 계열만 정적으로 끌어오므로(intent 모듈 없음) help 문자열을
+// 검증기 상수에서 만들어도 ./review-dispatch lazy require 계약이 깨지지 않는다.
+const validateSections = require("./validate-sections");
+const { CONTEXT_REVIEW_PERSPECTIVE, CONTEXT_REVIEW_STATUS, REVIEW_SEVERITY, findingFingerprint, REPORT_FINDING_STATUS, FINDING_ACTIONABILITY, FINDING_ORIGIN, CONTEXT_ROUND_MODES, } = validateSections;
+const USAGE = `usage: bouncer review-dispatch <plan|execute> [options]
+
+  review-dispatch plan --blueprint <dir> [--previous <file>]
+             Classify plan context-review strategy (read-only JSON).
+  review-dispatch execute --blueprint <dir> [--task <ddd>] --base <sha> --head <sha> [--mode discovery|delta]
+             Classify execute review strategy from the frozen final worktree state
+             (JSON). Writes only the snapshot artifact under .bouncer/runtime/
+             review-snapshots/ and returns target.snapshot_id/snapshot_path; --head
+             must be the current HEAD. On failure it prints reason/cause/next, exit 1.
+             When that blueprint's scale is light, returns single/combined
+             regardless of diff size. A blueprint with review_contract brief gets the
+             brief-compliance perspectives; only it accepts --mode delta without --task.
+`;
+// 예시 finding의 구성 요소. fingerprint는 아래에서 검증기와 같은 함수로 계산해
+// 손으로 쓴 값이 공식과 어긋나는 일(fingerprint mismatch)을 없앤다.
+const EXAMPLE_FINDING = {
+    category: 'scope',
+    brief_clause: 'tasks/001 touch',
+    file: '.bouncer/context/epics/014-auth/blueprints/001-signup/tasks/001/tasks.md',
+    symbol: 'touch',
+};
+/**
+ * `review-dispatch --help`에 실리는 `bouncer.context_review` 예시. 들여쓰기는
+ * `bouncer:` 아래에 붙인 `context_review:` 블록 그대로이고, `<target.digest>` 두 곳만
+ * `review-dispatch plan` 출력 값으로 바꾸면 기록 검증을 통과한다. fence는 하나만 둔다.
+ */
+const HELP_CONTEXT_REVIEW_EXAMPLE = `context_review:
+  rounds:
+    - round: 1
+      mode: discovery
+      target: { digest: <target.digest> }
+      perspectives:
+        - { name: combined, target_digest: <target.digest> }
+      severity_changes: []
+  findings:
+    - id: CR-1
+      severity: minor
+      status: accepted
+      note: Wording only; the clause is still unambiguous.
+      category: ${EXAMPLE_FINDING.category}
+      brief_clause: ${EXAMPLE_FINDING.brief_clause}
+      file: ${EXAMPLE_FINDING.file}
+      symbol: ${EXAMPLE_FINDING.symbol}
+      fingerprint: ${findingFingerprint(EXAMPLE_FINDING, 'context')}
+      actionability: advisory
+      origin: discovery
+      first_seen_round: 1
+      last_seen_round: 1`;
+/**
+ * `review-dispatch --help` stdout 본문. plan 에이전트가 검증기 소스를 열지 않고
+ * 기록 검증을 통과하는 기록을 쓰도록 형식·enum·digest 출처를 한곳에 모은다.
+ */
+const HELP = `${USAGE}
+Context review record shape (plan). Reports are recorded with
+\`bouncer context-review record\`; the projection it returns on --status accepted has
+this shape and goes under \`bouncer:\` in context-review.md. Do not hand-write rounds.
+
+\`\`\`yaml
+${HELP_CONTEXT_REVIEW_EXAMPLE}
+\`\`\`
+
+Enums:
+  severity: ${REVIEW_SEVERITY.join('|')}
+  finding status (context-review.md): ${CONTEXT_REVIEW_STATUS.join('|')} (accepted requires note)
+  finding status (record input): ${REPORT_FINDING_STATUS.join('|')} (open is in-progress only)
+  actionability: ${FINDING_ACTIONABILITY.join('|')}
+  origin: ${FINDING_ORIGIN.join('|')}
+  round mode: ${CONTEXT_ROUND_MODES.join('|')}
+  perspective name (also finding category): ${CONTEXT_REVIEW_PERSPECTIVE.join('|')}
+
+fingerprint formula: context:lower(category):lower(brief_clause):posix(file)#symbol
+
+Do not compute the digest. Copy \`target.digest\` from the JSON that
+\`review-dispatch plan --blueprint <dir>\` prints into both <target.digest>
+places. When it prints \`ok: false\` there is no digest: do not call a reviewer.
+
+Plan fields (\`single\` or \`perspectives\`; older stored \`clustered\` payloads are still read;
+absent on \`skip\` and failures):
+  A blueprint with review_contract brief gets strategy \`perspectives\`: full runs consistency, scope_minimality,
+  verifiability and risk_security in parallel; light runs verifiability only (one reviewer call per perspective).
+  snapshot_version 2. target.digest hashes the ordered {file, body, structure} of
+                   every plan document; status/title/timestamp/commit evidence are excluded
+  parts            per-document body sha256 (epic index, blueprint index, each tasks.md)
+  structure_parts  per-document sha256 of the normalized judgement structure
+                   (task: affected_paths, depends_on, parallel_safe, dependency_gate,
+                   exclusive_resources, execution_kind; blueprint: scale, review_scope)
+  scope_parts      observation only (Interface/Touch/affected_paths/depends_on hash);
+                   never used to choose follow_up
+  documents_content  path -> {body, structure}; the immutable content a later
+                   \`--previous\` run diffs against (no git or working-tree lookup)
+  follow_up        \`full\` | \`partial\` — compare with \`--previous <file>\` (the
+                   stored prior plan JSON). Omit \`--previous\` only for a first
+                   classification with no review evidence → \`full\`, every current
+                   document in changed_documents, before null.
+  changed_documents sorted union of added/removed/body-changed/structure-changed paths
+  related_documents contract references for the delta reviewer: changed tasks' previous
+                   and current cluster neighbours, DAG predecessors/successors (transitive),
+                   epic and blueprint; all tasks when epic/blueprint changed; the whole
+                   current set on \`full\`. Changed documents are not repeated (partial).
+  revision_diff    [{file, before, after}] with {body, structure}; added/removed
+                   documents null their missing side
+
+\`full\` when the document set or any document's normalized structure differs (task
+added/removed, affected_paths, depends_on, parallel_safe, exclusive_resources,
+execution_kind, scale/review_scope) or when \`--previous\` is a digest-only legacy
+payload (before null, reason legacy-payload-no-content, counts as a restart);
+otherwise every prose edit, including epic/blueprint, Interface and Touch, is
+\`partial\`. Once a cycle or recorded rounds exist, \`--previous\` is required and
+must equal the cycle latest_dispatch. Failures print
+\`{ ok: false, reason, cause, next }\` (exit 1) with reason
+previous-payload-required | previous-payload-invalid | previous-payload-stale.
+`;
+/**
+ * review-dispatch argv를 plan/execute로 분기한다. 잘못된 사용법은 resolver를
+ * 열기 전에 거절해 exit 2와 운영 실패(exit 1)를 구분한다.
+ *
+ * @param {string[]} rest - `review-dispatch` 뒤 argv
+ * @returns {ParsedArgs} 성공 시 mode별 필드, 실패 시 error
+ */
+function parseReviewDispatchArgs(rest) {
+    const sub = rest[0];
+    if (sub !== 'plan' && sub !== 'execute') {
+        return { mode: 'usage', error: `review-dispatch: command must be plan or execute\n${USAGE}` };
+    }
+    if (sub === 'plan')
+        return parsePlanArgs(rest.slice(1));
+    return parseExecuteArgs(rest.slice(1));
+}
+/**
+ * plan 하위 명령 인자. --blueprint는 필수, --previous는 이전 payload 경로다.
+ * 분류기는 문서를 읽기만 한다.
+ *
+ * @param {string[]} rest - `plan` 뒤 argv
+ * @returns {ParsedPlan} 성공 필드 또는 error
+ */
+function parsePlanArgs(rest) {
+    const f = parseFlags(rest);
+    const fail = (message) => ({
+        mode: 'plan',
+        error: `review-dispatch plan: ${message}\n`,
+        blueprint: null,
+        previous: null,
+    });
+    if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+        return fail('--blueprint is required');
+    }
+    // --previous만 있고 경로가 없으면 boolean true가 된다. 파일 부재(exit 1)와
+    // 구분하기 위해 사용법 거절(exit 2)로 돌린다.
+    if (Object.prototype.hasOwnProperty.call(f, 'previous')
+        && (typeof f.previous !== 'string' || f.previous === '')) {
+        return fail('--previous requires a file');
+    }
+    // parseFlags는 중복 플래그에서 마지막 값을 조용히 택한다. 어느 previous가 대조되는지
+    // 모호해지므로 분류기 전에 사용법 오류(exit 2)로 막는다.
+    for (const flag of ['--blueprint', '--previous']) {
+        if (rest.filter((tok) => tok === flag).length > 1)
+            return fail(`${flag} may be given only once`);
+    }
+    if (f.repo !== undefined && (typeof f.repo !== 'string' || f.repo === '')) {
+        return fail('--repo requires a directory');
+    }
+    return {
+        mode: 'plan',
+        blueprint: f.blueprint,
+        previous: typeof f.previous === 'string' ? f.previous : null,
+        repo: typeof f.repo === 'string' ? f.repo : undefined,
+    };
+}
+/**
+ * execute 하위 명령 인자. frozen base/head가 빠지면 분류를 시작하지 않는다.
+ * `--task`는 한 commit task 범위일 때만 필수이고, 생략하면 blueprint 전체
+ * numstat·위험 합집합으로 간다 — 최종 리뷰가 task 하나를 강제하면 CLI가
+ * 분류기보다 좁아진다. `--mode`는 discovery|delta만 받고, 없으면 discovery다.
+ *
+ * @param {string[]} rest - `execute` 뒤 argv
+ * @returns {ParsedExecute} 성공 필드 또는 error
+ */
+function parseExecuteArgs(rest) {
+    const f = parseFlags(rest);
+    const fail = (message) => ({
+        mode: 'execute',
+        error: `review-dispatch execute: ${message}\n`,
+        blueprint: null,
+        task: null,
+        base: null,
+        head: null,
+        reviewMode: 'discovery',
+    });
+    if (typeof f.blueprint !== 'string' || f.blueprint === '') {
+        return fail('--blueprint is required');
+    }
+    if (Object.prototype.hasOwnProperty.call(f, 'task')
+        && (typeof f.task !== 'string' || f.task === '')) {
+        return fail('--task <ddd> is required');
+    }
+    if (typeof f.base !== 'string' || f.base === '') {
+        return fail('--base <sha> is required');
+    }
+    if (typeof f.head !== 'string' || f.head === '') {
+        return fail('--head <sha> is required');
+    }
+    if (f.repo !== undefined && (typeof f.repo !== 'string' || f.repo === '')) {
+        return fail('--repo requires a directory');
+    }
+    // --mode만 있으면 parseFlags가 boolean true를 준다. 분류기 전에 거절해
+    // require.cache에 review-dispatch가 남지 않게 한다(usage exit 2 계약).
+    if (Object.prototype.hasOwnProperty.call(f, 'mode')) {
+        if (f.mode !== 'discovery' && f.mode !== 'delta') {
+            return fail('--mode must be discovery or delta');
+        }
+    }
+    // task 없는 delta는 여기서 거절하지 않는다. review_contract 표식이 있는 blueprint만
+    // 받으므로 표식 확인이 필요하고, 그 확인은 분류기 적재 전 cmdReviewDispatch가 맡는다.
+    return {
+        mode: 'execute',
+        blueprint: f.blueprint,
+        task: typeof f.task === 'string' ? f.task : null,
+        base: f.base,
+        head: f.head,
+        reviewMode: f.mode === 'delta' ? 'delta' : 'discovery',
+        repo: typeof f.repo === 'string' ? f.repo : undefined,
+    };
+}
+const DELTA_NEEDS_TASK = 'review-dispatch execute: --mode delta requires --task <ddd>'
+    + ' (the blueprint final review has no delta round)\n';
+/**
+ * task 없는 `--mode delta`를 분류기 적재 전에 거절해야 하는지 판정한다.
+ * review_contract brief 표식 blueprint만 이 호출을 받는다. 표식 확인은 분류기를
+ * require하지 않도록 `readDoc`과 `reviewContractOf`만 쓴다.
+ *
+ * @param {ParsedExecute} parsed - task 없는 delta로 해석된 execute 인자
+ * @returns {string | null} 거절 시 stderr 메시지(exit 2), 표식이 brief면 null
+ */
+function blueprintDeltaRefusal(parsed) {
+    const repoRoot = parsed.repo ? parsed.repo : process.cwd();
+    let bouncer;
+    try {
+        const doc = frontmatter.readDoc(path.join(repoRoot, parsed.blueprint, 'index.md'));
+        bouncer = doc.data?.bouncer;
+    }
+    catch {
+        // index 부재·파싱 실패를 모두 기존 --task 사용법 메시지로 접는다. 표식을 읽지
+        // 못한 호출은 legacy와 구분할 수 없고, legacy 출력을 보존하는 것이 이 경로의 계약이다.
+        return DELTA_NEEDS_TASK;
+    }
+    const contract = schema.reviewContractOf(bouncer);
+    if (contract === 'brief')
+        return null;
+    if (contract === null)
+        return `review-dispatch execute: ${schema.REVIEW_CONTRACT_INVALID_MESSAGE}\n`;
+    return DELTA_NEEDS_TASK;
+}
+/**
+ * 공개 review-dispatch 핸들러. 분류 모듈과 stdout JSON·exit 계약만 연결한다.
+ *
+ * @param {string[]} rest - 서브커맨드와 플래그
+ * @param {CliIo} io - stdout/stderr 싱크
+ * @returns {number} 도움말·성공 0, 분류 거절 1, 사용법 2
+ */
+function cmdReviewDispatch(rest, io) {
+    // help는 argv 해석·분류기 적재보다 앞에서 끝낸다. 도움말이 파일·git을 읽지 않게 함.
+    if (argvRequestsHelp(rest)) {
+        io.out(HELP);
+        return 0;
+    }
+    const parsed = parseReviewDispatchArgs(rest);
+    if (parsed.mode === 'usage' || parsed.error) {
+        io.err(parsed.error || USAGE);
+        return 2;
+    }
+    if (parsed.mode === 'execute' && parsed.reviewMode === 'delta' && parsed.task === null) {
+        const refusal = blueprintDeltaRefusal(parsed);
+        if (refusal !== null) {
+            io.err(refusal);
+            return 2;
+        }
+    }
+    // argv를 통과한 뒤에만 분류기를 적재한다. 사용법 거절이 review-dispatch·
+    // validate 그래프를 require.cache에 남기지 않게 하기 위함.
+    const reviewDispatch = require('./review-dispatch');
+    const repoRoot = (parsed.repo ? parsed.repo : process.cwd());
+    if (parsed.mode === 'plan') {
+        let previous;
+        if (parsed.previous) {
+            // 파일 부재·비JSON은 분류기 전에 거절한다. parts 부재는 분류기가
+            // previous-payload-invalid로 돌린다 — 읽기 실패와 같은 reason으로 맞춘다.
+            try {
+                const raw = fs.readFileSync(parsed.previous, 'utf8');
+                previous = JSON.parse(raw);
+            }
+            catch {
+                // ENOENT·SyntaxError·권한 오류를 모두 같은 reason으로 접는다. 운영자가
+                // 경로/형식을 고치면 되고, 세부 errno를 strategy 실패와 섞지 않기 위함.
+                io.out(`${JSON.stringify({
+                    ok: false,
+                    reason: 'previous-payload-invalid',
+                    cause: 'previous file is missing, unreadable, or not JSON',
+                    next: 'pass the unmodified JSON that review-dispatch plan printed (the stored cycle latest_dispatch)',
+                }, null, 2)}\n`);
+                return 1;
+            }
+        }
+        const result = reviewDispatch.classifyPlanReview({
+            repoRoot,
+            blueprintDir: parsed.blueprint,
+            ...(previous !== undefined ? { previous } : {}),
+        });
+        io.out(`${JSON.stringify(result, null, 2)}\n`);
+        return result.ok ? 0 : 1;
+    }
+    const result = reviewDispatch.classifyExecuteReview({
+        repoRoot,
+        blueprintDir: parsed.blueprint,
+        ...(parsed.task ? { taskId: parsed.task } : {}),
+        base: parsed.base,
+        head: parsed.head,
+        reviewMode: parsed.reviewMode,
+    });
+    io.out(`${JSON.stringify(result, null, 2)}\n`);
+    return result.ok ? 0 : 1;
+}
+module.exports = {
+    run: cmdReviewDispatch,
+    usage: cliUsage.COMMAND_USAGE['review-dispatch'],
+};

package/dist/cli-usage.js

@@ -0,0 +1,72 @@
+'use strict';
+/* eslint-disable max-len -- Static usage text intentionally preserves terminal output lines. */
+// 도움말은 기능 모듈 없이 출력되어야 하므로 문자열만 정적 보유한다.
+const COMMAND_USAGE = Object.freeze({
+    'validate': '  validate   --blueprint <dir> --gate <plan|execute|commit|finalize>\n             Run the structural checks and one gate. Reports failure codes.\n',
+    'verify': '  verify     --blueprint <dir>\n             Run the configured verify command and record its evidence.\n',
+    'scaffold': '  scaffold   epic --id <ddd> --name <slug> --description <text>\n             epic --name <slug> --description <text>   (v2 registry: slug epic, no --id)\n             blueprint --epic-dir <dir> --id <ddd> --name <slug> [--scale light|full]\n                  [--area <a>] [--attribution <text>]\n             blueprint --epic-dir <slug-epic> --order <n> --name <slug> [--scale light|full]\n                  [--area <a>] [--attribution <text>]\n             task --blueprint <dir> --id <ddd> [--execution-kind commit|verification]\n                  [--depends-on TASKS-NNN[,TASKS-NNN...]] [--verify <command>]\n             explain --blueprint <dir>\n             context-review --blueprint <dir>\n             Create a document set with correct frontmatter.\n             blueprint writes index.md, review.md, and (full) context-review.md;\n             a new task writes tasks.md and verification.md (legacy blueprints\n             without review_scope still get task review.md).\n             (explain is for finalize; epic/blueprint scaffold omit it.)\n',
+    'commit': '  commit     --blueprint <dir> [--yes]\n             Check task commit scope and, with --yes, commit one task.\n',
+    'commit-guard': '  commit-guard --staged [--repo <dir>]\n  commit-guard --command-stdin [--repo <dir>]\n             Allow or block a commit from the current index (git pre-commit) or a hook-supplied command.\n',
+    'finalize': '  finalize   prepare --blueprint <dir>\n             Print a read-only finalize digest JSON for Explain, Quiz, and PR.\n  finalize   links --blueprint <dir>\n             Print Explain URL candidates for a pushed GitHub head (read-only).\n  finalize   pr-body --digest <json-file> --summary <markdown-file> [--flow <mermaid-file>]\n             Print a draft PR body from a saved digest and a Korean summary (read-only, stdout).\n  finalize   comprehension --blueprint <dir> --digest <json-file> (--confirm-quiz | --refresh) [--repo <dir>]\n             Record the single explain.md comprehension entry after the user answered the quiz.\n             --refresh only updates an existing valid entry; the flags are mutually exclusive.\n  finalize   partial-finalize --blueprint <dir> [--yes --confirm-partial-finalize]\n             Review a partial_closed drive; explicit confirmation clears its pointer and worktrees.\n  finalize   release-main --blueprint <dir> [--allow-partial-merge --confirm-partial-merge]\n             Run from main; partial merge requires both independent flags.\n  finalize   worktree-path --blueprint <dir> [--repo <dir>]\n             Print the execute worktree path for a blueprint (read-only, one line).\n  finalize   diff-sha --base <ref> [--repo <dir>]\n             Print the explain diff_sha as JSON (read-only); exit 1 when ok is false.\n  finalize   --blueprint <dir> [--yes]\n             Check the commit scope and, with --yes, commit the blueprint.\n',
+    'seed-worktree': '  seed-worktree --blueprint <dir> --to <worktree>\n             Move the plan context documents into a freshly created worktree.\n',
+    'execute': '  execute    prepare --blueprint <dir>\n             Create or reuse the execute worktree, seed plan documents, and print JSON.\n',
+    'plan': '  plan       inspect [--epic-dir <dir>] [--blueprint <dir>]\n             Print epic registry candidates, next domain epic id, verify signals, pointer state,\n             and optional advisory light routing as JSON.\n  plan       approve --blueprint <dir> [--repo <dir>]\n             Move epic, blueprint, and task status to approved/ready in one\n             all-or-nothing step. Run only after the user approves the plan.\n',
+    'run': "  run        preflight --blueprint <dir>\n             Print pointer, open tasks, DAG, ready wave, and autonomy as JSON.\n  run        detach --blueprint <dir> --yes [--reason <text>]\n             After approval, preserve the ledger, mark the run detached, and remove this blueprint's pointer.\n",
+    'coordinate': '  coordinate <bootstrap|prepare|ready|dispatch|report|record|rerecord|integrate|status|revoke> --blueprint <dir>\n             [--task <ddd>] [--sha <sha>] [--lease-id <id>] [--generation <n>]\n             Operate the coordinator ledger and isolated integration worktrees.\n  coordinate integrate --blueprint <dir> [--task <ddd>]\n             --ledger-path <path> --ledger-hash <sha256>\n             Fan-in recorded commit tasks via a candidate worktree (omit --task for the wave).\n  coordinate dispatch --blueprint <dir> --task <ddd> --ledger-path <path> --ledger-hash <sha256>\n             [--repo <main>] [--lease-id <id> --generation <n>] [--model <value>]\n             Open one dispatch attempt on the assigned worker and return brief/HEAD metadata.\n  coordinate report --blueprint <dir> --task <ddd> --attempt <n>\n             --task-brief-hash <sha256> --outcome <accepted|rework|scope_revision|task_change|blocked>\n             --summary <text> --ledger-path <path> --ledger-hash <sha256> [--repo <main>]\n             [--lease-id <id> --generation <n>]\n             Record a worker report against the active attempt, or append stale-report evidence.\n  coordinate revoke --blueprint <dir> --task <ddd> --reason <text>\n             --ledger-path <path> --ledger-hash <sha256>\n             Revoke an active lease, clear dispatch/sha, and return the task to pending.\n  coordinate rerecord --blueprint <dir> --task <ddd> --reason <text>\n             --ledger-path <path> --ledger-hash <sha256> [--sha <sha>]\n             Replace a recorded worker SHA with its direct-child HEAD and preserve the decision.\n  coordinate repair --blueprint <dir> --task <ddd> --failure-command <cmd>\n             --summary <text> --paths <p> --decision <reason>\n             --ledger-path <path> --ledger-hash <sha256>\n             Add one audited repair task and move the terminal CI dependency.\n  coordinate repair --blueprint <dir> [--task <ddd>] --review-finding <id>\n             [--review-finding <id>]... --summary <text> --paths <p> --decision <reason>\n             --ledger-path <path> --ledger-hash <sha256>\n             Open a repair task from final-review must_fix findings (omit --task\n             when the blueprint has no terminal verification).\n  coordinate repair --blueprint <dir> --kind supplement --review-finding <id>\n             [--review-finding <id>]... --summary <text> --paths <test-path>\n             --ledger-path <path> --ledger-hash <sha256>\n             Accept an in-scope test-evidence gap in place (no new task or wave).\n  coordinate repair --blueprint <dir> --kind supplement --done --summary <text>\n             --ledger-path <path> --ledger-hash <sha256>\n             Verify the finished supplement; then run the one delta review.\n  coordinate reverify --blueprint <dir> --task <terminal ddd>\n             --ledger-path <path> --ledger-hash <sha256>\n             Re-run the terminal verification after an environment-only fix (no repair wave).\n  coordinate partial-close --blueprint <dir> --user-confirmed\n             --ledger-path <path> --ledger-hash <sha256>\n             Preserve the failed drive and mark it partial_closed after two repair waves.\n  coordinate critical-recovery --blueprint <dir> --task <ddd> --findings <id>\n             [--findings <id>]... --reason <text>\n             --ledger-path <path> --ledger-hash <sha256>\n             Record the one permitted blocker or major recovery for a prepared task.\n  coordinate critical-recovery --blueprint <dir> --task <ddd> --outcome <resolved|blocked>\n             --reason <text> --ledger-path <path> --ledger-hash <sha256>\n             Record the outcome without permitting another recovery.\n  coordinate revise --blueprint <dir> --task <ddd> --paths <p> [--paths <p>]...\n             [--release-do-not-touch <p>]... --reason <text> --ledger-path <path> --ledger-hash <sha256>\n             Record one scope decision in the task document and ledger.\n             --paths replaces the whole scope with exactly the given set.\n             --release-do-not-touch <p> drops one overlapping Do not touch entry from the brief.\n             Takes no --repo: the write boundary is the current directory, so\n             run it from the assigned task worktree, not the main checkout.\n  coordinate next --blueprint <dir> [--task <ddd>] [--repo <dir>]\n             Print the next coordinator action and filled argv without mutating the ledger.\n  coordinate advance --blueprint <dir> [--task <ddd>] [--max-steps <n>] [--repo <dir>]\n             Run deterministic next argv actions until judge, worker, terminal, or error.\n  coordinate promote-stop --blueprint <dir> --reason <enum> --summary <text>\n             --ledger-path <path> --ledger-hash <sha256>\n             Stop a light ledger for promotion; records reason and state (no resume).\n  coordinate session-open --blueprint <dir> --ledger-path <path> --ledger-hash <sha256>\n             Record a coordinator session boundary before dispatching a new coordinator.\n  coordinate worker-model --blueprint <dir> --role <implementer|reviewer|debugger> --model <value>\n             --ledger-path <path> --ledger-hash <sha256> [--task <ddd>] [--perspective <name>]\n             [--tokens <n>]\n             Record the model argument (and host-reported tokens) of a worker dispatch.\n  coordinate worker-tokens --blueprint <dir> --role <implementer|reviewer|debugger> --tokens <n>\n             --ledger-path <path> --ledger-hash <sha256> [--task <ddd>] [--perspective <name>]\n             Append host-reported subagent tokens that arrived after the worker-model record.\n  coordinate note --blueprint <dir> --text <text> --ledger-path <path> --ledger-hash <sha256> [--task <ddd>]\n             Leave a handoff note for the next coordinator session (no dispatch, lease, or status change).\n  Mutations (except bootstrap/status) require --ledger-path and --ledger-hash from\n  the latest status checkpoint so stale ledger writes are rejected before mutation.\n',
+    'init': '  init       [--upgrade-graphify] [--pre-commit-hook]\n             [--profile <standard|domain-only>] [--domain-epic-limit <n>]\n             Bootstrap .bouncer/ for this project. Never overwrites.\n',
+    'graph-sync': '  graph-sync Rebuild stale graphify source + test graphs (SessionStart / plan).\n',
+    'intent': '  intent     --symbol <function-name> [--candidate <qualified-ref>] [--limit <1..5>]\n             Print function intent provenance JSON (read-only).\n  intent     bundle --task <tasks.md> --symbol <name> [--candidate <qualified-ref>]...\n             Create or reuse a task intent bundle JSON (read/write cache).\n  intent     bundle --task <tasks.md> --no-symbols\n             Same, with an empty function list for tasks without function symbols.\n  intent     sections --task <tasks.md> --role <implementer|reviewer|debugger>\n             Print role-specific intent section bodies JSON (read-only).\n',
+    'ontology': '  ontology   entity --entity <token> [--repo <dir>] [--limit <1..100>]\n             file --file <path> [--repo <dir>] [--limit <1..100>]\n             impact --file <path> [--repo <dir>] [--limit <1..100>]\n             Search canonical Bouncer context in memory (read-only JSON).\n',
+    'graphify-bin': '  graphify-bin\n             Print the resolved graphify executable path (one line).\n',
+    'project-root': "  project-root\n             Print the consuming project's main worktree absolute path (one line).\n",
+    'subagent-model': "  subagent-model --agent <name> [--provider <name>]\n             Print the named agent's model slug, or inherit (one line).\n",
+    'codex-agents': '  codex-agents check --agent <name>\n             Compare local Codex TOML to generated bytes (read-only JSON).\n',
+    'current': '  current    [--set <blueprint dir> [--base <branch>] [--task <NNN|TASKS-NNN>] [--replace] [--keep-others] [--reapprove]]\n             [--clear]\n             Show the active blueprint pointer, or set / clear it.\n             --task picks a task doc; without it, first ready/in_progress wins.\n             --replace deletes the uniquely selected key then writes the target; omitted, --set adds a parallel key.\n             --replace at a multi-pointer base exits 1 with CURRENT_AMBIGUOUS.\n             At a base checkout, a second key is refused unless --replace or --keep-others is given.\n             --reapprove rewrites the approval snapshot after the user explicitly approves a scope change.\n',
+    'migrate': '  migrate    task-layout [--dry-run]\n             Move legacy task files into tasks/<NNN>/ units.\n  migrate    context-slugs [--yes]\n             Move numbered epic and blueprint directories to slugs, rewrite ids and hashes, record\n             aliases (dry-run plan unless --yes; refuses a dirty tree or in-progress runs).\n  migrate    merge-legacy-epics [--yes]\n             Move legacy epic blueprints into domain epics, rewrite ids and hashes, record moved_to\n             (dry-run plan unless --yes; refuses a dirty tree or in-progress runs).\n  migrate    review-scope --blueprint <dir>\n             Set review_scope: blueprint and create the root pending review.md (idempotent).\n  migrate    retention\n             Audit closed blueprints for retention (dry-run, JSON, no writes).\n  migrate    retention --apply --blueprint <dir>\n             Promote Explain then delete transients for one eligible closed blueprint.\n',
+    'import': '  import     [--source merges|commits] [--since <ref>] [--limit <n>]\n             [--epic-id <ddd>] [--epic-name <slug>] [--yes --message <msg>]\n             Transcribe git history into imported epic/blueprint documents.\n',
+    'review-dispatch': '  review-dispatch plan --blueprint <dir> [--previous <file>]\n             Classify plan context-review strategy (read-only JSON).\n',
+    'review': "  review-dispatch execute --blueprint <dir> [--task <ddd>] --base <sha> --head <sha> [--mode discovery|delta]\n             Classify execute review strategy from the frozen final worktree state\n             (JSON). Writes only the snapshot artifact under .bouncer/runtime/\n             review-snapshots/ and returns target.snapshot_id/snapshot_path; --head\n             must be the current HEAD. On failure it prints reason/cause/next, exit 1.\n             When that blueprint's scale is light, returns single/combined\n             regardless of diff size.\n  review record --blueprint <dir> [--task <ddd>] --round <json-file> [--status <requested|addressed|accepted>]\n             Record one review round and finding updates (JSON).\n  review accept-risk --blueprint <dir> --finding <id> --note <text> --yes\n             Close one open blueprint final-review finding as a user-accepted risk.\n",
+    'context-review': '  context-review <start|record|close|restart|route> --blueprint <dir>\n             Track plan context-review cycles; limit full restarts to one.\n',
+    'dispatch': '  dispatch print --role <implementer|reviewer|debugger|context-reviewer|coordinator> --cwd <dir> --input <file> --out <dir>\n             Run one Cursor print dispatch (JSON).\n',
+    'config': '  config --help\n             Show .bouncer/config.json "subagents" keys, allowed values, and defaults (read-only).\n',
+    'retro': '  retro sources [--repo <dir>] [--limit <1..200>] [--claude-root <dir>]\n             [--codex-root <dir>] [--cursor-root <dir>]\n             List Claude Code, Codex, and Cursor transcript candidates for this project (read-only JSON).\n  retro read --path <file> [--max-chars <n>]\n             Normalize one transcript into role/text messages with a character cap (read-only JSON).\n',
+    'epic': '  epic       add-domain --slug <s> --reason <text> --yes\n             add-area --name <a> --yes\n             Record a user-approved domain epic or area in .bouncer/epics.json.\n',
+    'metrics': '  metrics start --kind <coordinator-session|context-review|root-direct-session> --blueprint <dir> [--label <text>]\n             [--target-digest <64hex>]\n             Record a coordinator, root-direct, or plan context-review session start in drive-metrics.json.\n  metrics end --id <m-id> [--tokens <n>] [--input-tokens <n>] [--output-tokens <n>]\n             [--cache-read-tokens <n>] [--cache-write-tokens <n>] [--model <slug>] [--host-duration-ms <n>]\n             Record host-reported tokens and time; missing values are stored as null with a reason.\n  metrics summary --blueprint <dir>\n             Sum sessions per kind (null tokens and costs are counted as missing, never as 0).\n             worker_tokens_source says whether worker totals came from the ledger, a saved snapshot, or are unavailable.\n  metrics snapshot --blueprint <dir>\n             Save worker token totals and the ledger SHA-256 to the Git common dir before cleanup removes the ledger.\n\nEvery command accepts --repo <dir> to run against another repository.\n',
+});
+const COORDINATE_USAGE = Object.freeze({
+    'bootstrap': 'usage: bouncer coordinate bootstrap\n  --blueprint <dir> [--repo <dir>] [--promote-light]\n  Seed the integration worktree and ledger. Not ledger-fenced.\n  --promote-light archives a promotion_stopped light ledger and starts a full ledger.\n',
+    'prepare': 'usage: bouncer coordinate prepare\n  --blueprint <dir> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Create or reuse assigned worker worktrees and refresh leases.\n',
+    'ready': 'usage: bouncer coordinate ready\n  --blueprint <dir> [--repo <dir>]\n  Alias of coordinate status. Prints the checkpoint; not ledger-fenced.\n',
+    'dispatch': 'usage: bouncer coordinate dispatch\n  --blueprint <dir> --task <ddd> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--repo <main>] [--lease-id <id>] [--generation <n>] [--model <value>]\n  Open one dispatch attempt on the assigned worker and return brief/HEAD metadata.\n  --model records the dispatch model argument (`bouncer subagent-model` output) on the ledger.\n',
+    'report': 'usage: bouncer coordinate report\n  --blueprint <dir> --task <ddd> --attempt <n> --task-brief-hash <sha256>\n  --outcome <accepted|rework|scope_revision|task_change|blocked> --summary <text>\n  --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <main>] [--lease-id <id>] [--generation <n>]\n  Record a worker report against the active attempt, or append stale-report evidence.\n',
+    'record': 'usage: bouncer coordinate record\n  --blueprint <dir> --task <ddd> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--sha <sha>] [--repo <dir>] [--lease-id <id>] [--generation <n>]\n  Record the worker HEAD after an accepted report.\n',
+    'rerecord': 'usage: bouncer coordinate rerecord\n  --blueprint <dir> --task <ddd> --reason <text> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--sha <sha>] [--repo <dir>]\n  Replace a recorded worker SHA with its direct-child HEAD and preserve the decision.\n',
+    'integrate': 'usage: bouncer coordinate integrate\n  --blueprint <dir> [--task <ddd>] --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--sha <sha>] [--repo <dir>] [--lease-id <id>] [--generation <n>]\n  Fan-in recorded commit tasks via a candidate worktree (omit --task for the wave).\n',
+    'status': 'usage: bouncer coordinate status\n  --blueprint <dir> [--repo <dir>] [--write-input <file>]\n  Print the checkpoint (including checkpoint.ledger). Not ledger-fenced.\n  --write-input writes the coordinator print-dispatch input text to <file>\n  (status only; reports input_file) for `dispatch print --role coordinator --input`.\n',
+    'revoke': 'usage: bouncer coordinate revoke\n  --blueprint <dir> --task <ddd> --reason <text> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Revoke an active lease, clear dispatch/sha, and return the task to pending.\n',
+    'advance': "usage: bouncer coordinate advance\n  --blueprint <dir> [--task <ddd>] [--max-steps <n>] [--repo <dir>]\n  Not ledger-fenced. Calls coordinate next and runs argv for prepare, integrate,\n  verification_node, verify, and commit until a stop or failure.\n  Stop reasons (ok: true): judge, worker, blocked, done, none, max-steps, yield\n  Failure reasons (ok: false): repeated-failure, unclear-result, advance-argv-invalid,\n  or the automatic action's failure reason.\n  Response fields: executed, stop.next (success) or reason, cause, next, executed (failure)\n",
+    'critical-recovery': 'usage: bouncer coordinate critical-recovery\n  --blueprint <dir> --task <ddd> --findings <id> [--findings <id>]... --reason <text>\n  --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Record the one permitted blocker or major recovery for a prepared task.\n  --blueprint <dir> --task <ddd> --outcome <resolved|blocked> --reason <text>\n  --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Record the outcome without permitting another recovery.\n',
+    'next': 'usage: bouncer coordinate next\n  --blueprint <dir> [--task <ddd>] [--repo <dir>]\n  Read-only. Ignores --ledger-path and --ledger-hash if given (not ledger-fenced).\n  Blueprint actions: prepare, yield, drive_tasks, integrate, verification_node, supplement, final_review, done, blocked\n  Task actions: dispatch, implement, verify, review, commit, report, record, revise, none, blocked\n  Response fields: action, cwd, argv, judge, task_ids, payload, card, checkpoint\n  card {id,body} only on: dispatch, implement, verify, review, report, revise, record, supplement, final_review, blocked\n',
+    'reverify': 'usage: bouncer coordinate reverify\n  --blueprint <dir> --task <terminal ddd> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Re-run the terminal verification after an environment-only fix. Uses no repair wave;\n  refused with reverify-source-moved or reverify-worktree-dirty when the source changed.\n',
+    'partial-close': 'usage: bouncer coordinate partial-close\n  --blueprint <dir> --user-confirmed --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Preserve the failed drive and mark it partial_closed after two repair waves.\n',
+    'promote-stop': "usage: bouncer coordinate promote-stop\n  --blueprint <dir> --reason <security-risk|out-of-scope|task-split|interface-semantics|reviewer-wider-scope>\n  --summary <text> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Record promotion_stopped on a light ledger with the open task's diff and evidence ids.\n  Same reason+summary is idempotent; other mutations then fail with promotion-stopped.\n",
+    'repair': 'usage: bouncer coordinate repair\n  --blueprint <dir> --task <ddd> --failure-command <cmd> --summary <text>\n  --paths <p> --decision <reason> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Add one audited repair task and move the terminal CI dependency.\n  --blueprint <dir> [--task <ddd>] --review-finding <id> [--review-finding <id>]...\n  --summary <text> --paths <p> --decision <reason> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Open a repair task from final-review must_fix findings (omit --task\n  when the blueprint has no terminal verification).\n  --kind <product|supplement> (default product, the forms above)\n  --blueprint <dir> --kind supplement --review-finding <id> [--review-finding <id>]...\n  --summary <text> --paths <test-path> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Accept an in-scope test-evidence gap in place: no new task, no repair wave.\n  --blueprint <dir> --kind supplement --done --summary <text> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Verify the finished supplement; the next final review is the one delta round.\n  Product-behavior fixes, new dependencies, and public interfaces are not supplements.\n',
+    'revise': 'usage: bouncer coordinate revise\n  --blueprint <dir> --task <ddd> --paths <p> [--paths <p>]... [--release-do-not-touch <p>]... --reason <text>\n  --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  Record one scope decision in the task document and ledger.\n  --paths replaces the whole scope with exactly the given set; pass every path\n  the task still needs, not only new ones (dropped paths are reported as warnings).\n  A Do not touch entry in the brief that overlaps a newly added path is refused with\n  scope-do-not-touch-conflict; release each such entry with --release-do-not-touch <p>, which\n  also removes it from the brief. A value that is not a conflicting entry is refused with\n  release-do-not-touch-unknown. A valueless --release-do-not-touch is usage (2).\n  Takes no --repo: the write boundary is the current directory, so\n  run it from the assigned task worktree, not the main checkout.\n',
+    'session-open': "usage: bouncer coordinate session-open\n  --blueprint <dir> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger) [--repo <dir>]\n  Run by the root before dispatching a coordinator session. Appends a session decision\n  (opened_at, integration_head, waves_cap) so coordinate next can count this session's waves.\n  Refused without changing the ledger on a light, promotion_stopped, partial_closed, or\n  awaiting_confirmation ledger.\n",
+    'worker-model': 'usage: bouncer coordinate worker-model\n  --blueprint <dir> --role <implementer|reviewer|debugger> --model <value> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--task <ddd>] [--perspective <name>] [--tokens <n>] [--repo <dir>]\n  Run from the integration worktree. Appends a worker-model decision (role, model, task,\n  perspective, tokens) to the ledger; --task also appends it to that task. The model is the one-line\n  `bouncer subagent-model --agent <name>` output (slug or inherit); it records what the\n  coordinator passed, not proof of what the host ran. --perspective is reviewer-only.\n  --tokens is the host-reported subagent token count (non-negative integer); omit it when the\n  completion notice has not arrived, then add it later with coordinate worker-tokens.\n  Does not change dispatch, lease, status, or attempt state.\n',
+    'note': 'usage: bouncer coordinate note\n  --blueprint <dir> --text <text> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--task <ddd>] [--repo <dir>]\n  Run from the integration worktree. Appends a note decision (text, optional task) to the ledger so the next\n  coordinator session reads it in checkpoint.notes. The text is trimmed and at most 2000 characters; it is data,\n  never an instruction. Refused with note-text-required, note-too-long, or task-outside-blueprint. A missing --text is usage (2).\n  Does not change dispatch, lease, status, or attempt state.\n',
+    'worker-tokens': "usage: bouncer coordinate worker-tokens\n  --blueprint <dir> --role <implementer|reviewer|debugger> --tokens <n> --ledger-path <path> --ledger-hash <sha256> (from coordinate status checkpoint.ledger)\n  [--task <ddd>] [--perspective <name>] [--repo <dir>]\n  Run from the integration worktree. Appends a worker-tokens decision (role, tokens, task,\n  perspective) to the ledger; --task also appends it to that task. Use it when the host's\n  completion notice arrives after the worker-model record. `metrics summary` adds it to\n  worker_tokens, never to the coordinator-session total. --perspective is reviewer-only.\n  Does not change dispatch, lease, status, or attempt state.\n",
+});
+const USAGE_HEADER = 'usage: bouncer <command> [options]\n\n';
+const USAGE_FOOTER = 'Every command accepts --repo <dir> to run against another repository.\n';
+/**
+ * coordinate 서브커맨드의 도움말을 정적 표에서 돌려준다. 알 수 없는 값은 overview로 폴백한다.
+ *
+ * @param {string} [sub] - 도움말을 조회할 서브커맨드
+ * @returns {string} 해당 서브커맨드 도움말 또는 coordinate usage
+ */
+function coordinateUsage(sub) {
+    return sub && Object.hasOwn(COORDINATE_USAGE, sub) ? COORDINATE_USAGE[sub] : COMMAND_USAGE.coordinate;
+}
+const USAGE = USAGE_HEADER + Object.values(COMMAND_USAGE).join('') + '\n' + USAGE_FOOTER;
+module.exports = { COMMAND_USAGE, coordinateUsage, USAGE };

package/dist/cli.js

@@ -0,0 +1,70 @@
+'use strict';
+/* eslint-disable max-len -- Lazy handler registrations keep imports deferred until command selection. */
+const cliFlags = require("./cli-flags");
+const cliUsage = require("./cli-usage");
+const { parseFlags, argvRequestsHelp } = cliFlags;
+const { COMMAND_USAGE, USAGE } = cliUsage;
+// help에서 핸들러 모듈을 읽지 않도록, 레지스트리는 선택 뒤에 실행할 로더만 보유한다.
+const COMMANDS = {
+    validate: { usage: COMMAND_USAGE.validate, load: () => require('./cli-doc-commands').validate.run },
+    verify: { usage: COMMAND_USAGE.verify, load: () => require('./cli-doc-commands').verify.run },
+    scaffold: { usage: COMMAND_USAGE.scaffold, load: () => require('./cli-doc-commands').scaffold.run },
+    commit: { usage: COMMAND_USAGE.commit, load: () => require('./cli-git-commands').commit.run },
+    'commit-guard': { usage: COMMAND_USAGE['commit-guard'], load: () => require('./cli-commit-guard-command').run },
+    finalize: { usage: COMMAND_USAGE.finalize, load: () => require('./cli-git-commands').finalize.run },
+    'seed-worktree': { usage: COMMAND_USAGE['seed-worktree'], load: () => require('./cli-git-commands')['seed-worktree'].run },
+    execute: { usage: COMMAND_USAGE.execute, load: () => require('./cli-git-commands').execute.run },
+    plan: { usage: COMMAND_USAGE.plan, load: () => require('./cli-doc-commands').plan.run },
+    run: { usage: COMMAND_USAGE.run, load: () => require('./cli-project-commands').run.run },
+    coordinate: { usage: COMMAND_USAGE.coordinate, ownHelp: true, load: () => require('./cli-git-commands').coordinate.run },
+    init: { usage: COMMAND_USAGE.init, load: () => require('./cli-project-commands').init.run },
+    'graph-sync': { usage: COMMAND_USAGE['graph-sync'], load: () => require('./cli-project-commands')['graph-sync'].run },
+    intent: { usage: COMMAND_USAGE.intent, load: () => require('./cli-project-commands').intent.run },
+    'graphify-bin': { usage: COMMAND_USAGE['graphify-bin'], load: () => require('./cli-project-commands')['graphify-bin'].run },
+    'project-root': { usage: COMMAND_USAGE['project-root'], load: () => require('./cli-project-commands')['project-root'].run },
+    'subagent-model': { usage: COMMAND_USAGE['subagent-model'], load: () => require('./cli-project-commands')['subagent-model'].run },
+    'codex-agents': { usage: COMMAND_USAGE['codex-agents'], load: () => require('./cli-project-commands')['codex-agents'].run },
+    current: { usage: COMMAND_USAGE.current, load: () => require('./cli-current-command').current.run },
+    migrate: { usage: COMMAND_USAGE.migrate, load: () => require('./cli-project-commands').migrate.run },
+    import: { usage: COMMAND_USAGE.import, load: () => require('./cli-git-commands').import.run },
+    'review-dispatch': { usage: COMMAND_USAGE['review-dispatch'], ownHelp: true, load: () => require('./cli-review-dispatch-command').run },
+    review: { usage: COMMAND_USAGE.review, ownHelp: true, load: () => require('./cli-review-command').run },
+    'context-review': { usage: COMMAND_USAGE['context-review'], ownHelp: true, load: () => require('./cli-context-review-command').run },
+    dispatch: { usage: COMMAND_USAGE.dispatch, ownHelp: true, load: () => require('./cli-dispatch-command').run },
+    config: { usage: COMMAND_USAGE.config, ownHelp: true, load: () => require('./cli-config-command').run },
+    retro: { usage: COMMAND_USAGE.retro, load: () => require('./cli-retro-command').run },
+    metrics: { usage: COMMAND_USAGE.metrics, load: () => require('./cli-metrics-command').run },
+    epic: { usage: COMMAND_USAGE.epic, ownHelp: true, load: () => require('./cli-epic-command').run },
+    ontology: { usage: COMMAND_USAGE.ontology, load: () => require('./cli-project-commands').ontology.run },
+};
+/**
+ * CLI argv를 처리하고 선택한 명령의 handler만 적재한다.
+ * help와 unknown 경로는 static usage만 출력하며, 주입된 IO가 있으면 프로세스 스트림을 쓰지 않는다.
+ *
+ * @param {string[]} argv - bouncer 명령과 인자
+ * @param {Partial<CliIo> | null} [io] - 선택적 stdout/stderr 싱크
+ * @returns {number} handler 또는 help/unknown 경로의 종료 코드
+ */
+function runCli(argv, io) {
+    const out = io && io.out ? io.out : (s) => process.stdout.write(s);
+    const err = io && io.err ? io.err : (s) => process.stderr.write(s);
+    const sink = { out, err };
+    const [cmd, ...rest] = argv;
+    if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        out(USAGE);
+        return 0;
+    }
+    const entry = Object.hasOwn(COMMANDS, cmd) ? COMMANDS[cmd] : undefined;
+    if (!entry) {
+        err(`unknown command: ${cmd}\n\n${USAGE}`);
+        return 2;
+    }
+    // handler를 적재하기 전에 help를 끝내 `<cmd> --help`가 명령을 실행하거나 저장소를 바꾸지 못하게 한다.
+    // ownHelp 명령은 하위 명령별 usage를 내야 하므로 handler가 판정한다.
+    if (!entry.ownHelp && argvRequestsHelp(rest)) {
+        out(COMMAND_USAGE[cmd]);
+        return 0;
+    }
+    return entry.load()(rest, sink);
+}
+module.exports = { runCli, parseFlags };