prooflist 0.1.0

package/dist/detect.js

@@ -0,0 +1,43 @@
+import { adapters } from "./adapters/index.js";
+// Tier1: 전 어댑터의 detect를 돌려 실제로 쓰는(used) 것만 보고. (§5.2)
+export function detectFrameworks(repoRoot) {
+    return adapters.map((a) => a.detect(repoRoot)).filter((d) => d.used);
+}
+// 강도 순서, 약→강. (§6.1)
+export const STRENGTH_ORDER = [
+    "none",
+    "scenario",
+    "ran-pass",
+    "visual-verified",
+];
+// 단일 증거의 강도. PURE-DERIVE: 저장된 ev.strength 와 ev.note(watch 힌트)는 절대 신뢰/사용하지
+// 않고, 검증 가능한 사실(type/tier/passed/humanVerified)에서만 도출한다. operator-Claude가
+// strength:"visual-verified"를 위조하거나 watch 분석으로 자기-등급을 올릴 수 없게 하는 F1 방어. (§6.1)
+//
+// 주의: strength는 v1에서 **표시/자문용(advisory)** — 게이트(canComplete/checkIntegrity)는 strength를
+// 보지 않고 isEvidenceValid(passed+fresh+hash+exists)로만 강제한다. §6.1의 kind별 최소 강도 강제는
+// 결정론 게이트를 바꿔야 하므로(3차 개정 불변식: 게이트 불변) 후속 단계. 이 함수가 load-bearing이라고
+// 가정하지 말 것.
+export function evidenceStrength(ev) {
+    if (ev.type === "video" && ev.humanVerified === true)
+        return "visual-verified";
+    if (ev.type === "video")
+        return "ran-pass"; // 실행 녹화이나 아직 사람 확인 전
+    if (ev.tier === "run" && ev.passed === true)
+        return "ran-pass";
+    if (ev.tier === "run")
+        return "scenario"; // 실행했으나 실패 — 시나리오는 존재
+    if (ev.tier === "detect")
+        return "scenario";
+    return "none";
+}
+// 증거 묶음에서 가장 강한 강도, 비어 있으면 none. (§6.1)
+export function bestStrength(evidence) {
+    let best = "none";
+    for (const ev of evidence) {
+        const s = evidenceStrength(ev);
+        if (STRENGTH_ORDER.indexOf(s) > STRENGTH_ORDER.indexOf(best))
+            best = s;
+    }
+    return best;
+}

package/dist/evidence.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+export function stateHash(flowContent, codeFingerprint) {
+    return createHash("sha256").update(flowContent).update("\0").update(codeFingerprint).digest("hex");
+}
+export function isEvidenceValid(ev, f) {
+    if (!ev.passed)
+        return { ok: false, reason: "evidence did not pass" };
+    if (!f.fileExists)
+        return { ok: false, reason: "artifact file missing" };
+    if (ev.hash !== f.expectedHash)
+        return { ok: false, reason: "artifact hash mismatch (stale or reused)" };
+    if (new Date(ev.runAt).getTime() < new Date(f.latestCodeChange).getTime())
+        return { ok: false, reason: "artifact older than latest code change" };
+    return { ok: true };
+}

package/dist/gate.js

