@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/sync-claude-md.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// CLAUDE.md / .claude/CLAUDE.md 의 HARNESS:START~HARNESS:END 영역을
+// agent.yaml + package.json + manifests 에서 다시 생성해 갈아낀다.
+// 사용자 작성 영역(마커 바깥)은 그대로 보존한다.
+// 멱등(idempotent). 마커가 없으면 "## 자동 갱신 영역" 헤딩 다음에 삽입한다.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const TARGETS = [
+  path.join(ROOT, 'CLAUDE.md'),
+  path.join(ROOT, '.claude', 'CLAUDE.md'),
+];
+
+const START_RE = /<!--\s*HARNESS:START(?:\s+version=\S+)?\s*-->/;
+const END_RE = /<!--\s*HARNESS:END\s*-->/;
+const AUTO_HEADING_RE = /^##\s*자동 갱신 영역\s*$/m;
+
+function parseArgs(argv) {
+  const args = { check: false, dryRun: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') args.check = true;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--verbose' || a === '-v') args.verbose = true;
+    else if (a === '--help' || a === '-h') { printHelp(); process.exit(0); }
+    else { console.error(`알 수 없는 인자: ${a}`); process.exit(2); }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+HARNESS sync-claude-md
+
+사용법:
+  node scripts/sync-claude-md.js [--check] [--dry-run] [--verbose]
+
+옵션:
+  --check    변경이 필요한지만 검사 (CI 용). 변경 필요하면 exit 1.
+  --dry-run  렌더링 결과만 stdout 으로 출력하고 파일은 건드리지 않음.
+  --verbose  대상 파일별 상세 로그.
+`);
+}
+
+function readJson(rel) { return JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8')); }
+function readYaml(rel) { return YAML.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8')); }
+
+function buildAutoSection() {
+  const manifest = readYaml('agent.yaml');
+  const pkg = readJson('package.json');
+  const profilesDoc = readJson('manifests/install-profiles.json');
+
+  const agentNames = manifest.agents || [];
+  const skillNames = manifest.skills || [];
+  const commandNames = manifest.commands || [];
+  const hookList = manifest.hooks?.active || [];
+  const profileNames = Object.keys(profilesDoc.profiles || {});
+  const harnessNames = (manifest.harnesses || []).map(h => h.name);
+
+  // agents/<name>.md frontmatter 에서 provider/model/sandbox 추출
+  const rows = [];
+  for (const a of agentNames) {
+    const file = path.join(ROOT, 'agents', `${a}.md`);
+    if (!fs.existsSync(file)) {
+      rows.push({ name: a, provider: '?', model: '?', sandbox: '?' });
+      continue;
+    }
+    const content = fs.readFileSync(file, 'utf8');
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    const fm = fmMatch ? YAML.parse(fmMatch[1]) : {};
+    rows.push({
+      name: a,
+      provider: fm.provider || '?',
+      model: fm.model || '?',
+      sandbox: fm.sandbox || (Array.isArray(fm.disallowedTools) && fm.disallowedTools.length ? 'read-only' : 'full'),
+    });
+  }
+
+  const lines = [];
+  lines.push(`<!-- HARNESS:START version=${pkg.version} -->`);
+  lines.push('<!-- 이 영역은 scripts/sync-claude-md.js 가 자동 갱신한다. 직접 편집 금지. -->');
+  lines.push('');
+  lines.push('## 카탈로그 요약');
+  lines.push('');
+  lines.push(`- agents: ${agentNames.length}`);
+  lines.push(`- skills: ${skillNames.length}`);
+  lines.push(`- commands: ${commandNames.length}${commandNames.length ? ' (legacy compat)' : ''}`);
+  lines.push(`- hooks: ${hookList.length}${hookList.length ? ' (' + hookList.join(', ') + ')' : ''}`);
+  lines.push(`- profiles: ${profileNames.join(', ')}`);
+  lines.push(`- harnesses: ${harnessNames.join(', ')}`);
+  lines.push('');
+
+  lines.push('## 에이전트 → 모델 매트릭스');
+  lines.push('');
+  lines.push('| Agent | Provider | Model | Sandbox |');
+  lines.push('|---|---|---|---|');
+  for (const r of rows) {
+    lines.push(`| ${r.name} | ${r.provider} | ${r.model} | ${r.sandbox} |`);
+  }
+  lines.push('');
+
+  lines.push('## 핵심 명령어');
+  lines.push('');
+  lines.push('```bash');
+  lines.push('harness install --plan --profile core      # 설치 dry-run');
+  lines.push('harness ask "<task>"                       # question gate, no project mutation');
+  lines.push('harness team "<task>"                      # read-only worker handoffs');
+  lines.push('harness work "<task>"                      # single executor implement handoff');
+  lines.push('harness verify "<task>" --session <id>     # Codex-only verification');
+  lines.push('harness gate status --session <id>         # inspect or resolve HUMAN_GATE state');
+  lines.push('harness ship "<task>" --session <id>       # ship/no-ship readiness handoff');
+  lines.push('harness apply --session <id>               # apply verified SHIP_READY live-work diff');
+  lines.push('harness run "<task>" --session <id>        # work -> verify -> ship, optional --apply');
+  lines.push('harness review "<task>" [--secure|--fast|--no-ship]  # legacy full cycle');
+  lines.push('harness review-cycle "<task>" [--secure|--fast|--no-ship]  # explicit legacy alias');
+  lines.push('harness plan "<task>"');
+  lines.push('harness self-review');
+  lines.push('harness codex-review                       # 단계 5 단독');
+  lines.push('harness sessions');
+  lines.push('harness costs --since=7d');
+  lines.push('```');
+  lines.push('');
+
+  lines.push('## State 경로');
+  lines.push('');
+  const st = manifest.state || {};
+  lines.push(`- 세션: \`${st.session_dir || '.harness/state/sessions'}/<id>/{prd.json,progress.txt,notepad.md,handoffs/}\``);
+  lines.push(`- 프로젝트: \`${st.project_memory || '.harness/project-memory.json'}\` + \`WORKING-CONTEXT.md\``);
+  lines.push(`- 글로벌: \`${st.global_instincts || '~/.harness/instincts'}/\` + \`${st.costs || '.harness/costs.jsonl'}\``);
+  lines.push('');
+
+  lines.push('## 매직 키워드 → 스킬 (명시 옵트인만)');
+  lines.push('');
+  lines.push('자동 활성 키워드 감지는 **사용**하지 않는다. 사용자 룰("확인 후 실행") 우선. 모든 스킬은 슬래시 명령(`/claude-led-codex-review`) 또는 CLI(`harness review`) 로 명시 호출.');
+  lines.push('');
+
+  lines.push('## 핸드오프 5필드');
+  lines.push('');
+  lines.push('Decided / Rejected / Risks / Files / Remaining — 10~20줄.');
+  lines.push('');
+  lines.push('<!-- HARNESS:END -->');
+
+  return lines.join('\n') + '\n';
+}
+
+function applyToContent(content, autoSection) {
+  const sIdx = content.search(START_RE);
+  const eIdx = content.search(END_RE);
+
+  if (sIdx !== -1 && eIdx !== -1 && sIdx < eIdx) {
+    // 두 마커 사이를 통째로 교체. 끝 마커 라인 끝까지 포함.
+    const endLineEnd = content.indexOf('\n', eIdx);
+    const tail = endLineEnd === -1 ? '' : content.slice(endLineEnd + 1);
+    return content.slice(0, sIdx) + autoSection + (tail.length ? tail : '');
+  }
+
+  // 마커 없음 → "## 자동 갱신 영역" 다음 줄부터 EOF 까지 자동 컨텐츠로 본다.
+  // 그 영역을 통째로 새 마커 블록으로 갈아낀다 (사용자 작성 영역은 헤딩 위쪽이므로 보존).
+  const headingMatch = AUTO_HEADING_RE.exec(content);
+  if (headingMatch) {
+    const headingEnd = content.indexOf('\n', headingMatch.index);
+    const before = content.slice(0, headingEnd + 1);
+    return before + '\n' + autoSection;
+  }
+
+  // 헤딩도 없으면 파일 끝에 추가
+  return content.replace(/\s*$/, '\n\n## 자동 갱신 영역\n\n') + autoSection;
+}
+
+function processFile(file, autoSection, args) {
+  if (!fs.existsSync(file)) {
+    if (args.verbose) console.log(`[SKIP] ${path.relative(ROOT, file)} 없음`);
+    return { changed: false, skipped: true };
+  }
+  const before = fs.readFileSync(file, 'utf8');
+  const after = applyToContent(before, autoSection);
+  const changed = before !== after;
+  if (args.verbose || changed) {
+    console.log(`[${changed ? 'DIFF' : ' OK '}] ${path.relative(ROOT, file)}`);
+  }
+  if (changed && !args.dryRun && !args.check) {
+    fs.writeFileSync(file, after);
+  }
+  return { changed, skipped: false };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const autoSection = buildAutoSection();
+
+  if (args.dryRun) {
+    process.stdout.write(autoSection);
+    return;
+  }
+
+  let anyChanged = false;
+  for (const f of TARGETS) {
+    const r = processFile(f, autoSection, args);
+    if (r.changed) anyChanged = true;
+  }
+
+  if (args.check) {
+    if (anyChanged) {
+      console.error('CLAUDE.md 자동 영역이 카탈로그와 어긋남. `node scripts/sync-claude-md.js` 실행 필요.');
+      process.exit(1);
+    }
+    console.log('CLAUDE.md 자동 영역 동기화 OK.');
+    return;
+  }
+
+  console.log(anyChanged ? '동기화 완료.' : '변경 없음.');
+}
+
+main();

