@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/claude/hooks/pipeline.mjs

@@ -0,0 +1,207 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentFingerprint, readState, sessionStartMs, writeState } from './lib.mjs';
+import { atStop as progressAtStop, cadence, cardPrompt } from './vendor/progress/progress.mjs';
+import { defaultPipeline, evaluate, forbidsBuild, gatesWithoutEvidence, ownerGateItems, PIPELINE_FILE, readPipeline, SESSION_RULE, stageBlock } from './vendor/pipeline/pipeline.mjs';
+import { FLOW_FILE, PLAN_STAGE_IDS, planAgreement } from './vendor/flow/flow.mjs';
+export const PIPELINE_EVERY = 30;
+function tierOf(root) {
+    try {
+        const t = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).production?.tier;
+        return t === 'mid' || t === 'deep' ? t : 'small';
+    }
+    catch {
+        return 'small';
+    }
+}
+export function beforeSignOff(root) {
+    if (!root || !(existsSync(join(root, FLOW_FILE)) || existsSync(join(root, 'design', 'GDD.md'))))
+        return false;
+    try {
+        return planAgreement(root).agreed !== true;
+    }
+    catch {
+        return true;
+    }
+}
+export const holdLine = (n) => `waiting on the owner: their note ${n.id} holds the stage: "${n.text.slice(0, 160)}${n.text.length > 160 ? '…' : ''}" (theirs to release; never a step to close)`;
+export async function pipelineEval(root) {
+    const file = readPipeline(root);
+    const p = file ?? defaultPipeline(tierOf(root), new Date(), 'the tier default (not written yet)');
+    const fp = await currentFingerprint(root).catch(() => null);
+    let agreed = false;
+    try {
+        agreed = planAgreement(root).agreed === true;
+    }
+    catch { }
+    return { e: evaluate(root, p, fp, undefined, { agreed }), written: Boolean(file) };
+}
+export async function pipelineContext(root, input) {
+    if (!readPipeline(root))
+        return `- path: no ${PIPELINE_FILE} yet: \`npx @funpixel/tools flow\` writes this game's stages and gates (sized to its tier) and prints the one next step`;
+    const { e } = await pipelineEval(root);
+    if (input)
+        writeState(input, { ...readState(input), pipeKey: stageKey(e), pipeSig: recordsSig(root), pipeSaidAt: readState(input).pipeCalls ?? 0, pipeStage: e.current?.stage.id ?? 'done' });
+    return stageBlock(e);
+}
+export const stageKey = (e) => `${e.current?.stage.id ?? 'done'}|${e.next.step}|${e.openNotes.map((n) => n.id).join(',')}`;
+const RECORDS = ['verify.json', PIPELINE_FILE, join('.funtools', 'sim.json'), join('.funtools', 'tests.json'), join('.funtools', 'hook.json'), join('.funtools', 'life.json'), join('.funtools', 'walk.json'), join('.funtools', 'boxes.json'), join('design', 'look', 'scores.json'), join('.funtools', 'playtest', 'history.json'), join('design', 'GDD.md'), join('design', 'plan.md'), join('design', 'first-look'), join('design', 'studio.json'), 'funpixel.json'];
+function recordsSig(root) {
+    return RECORDS.map((r) => { try {
+        return statSync(join(root, r)).mtimeMs;
+    }
+    catch {
+        return 0;
+    } }).join(',');
+}
+export async function pipelineReminder(input, root) {
+    if (!existsSync(join(root, PIPELINE_FILE)))
+        return null;
+    const state = readState(input);
+    const calls = (state.pipeCalls ?? 0) + 1;
+    const sig = recordsSig(root);
+    const due = calls - (state.pipeSaidAt ?? 0) >= PIPELINE_EVERY;
+    if (sig === state.pipeSig && !due) {
+        writeState(input, { ...state, pipeCalls: calls });
+        return null;
+    }
+    const { e } = await pipelineEval(root);
+    const key = stageKey(e);
+    const holds = e.holds ?? [];
+    if (holds.length || beforeSignOff(root)) {
+        const was = state.holdsSaid ?? {};
+        const fresh = holds.filter((n) => !was[n.id]);
+        writeState(input, { ...readState(input), pipeCalls: calls, pipeSig: sig, pipeKey: key, pipeSaidAt: calls, pipeStage: e.current?.stage.id ?? 'done', holdsSaid: { ...was, ...Object.fromEntries(fresh.map((n) => [n.id, 1])) } });
+        return fresh.length ? `Funpixel: ${fresh.map(holdLine).join('\n')}` : null;
+    }
+    const moved = key !== state.pipeKey;
+    if (!moved && !due) {
+        writeState(input, { ...readState(input), pipeCalls: calls, pipeSig: sig, pipeKey: key });
+        return null;
+    }
+    const stage = e.current?.stage.id ?? 'done';
+    const stageMoved = state.pipeStage !== undefined && stage !== state.pipeStage;
+    writeState(input, { ...readState(input), pipeCalls: calls, pipeSig: sig, pipeKey: key, pipeSaidAt: calls, pipeStage: stage, ...(stageMoved ? { stageMovedAt: Date.now(), stageFrom: state.pipeStage } : {}) });
+    const block = stageBlock(e, { heading: moved ? 'The path moved' : 'Still on the path' });
+    return stageMoved ? `${block}\n${cardPrompt(state.pipeStage)}` : block;
+}
+export function progressCadence(input, root, now = Date.now()) {
+    if (!existsSync(join(root, PIPELINE_FILE)))
+        return null;
+    const state = readState(input);
+    if (state.pipeStage === 'done')
+        return null;
+    const r = cadence(root, { now, start: sessionStartMs(input), stageMovedAt: state.stageMovedAt, stage: state.pipeStage ?? null, said: state.progressSaid ?? {}, spoke: state.spokeAt });
+    if (!r.lines.length)
+        return null;
+    writeState(input, { ...readState(input), progressSaid: { ...(state.progressSaid ?? {}), ...Object.fromEntries(r.said.map((k) => [k, true])) } });
+    return r.lines.join('\n');
+}
+const BG_TOOLS = /^(Bash|Agent|Task)$/;
+const DONE_TOOLS = /^(KillShell|KillBash|TaskStop)$/;
+export function recordBackground(input) {
+    const name = String(input.tool_name ?? '');
+    const ti = input.tool_input ?? {};
+    const tr = input.tool_response ?? {};
+    const state = readState(input);
+    const jobs = { ...(state.bgJobs ?? {}) };
+    if (BG_TOOLS.test(name) && ti.run_in_background === true) {
+        const said = typeof tr === 'string' ? tr : JSON.stringify(tr);
+        const id = tr.backgroundTaskId ?? tr.agentId ?? tr.task_id ?? /background with ID:\s*([\w-]+)/.exec(said)?.[1] ?? /agentId:\s*([\w-]+)/.exec(said)?.[1] ?? input.tool_use_id ?? `bg-${Date.now()}`;
+        jobs[id] = { what: String(ti.description ?? ti.command ?? ti.prompt ?? name).replace(/\s+/g, ' ').slice(0, 120), tool: name, at: Date.now() };
+    }
+    else if (DONE_TOOLS.test(name)) {
+        const id = ti.shell_id ?? ti.bash_id ?? ti.task_id ?? ti.id;
+        if (id && jobs[id])
+            jobs[id] = { ...jobs[id], done: true };
+    }
+    else if (/^(TaskOutput|BashOutput)$/.test(name)) {
+        const id = ti.task_id ?? ti.bash_id ?? ti.shell_id;
+        const said = typeof tr === 'string' ? tr : JSON.stringify(tr);
+        if (id && jobs[id] && /\b(status["':\s]+(completed|failed|killed|stopped)|exit code|exited with)\b/i.test(said))
+            jobs[id] = { ...jobs[id], done: true };
+    }
+    else
+        return false;
+    writeState(input, { ...readState(input), bgJobs: jobs });
+    return true;
+}
+export function finishedInTranscript(path) {
+    const done = new Set();
+    if (!path || !existsSync(path))
+        return done;
+    let text = '';
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return done;
+    }
+    for (const m of text.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)) {
+        const body = m[1].replace(/\\n/g, '\n').replace(/\\"/g, '"');
+        const id = /<task-id>\s*([\w-]+)\s*<\/task-id>/.exec(body)?.[1];
+        const status = /<status>\s*(\w+)\s*<\/status>/.exec(body)?.[1];
+        if (id && (!status || /^(completed|failed|killed|stopped|error)$/i.test(status)))
+            done.add(id);
+    }
+    return done;
+}
+const AGENT = /^(\S*\/)?(claude|codex|kiro(-cli)?|cursor(-agent)?|gemini|amp|opencode|robin)(\s|$)|@anthropic-ai\/claude-code|\/claude-code\/|\.claude\/local\/claude/;
+const PROGRAM = /^(\S*\/)?(node|npx|tsx|bun|pnpm|npm|yarn|funtools)(\s|$)/;
+export function runningJobs(root, ps = () => spawnSync('ps', ['-Ao', 'pid=,ppid=,command='], { encoding: 'utf8' }).stdout ?? '', self = process.pid) {
+    let out = '';
+    try {
+        out = ps();
+    }
+    catch {
+        return [];
+    }
+    const long = /(@funpixel\/tools|funtools|bin\.ts)\s+(play|playtest|hook|life|walk|trailer|reel|capture|profile|journey|sim|score|gen|assets|mobile-qa|phone|compare-takes|boxes)\b/;
+    const rows = out.split('\n').map((l) => {
+        const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(l) ?? /^\s*(\d+)\s+()(.*)$/.exec(l);
+        return m ? { pid: Number(m[1]), ppid: m[2] === '' ? null : Number(m[2]), cmd: m[3].trim() } : null;
+    }).filter(Boolean);
+    const parent = new Map(rows.filter((r) => r.ppid !== null).map((r) => [r.pid, r.ppid]));
+    const mine = new Set();
+    for (let p = self, i = 0; p && i < 64 && !mine.has(p); i++) {
+        mine.add(p);
+        p = parent.get(p) ?? (p === self ? process.ppid : null);
+    }
+    return rows.filter((r) => !mine.has(r.pid) && !AGENT.test(r.cmd) && PROGRAM.test(r.cmd) && long.test(r.cmd) && r.cmd.includes(root))
+        .map((r) => r.cmd.slice(0, 140));
+}
+export function stillRunning(input, root, ps) {
+    const jobs = readState(input).bgJobs ?? {};
+    const finished = finishedInTranscript(input.transcript_path);
+    const open = Object.entries(jobs).filter(([id, j]) => !j.done && !finished.has(id)).map(([id, j]) => `${j.tool === 'Bash' ? 'background command' : 'subagent'} ${id}: ${j.what}`);
+    return [...open, ...runningJobs(root, ps).map((c) => `a funtools job is still running: ${c}`)];
+}
+export const BACKGROUND_WARNING = (lines) => `STOP: work is still running in the background, and a session that ends does not come back.\n${lines.map((l) => `- ${l}`).join('\n')}\nWait for it (read its output, or wait for its notification) and use what it made before you end; if it is no longer needed, stop it on purpose and say so. ${SESSION_RULE}`;
+export async function pipelineAtStop(input, root, ps) {
+    const running = stillRunning(input, root, ps);
+    let e = null;
+    try {
+        if (readPipeline(root))
+            e = (await pipelineEval(root)).e;
+    }
+    catch { }
+    const holds = e?.holds ?? [];
+    const forbidden = holds[0] ?? (e?.current && !PLAN_STAGE_IDS.includes(e.current.stage.id) ? e.openNotes.find((n) => n.by === 'owner' && forbidsBuild(n)) : null);
+    const gates = e && !forbidden ? gatesWithoutEvidence(e) : [];
+    const owner = e ? ownerGateItems(e) : [];
+    const notes = e ? e.openNotes.filter((n) => n.by === 'owner' && !holds.includes(n)).map((n) => `the owner's note ${n.id} [${n.stage}] is open${n === forbidden ? ` and forbids the build, so ${e.current.stage.title}'s gates wait for the owner's word` : ''}: "${n.text.slice(0, 140)}"`) : [];
+    const state = readState(input);
+    let progress = [];
+    try {
+        if (e)
+            progress = progressAtStop(root, { stageMovedAt: state.stageMovedAt, stage: e.current?.stage.id ?? null, now: Date.now() });
+    }
+    catch { }
+    return { running, gates, owner, notes: [...notes, ...progress], holds: holds.map(holdLine), holdIds: holds.map((n) => n.id), stage: e?.current?.stage.title ?? null, planned: e ? plannedKinds(e) : new Set() };
+}
+export function plannedKinds(e) {
+    const upTo = e.current?.index ?? Infinity;
+    return new Set(e.stages.filter((s) => !s.skipped && s.index <= upTo).flatMap((s) => s.stage.gates.map((g) => g.kind)));
+}
+export const ROUND_ASK = (stage, lines) => `Before you hand back: the current stage (${stage}) has gates without evidence:\n${lines.map((l) => `- ${l}`).join('\n')}\nA round is not done without evidence. Close them now if this session was meant to, or say plainly in the hand-back which gates are open and why. Asked once; \`npx @funpixel/tools flow\` shows the step.`;

package/plugins/claude/hooks/prompt.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { client, findGameRoot, forHost, readInput, readState, startDir, writeState, isMain } from './lib.mjs';
+import { flowBeat } from './flow.mjs';
+import { outsideChanges } from './memory.mjs';
+import { scopeSignal } from './scope.mjs';
+import { reachContext, skillsFor } from './reach.mjs';
+export function remember(input, now = Date.now()) {
+    const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+    const state = readState(input);
+    const next = { ...state, spokeAt: now, lastPrompt: prompt.slice(0, 2000) };
+    if (prompt && !state.firstPrompt)
+        next.firstPrompt = prompt.slice(0, 4000);
+    const asked = scopeSignal(prompt);
+    if (asked && state.completeAsked !== 'command')
+        next.completeAsked = asked;
+    writeState(input, next);
+}
+export function firstPromptReach(input) {
+    const state = readState(input);
+    if (state.reachAtPrompt)
+        return null;
+    const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+    writeState(input, { ...state, reachAtPrompt: true });
+    if (!prompt)
+        return null;
+    const root = findGameRoot(startDir(input));
+    const named = new Set(state.reachNamed ?? []);
+    const picks = skillsFor(root, prompt).filter((p) => !named.has(p.skill) && p.skill !== 'funpixel-game-feel');
+    if (!picks.length)
+        return null;
+    writeState(input, { ...readState(input), reachNamed: [...named, ...picks.map((p) => p.skill)] });
+    return reachContext(picks, named.size ? 'your first message' : 'your first message and the folder');
+}
+export async function betweenTurns(input) {
+    const root = findGameRoot(startDir(input));
+    return root ? outsideChanges(root) : null;
+}
+async function main() {
+    const input = await readInput();
+    remember(input);
+    flowBeat(findGameRoot(startDir(input)), 'work');
+    const reach = client(input) === 'cursor' ? null : firstPromptReach(input);
+    const moved = [reach, await betweenTurns(input)].filter(Boolean).join('\n\n') || null;
+    if (client(input) === 'cursor')
+        process.stdout.write(JSON.stringify({ continue: true }));
+    else if (moved)
+        process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: forHost(moved) } }));
+}
+if (isMain(import.meta.url)) {
+    main().catch((e) => process.stderr.write(`funpixel prompt: ${e instanceof Error ? e.message : e}\n`));
+}