@@ -0,0 +1,37 @@
+import { kindMismatch } from "./classify.js";
+// pl done 시 단일 작업 완료 가능 판정.
+export function canComplete(task, f) {
+    if (task.kind === "human-gate")
+        return {
+            ok: false,
+            reason: "human-gate task cannot be completed by Claude",
+            nextAction: `Ask 승기 to sign off task '${task.id}' via the dashboard '내가 확인함' button (Claude cannot sign off).`,
+        };
+    if (task.kind === "screen" && !f.hasValidEvidence)
+        return {
+            ok: false,
+            reason: "screen task has no valid passing Maestro artifact",
+            nextAction: `Run 'pl test ${task.id}' and attach a passing Maestro artifact before claiming done.`,
+        };
+    return { ok: true };
+}
+// pl gate --check (Stop 훅) 시 전체 무결성 검사.
+// isValidEvidence(taskId): 해당 작업에 유효 아티팩트가 있는지 — CLI가 fs로 채워 주입.
+export function checkIntegrity(c, isValidEvidence) {
+    const out = [];
+    for (const t of c.tasks) {
+        if (t.status !== "done")
+            continue;
+        // signedAt is set only by the dashboard human-only signoff route; like all checklist.json state it is F5-hand-editable (documented limit — full closure needs the §11 isolated verifier).
+        if (t.kind === "human-gate" && !t.signedAt)
+            out.push({ taskId: t.id, rule: "F2", reason: "human-gate marked done without human signoff",
+                nextAction: `Revert task '${t.id}' to needs-human; only 승기 can sign it off (via the dashboard).` });
+        if (t.kind === "screen" && !isValidEvidence(t.id))
+            out.push({ taskId: t.id, rule: "F1", reason: "screen task done without valid Maestro artifact",
+                nextAction: `Run 'pl test ${t.id}' to produce passing evidence, or revert it.` });
+        if (kindMismatch(t))
+            out.push({ taskId: t.id, rule: "F3", reason: "logic task touched UI files (kind downgraded)",
+                nextAction: `Set kind of '${t.id}' to screen ('pl set-kind ${t.id} screen') and run 'pl test ${t.id}'.` });
+    }
+    return out;
+}

package/dist/hook.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+import { isMainModule } from "./ismain.js";
+// Claude Code Stop 훅 계약: 차단하려면 stdout에 {"decision":"block","reason":...} 출력.
+export function gateHook(dir) {
+    const out = runCli(["gate", "--check"], dir);
+    if (out.ok)
+        return { continue: true };
+    const lines = out.violations.map((v) => `- [${v.rule}] ${v.taskId}: ${v.reason}\n  → ${v.nextAction}`);
+    return {
+        decision: "block",
+        reason: `ProofList gate blocked turn end. Unverified work:\n${lines.join("\n")}`,
+    };
+}
+if (isMainModule(import.meta.url)) {
+    console.log(JSON.stringify(gateHook(process.cwd())));
+    process.exit(0); // 차단은 decision 필드로, 종료코드 아님
+}