package/scripts/verify/claude-live.js

@@ -0,0 +1,30 @@
+// Claude Code CLI live smoke.
+// Uses the local Claude subscription/OAuth session by default, not ANTHROPIC_API_KEY.
+
+import { runClaude } from '../agents/runners/claude.js';
+
+const result = await runClaude({
+  agent: 'claude-live-smoke',
+  stage: 'plan',
+  task: 'Return a minimal HARNESS handoff JSON for a local Claude Code CLI smoke test.',
+  model: process.env.HARNESS_CLAUDE_SMOKE_MODEL || 'sonnet',
+  sandbox: 'read-only',
+  disallowedTools: [],
+  promptBody: [
+    'Return only one JSON object.',
+    'Required shape:',
+    '{"decided":"...","rejected":"","risks":"","files":["SMOKE.md"],"remaining":"","issues":[],"verdict":"approve","confidence":0.9}',
+  ].join('\n'),
+  context: {},
+});
+
+const ok = result?.verdict === 'approve'
+  && Array.isArray(result.files)
+  && result.files.includes('SMOKE.md');
+
+if (!ok) {
+  console.error(JSON.stringify(result, null, 2));
+  throw new Error('Claude live smoke returned an unexpected handoff');
+}
+
+console.log(`Claude CLI live smoke PASS: verdict=${result.verdict}, files=${result.files.join(', ')}`);

