@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/_shared/scripts/dev-start.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Start (or stop) the persistent preview dev server and record the real devUrl.
+ *
+ * This removes the LLM from port handling entirely (docs/harness/experiment-lessons.md §9.2):
+ * Vite runs with strictPort:false, so when 3000 is taken it auto-increments; this
+ * script parses Vite's actual `Local:` URL from the log, appends `?debug=1`, and
+ * writes it back to project-state via the same layer `state:set` uses. The agent
+ * never reads or records a port by hand.
+ *
+ * Usage:
+ *   npm run dev:start          # start server, capture real URL, write devUrl
+ *   npm run dev:stop           # stop the server started by dev:start
+ *   node skills/_shared/scripts/dev-start.mjs --root=. [--stop] [--timeout=30000]
+ *
+ * Exit 0 = server up + devUrl written (or stopped); 1 = failed to detect URL.
+ */
+
+import { openSync, closeSync, existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { applyHandoffUpdates, resolveProjectStatePath } from './state-handoff.mjs';
+import { parseLocalUrl, waitForHttp } from '../../playable-record/scripts/lib/dev-server.mjs';
+
+const PID_FILE = '.playcraft-dev.pid';
+const LOG_FILE = '.playcraft-dev.log';
+const PREFERRED_URL = 'http://127.0.0.1:3000/';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), stop: false, timeout: 30000 };
+  for (const arg of argv) {
+    if (arg === '--stop') opts.stop = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice('--timeout='.length));
+  }
+  return opts;
+}
+
+/** Append the `?debug=1` flag that gates the on-screen one-click clear button. */
+function withDebugFlag(url) {
+  return /[?&]debug=1\b/.test(url) ? url : `${url}${url.includes('?') ? '&' : '?'}debug=1`;
+}
+
+function readPid(root) {
+  const pidPath = join(root, PID_FILE);
+  if (!existsSync(pidPath)) return null;
+  const pid = Number(readFileSync(pidPath, 'utf8').trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stopServer(root) {
+  const pid = readPid(root);
+  const pidPath = join(root, PID_FILE);
+  if (pid && isAlive(pid)) {
+    // Detached child is its own process-group leader; kill the whole group.
+    try {
+      process.kill(-pid, 'SIGTERM');
+    } catch {
+      try {
+        process.kill(pid, 'SIGTERM');
+      } catch {
+        /* already gone */
+      }
+    }
+    console.log(`[dev:stop] stopped dev server (pid ${pid})`);
+  } else {
+    console.log('[dev:stop] no running dev server recorded');
+  }
+  if (existsSync(pidPath)) rmSync(pidPath);
+}
+
+/** Poll the dev-server log file for Vite's `Local:` URL. */
+async function detectUrlFromLog(logPath, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(logPath)) {
+      const url = parseLocalUrl(readFileSync(logPath, 'utf8'));
+      if (url) return url;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return null;
+}
+
+async function startServer(root, timeoutMs) {
+  const existingPid = readPid(root);
+  if (existingPid && isAlive(existingPid)) {
+    const logPath = join(root, LOG_FILE);
+    const url = (existsSync(logPath) && parseLocalUrl(readFileSync(logPath, 'utf8'))) || PREFERRED_URL;
+    return finalize(root, url, existingPid, true);
+  }
+
+  const logPath = join(root, LOG_FILE);
+  const logFd = openSync(logPath, 'w');
+  const child = spawn('npm', ['run', 'dev', '--', '--host', '127.0.0.1'], {
+    cwd: root,
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+  });
+  closeSync(logFd);
+  child.unref();
+  writeFileSync(join(root, PID_FILE), String(child.pid));
+
+  const detected = await detectUrlFromLog(logPath, timeoutMs);
+  const url = detected || PREFERRED_URL;
+  try {
+    await waitForHttp(url, 10000);
+  } catch {
+    if (!detected) {
+      console.error(
+        `[dev:start] could not detect dev URL within ${timeoutMs}ms and ${PREFERRED_URL} is not reachable — check ${LOG_FILE}`,
+      );
+      return { ok: false };
+    }
+  }
+  return finalize(root, url, child.pid, false);
+}
+
+function finalize(root, baseUrl, pid, reused) {
+  const devUrl = withDebugFlag(baseUrl);
+  applyHandoffUpdates(resolveProjectStatePath(root), { devUrl });
+  console.log(`[dev:start] ${reused ? 'reusing' : 'started'} dev server (pid ${pid})`);
+  console.log(`[dev:start] devUrl recorded: ${devUrl}`);
+  return { ok: true, devUrl, pid };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.stop) {
+    stopServer(opts.root);
+    return;
+  }
+  const result = await startServer(opts.root, opts.timeout);
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(`[dev:start] error: ${err.message}`);
+  process.exit(1);
+});

