prooflist 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# ProofList
+
+**증거 없으면 완료 불가.** Claude 전용 개발·테스트 체크리스트 — 프로젝트마다 임베디드되는 CLI + 로컬 감독 대시보드.
+
+화면 작업은 Claude가 직접 작성·실행한 자동 UI 테스트(모바일=Maestro)의 **실행 결과물(스크린샷·pass/fail)이 붙어야만** `done`으로 체크된다. 자동화로 못 잡는 영역(`human-gate`)은 사람 서명 전까지 Claude가 절대 완료할 수 없다. 완료 강제는 하네스 Stop 훅이 한다 — Claude의 자기 절제가 아니라.
+
+## 왜
+
+todolist 관리에서 두 가지 문제를 동시에 해결한다:
+
+- **(A) 관리 가시성** — 기획→작업단위 분할→리스트→상태/퍼센트→완료마다 갱신이 한눈에. 퍼센트는 트리 롤업으로 자동 계산(수동 입력 누락 차단).
+- **(B) 테스트 정직성** — Claude가 화면을 안 보고 "됐다"고 하거나, 못 하는 영역도 했다고 하는 문제를 증거 게이트로 차단. 특히 모바일앱.
+
+## 운영자는 Claude
+
+사람이 손으로 체크하는 todo 앱이 아니다. `pl` CLI가 Claude의 1차 인터페이스(JSON-first 출력 + `nextAction` 지시문), 웹 대시보드는 승기의 **감독 패널**(주장 vs 증거를 대조하는 신뢰 원장).
+
+## 워크플로우
+
+```
+pl init             # .prooflist/ 스캐폴드 + Stop 훅 자동 배선
+pl plan             # 작업 트리 + 각 작업 kind(logic/screen/human-gate)
+pl start <id>
+pl test <id>        # .maestro/<id>.yaml 실행 → 스샷·pass 증거 생성
+pl done <id>        # 게이트 통과 시에만 done. 거부 시 nextAction 따름
+pl signoff <id>     # human-gate 작업을 사람이 서명 완료
+pl ui               # 로컬 감독 대시보드
+pl gate --check     # 무결성 검사(Stop 훅이 호출)
+```
+
+## 위협 모델 (Claude의 우회 패턴 차단)
+
+| ID | 패턴 | 방어 |
+|---|---|---|
+| F1 | 화면 안 보고 "됐다" | screen done은 통과 Maestro 아티팩트 필수 |
+| F2 | 못 하는 영역 했다고 함 | `human-gate`는 사람 서명만 |
+| F3 | kind를 screen→logic으로 낮춤 | touchedPaths로 검증·차단, 사람이 잠금 |
+| F4 | 오래된/재사용 아티팩트 | 해시 + 최신성 검사 |
+| F5 | checklist.json 손편집 | Stop 훅이 전체 무결성 재검증 |
+
+## 상태
+
+설계·구현 계획 완료, 구현 진행 중. 모바일(Maestro) 먼저, 웹(Playwright)은 후속.
+
+- 설계 스펙·구현 계획은 포트폴리오 메타 repo(`prooflist-design.md` / `prooflist-plan.md`)에 있음.
+
+## 스택
+
+TypeScript(ESM, Node 20+) · vitest · commander · node:http(대시보드, 무프레임워크) · Maestro.

package/dist/adapters/index.js