package/dist/init.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { saveChecklist, emptyChecklist } from "./store.js";
+import { isMainModule } from "./ismain.js";
+const HOOK_CMD = "npx prooflist-hook";
+const GITIGNORE_ENTRY = ".prooflist/artifacts/";
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+// .claude/settings.json 변이를 메모리에서 준비한다 (Stop 훅 머지). 파일은 쓰지 않는다.
+// 반환: { prepared } = 쓸 준비된 객체+신규여부, 또는 { reason } = 깨끗한 실패(덮어쓰지 않음).
+function prepareSettings(dir) {
+    const sp = join(dir, ".claude/settings.json");
+    let settings = {};
+    if (existsSync(sp)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(sp, "utf8"));
+        }
+        catch {
+            return {
+                reason: ".claude/settings.json is not valid JSON; fix it and re-run 'pl init' (refusing to overwrite).",
+            };
+        }
+        if (!isPlainObject(parsed)) {
+            return { reason: ".claude/settings.json is not a JSON object; refusing to overwrite." };
+        }
+        settings = parsed;
+    }
+    if (!isPlainObject(settings.hooks)) {
+        if (settings.hooks === undefined)
+            settings.hooks = {};
+        else
+            return { reason: ".claude/settings.json 'hooks' is not an object; refusing to overwrite." };
+    }
+    const hooks = settings.hooks;
+    if (hooks.Stop === undefined)
+        hooks.Stop = [];
+    else if (!Array.isArray(hooks.Stop))
+        return { reason: ".claude/settings.json 'hooks.Stop' is not an array; refusing to overwrite." };
+    const stop = hooks.Stop;
+    const already = stop.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => h?.command === HOOK_CMD));
+    if (!already)
+        stop.push({ hooks: [{ type: "command", command: HOOK_CMD }] });
+    return { prepared: { path: sp, config: settings, added: !already } };
+}
+// .mcp.json 변이를 메모리에서 준비한다 (prooflist stdio 서버 머지). 파일은 쓰지 않는다.
+// settings.json과 동일한 가드된-파스 견고성.
+function prepareMcpJson(dir) {
+    const mp = join(dir, ".mcp.json");
+    let config = {};
+    if (existsSync(mp)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(mp, "utf8"));
+        }
+        catch {
+            return { reason: ".mcp.json is not valid JSON; fix it and re-run 'pl init' (refusing to overwrite)." };
+        }
+        if (!isPlainObject(parsed)) {
+            return { reason: ".mcp.json is not a JSON object; refusing to overwrite." };
+        }
+        config = parsed;
+    }
+    if (config.mcpServers === undefined)
+        config.mcpServers = {};
+    else if (!isPlainObject(config.mcpServers))
+        return { reason: ".mcp.json 'mcpServers' is not an object; refusing to overwrite." };
+    const servers = config.mcpServers;
+    const already = servers.prooflist !== undefined;
+    if (!already)
+        servers.prooflist = { type: "stdio", command: "npx", args: ["prooflist-mcp"] };
+    return { prepared: { path: mp, config, added: !already } };
+}
+function writePrepared(p) {
+    writeFileSync(p.path, JSON.stringify(p.config, null, 2) + "\n");
+}
+// .gitignore에 .prooflist/artifacts/ 를 보장한다 (스샷·영상·junit은 git 추적 제외;
+// checklist.json은 추적). 멱등 — 이미 있으면 건드리지 않는다. 없으면 생성/추가.
+function ensureGitignore(dir) {
+    const gp = join(dir, ".gitignore");
+    let body = "";
+    if (existsSync(gp)) {
+        body = readFileSync(gp, "utf8");
+        const has = body
+            .split(/\r?\n/)
+            .some((l) => l.trim() === GITIGNORE_ENTRY || l.trim() === ".prooflist/artifacts");
+        if (has)
+            return false;
+    }
+    const prefix = body.length > 0 && !body.endsWith("\n") ? "\n" : "";
+    const block = `${prefix}\n# ProofList: evidence artifacts (screenshots/videos/junit) — not tracked; checklist.json IS tracked\n${GITIGNORE_ENTRY}\n`;
+    writeFileSync(gp, body + block);
+    return true;
+}
+export function initProject(dir) {
+    // 1) .prooflist 스캐폴드 (멱등 — 먼저 해도 안전).
+    mkdirSync(join(dir, ".prooflist/artifacts"), { recursive: true });
+    if (!existsSync(join(dir, ".prooflist/checklist.json")))
+        saveChecklist(dir, emptyChecklist());
+    mkdirSync(join(dir, ".claude"), { recursive: true });
+    // 2) BOTH 설정 파일을 검증/준비만 한다 — 둘 다 통과하기 전엔 아무것도 쓰지 않는다(부분 와이어링 금지).
+    const settings = prepareSettings(dir);
+    if ("reason" in settings)
+        return { ok: false, reason: settings.reason };
+    const mcp = prepareMcpJson(dir);
+    if ("reason" in mcp)
+        return { ok: false, reason: mcp.reason };
+    // 3) 둘 다 검증 성공한 뒤에만 쓴다.
+    writePrepared(settings.prepared);
+    writePrepared(mcp.prepared);
+    // 4) .gitignore에 artifacts 제외 보장 (멱등, append-only — JSON 파손 위험 없음).
+    const gitignored = ensureGitignore(dir);
+    return { ok: true, wired: settings.prepared.added, mcpWired: mcp.prepared.added, gitignored };
+}
+if (isMainModule(import.meta.url)) {
+    console.log(JSON.stringify(initProject(process.cwd())));
+}

package/dist/ismain.js

