@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/demo-review.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// claude-led-codex-review 풀사이클 시뮬레이션 (Week 1 데모).
+// 실제 LLM 호출은 안 함 — 7단계의 핸드오프 파일 / 상태 / round 카운터가 잘 흐르는지만 검증.
+// 사용자 룰("git push 사용자 확인") 우선이라 실 ship 은 안 함.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+const TASK = process.argv[2] || 'JWT 검증 미들웨어 추가';
+const SESSION_ID = process.argv[3] || `demo-${Date.now()}`;
+const SECURE = process.argv.includes('--secure');
+const NO_SHIP = process.argv.includes('--no-ship');
+
+const SESSION_DIR = path.join(ROOT, '.harness', 'state', 'sessions', SESSION_ID);
+fs.mkdirSync(path.join(SESSION_DIR, 'handoffs'), { recursive: true });
+
+console.log(`\n=== claude-led-codex-review demo ===`);
+console.log(`session : ${SESSION_ID}`);
+console.log(`task    : ${TASK}`);
+console.log(`flags   : ${SECURE ? '--secure ' : ''}${NO_SHIP ? '--no-ship' : ''}`);
+console.log('');
+
+function callMcp(tool, args) {
+  // 단순 시뮬레이션: 직접 디스크에 쓰기.
+  if (tool === 'state_write') {
+    const file = path.join(SESSION_DIR, args.key === 'prd' ? 'prd.json' : args.key);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, typeof args.value === 'string' ? args.value : JSON.stringify(args.value, null, 2));
+  } else if (tool === 'handoff_write') {
+    const stageOrder = ['ideate', 'plan', 'implement', 'self-review', 'codex-review', 'codex-challenge', 'ship'];
+    const nn = String(stageOrder.indexOf(args.stage) + 1).padStart(2, '0');
+    const base = handoffBase(nn, args);
+    const md = renderHandoff(args);
+    fs.writeFileSync(path.join(SESSION_DIR, 'handoffs', `${base}.md`), md);
+    fs.writeFileSync(path.join(SESSION_DIR, 'handoffs', `${base}.json`),
+      JSON.stringify({ ...args, timestamp: new Date().toISOString() }, null, 2));
+  }
+}
+
+function handoffBase(nn, args) {
+  const round = Number(args.round || 1);
+  return `${nn}-${args.stage}${round > 1 ? `-r${round}` : ''}`;
+}
+
+function renderHandoff(a) {
+  const L = [];
+  L.push(`# Handoff: ${a.stage}  (round ${a.round || 1}, agent: ${a.agent})`);
+  L.push('');
+  L.push(`**Decided**: ${a.decided}`);
+  if (a.rejected)  L.push(`**Rejected**: ${a.rejected}`);
+  if (a.risks)     L.push(`**Risks**: ${a.risks}`);
+  L.push(`**Files**: ${(a.files || []).join(', ')}`);
+  if (a.remaining) L.push(`**Remaining**: ${a.remaining}`);
+  if (a.verdict)   L.push(`**Verdict**: ${a.verdict}`);
+  if (a.issues?.length) {
+    L.push(''); L.push('## Issues');
+    for (const i of a.issues) L.push(`- [${i.severity}/${i.category}] ${i.file || ''} — ${i.summary}`);
+  }
+  return L.join('\n') + '\n';
+}
+
+function step(n, name, fn) {
+  console.log(`[${n}] ${name} …`);
+  fn();
+  console.log(`    ✓ handoff ${path.relative(ROOT, path.join(SESSION_DIR, 'handoffs')).replace(/\\/g, '/')}/...`);
+}
+
+// ---- 1. ideate ----
+step(1, 'ideate (research, planner)', () => {
+  callMcp('handoff_write', {
+    stage: 'ideate', agent: 'planner', round: 1,
+    decided: `${TASK} 의 후보 접근 3개 비교 후 표준 lib jose 채택`,
+    rejected: 'jsonwebtoken (CVE 이력), 자체 구현 (유지보수 부담)',
+    risks: '키 회전 정책 미정',
+    files: ['src/auth/jwt.ts (예정)'],
+    remaining: 'planner 에 PRD 시드',
+  });
+});
+
+// ---- 2. plan ----
+step(2, 'plan (planner)', () => {
+  callMcp('state_write', { key: 'prd', value: {
+    task: TASK,
+    acceptance: [
+      { id: 'AC-001', desc: 'verifyJwt 가 유효한 토큰을 통과시킨다', passes: false },
+      { id: 'AC-002', desc: 'verifyJwt 가 만료 토큰을 거절한다', passes: false },
+      { id: 'AC-003', desc: 'verifyJwt 가 잘못된 서명을 거절한다', passes: false },
+    ],
+    non_goals: ['키 회전', '리프레시 토큰'],
+  }});
+  callMcp('handoff_write', {
+    stage: 'plan', agent: 'planner', round: 1,
+    decided: 'AC 3개로 분해. jose 라이브러리. 단계 4 에서 security-reviewer 추가 강제 (auth 영역)',
+    files: ['prd.json'], remaining: 'executor 에 핸드오프',
+  });
+});
+
+// ---- 3. implement ----
+step(3, 'implement (executor + test-engineer, TDD)', () => {
+  callMcp('handoff_write', {
+    stage: 'implement', agent: 'executor', round: 1,
+    decided: 'TDD 3 사이클. AC-001/002/003 모두 GREEN. quality-gate 통과.',
+    files: ['src/auth/jwt.ts', 'tests/unit/jwt.test.ts'],
+    remaining: 'self-review',
+  });
+});
+
+// ---- 4. self-review ----
+let round = 1;
+let block = false;
+step(4, `self-review (code-reviewer, opus, ro) round ${round}`, () => {
+  const issues = [
+    { severity: 'high', category: 'security', file: 'src/auth/jwt.ts', line: 23,
+      summary: 'iat / nbf 검증 누락', why: '토큰의 발급 시각 검증 없음. 미래 토큰 허용 가능' },
+    { severity: 'medium', category: 'test', file: 'tests/unit/jwt.test.ts',
+      summary: 'audience claim 케이스 부족', why: 'aud 미스매치 테스트 없음' },
+  ];
+  callMcp('handoff_write', {
+    stage: 'self-review', agent: 'code-reviewer', round,
+    decided: 'high 1, medium 1 발견. fix loop 진입.',
+    files: ['src/auth/jwt.ts'], remaining: '단계 3a fix-loop',
+    issues, verdict: 'approve_with_fixes', confidence: 0.85,
+  });
+  block = issues.some(i => i.severity === 'critical');
+});
+
+// ---- 3a. fix loop (high 발견 → executor 재호출) ----
+console.log('[3a] fix-loop: executor 재호출 (high 수정) …');
+round = 2;
+callMcp('handoff_write', {
+  stage: 'implement', agent: 'executor', round,
+  decided: 'iat/nbf 검증 추가. audience claim 테스트 추가.',
+  files: ['src/auth/jwt.ts', 'tests/unit/jwt.test.ts'],
+  remaining: 'self-review 재실행',
+});
+console.log(`    ✓ round ${round} 진입`);
+
+step(4, `self-review round ${round}`, () => {
+  callMcp('handoff_write', {
+    stage: 'self-review', agent: 'code-reviewer', round,
+    decided: '이전 high 해결. 신규 발견 0건.',
+    files: ['src/auth/jwt.ts'], remaining: 'codex-review',
+    verdict: 'approve', confidence: 0.92,
+  });
+});
+
+// ---- 5. codex-review ----
+round = 1;
+step(5, 'codex-review (Codex CLI 별도 세션)', () => {
+  callMcp('handoff_write', {
+    stage: 'codex-review', agent: 'codex-reviewer', round,
+    decided: 'Claude self-review 와 일치. 추가 발견 medium 1 (네트워크 timeout 미설정).',
+    rejected: '없음',
+    files: ['src/auth/jwt.ts'],
+    remaining: '--secure 가 활성이면 단계 6, 아니면 단계 7',
+    issues: [{ severity: 'medium', category: 'correctness', file: 'src/auth/jwt.ts',
+      summary: 'JWKS fetch timeout 미설정', why: 'fetch 가 무한 대기 가능' }],
+    verdict: 'approve_with_fixes', confidence: 0.88,
+  });
+});
+
+// ---- 6. codex-challenge (--secure 자동 활성: auth/ 디렉터리 변경) ----
+const isAuthChange = true;
+const wantChallenge = SECURE || isAuthChange;
+if (wantChallenge) {
+  step(6, 'codex-challenge (auth 영역 자동 활성)', () => {
+    callMcp('handoff_write', {
+      stage: 'codex-challenge', agent: 'codex-challenger', round: 1,
+      decided: '적대적 시나리오 5건 검토. 신규 critical 0, high 0, info 1 (replay 방어 권장).',
+      files: ['src/auth/jwt.ts'],
+      remaining: 'ship',
+      issues: [{ severity: 'info', category: 'security', summary: 'jti / replay cache 권장 (현 PRD 비목표)' }],
+      verdict: 'approve', confidence: 0.95,
+    });
+  });
+} else {
+  console.log('[6] codex-challenge skipped (--secure 미활성, auth 영역 아님)');
+}
+
+// ---- 7. ship ----
+if (NO_SHIP) {
+  console.log('[7] ship skipped (--no-ship)');
+} else {
+  step(7, 'ship (doc-writer + git-master)', () => {
+    callMcp('handoff_write', {
+      stage: 'ship', agent: 'doc-writer', round: 1,
+      decided: 'CHANGELOG 갱신. PR 본문 한국어 초안. 자동 push 안 함 (사용자 룰).',
+      files: ['docs/CHANGELOG.md', 'WORKING-CONTEXT.md'],
+      remaining: '사용자 검토 후 gh pr create 또는 git push 수동 실행',
+    });
+  });
+}
+
+console.log('\n=== 결과 ===');
+const handoffs = fs.readdirSync(path.join(SESSION_DIR, 'handoffs')).filter(f => f.endsWith('.md')).sort();
+for (const f of handoffs) console.log('  - handoffs/' + f);
+console.log('\n=== prd.json ===');
+console.log(fs.readFileSync(path.join(SESSION_DIR, 'prd.json'), 'utf8'));
+console.log('=== 데모 종료 ===\n');