package/scripts/verify/codex-live.js

@@ -0,0 +1,60 @@
+// codex runner 단독 live 검증 (P2-c).
+//
+// 환경: codex CLI (≥0.124) + ChatGPT 로그인 세션.
+// OPENAI_API_KEY 는 기본 차단되며, 종량제 opt-in 때만 HARNESS_AUTH_ALLOW_ENV_OVERRIDE=1 과 함께 사용.
+// 비용: 1회 호출 약 ~15K 토큰 (ChatGPT 구독 시 무과금).
+//
+// 사용:
+//   node scripts/verify/codex-live.js
+//
+// 옵트인 env:
+//   HARNESS_CODEX_PROFILE_REVIEW   ~/.codex/config.toml 의 review 프로파일 명
+//   HARNESS_CODEX_PROFILE          공통 프로파일 (위가 없을 때 fallback)
+//   HARNESS_CODEX_TIMEOUT_S        codex 호출 timeout (디폴트 180)
+//
+// 종료 코드: 0 = PASS, 1 = FAIL.
+// codex CLI 메이저 업데이트 시 본 스크립트로 회귀 감지 권장.
+
+import { runCodex } from '../agents/runners/codex.js';
+
+const args = {
+  stage: 'codex-review',
+  context: {
+    diff: "+ console.log('password:', password);\n+ const token = req.headers.authorization;\n+ db.query(`SELECT * FROM users WHERE id = ${userId}`);",
+    priorHandoffs: [
+      {
+        stage: 'self-review',
+        decided: 'approve',
+        files: ['auth/login.js'],
+        verdict: 'approve'
+      }
+    ],
+    prd: {
+      goal: 'login 디버그 로그 추가',
+      acceptanceCriteria: [
+        { id: 'ac-1', text: '로그인 실패 사유 식별 가능', passes: true }
+      ]
+    }
+  }
+};
+
+try {
+  const start = Date.now();
+  const result = await runCodex(args);
+  const ms = Date.now() - start;
+
+  const issues = result.issues || [];
+  const verdict = result.verdict;
+  const validVerdicts = ['approve', 'approve_with_fixes', 'block'];
+  if (!validVerdicts.includes(verdict)) {
+    throw new Error(`unexpected verdict: ${verdict} (expected one of: ${validVerdicts.join(', ')})`);
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+  console.log(`\n[PASS] verdict=${verdict} issues=${issues.length} duration_ms=${ms}`);
+  process.exit(0);
+} catch (e) {
+  console.error(`[FAIL] ${e.message}`);
+  if (e.stack) console.error(e.stack);
+  process.exit(1);
+}

package/scripts/verify/gemini-live.js

@@ -0,0 +1,48 @@
+// Gemini CLI live smoke.
+// Uses the local Gemini/gcloud session by default, not GEMINI_API_KEY.
+
+import { runGemini } from '../agents/runners/gemini.js';
+
+const started = Date.now();
+let result;
+try {
+  result = await runGemini({
+    agent: 'gemini-live-smoke',
+    stage: 'ideate',
+    task: [
+      'Return a minimal HARNESS handoff JSON for a local Gemini CLI smoke test.',
+      'Do not browse, do not call tools, and do not modify files.',
+    ].join(' '),
+    model: process.env.HARNESS_GEMINI_SMOKE_MODEL || 'gemini-2.5-flash',
+    sandbox: 'read-only',
+    disallowedTools: ['Write', 'Edit', 'Bash'],
+    promptBody: [
+      'Return only one JSON object.',
+      'Required shape:',
+      '{"decided":"Gemini CLI smoke passed","rejected":"","risks":"","files":["GEMINI_SMOKE.md"],"remaining":"","issues":[],"verdict":"approve","confidence":0.9}',
+    ].join('\n'),
+    context: {},
+  });
+} catch (e) {
+  const msg = String(e?.message || e);
+  if (/Auth method|GEMINI_API_KEY|GOOGLE_GENAI_USE/i.test(msg)) {
+    console.error([
+      'Gemini CLI is installed, but headless auth is not configured.',
+      'Run interactive `gemini` once and choose Login with Google, or configure Vertex/ADC auth for headless mode.',
+      'HARNESS still blocks GEMINI_API_KEY/GOOGLE_API_KEY by default; use delegated Google/Gemini auth unless you explicitly opt into API-key billing.',
+    ].join('\n'));
+    process.exit(2);
+  }
+  throw e;
+}
+
+const ok = result?.verdict === 'approve'
+  && Array.isArray(result.files)
+  && result.files.includes('GEMINI_SMOKE.md');
+
+if (!ok) {
+  console.error(JSON.stringify(result, null, 2));
+  throw new Error('Gemini live smoke returned an unexpected handoff');
+}
+
+console.log(`Gemini CLI live smoke PASS: verdict=${result.verdict}, files=${result.files.join(', ')}, duration_ms=${Date.now() - started}`);

package/scripts/verify/runtime.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Rust runtime verification smoke: cargo build/test/clippy plus CLI IPC checks.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveCli } from '../core/cli-resolver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..', '..');
+const runtimeDir = path.join(root, 'runtime');
+
+const cargo = resolveCargo();
+const runtimeBin = path.join(
+  runtimeDir,
+  'target',
+  'release',
+  process.platform === 'win32' ? 'harness-runtime.exe' : 'harness-runtime',
+);
+
+console.log(`cargo: ${cargo}`);
+
+run(cargo, ['build', '--release'], { cwd: runtimeDir, inherit: true });
+run(cargo, ['test'], { cwd: runtimeDir, inherit: true });
+run(cargo, ['clippy', '--all-targets', '--', '-D', 'warnings'], { cwd: runtimeDir, inherit: true });
+
+if (!fs.existsSync(runtimeBin)) {
+  throw new Error(`runtime binary not found after build: ${runtimeBin}`);
+}
+
+const smokeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-runtime-smoke-'));
+try {
+  run(runtimeBin, ['--help'], { cwd: root, inherit: true });
+  run(runtimeBin, ['--root', smokeRoot, 'init'], { cwd: root, inherit: true });
+  run(runtimeBin, ['--root', smokeRoot, 'status'], { cwd: root, inherit: true });
+
+  const ping = run(runtimeBin, ['--root', smokeRoot, 'ipc'], {
+    cwd: root,
+    input: '{"id":1,"method":"ping"}\n',
+  });
+  const response = JSON.parse(ping.trim());
+  if (response?.id !== 1 || response?.result?.pong !== true || response.error) {
+    throw new Error(`unexpected IPC ping response: ${ping}`);
+  }
+  console.log(`ipc ping: ${ping.trim()}`);
+} finally {
+  fs.rmSync(smokeRoot, { recursive: true, force: true });
+}
+
+console.log('Runtime verification PASS');
+
+function resolveCargo() {
+  if (process.env.HARNESS_CARGO) return process.env.HARNESS_CARGO;
+
+  const onPath = resolveCli('cargo');
+  if (onPath) return onPath;
+
+  const exe = process.platform === 'win32' ? 'cargo.exe' : 'cargo';
+  const candidates = [
+    path.join(os.homedir(), '.cargo', 'bin', exe),
+  ];
+
+  if (process.platform === 'win32') {
+    candidates.push(
+      path.join(os.homedir(), '.rustup', 'toolchains', 'stable-x86_64-pc-windows-msvc', 'bin', exe),
+    );
+  }
+
+  const found = candidates.find((candidate) => fs.existsSync(candidate));
+  if (found) return found;
+
+  throw new Error([
+    'cargo was not found on PATH or in the default rustup locations.',
+    'Install Rust from https://rustup.rs or set HARNESS_CARGO to the cargo executable path.',
+  ].join('\n'));
+}
+
+function run(bin, args, options = {}) {
+  const command = [quote(bin), ...args.map(quote)].join(' ');
+  console.log(`> ${command}`);
+
+  const result = spawnSync(bin, args, {
+    cwd: options.cwd,
+    input: options.input,
+    encoding: 'utf8',
+    stdio: options.inherit ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const stdout = result.stdout ? `\nstdout:\n${result.stdout}` : '';
+    const stderr = result.stderr ? `\nstderr:\n${result.stderr}` : '';
+    throw new Error(`${command} exited ${result.status}${stdout}${stderr}`);
+  }
+
+  return result.stdout || '';
+}
+
+function quote(value) {
+  const text = String(value);
+  return /\s/.test(text) ? `"${text}"` : text;
+}

package/skills/claude-led-codex-review/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: claude-led-codex-review
+description: "Claude 주도 + Codex 위임 7단계 풀사이클 (idea → ship). Week 1 데모 정전(canon)."
+origin: harness-core
+level: 3
+prerequisites: [tdd-workflow, plan-eng-review]
+conflicts: []
+auto_inject_keywords: []
+tags: [workflow, review, codex, primary]
+---
+
+# claude-led-codex-review
+
+Claude 가 구현하고 Codex 가 의심하는 7단계 풀사이클. **HARNESS 의 정전 워크플로우.** 자동 활성 키워드는 비워두고 명시 호출만 받는다 (사용자 환경의 "확인 후 실행" 류 룰을 우회하지 않기 위함).
+
+## 호출
+
+```bash
+harness review "<task>"                    # 전체 사이클
+harness review "<task>" --secure           # + 단계 6 codex-challenge 강제
+harness review "<task>" --fast             # 단계 1·6 스킵
+harness review "<task>" --no-ship          # 단계 7 생략 (리뷰까지만)
+harness review "<task>" --no-codex         # 단계 5·6 스킵 (Codex 검증 생략)
+```
+
+또는 슬래시: `/claude-led-codex-review <task> [--flags]`
+
+## 7단계
+
+| # | 단계 | 담당 | 출력 |
+|---|---|---|---|
+| 1 | ideate | research, planner | `handoffs/01-ideate.md` |
+| 2 | plan | planner (opus, ro) | `prd-<id>.md` + `handoffs/02-plan.md` |
+| 3 | implement | executor (sonnet) + test-engineer | git diff, `handoffs/03-implement.md` |
+| 4 | self-review | code-reviewer (opus, ro) | `handoffs/04-self-review.md` (JSON) |
+| 5 | codex-review | codex-reviewer (별도 세션) | `handoffs/05-codex-review.md` (JSON) |
+| 6 | codex-challenge | codex-challenger (--secure) | `handoffs/06-challenge.md` (JSON) |
+| 7 | ship | doc-writer + git-master | PR + CHANGELOG diff + `handoffs/07-ship.md` |
+
+## Stage Routing 표 (필수 / 옵션)
+
+| Stage | Required | Optional (escalate) | 트리거 |
+|---|---|---|---|
+| 1 ideate | research, planner | architect | 모호한 요구 |
+| 2 plan | planner | architect | 시스템 설계 |
+| 3 implement | executor | debugger, test-engineer | TDD |
+| 4 self-review | code-reviewer | security-reviewer | auth/crypto / >20파일 |
+| 5 codex-review | codex-reviewer | — | --no-codex 가 아닐 때 |
+| 6 codex-challenge | codex-challenger | — | --secure 또는 sensitive 자동 감지 (--fast 와 동시 사용 불가) |
+| 7 ship | doc-writer, git-master | — | 모든 게이트 PASS |
+
+## 단계 5+6 병렬 실행
+
+`codex-review` 와 `codex-challenge` 는 같은 입력(`prd` / `priorHandoffs` / `diff`)을 받고 컨텍스트가 독립이라
+orchestrator 가 `Promise.all` 로 동시 호출한다. codex CLI 호출 시간(풀사이클의 가장 큰 비용)을
+1회 비용으로 단축.
+
+- 직렬 의미 동일: stage 5 critical 시 stage 6 결과는 폐기 (humanGate 즉시 return)
+- `--no-codex` 이면 stage 5·6 전체 스킵
+- `--fast` 또는 sensitive 미감지 + `--secure` 미지정이면 stage 6 자체 스킵 (병렬 안 함)
+- `--fast` 와 `--secure` 는 의미가 충돌하므로 CLI 가 즉시 거절
+- 코드: `scripts/orchestrators/review.js` 의 5+6 블록
+
+## Verdict 처리 + Fix Loop
+
+각 단계의 핸드오프는 `verdict: block | approve_with_fixes | approve` 와 issues 배열을 갖는다.
+
+### Verdict 자동 판정 룰
+
+`scripts/lib/severity.js` 의 `deriveVerdict(issues, opts)` 가 정전(canon).
+
+**BLOCK 강성 룰** (하나라도 충족):
+- `critical >= 1`
+- `high > 5` — high 다수는 자동 통과 위험, 추가 검토 강제
+- `confidence < 0.6` — codex 가 자신없게 답할 때 보수 안전망
+
+**APPROVE_WITH_FIXES**:
+- `high in [1, 5]`
+- `medium >= 1`
+- `blast_radius >= 10` 이면서 `issues.length >= 1` — 큰 변경은 작은 issue 라도 추가 검토
+
+**APPROVE**: 그 외.
+
+명시 verdict (`block`/`approve_with_fixes`/`approve`) 가 codex 응답에 있으면 그대로 따르되,
+`high > 5` 또는 `confidence < 0.6` 인 경우는 **block 으로 강등**한다 (codex 가 자신감 없이 approve 한 경우의 안전망).
+
+### Fix Loop
+
+```
+[5 codex-review] ──verdict──┐
+                            │
+       block / w_fixes ─────▶ [3a fix-loop] ──▶ [4 self] ──▶ [5 codex]
+                                    │
+                              round++; 한도 = 3
+                                    │
+                              critical 1+ 또는 round ≥ 3 ──▶ HUMAN_GATE
+                            │
+       approve ─────────────▶ [6? challenge | 7 ship]
+```
+
+## --secure 자동 활성 조건
+
+- 사용자 명시 플래그
+- 변경에 다음 보안 카테고리 키워드 포함 (단어 경계 매칭, 대소문자 무시):
+  - 인증·세션·시크릿: `auth`, `crypto`, `payment`, `session`, `permission`, `oauth`, `jwt`, `password`, `secret`
+  - 자격증명·토큰: `token`, `apikey`, `api-key`, `api_key`
+  - 인증서·전송보안: `cert`, `tls`, `ssl`, `mtls`
+  - 웹 보안: `csrf`, `cors`, `xss`
+  - 외부 검증: `webhook`
+- 단계 5 verdict = block 후 round = 2 진입 시
+
+## Fast 모드
+
+`--fast`:
+- 단계 1 (office-hours) 스킵 → 사용자 한 줄 → 바로 단계 2
+- 단계 6 (challenge) 스킵
+- `--secure` 와 같이 오면 실패. 보안 검증이 필요하면 `--secure` 만 사용
+
+단순 리팩토링·문서 변경에 권장. 보안·인증 코드에는 금지.
+
+## 핸드오프 5필드
+
+모든 단계의 마크다운 핸드오프는 `Decided / Rejected / Risks / Files / Remaining` 5필드를 지킨다. 자유 산문 금지. JSON 부속 (`schemas/handoff.schema.json`) 은 기계 처리용.
+
+## 비용 / 토큰 정책
+
+- Opus 에이전트(architect / planner / code-reviewer)는 read-only 강제 → 변경 비용 0.
+- Codex / Gemini 워커는 사용자 ChatGPT Pro / Gemini Pro CLI 를 통해 호출 → Anthropic 토큰 소비 0.
+- eco mode 시 opus → sonnet, sonnet → haiku (단계 4·5 는 sonnet floor).
+
+## 단계별 상세
+
+본 SKILL.md 가 단계별 상세의 정전(canon). 추가 노트 파일은 단계가 복잡해질 때 점진 추가.

package/skills/plan-eng-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plan-eng-review
+description: "엔지니어링 매니저 모드 계획 리뷰. 아키텍처 / 데이터 흐름 / 엣지 케이스 / 테스트 / 성능."
+origin: harness-core
+level: 2
+prerequisites: []
+conflicts: []
+tags: [planning, review]
+---
+
+# plan-eng-review
+
+planner / architect 가 산출한 PRD 와 단계 분해를 락인 직전에 한 번 더 본다. 구현 시작 전에 잡을 수 있는 아키텍처 이슈를 잡는다.
+
+## 호출
+
+```bash
+harness plan-eng-review <prd-path>
+```
+
+claude-led-codex-review 단계 2 의 일부로 자동 호출된다.
+
+## 체크리스트
+
+### 아키텍처
+- [ ] 모듈 경계 / 책임 명확
+- [ ] 의존 방향 (DI, 인터페이스 분리)
+- [ ] 결합도 / 응집도
+
+### 데이터 흐름
+- [ ] 입력 / 출력 / 부수 효과 표
+- [ ] 트랜잭션 경계
+- [ ] 롤백 / 복구
+
+### 엣지 케이스
+- [ ] null / empty / 음수 / 매우 큰 값
+- [ ] 동시성 / race condition
+- [ ] 부분 실패 (외부 API timeout, 네트워크 끊김)
+
+### 테스트 커버리지
+- [ ] 단위 / 통합 / E2E 분배
+- [ ] 80% 게이트
+- [ ] 회귀 케이스
+
+### 성능
+- [ ] N+1 / 메모리 / 알고리즘 복잡도
+- [ ] 벤치 기준선
+
+## 출력
+
+체크리스트 채워진 마크다운 + 발견 이슈 (severity 분류). 이슈는 PRD 에 다시 반영 (acceptance criteria 추가 또는 비목표 명시).