package/project-templates/phaser/skills/_shared/scripts/disclosure-config.mjs

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+/**
+ * Current-action disclosure rules for growth-rings-v1.
+ *
+ * The L0 project entry should not explain every future ring. It asks state:get
+ * for the current action surface, and this file is the machine-readable source
+ * for that surface.
+ */
+
+const COMMON_REQUIRED = ['CLAUDE.md'];
+
+export const FUTURE_RING_FILES = [
+  'docs/design-brief.md',
+  'docs/layout-spec.md',
+  'docs/implementation-plan.md',
+  'docs/style-exploration.md',
+  'logs/artist-log.md',
+  'logs/ta-log.md',
+  'logs/review-report.md',
+];
+
+const DISCLOSURE_BY_RING_LOOP = {
+  '1:clarify': {
+    currentAction:
+      'Orchestrator: invoke @game-designer for Ring 1 clarify — design-brief discovery + DESIGN seed + playcraft skills match compact refs + minimal developer slice queue (not layout/style/CTA/full plan).',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
+    deferredFiles: FUTURE_RING_FILES.filter((f) => f !== 'docs/design-brief.md'),
+    nextRole: 'game-designer',
+    artifactRefs: ['docs/DESIGN.md', 'docs/design-brief.md', 'docs/atom-tree.json', 'sliceState'],
+    requiredContextFields: ['ring.goal', 'lastRole.summary', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    allowedTasks: [
+      'Invoke @game-designer for ring 1 clarify',
+      'Game Designer: design-brief discovery + DESIGN seed + playcraft skills match + sliceState queue',
+      'Game Designer: run playcraft skills match and write meta.skillsMatch + compact selectedAtoms',
+      'Record fromScratchReason when core mechanic is novel',
+      'Define first-level win strategy and semantic placeholders (Game Designer subagent)',
+    ],
+    forbiddenTasks: [
+      'Do not write docs/DESIGN.md as orchestrator',
+      'Do not implement game/ as orchestrator during clarify',
+      'Do not require layout-spec or full implementation-plan in Ring 1',
+      'Do not build a full atom graph in Ring 1 clarify — compact skillsMatch refs only',
+      'Do not design CTA polish or production assets in Ring 1',
+      'Do not claim skillRefs implement core mechanic without skills read',
+      'Do not run standalone record:mp4 as a Ring 1 blocker',
+      'Do not run verify:ui as Ring 1 blockers',
+    ],
+    nextCommands: [
+      'Invoke @game-designer — ring 1 clarify (skills match + design-brief + DESIGN seed + slice queue)',
+    ],
+  },
+  '1:select': {
+    currentAction: 'Orchestrator: after Game Designer STOP, spawn a temporary ref-flow atom-selection subagent for compact Ring 1 atom-tree selection.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
+    deferredFiles: FUTURE_RING_FILES,
+    nextRole: 'temporary-ref-flow',
+    artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    allowedTasks: [
+      'Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection',
+      'Pass DESIGN.md gameplay keywords and constraints to the temporary selector',
+    ],
+    forbiddenTasks: [
+      'Do not select atoms inline as orchestrator',
+      'Do not run init-template before atom-selection STOP',
+      'Do not implement gameplay logic as orchestrator',
+    ],
+    nextCommands: [
+      'Spawn temporary ref-flow atom-selection subagent — ring 1 atom-tree selection (engine + compact gameplay trunk)',
+    ],
+  },
+  '1:scaffold': {
+    currentAction: 'Orchestrator: after temporary atom-selection STOP, run engine scaffold before @developer build.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/atom-tree.json'],
+    deferredFiles: FUTURE_RING_FILES,
+    nextRole: 'orchestrator',
+    artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json', 'docs/scaffold-manifest.md'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'sharedDecisions.engine', 'sharedDecisions.coreAction'],
+    allowedTasks: [
+      'Validate atom-tree selection',
+      'Apply engine template from atom-tree',
+    ],
+    forbiddenTasks: [
+      'Do not invoke @developer before init-template + verify:contract pass',
+      'Do not select atoms inline as orchestrator',
+      'Do not implement gameplay logic as orchestrator',
+    ],
+    nextCommands: [
+      'playcraft skills validate-atom-tree-selection',
+      '# auto-link: saving docs/atom-tree.json links selected atoms into .claude/skills/ (validate-atom-tree-selection hook) — no manual "skills link" needed',
+      'playcraft remix init-template --from-atom-tree',
+      'npm install',
+      'npm run verify:contract',
+      'Invoke @developer for ring 1 build loop',
+    ],
+  },
+  '1:build': {
+    currentAction: 'Orchestrator: invoke @developer for Ring 1 build. Developer: implement playable spine to first-level win.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/atom-tree.json', 'docs/scaffold-manifest.md', 'game/'],
+    deferredFiles: FUTURE_RING_FILES.filter((file) => file !== 'logs/review-report.md'),
+    nextRole: 'developer',
+    artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json', 'logs/developer-log.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'nextRole.mustKnow', 'sharedDecisions.engine', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    allowedTasks: [
+      'Invoke @developer for ring 1 build',
+      'Apply engine scaffold if needed (orchestrator only, before developer)',
+      'Implement core gameplay loop (Developer subagent)',
+      'Wire window.__playable runtime contract (Developer subagent)',
+      'Make autoPlay follow player-reachable actions (Developer subagent)',
+      'Record devUrl when ready (Developer subagent)',
+    ],
+    forbiddenTasks: [
+      'Do not implement game/ as orchestrator when @developer should own build',
+      'Do not polish HUD',
+      'Do not implement CTA fallback as a Ring 1 blocker',
+      'Do not run full MP4 as a Ring 1 blocker',
+      'Do not produce production assets',
+    ],
+    nextCommands: [
+      'Invoke @developer — ring 1 build (placeholder art + core loop)',
+      'npm run placeholder:gen',
+      'npm run verify:contract',
+      'npm run verify:lifecycle',
+      'npm run verify:firstwin',
+      'npm run verify:placeholders',
+    ],
+  },
+  '1:verify': {
+    currentAction: 'Run Ring 1 objective gate and route failures before user Ring Gate.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'logs/developer-log.md', 'game/'],
+    deferredFiles: FUTURE_RING_FILES,
+    nextRole: 'orchestrator',
+    artifactRefs: ['docs/DESIGN.md', 'logs/developer-log.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.validation', 'lastRole.blockers', 'sharedDecisions.coreAction'],
+    allowedTasks: [
+      'Run Ring 1 script verifiers',
+      'Route verifier failures to Developer',
+      'Ask user only after ring:gate canAskUser=yes',
+    ],
+    forbiddenTasks: ['Do not invoke Reviewer for Ring 1 verify', 'Do not ask user before ring:gate passes'],
+    nextCommands: [
+      'npm run verify:contract',
+      'npm run verify:lifecycle',
+      'npm run verify:firstwin',
+      'npm run verify:placeholders',
+      'npm run ring:gate -- --iteration 1',
+    ],
+  },
+  '2:clarify': {
+    currentAction:
+      'Orchestrator: invoke @game-designer for Ring 2 clarify — append design-brief periphery discovery + refresh compact skills match + deepen slice queue with 2–4 skill-informed developer periphery slices (optional layout intent; not full plan or production asset mapping).',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/design-brief.md', 'docs/atom-tree.json'],
+    deferredFiles: [
+      'docs/style-exploration.md',
+      'logs/artist-log.md',
+      'logs/ta-log.md',
+      'logs/review-report.md',
+    ],
+    nextRole: 'game-designer',
+    artifactRefs: [
+      'docs/DESIGN.md',
+      'docs/design-brief.md',
+      'docs/atom-tree.json',
+      'sliceState',
+      'docs/implementation-plan.md',
+      'docs/layout-spec.md',
+    ],
+    requiredContextFields: [
+      'ring.goal',
+      'archivedRings.1',
+      'sharedDecisions.coreAction',
+      'sharedDecisions.semanticPlaceholders',
+    ],
+    allowedTasks: [
+      'Append design-brief with Ring 2 periphery discovery',
+      'Refresh meta.skillsMatch when periphery intent shifts',
+      'Deepen sliceState with 2–4 developer periphery slices (skillRefs/skillUse or fromScratchReason each)',
+      'Optional: minimal layout-spec layout intent (zones/screen only)',
+      'Optional: update implementation-plan as slice explain view',
+      'Update atom-tree.meta.activatedSlices[] to match new sliceIds',
+    ],
+    forbiddenTasks: [
+      'Do not invoke Artist or TA in Ring 2 clarify',
+      'Do not lock production assetMapping or full atlas tables in layout-spec',
+      'Do not create style-exploration or Hook/CTA production specs',
+      'Do not replace sliceState with a full feature backlog',
+      'Do not require complete atom graph expansion in one clarify pass',
+    ],
+    nextCommands: [
+      'Invoke @game-designer — ring 2 clarify (skills match refresh + slice queue deepening + optional layout intent)',
+    ],
+  },
+  '2:build': {
+    currentAction: 'Build Ring 2 periphery and full playthrough skeleton.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/layout-spec.md', 'docs/atom-tree.json', 'docs/implementation-plan.md', 'logs/developer-log.md', 'game/'],
+    deferredFiles: ['docs/style-exploration.md', 'logs/artist-log.md', 'logs/ta-log.md'],
+    nextRole: 'developer',
+    artifactRefs: ['docs/DESIGN.md', 'docs/layout-spec.md', 'docs/implementation-plan.md', 'logs/developer-log.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'nextRole.mustKnow', 'sharedDecisions.coreAction'],
+    allowedTasks: ['Implement HUD and flow skeleton', 'Bind placeholder assets', 'Prepare full playthrough'],
+    forbiddenTasks: ['Do not lock final art style', 'Do not create production asset set'],
+    nextCommands: [
+      'Invoke @developer — ring 2 build (HUD + flow skeleton, placeholder art)',
+      'npm run placeholder:gen',
+      'npm run verify:ui',
+      'npm run verify:visual-ring2',
+      'npm run verify:placeholders',
+    ],
+  },
+  '2:verify': {
+    currentAction: 'Run Ring 2 Reviewer checks and objective gate.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/layout-spec.md', 'docs/implementation-plan.md', 'logs/review-report.md', 'game/'],
+    deferredFiles: ['docs/style-exploration.md', 'logs/artist-log.md', 'logs/ta-log.md'],
+    nextRole: 'reviewer',
+    artifactRefs: ['docs/DESIGN.md', 'logs/developer-log.md', 'logs/review-report.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.validation', 'lastRole.blockers', 'sharedDecisions.coreAction'],
+    allowedTasks: ['Run gameplay_conformance', 'Run load_check', 'Run Ring 2 gate'],
+    forbiddenTasks: ['Do not run style lock or production asset checks'],
+    nextCommands: [
+      'Invoke @reviewer gameplay_conformance — fill logs/review-report.md § Ring DoD Fields gameplayConformance',
+      'Invoke @reviewer load_check — confirm page load + no console errors',
+      'npm run verify:ui',
+      'npm run verify:visual-ring2',
+      'npm run verify:placeholders',
+      'npm run ring:gate -- --iteration 2',
+    ],
+  },
+  '3:clarify': {
+    currentAction: 'Clarify playable-ad hook, CTA, and style direction.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/layout-spec.md', 'docs/style-exploration.md'],
+    deferredFiles: ['logs/ta-log.md'],
+    nextRole: 'game-designer',
+    artifactRefs: ['docs/DESIGN.md', 'docs/style-exploration.md'],
+    requiredContextFields: ['ring.goal', 'archivedRings.2', 'sharedDecisions.coreAction', 'sharedDecisions.assetContractRefs'],
+    allowedTasks: ['Define hook and CTA intent', 'Prepare style direction', 'Select MC option'],
+    forbiddenTasks: ['Do not produce final asset set', 'Do not lock assetMapping as final'],
+    nextCommands: [
+      'Invoke @game-designer — ring 3 clarify (hook/CTA intent + style direction in docs/style-exploration.md)',
+    ],
+  },
+  '3:build': {
+    currentAction: 'Build Ring 3 hook/CTA and style-direction handoff.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md', 'logs/developer-log.md', 'game/'],
+    deferredFiles: ['logs/ta-log.md'],
+    nextRole: 'artist',
+    artifactRefs: ['docs/style-exploration.md', 'logs/artist-log.md', 'logs/developer-log.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'nextRole.mustKnow', 'sharedDecisions.assetContractRefs'],
+    allowedTasks: ['Integrate hook and CTA', 'Create ASR handoff evidence', 'Run playable_validate preparation'],
+    forbiddenTasks: ['Do not mass-produce assets', 'Do not run Ring 4 ui_diff'],
+    nextCommands: [
+      'Invoke @artist — ring 3 ASR + style direction (logs/artist-log.md, no production-grade PNGs)',
+      'Invoke @developer — ring 3 integrate hook/CTA',
+      'npm run verify:ui',
+      'npm run verify:visual-ring3',
+      'npm run verify:placeholders',
+    ],
+  },
+  '3:verify': {
+    currentAction: 'Verify hook/CTA and run Ring 3 gate.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md', 'logs/review-report.md', 'game/'],
+    deferredFiles: ['logs/ta-log.md'],
+    nextRole: 'reviewer',
+    artifactRefs: ['docs/style-exploration.md', 'logs/artist-log.md', 'logs/review-report.md', 'game/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.validation', 'lastRole.blockers', 'sharedDecisions.assetContractRefs'],
+    allowedTasks: ['Run playable_validate', 'Run Ring 3 gate'],
+    forbiddenTasks: ['Do not lock production asset budget yet'],
+    nextCommands: [
+      'Invoke @reviewer gameplay_conformance — fill § Ring DoD Fields gameplayConformance',
+      'Invoke @reviewer load_check — confirm page load + no console errors',
+      'Invoke @reviewer playable_validate — fill § Ring DoD Fields hookCta',
+      'npm run verify:ui',
+      'npm run verify:visual-ring3',
+      'npm run verify:placeholders',
+      'npm run ring:gate -- --iteration 3',
+    ],
+  },
+  '4:clarify': {
+    currentAction: 'Prepare production freeze and assetMapping lock criteria.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md'],
+    deferredFiles: [],
+    nextRole: 'artist',
+    artifactRefs: ['docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md'],
+    requiredContextFields: ['ring.goal', 'archivedRings.3', 'sharedDecisions.assetContractRefs', 'openQuestions'],
+    allowedTasks: ['Prepare production asset contract', 'Confirm freeze criteria'],
+    forbiddenTasks: [],
+    nextCommands: [
+      'Invoke @artist — ring 4 clarify (production asset contract + assetMapping freeze criteria)',
+    ],
+  },
+  '4:build': {
+    currentAction: 'Produce and integrate production assets (Artist Wave 1 → TA Wave 2 → Developer integration).',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md', 'logs/ta-log.md', 'logs/developer-log.md', 'game/'],
+    deferredFiles: [],
+    nextRole: 'artist',
+    artifactRefs: ['docs/layout-spec.md', 'logs/artist-log.md', 'logs/ta-log.md', 'logs/developer-log.md', 'assets/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.validation', 'lastRole.blockers', 'sharedDecisions.assetContractRefs', 'productionPipeline.waves'],
+    allowedTasks: ['Run Artist Wave 1', 'Run Technical Artist Wave 2', 'Integrate production assets'],
+    forbiddenTasks: ['Do not change core gameplay semantics without routeTo'],
+    nextCommands: [
+      'Invoke @artist — Ring 4 Wave 1 (audio + digit strip, logs/artist-log.md)',
+      'Invoke @technical-artist — Ring 4 Wave 2 (bulk production, logs/ta-log.md; only after Artist Wave 1)',
+      'npm run mark:slices',
+      'npm run import:gpt-art',
+      'npm run build-atlas',
+      'npm run review:assets',
+      'npm run verify:asset-review',
+      'npm run verify:ui:assets',
+      'Invoke @developer — Ring 4 production integration (wire TILE_KEYS/loaders/bg; npm run verify:asset-code-sync)',
+      'npm run verify:asset-code-sync',
+      'npm run verify:atom-conformance',
+    ],
+    evidencePaths: ['assets/reference/marked/', 'validate/art-review/', 'validate/vision/'],
+  },
+  '4:verify': {
+    currentAction: 'Run production visual and asset gates before final Ring Gate.',
+    requiredFiles: [...COMMON_REQUIRED, 'docs/layout-spec.md', 'docs/style-exploration.md', 'logs/artist-log.md', 'logs/ta-log.md', 'logs/review-report.md', 'game/'],
+    deferredFiles: [],
+    nextRole: 'reviewer',
+    artifactRefs: ['docs/layout-spec.md', 'logs/artist-log.md', 'logs/ta-log.md', 'logs/review-report.md', 'game/', 'validate/'],
+    requiredContextFields: ['lastRole.summary', 'lastRole.validation', 'lastRole.blockers', 'sharedDecisions.assetContractRefs'],
+    allowedTasks: ['Run ui_diff', 'Run verify:visual', 'Run asset budget checks', 'Run final ring gate'],
+    forbiddenTasks: ['Do not ask user before all production gates pass'],
+    nextCommands: [
+      'Invoke @reviewer gameplay_conformance — fill § Ring DoD Fields gameplayConformance',
+      'Invoke @reviewer playable_validate — fill § Ring DoD Fields hookCta',
+      'npm run verify:vision',
+      'Invoke @reviewer ui_diff — Read each screenshot + Structured Visual Rubric → fill § Ring DoD Fields uiDiff',
+      'npm run verify:visual',
+      'npm run verify:bg-clean',
+      'npm run verify:tile-consistency',
+      'npm run verify:text-overlap',
+      'npm run verify:asset-review',
+      'npm run verify:ui:assets',
+      'npm run verify:asset-code-sync',
+      'npm run verify:atom-conformance',
+      'npm run ring:gate -- --iteration 4',
+    ],
+    evidencePaths: ['assets/reference/marked/', 'validate/art-review/', 'validate/vision/'],
+  },
+};
+
+function normalizeLoop(loop) {
+  const value = String(loop || '').trim().toLowerCase();
+  return ['clarify', 'build', 'verify'].includes(value) ? value : 'clarify';
+}
+
+function normalizeIteration(iteration) {
+  const n = Number.parseInt(String(iteration ?? '1'), 10);
+  return Number.isFinite(n) && n >= 1 && n <= 4 ? n : 1;
+}
+
+function resolveDisclosureKey({ iteration = 1, loop = 'clarify', handoff = {} } = {}) {
+  const ring = normalizeIteration(iteration);
+  const normalizedLoop = normalizeLoop(loop);
+  if (
+    ring === 1
+    && normalizedLoop === 'clarify'
+    && String(handoff.last_completed_by || '').toLowerCase() === 'game-designer'
+    && String(handoff.subagent_stop || '').toLowerCase() === 'true'
+  ) {
+    return '1:select';
+  }
+  if (
+    ring === 1
+    && normalizedLoop === 'clarify'
+    && ['skill-selector', 'ref-flow'].includes(String(handoff.last_completed_by || '').toLowerCase())
+    && String(handoff.subagent_stop || '').toLowerCase() === 'true'
+  ) {
+    return '1:scaffold';
+  }
+  return `${ring}:${normalizedLoop}`;
+}
+
+export function disclosureForState({ iteration = 1, loop = 'clarify', handoff = {} } = {}) {
+  const ring = normalizeIteration(iteration);
+  const normalizedLoop = normalizeLoop(loop);
+  const key = resolveDisclosureKey({ iteration, loop, handoff });
+  const disclosure = DISCLOSURE_BY_RING_LOOP[key] || DISCLOSURE_BY_RING_LOOP[`${ring}:${normalizedLoop}`] || DISCLOSURE_BY_RING_LOOP['1:clarify'];
+  return {
+    dispatchMode: false,
+    ring,
+    loop: normalizedLoop,
+    currentAction: disclosure.currentAction,
+    currentRingRequiredFiles: disclosure.requiredFiles,
+    deferredFiles: disclosure.deferredFiles || [],
+    allowedTasks: disclosure.allowedTasks || [],
+    forbiddenTasks: disclosure.forbiddenTasks || [],
+    nextCommands: disclosure.nextCommands || [],
+    nextRole: disclosure.nextRole || null,
+    artifactRefs: disclosure.artifactRefs || [],
+    requiredContextFields: disclosure.requiredContextFields || [],
+    evidencePaths: disclosure.evidencePaths || [],
+  };
+}
+
+/**
+ * slice-axis-v1 (Knife 6): orchestrator disclosure when an active slice is dispatched.
+ * Ring is budget/boundary only — wording must not re-introduce ring-loop as dispatch axis.
+ */
+export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
+  const ring = normalizeIteration(iteration);
+  const role = String(dispatchPacket.role || 'developer');
+  const sliceId = String(dispatchPacket.sliceId || 'active');
+  const doWhat = String(dispatchPacket.doWhat || '').trim() || '(see dispatchPacket.doWhat)';
+  const flow = String(dispatchPacket.flow || 'implement').trim();
+  const verifier = String(dispatchPacket.verifier || 'verify:slice').trim();
+  const status = String(dispatchPacket.status || 'pending').trim();
+  const allowedFiles = Array.isArray(dispatchPacket.allowedFiles) ? dispatchPacket.allowedFiles : [];
+  const packetForbidden = Array.isArray(dispatchPacket.forbiddenTasks) ? dispatchPacket.forbiddenTasks : [];
+
+  const currentAction =
+    `Orchestrator: invoke @${role} for slice "${sliceId}" — ${doWhat} (flow: ${flow}). ` +
+    `Ring ${ring} is outer budget/boundary only; do not tell the subagent "Ring ${ring} ${flow}" or ask it to self-identify Ring/Gate/Loop.`;
+
+  const nextCommands = [];
+  if (status === 'failed' && dispatchPacket.routeTo?.role) {
+    nextCommands.push(
+      `Re-dispatch slice "${sliceId}" to @${dispatchPacket.routeTo.role} (${dispatchPacket.routeTo.reason || 'routed failure'})`,
+    );
+  } else if (status === 'verified') {
+    nextCommands.push(`Slice "${sliceId}" verified — orchestrator: promote queue or dispatch next pending slice`);
+  } else {
+    nextCommands.push(`Invoke @${role} — slice ${sliceId}: ${doWhat}`);
+    nextCommands.push(`Subagent: npm run ${verifier} then npm run slice:set -- status=verified|failed …`);
+  }
+
+  return {
+    dispatchMode: true,
+    ring,
+    loop: flow,
+    currentAction,
+    currentRingRequiredFiles: [...COMMON_REQUIRED, ...allowedFiles],
+    deferredFiles: FUTURE_RING_FILES.filter((f) => !allowedFiles.includes(f)),
+    allowedTasks: [
+      `Invoke @${role} with dispatchPacket only (sliceId=${sliceId}, flow=${flow})`,
+      `Let subagent run ${verifier} and update slice via slice:set`,
+    ],
+    forbiddenTasks: [
+      'Do not dispatch by ring loop name (e.g. "Ring 1 build", "Ring 2 verify")',
+      'Do not tell subagent to self-identify Ring / Gate / Loop',
+      'Do not substitute handoff documents for dispatchPacket scope',
+      ...packetForbidden,
+    ],
+    nextCommands,
+    nextRole: role,
+    artifactRefs: allowedFiles.length ? allowedFiles : ['dispatchPacket'],
+    requiredContextFields: [
+      'dispatchPacket.sliceId',
+      'dispatchPacket.role',
+      'dispatchPacket.doWhat',
+      'dispatchPacket.flow',
+      'dispatchPacket.verifier',
+    ],
+    evidencePaths: [],
+  };
+}
+
+/** Unified entry: active dispatchPacket wins; otherwise legacy ring:loop disclosure. */
+export function disclosureForProjectState({ iteration = 1, loop = 'clarify', handoff = {}, dispatchPacket = null } = {}) {
+  if (dispatchPacket) {
+    return disclosureForSlice(dispatchPacket, { iteration });
+  }
+  return disclosureForState({ iteration, loop, handoff });
+}
+
+/** Machine-readable orchestrator next step when a slice is active. */
+export function recommendedActionForDispatch(dispatchPacket) {
+  if (!dispatchPacket) return null;
+  const { sliceId, role, doWhat, status, routeTo, verifier } = dispatchPacket;
+  if (status === 'failed' && routeTo?.role) {
+    return `Re-dispatch slice "${sliceId}" to @${routeTo.role} (${routeTo.reason || 'routed failure'})`;
+  }
+  if (status === 'verified') {
+    return `Slice "${sliceId}" verified — orchestrator: promote queue or dispatch next pending slice`;
+  }
+  if (status === 'in_progress') {
+    return `Await @${role} completing slice "${sliceId}" (${verifier || 'verify:slice'} + slice:set)`;
+  }
+  return `Invoke @${role} — slice ${sliceId}: ${doWhat || '(see dispatchPacket)'}`;
+}