package/scripts/doctor.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveProviderCli } from './core/cli-resolver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = path.resolve(__dirname, '..');
+
+const BLOCKED_ENV = {
+  claude: ['ANTHROPIC_API_KEY'],
+  codex: ['OPENAI_API_KEY'],
+  gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+};
+
+const STATUS_RANK = { PASS: 0, WARN: 1, FAIL: 2 };
+
+export function parseDoctorArgs(argv = []) {
+  const opts = {
+    json: false,
+    geminiSmoke: false,
+    projectRoot: null,
+    quick: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') opts.json = true;
+    else if (arg === '--gemini-smoke') opts.geminiSmoke = true;
+    else if (arg === '--quick') opts.quick = true;
+    else if (arg === '--project-root') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error('--project-root requires a value');
+      opts.projectRoot = value;
+    } else if (arg.startsWith('--project-root=')) {
+      opts.projectRoot = arg.slice('--project-root='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown doctor option: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+export function buildDoctorReport(options = {}) {
+  const harnessRoot = path.resolve(options.harnessRoot || DEFAULT_ROOT);
+  const projectRoot = path.resolve(options.projectRoot || process.env.HARNESS_PROJECT_ROOT || process.cwd());
+  const env = options.env || process.env;
+  const runCommand = options.runCommand || defaultRunCommand;
+  const nodeVersion = options.nodeVersion || process.versions.node;
+  const quick = Boolean(options.quick);
+  const geminiSmoke = Boolean(options.geminiSmoke);
+
+  const checks = [];
+
+  checks.push(checkNodeVersion(nodeVersion));
+  checks.push(checkPackageMetadata(harnessRoot));
+  checks.push(checkGitWorktree(projectRoot, runCommand));
+  checks.push(checkApiKeyEnvironment(env));
+
+  checks.push(...checkProviderClis({ harnessRoot, projectRoot, env, runCommand, geminiSmoke }));
+
+  if (geminiSmoke) {
+    checks.push(checkCommand('gemini live smoke', 'node scripts/verify/gemini-live.js', runCommand, harnessRoot, [
+      process.execPath,
+      ['scripts/verify/gemini-live.js'],
+    ]));
+  }
+
+  if (!quick) {
+    checks.push(checkCommand('repair freshness', 'node scripts/repair.js --check', runCommand, harnessRoot, [
+      process.execPath,
+      ['scripts/repair.js', '--check'],
+    ]));
+    checks.push(checkCommand('CLAUDE.md sync', 'node scripts/sync-claude-md.js --check', runCommand, harnessRoot, [
+      process.execPath,
+      ['scripts/sync-claude-md.js', '--check'],
+    ]));
+    checks.push(checkCommand('codemaps freshness', 'node scripts/build-codemaps.js --check', runCommand, harnessRoot, [
+      process.execPath,
+      ['scripts/build-codemaps.js', '--check'],
+    ]));
+  }
+
+  const summary = summarize(checks);
+  return {
+    name: 'NEKOWORK doctor',
+    harnessRoot,
+    projectRoot,
+    quick,
+    geminiSmoke,
+    summary,
+    checks,
+  };
+}
+
+export function renderDoctorReport(report) {
+  const lines = [];
+  lines.push('NEKOWORK doctor');
+  lines.push(`harness root : ${report.harnessRoot}`);
+  lines.push(`project root : ${report.projectRoot}`);
+  lines.push('');
+  lines.push(`${pad('STATUS', 6)}  ${pad('CHECK', 22)}  MESSAGE`);
+  lines.push(`${'-'.repeat(6)}  ${'-'.repeat(22)}  ${'-'.repeat(50)}`);
+  for (const check of report.checks) {
+    lines.push(`${pad(check.status, 6)}  ${pad(check.name, 22)}  ${check.message}`);
+  }
+  lines.push('');
+  lines.push(`summary: ${report.summary.status} (${report.summary.pass} pass, ${report.summary.warn} warn, ${report.summary.fail} fail)`);
+  return lines.join('\n');
+}
+
+function checkNodeVersion(version) {
+  const major = Number(String(version).split('.')[0]);
+  if (major >= 22) return pass('node', `Node ${version}`);
+  return fail('node', `Node ${version}; required >= 22`);
+}
+
+function checkPackageMetadata(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name !== '@ps-neko/nekowork') {
+      return fail('package metadata', `unexpected package name: ${pkg.name}`);
+    }
+    if (!pkg.version) return fail('package metadata', 'missing package version');
+    if (pkg.private === true) {
+      return pass('package metadata', `${pkg.name}@${pkg.version}; private publish disabled`);
+    }
+    if (pkg.private === false && isPublicAlphaVersion(pkg.version)) {
+      return pass('package metadata', `${pkg.name}@${pkg.version}; public alpha publish candidate`);
+    }
+    return warn('package metadata', `${pkg.name}@${pkg.version}; publish guard is not explicit`);
+  } catch (error) {
+    return fail('package metadata', `cannot read package.json: ${error.message}`);
+  }
+}
+
+function isPublicAlphaVersion(version) {
+  return /^\d+\.\d+\.\d+-alpha\.\d+$/.test(String(version));
+}
+
+function checkGitWorktree(projectRoot, runCommand) {
+  const result = runCommand('git', ['rev-parse', '--is-inside-work-tree'], { cwd: projectRoot, timeoutMs: 5000 });
+  if (result.status === 0 && result.stdout.trim() === 'true') {
+    return pass('git worktree', 'project root is inside a git worktree');
+  }
+  return warn('git worktree', 'project root is not a git worktree; reviews still run, but git-aware guards are limited');
+}
+
+function checkApiKeyEnvironment(env) {
+  const found = [];
+  for (const keys of Object.values(BLOCKED_ENV)) {
+    for (const key of keys) if (env[key]) found.push(key);
+  }
+  if (!found.length) return pass('api key env', 'no delegated-provider API key overrides detected');
+  if (env.HARNESS_AUTH_ALLOW_ENV_OVERRIDE === '1') {
+    return warn('api key env', `explicit metered opt-in is enabled for: ${found.join(', ')}`);
+  }
+  return warn('api key env', `will be blocked before delegated CLI calls: ${found.join(', ')}`);
+}
+
+function checkProviderClis({ harnessRoot, projectRoot, env, runCommand, geminiSmoke }) {
+  return [
+    checkProviderCli('claude', ['auth', 'status'], { harnessRoot, projectRoot, env, runCommand }),
+    checkProviderCli('codex', ['login', 'status'], { harnessRoot, projectRoot, env, runCommand }),
+    checkProviderCli('gemini', null, { harnessRoot, projectRoot, env, runCommand, geminiSmoke }),
+  ];
+}
+
+function checkProviderCli(provider, authArgs, { harnessRoot, projectRoot, env, runCommand, geminiSmoke }) {
+  let resolved;
+  try {
+    resolved = resolveProviderCli(provider, {
+      root: projectRoot,
+      roots: [projectRoot, harnessRoot],
+      env,
+    });
+  } catch (error) {
+    return fail(`${provider} cli`, error.message.split('\n')[0]);
+  }
+
+  if (!resolved) return warn(`${provider} cli`, `${provider} CLI not found on PATH; mock mode still works`);
+
+  if (!authArgs) {
+    if (provider === 'gemini' && geminiSmoke) {
+      return pass(`${provider} cli`, `${resolved}; installed; live smoke requested`);
+    }
+    return warn(`${provider} cli`, `${resolved}; installed; auth status is not checked non-interactively; run --gemini-smoke or npm run verify:gemini`);
+  }
+
+  const auth = runCommand(resolved, authArgs, { cwd: projectRoot, timeoutMs: 10000 });
+  if (auth.status === 0) return pass(`${provider} cli`, `${resolved}; auth status OK`);
+
+  const detail = firstNonEmptyLine(auth.stderr) || firstNonEmptyLine(auth.stdout) || `exit ${auth.status}`;
+  return warn(`${provider} cli`, `${resolved}; auth status not ready (${detail})`);
+}
+
+function checkCommand(name, label, runCommand, cwd, command) {
+  const [bin, args] = command;
+  const result = runCommand(bin, args, { cwd, timeoutMs: 30000 });
+  if (result.status === 0) return pass(name, `${label} passed`);
+  const detail = firstNonEmptyLine(result.stderr) || firstNonEmptyLine(result.stdout) || `exit ${result.status}`;
+  return fail(name, `${label} failed: ${detail}`);
+}
+
+function summarize(checks) {
+  const counts = { pass: 0, warn: 0, fail: 0 };
+  for (const check of checks) counts[check.status.toLowerCase()]++;
+  const status = counts.fail ? 'FAIL' : (counts.warn ? 'WARN' : 'PASS');
+  return { status, ...counts };
+}
+
+function pass(name, message) {
+  return { status: 'PASS', name, message };
+}
+
+function warn(name, message) {
+  return { status: 'WARN', name, message };
+}
+
+function fail(name, message) {
+  return { status: 'FAIL', name, message };
+}
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}
+
+function firstNonEmptyLine(value = '') {
+  return String(value).split(/\r?\n/).map((line) => line.trim()).find(Boolean) || '';
+}
+
+function defaultRunCommand(command, args, options = {}) {
+  const invocation = normalizeSpawnInvocation(command, args);
+  const result = spawnSync(invocation.command, invocation.args, {
+    cwd: options.cwd,
+    env: { ...process.env, FORCE_COLOR: '0' },
+    encoding: 'utf8',
+    timeout: options.timeoutMs || 10000,
+  });
+  return {
+    status: result.status ?? (result.error ? 1 : 0),
+    stdout: result.stdout || '',
+    stderr: result.stderr || (result.error ? result.error.message : ''),
+  };
+}
+
+function normalizeSpawnInvocation(command, args) {
+  const ext = path.extname(command).toLowerCase();
+  if (process.platform === 'win32' && (ext === '.cmd' || ext === '.bat')) {
+    return { command: 'cmd.exe', args: ['/d', '/c', command, ...args] };
+  }
+  return { command, args };
+}
+
+function printHelp() {
+  console.log(`NEKOWORK doctor
+
+Usage:
+  harness doctor [--project-root <dir>] [--quick] [--gemini-smoke] [--json]
+
+Checks:
+  - Node.js version
+  - package metadata and publish guard
+  - git worktree
+  - delegated-provider API key environment overrides
+  - Claude/Codex/Gemini CLI presence and auth where non-interactive status exists
+  - Gemini live smoke when --gemini-smoke is set
+  - repair, CLAUDE.md sync, and codemap freshness unless --quick is set
+`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const opts = parseDoctorArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const report = buildDoctorReport({
+      harnessRoot: DEFAULT_ROOT,
+      projectRoot: opts.projectRoot,
+      quick: opts.quick,
+      geminiSmoke: opts.geminiSmoke,
+    });
+    if (opts.json) console.log(JSON.stringify(report, null, 2));
+    else console.log(renderDoctorReport(report));
+    process.exit(STATUS_RANK[report.summary.status] === 2 ? 1 : 0);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+}

package/scripts/install-apply.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// HARNESS install --apply : plan 단계 검증 → harness 별 빌드 (agent.yaml harnesses 전부) → install-state 기록 → 마커 검증.
+// 멱등(idempotent). 실패 시 롤백은 git checkout 으로.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import {
+  buildInstallState,
+  loadInstallState,
+  writeInstallState,
+} from './core/install-state.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+function parseArgs(argv) {
+  const args = {
+    profile: null,
+    harness: null,
+    force: false,
+    dryRun: false,
+    projectRoot: null,
+    modules: [],
+    withoutModules: [],
+    components: [],
+    withoutComponents: [],
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--profile') args.profile = takeValue(argv, i++, a);
+    else if (a === '--harness' || a === '--target') args.harness = takeValue(argv, i++, a);
+    else if (a === '--module' || a === '--with-module') args.modules.push(takeValue(argv, i++, a));
+    else if (a === '--without-module') args.withoutModules.push(takeValue(argv, i++, a));
+    else if (a === '--component' || a === '--with-component') args.components.push(takeValue(argv, i++, a));
+    else if (a === '--without-component') args.withoutComponents.push(takeValue(argv, i++, a));
+    else if (a === '--project-root' || a === '--target-root') args.projectRoot = takeValue(argv, i++, a);
+    else if (a === '--force') args.force = true;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--help' || a === '-h') { printHelp(); process.exit(0); }
+    else { console.error(`알 수 없는 인자: ${a}`); process.exit(2); }
+  }
+  return args;
+}
+
+function takeValue(argv, i, flag) {
+  const value = argv[i + 1];
+  if (!value || value.startsWith('--')) {
+    console.error(`${flag} value required`);
+    process.exit(2);
+  }
+  return value;
+}
+
+function printHelp() {
+  console.log(`
+HARNESS install --apply
+
+사용법:
+  install.sh --apply [--profile <name>] [--harness <name>] [--module <id>] [--component <id>] [--project-root <dir>] [--force] [--dry-run]
+
+옵션:
+  --profile <name>          프로파일 선택 (기본: agent.yaml profiles.default)
+  --harness <name>          특정 하네스만 빌드 (claude | codex | cursor | gemini | opencode)
+  --target <name>           --harness alias
+  --module <id>             include an additional module, repeatable
+  --without-module <id>     exclude a module, repeatable
+  --component <id>          include a direct component, repeatable
+  --without-component <id>  exclude a component, repeatable
+  --project-root <dir>      write harness outputs and .harness/install-state.json to this project root
+  --target-root <dir>       alias for --project-root
+  --force                   기존 출력 무시하고 재생성
+  --dry-run                 plan 만 다시 출력하고 종료
+`);
+}
+
+function runBuilder(name, targetRoot) {
+  const script = path.join(__dirname, `build-${name}.js`);
+  if (!fs.existsSync(script)) {
+    console.error(`  [SKIP] build-${name}.js 없음`);
+    return false;
+  }
+  const r = spawnSync(process.execPath, [script], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      HARNESS_SOURCE_ROOT: ROOT,
+      HARNESS_TARGET_ROOT: targetRoot,
+    },
+  });
+  return r.status === 0;
+}
+
+function recordState(profile, harnessDefs, builders, targetRoot) {
+  const previousState = loadInstallState(targetRoot);
+  const { state, sourceSha } = buildInstallState(ROOT, {
+    targetRoot,
+    profile,
+    harnessDefs,
+    harnessNames: builders,
+    previousState,
+  });
+  const stateFile = writeInstallState(targetRoot, state, { schemaRoot: ROOT });
+  console.log(`  state: ${path.relative(targetRoot, stateFile)}`);
+  console.log(`  source_sha256: ${sourceSha.slice(0, 12)}…`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const targetRoot = path.resolve(args.projectRoot || process.env.HARNESS_PROJECT_ROOT || ROOT);
+
+  // 1. plan 먼저 (검증 + 결과 표시)
+  console.log('=> plan 단계');
+  const planResult = spawnSync(
+    process.execPath,
+    [path.join(__dirname, 'install-plan.js'), ...planArgs(args)],
+    { stdio: 'inherit' },
+  );
+  if (planResult.status !== 0) {
+    console.error('plan 실패. apply 중단.');
+    process.exit(1);
+  }
+
+  if (args.dryRun) {
+    console.log('--dry-run: apply 안 함.');
+    return;
+  }
+
+  console.log(`=> target root: ${targetRoot}`);
+
+  // 2. .mcp.json 검증 (있으면 OK, 없으면 경고)
+  if (!fs.existsSync(path.join(ROOT, '.mcp.json'))) {
+    console.warn('WARN: .mcp.json 없음. bridge/mcp-server.js 등록 필요.');
+  }
+
+  // 3. 빌더 실행 (agent.yaml harnesses 의 name 그대로)
+  const manifest = YAML.parse(fs.readFileSync(path.join(ROOT, 'agent.yaml'), 'utf8'));
+  const harnessDefs = manifest.harnesses || [];
+  const allBuilders = harnessDefs.map(h => h.name);
+  const builders = args.harness ? [args.harness] : allBuilders;
+  console.log('');
+  console.log(`=> apply: ${builders.join(', ')}`);
+  for (const b of builders) {
+    console.log('');
+    if (!runBuilder(b, targetRoot)) {
+      console.error(`build-${b} 실패`);
+      process.exit(1);
+    }
+  }
+
+  // 4. state 기록
+  console.log('');
+  console.log('=> state 기록');
+  recordState(args.profile || manifest.profiles?.default || 'developer', harnessDefs, builders, targetRoot);
+
+  // 5. 마커 검증
+  console.log('');
+  console.log('=> 마커 검증');
+  const markerCheck = spawnSync(process.execPath, [path.join(__dirname, 'ci', 'check-markers.js')], { stdio: 'inherit' });
+  if (markerCheck.status !== 0) {
+    console.warn('WARN: 마커 검증 실패. CLAUDE.md 영역 확인 필요.');
+  }
+
+  console.log('');
+  console.log('apply 완료.');
+}
+
+function planArgs(args) {
+  return [
+    ...(args.profile ? ['--profile', args.profile] : []),
+    ...(args.harness ? ['--target', args.harness] : []),
+    ...(args.projectRoot ? ['--project-root', args.projectRoot] : []),
+    ...args.modules.flatMap(v => ['--module', v]),
+    ...args.withoutModules.flatMap(v => ['--without-module', v]),
+    ...args.components.flatMap(v => ['--component', v]),
+    ...args.withoutComponents.flatMap(v => ['--without-component', v]),
+  ];
+}
+
+main().catch((e) => {
+  console.error('UNEXPECTED:', e?.stack || e);
+  process.exit(1);
+});