@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/lanes.js

@@ -0,0 +1,571 @@
+import { keepLines, readKeep } from "../playtest/keep.js";
+import { laneDefects, readLooks } from "../flow/look.js";
+import { readGameBar } from "../owner/bar.js";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync, writeFileSync, appendFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ensurePipeline } from "./next.js";
+import { evaluate } from "../pipeline/pipeline.js";
+import { readProgress, appendEntry, nextCard, PROGRESS_FILE } from "../progress/progress.js";
+import { planAgreement, readFlow } from "../flow/flow.js";
+import { readDecisions, setDecisionStatus } from "../memory/decisions.js";
+import { settlePicks } from "./pick.js";
+import { briefPath, extraGates, laneDir, laneGame, laneView, LANES_DIR, logMaking, makeLane, makingSection, openDecisionsFor, readCosts, readLanes, readMaking, renderBrief, renderVerifyBrief, roomIds, spentUsd, STAGE_LANES, verifyPath, WORKTREES_DIR, writeLanes, } from "../lanes/lanes.js";
+import { branchOf, git, headOf, runGate } from "../lanes/gate.js";
+import { laneOf } from "../lanes/where.js";
+import { resolveUnion } from "../lanes/union.js";
+import { ui } from "../ui.js";
+export const LANES_SUBCOMMANDS = ['status', 'plan', 'brief', 'start', 'checkpoint', 'done', 'gate', 'sync', 'verdict', 'merge', 'report', 'cap', 'drop'];
+const T = 'npx @funpixel/tools';
+const MAX_LANES = 6;
+export async function lanes(opts, io = console) {
+    const u = ui(io, 'lanes');
+    const here = resolve(opts.dir ?? '.');
+    const root = laneOf(here)?.home ?? here;
+    const now = opts.now ?? (() => new Date());
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        u.error(`${root} is not a game folder (no funpixel.json)`, '--dir <game>');
+        return EXIT.error;
+    }
+    try {
+        if (opts.sub === 'plan')
+            return plan(root, opts, u, io, now());
+        const f = readLanes(root);
+        if (!f) {
+            if (opts.json)
+                io.log(JSON.stringify({ lanes: [] }));
+            else
+                u.summary('not_observed', `no lanes yet: \`${T} lanes plan\` splits the stage the game is at into lanes`);
+            return EXIT.not_observed;
+        }
+        if (opts.sub === 'status')
+            return status(root, f, opts, u, io, now());
+        if (opts.sub === 'report')
+            return report(root, f, opts, u, io, now());
+        if (opts.sub === 'start' && opts.all) {
+            let code = EXIT.pass;
+            const planned = f.lanes.filter((l) => l.state === 'planned');
+            if (!planned.length) {
+                u.summary('not_observed', 'no planned lane to start');
+                return EXIT.not_observed;
+            }
+            const calls = [];
+            for (const l of planned) {
+                const r = start(root, readLanes(root), l.id, opts, u, now());
+                if (r.code !== EXIT.pass)
+                    code = r.code;
+                else
+                    calls.push(r.call);
+            }
+            if (!opts.json)
+                hostCalls(u, root, calls);
+            return code;
+        }
+        const id = opts.args[0];
+        const lane = f.lanes.find((l) => l.id === id);
+        if (!lane) {
+            u.error(id ? `no lane ${id}` : 'which lane?', `${T} lanes lists them (${f.lanes.map((l) => l.id).join(', ')})`);
+            return EXIT.error;
+        }
+        switch (opts.sub) {
+            case 'brief': {
+                const p = writeBriefs(root, f, lane);
+                if (opts.json)
+                    io.log(JSON.stringify({ brief: p, carried: lane.carried ?? [] }));
+                else
+                    io.log(readFileSync(p, 'utf8'));
+                return EXIT.pass;
+            }
+            case 'start': {
+                const r = start(root, f, id, opts, u, now());
+                if (r.code === EXIT.pass && !opts.json)
+                    hostCalls(u, root, [r.call]);
+                return r.code;
+            }
+            case 'checkpoint': return checkpoint(root, f, lane, opts, u, now());
+            case 'done':
+            case 'gate': return await gate(root, f, lane, opts, u, io, now());
+            case 'sync': return sync(root, f, lane, u, now());
+            case 'verdict': return verdict(root, f, lane, opts, u, now());
+            case 'merge': return merge(root, f, lane, opts, u, io, now());
+            case 'cap':
+            case 'drop': return owner(root, f, lane, opts, u, now());
+        }
+        return EXIT.error;
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+}
+const save = (root, f, lane) => { const g = readLanes(root) ?? f; g.lanes = g.lanes.map((l) => (l.id === lane.id ? lane : l)); writeLanes(root, g); };
+const isRepo = (root) => git(['rev-parse', '--show-toplevel'], root).ok;
+const identity = (root) => (git(['config', 'user.email'], root).out ? [] : ['-c', 'user.name=funtools lanes', '-c', 'user.email=lanes@funtools.invalid']);
+function plan(root, opts, u, io, now) {
+    if (readFlow(root)) {
+        const a = planAgreement(root);
+        if (!a.agreed) {
+            u.summary('fail', `the plan is not agreed yet (${a.says}): lanes build, and building waits for the owner's yes`);
+            u.line(`next: ${T} flow`, 1);
+            return EXIT.fail;
+        }
+    }
+    const [p] = ensurePipeline(root, now);
+    let stage = opts.stage ?? '';
+    if (!stage) {
+        try {
+            stage = evaluate(root, p, null).current?.stage.id ?? 'slice';
+        }
+        catch {
+            stage = 'slice';
+        }
+    }
+    if (!p.stages.some((s) => s.id === stage)) {
+        u.error(`no stage ${stage} in design/pipeline.json`, `--stage one of ${p.stages.map((s) => s.id).join(', ')}`);
+        return EXIT.error;
+    }
+    const list = (d) => { try {
+        return readdirSync(d);
+    }
+    catch {
+        return [];
+    } };
+    let ids = (opts.lanes ? opts.lanes.split(',') : STAGE_LANES[stage] ?? ['play', 'look', 'audio']).map((x) => x.trim()).filter(Boolean);
+    ids = ids.flatMap((x) => (x === 'rooms' ? roomIds(root, list).map((r) => `room-${r}`) : [x]));
+    ids = [...new Set(ids)];
+    if (ids.length > MAX_LANES) {
+        u.error(`${ids.length} lanes: at most ${MAX_LANES} at once (one integrator merges them)`, '--lanes a,b,c');
+        return EXIT.error;
+    }
+    const cap = opts.cap === undefined ? undefined : Number(opts.cap);
+    const box = opts.timebox === undefined ? undefined : Number(opts.timebox);
+    if (cap !== undefined && !(cap >= 0)) {
+        u.error('--cap is dollars per lane', '--cap 5');
+        return EXIT.error;
+    }
+    if (box !== undefined && !(Number.isInteger(box) && box > 0)) {
+        u.error('--timebox is whole minutes', '--timebox 240');
+        return EXIT.error;
+    }
+    const old = readLanes(root);
+    const keep = (old?.lanes ?? []).filter((l) => l.state !== 'planned');
+    const extra = extraGates(root, opts.has ?? (() => false));
+    const fresh = [];
+    for (const id of ids) {
+        if (keep.some((l) => l.id === id && l.state !== 'merged' && l.state !== 'dropped')) {
+            u.item('note', `lane ${id} is already out (${keep.find((l) => l.id === id).state}): kept as it is`);
+            continue;
+        }
+        fresh.push(makeLane(id, stage, keep.length + fresh.length, { cap, timebox: box, extra }));
+    }
+    const f = { version: 1, planned_at: now.toISOString(), lanes: [...keep.filter((l) => !fresh.some((x) => x.id === l.id)), ...fresh] };
+    writeLanes(root, f);
+    for (const l of fresh) {
+        writeBriefs(root, f, l);
+        logMaking(root, { lane: l.id, kind: 'plan', line: `planned on ${stage}: ${l.title}; cap $${l.cap_usd}, ${l.timebox_min} min`, at: now.toISOString() });
+    }
+    const ds = readDecisions(root);
+    const loose = p.notes.filter((n) => n.by === 'owner' && n.status === 'open' && !ds.some((d) => d.from === n.id));
+    if (opts.json) {
+        io.log(JSON.stringify({ stage, lanes: fresh.map((l) => ({ id: l.id, title: l.title, owns: l.owns, cap_usd: l.cap_usd, timebox_min: l.timebox_min, branch: l.branch, worktree: l.worktree, gates: l.gates.map((g) => g.name ?? g.kind), brief: briefPath(root, l.id) })), notes_without_decision: loose.map((n) => n.id) }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`lanes · ${stage} split into ${fresh.length}`);
+    for (const l of fresh) {
+        u.item('pass', `${l.id} · ${l.title}`, `owns ${l.owns.slice(0, 4).join(', ')}${l.owns.length > 4 ? '…' : ''} · $${l.cap_usd} cap · ${l.timebox_min} min · gate: ${l.gates.map((g) => g.name ?? g.kind).join(', ')}`);
+    }
+    for (const n of loose)
+        u.item('warn', `the owner's note ${n.id} has no decision yet: "${n.text.slice(0, 100)}"`, `${T} decide --from ${n.id} (it then reaches the briefs it touches)`);
+    u.summary('pass', `${fresh.length} brief(s) in ${LANES_DIR}/<id>/brief.md`);
+    u.line(`next: ${T} lanes start --all (one checkout each, and the host calls that run them at once)`, 1);
+    return EXIT.pass;
+}
+function writeBriefs(root, f, lane) {
+    const m = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+    const decisions = openDecisionsFor(root, lane);
+    let why = [];
+    try {
+        const [p] = ensurePipeline(root);
+        const st = evaluate(root, p, null).stages.find((x) => x.stage.id === lane.stage);
+        why = (st?.gates ?? []).filter((g) => g.state !== 'met').map((g) => `${st.stage.title}: ${g.gate.kind} — ${g.says}`);
+    }
+    catch { }
+    const before = [
+        ...(lane.gate && !lane.gate.passed ? lane.gate.checks.filter((c) => c.state !== 'pass').map((c) => `the gate refused it (${c.name}): ${c.says}`) : []),
+        ...lane.verdicts.filter((v) => v.says === 'fail').map((v) => `the verifier ${v.by} failed it: ${v.words ?? ''}`),
+    ];
+    const repo = isRepo(root);
+    const text = renderBrief(f, lane, { game: String(m.title ?? m.name ?? 'this game'), home: root, homeBranch: repo ? branchOf(root) : '(no git yet)', base: lane.base ?? (repo ? headOf(root) : null), worktreeAbs: laneGame(root, lane), decisions, why, before, bar: (readGameBar(root)?.lines ?? []).filter((l) => l.verdict === 'applies').map((l) => `${l.text}${l.note ? ` (${l.note})` : ''}`), keep: keepLines(readKeep(root)), look: laneDefects(readLooks(root, f.lanes).filter((l) => l.filed).at(-1) ?? null, lane.id) });
+    mkdirSync(laneDir(root, lane.id), { recursive: true });
+    writeFileSync(briefPath(root, lane.id), text);
+    writeFileSync(verifyPath(root, lane.id), renderVerifyBrief(lane, { worktreeAbs: laneGame(root, lane) }));
+    lane.carried = decisions.map((d) => d.id);
+    save(root, f, lane);
+    return briefPath(root, lane.id);
+}
+function exclude(root) {
+    const r = git(['rev-parse', '--git-common-dir'], root);
+    if (!r.ok)
+        return;
+    const file = join(resolve(root, r.out), 'info', 'exclude');
+    let text = '';
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch { }
+    const prefix = git(['rev-parse', '--show-prefix'], root).out;
+    const want = [`/${prefix}${LANES_DIR}/`, `/${prefix}${WORKTREES_DIR}/`].filter((l) => !text.split('\n').includes(l));
+    if (!want.length)
+        return;
+    mkdirSync(join(file, '..'), { recursive: true });
+    appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}# funtools lanes: control files and checkouts\n${want.join('\n')}\n`);
+}
+function start(root, f, id, opts, u, now) {
+    const lane = f.lanes.find((l) => l.id === id);
+    if (lane.state !== 'planned') {
+        u.item('note', `lane ${id} is ${lane.state}`, `${T} lanes status`);
+        return { code: EXIT.pass, call: callFor(root, lane) };
+    }
+    if (!isRepo(root)) {
+        u.error('lanes need the game in git (each lane is a branch and a checkout)', 'git init, then commit what is there');
+        return { code: EXIT.error, call: '' };
+    }
+    if (!headOf(root)) {
+        u.error('the game has no commit yet', 'commit what is there first');
+        return { code: EXIT.error, call: '' };
+    }
+    exclude(root);
+    const top = git(['rev-parse', '--show-toplevel'], root).out;
+    const prefix = git(['rev-parse', '--show-prefix'], root).out;
+    const wt = join(root, lane.worktree);
+    mkdirSync(join(root, WORKTREES_DIR), { recursive: true });
+    const has = git(['rev-parse', '--verify', '--quiet', `refs/heads/${lane.branch}`], top).ok;
+    const add = git(has ? ['worktree', 'add', wt, lane.branch] : ['worktree', 'add', '-b', lane.branch, wt, 'HEAD'], root);
+    if (!add.ok && !existsSync(wt)) {
+        u.error(`git worktree add failed: ${add.err.split('\n')[0]}`);
+        return { code: EXIT.error, call: '' };
+    }
+    lane.prefix = prefix;
+    const game = laneGame(root, lane);
+    if (existsSync(join(root, 'node_modules')) && !existsSync(join(game, 'node_modules'))) {
+        try {
+            symlinkSync(join(root, 'node_modules'), join(game, 'node_modules'), 'dir');
+        }
+        catch { }
+    }
+    lane.state = 'running';
+    lane.builder = opts.by ?? `lane-${id}`;
+    lane.started_at = now.toISOString();
+    lane.base = headOf(root) ?? undefined;
+    save(root, f, lane);
+    writeBriefs(root, readLanes(root), lane);
+    logMaking(root, { lane: id, kind: 'start', line: `started on ${lane.branch} from ${lane.base?.slice(0, 7)} by ${lane.builder}${lane.carried?.length ? `; carries ${lane.carried.join(', ')}` : ''}`, by: lane.builder, at: now.toISOString() });
+    u.item('pass', `lane ${id}: ${lane.branch} at ${lane.worktree}${top !== root && prefix ? ` (game at ${prefix})` : ''}`, `brief ${briefPath(root, id)}${lane.carried?.length ? ` · carries the owner's ${lane.carried.join(', ')}` : ''}`);
+    return { code: EXIT.pass, call: callFor(root, lane) };
+}
+const callFor = (root, lane) => `Read ${briefPath(root, lane.id)} and do exactly what it says.`;
+export const robinTaskFor = (root, lane) => `You are lane ${lane.id}. Read ${join(root, briefPath(root, lane.id))} and do exactly what it says. You have no shell: each \`npx @funpixel/tools <command>\` in it is the funtools.<command> tool (flow, check, capture, compare, score, assets_gen, …; anything else is funtools.run with the command's words), and every call names dir ${join(root, lane.worktree)}, your checkout. Reply with what plays now, the stills, the spend.`;
+function hostCalls(u, root, calls) {
+    if (!calls.length)
+        return;
+    const ids = calls.map((c) => /lanes\/([^/]+)\/brief\.md/.exec(c)?.[1] ?? '?');
+    u.heading('run them at once');
+    u.line('Claude Code (one message, one Agent call per lane, so they run in parallel):', 1);
+    for (const [i, c] of calls.entries())
+        u.line(`Agent({ subagent_type: "fp:lane", description: "Lane ${ids[i]}", prompt: "${c}" })`, 2);
+    u.line('Codex: one `codex exec` per lane, each in its checkout, with the same line as the prompt. Cursor: one background agent per checkout. Any host: the same line.', 1);
+    const f = readLanes(root);
+    const robin = ids.map((id) => f?.lanes.find((l) => l.id === id)).filter((l) => !!l).slice(0, 4).map((l) => robinTaskFor(root, l));
+    if (robin.length > 1)
+        u.line(`Robin (one agent.delegate call, up to 4 lanes at once): agent.delegate({ tasks: ${JSON.stringify(robin)} })`, 1);
+    u.line(`Then: ${T} lanes status (checkpoints, spend, gates); a verifier per lane once it hands back; ${T} lanes merge <id>.`, 1);
+}
+function checkpoint(root, f, lane, opts, u, now) {
+    const line = opts.line?.replace(/\s+/g, ' ').trim();
+    if (!line) {
+        u.error('a checkpoint says what changed', `${T} lanes checkpoint ${lane.id} --line "<what changed, what you tried>" --shot <still>`);
+        return EXIT.error;
+    }
+    const cost = opts.cost === undefined ? undefined : Number(opts.cost);
+    const minutes = opts.minutes === undefined ? undefined : Number(opts.minutes);
+    if (cost !== undefined && !(cost >= 0)) {
+        u.error('--cost is dollars', '--cost 0.40');
+        return EXIT.error;
+    }
+    const shotAbs = opts.shot ? [resolve(laneGame(root, lane), opts.shot), resolve(opts.shot)].find((p) => existsSync(p)) : undefined;
+    if (opts.shot && !shotAbs)
+        u.item('warn', `${opts.shot} does not exist`, 'a checkpoint\'s still is a capture of the lane\'s build');
+    const rel = shotAbs ? keepStill(root, lane, shotAbs, now) : undefined;
+    logMaking(root, { lane: lane.id, kind: opts.final ? 'final' : 'checkpoint', line, by: opts.by ?? lane.builder, ...(cost !== undefined ? { cost_usd: cost } : {}), ...(minutes !== undefined ? { minutes } : {}), ...(rel ? { evidence: rel } : {}), at: now.toISOString() });
+    if (rel)
+        appendEntry(root, { type: 'card', n: nextCard(readProgress(root)), at: now.toISOString(), kind: 'heartbeat', stage: lane.stage, line: `Lane ${lane.id}: ${line}`, shot: { path: rel, source: 'funtools' }, observed: true });
+    const spent = spentUsd(root, lane.id);
+    u.summary('pass', `lane ${lane.id}: ${opts.final ? 'final report' : 'checkpoint'} logged · $${spent.toFixed(2)} of $${lane.cap_usd.toFixed(2)}${spent > lane.cap_usd ? ' — over the cap: paid calls are refused until the owner raises it' : ''}`);
+    return EXIT.pass;
+}
+const stillsDir = (id) => join('.funtools', 'progress', 'lanes', id);
+function keepStill(root, lane, abs, now) {
+    const rel = join(stillsDir(lane.id), `${now.toISOString().replace(/[:.]/g, '-')}-${basename(abs)}`);
+    mkdirSync(join(root, dirname(rel)), { recursive: true });
+    copyFileSync(abs, join(root, rel));
+    return rel;
+}
+function sweepStills(root, lane) {
+    const prefix = lane.worktree.replace(/\/+$/, '') + '/';
+    let moved = 0;
+    const repoint = (v) => {
+        if (typeof v === 'string' && v.startsWith(prefix)) {
+            const to = join(stillsDir(lane.id), v.slice(prefix.length));
+            if (existsSync(join(root, v))) {
+                mkdirSync(join(root, dirname(to)), { recursive: true });
+                copyFileSync(join(root, v), join(root, to));
+                moved++;
+                return to;
+            }
+            return v;
+        }
+        if (Array.isArray(v))
+            return v.map(repoint);
+        if (v && typeof v === 'object')
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, repoint(x)]));
+        return v;
+    };
+    for (const file of [join(root, PROGRESS_FILE), join(laneDir(root, lane.id), 'making.jsonl')]) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!text.includes(prefix))
+            continue;
+        const out = text.split('\n').map((l) => { if (!l.includes(prefix))
+            return l; try {
+            return JSON.stringify(repoint(JSON.parse(l)));
+        }
+        catch {
+            return l;
+        } });
+        writeFileSync(file, out.join('\n'));
+    }
+    return moved;
+}
+async function gate(root, f, lane, opts, u, io, now) {
+    if (lane.state === 'planned') {
+        u.error(`lane ${lane.id} has not started`, `${T} lanes start ${lane.id}`);
+        return EXIT.error;
+    }
+    if (lane.state === 'merged') {
+        u.summary('pass', `lane ${lane.id} is merged`);
+        return EXIT.pass;
+    }
+    const rec = await runGate(root, f, lane, { now });
+    lane.gate = rec;
+    if (opts.sub === 'done') {
+        lane.state = 'waiting-gate';
+        lane.done_at = now.toISOString();
+    }
+    save(root, f, lane);
+    logMaking(root, { lane: lane.id, kind: rec.passed ? 'gate' : 'refused', line: `gate on ${rec.sha.slice(0, 7)}: ${rec.passed ? 'passed' : `refused — ${rec.checks.filter((c) => c.state !== 'pass').map((c) => `${c.name}: ${c.says}`).join('; ')}`}`, at: now.toISOString() });
+    if (opts.json) {
+        io.log(JSON.stringify({ lane: lane.id, ...rec }, null, 2));
+        return rec.passed ? EXIT.pass : EXIT.fail;
+    }
+    u.heading(`lane ${lane.id} · gate on ${rec.sha.slice(0, 7)}`);
+    for (const c of rec.checks)
+        u.item(c.state === 'pass' ? 'pass' : c.state === 'fail' ? 'fail' : 'not_observed', `${c.name}: ${c.says}`, c.run);
+    if (!rec.passed) {
+        u.summary('fail', `lane ${lane.id} does not pass its gate: fix what it names in the checkout, commit, then ${T} lanes ${opts.sub} ${lane.id}`);
+        return EXIT.fail;
+    }
+    u.summary('pass', `lane ${lane.id}: the gate passes on ${rec.sha.slice(0, 7)}`);
+    u.line(`next: a verifier that did not build it reads ${verifyPath(root, lane.id)} (Claude Code: Agent({ subagent_type: "fp:qa-lead", prompt: "Read ${verifyPath(root, lane.id)} and do exactly what it says." }))`, 1);
+    return EXIT.pass;
+}
+function sync(root, f, lane, u, now) {
+    const wt = join(root, lane.worktree);
+    const branch = branchOf(root);
+    const r = git([...identity(root), 'merge', '--no-edit', branch], wt);
+    const conflicts = r.ok ? [] : git(['diff', '--name-only', '--diff-filter=U'], wt).out.split('\n').filter(Boolean);
+    const unioned = conflicts.length && settleUnion(wt, conflicts) && git([...identity(root), 'commit', '--no-edit', '--no-verify', '-q'], wt).ok;
+    if (r.ok || unioned) {
+        const by = unioned ? `; kept both sides' lines in ${conflicts.join(', ')} (fp:union)` : '';
+        logMaking(root, { lane: lane.id, kind: 'sync', line: `took the landed work (${branch} ${headOf(root)?.slice(0, 7)})${by}`, at: now.toISOString() });
+        u.summary('pass', `lane ${lane.id} has the landed work from ${branch}${by}`);
+        return EXIT.pass;
+    }
+    git(['merge', '--abort'], wt);
+    logMaking(root, { lane: lane.id, kind: 'refused', line: `sync conflicts with the landed work in ${conflicts.join(', ') || 'files git named'}`, at: now.toISOString() });
+    u.summary('fail', `lane ${lane.id} conflicts with the landed work in ${conflicts.join(', ') || '(see git)'}: two lanes changed one file`);
+    u.line('resolve it in the checkout by hand (git merge ' + branch + '), or the integrator moves the file to one lane', 1);
+    return EXIT.fail;
+}
+function settleUnion(dir, conflicts) {
+    const top = git(['rev-parse', '--show-toplevel'], dir).out;
+    if (!top)
+        return false;
+    const resolved = conflicts.map((p) => { try {
+        return resolveUnion(readFileSync(join(top, p), 'utf8'));
+    }
+    catch {
+        return null;
+    } });
+    if (resolved.some((t) => t === null))
+        return false;
+    conflicts.forEach((p, i) => writeFileSync(join(top, p), resolved[i]));
+    return git(['add', '--', ...conflicts], top).ok;
+}
+function verdict(root, f, lane, opts, u, now) {
+    const [, says, ...words] = opts.args;
+    if (says !== 'pass' && says !== 'fail') {
+        u.error('a verdict is pass or fail', `${T} lanes verdict ${lane.id} pass|fail --by <seat> "what you saw"`);
+        return EXIT.error;
+    }
+    const by = opts.by?.trim();
+    if (!by) {
+        u.error('a verdict names its seat', '--by <the verifier\'s seat name>');
+        return EXIT.error;
+    }
+    const built = new Set([lane.builder, `lane-${lane.id}`, ...readMaking(root, lane.id).filter((e) => e.kind === 'checkpoint' || e.kind === 'final').map((e) => e.by)].filter(Boolean));
+    if (built.has(by)) {
+        u.summary('fail', `${by} built lane ${lane.id}: the builder never judges its own lane. A different seat verifies it (${verifyPath(root, lane.id)})`);
+        logMaking(root, { lane: lane.id, kind: 'refused', line: `${by} tried to verify its own lane`, at: now.toISOString() });
+        return EXIT.fail;
+    }
+    const sha = headOf(join(root, lane.worktree)) ?? '';
+    lane.verdicts.push({ by, says, ...(words.length ? { words: words.join(' ') } : {}), sha, at: now.toISOString() });
+    save(root, f, lane);
+    logMaking(root, { lane: lane.id, kind: 'verdict', line: `${by}: ${says}${words.length ? ` — ${words.join(' ')}` : ''} (on ${sha.slice(0, 7)})`, by, at: now.toISOString() });
+    u.summary(says === 'pass' ? 'pass' : 'warn', `${by} ${says === 'pass' ? 'passes' : 'fails'} lane ${lane.id} on ${sha.slice(0, 7)}${says === 'fail' ? ': the lane is open again with those words in its next brief' : ''}`);
+    return EXIT.pass;
+}
+function merge(root, f, lane, opts, u, io, now) {
+    settlePicks(root, now);
+    const wt = join(root, lane.worktree);
+    const head = lane.state === 'merged' ? null : headOf(wt);
+    const v = laneView(root, f, lane, head, now.getTime());
+    const refuse = (why, next) => {
+        logMaking(root, { lane: lane.id, kind: 'refused', line: `merge refused: ${why}`, at: now.toISOString() });
+        if (opts.json)
+            io.log(JSON.stringify({ merged: false, lane: lane.id, status: v.status, why, next }, null, 2));
+        else {
+            u.summary('fail', `lane ${lane.id} does not merge: ${why}`);
+            u.line(`next: ${next}`, 1);
+        }
+        return EXIT.fail;
+    };
+    if (v.status === 'merged') {
+        u.summary('pass', `lane ${lane.id} is already merged`);
+        return EXIT.pass;
+    }
+    if (v.status !== 'ready')
+        return refuse(`${v.status} — ${v.says}`, v.next);
+    const homeHead = headOf(root);
+    if (!git(['merge-base', '--is-ancestor', homeHead, head], wt).ok)
+        return refuse('the game moved since the gate ran (another lane landed)', `${T} lanes sync ${lane.id}, then ${T} lanes gate ${lane.id}`);
+    const ident = identity(root);
+    const r = git([...ident, 'merge', '--no-ff', '--no-commit', lane.branch], root);
+    if (!r.ok) {
+        git(['merge', '--abort'], root);
+        return refuse(`git refused the merge: ${(r.err || r.out).split('\n')[0]}`, `${T} lanes sync ${lane.id}`);
+    }
+    const carried = openDecisionsFor(root, lane);
+    const making = join(root, 'design', 'MAKING.md');
+    mkdirSync(join(root, 'design'), { recursive: true });
+    const head0 = existsSync(making) ? readFileSync(making, 'utf8') : '# Making of\n\nOne section per merged lane: who built it, who verified it, what it cost, what it tried, what is still weak.\n';
+    writeFileSync(making, `${head0.replace(/\s*$/, '')}\n\n${makingSection(root, lane, { sha: head, at: now, carried })}`);
+    for (const d of carried)
+        setDecisionStatus(root, d.id, `built by lane ${lane.id} (${head.slice(0, 7)}, ${now.toISOString().slice(0, 10)})`);
+    const add = ['design/MAKING.md', ...(existsSync(join(root, 'design', 'decisions.md')) ? ['design/decisions.md'] : [])];
+    git(['add', '--', ...add], root);
+    const by = [...lane.verdicts].reverse().find((x) => x.says === 'pass').by;
+    const c = git([...ident, 'commit', '--no-verify', '-q', '-m', `lanes: merge ${lane.id} — ${lane.title}\n\nBuilt by ${lane.builder}; verified by ${by}. Spend $${spentUsd(root, lane.id).toFixed(2)} of $${lane.cap_usd.toFixed(2)}.${carried.length ? ` Builds ${carried.map((d) => d.id).join(', ')}.` : ''}`], root);
+    if (!c.ok) {
+        git(['merge', '--abort'], root);
+        return refuse(`the merge commit failed: ${(c.err || c.out).split('\n')[0]}`, 'commit by hand');
+    }
+    lane.state = 'merged';
+    lane.merged_at = now.toISOString();
+    lane.merge_sha = headOf(root) ?? undefined;
+    save(root, f, lane);
+    sweepStills(root, lane);
+    git(['worktree', 'remove', '--force', wt], root);
+    logMaking(root, { lane: lane.id, kind: 'merge', line: `merged --no-ff as ${lane.merge_sha?.slice(0, 7)}${carried.length ? `; built ${carried.map((d) => d.id).join(', ')}` : ''}`, at: now.toISOString() });
+    if (opts.json) {
+        io.log(JSON.stringify({ merged: true, lane: lane.id, sha: lane.merge_sha, built: carried.map((d) => d.id) }, null, 2));
+        return EXIT.pass;
+    }
+    u.summary('pass', `lane ${lane.id} merged (${lane.merge_sha?.slice(0, 7)}): design/MAKING.md has its section${carried.length ? `; ${carried.map((d) => d.id).join(', ')} marked built` : ''}; its checkout is removed`);
+    const others = (readLanes(root)?.lanes ?? []).filter((l) => l.state === 'running' || l.state === 'waiting-gate');
+    if (others.length)
+        u.line(`the other lanes take this first: ${others.map((l) => `${T} lanes sync ${l.id}`).join(' · ')}`, 1);
+    return EXIT.pass;
+}
+function owner(root, f, lane, opts, u, now) {
+    if (opts.by !== 'owner') {
+        u.error(`${opts.sub === 'cap' ? 'raising a cap' : 'dropping a lane'} is the owner's`, `${T} lanes ${opts.sub} ${lane.id}${opts.sub === 'cap' ? ' <usd>' : ''} --by owner`);
+        return EXIT.fail;
+    }
+    if (opts.sub === 'drop') {
+        lane.state = 'dropped';
+        save(root, f, lane);
+        logMaking(root, { lane: lane.id, kind: 'cap', line: 'dropped by the owner', by: 'owner', at: now.toISOString() });
+        u.summary('pass', `lane ${lane.id} dropped`);
+        return EXIT.pass;
+    }
+    const usd = Number(opts.args[1]);
+    if (!(usd >= 0)) {
+        u.error('the cap is dollars', `${T} lanes cap ${lane.id} 20 --by owner`);
+        return EXIT.error;
+    }
+    const was = lane.cap_usd;
+    lane.cap_usd = usd;
+    save(root, f, lane);
+    logMaking(root, { lane: lane.id, kind: 'cap', line: `the owner set the cap $${was} → $${usd}`, by: 'owner', at: now.toISOString() });
+    u.summary('pass', `lane ${lane.id}: cap $${was} → $${usd}`);
+    return EXIT.pass;
+}
+function views(root, f, now) {
+    return f.lanes.map((l) => laneView(root, f, l, l.state === 'merged' || l.state === 'planned' ? null : headOf(join(root, l.worktree)), now.getTime()));
+}
+function status(root, f, opts, u, io, now) {
+    settlePicks(root, now);
+    const vs = views(root, readLanes(root) ?? f, now);
+    if (opts.json) {
+        io.log(JSON.stringify({ lanes: vs.map((v) => ({ id: v.lane.id, title: v.lane.title, status: v.status, says: v.says, next: v.next, spent_usd: v.spent, cap_usd: v.lane.cap_usd, minutes: v.minutes, timebox_min: v.lane.timebox_min, builder: v.lane.builder ?? null, head: v.head })) }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`lanes · ${vs.filter((v) => v.status === 'merged').length} of ${vs.length} merged`);
+    const mark = (s) => (s === 'merged' || s === 'ready' ? 'pass' : s === 'gate failed' || s === 'stuck' || s === 'reopened' ? 'fail' : s === 'planned' || s === 'dropped' ? 'note' : 'warn');
+    for (const v of vs)
+        u.item(mark(v.status), `${v.lane.id} · ${v.status} · $${v.spent.toFixed(2)}/$${v.lane.cap_usd.toFixed(2)}${v.minutes !== null && v.status !== 'merged' ? ` · ${v.minutes}/${v.lane.timebox_min} min` : ''} — ${v.says}`, v.next || undefined);
+    return EXIT.pass;
+}
+function report(root, f, opts, u, io, now) {
+    const vs = views(root, f, now);
+    const costs = readCosts(root);
+    const L = [`# Lanes report · ${now.toISOString().slice(0, 16).replace('T', ' ')}`, ''];
+    const total = vs.reduce((n, v) => n + v.spent, 0);
+    L.push(`${vs.length} lane(s), ${vs.filter((v) => v.status === 'merged').length} merged · spend $${total.toFixed(2)} of $${vs.reduce((n, v) => n + v.lane.cap_usd, 0).toFixed(2)} capped`, '');
+    for (const v of vs) {
+        const m = readMaking(root, v.lane.id);
+        const ver = [...v.lane.verdicts].reverse()[0];
+        L.push(`## ${v.lane.id} · ${v.status}`, '', `- ${v.lane.title}`, `- Built by ${v.lane.builder ?? '—'}; verifier ${ver ? `${ver.by} (${ver.says})` : '—'}`, `- Spend $${v.spent.toFixed(2)} of $${v.lane.cap_usd.toFixed(2)}${costs.some((c) => c.lane === v.lane.id) ? ` (${costs.filter((c) => c.lane === v.lane.id).map((c) => `${c.kind} $${c.usd.toFixed(2)}`).join(', ')})` : ''} · time ${v.minutes ?? '—'} of ${v.lane.timebox_min} min`, `- Now: ${v.says}${v.next ? ` → ${v.next}` : ''}`);
+        if (v.lane.carried?.length)
+            L.push(`- Carries the owner's ${v.lane.carried.join(', ')}`);
+        for (const e of m)
+            L.push(`  - ${e.at.slice(11, 16)} ${e.kind}: ${e.line}${e.evidence ? ` (${e.evidence})` : ''}`);
+        L.push('');
+    }
+    const text = L.join('\n');
+    mkdirSync(join(root, LANES_DIR), { recursive: true });
+    writeFileSync(join(root, LANES_DIR, 'report.md'), text);
+    if (opts.json)
+        io.log(JSON.stringify({ file: join(LANES_DIR, 'report.md'), spent_usd: total, lanes: vs.map((v) => ({ id: v.lane.id, status: v.status, spent_usd: v.spent })) }, null, 2));
+    else {
+        io.log(text);
+        u.summary('pass', `written to ${join(LANES_DIR, 'report.md')}`);
+    }
+    return EXIT.pass;
+}

package/dist/commands/lessons.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { addLesson, lessonLines, rankLessons } from "../lessons/store.js";
+import { motifLines, recentMotifs, recordMotif } from "../lessons/motifs.js";
+import { ui } from "../ui.js";
+export const LESSON_SOURCES = ['panel', 'player', 'verify', 'look'];
+function metadata(root) {
+    try {
+        const m = existsSync(join(root, 'funpixel.json')) ? JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).metadata ?? {} : {};
+        return { genre: typeof m.genre === 'string' && m.genre ? m.genre : 'any', style: typeof m.artStyle === 'string' ? m.artStyle : '' };
+    }
+    catch {
+        return { genre: 'any', style: '' };
+    }
+}
+export async function lessons(opts, io = console) {
+    const u = ui(io, 'lessons');
+    const root = resolve(opts.dir ?? '.');
+    const meta = metadata(root);
+    const genre = opts.genre ?? meta.genre;
+    if (opts.motif) {
+        const m = recordMotif(root);
+        if (!m) {
+            u.error('no design note to read the motif from', 'write the design document first: design/GDD.md (skill funpixel-gdd)');
+            return EXIT.not_observed;
+        }
+        if (opts.json)
+            io.log(JSON.stringify(m, null, 2));
+        else
+            u.summary('pass', `recorded: ${motifLines([m])[0].slice(2)}`);
+        return EXIT.pass;
+    }
+    if (opts.add) {
+        const finding = opts.finding?.trim(), fix = opts.fix?.trim();
+        if (!finding || !fix) {
+            u.error('a lesson is a finding and its fix', 'funtools lessons add "threats read as pickups at phone size" --fix "harm colour on every threat, 3 px ink outline"');
+            return EXIT.error;
+        }
+        const source = opts.source ?? 'panel';
+        if (!LESSON_SOURCES.includes(source)) {
+            u.error(`--source is ${LESSON_SOURCES.join(', ')}`, 'who named the finding');
+            return EXIT.error;
+        }
+        const delta = opts.delta === undefined ? undefined : Number(opts.delta);
+        if (delta !== undefined && !Number.isFinite(delta)) {
+            u.error('--delta is a number (the panel-mean change)', 'e.g. --delta 0.4');
+            return EXIT.error;
+        }
+        const l = addLesson(root, { genre, style: meta.style, source, finding, fix, ...(delta !== undefined ? { delta } : {}) }, opts.share);
+        if (opts.json)
+            io.log(JSON.stringify(l, null, 2));
+        else
+            u.summary('pass', `recorded for ${genre}${opts.share ? ', shared in ~/.funpixel/lessons' : ''}`);
+        return EXIT.pass;
+    }
+    const ranked = rankLessons(root, genre);
+    const motifs = recentMotifs(root, 5);
+    if (opts.json) {
+        io.log(JSON.stringify({ genre, lessons: ranked, recent_motifs: motifs }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`lessons · ${genre}`);
+    if (!ranked.length)
+        u.item('note', 'none yet', 'after a fix round, record each settled finding: funtools lessons add "<finding>" --fix "<fix>"');
+    for (const line of lessonLines(ranked, 10))
+        u.line(line.slice(2));
+    if (motifs.length) {
+        u.heading('recently used in other games (avoid unless asked)');
+        for (const line of motifLines(motifs))
+            u.line(line.slice(2));
+    }
+    return EXIT.pass;
+}