@@ -0,0 +1,150 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { maestroAdapter } from "../runner.js";
+// --- 작은 파일시스템 헬퍼들 (탐지는 repo를 들여다보는 게 본분) ---
+function exists(...parts) {
+    return existsSync(join(...parts));
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// repoRoot 기준 첫 N단계까지 디렉터리/파일을 훑되, node_modules·.git은 가지치기.
+function walk(root, maxDepth = 4) {
+    const out = [];
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next"]);
+    const rec = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            out.push(full);
+            if (isDir(full) && !SKIP.has(name))
+                rec(full, depth + 1);
+        }
+    };
+    rec(root, 0);
+    return out;
+}
+function readPackageJson(repoRoot) {
+    const p = join(repoRoot, "package.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function pkgHasKeyOrDep(repoRoot, key) {
+    const pkg = readPackageJson(repoRoot);
+    if (!pkg)
+        return false;
+    if (pkg[key])
+        return true;
+    return Boolean(pkg.dependencies?.[key] || pkg.devDependencies?.[key]);
+}
+const det = (framework, scenarioFiles, used) => ({ framework, used, scenarioFiles });
+// --- Detox: .detoxrc* 파일 | package.json의 detox 키 | e2e/*.e2e.{js,ts} ---
+export const detoxAdapter = {
+    framework: "detox",
+    detect(repoRoot) {
+        const all = walk(repoRoot);
+        const scenarioFiles = all.filter((f) => /\.e2e\.(js|ts)$/.test(f));
+        const hasRc = all.some((f) => /(^|\/)\.detoxrc[^/]*$/.test(f));
+        const used = hasRc || pkgHasKeyOrDep(repoRoot, "detox") || scenarioFiles.length > 0;
+        return det("detox", scenarioFiles, used);
+    },
+};
+// --- Playwright: playwright.config.{ts,js} | e2e//tests/ 하위 *.spec.{ts,js} ---
+export const playwrightAdapter = {
+    framework: "playwright",
+    detect(repoRoot) {
+        const hasConfig = exists(repoRoot, "playwright.config.ts") || exists(repoRoot, "playwright.config.js");
+        const all = walk(repoRoot);
+        const scenarioFiles = all.filter((f) => /\.spec\.(ts|js)$/.test(f) && /(^|\/)(e2e|tests)\//.test(f));
+        const used = hasConfig || scenarioFiles.length > 0;
+        return det("playwright", scenarioFiles, used);
+    },
+};
+// --- Cypress: cypress/ 디렉터리 | cypress.config.{ts,js}; 시나리오 cypress/e2e/** ---
+export const cypressAdapter = {
+    framework: "cypress",
+    detect(repoRoot) {
+        const hasConfig = exists(repoRoot, "cypress.config.ts") || exists(repoRoot, "cypress.config.js");
+        const hasDir = isDir(join(repoRoot, "cypress"));
+        const all = walk(repoRoot);
+        const scenarioFiles = all.filter((f) => /(^|\/)cypress\/e2e\//.test(f) && statSafe(f));
+        const used = hasConfig || hasDir;
+        return det("cypress", scenarioFiles, used);
+    },
+};
+// --- XCUITest: *UITests 디렉터리 | *.xctest ---
+export const xcuitestAdapter = {
+    framework: "xcuitest",
+    detect(repoRoot) {
+        const all = walk(repoRoot);
+        const scenarioFiles = all.filter((f) => (/UITests$/.test(f) && isDir(f)) || /\.xctest$/.test(f));
+        return det("xcuitest", scenarioFiles, scenarioFiles.length > 0);
+    },
+};
+// --- Espresso: androidTest 디렉터리 | build.gradle 내 espresso ---
+export const espressoAdapter = {
+    framework: "espresso",
+    detect(repoRoot) {
+        const all = walk(repoRoot);
+        const androidTestDirs = all.filter((f) => /(^|\/)androidTest$/.test(f) && isDir(f));
+        const gradleHasEspresso = all
+            .filter((f) => /build\.gradle(\.kts)?$/.test(f))
+            .some((f) => {
+            try {
+                return /espresso/i.test(readFileSync(f, "utf8"));
+            }
+            catch {
+                return false;
+            }
+        });
+        const used = androidTestDirs.length > 0 || gradleHasEspresso;
+        return det("espresso", androidTestDirs, used);
+    },
+};
+// --- Appium: wdio.conf* | package.json의 appium dep/키 ---
+export const appiumAdapter = {
+    framework: "appium",
+    detect(repoRoot) {
+        const all = walk(repoRoot);
+        const wdio = all.filter((f) => /(^|\/)wdio\.conf[^/]*\.(js|ts)$/.test(f));
+        const used = wdio.length > 0 || pkgHasKeyOrDep(repoRoot, "appium");
+        return det("appium", wdio, used);
+    },
+};
+function statSafe(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// 전 어댑터 레지스트리. Maestro만 run(Tier2)을 가짐 (§5.2).
+export const adapters = [
+    maestroAdapter,
+    detoxAdapter,
+    appiumAdapter,
+    xcuitestAdapter,
+    espressoAdapter,
+    playwrightAdapter,
+    cypressAdapter,
+];

package/dist/classify.js

@@ -0,0 +1,15 @@
+const UI_PATTERNS = [/\.tsx$/, /\.jsx$/, /\/screens?\//i, /\/components?\//i, /App\.(t|j)sx$/];
+export function expectedKind(touchedPaths) {
+    const touchesUI = touchedPaths.some((p) => UI_PATTERNS.some((re) => re.test(p)));
+    return touchesUI ? "screen" : "logic";
+}
+// F3: Claude가 게이트 회피하려 screen→logic으로 낮춘 경우 탐지.
+export function kindMismatch(task) {
+    if (task.kindLocked)
+        return false; // 사람이 잠근 분류는 신뢰
+    if (task.status !== "done")
+        return false;
+    if (task.kind !== "logic")
+        return false;
+    return expectedKind(task.touchedPaths) === "screen";
+}

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { loadChecklist, saveChecklist, getTask, setStatus, updateTask, rollupPercent } from "./store.js";
+import { canComplete, checkIntegrity } from "./gate.js";
+import { isEvidenceValid, stateHash } from "./evidence.js";
+import { runMaestro } from "./runner.js";
+import { codeFingerprint, latestCodeChange, flowContent, artifactExists } from "./util.js";
+import { detectFrameworks } from "./detect.js";
+import { isMainModule } from "./ismain.js";
+// Tier1 자문(advisory) 경고. 절대 gate enforcement(ok/violations)에 영향 주지 않음. (Task 13 Step 4)
+// 이미 계산한 detections 를 받는다 — status/gate 에서 detectFrameworks 를 두 번 돌지 않도록.
+function tierOneWarnings(fw) {
+    if (fw.length === 0)
+        return ["no test framework detected in this repo (Tier1) — screen tasks cannot reach ran-pass without one"];
+    return [];
+}
+// 작업에서 검증을 통과한 모든 증거 항목을 반환 (fs 사실을 코어에 주입).
+// 유일한 validity 출처 — validEvidenceEntry/hasValidEvidence/dashboard 가 모두 이걸 쓴다.
+export function validEvidenceEntries(dir, taskId) {
+    const c = loadChecklist(dir);
+    const t = getTask(c, taskId);
+    if (!t)
+        return [];
+    const expected = stateHash(flowContent(dir, taskId), codeFingerprint(dir));
+    const latest = latestCodeChange(dir, t.touchedPaths);
+    return t.evidence.filter((ev) => isEvidenceValid(ev, { latestCodeChange: latest, expectedHash: expected, fileExists: artifactExists(dir, ev.path) }).ok);
+}
+// 작업에서 실제로 검증을 통과한 증거 1건을 반환 (fs 사실을 코어에 주입).
+export function validEvidenceEntry(dir, taskId) {
+    return validEvidenceEntries(dir, taskId)[0];
+}
+// 작업에 유효 아티팩트가 있는지 — validEvidenceEntry 한 곳에서 판정.
+export function hasValidEvidence(dir, taskId) {
+    return !!validEvidenceEntry(dir, taskId);
+}
+export function runCli(argv, dir) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case "done": {
+            const id = rest[0];
+            const c = loadChecklist(dir);
+            const t = getTask(c, id);
+            if (!t)
+                return { ok: false, reason: `unknown task ${id}` };
+            const v = canComplete(t, { hasValidEvidence: hasValidEvidence(dir, id) });
+            if (!v.ok)
+                return v;
+            saveChecklist(dir, setStatus(c, id, "done"));
+            return { ok: true, id, status: "done" };
+        }
+        case "gate": { // gate --check
+            const c = loadChecklist(dir);
+            const fw = detectFrameworks(dir);
+            const violations = checkIntegrity(c, (taskId) => hasValidEvidence(dir, taskId));
+            return { ok: violations.length === 0, violations, warnings: tierOneWarnings(fw) };
+        }
+        case "start": {
+            const c = loadChecklist(dir);
+            saveChecklist(dir, setStatus(c, rest[0], "in_progress"));
+            return { ok: true, id: rest[0], status: "in_progress" };
+        }
+        case "signoff": {
+            // signoff is human-only and intentionally NOT a state-changing CLI action — this removes the
+            // Bash-reachable forge path. The genuine human channel is the dashboard '내가 확인함' button. (F2)
+            return {
+                ok: false,
+                reason: "signoff is human-only and not available via the CLI",
+                nextAction: "Ask 승기 to sign off task '" + rest[0] + "' via the dashboard '내가 확인함' button.",
+            };
+        }
+        case "status": {
+            const c = loadChecklist(dir);
+            const fw = detectFrameworks(dir);
+            return {
+                ok: true,
+                tasks: c.tasks.map((t) => ({ id: t.id, status: t.status, kind: t.kind, percent: rollupPercent(c, t.id) })),
+                frameworks: fw,
+                warnings: tierOneWarnings(fw),
+            };
+        }
+        case "test": {
+            const id = rest[0];
+            const c = loadChecklist(dir);
+            const t = getTask(c, id);
+            if (!t)
+                return { ok: false, reason: `unknown task ${id}` };
+            // 실제 maestro 호출은 동기 진입점에서만; 단위테스트는 runMaestro를 직접 검증(Task 6).
+            return { ok: true, id, note: "use the binary entrypoint to actually run maestro" };
+        }
+        case "set-kind": {
+            const id = rest[0];
+            const kind = rest[1];
+            const c = loadChecklist(dir);
+            const t = getTask(c, id);
+            if (!t)
+                return { ok: false, reason: `unknown task ${id}` };
+            if (kind !== "logic" && kind !== "screen" && kind !== "human-gate")
+                return { ok: false, reason: `invalid kind '${rest[1]}'`, nextAction: `Use one of: logic | screen | human-gate.` };
+            if (t.kindLocked)
+                return {
+                    ok: false,
+                    reason: `kind of '${id}' is locked by the human`,
+                    nextAction: `Ask 승기 to change the kind of '${id}'; Claude cannot modify a human-locked classification.`,
+                };
+            saveChecklist(dir, updateTask(c, id, { kind }));
+            return { ok: true, id, kind };
+        }
+        default:
+            return { ok: false, reason: `unknown command ${cmd}` };
+    }
+}
+// 실제 진입점(테스트 외): 인자 파싱 + JSON 출력. test/init은 부수효과 때문에 여기서 처리.
+if (isMainModule(import.meta.url)) {
+    (async () => {
+        const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+        const human = process.argv.includes("--human");
+        const dir = process.cwd();
+        if (argv[0] === "test") {
+            const { execFileSync } = await import("node:child_process");
+            const id = argv[1];
+            const ev = await runMaestro({
+                taskId: id,
+                flowContent: flowContent(dir, id),
+                codeFingerprint: codeFingerprint(dir),
+                exec: async () => {
+                    const outDir = `.prooflist/artifacts/${id}`;
+                    try {
+                        execFileSync("maestro", ["test", `.maestro/${id}.yaml`, "--format", "junit", "--output", outDir], { cwd: dir });
+                        return { code: 0, screenshots: [] };
+                    }
+                    catch {
+                        return { code: 1, screenshots: [] };
+                    }
+                },
+            });
+            const c = loadChecklist(dir);
+            saveChecklist(dir, updateTask(c, id, { evidence: [...(getTask(c, id)?.evidence ?? []), ev] }));
+            console.log(JSON.stringify({ ok: ev.passed, id, evidence: ev }));
+            process.exit(ev.passed ? 0 : 1);
+        }
+        if (argv[0] === "init") {
+            const { initProject } = await import("./init.js");
+            const out = initProject(dir);
+            console.log(JSON.stringify(out));
+            process.exit(0);
+        }
+        const out = runCli(argv, dir);
+        if (human)
+            console.log(JSON.stringify(out, null, 2));
+        else
+            console.log(JSON.stringify(out));
+        process.exit(out.ok === false ? 1 : 0);
+    })();
+}

package/dist/dashboard.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
+import { join, dirname, normalize, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadChecklist, getTask, updateTask, saveChecklist } from "./store.js";
+import { validEvidenceEntries } from "./cli.js";
+import { detectFrameworks, bestStrength } from "./detect.js";
+import { clearRepoMtimeMemo } from "./util.js";
+import { isMainModule } from "./ismain.js";
+// flat status → design status. in_progress 만 다름.
+function mapStatus(s) {
+    return s === "in_progress" ? "in-progress" : s;
+}
+const shortHash = (h) => (h ? h.slice(0, 8) + "…" : "");
+// ev.path 아래 아티팩트 파일을 화면용 shot 목록으로 합성.
+// 주의: shot 은 디렉터리 파일 목록일 뿐 per-shot 판정이 아니다 — 게이트가 이미 run 통과를
+// 보장했으므로 모든 항목을 pass 로 표기한다 (각 파일을 개별 검증하는 게 아님).
+function synthShots(dir, evPath) {
+    const abs = join(dir, ".prooflist/artifacts", evPath);
+    if (!existsSync(abs) || !statSync(abs).isDirectory())
+        return [];
+    return readdirSync(abs)
+        .filter((f) => statSync(join(abs, f)).isFile())
+        .map((f) => ({ cap: f, result: "pass" }));
+}
+// 검증을 통과한 증거 1건을 화면 표시 모양으로 변환. (검증 안 된 항목은 alarm 패널이 claim 으로 처리)
+function displayEvidence(dir, t, valid) {
+    const ev = valid[0];
+    if (!ev)
+        return undefined;
+    const video = valid.find((e) => e.type === "video") ?? (ev.type === "video" ? ev : undefined);
+    return {
+        type: t.kind === "screen" ? "screen" : "test",
+        framework: ev.framework ?? null,
+        runAt: ev.runAt,
+        hash: shortHash(ev.hash),
+        result: "pass",
+        ran: true,
+        stale: false,
+        scenario: false,
+        tests: "",
+        video: video ? video.path : null,
+        shots: t.kind === "screen" ? synthShots(dir, ev.path) : undefined,
+        watchNote: ev.note,
+    };
+}
+// 권위 있는 강도/알람 계산. operator-Claude 가 위조할 수 없도록 SERVER 가 산정한다 (F1).
+function authoritative(dir, t) {
+    const valid = validEvidenceEntries(dir, t.id);
+    // strength 는 검증을 통과한 증거에서만 도출 (evidenceStrength: video+humanVerified → visual-verified 등).
+    let strength;
+    if (valid.length > 0) {
+        // evidenceStrength(detect.ts) 가 강도의 단일 출처다 — 여기서 병렬 규칙을 재구현하지 않는다.
+        const derived = bestStrength(valid);
+        // 좁은 back-compat 승격: tier 필드 자체가 없는 **레거시(Task 9-era)** 증거만 대상.
+        // 그런 항목은 evidenceStrength 가 none/scenario 로 보지만, isEvidenceValid 를 통과한 유효 증거는
+        // 정의상 실제 실행·통과(passed+fresh+hash+exists)이므로 ran-pass 자격이 있다. tier 를 가진
+        // 증거는 절대 건드리지 않는다 — 그쪽은 evidenceStrength 의 판정을 그대로 보존한다.
+        const allLegacy = valid.every((e) => e.tier === undefined);
+        strength =
+            allLegacy && (derived === "none" || derived === "scenario") ? "ran-pass" : derived;
+    }
+    else
+        strength = t.evidence.length ? "scenario" : "none"; // 증거가 있으나 무효=stale/scenario, 없으면 none
+    const status = mapStatus(t.status);
+    const alarm = status === "done" && (strength === "none" || strength === "scenario");
+    const verifiedVideo = valid.find((e) => e.type === "video" && e.humanVerified === true);
+    return {
+        strength,
+        alarm,
+        humanVerified: !!verifiedVideo,
+        verifiedAt: verifiedVideo?.verifiedAt,
+        valid,
+    };
+}
+function nodeFor(dir, t, all, visited) {
+    // 사이클 방어: 현재 경로에 이미 방문한 노드면 다시 내려가지 않는다 (손편집 parent 순환 → 무한루프 방지).
+    const seen = new Set(visited);
+    seen.add(t.id);
+    const children = all
+        .filter((c) => c.parent === t.id && !seen.has(c.id))
+        .map((c) => nodeFor(dir, c, all, seen));
+    const node = {
+        id: t.id,
+        title: t.title,
+        kind: t.kind,
+        platform: t.platform,
+        locked: t.kindLocked,
+        status: mapStatus(t.status),
+        children,
+    };
+    // 부모(자식 보유) 노드는 강도/증거를 생략 — 자동 집계만. leaf claim 만 권위 강도 계산.
+    if (children.length === 0 && t.kind !== "human-gate") {
+        const a = authoritative(dir, t);
+        node.strength = a.strength;
+        node.alarm = a.alarm;
+        if (a.humanVerified) {
+            node.humanVerified = true;
+            if (a.verifiedAt)
+                node.verifiedAt = a.verifiedAt;
+        }
+        const ev = displayEvidence(dir, t, a.valid);
+        if (ev)
+            node.evidence = ev;
+        // done 인데 유효 증거 없음 → ⚠ 알람 패널은 claim 으로 렌더 (Task 9 동작 유지).
+        if (a.alarm)
+            node.claim = t.title || "완료";
+    }
+    // human-gate / needs-human: evidence·claim·strength 없음 (클라가 🔒/진행 렌더)
+    return node;
+}
+// 7개 Tier1 프레임워크의 표시명 (display-cased).
+const FW_DISPLAY = {
+    maestro: "Maestro",
+    detox: "Detox",
+    appium: "Appium",
+    xcuitest: "XCUITest",
+    espresso: "Espresso",
+    playwright: "Playwright",
+    cypress: "Cypress",
+};
+const ALL_FRAMEWORKS = [
+    "maestro", "detox", "appium", "xcuitest", "espresso", "playwright", "cypress",
+];
+function buildTier1(dir) {
+    const detected = detectFrameworks(dir); // used 인 것만
+    const usedSet = new Set(detected.map((d) => d.framework));
+    const frameworks = ALL_FRAMEWORKS.map((fw) => {
+        const used = usedSet.has(fw);
+        const tier2 = fw === "maestro"; // v1: 실제 실행(Tier2) 러너는 Maestro 만.
+        return {
+            name: FW_DISPLAY[fw],
+            status: used ? "active" : "unused",
+            tier2,
+            note: used ? "탐지됨" : "미설정",
+        };
+    });
+    const warnings = [];
+    if (usedSet.size === 0) {
+        warnings.push({ level: "red", text: "테스트 프레임워크 아예 없음 — screen 작업은 ran-pass 도달 불가" });
+    }
+    else {
+        const nonMaestroUsed = [...usedSet].some((f) => f !== "maestro");
+        if (nonMaestroUsed) {
+            warnings.push({
+                level: "orange",
+                text: "실제 실행(Tier2) 가능 = Maestro 뿐. 나머지는 탐지만 가능(시나리오 존재 확인).",
+            });
+        }
+    }
+    return { frameworks, warnings };
+}
+export function buildLedger(dir) {
+    // 매 렌더마다 repo-mtime 메모를 비워 fresh walk 강제 — 장수 서버가 세션 내내 staleness 를
+    // 과소보고(stale-lenient drift)하지 않게. 이 렌더 안의 많은 작업끼리는 여전히 1 walk 로 메모. (F4)
+    clearRepoMtimeMemo();
+    const c = loadChecklist(dir);
+    const ids = new Set(c.tasks.map((t) => t.id));
+    // root = parent 없음 OR parent 가 존재하지 않는 id (orphan) → 트리에서 사라지지 않도록 top-level 로 노출.
+    const roots = c.tasks.filter((t) => t.parent === null || !ids.has(t.parent));
+    return {
+        tier1: buildTier1(dir),
+        groups: roots.map((t) => nodeFor(dir, t, c.tasks, new Set())),
+    };
+}
+// 사람 전용 영상 확인 경로. 작업의 video 증거에 humanVerified+verifiedAt 를 set 하고 영속화한다.
+// MCP/CLI(Claude 접근 가능) 경로가 아니다 — 브라우저 버튼만 호출. (F1)
+export function verifyVideo(dir, taskId) {
+    const c = loadChecklist(dir);
+    const t = getTask(c, taskId);
+    if (!t)
+        return { ok: false, reason: `unknown task ${taskId}` };
+    // VALID video 를 우선 대상으로 한다 — authoritative()/displayEvidence 가 humanVerified 를
+    // VALID video 에서만 읽으므로, stale video 를 stamp 하면 UI 가 반응하지 않는다. 유효 video 가
+    // 없으면 첫 video 로 폴백(아직 검증 전이라도 사람이 확인할 수 있게).
+    // validEvidenceEntries 는 별도 로드본이라 참조가 다르다 — 안정 키(path+runAt+hash)로 대조한다.
+    const key = (e) => `${e.path}|${e.runAt}|${e.hash}`;
+    const validVideoKeys = new Set(validEvidenceEntries(dir, taskId).filter((e) => e.type === "video").map(key));
+    let idx = t.evidence.findIndex((e) => e.type === "video" && validVideoKeys.has(key(e)));
+    if (idx < 0)
+        idx = t.evidence.findIndex((e) => e.type === "video");
+    if (idx < 0)
+        return { ok: false, reason: `no video evidence on ${taskId}` };
+    const verifiedAt = new Date().toISOString();
+    const evidence = t.evidence.map((e, i) => i === idx ? { ...e, humanVerified: true, verifiedAt } : e);
+    saveChecklist(dir, updateTask(c, taskId, { evidence }));
+    return { ok: true };
+}
+// 사람 전용 signoff 경로. human-gate 작업을 done 으로 만들고 신뢰 marker(signedAt)를 영속화한다.
+// MCP/CLI(Claude 접근 가능) 경로가 아니다 — 브라우저 '내가 확인함' 버튼만 호출. F2가 signedAt 을 존중한다. (F2)
+export function signoffTask(dir, id, signedAt = new Date().toISOString()) {
+    const c = loadChecklist(dir);
+    const t = getTask(c, id);
+    if (!t)
+        return { ok: false, id, reason: `unknown task ${id}` };
+    saveChecklist(dir, updateTask(c, id, { status: "done", signedAt }));
+    return { ok: true, id, status: "done", signedAt };
+}
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".json": "application/json; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "application/xml; charset=utf-8",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+};
+function readBody(req) {
+    return new Promise((resolve) => {
+        let data = "";
+        req.on("data", (c) => (data += c));
+        req.on("end", () => resolve(data));
+    });
+}
+export function startDashboard(dir, port = 4477) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const indexPath = join(here, "web", "index.html");
+    const server = createServer(async (req, res) => {
+        const url = (req.url || "/").split("?")[0];
+        if (req.method === "GET" && (url === "/" || url === "/index.html")) {
+            if (!existsSync(indexPath)) {
+                res.writeHead(404);
+                res.end("index.html not found");
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(readFileSync(indexPath));
+            return;
+        }
+        if (req.method === "GET" && url === "/api/checklist") {
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify(buildLedger(dir)));
+            return;
+        }
+        if (req.method === "POST" && url === "/api/signoff") {
+            const body = await readBody(req);
+            let id = "";
+            try {
+                id = JSON.parse(body || "{}").id;
+            }
+            catch { /* ignore */ }
+            const out = signoffTask(dir, id);
+            res.writeHead(out.ok === false ? 400 : 200, { "content-type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify(out));
+            return;
+        }
+        // 사람 전용 영상 확인 — 브라우저 버튼만 호출. Claude(MCP/CLI) 경로 없음. (F1)
+        if (req.method === "POST" && url === "/api/verify-video") {
+            const body = await readBody(req);
+            let id = "";
+            try {
+                id = JSON.parse(body || "{}").id;
+            }
+            catch { /* ignore */ }
+            const out = verifyVideo(dir, id);
+            res.writeHead(out.ok === false ? 400 : 200, { "content-type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify(out));
+            return;
+        }
+        if (req.method === "GET" && url.startsWith("/artifacts/")) {
+            const rel = decodeURIComponent(url.slice("/artifacts/".length));
+            const base = join(dir, ".prooflist", "artifacts");
+            const target = normalize(join(base, rel));
+            if (!target.startsWith(base + (base.endsWith("/") ? "" : "/"))) {
+                res.writeHead(403);
+                res.end("forbidden");
+                return;
+            }
+            if (!existsSync(target) || !statSync(target).isFile()) {
+                res.writeHead(404);
+                res.end("not found");
+                return;
+            }
+            res.writeHead(200, { "content-type": CONTENT_TYPES[extname(target).toLowerCase()] || "application/octet-stream" });
+            res.end(readFileSync(target));
+            return;
+        }
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("not found");
+    });
+    // localhost 전용 바인드 — /api/signoff·/artifacts 를 LAN 에 노출하지 않는다.
+    server.listen(port, "127.0.0.1", () => {
+        const addr = server.address();
+        const p = typeof addr === "object" && addr ? addr.port : port;
+        console.log(`prooflist dashboard → http://localhost:${p}`);
+    });
+    return server;
+}
+// 바이너리로 실행될 때만 자동 기동.
+if (isMainModule(import.meta.url))
+    startDashboard(process.cwd());