@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/hooks/lib.mjs

@@ -0,0 +1,362 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fingerprintOfDigests, HashBudgetExceeded, stagedDigests } from './vendor/verify/fingerprint.mjs';
+import { toClaudeNames } from './vendor/find/names.mjs';
+import { frontDoorItem } from './front-door.mjs';
+import { completeGameScope } from './scope.mjs';
+import { isGraybox, lastAssistantText, qualityReport } from './quality.mjs';
+let hostNames;
+export function skillNames() {
+    if (hostNames === undefined) {
+        try {
+            hostNames = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'skill-names.json'), 'utf8')).names ?? null;
+        }
+        catch {
+            hostNames = null;
+        }
+    }
+    return hostNames;
+}
+export const forHost = (text) => {
+    const names = skillNames();
+    return names && typeof text === 'string' ? toClaudeNames(text, names) : text;
+};
+export function skillNamesLine() {
+    const names = skillNames();
+    if (!names)
+        return null;
+    const odd = Object.entries(names).filter(([long, short]) => long !== `funpixel-${short}`)
+        .map(([long, short]) => `\`.agents/skills/${long}/\` is \`fp:${short}\``);
+    return '- skill names: in Claude Code a kit skill is `fp:<name>`; funtools, AGENTS.md and the folders under '
+        + '.agents/skills say `funpixel-<name>` for the same skill'
+        + (odd.length ? `. Named apart because a command has the short name: ${odd.join(', ')}` : '');
+}
+export function isMain(metaUrl) {
+    try {
+        return Boolean(process.argv[1]) && realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+export async function readInput() {
+    let raw = '';
+    for await (const chunk of process.stdin)
+        raw += chunk;
+    try {
+        return raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+const KIRO_EVENTS = /^(agentSpawn|userPromptSubmit|preToolUse|postToolUse|stop)$/;
+export function client(input) {
+    if (input.cursor_version || input.conversation_id)
+        return 'cursor';
+    return KIRO_EVENTS.test(String(input.hook_event_name ?? '')) ? 'kiro' : 'claude';
+}
+export function deferForKiro(input, key, text) {
+    writeState(input, { ...readState(input), [key]: text });
+}
+export function takeDeferred(input) {
+    const state = readState(input);
+    const out = [state.pendingGate ?? state.pendingNudge].filter(Boolean);
+    if (out.length)
+        writeState(input, { ...state, pendingGate: undefined, pendingNudge: undefined });
+    return out;
+}
+export const ANONYMOUS_TTL_MS = 6 * 60 * 60 * 1000;
+export function sessionId(input) {
+    const id = input.session_id || input.conversation_id || process.env.KIRO_SESSION_ID;
+    if (id)
+        return String(id).replace(/[^\w.-]/g, '_');
+    return `anon-${createHash('sha256').update(String(startDir(input))).digest('hex').slice(0, 16)}`;
+}
+export function startDir(input) {
+    return input.cwd || (Array.isArray(input.workspace_roots) && input.workspace_roots[0]) || process.cwd();
+}
+export function findGameRoot(from) {
+    let dir = from;
+    for (;;) {
+        if (existsSync(join(dir, 'funpixel.json')))
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+export function gatePolicy(root) {
+    const env = process.env.FUNPIXEL_GDK_GATE;
+    if (env === 'off' || env === 'warn' || env === 'block')
+        return env;
+    try {
+        const g = JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).gdk?.gate;
+        if (g === 'off' || g === 'warn' || g === 'block')
+            return g;
+    }
+    catch {
+    }
+    return 'warn';
+}
+function stateFile(input) {
+    const base = process.env.CLAUDE_PLUGIN_DATA || process.env.PLUGIN_DATA || join(tmpdir(), 'funpixel-gdk');
+    mkdirSync(base, { recursive: true });
+    return join(base, `session-${sessionId(input)}.json`);
+}
+export function readState(input) {
+    try {
+        const file = stateFile(input);
+        if (sessionId(input).startsWith('anon-') && Date.now() - statSync(file).mtimeMs > ANONYMOUS_TTL_MS)
+            return {};
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeState(input, state) {
+    writeFileSync(stateFile(input), JSON.stringify(state));
+}
+function digestCacheFile(root) {
+    const base = process.env.CLAUDE_PLUGIN_DATA || process.env.PLUGIN_DATA || join(tmpdir(), 'funpixel-gdk');
+    mkdirSync(base, { recursive: true });
+    return join(base, `digests-${createHash('sha256').update(resolve(root)).digest('hex').slice(0, 16)}.json`);
+}
+const digestsByRoot = new Map();
+const HASH_BUDGET_MS = 8000;
+export function gameDigests(root) {
+    if (!digestsByRoot.has(root)) {
+        digestsByRoot.set(root, (async () => {
+            const file = digestCacheFile(root);
+            let cache = {};
+            try {
+                cache = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch { }
+            try {
+                return await stagedDigests(root, cache, Date.now() + HASH_BUDGET_MS);
+            }
+            finally {
+                try {
+                    writeFileSync(file, JSON.stringify(cache));
+                }
+                catch { }
+            }
+        })());
+    }
+    return digestsByRoot.get(root);
+}
+export async function currentFingerprint(root) {
+    try {
+        return fingerprintOfDigests(await gameDigests(root));
+    }
+    catch (e) {
+        if (e instanceof HashBudgetExceeded)
+            return null;
+        throw e;
+    }
+}
+export function verifyStatus(root, now) {
+    const file = join(root, 'verify.json');
+    if (!existsSync(file))
+        return 'missing';
+    let record;
+    try {
+        record = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return 'missing';
+    }
+    if (record.fingerprint !== now)
+        return 'stale';
+    if (record.verdict === 'fail')
+        return 'fail';
+    if (record.verdict !== 'pass')
+        return 'not_observed';
+    return 'pass';
+}
+export const DEVLOG = () => join(homedir(), '.funpixel', 'devlog.jsonl');
+export const GAME_DEVLOG = (root) => join(root, '.funtools', 'devlog.jsonl');
+export const KIT_FEEDBACK = (root) => join(root, '.funtools', 'kit-feedback.jsonl');
+export const KIT_KINDS = ['worked', 'hurt', 'missing'];
+export function isFeedbackCall(input) {
+    const r = input.tool_response;
+    const failed = r && typeof r === 'object' && (r.isError === true || r.is_error === true);
+    return /report_feedback$/.test(input.tool_name ?? '') && !failed;
+}
+const hasKitItems = (items) => Array.isArray(items) && items.some((i) => KIT_KINDS.includes(i?.kind));
+export const isKitVerdictCall = (input) => isFeedbackCall(input) && hasKitItems(input.tool_input?.items);
+function linesSince(file, sinceMs) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+            const e = JSON.parse(line);
+            const at = Date.parse(e.at ?? e.t ?? e.date ?? '');
+            if (Number.isNaN(at) || at >= sinceMs)
+                out.push(e);
+        }
+        catch {
+        }
+    }
+    return out;
+}
+export function kitVerdictFiled(input, root, sinceMs) {
+    if (readState(input).kitVerdictAt)
+        return true;
+    const t = input.transcript_path;
+    if (t && existsSync(t)) {
+        for (const line of readFileSync(t, 'utf8').split('\n')) {
+            if (!line.includes('report_feedback'))
+                continue;
+            try {
+                const blocks = JSON.parse(line).message?.content;
+                if (Array.isArray(blocks) && blocks.some((b) => b?.type === 'tool_use' && /report_feedback$/.test(b.name ?? '') && hasKitItems(b.input?.items)))
+                    return true;
+            }
+            catch {
+            }
+        }
+    }
+    if (linesSince(KIT_FEEDBACK(root), sinceMs).some((e) => e.kind === 'kit-verdict' || hasKitItems(e.items)))
+        return true;
+    return linesSince(GAME_DEVLOG(root), sinceMs).some((e) => e.kind === 'feedback' && hasKitItems(e.items));
+}
+export function kitVerdictOn(root) {
+    if (process.env.FUNPIXEL_GDK_KIT_VERDICT === 'off')
+        return false;
+    try {
+        return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).gdk?.kitVerdict !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export const KIT_ASK = 'One question before you hand back, asked once (answer it or skip it; nothing depends on it): how did the Funpixel kit do for you in this session? '
+    + 'In one report_feedback call (skill funpixel-feedback, "The kit verdict"), give items with `kind` worked, hurt or missing and the `tool` each is about (a tool, skill, hook or command): '
+    + 'what in the kit helped, what got in the way or was wrong, what was missing, and one overall line with `tool` "kit" saying whether the kit did well or let you down, and why. '
+    + 'About the kit, not the game. If the call fails, write the same items as one line with "kind": "kit-verdict" in .funtools/kit-feedback.jsonl with your file tools.';
+export function feedbackFiled(input, root, sinceMs) {
+    if (readState(input).feedbackAt)
+        return true;
+    const t = input.transcript_path;
+    if (t && existsSync(t) && /"name"\s*:\s*"[^"]*report_feedback"/.test(readFileSync(t, 'utf8')))
+        return true;
+    if (linesSince(KIT_FEEDBACK(root), sinceMs).length)
+        return true;
+    for (const [log, own] of [[GAME_DEVLOG(root), true], [DEVLOG(), false]]) {
+        if (!existsSync(log))
+            continue;
+        for (const line of readFileSync(log, 'utf8').split('\n').reverse()) {
+            try {
+                const e = JSON.parse(line);
+                if (e.kind === 'feedback' && (e.game === root || (own && e.game === undefined)) && Date.parse(e.at) >= sinceMs)
+                    return true;
+            }
+            catch {
+            }
+        }
+    }
+    return false;
+}
+export function sessionStartMs(input) {
+    const s = readState(input);
+    if (s.startedAt)
+        return s.startedAt;
+    const t = input.transcript_path;
+    if (t && existsSync(t)) {
+        const st = statSync(t);
+        return st.birthtimeMs || st.ctimeMs;
+    }
+    return 0;
+}
+export const VERIFY = '`npm run build`, then `npx @funpixel/tools verify` (or `npx @funpixel/tools check`: both and the rules suite in one call)';
+const GAME_CODE = /^(src|public)\/|^index\.html$|^package(-lock)?\.json$|^vite\.config|^tsconfig/;
+export function changedSince(snapshot, hashes) {
+    if (!snapshot)
+        return [];
+    const out = [];
+    for (const [p, h] of Object.entries(hashes))
+        if (snapshot[p] !== h)
+            out.push(snapshot[p] ? p : `${p} (new)`);
+    for (const p of Object.keys(snapshot))
+        if (!(p in hashes))
+            out.push(`${p} (removed)`);
+    return out.sort();
+}
+export function staleDetail(changed) {
+    if (!changed.length)
+        return '';
+    const names = changed.slice(0, 5).join(', ') + (changed.length > 5 ? ` and ${changed.length - 5} more` : '');
+    const outside = changed.every((c) => !GAME_CODE.test(c.replace(/ \((new|removed)\)$/, '')));
+    return ` Changed since the last pass: ${names}.` + (outside
+        ? ' None of these is game code: if they are notes, captures or logs, they would ship with the game — list them in .harnessignore (that also keeps verify fresh).'
+        : '');
+}
+export async function openItems(input, root, atStop = false) {
+    return (await openReport(input, root, atStop)).items;
+}
+export async function openReport(input, root, atStop = false) {
+    const state = readState(input);
+    let digests;
+    try {
+        digests = await gameDigests(root);
+    }
+    catch (e) {
+        if (e instanceof HashBudgetExceeded)
+            return { items: [], quality: null, tags: new Map() };
+        throw e;
+    }
+    const now = fingerprintOfDigests(digests);
+    const hashes = Object.fromEntries(digests.map((e) => [e.path, e.digest.slice(0, 16)]));
+    const v = verifyStatus(root, now);
+    if (v === 'pass' && state.verifiedFingerprint !== now)
+        writeState(input, { ...readState(input), verifiedFingerprint: now, verifiedFiles: hashes });
+    if (state.startFingerprint && state.startFingerprint === now)
+        return { items: [], quality: null, tags: new Map() };
+    const items = [];
+    const tags = new Map();
+    const add = (text, kind, fault = false) => { items.push(text); tags.set(text, { kind, fault }); };
+    const detail = v === 'stale' ? staleDetail(changedSince(state.verifiedFiles, hashes)) : '';
+    const existing = state.startGame === true && !completeGameScope(state, root);
+    const scoped = ' Validate the requested change and fix regressions it caused. Report unrelated or pre-existing failures and unobserved coverage explicitly; do not expand the task or call those gaps passing.';
+    if (v === 'missing')
+        add(`The game changed and was never verified. Run ${VERIFY}.${existing ? scoped : ' Each FAIL line names what broke.'}`, 'verify');
+    else if (v === 'stale')
+        add(`verify.json is stale: the files that ship changed after it ran.${detail} Run ${VERIFY}.${existing ? scoped : ''}`, 'verify', lastVerdict(root) === 'fail');
+    else if (v === 'fail')
+        add(existing
+            ? `The last verify FAILED.${scoped} After a fix, run ${VERIFY} again.`
+            : `The last verify FAILED. Fix what its FAIL lines name, then run ${VERIFY} again.`, 'verify', true);
+    else if (v === 'not_observed')
+        add(existing
+            ? `The last verify measured nothing (exit 2).${scoped} Add instrumentation needed for the requested check (skill funpixel-verify); whole-game coverage remains unproved.`
+            : `The last verify measured nothing (exit 2): declare the __FPX_* hooks (skill funpixel-verify), then run ${VERIFY}.`, 'verify');
+    if (v === 'pass' && !isGraybox(input, root, state)) {
+        const door = frontDoorItem(root, state, now, atStop ? lastAssistantText(input) : '');
+        if (door)
+            add(door, 'verify', /front-door verify FAILED/.test(door));
+    }
+    const quality = qualityReport(input, root, state, now, v === 'pass', atStop);
+    for (const t of quality.items)
+        add(t, quality.tags.get(t)?.kind ?? 'quality', quality.tags.get(t)?.fault === true);
+    if (!feedbackFiled(input, root, sessionStartMs(input))) {
+        add('File this session\'s feedback: one report_feedback call (skill funpixel-feedback) with what the kit was missing, what you worked around and which tool or skill helped or got in the way, plus the dev-log entries (steps, dead ends, lessons, decisions, with cost). ' +
+            'Without the Funpixel MCP, or when the call fails, write them to .funtools/devlog.jsonl in the game folder with your file tools, as that skill shows.', 'feedback');
+    }
+    return { items, quality, tags };
+}
+function lastVerdict(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, 'verify.json'), 'utf8')).verdict ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/plugins/codex/hooks/memory.mjs

@@ -0,0 +1,92 @@
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { lessonLines, rankLessons } from './vendor/lessons/store.mjs';
+import { MOTIF_HEADING, motifLines, recentMotifs, recordMotif } from './vendor/lessons/motifs.mjs';
+import { explained, journalLine, noticeOutsideChanges, readJournal, recordAgentFile, trackedHashes, writeAgentFiles } from './vendor/memory/journal.mjs';
+import { decisionLine, liveDecisions, readDecisions } from './vendor/memory/decisions.mjs';
+import { gameDigests } from './lib.mjs';
+import { completeGameScope } from './scope.mjs';
+const genreOf = (root) => {
+    try {
+        return JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8')).metadata?.genre || 'any';
+    }
+    catch {
+        return 'any';
+    }
+};
+const motifBlock = (root) => {
+    const lines = motifLines(recentMotifs(root, 5));
+    return lines.length ? `## ${MOTIF_HEADING}\n${lines.join('\n')}` : '';
+};
+export function memoryContext(root) {
+    const genre = genreOf(root);
+    const lessons = lessonLines(rankLessons(root, genre), 3);
+    return [
+        lessons.length ? `## Lessons from earlier games (${genre})\n${lessons.join('\n')}` : '',
+        motifBlock(root),
+    ].filter(Boolean).join('\n\n');
+}
+export function motifReminder(root, state) {
+    if (state.motifsShown || !completeGameScope(state, root))
+        return null;
+    const block = motifBlock(root);
+    return block ? { text: `${block}\nUse this context when it helps the brief (skill funpixel-art).`, state: { ...state, motifsShown: true } } : null;
+}
+export function rememberMotif(root) {
+    try {
+        recordMotif(root);
+    }
+    catch { }
+}
+export const JOURNAL_SHOWN = 5;
+export const DECISIONS_SHOWN = 8;
+export function creatorContext(root) {
+    const parts = [];
+    const entries = explained(readJournal(root));
+    if (entries.length) {
+        const recent = entries.slice(-JOURNAL_SHOWN);
+        const earlier = entries.length - recent.length;
+        parts.push(`## What the person changed (.funtools/journal.jsonl, newest last${earlier ? `; ${earlier} earlier: \`npx @funpixel/tools journal\`` : ''})\n${recent.map(journalLine).join('\n')}\n`
+            + 'Keep these unless the person asks otherwise; re-read a file before you edit it. A detected entry is a fact about the files, not about intent: ask when it matters.');
+    }
+    const all = readDecisions(root);
+    const live = liveDecisions(all);
+    if (live.length) {
+        const shown = live.slice(-DECISIONS_SHOWN);
+        const more = live.length - shown.length;
+        parts.push(`## Decisions in force (design/decisions.md${more ? `; ${more} older live ones there` : ''})\n${shown.map(decisionLine).join('\n')}\n`
+            + 'Changing one is allowed: record the new choice with `npx @funpixel/tools decide "…" --because "…" --supersedes D<n>`, so the change is a decision and not a drift.');
+    }
+    return parts.join('\n\n');
+}
+export async function outsideChanges(root) {
+    try {
+        const e = await noticeOutsideChanges(root, new Date(), await gameDigests(root));
+        return e ? `## Changed since the last agent turn\n${journalLine(e)}\nRead these files before editing them; keep what looks deliberate, and ask the person when unsure. Recorded in .funtools/journal.jsonl.` : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function rememberAgentFiles(root) {
+    try {
+        writeAgentFiles(root, await trackedHashes(root, await gameDigests(root)));
+    }
+    catch { }
+}
+const EDIT_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit|write|fs_write|edit_file|write_file)$/;
+export function rememberAgentEdit(root, input) {
+    try {
+        if (!EDIT_TOOLS.test(String(input.tool_name ?? '')))
+            return;
+        const ti = input.tool_input ?? {};
+        const path = ti.file_path ?? ti.path ?? ti.notebook_path;
+        if (typeof path !== 'string' || !path)
+            return;
+        const abs = isAbsolute(path) ? path : join(input.cwd ?? root, path);
+        const rel = relative(root, abs).split(sep).join('/');
+        if (rel && !rel.startsWith('..'))
+            recordAgentFile(root, rel);
+    }
+    catch { }
+}

package/plugins/codex/hooks/mobile-qa.mjs

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const readJson = (f) => { try {
+    const raw = readFileSync(f, 'utf8');
+    return JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+}
+catch {
+    return null;
+} };
+export function latestMobileQa(root) {
+    const files = [];
+    const pt = join(root, '.funtools', 'playtest');
+    if (existsSync(pt))
+        for (const d of readdirSync(pt))
+            files.push(join(pt, d, 'mobile', 'mobile-qa.json'));
+    const mq = join(root, '.funtools', 'mobile-qa');
+    if (existsSync(mq))
+        for (const d of readdirSync(mq))
+            files.push(join(mq, d, 'mobile-qa.json'));
+    const found = files.filter((f) => existsSync(f)).map((f) => ({ f, at: statSync(f).mtimeMs })).sort((a, b) => b.at - a.at)[0];
+    if (!found)
+        return null;
+    const v = readJson(found.f);
+    if (!v || !Array.isArray(v.findings))
+        return null;
+    return { file: found.f, at: found.at, verdict: v, evidence: readJson(join(found.f, '..', 'evidence.json')) };
+}
+export function mobileNote(root, state, fingerprint) {
+    const m = latestMobileQa(root);
+    if (!m)
+        return null;
+    const high = m.verdict.findings.filter((f) => String(f?.severity).toLowerCase() === 'high' && typeof f.finding === 'string');
+    const key = `${m.file}@${Math.round(m.at)}`;
+    if (!high.length || state?.mobileNoted === key)
+        return null;
+    const older = m.evidence?.fingerprint && fingerprint && m.evidence.fingerprint !== fingerprint ? ' (judged on an earlier build: run it again to see whether it holds)' : '';
+    const first = high[0].finding.replace(/\s+/g, ' ').slice(0, 160);
+    const score = typeof m.verdict.phoneNative === 'number' ? `, phone-native ${m.verdict.phoneNative}/10` : '';
+    return {
+        key,
+        line: `Mobile QA: ${high.length} high finding${high.length > 1 ? 's' : ''} open on a phone${score}${older} — ${first}${high.length > 1 ? ' …' : ''} (${relative(root, m.file)}; \`npx @funpixel/tools mobile-qa report\` or the playtest report ranks them). Advisory: yours to pick, edit or ignore.`,
+    };
+}

package/plugins/codex/hooks/note.mjs

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const NOTE_FILES = ['GDD.md', 'README.md'];
+export const notePath = (root) => {
+    const f = root ? NOTE_FILES.find((n) => existsSync(join(root, 'design', n))) : undefined;
+    return f ? join(root, 'design', f) : null;
+};
+export function readNote(root) {
+    const path = notePath(root);
+    if (!path)
+        return null;
+    const extra = join(root, 'design', 'gameplay.md');
+    return `${readFileSync(path, 'utf8')}\n\n${existsSync(extra) ? readFileSync(extra, 'utf8') : ''}`;
+}
+export const section = (note, heading) => note.match(new RegExp(`^## ${heading}[^\\n]*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'mi'))?.[1];
+const unfilled = (s) => /<[^>]*>|^…/.test(s.trim());
+const blank = (cell) => !cell || /^(-|—|–|…|<.*>)$/.test(cell);
+function table(note, heading) {
+    const body = section(note ?? '', heading);
+    if (body === undefined)
+        return null;
+    const rows = body.split('\n').filter((l) => l.trim().startsWith('|')).map((l) => l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim()));
+    return { header: rows[0] ?? [], rows: rows.slice(1).filter((r) => !r.every((c) => /^:?-+:?$/.test(c)) && r[0] && !/<[^>]*>|^…$/.test(r[0])) };
+}
+export const adRules = (note) => (section(note, 'AD rules') ?? '').split('\n').filter((l) => /^\s*\d+[.)]\s+\S/.test(l) && !unfilled(l.replace(/^\s*\d+[.)]\s+/, ''))).length;
+const SILENCE_CELL = /silen|^none$|^no (sound|audio)/i;
+export function juiceGaps(note) {
+    const t = table(note, 'Juice');
+    if (!t)
+        return 'no juice table';
+    if (!t.rows.length)
+        return 'a juice table with no concrete events';
+    const sound = t.header.findIndex((c) => /sound|sfx|audio/i.test(c));
+    const named = t.header.findIndex((c) => /visual|feedback|effect|response/i.test(c));
+    const visual = named >= 0 ? [named] : t.header.map((_, i) => i).filter((i) => i > 0 && i !== sound);
+    const unanswered = t.rows.filter((r) => !visual.length || visual.every((i) => blank(r[i])));
+    if (unanswered.length)
+        return `juice rows with no visible response: ${unanswered.map((r) => r[0]).join(', ')}`;
+    const undecided = t.rows.filter((r) => sound < 0 || blank(r[sound]));
+    return undecided.length ? `juice rows with no sound decision: ${undecided.map((r) => r[0]).join(', ')}` : '';
+}
+const SILENT_ASK = /\b(no|without( any)?) (sound|audio)\b|\bsilent game\b/i;
+const SILENT_NOTE = /\bsilent (game|by design)\b|\bno (sound|audio) (at all|by design)\b|^\s*[-*]?\s*\**(sound|audio)\**\s*:\s*\**\s*(none|silent|silence|no sound)\b/im;
+export function agreedSilence(prompt, note) {
+    if (SILENT_ASK.test(prompt ?? ''))
+        return true;
+    if (!note)
+        return false;
+    if (SILENT_NOTE.test(note.replace(/^\s*\|.*$/gm, '')))
+        return true;
+    const t = table(note, 'Juice');
+    const sound = t ? t.header.findIndex((c) => /sound|sfx|audio/i.test(c)) : -1;
+    return Boolean(t && t.rows.length && sound >= 0 && t.rows.every((r) => SILENCE_CELL.test(r[sound] ?? '')));
+}
+const norm = (s) => String(s).toLowerCase().replace(/[_\s]+/g, ' ').trim();
+export function fixRound(note) {
+    const t = table(note, 'Fix round');
+    if (!t)
+        return [];
+    const next = Math.max(1, t.header.findIndex((c) => /next|step|plan|fix/i.test(c)));
+    return t.rows.filter((r) => !blank(r[0]) && !blank(r[next] ?? '')).map((r) => ({ finding: r[0], next: r[next] }));
+}
+export const inFixRound = (rows, key) => rows.some((r) => norm(r.finding).includes(norm(key)) || (norm(r.finding).length > 3 && norm(key).includes(norm(r.finding))));

package/plugins/codex/hooks/nudge.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { client, deferForKiro, findGameRoot, forHost, gatePolicy, isFeedbackCall, isKitVerdictCall, openReport, readInput, readState, startDir, writeState, isMain } from './lib.mjs';
+import { recordToolUse } from './quality.mjs';
+import { motifReminder, rememberAgentEdit } from './memory.mjs';
+import { shelfHints } from './hints.mjs';
+import { pipelineReminder, progressCadence, recordBackground } from './pipeline.mjs';
+import { adoptionOffer, flowBeat, flowEditLine, flowQuiet } from './flow.mjs';
+export const NUDGE_MS = 4 * 60 * 1000;
+export async function nudge(input, now = Date.now()) {
+    recordBackground(input);
+    if (isFeedbackCall(input))
+        writeState(input, { ...readState(input), feedbackAt: now, ...(isKitVerdictCall(input) ? { kitVerdictAt: now } : {}) });
+    const seen = readState(input);
+    const recorded = recordToolUse(input, seen, now);
+    if (recorded !== seen)
+        writeState(input, recorded);
+    const state = readState(input);
+    const fresh = findGameRoot(startDir(input));
+    flowBeat(fresh, 'work');
+    if (fresh)
+        rememberAgentEdit(fresh, input);
+    const motifs = fresh ? motifReminder(fresh, state) : null;
+    if (motifs) {
+        writeState(input, motifs.state);
+        return motifs.text;
+    }
+    const root = fresh;
+    if (!root || gatePolicy(root) === 'off')
+        return null;
+    const hint = shelfHints(input, state, root);
+    if (hint)
+        writeState(input, hint.state);
+    let quiet = false;
+    try {
+        quiet = flowQuiet(input, root);
+    }
+    catch { }
+    const path = quiet ? null : await pipelineReminder(input, root).catch(() => null);
+    let loop = null;
+    try {
+        if (!quiet)
+            loop = progressCadence(input, root, now);
+    }
+    catch { }
+    let early = null;
+    try {
+        early = quiet ? adoptionOffer(input, root) : await flowEditLine(input, root);
+    }
+    catch { }
+    const withHint = (text) => [early, hint?.text, path, loop, text].filter(Boolean).join('\n\n') || null;
+    const verifiedAt = mtime(join(root, 'verify.json'));
+    const newVerify = verifiedAt !== null && verifiedAt !== state.nudgedVerifyAt;
+    const waiting = state.lastNudge && now - state.lastNudge < NUDGE_MS;
+    if (waiting && !newVerify)
+        return withHint(null);
+    const report = await openReport(input, root);
+    const items = report.items.filter((i) => { const t = report.tags.get(i); return !(t && MILESTONE.has(t.kind) && !t.fault); });
+    const said = state.nudgedItems ?? {};
+    const burst = String(verifiedAt ?? 'none');
+    const show = items.filter((i) => said[itemKey(i)] !== signature(i) && !(STALE.test(i) && state.staleBurst === burst));
+    const staleSaid = show.some((i) => STALE.test(i));
+    writeState(input, { ...readState(input), lastNudge: now, nudgedVerifyAt: verifiedAt, nudgedItems: Object.fromEntries(items.map((i) => [itemKey(i), signature(i)])), ...(staleSaid ? { staleBurst: burst } : {}) });
+    if (!show.length)
+        return withHint(null);
+    const first = !Object.keys(said).length;
+    const head = first ? 'Before you finish (Funpixel) — each item is said once, and again only when it changes:' : 'Before you finish (Funpixel), new or changed:';
+    return withHint(`${head}\n${show.join('\n')}${first ? '\nLog dead ends and lessons as they happen.' : ''}`);
+}
+export const MILESTONE = new Set(['play', 'panel']);
+const STALE = /^(verify\.json is stale|The game changed and was never verified)/;
+const itemKey = (item) => item.slice(0, 48);
+export const signature = (item) => item.replace(/ Changed since the last pass: .*?\.(?= |$)/, '');
+function mtime(file) {
+    try {
+        return statSync(file).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+async function main() {
+    const input = await readInput();
+    const text = forHost(await nudge(input));
+    if (!text)
+        return;
+    if (client(input) === 'kiro') {
+        deferForKiro(input, 'pendingNudge', text);
+        return;
+    }
+    process.stdout.write(JSON.stringify(client(input) === 'cursor'
+        ? { additional_context: text }
+        : { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }));
+}
+if (isMain(import.meta.url)) {
+    main().catch((e) => process.stderr.write(`funpixel nudge: ${e instanceof Error ? e.message : e}\n`));
+}