@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/flow.js

@@ -0,0 +1,600 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ensurePipeline, growForStage, markDone, writePipeline } from "./next.js";
+import { init } from "./init.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { evaluate, readPipeline } from "../pipeline/pipeline.js";
+import { appendEntry, nextCard, nextQuestion, readProgress } from "../progress/progress.js";
+import { answerQuestion } from "../progress/answers.js";
+import { designDoc } from "../gdd/doc.js";
+import { apply, currentVersion } from "../plan/actions.js";
+import { lockedNotes, readStudio } from "../studio/pitch.js";
+import { lockRefusal } from "../studio/forks.js";
+import { studioFor } from "./pitch.js";
+import { commitPlan } from "../init/git.js";
+import { beat, flowBlock, flowView, freshFlow, keepRound, ownerSettings, planAgreement, planQuestions, readFlow, roundEvidence, roundsWithoutGates, startFlow, STUCK_ROUNDS, stuckAsk, whereLine, writeFlow } from "../flow/flow.js";
+import { ui } from "../ui.js";
+import { fixList } from "../direct/round.js";
+import { matchBar } from "../owner/match.js";
+import { firstLookSet, missingLines, setApplies } from "../firstlook/set.js";
+import { worthGate, WORTH_TITLE } from "../gdd/worth.js";
+import { firstLookQuality, qualityLines } from "../firstlook/quality.js";
+import { ensurePrototype } from "../greenlight/worth.js";
+import { readFileSync, writeFileSync } from 'node:fs';
+import { budgetLine, budgetNeed, budgetPick, foldBudget, planPrice, settledBudget, writeAgreedBudget } from "../progress/progress.js";
+import { evaluateGate } from "../pipeline/pipeline.js";
+import { lastWorthQuestion } from "../gdd/worth.js";
+import { droppedOf } from "../flow/flow.js";
+import { writeStatus } from "../status/status.js";
+import { takeInbox } from "../status/inbox.js";
+import { lookBrief, lookLines, prepareLook, readLooks } from "../flow/look.js";
+import { keepLines, readKeep } from "../playtest/keep.js";
+import { readLanes } from "../lanes/lanes.js";
+export const FLOW_SUBCOMMANDS = ['status', 'start', 'ask', 'agree', 'round', 'drop', 'look'];
+const T = 'npx @funpixel/tools';
+async function judged(root, now) {
+    const [p0] = ensurePipeline(root, now);
+    const fl = p0.stages.find((x) => x.id === 'first-look');
+    if (fl && fl.status !== 'done' && fl.status !== 'skipped' && !fl.gates.some((g) => g.kind === 'set')) {
+        fl.gates.push({ kind: 'set' });
+        writePipeline(root, p0);
+    }
+    if (!p0.stages.some((x) => x.gates.some((g) => g.kind === 'worth'))) {
+        const st = ['pitch', 'lock', 'gdd', 'first-look'].map((id) => p0.stages.find((x) => x.id === id)).find((x) => x && x.status !== 'done' && x.status !== 'skipped');
+        if (st) {
+            if (st.id === 'first-look')
+                st.gates.unshift({ kind: 'worth' });
+            else
+                st.gates.push({ kind: 'worth' });
+            writePipeline(root, p0);
+        }
+    }
+    ensurePrototype(root, now, p0);
+    try {
+        foldBudget(root, readProgress(root));
+    }
+    catch { }
+    const wq = lastWorthQuestion(readProgress(root));
+    if (wq?.answer?.pick === 'drop' && wq.answer.by === 'owner' && !droppedOf(root, readFlow(root)))
+        dropGame(root, { by: 'owner', words: wq.answer.words ?? `drop (${wq.id}: not worth building at this length)`, from: wq.id, now });
+    let bar = null;
+    try {
+        bar = matchBar(root, { now });
+    }
+    catch { }
+    try {
+        takeInbox(root, now);
+    }
+    catch { }
+    const [p] = ensurePipeline(root, now);
+    const fp = (await fingerprint(root).catch(() => null))?.fingerprint ?? null;
+    const s = readProgress(root);
+    let moved = false;
+    for (const q of s.questions) {
+        if (q.kind !== 'scope' || !q.answer || (q.answer.pick !== 'skip' && q.answer.pick !== 'cut'))
+            continue;
+        const st = p.stages.find((x) => x.id === q.stage);
+        if (!st || st.status === 'done' || st.status === 'skipped')
+            continue;
+        st.status = 'skipped';
+        st.because = `the ${q.answer.by === 'owner' ? 'owner' : 'default'}'s answer to ${q.id}: ${q.answer.pick}${q.answer.words ? ` ("${q.answer.words}")` : ''}`;
+        moved = true;
+    }
+    for (const v of p.verdicts ?? []) {
+        const st = p.stages.find((x) => x.id === v.stage);
+        if (v.says === 'accept' && st && st.status !== 'done' && st.status !== 'skipped') {
+            st.status = 'done';
+            st.found = `the owner accepted it (${v.at.slice(0, 10)})`;
+            st.done_at = now.toISOString();
+            moved = true;
+        }
+    }
+    if (moved)
+        writePipeline(root, p);
+    const agreed = (() => { try {
+        return planAgreement(root).agreed === true;
+    }
+    catch {
+        return false;
+    } })();
+    let e = evaluate(root, p, fp, undefined, { agreed });
+    if (markDone(root, p, e, now))
+        e = evaluate(root, p, fp, undefined, { agreed });
+    try {
+        growForStage(root, e.current?.stage.id ?? null);
+    }
+    catch { }
+    return { p, e, fp, bar };
+}
+function flowOf(root, now) {
+    const f = readFlow(root);
+    if (f) {
+        const fresh = freshFlow(root, f);
+        if (fresh !== f)
+            writeFlow(root, fresh);
+        return [fresh, false];
+    }
+    return [startFlow(root, { now }), true];
+}
+function record(root, f, v, now) {
+    writeFlow(root, { ...keepRound(f, v), at: { phase: v.phase, stage: v.stage?.id ?? null, round: v.round?.n ?? null, waiting_on: v.waitingOn, step: v.step, run: v.run, said_at: now.toISOString() } });
+    writeStatus(root, v, now);
+}
+function show(u, io, v, opts, extra = {}) {
+    if (opts.json) {
+        io.log(JSON.stringify({ tool: 'funtools', command: 'flow', phase: v.phase, where: whereLine(v), waiting_on: v.waitingOn, stage: v.stage, round: v.round, closed_this_session: v.closedThisSession, cap: v.cap,
+            agreement: v.agreement, autonomy: v.autonomy, built_early: v.builtEarly, first: v.first,
+            evidence: v.evidence ? { unrun: v.evidence.unrun.map((g) => g.gate.kind), card: v.evidence.card, unpicked: v.evidence.unpicked.map((n) => n.id) } : null,
+            next: { step: v.step, run: v.run, why: v.why }, ...extra }, null, 2));
+        return;
+    }
+    io.log(flowBlock(v));
+}
+export async function flow(opts, io = console) {
+    const u = ui(io, 'flow');
+    const now = opts.now ?? (() => new Date());
+    const root = resolve(opts.dir ?? '.');
+    try {
+        if (opts.sub === 'start')
+            return await start(root, opts, u, io, now);
+        if (!existsSync(join(root, 'funpixel.json'))) {
+            u.summary('not_observed', `${root} is not a game folder yet (no funpixel.json)`);
+            u.line(`start one: ${T} flow start <folder> --idea "<the game in a line>"`, 1);
+            return EXIT.not_observed;
+        }
+        if (opts.sub !== 'agree' && opts.sub !== 'drop')
+            beat(root, 'work', { now: now() });
+        const was = readFlow(root);
+        if (was) {
+            const fresh = freshFlow(root, was);
+            if (fresh !== was)
+                writeFlow(root, fresh);
+        }
+        if (opts.sub === 'ask')
+            return await ask(root, opts, u, io, now());
+        if (opts.sub === 'agree')
+            return await agree(root, opts, u, io, now());
+        if (opts.sub === 'round')
+            return await round(root, opts, u, io, now());
+        if (opts.sub === 'drop')
+            return dropCmd(root, opts, u, io, now());
+        if (opts.sub === 'look')
+            return await lookCmd(root, opts, u, io, now());
+        const [f, started] = flowOf(root, now());
+        const { e } = await judged(root, now());
+        const v = flowView(root, e, f, { sessionStart: opts.sessionStart });
+        record(root, f, v, now());
+        if (started && !opts.json)
+            u.item('note', `started ${join('.funtools', 'flow.json')} on a game in progress: its code as it stands counts as the scaffold`);
+        show(u, io, v, opts);
+        return EXIT.pass;
+    }
+    catch (err) {
+        u.error(err.message);
+        return EXIT.error;
+    }
+}
+const AUTONOMY = new Set(['ask', 'plan-then-go', 'go']);
+async function start(root, opts, u, io, now) {
+    const extraJson = {};
+    if (opts.autonomy !== undefined && !AUTONOMY.has(opts.autonomy)) {
+        u.error(`--autonomy ${opts.autonomy}`, '--autonomy ask|plan-then-go|go: the owner\'s words from the brief');
+        return EXIT.error;
+    }
+    const rounds = opts.rounds === undefined ? undefined : Number(opts.rounds);
+    if (rounds !== undefined && !(Number.isInteger(rounds) && rounds >= 1 && rounds <= 50)) {
+        u.error(`--rounds ${opts.rounds}`, '--rounds n: rounds one session runs before it hands back (1 to 50)');
+        return EXIT.error;
+    }
+    const settings = { ...(opts.autonomy ? { autonomy: opts.autonomy } : {}), ...(rounds ? { rounds_per_session: rounds } : {}) };
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        const code = await init({ target: root, idea: opts.idea, framework: opts.framework, name: opts.name, bare: opts.bare, offline: opts.offline, noGit: opts.noGit, flow: settings }, opts.json ? { log: () => { }, error: (m) => io.error(m) } : io);
+        if (code !== 0)
+            return code;
+    }
+    else if (Object.keys(settings).length) {
+        const { readFileSync, writeFileSync } = await import('node:fs');
+        const m = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+        m.flow = { ...(m.flow ?? {}), ...settings };
+        writeFileSync(join(root, 'funpixel.json'), JSON.stringify(m, null, 2) + '\n');
+    }
+    const [f] = flowOf(root, now());
+    const spend = settleAtStart(root, opts, now());
+    if (spend.error) {
+        u.error(spend.error, '--budget <credits>|open|free|code-drawn: the owner\'s figure from the brief');
+        return EXIT.error;
+    }
+    extraJson.budget = spend;
+    const { e, bar } = await judged(root, now());
+    const v = flowView(root, e, f, { sessionStart: opts.sessionStart });
+    record(root, f, v, now());
+    if (!opts.json) {
+        u.heading('the budget (settled at the start)');
+        u.item(spend.asked ? 'warn' : 'pass', spend.says, spend.asked ? 'ask the owner in the chat; the build never stops to ask again unless it would go over the figure they pick' : undefined);
+    }
+    if (!opts.json && bar?.bar.lines.length) {
+        const L = bar.bar.lines;
+        u.heading(`the owner's bar · ${L.filter((l) => l.verdict === 'applies').length} apply, ${L.filter((l) => l.verdict === 'skipped').length} skipped, ${L.filter((l) => l.verdict === 'asked').length} asked`);
+        for (const l of L)
+            u.item(l.verdict === 'applies' ? 'pass' : l.verdict === 'skipped' ? 'skip' : 'warn', l.text, `${l.verdict}${l.note ? ` as ${l.note}` : ''}${l.ask ? ` (${l.ask})` : ''} — ${l.why}`);
+        u.line(`the owner flips any line: ${T} owner apply|skip <n> --dir ${root} (or tell the agent in the chat)`, 1);
+    }
+    if (opts.json && bar)
+        extraJson.bar = bar.bar;
+    if (!opts.json)
+        u.heading('the flow');
+    if (!opts.json && !ownerSettings(root).autonomy)
+        u.item('note', 'autonomy: the owner set none, so the run is plan-then-go, the recommended autonomy for a game meant to be built: one plan agreement, then the build runs round after round without a stop at every stage', 'only the owner sets it: their brief\'s words, as --autonomy on `flow start` (funpixel.json flow.autonomy); "ask" stays available for an owner who wants a stop at each stage');
+    else if (!opts.json && ownerSettings(root).autonomy === 'ask')
+        u.item('note', 'autonomy: ask (the owner\'s). For a game meant to be built, plan-then-go is the recommended setting: one plan agreement, then build without a stop at every stage', 'the owner changes it with `flow start --autonomy plan-then-go` (funpixel.json flow.autonomy)');
+    show(u, io, v, opts, extraJson);
+    if (!opts.json)
+        u.line(`the owner follows in the chat: the GDD (${join(root, 'design', 'GDD.md')}, its \`## Where we are\` at the top, updated each round) and the running game (open it beside the chat: the host's own browser when it has one, else \`${T} dev --open\`)`);
+    return EXIT.pass;
+}
+async function ask(root, opts, u, io, now) {
+    if (droppedOf(root, readFlow(root))) {
+        u.summary('fail', 'the owner dropped this game: nothing is put to them');
+        return EXIT.fail;
+    }
+    const s = readProgress(root);
+    const open = s.questions.find((q) => q.kind === 'plan' && q.state === 'open');
+    const a = planAgreement(root, s);
+    if (a.agreed) {
+        u.summary('pass', `the plan is already agreed: ${a.says}`);
+        return EXIT.pass;
+    }
+    if (open) {
+        u.summary('pass', `the plan is already with the owner (${open.id}): ask them in the chat and wait for their word`);
+        return EXIT.pass;
+    }
+    const doc = designDoc(root);
+    const version = doc ? currentVersion(root) : null;
+    const owes = planOwes(root, doc?.text ?? null);
+    if (owes.length && !opts.json) {
+        u.heading('flow ask · what the plan still owes (shown to the owner with it)');
+        for (const o of owes)
+            u.item('warn', o);
+    }
+    const fp0 = (await fingerprint(root).catch(() => null))?.fingerprint ?? null;
+    const judgedNow = judgedLine(root, fp0);
+    const price = planPrice(root);
+    const q = { type: 'ask', id: nextQuestion(readProgress(root)), at: now.toISOString(), kind: 'plan', stage: 'plan', price: price.credits, text: `Agree the plan${version ? ` (${version})` : ''}? It is the GDD (design/GDD.md), its target frames and its asset list. Its assets cost about ${price.credits} credits (${price.says}), made as the build goes from the account's credits.${owes.length ? ` It still owes ${owes.length} item${owes.length === 1 ? '' : 's'}: ${owes.slice(0, 3).map((o) => o.replace(/;.*$/, '').slice(0, 70)).join('; ')}${owes.length > 3 ? '; …' : ''}.` : ''} Approve to start the build, or say what to change.`, options: ['approve', 'change'] };
+    appendEntry(root, q);
+    appendEntry(root, { type: 'card', n: nextCard(readProgress(root)), at: now.toISOString(), kind: 'waiting', stage: 'plan', line: `${judgedNow}. The plan${version ? ` ${version}` : ''} is ready for you: approve it, or say what to change`, observed: !!doc, ...(doc ? { evidence: { path: doc.rel, says: `the plan: ${doc.rel}` } } : { why_not: 'no design/GDD.md yet' }), asks: q.id });
+    const revised = planQuestions(s).some((x) => x.answer?.by === 'owner' && x.answer.pick !== 'approve');
+    const change = planAgreement(root, s).change;
+    const git = commitPlan(root, `Plan${version ? ` ${version}` : ''}: ${revised ? 'revised and ' : ''}put to the owner (${q.id})${revised && change ? ` — their change: ${change.slice(0, 120)}` : ''}`);
+    if (opts.json)
+        io.log(JSON.stringify({ ask: q, git, judged: judgedNow }, null, 2));
+    else {
+        u.item(/^Below/.test(judgedNow) ? 'fail' : /^Not judged/.test(judgedNow) ? 'not_observed' : 'pass', `the kit's read, first on the card: ${judgedNow}`, 'say it the same way when you hand back, never only "N items pass"');
+        u.item(git.state === 'committed' ? 'pass' : 'note', git.says, git.next);
+        u.summary('pass', `${q.id}: show the owner the plan in the chat: the GDD (its \`## Where we are\` at the top), its target frames and its price (${price.credits} credits). When they say yes, record it with their words: \`${T} flow agree --by owner "<their words>"\`; a change they ask for goes into the GDD as a new version`);
+    }
+    return EXIT.pass;
+}
+export function planOwes(root, gdd) {
+    const out = [];
+    const studio = readStudio(root) ? studioFor(root).studio : null;
+    const held = lockRefusal(root, studio);
+    if (held)
+        out.push(held.says);
+    if (gdd && studio?.locked)
+        for (const n of lockedNotes(studio, gdd))
+            if (n.state === 'warn')
+                out.push(n.what);
+    try {
+        if (setApplies(readPipeline(root)))
+            out.push(...missingLines(firstLookSet(root)));
+    }
+    catch { }
+    try {
+        const p = readPipeline(root);
+        if (p?.stages.some((x) => x.status !== 'skipped' && x.gates.some((g) => g.kind === 'worth'))) {
+            const w = worthGate(root);
+            if (w.state !== 'met')
+                out.push(`worth · ${WORTH_TITLE} ${w.says}; ${w.run}`);
+        }
+    }
+    catch { }
+    try {
+        out.push(...qualityLines(firstLookQuality(root)));
+    }
+    catch { }
+    return out;
+}
+async function agree(root, opts, u, io, now) {
+    if (opts.by !== 'owner') {
+        u.error('agreeing the plan is the owner\'s', `show the plan in the chat (\`${T} flow ask\`); when the owner says yes there, record it with their words: \`${T} flow agree --by owner "<their words>"\``);
+        return EXIT.fail;
+    }
+    const words = (opts.args ?? []).join(' ').trim();
+    const r = agreePlan(root, { words, now });
+    const [f] = flowOf(root, now);
+    const { e } = await judged(root, now);
+    const v = flowView(root, e, f, { sessionStart: opts.sessionStart });
+    record(root, f, v, now);
+    if (opts.json)
+        io.log(JSON.stringify({ ...r, next: { where: whereLine(v), step: v.step, run: v.run } }, null, 2));
+    else {
+        u.summary('pass', `the owner agreed the plan (${r.q}${r.version ? `, ${r.version}` : ''})${r.locked ? '; locked' : ''}. The build starts`);
+        u.line(whereLine(v));
+        u.line(`next: ${v.step}`);
+        u.line(`run: ${v.run}`, 1);
+    }
+    return EXIT.pass;
+}
+export function agreePlan(root, o = {}) {
+    const now = o.now ?? new Date();
+    const s = readProgress(root);
+    let q = s.questions.find((x) => x.kind === 'plan' && x.state === 'open');
+    if (!q) {
+        const ask = { type: 'ask', id: nextQuestion(s), at: now.toISOString(), kind: 'plan', stage: 'plan', price: planPrice(root).credits, text: 'Agree the plan?', options: ['approve', 'change'] };
+        appendEntry(root, ask);
+        q = readProgress(root).questions.find((x) => x.id === ask.id);
+    }
+    answerQuestion(root, q.id, 'approve', { words: o.words, now });
+    let locked = false, version = null;
+    if (designDoc(root)) {
+        version = currentVersion(root);
+        try {
+            apply(root, { by: 'owner', ...(o.words ? { why: o.words } : {}) }, now);
+            locked = true;
+        }
+        catch { }
+    }
+    return { q: q.id, version, locked };
+}
+async function lookCmd(root, opts, u, io, now) {
+    const [f] = flowOf(root, now);
+    const { e } = await judged(root, now);
+    const v = flowView(root, e, f, { sessionStart: opts.sessionStart });
+    const lanes = readLanes(root)?.lanes ?? [];
+    const L = v.look;
+    if (L.state === 'owed' && L.last) {
+        record(root, f, v, now);
+        if (opts.json) {
+            io.log(JSON.stringify({ look: L.last, state: 'owed', problem: L.last.problem ?? null }, null, 2));
+            return L.last.problem ? EXIT.fail : EXIT.not_observed;
+        }
+        if (L.last.problem) {
+            u.item('fail', `look ${L.last.k}: the answer cannot be read: ${L.last.problem}`, join(root, L.last.answer));
+            u.summary('fail', 'the seat writes it again in the shape its brief asks for');
+            return EXIT.fail;
+        }
+        u.summary('not_observed', `look ${L.last.k} is owed: hand ${join(root, L.last.brief)} to a fresh agent with only that file; it writes ${join(root, L.last.answer)}`);
+        return EXIT.not_observed;
+    }
+    if (L.state === 'due' && v.round) {
+        const m = (() => { try {
+            return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+        }
+        catch {
+            return {};
+        } })();
+        const title = (designDoc(root) && /^#\s+(.+)$/m.exec(designDoc(root).text)?.[1].trim()) || m.name || 'this game';
+        const previous = readLooks(root, lanes).filter((l) => l.filed).at(-1) ?? null;
+        const look = prepareLook(root, v.round.n, (k, answer) => lookBrief({ game: title, round: v.round.n, k, answer, keep: keepLines(readKeep(root)), previous, lanes: lanes.filter((l) => l.state !== 'dropped' && l.state !== 'merged').map((l) => ({ id: l.id, kind: l.kind, title: l.title })) }), now);
+        const after = flowView(root, e, f, { sessionStart: opts.sessionStart });
+        record(root, f, after, now);
+        if (opts.json) {
+            io.log(JSON.stringify({ look, state: 'prepared' }, null, 2));
+            return EXIT.pass;
+        }
+        u.item('pass', `look ${look.k} (round ${look.round}): the brief is written`, join(root, look.brief));
+        u.summary('pass', `hand it to a fresh agent with only that file; it plays the whole game and writes ${join(root, look.answer)}; then ${T} flow look routes it`);
+        return EXIT.pass;
+    }
+    record(root, f, v, now);
+    if (opts.json) {
+        io.log(JSON.stringify({ look: L.last, state: L.state, why: L.why, next: L.next, every: L.every }, null, 2));
+        return EXIT.pass;
+    }
+    if (L.last?.filed) {
+        const [head, ...rest] = lookLines(L.last);
+        u.item(L.last.ship === 'yes' ? 'pass' : 'warn', head);
+        for (const d of L.last.defects)
+            u.item(d.severity === 'blocker' ? 'fail' : d.severity === 'major' ? 'warn' : 'note', rest[L.last.defects.indexOf(d)], d.where || undefined);
+        if (L.last.defects.some((d) => d.routed === 'the owner'))
+            u.line('the owner\'s are questions of taste or scope: put each to them in the chat', 1);
+        if (L.last.defects.some((d) => d.routed.startsWith('lane ')))
+            u.line(`a lane's next brief carries its defects (${T} lanes start <id> rewrites it)`, 1);
+    }
+    u.summary('pass', L.state === 'none' ? `no look due: ${L.why}` : L.why);
+    return EXIT.pass;
+}
+async function round(root, opts, u, io, now) {
+    const [f] = flowOf(root, now);
+    const { e } = await judged(root, now);
+    const v = flowView(root, e, f, { sessionStart: opts.sessionStart });
+    const sr = v.round ? e.stages.find((x) => x.stage.id === v.round.stage) ?? null : null;
+    if (v.phase === 'dropped') {
+        if (opts.json)
+            io.log(JSON.stringify({ closed: false, why: 'dropped', next: null }, null, 2));
+        else
+            u.summary('fail', `no round: ${v.step}`);
+        return EXIT.fail;
+    }
+    if (v.refused) {
+        if (opts.json)
+            io.log(JSON.stringify({ closed: false, refused: v.refused, next: { step: v.step, run: v.run } }, null, 2));
+        else {
+            u.item('fail', `${v.refused.stage} does not start: ${v.refused.says}`);
+            u.line(`run: ${v.run}`, 1);
+        }
+        return EXIT.fail;
+    }
+    if (v.phase !== 'rounds' || !v.round || !sr) {
+        const why = v.phase === 'done' ? 'every stage has its evidence' : v.phase === 'waiting' ? 'the plan is not agreed yet: rounds start after the owner approves' : 'the plan is still being made';
+        if (opts.json)
+            io.log(JSON.stringify({ closed: false, why, next: { step: v.step, run: v.run } }, null, 2));
+        else {
+            u.item('note', `no round to close: ${why}`);
+            u.line(`next: ${v.step}`);
+            u.line(`run: ${v.run}`, 1);
+        }
+        return v.phase === 'done' ? EXIT.pass : EXIT.fail;
+    }
+    const s = readProgress(root);
+    const ev = roundEvidence(root, sr, Date.parse(v.round.since), s);
+    const missing = [
+        ...ev.unrun.map((g) => `${g.gate.kind} did not run on the current files (${g.says}): ${g.run}`),
+        ...(ev.card === null ? [`no card with a frame of the build since the round opened: ${T} capture, then ${T} progress card --stage ${sr.stage.id} --shot last --line "<what changed>"`] : []),
+        ...(ev.unpicked.length ? [`the owner's note${ev.unpicked.length > 1 ? 's' : ''} ${ev.unpicked.map((n) => n.id).join(', ')} not picked up by a card yet: post the round's card after reading ${ev.unpicked.length > 1 ? 'them' : 'it'}`] : []),
+    ];
+    if (missing.length) {
+        if (opts.json)
+            io.log(JSON.stringify({ closed: false, round: v.round.n, missing }, null, 2));
+        else {
+            u.heading(`round ${v.round.n} · ${sr.stage.title}: not closed`);
+            for (const m of missing)
+                u.item('fail', m);
+            u.summary('fail', 'a round closes on evidence: the gates run on the current files, a card with a frame of the build, the owner\'s notes picked up');
+        }
+        return EXIT.fail;
+    }
+    const card = s.cards.find((c) => c.n === ev.card);
+    const gates = sr.gates.map((g) => ({ kind: g.gate.kind, state: g.state, says: g.says }));
+    const met = sr.done || sr.gates.every((g) => g.state === 'met');
+    const scored = sr.gates.some((g) => g.gate.kind === 'score') ? fixList(root).mean : null;
+    const closed = { n: v.round.n, stage: sr.stage.id, opened_at: v.round.since, closed_at: now.toISOString(), card: ev.card, gates, met, ...(scored !== null ? { accuracy: scored } : {}), ...(card.picked?.length ? { notes: card.picked.map((p) => p.id) } : {}), ...(met ? { ended: (sr.stage.found?.startsWith('the owner accepted') ? 'owner' : 'gates') } : {}) };
+    const nf = { ...f, rounds: [...f.rounds.filter((r) => r.closed_at), closed] };
+    writeFlow(root, nf);
+    let stuck = null;
+    const title = sr.stage.title, sid = sr.stage.id;
+    if (!met && roundsWithoutGates(nf, sid, s) >= STUCK_ROUNDS && !s.open.some((q) => q.kind === 'scope' && q.stage === sid)) {
+        stuck = stuckAsk(sid, title, roundsWithoutGates(nf, sid, s), gates.filter((g) => g.state !== 'met').map((g) => `${g.kind}: ${g.says}`).join('; '), now, nextQuestion(s));
+        appendEntry(root, stuck);
+        appendEntry(root, { type: 'card', n: nextCard(readProgress(root)), at: now.toISOString(), kind: 'stuck', stage: sid, line: `Stuck on ${title}: ${STUCK_ROUNDS} rounds without ${scored !== null ? 'a gain on the target score' : 'its gates'}`, observed: false, why_not: 'a question, not a frame', asks: stuck.id });
+    }
+    const after = await judged(root, now);
+    const nv = flowView(root, after.e, readFlow(root), { sessionStart: opts.sessionStart });
+    record(root, readFlow(root), nv, now);
+    if (opts.json) {
+        io.log(JSON.stringify({ closed: true, round: closed, stuck: stuck?.id ?? null, next: { where: whereLine(nv), step: nv.step, run: nv.run } }, null, 2));
+        return EXIT.pass;
+    }
+    u.heading(`round ${closed.n} closed · ${title}`);
+    for (const g of gates)
+        u.item(g.state === 'met' ? 'pass' : g.state === 'failing' ? 'fail' : 'warn', `${g.kind}: ${g.says}`);
+    u.item('pass', `card ${closed.card}${closed.notes ? ` (picked up ${closed.notes.join(', ')})` : ''}`);
+    if (met)
+        u.item('pass', `${title}: ${closed.ended === 'owner' ? 'the owner accepted it' : 'its gates are met'}; the stage ends`);
+    if (stuck)
+        u.item('warn', `${stuck.id} asks the owner: ${stuck.text}`, 'skip / cut / keep going, asked in the chat; under autonomy go the default (keep going) lands after 10 min');
+    u.heading('next');
+    u.line(whereLine(nv));
+    u.line(nv.step);
+    u.line(`run: ${nv.run}`, 1);
+    return EXIT.pass;
+}
+export function settleAtStart(root, opts, now) {
+    const s = readProgress(root);
+    const was = settledBudget(root, s);
+    if (opts.budget !== undefined) {
+        const v = budgetPick(opts.budget);
+        if (v === null)
+            return { state: 'error', says: '', asked: null, error: `--budget ${opts.budget}` };
+        writeAgreedBudget(root, v, 'the owner (the brief: flow start --budget)', { codeDrawn: opts.budget === 'code-drawn', now });
+        const b = settledBudget(root);
+        return { state: b.state, says: `budget ${budgetLine(b)}${opts.budget === 'code-drawn' ? ', a code-drawn look on purpose' : ''}`, asked: null };
+    }
+    if (was.state !== 'unset')
+        return { state: was.state, says: `budget ${budgetLine(was)}`, asked: null };
+    if (was.asking)
+        return { state: 'unset', says: `budget: ${was.asking} waits on the owner`, asked: was.asking };
+    const need = budgetNeed(root);
+    return { state: 'unset', says: `budget: none — the account's credits pay; out of credits is a pause (the owner tops up). The tier's estimate: ${need.recommended} credits (${need.says})`, asked: null };
+}
+export function dropGame(root, o) {
+    if (o.by !== 'owner')
+        throw new Error('only the owner drops a game');
+    const now = o.now ?? new Date();
+    const at = now.toISOString();
+    const words = o.words.replace(/\s+/g, ' ').trim().slice(0, 500) || 'dropped';
+    const drop = { by: 'owner', words, at, ...(o.from ? { from: o.from } : {}) };
+    const f = readFlow(root);
+    if (f)
+        writeFlow(root, { ...f, dropped: drop });
+    const notes = [];
+    const pfile = join(root, 'design', 'pipeline.json');
+    try {
+        const p = JSON.parse(readFileSync(pfile, 'utf8'));
+        p.dropped = drop;
+        for (const n of Array.isArray(p.notes) ? p.notes : [])
+            if (n && (n.status === 'open' || n.verdict?.says === 'reject')) {
+                n.status = 'dropped';
+                n.dropped_at = at;
+                notes.push(n.id);
+            }
+        writeFileSync(pfile, JSON.stringify(p, null, 2) + '\n');
+    }
+    catch { }
+    const s = readProgress(root);
+    const questions = s.open.map((q) => q.id);
+    appendEntry(root, {
+        type: 'card', n: nextCard(s), at, kind: 'dropped', stage: s.last?.stage ?? 'plan', line: `Dropped by the owner: "${words}"`, observed: false, why_not: 'a decision, not a frame', dropped_by: 'owner',
+        decisions: [`the game is dropped${o.from ? ` (${o.from})` : ''}; nothing more is built`, ...(notes.length ? [`notes closed as dropped, not fixed: ${notes.join(', ')}`] : []), ...(questions.length ? [`questions closed with it: ${questions.join(', ')}`] : [])],
+    });
+    return { notes, questions };
+}
+function dropCmd(root, opts, u, io, now) {
+    if (opts.by !== 'owner') {
+        u.error('only the owner drops a game', `the owner says so in the chat (answers the worth question "drop"), then you run \`${T} flow drop --by owner "<their words>"\`; an agent never drops one: recommend it, with the numbers`);
+        return EXIT.fail;
+    }
+    const words = (opts.args ?? []).join(' ').trim();
+    if (!words) {
+        u.error('say why, in the owner\'s words', `${T} flow drop --by owner "not worth building: one unproven verb"`);
+        return EXIT.error;
+    }
+    const was = droppedOf(root, readFlow(root));
+    if (was) {
+        u.summary('pass', `already dropped by the owner (${was.at.slice(0, 10)}): "${was.words}"`);
+        return EXIT.pass;
+    }
+    const r = dropGame(root, { by: 'owner', words, now });
+    if (opts.json)
+        io.log(JSON.stringify({ dropped: true, ...r }, null, 2));
+    else {
+        u.item('pass', 'flow.json and design/pipeline.json marked dropped by the owner');
+        if (r.notes.length)
+            u.item('pass', `owner notes closed as dropped (not fixed): ${r.notes.join(', ')}`);
+        if (r.questions.length)
+            u.item('pass', `open questions closed with it: ${r.questions.join(', ')}`);
+        u.summary('pass', `dropped: "${words}". \`${T} flow\` now says the game is dropped, with no next step`);
+    }
+    return EXIT.pass;
+}
+export function judgedLine(root, fp, p = readPipeline(root)) {
+    const pipe = p ?? { version: 1, tier: 'mid', written_by: '', at: '', stages: [], notes: [] };
+    const reads = [['score', 'score'], ['critic panel', 'panel'], ['blind player', 'play'], ['world check', 'world']];
+    const below = [], met = [], unjudged = [];
+    for (const [name, kind] of reads) {
+        try {
+            const g = evaluateGate(root, { kind }, fp, pipe, 'judged');
+            if (g.state === 'failing')
+                below.push(`${name} ${g.says}`);
+            else if (g.state === 'met')
+                met.push(`${name} ${g.says}`);
+            else
+                unjudged.push(name);
+        }
+        catch {
+            unjudged.push(name);
+        }
+    }
+    try {
+        for (const l of qualityLines(firstLookQuality(root)))
+            below.push(l.replace(/; fix: .*$/, ''));
+    }
+    catch { }
+    const cap = (t) => (t.length > 160 ? `${t.slice(0, 159)}…` : t);
+    if (below.length)
+        return `Below the bar: ${below.map(cap).join('; ')}`;
+    if (met.length)
+        return `At the bar on what ran: ${met.map(cap).join('; ')}${unjudged.length ? ` (not judged yet: ${unjudged.join(', ')})` : ''}`;
+    return `Not judged yet: no ${unjudged.join(', ')} on these files`;
+}

package/dist/commands/framing.js

@@ -0,0 +1,53 @@
+import { EXIT } from "./verify.js";
+import { targetFraming } from "./compare-target.js";
+import { withPage } from "./look.js";
+import { drive, evalJson, load } from "../look/look.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { readWalk } from "../walk/routes.js";
+import { ACTORS_DOC } from "../walk/judge.js";
+import { ui } from "../ui.js";
+export function framed(actors, ids, want) {
+    return ids.map((id) => {
+        const a = actors.find((x) => x.id === id || x.node === id) ?? null;
+        const w = want[id] ?? null;
+        if (!a || !a.screen)
+            return { id, kind: a?.kind ?? '', found: !!a, on: false, box: null, share: null, want: w, verdict: 'not_observed' };
+        const s = a.screen;
+        const ok = !w || (s.share >= w[0] && s.share <= w[1]);
+        return { id, kind: a.kind, found: true, on: s.on, box: { x: s.x, y: s.y, w: s.w, h: s.h }, share: s.share, want: w, verdict: !s.on ? 'warn' : ok ? 'pass' : 'warn' };
+    });
+}
+export async function framing(opts, io = console) {
+    const u = ui(io, 'framing');
+    const r = await withPage(u, opts, async (page, t) => {
+        const { size } = targetFraming(opts.viewport, t.manifest);
+        await page.setViewportSize(size);
+        await load(page, t.url, hookMapOf(t.manifest));
+        const entered = opts.view ? (await drive(page, { view: opts.view, verbs: [], holdMs: 900, freeze: false, click: null })).view?.entered === true : true;
+        const read = await evalJson(page, 'world_actors', { max: 800 });
+        const cfg = readWalk(t.manifest);
+        const ids = opts.actors.length ? opts.actors : Object.keys(cfg.framing).length ? Object.keys(cfg.framing) : (read?.actors ?? []).filter((a) => a.kind === 'player').map((a) => a.id);
+        return { entered, source: read?.source ?? 'none', view: read?.view ?? null, size, rows: framed(read?.actors ?? [], ids, cfg.framing) };
+    });
+    if (typeof r === 'number')
+        return r;
+    const seen = r.rows.some((x) => x.found);
+    if (opts.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return seen ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`framing · ${opts.view ?? 'as loaded'} · ${opts.viewport} ${r.size.width}×${r.size.height}${r.entered ? '' : ' · VIEW NOT ENTERED'} · actors from ${r.source}`);
+    for (const x of r.rows) {
+        if (!x.found) {
+            u.item('not_observed', `${x.id}: not in the actors contract`);
+            continue;
+        }
+        if (!x.box) {
+            u.item('not_observed', `${x.id}: no screen box (no camera, or no height)`);
+            continue;
+        }
+        u.item(x.verdict, `${x.id}: ${x.on ? '' : 'OFF SCREEN · '}${Math.round((x.share ?? 0) * 100)}% of the frame height, box ${x.box.w}×${x.box.h} at (${x.box.x}, ${x.box.y})${x.want ? ` — the plan wants ${Math.round(x.want[0] * 100)}–${Math.round(x.want[1] * 100)}%` : ''}`);
+    }
+    u.summary(seen ? (r.rows.some((x) => x.verdict === 'warn') ? 'warn' : 'pass') : 'not_observed', seen ? 'tune the camera against these numbers, then capture once' : `none of the actors were found: expose window.__FPX_ACTORS__() — ${ACTORS_DOC}`);
+    return seen ? EXIT.pass : EXIT.not_observed;
+}