@@ -0,0 +1,18 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+// "이 모듈이 직접 실행됐나?" 판정 — npm bin **심볼릭 링크**로 실행돼도 동작한다.
+// process.argv[1].endsWith("x.js")는 bin 심링크(예: /opt/homebrew/bin/prooflist-init)로
+// 실행하면 argv[1]이 심링크 경로라 false가 되어 엔트리포인트가 안 돈다. 그래서
+// argv[1]을 realpath로 풀어 import.meta.url(이미 실제 경로)과 비교한다. 테스트에서
+// import할 때는 argv[1]이 vitest 러너라 false → 부수효과 없음.
+export function isMainModule(metaUrl) {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return metaUrl === pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// ProofList MCP 서버 — 게이트 코어를 first-class 툴로 노출.
+//
+// 보안 척추(절대 깨지 않음):
+//  - MCP = 편의 기능이지 ENFORCEMENT가 아니다. enforcement는 Stop 훅(pl gate --check)에 남는다.
+//  - signoff/init/ui 는 절대 MCP 툴로 노출하지 않는다 (노출된 툴 = Claude가 호출 가능한 액션 = F2 구멍).
+//    이 파일은 signoff/init/ui 핸들러·import를 물리적으로 포함하지 않는다.
+//  - 게이트 판정 툴은 runCli(...)에 위임한다 — CLI와 동일한 코드/판정.
+//
+// 단위 테스트 가능한 코어(listTools)는 MCP SDK를 import하지 않는다.
+// SDK는 파일 끝의 가드된 stdio 진입점에서만 사용한다.
+import { z } from "zod";
+import { runCli } from "./cli.js";
+import { loadChecklist, saveChecklist, planTasks } from "./store.js";
+import { isMainModule } from "./ismain.js";
+// 정확히 이 6개 안전 툴만 — signoff/init/ui는 절대 없음.
+export function listTools() {
+    return [
+        {
+            name: "pl_plan",
+            description: "Fold a task tree into the checklist (shared planTasks core).",
+            inputSchema: {
+                tasks: z
+                    .array(z.object({
+                    id: z.string(),
+                    title: z.string(),
+                    kind: z.enum(["logic", "screen", "human-gate"]).optional(),
+                    parent: z.string().nullable().optional(),
+                    platform: z.enum(["ios", "android", "web", "cli"]).optional(),
+                    touchedPaths: z.array(z.string()).optional(),
+                }))
+                    .describe("Task specs to add (missing fields get sensible defaults)."),
+            },
+            handler: (args, dir) => {
+                const tasks = args.tasks ?? [];
+                const c = loadChecklist(dir);
+                // planTasks는 순수 — addTask가 중복 id에 throw하면 아무것도 저장되지 않는다(스토어 무손상).
+                try {
+                    const next = planTasks(c, tasks);
+                    saveChecklist(dir, next);
+                    return { ok: true, added: tasks.length };
+                }
+                catch (e) {
+                    return {
+                        ok: false,
+                        reason: e?.message ?? String(e),
+                        nextAction: "Use unique task ids; check 'pl_status' for existing ids before planning.",
+                    };
+                }
+            },
+        },
+        {
+            name: "pl_start",
+            description: "Mark a task in_progress.",
+            inputSchema: { taskId: z.string() },
+            handler: (args, dir) => runCli(["start", args.taskId], dir),
+        },
+        {
+            name: "pl_test",
+            description: "Run/attach evidence for a task (gate core).",
+            inputSchema: { taskId: z.string() },
+            handler: (args, dir) => runCli(["test", args.taskId], dir),
+        },
+        {
+            name: "pl_done",
+            description: "Attempt to complete a task — gate core decides (F1/F2 enforced).",
+            inputSchema: { taskId: z.string() },
+            handler: (args, dir) => runCli(["done", args.taskId], dir),
+        },
+        {
+            name: "pl_status",
+            description: "Report checklist status and rollups.",
+            inputSchema: {},
+            handler: (_args, dir) => runCli(["status"], dir),
+        },
+        {
+            name: "pl_gate",
+            description: "Run the integrity gate (pl gate --check) — same verdict as the Stop hook.",
+            inputSchema: {},
+            handler: (_args, dir) => runCli(["gate", "--check"], dir),
+        },
+    ];
+}
+// ── 가드된 stdio 진입점 (SDK는 여기서만 import) ─────────────────────────────
+// stdio MCP 서버는 절대 stdout에 쓰면 안 된다(JSON-RPC 파손) — 로그는 stderr만.
+if (isMainModule(import.meta.url)) {
+    (async () => {
+        const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+        const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+        const server = new McpServer({ name: "prooflist", version: "0.1.0" });
+        for (const t of listTools()) {
+            server.registerTool(t.name, { description: t.description, inputSchema: t.inputSchema }, async (args) => {
+                const r = t.handler(args, process.cwd());
+                return {
+                    content: [{ type: "text", text: JSON.stringify(r) }],
+                    structuredContent: r,
+                };
+            });
+        }
+        await server.connect(new StdioServerTransport());
+        console.error("prooflist MCP server connected (stdio)");
+    })().catch((e) => {
+        console.error("prooflist MCP server failed:", e);
+        process.exit(1);
+    });
+}

package/dist/runner.js

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { stateHash } from "./evidence.js";
+export async function runMaestro(o) {
+    const result = await o.exec(o.taskId);
+    const runAt = o.runAt ?? new Date().toISOString();
+    return {
+        type: "maestro",
+        path: `${o.taskId}/${runAt.replace(/[:.]/g, "-")}`,
+        runAt,
+        passed: result.code === 0,
+        hash: stateHash(o.flowContent, o.codeFingerprint),
+        framework: "maestro",
+        tier: "run",
+        // strength는 저장하지 않는다 — evidenceStrength(detect.ts)가 도출한다. 저장하면
+        // "저장된 strength 불신" 원칙(F1)과 충돌하고 도출값과 어긋날 수 있다.
+    };
+}
+// 영상 증거 팩토리(기기 불필요). type:"video", tier:"run", passed:true 로 만들되 strength·humanVerified
+// 는 절대 set하지 않는다 — strength는 evidenceStrength가 도출하고, humanVerified는 이후 사람 확인 경로만
+// set한다. 따라서 갓 캡처한 영상은 ran-pass로 도출되고, 사람이 확인해야 visual-verified가 된다. (§6.1, F1)
+export function makeVideoEvidence(o) {
+    const runAt = o.runAt ?? new Date().toISOString();
+    return {
+        type: "video",
+        path: o.videoPath,
+        runAt,
+        passed: true,
+        hash: stateHash(o.flowContent, o.codeFingerprint),
+        framework: "maestro",
+        tier: "run",
+    };
+}
+// Maestro Tier1 탐지: .maestro/ 디렉터리의 *.yaml. detect.ts 레지스트리가 재사용. (§5.2)
+export function detectMaestro(repoRoot) {
+    const dir = join(repoRoot, ".maestro");
+    let scenarioFiles = [];
+    if (existsSync(dir)) {
+        try {
+            scenarioFiles = readdirSync(dir)
+                .filter((f) => /\.ya?ml$/.test(f))
+                .map((f) => join(dir, f));
+        }
+        catch {
+            scenarioFiles = [];
+        }
+    }
+    return { framework: "maestro", used: scenarioFiles.length > 0, scenarioFiles };
+}
+export const maestroAdapter = {
+    framework: "maestro",
+    detect: detectMaestro,
+    run: (taskId, exec) => runMaestro({ taskId, flowContent: "", codeFingerprint: "", exec }),
+};

package/dist/store.js

@@ -0,0 +1,54 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+export const CHECKLIST_PATH = ".prooflist/checklist.json";
+export const emptyChecklist = () => ({ version: 1, tasks: [] });
+export function loadChecklist(dir) {
+    const p = join(dir, CHECKLIST_PATH);
+    if (!existsSync(p))
+        return emptyChecklist();
+    return JSON.parse(readFileSync(p, "utf8"));
+}
+export function saveChecklist(dir, c) {
+    const p = join(dir, CHECKLIST_PATH);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(c, null, 2) + "\n");
+}
+export const getTask = (c, id) => c.tasks.find((t) => t.id === id);
+export function addTask(c, t) {
+    if (getTask(c, t.id))
+        throw new Error(`duplicate task id: ${t.id}`);
+    return { ...c, tasks: [...c.tasks, t] };
+}
+// pl_plan 공유 코어 — 각 spec을 기존 addTask로 폴드해 새 Checklist를 만든다(순수).
+// 누락 필드는 합리적 기본값으로 채운다. (CLI에는 plan 명령이 없는 알려진 단순화 — MCP가 store를 통해 직접 사용.)
+export function planTasks(c, specs) {
+    return specs.reduce((acc, spec) => {
+        const task = {
+            parent: null,
+            kind: "logic",
+            kindLocked: false,
+            status: "todo",
+            platform: "cli",
+            touchedPaths: [],
+            evidence: [],
+            ...spec,
+        };
+        return addTask(acc, task);
+    }, c);
+}
+export function setStatus(c, id, status) {
+    return { ...c, tasks: c.tasks.map((t) => (t.id === id ? { ...t, status } : t)) };
+}
+export function updateTask(c, id, patch) {
+    return { ...c, tasks: c.tasks.map((t) => (t.id === id ? { ...t, ...patch } : t)) };
+}
+const childrenOf = (c, id) => c.tasks.filter((t) => t.parent === id);
+export function rollupPercent(c, id) {
+    const kids = childrenOf(c, id);
+    if (kids.length === 0) {
+        const t = getTask(c, id);
+        return t?.status === "done" ? 100 : 0;
+    }
+    const sum = kids.reduce((acc, k) => acc + rollupPercent(c, k.id), 0);
+    return Math.round(sum / kids.length);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.js

@@ -0,0 +1,88 @@
+import { execSync } from "node:child_process";
+import { existsSync, statSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+export function codeFingerprint(dir) {
+    try {
+        const head = execSync("git rev-parse HEAD", { cwd: dir }).toString().trim();
+        const dirty = execSync("git status --porcelain", { cwd: dir }).toString().trim();
+        return `${head}:${dirty.length}`;
+    }
+    catch {
+        return "no-git";
+    }
+}
+// repo의 최신 소스 파일 mtime(ms). touchedPaths가 비었거나 모두 사라진 작업의
+// freshness 기준선으로 쓰인다 — epoch(0) 면죄부 대신 "가장 최근 코드 변경" 보수 기준. (F4)
+// 가지치기: node_modules/.git/dist/build/.next/.prooflist/artifacts (아티팩트 자신의 mtime은 코드변경이 아님).
+// 메모이즈: 한 프로세스(예: pl gate --check 1회) 안에서 dir당 1번만 walk. CLI/훅은 매 호출이 새 프로세스라 stale 우려 없음.
+const repoMtimeMemo = new Map();
+export function repoLatestMtime(dir) {
+    const cached = repoMtimeMemo.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next"]);
+    let max = 0;
+    const rec = (cur, depth) => {
+        if (depth > 6)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(cur);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = join(cur, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (SKIP.has(name))
+                    continue;
+                // .prooflist/artifacts 가지치기 — 아티팩트 자신의 mtime이 "코드 변경"으로 잡히지 않게.
+                if (name === "artifacts" && full.endsWith(join(".prooflist", "artifacts")))
+                    continue;
+                rec(full, depth + 1);
+            }
+            else {
+                if (st.mtimeMs > max)
+                    max = st.mtimeMs;
+            }
+        }
+    };
+    rec(dir, 0);
+    repoMtimeMemo.set(dir, max);
+    return max;
+}
+// 메모 무효화. 장수 서버(대시보드)는 매 렌더마다 호출해 fresh walk 를 강제한다 —
+// 안 그러면 서버 시작 시점의 repo-latest mtime 을 세션 내내 캐시해 staleness 를 과소보고(stale-lenient)할 수 있다.
+// CLI/훅은 매 호출이 새 프로세스라 영향 없음 (프로세스당 1 walk 메모 이점 유지).
+export function clearRepoMtimeMemo() {
+    repoMtimeMemo.clear();
+}
+export function latestCodeChange(dir, paths) {
+    let max = 0;
+    for (const p of paths) {
+        const abs = join(dir, p);
+        if (existsSync(abs))
+            max = Math.max(max, statSync(abs).mtimeMs);
+    }
+    // touchedPaths가 무언가로 해석됐으면 그대로(기존 동작 불변). 아니면 repo-latest mtime으로
+    // 폴백 — 그것도 0(빈 repo)이면 기존처럼 epoch. (F4: 빈 touchedPaths의 freshness 면죄부 차단)
+    if (max > 0)
+        return new Date(max).toISOString();
+    const fallback = repoLatestMtime(dir);
+    return new Date(fallback || 0).toISOString();
+}
+export function flowContent(dir, taskId) {
+    const p = join(dir, `.maestro/${taskId}.yaml`);
+    return existsSync(p) ? readFileSync(p, "utf8") : "";
+}
+export function artifactExists(dir, relPath) {
+    return existsSync(join(dir, ".prooflist/artifacts", relPath));
+}