package/plugins/claude/hooks/quality.mjs

@@ -0,0 +1,310 @@
+export const GDD_MISSING = 3;
+export function gddNote(note) {
+    if (!note)
+        return '';
+    const g = scoreGdd(note);
+    const missing = thinSections(g).filter((k) => g.sections[k].score === 0).map(sectionLabel);
+    const invention = /^##\s+(the\s+)?invention\b/im.test(note);
+    if (missing.length < GDD_MISSING)
+        return '';
+    return `Advisory, never blocking: ${invention ? '' : 'the design document has no ## The invention (six forcing questions answered for this game, before the template). '}${missing.length >= GDD_MISSING ? `Sections missing: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ` and ${missing.length - 5} more` : ''}. ` : ''}\`npx @funpixel/tools gdd\` lists them (skill funpixel-gdd); the creator decides what this game needs.`;
+}
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { declaredViews, heroMakeFloor, momentFloor, motionFloor, phoneLayoutFloor, playerFloor, testSuiteItem, viewFloors } from './floors.mjs';
+import { codexPanel, panelScore } from './critic-receipts.mjs';
+import { adRules, agreedSilence, fixRound, inFixRound, juiceGaps, readNote } from './note.mjs';
+import { completeGameScope, markComplete } from './scope.mjs';
+import { scoreGdd, sectionLabel, thinSections } from './vendor/gdd/rubric.mjs';
+export { adRules, juiceGaps };
+export const PANEL_OVERALL = 6.0;
+export const PANEL_LOOK = 7.0;
+export const PERSONAS = { veteran: 'veteran player', ux: 'UX designer', skeptic: 'skeptic' };
+const TARGETS = ['design', 'assets'].flatMap((d) => ['target', 'style-frame'].flatMap((n) => ['png', 'jpg', 'jpeg', 'webp'].map((x) => `${d}/${n}.${x}`)));
+const GRAYBOX = /\b(gr[ae]y[- ]?box(ed|ing)?|white[- ]?box|block[- ]?out|prototype|placeholder (art|graphics|shapes)|programmer art|no art|without (any )?art)\b/i;
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const transcriptText = (input) => {
+    const t = input.transcript_path;
+    return t && existsSync(t) ? readFileSync(t, 'utf8') : '';
+};
+function* transcriptRecords(input) {
+    for (const line of transcriptText(input).split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            yield JSON.parse(line);
+        }
+        catch { }
+    }
+}
+const textOf = (c) => (typeof c === 'string' ? c : Array.isArray(c) ? c.map((b) => (typeof b === 'string' ? b : b?.text ?? '')).join('\n') : '');
+export function firstPrompt(input, state) {
+    if (state.firstPrompt)
+        return state.firstPrompt;
+    for (const r of transcriptRecords(input)) {
+        const c = r.message?.content;
+        if (r.type === 'user' && (typeof c === 'string' || (Array.isArray(c) && c.some((b) => b?.type === 'text'))))
+            return textOf(c);
+    }
+    return '';
+}
+export function lastPrompt(input, state) {
+    if (typeof state.lastPrompt === 'string')
+        return state.lastPrompt;
+    let last = '';
+    for (const r of transcriptRecords(input)) {
+        const c = r.message?.content;
+        if (r.type !== 'user' || !(typeof c === 'string' || (Array.isArray(c) && c.some((b) => b?.type === 'text'))))
+            continue;
+        const text = textOf(c).trim();
+        if (text && !text.startsWith('<'))
+            last = text;
+    }
+    return last;
+}
+export function lastAssistantText(input) {
+    if (typeof input.last_assistant_message === 'string')
+        return input.last_assistant_message;
+    if (typeof input.assistant_response === 'string')
+        return input.assistant_response;
+    let last = '';
+    for (const r of transcriptRecords(input)) {
+        if (r.type !== 'assistant' || !Array.isArray(r.message?.content))
+            continue;
+        const text = r.message.content.filter((b) => b?.type === 'text').map((b) => b.text).join('\n');
+        if (text.trim())
+            last = text;
+    }
+    return last;
+}
+export const isGraybox = (input, root, state) => existsSync(join(root, '.funtools', 'graybox')) || GRAYBOX.test(firstPrompt(input, state));
+export const buildsTheGame = (state, root) => Boolean(completeGameScope(state, root));
+const isImage = (p) => {
+    try {
+        const b = readFileSync(p).subarray(0, 12);
+        return (b[0] === 0x89 && b[1] === 0x50) || (b[0] === 0xff && b[1] === 0xd8) || b.subarray(8, 12).toString() === 'WEBP';
+    }
+    catch {
+        return false;
+    }
+};
+const failed = (r) => r && typeof r === 'object' && (r.isError === true || r.is_error === true);
+const strings = (v, out = []) => {
+    if (typeof v === 'string')
+        out.push(v);
+    else if (Array.isArray(v))
+        v.forEach((x) => strings(x, out));
+    else if (v && typeof v === 'object')
+        Object.values(v).forEach((x) => strings(x, out));
+    return out;
+};
+function personaOf(verdict, request) {
+    const hay = `${verdict?.persona ?? ''} ${verdict?.persona ? '' : request}`.toLowerCase();
+    if (/veteran/.test(hay))
+        return 'veteran';
+    if (/\bux\b|ux designer/.test(hay))
+        return 'ux';
+    if (/skeptic|sceptic/.test(hay))
+        return 'skeptic';
+    return null;
+}
+function jsonIn(text) {
+    const out = [];
+    for (const m of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)) {
+        try {
+            out.push(JSON.parse(m[1]));
+        }
+        catch { }
+    }
+    if (!out.length) {
+        const start = text.search(/[[{]/);
+        const end = Math.max(text.lastIndexOf('}'), text.lastIndexOf(']'));
+        if (start >= 0 && end > start) {
+            try {
+                out.push(JSON.parse(text.slice(start, end + 1)));
+            }
+            catch { }
+        }
+    }
+    return out.flat();
+}
+const meanOf = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+export function panelVerdict(reply, request = '') {
+    const surfaces = jsonIn(reply).filter((v) => v && typeof v === 'object' && v.scores);
+    return panelScore(surfaces.map((s) => ({ ...s, persona: personaOf(s, request) })));
+}
+const isCriticCall = (input) => (/^(Task|Agent)$/.test(input.tool_name ?? '') && /critic/i.test(String(input.tool_input?.subagent_type ?? input.tool_input?.agent ?? '')))
+    || (/^(subagent|use_subagent|agent_crew)$/.test(input.tool_name ?? '') && (input.tool_input?.stages ?? []).some((st) => /critic/i.test(`${st?.name ?? ''} ${st?.prompt_template ?? ''}`)));
+export function recordToolUse(input, state, now) {
+    if (failed(input.tool_response))
+        return state;
+    if (isCriticCall(input)) {
+        const v = panelVerdict(strings(input.tool_response).join('\n'), strings(input.tool_input).join('\n'));
+        if (v)
+            return { ...state, panel: [...(state.panel ?? []), { ...v, at: now }] };
+        if (input.tool_input?.run_in_background === true || /async agent launched|running in the background/i.test(strings(input.tool_response).join('\n'))) {
+            return { ...state, backgroundCritics: (state.backgroundCritics ?? 0) + 1 };
+        }
+    }
+    return state;
+}
+function transcriptPanel(input) {
+    const calls = new Map();
+    const out = [];
+    for (const r of transcriptRecords(input)) {
+        for (const b of Array.isArray(r.message?.content) ? r.message.content : []) {
+            if (b?.type === 'tool_use' && isCriticCall({ tool_name: b.name, tool_input: b.input }))
+                calls.set(b.id, strings(b.input).join('\n'));
+            if (b?.type === 'tool_result' && calls.has(b.tool_use_id) && !b.is_error) {
+                const v = panelVerdict(textOf(b.content), calls.get(b.tool_use_id));
+                if (v)
+                    out.push({ ...v, at: Date.parse(r.timestamp ?? '') || 0 });
+            }
+        }
+    }
+    return out;
+}
+function captures(root, fingerprint) {
+    const fresh = Object.values(readJson(join(root, '.funtools', 'capture', 'index.json')) ?? {})
+        .filter((c) => c && c.entered === true && c.fingerprint === fingerprint);
+    const views = (vp) => new Set(fresh.filter((c) => c.viewport === vp).map((c) => c.view));
+    const desktop = views('desktop'), phone = views('phone');
+    return {
+        desktop: desktop.size > 0,
+        phone: phone.size > 0,
+        oneSize: [...new Set([...desktop, ...phone])].filter((v) => !desktop.has(v) || !phone.has(v)).sort(),
+        latest: Math.max(0, ...fresh.map((c) => Date.parse(c.at) || 0)),
+    };
+}
+function panelSince(input, state, since, root, fingerprint) {
+    const records = [...(state.panel?.length ? state.panel : transcriptPanel(input)), ...codexPanel(root, fingerprint)]
+        .filter((p) => p.at >= since).sort((a, b) => a.at - b.at);
+    const latest = {};
+    for (const p of records)
+        latest[p.persona] = p;
+    return latest;
+}
+const CAPTURE = 'npx @funpixel/tools capture --all';
+const NOT_OBSERVED = /\b(not observed|unobserved|unseen|could not (see|observe|hear|check|judge)|was not (seen|observed|judged)|wasn'?t (seen|observed|judged))\b/i;
+export const qualityItems = (...args) => qualityReport(...args).items;
+export function qualityReport(input, root, state, fingerprint, verified, atStop) {
+    const report = { items: [], deferred: [], unseen: [], notes: [], tags: new Map(), scope: completeGameScope(state, root), done: false };
+    if (!report.scope)
+        return report;
+    markComplete(root, report.scope);
+    const { items, deferred, unseen } = report;
+    const add = (text, kind, fault = false) => { items.push(text); report.tags.set(text, { kind, fault }); };
+    if (isGraybox(input, root, state)) {
+        if (!atStop)
+            return report;
+        const said = lastAssistantText(input);
+        if (said && !(/gr[ae]y[- ]?box/i.test(said) && /stand-?in/i.test(said))) {
+            add('This is a gray-box: say "gray-box" in the hand-back and list every stand-in (each code shape and what art will replace it).', 'handback');
+        }
+        return report;
+    }
+    const target = TARGETS.find((t) => existsSync(join(root, t)) && isImage(join(root, t)));
+    if (!target) {
+        add('No target frame yet. Save an authored, procedural or generated composition as design/target.png at the game aspect (skill funpixel-art). It states the intended look; the captures and the panel then show how close the game comes.', 'targets');
+    }
+    const note = readNote(root);
+    const thinDoc = atStop ? gddNote(note) : '';
+    if (thinDoc)
+        report.notes.push(thinDoc);
+    const juice = note === null ? '' : juiceGaps(note);
+    if (note === null) {
+        add('No design note. Write design/GDD.md from the funpixel-gdd template (v0.1; an older design/README.md counts): the core loop in one sentence, five AD rules a viewer can check in one frame, and the juice table (skill funpixel-game-feel). The panel receives its AD rules, not the full note.', 'gdd');
+    }
+    else if (adRules(note) < 5) {
+        add(`The design note has ${adRules(note)} AD rule(s) under \`## AD rules\`; the panel scores the look against five rules a viewer can check in one frame (skill funpixel-art).`, 'gdd');
+    }
+    const suite = testSuiteItem(root, fingerprint);
+    if (suite)
+        add(suite, 'tests', /^The rules suite FAILED/.test(suite));
+    if (juice) {
+        add(`The design note has ${juice}. Fill \`## Juice\` in the design document (design/GDD.md): one row per event the player causes or suffers, with a visible response and an audio choice (including intentional silence), then build it (skill funpixel-game-feel).`, 'gdd');
+    }
+    if (!verified && !atStop)
+        return report;
+    const rounds = fixRound(note ?? '');
+    const player = playerFloor(root, fingerprint);
+    if (player.findings.length && rounds.length && player.findings.every((f) => inFixRound(rounds, f))) {
+        deferred.push(`phone player: ${player.findings.join('; ')}`);
+    }
+    else
+        for (const t of player.items)
+            add(t, 'play', player.findings.length > 0);
+    const silent = agreedSilence(firstPrompt(input, state), note);
+    const audio = readJson(join(root, 'verify.json'))?.report?.audio;
+    if (verified && !silent && audio?.observed === true && audio.declared !== true) {
+        add('Verify could not hear the game: it never declares window.__FPX_AUDIO__, so nothing proved it makes a sound. Implement the promised cues, declare __FPX_AUDIO__, mark each sounding check "sound": true, and verify again (skill funpixel-audio). A silent design is recorded as `Sound: none` in the design note.', 'verify');
+    }
+    if (verified && !silent && audio && audio.observed !== true)
+        unseen.push('sound (verify could not listen)');
+    const shots = captures(root, fingerprint);
+    if (!shots.desktop || !shots.phone || shots.oneSize.length) {
+        const which = shots.oneSize.length ? ` (${shots.oneSize.join(', ')} ${shots.oneSize.length > 1 ? 'were' : 'was'} shot at one size only)` : '';
+        add(`No fresh captures of every view at both sizes${which}: after the last change, run \`${CAPTURE}\` (every declared view, desktop and phone, one command); the critic panel then judges those frames (skill funpixel-verify).`, 'panel');
+        return report;
+    }
+    const index = readJson(join(root, '.funtools', 'capture', 'index.json'));
+    for (const t of viewFloors(declaredViews(index, fingerprint), note ?? ''))
+        add(t, 'screens');
+    for (const t of momentFloor(index, fingerprint))
+        add(t, 'panel');
+    const motion = motionFloor(readJson(join(root, '.funtools', 'scene', 'motion.json')), fingerprint, note, root);
+    for (const t of motion.items)
+        add(t, 'life', motion.fault);
+    unseen.push(...motion.unseen);
+    const layout = phoneLayoutFloor(readJson(join(root, '.funtools', 'capture', 'audit.json')), fingerprint);
+    for (const t of layout.items)
+        add(t, 'phone', true);
+    unseen.push(...layout.unseen);
+    const heroes = heroMakeFloor(root, readJson(join(root, '.funtools', 'look', '3d.json')), fingerprint, atStop ? lastAssistantText(input) : null);
+    for (const t of heroes.items)
+        add(t, 'handback');
+    unseen.push(...heroes.unseen);
+    const panel = panelSince(input, state, shots.latest, root, fingerprint);
+    const missing = Object.keys(PERSONAS).filter((k) => panel[k] === undefined);
+    if (missing.length) {
+        const bg = state.backgroundCritics ? ` ${state.backgroundCritics} critic run(s) went to the background, and a background verdict never reaches this check: run the seats in the foreground, four critic calls in one message (never run_in_background).` : '';
+        add(`The critic panel has not judged the latest captures: run the critic agent once per persona, blind (${missing.map((k) => PERSONAS[k]).join(', ')}), skill funpixel-verify.${bg}`, 'panel');
+        return report;
+    }
+    const seats = Object.values(panel);
+    const overall = meanOf(seats.map((p) => p.overall));
+    const look = meanOf(seats.map((p) => p.look));
+    unseen.push(...[...new Set(seats.flatMap((p) => p.unseen ?? []))].map((k) => `${k.replace(/_/g, ' ')} (critics marked it unseen)`));
+    const open = Object.entries(panel).flatMap(([k, p]) => p.open.map((issue, i) => ({ text: `${PERSONAS[k]}: ${issue}`, key: p.openKeys?.[i] ?? issue })));
+    const under = overall < PANEL_OVERALL || look < PANEL_LOOK;
+    const means = `overall mean ${overall.toFixed(2)}, look-and-feel mean ${look.toFixed(2)} (bar ${PANEL_OVERALL.toFixed(1)} / ${PANEL_LOOK.toFixed(1)})`;
+    if (open.length) {
+        const unnamed = open.filter((o) => !inFixRound(rounds, o.key));
+        if (unnamed.length) {
+            add(`The panel still has open quality findings despite its scores: ${unnamed.map((o) => o.text).join('; ')}. Fix and re-review; to hand back unfinished, record each finding by name with its next step in the design note's \`## Fix round\` table. This is not acceptance.`, 'panel');
+        }
+        else
+            deferred.push(`panel findings: ${open.map((o) => o.key).join(', ')}`);
+    }
+    if (under) {
+        if (rounds.length)
+            deferred.push(`panel under the bar: ${means}`);
+        else
+            add(`The panel's ${means}; the bar is the bar games' own (BAR.md): a fix round on its highest findings, then fresh captures and seats, is how the bar games got there (5 to 14 panels each). If you stop before it passes, record the round still to run in the design note's \`## Fix round\` table (| Finding | Next step |).`, 'panel');
+    }
+    if (atStop && unseen.length) {
+        const said = lastAssistantText(input);
+        const word = (u) => (u.startsWith('motion') ? 'motion' : u.split(' (')[0]).toLowerCase();
+        const missed = unseen.filter((u) => !said.toLowerCase().includes(word(u)));
+        if (!NOT_OBSERVED.test(said) || missed.length) {
+            add(`Nothing observed these, so the checks are quiet about them, not satisfied: ${unseen.join('; ')}. Say in the hand-back that each was not observed (and how to observe it), or observe it now.`, 'handback');
+        }
+    }
+    report.done = atStop && verified && !items.length && !deferred.length;
+    return report;
+}

package/plugins/claude/hooks/reach.mjs

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const read = (p, max = 120_000) => {
+    try {
+        return statSync(p).isFile() ? readFileSync(p, 'utf8').slice(0, max) : '';
+    }
+    catch {
+        return '';
+    }
+};
+const manifestOf = (root) => { try {
+    return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'));
+}
+catch {
+    return {};
+} };
+export function designText(root) {
+    if (!root)
+        return '';
+    return ['plan.md', 'GDD.md', 'README.md'].map((f) => read(join(root, 'design', f))).join('\n');
+}
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+export function targetFrames(root) {
+    if (!root)
+        return [];
+    const out = [];
+    for (const sub of ['first-look', 'targets']) {
+        const dir = join(root, 'design', sub);
+        try {
+            for (const f of readdirSync(dir))
+                if (IMAGE.test(f))
+                    out.push(`design/${sub}/${f}`);
+        }
+        catch { }
+    }
+    try {
+        for (const f of readdirSync(join(root, 'design')))
+            if (IMAGE.test(f) && /target|key.?art|style.?frame/i.test(f))
+                out.push(`design/${f}`);
+    }
+    catch { }
+    return out;
+}
+export function is3d(root) {
+    const m = manifestOf(root).metadata ?? {};
+    if (String(m.dimension ?? '').toLowerCase() === '3d' || /^three/i.test(String(m.framework ?? '')))
+        return true;
+    try {
+        return /"three"\s*:/.test(readFileSync(join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+const STORY = /\b(story|chapters?|dialogue|narrat\w+|cutscene|characters? (who|that) (say|speak|talk)|npcs?|quest|lines? (said|spoken)|voice[ds]?|prologue|epilogue)\b/i;
+const WORLD = /\b(world|places?|landscape|environment|atmosphere|biomes?|living world|creatures?|weather)\b/i;
+const LIVING = /\b(people|folk|townsfolk|villagers?|crowds?|npcs?|creatures?|animals?|wildlife|birds?|flocks?|herds?|living world|town|village|market|harbou?r|port)\b/i;
+const LOOK = /\b(target frames?|key ?art|style (block|frame|bible)|first look|look like|art direction|identity lock|reference sheets?|title (screen|scene))\b/i;
+const BIG = /\b(chapters?|levels?|runs?|acts?|episodes?|campaign|hours? of play|\d{2,} ?min(utes)?)\b/gi;
+export function skillsFor(root, prompt = '') {
+    const m = manifestOf(root);
+    const design = designText(root);
+    const text = `${design}\n${prompt}`;
+    const frames = targetFrames(root);
+    const three = root ? is3d(root) : /\b3d\b|three\.?js/i.test(prompt);
+    const tier = m.production?.tier;
+    const big = tier === 'mid' || tier === 'deep' || design.split(/\s+/).length > 4000 || (text.match(BIG) ?? []).length >= 6;
+    const picks = [];
+    if (frames.length || LOOK.test(text)) {
+        picks.push({ skill: 'funpixel-art', ref: null, why: frames.length ? `the plan pins ${frames.length} target picture(s) (${frames.slice(0, 2).join(', ')}${frames.length > 2 ? ', …' : ''}): the look from them, the identity lock, the title and HUD as art` : 'the look is part of the request: the style frame, the identity lock, the title and HUD as art' });
+    }
+    if (three) {
+        picks.push({ skill: 'funpixel-3d', ref: 'references/painted-target.md', why: 'a 3D world: camera at the target\'s framing, haze matched to the sky, ground in layers, a backdrop, a light rig, ambient motion, and a 2D hero that stays in one piece' });
+    }
+    if (STORY.test(text) || WORLD.test(design)) {
+        picks.push({ skill: 'funpixel-world-and-story', ref: LIVING.test(text) || three ? 'references/living-world.md' : null, why: 'a place with people and a story: people on task loops and creatures with gaits in the first minutes (never the hero\'s face on a crowd), a sound bed, beats as data, lines said by someone' });
+    }
+    if (big)
+        picks.push({ skill: 'funpixel-gdd', ref: 'references/production-tiers.md', why: `a bigger game${tier ? ` (production.tier ${tier})` : ''}: how far directing, consistency and the QA loop turn up at this size` });
+    if (picks.length < 2)
+        picks.push({ skill: 'funpixel-game-feel', ref: null, why: 'how each action answers: timings, payoffs, the feel table' });
+    return picks.slice(0, 4);
+}
+export function reachContext(picks, from) {
+    if (!picks.length)
+        return null;
+    const lines = picks.map((p) => `- \`${p.skill}\`${p.ref ? ` → ${p.ref}` : ''}: ${p.why}`);
+    return `## Skills this game needs (read from ${from})\n`
+        + 'Each loads in one Skill call (or read its SKILL.md in .agents/skills/funpixel-<name>/); load it before the first edit in its area. '
+        + 'They hold what earlier games learned the hard way; the choices stay yours.\n'
+        + `${lines.join('\n')}\n`
+        + 'The hook: the title and the first minutes of play decide whether people keep playing; the world, life, animation and the real assets land there first (`npx @funpixel/tools hook` reads them).';
+}