@playcraft/cli 0.0.44 → 0.0.46

package/project-template/.claude/hooks/asr-coverage-validate.mjs

@@ -238,14 +238,14 @@ export function validateSheetGridMetadata(content) {
 }
 
 /**
- * @param {string} designerLog
+ * @param {string} artistLog
  * @param {string} layoutSpec
  */
-export function validateCoverageRowCount(designerLog, layoutSpec) {
+export function validateCoverageRowCount(artistLog, layoutSpec) {
   const errors = [];
   const { elementIds, staticTextIds } = parseLayoutSpecContractIds(layoutSpec);
   const expected = elementIds.length + staticTextIds.length;
-  const matrixRows = parseCoverageMatrixRows(designerLog);
+  const matrixRows = parseCoverageMatrixRows(artistLog);
 
   if (expected === 0) {
     errors.push('layout-spec: could not parse assetMapping/static text ids — fill Asset Mapping table');
@@ -270,11 +270,11 @@ export function validateCoverageRowCount(designerLog, layoutSpec) {
 }
 
 /**
- * @param {string} designerLog
+ * @param {string} artistLog
  */
-export function validateTypeRepresentatives(designerLog) {
+export function validateTypeRepresentatives(artistLog) {
   const errors = [];
-  const rows = parseCoverageMatrixRows(designerLog);
+  const rows = parseCoverageMatrixRows(artistLog);
   /** @type {Map<string, Set<string>>} */
   const typeLayers = new Map();
 
@@ -304,9 +304,9 @@ export function validateTypeRepresentatives(designerLog) {
 /**
  * @param {string} projectDir
  * @param {string} option
- * @param {string} [designerLog]
+ * @param {string} [artistLog]
  */
-export function validateAsrPngFiles(projectDir, option, designerLog) {
+export function validateAsrPngFiles(projectDir, option, artistLog) {
   const errors = [];
   const ui = path.join(projectDir, `assets/images/reference/ui_state_sheet_${option}.png`);
   const el = path.join(projectDir, `assets/images/reference/element_state_sheet_${option}.png`);
@@ -325,7 +325,7 @@ export function validateAsrPngFiles(projectDir, option, designerLog) {
     errors.push(`Missing ASR: assets/images/reference/element_state_sheet_${option}.png`);
   }
 
-  if (designerLog && /element_2|element_state_sheet_\w+_2\.png/i.test(designerLog)) {
+  if (artistLog && /element_2|element_state_sheet_\w+_2\.png/i.test(artistLog)) {
     const el2 = path.join(
       projectDir,
       `assets/images/reference/element_state_sheet_${option}_2.png`,
@@ -344,30 +344,30 @@ export function validateAsrPngFiles(projectDir, option, designerLog) {
  * @param {string} projectDir
  * @returns {string[]}
  */
-export function validateDesignerGate2b(projectDir) {
+export function validateArtistGate2b(projectDir) {
   const errors = [];
-  const logPath = path.join(projectDir, 'logs/designer-log.md');
+  const logPath = path.join(projectDir, 'logs/artist-log.md');
   const layoutPath = path.join(projectDir, 'docs/layout-spec.md');
   const statePath = path.join(projectDir, 'docs/project-state.md');
 
   if (!fs.existsSync(logPath)) {
-    return ['Create logs/designer-log.md before Gate #2b STOP'];
+    return ['Create logs/artist-log.md before ring 3 verify STOP'];
   }
   if (!fs.existsSync(layoutPath)) {
     return ['Missing docs/layout-spec.md'];
   }
 
-  const designerLog = fs.readFileSync(logPath, 'utf8');
+  const artistLog = fs.readFileSync(logPath, 'utf8');
   const layoutSpec = fs.readFileSync(layoutPath, 'utf8');
 
-  errors.push(...validateImageProductionPreflight(designerLog));
+  errors.push(...validateImageProductionPreflight(artistLog));
 
-  if (!designerLog.includes(ASR_COVERAGE_HEADING)) {
+  if (!artistLog.includes(ASR_COVERAGE_HEADING)) {
     errors.push(`Missing "${ASR_COVERAGE_HEADING}" section`);
   } else {
-    errors.push(...validateSheetGridMetadata(designerLog));
-    errors.push(...validateCoverageRowCount(designerLog, layoutSpec));
-    errors.push(...validateTypeRepresentatives(designerLog));
+    errors.push(...validateSheetGridMetadata(artistLog));
+    errors.push(...validateCoverageRowCount(artistLog, layoutSpec));
+    errors.push(...validateTypeRepresentatives(artistLog));
   }
 
   let option = 'A';
@@ -375,7 +375,7 @@ export function validateDesignerGate2b(projectDir) {
     const opt = readSelectedMcOption(fs.readFileSync(statePath, 'utf8'));
     if (opt) option = opt;
   }
-  errors.push(...validateAsrPngFiles(projectDir, option, designerLog));
+  errors.push(...validateAsrPngFiles(projectDir, option, artistLog));
 
   return errors;
 }

package/project-template/.claude/hooks/block-developer-preflight.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft Developer preflight gate — PreToolUse hook (Write|Edit).
+ *
+ * During growth rings 1-3, before any `game/**` source edit, this gate enforces
+ * that the Developer has actually wired the project's skills:
+ *   1. Selected atom skills are linked into `.claude/skills/` (link evidence) —
+ *      auto-linked by validate-atom-tree-selection.mjs on atom-tree write, so a
+ *      missing link usually means selection never happened.
+ *   2. `logs/developer-log.md` § Skill Preflight is filled (no `{{}}` template
+ *      rows, at least one row per selected atom) — proof the dev read the skills
+ *      before coding.
+ *
+ * Only `game/**` writes are gated. Writes to logs/developer-log.md (and anything
+ * else) pass through, so the developer can fill the preflight first.
+ *
+ * Exit 0 = allow
+ * Exit 2 + JSON deny = block (Claude Code PreToolUse)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  parseHandoffBlock,
+  parseHandoffYaml,
+  resolveProjectStatePath,
+} from '../../skills/_shared/scripts/state-handoff.mjs';
+
+function resolveProjectDir() {
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw)) {
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  }
+  return raw;
+}
+
+function readIteration(projectDir) {
+  const statePath = resolveProjectStatePath(projectDir);
+  if (!fs.existsSync(statePath)) return 1;
+  const block = parseHandoffBlock(fs.readFileSync(statePath, 'utf8'));
+  if (!block) return 1;
+  const handoff = parseHandoffYaml(block.yaml);
+  return Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
+}
+
+/** Selected atoms that should be linked into .claude/skills/ (excludes bundled playcraft-* skills). */
+function readSelectedAtoms(projectDir) {
+  const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+  if (!fs.existsSync(jsonPath)) return [];
+  try {
+    const tree = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    const atoms = Array.isArray(tree?.meta?.selectedAtoms) ? tree.meta.selectedAtoms : [];
+    return atoms
+      .map((a) => (typeof a === 'string' ? a.trim() : ''))
+      .filter((a) => a && !a.startsWith('{{') && !a.startsWith('playcraft-'));
+  } catch {
+    return [];
+  }
+}
+
+/** Atoms with no linked dir under .claude/skills/. */
+function missingLinks(projectDir, atoms) {
+  const skillsDir = path.join(projectDir, '.claude', 'skills');
+  return atoms.filter((atom) => !fs.existsSync(path.join(skillsDir, atom)));
+}
+
+/** Extract the "## Skill Preflight" section body (up to the next "## " heading). */
+function extractSection(content, heading) {
+  const start = content.indexOf(heading);
+  if (start === -1) return null;
+  const after = content.slice(start + heading.length);
+  const nextIdx = after.indexOf('\n## ');
+  return nextIdx === -1 ? after : after.slice(0, nextIdx);
+}
+
+/** Count filled (non-template) table data rows in a markdown section. */
+function countFilledRows(section) {
+  let count = 0;
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|[\s|:-]+\|?$/.test(trimmed)) continue; // separator row
+    if (/selectedAtomRef|Read path|怎么用/.test(trimmed)) continue; // header row
+    if (trimmed.includes('{{')) continue; // unfilled template row
+    count += 1;
+  }
+  return count;
+}
+
+function isSkillPreflightFilled(projectDir, atomCount) {
+  const logPath = path.join(projectDir, 'logs', 'developer-log.md');
+  if (!fs.existsSync(logPath)) return false;
+  const content = fs.readFileSync(logPath, 'utf8');
+  const section = extractSection(content, '## Skill Preflight');
+  if (!section) return false;
+  return countFilledRows(section) >= Math.max(1, atomCount);
+}
+
+function isGameSourcePath(filePath, projectDir) {
+  if (!filePath) return false;
+  let rel = filePath;
+  const abs = path.resolve(projectDir);
+  if (path.isAbsolute(filePath)) rel = path.relative(abs, filePath);
+  rel = rel.replace(/\\/g, '/');
+  if (rel.startsWith('../')) return false;
+  return /^game\//.test(rel) && /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(rel);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function emitDeny(reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  })}\n`);
+  process.stderr.write(`[playcraft-dev-preflight] ${reason}\n`);
+  process.exit(2);
+}
+
+export {
+  readSelectedAtoms,
+  missingLinks,
+  isSkillPreflightFilled,
+  isGameSourcePath,
+  countFilledRows,
+  extractSection,
+};
+
+async function main() {
+  const stdin = await readStdin();
+  if (!stdin.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(stdin);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || input.toolName || '';
+  if (!/^(Write|Edit|MultiEdit)$/.test(toolName)) process.exit(0);
+
+  const projectDir = resolveProjectDir();
+  const filePath =
+    input.tool_input?.file_path ||
+    input.tool_input?.filePath ||
+    input.toolInput?.file_path ||
+    '';
+  if (!isGameSourcePath(filePath, projectDir)) process.exit(0);
+
+  const iteration = readIteration(projectDir);
+  if (iteration < 1 || iteration > 3) process.exit(0);
+
+  const atoms = readSelectedAtoms(projectDir);
+
+  const unlinked = missingLinks(projectDir, atoms);
+  if (unlinked.length > 0) {
+    emitDeny(
+      `Developer preflight gate: selected atom skill(s) not linked into .claude/skills/: ${unlinked.join(', ')}. `
+      + 'Linking is automatic when docs/atom-tree.json meta.selectedAtoms is saved — re-save the atom-tree (or run playcraft skills link --from-atom-tree --prune) so the skill folders appear before editing game/.',
+    );
+  }
+
+  if (!isSkillPreflightFilled(projectDir, atoms.length)) {
+    emitDeny(
+      'Developer preflight gate: logs/developer-log.md § Skill Preflight is not filled. '
+      + 'Before editing game/, read .claude/skills/<atom>/SKILL.md for each selected atom and fill the § Skill Preflight table (one non-template row per atom: what it provides + how you use it). '
+      + 'Then generate placeholders (npm run placeholder:gen) and resume coding.',
+    );
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[playcraft-dev-preflight] ${err.message}\n`);
+  process.exit(1);
+});

package/project-template/.claude/hooks/block-ring1-tasklist.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft Ring 1 Task-list blocker — PreToolUse hook.
+ *
+ * Blocks internal Task list tools during iteration 1 so the orchestrator follows
+ * the Ring 1 Direct Path instead of creating parallel plans.
+ *
+ * Exit 0 = allow
+ * Exit 2 + JSON deny = block (Claude Code PreToolUse)
+ */
+
+import fs from 'node:fs';
+import {
+  parseHandoffBlock,
+  parseHandoffYaml,
+  resolveProjectStatePath,
+} from '../../skills/_shared/scripts/state-handoff.mjs';
+
+const RING1_BLOCKED_TOOLS = new Set([
+  'TaskCreate',
+  'TaskUpdate',
+  'TaskList',
+  'TaskGet',
+  'TaskOutput',
+  'TaskStop',
+]);
+
+function resolveProjectDir() {
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw)) {
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  }
+  return raw;
+}
+
+function readIteration(projectDir) {
+  const statePath = resolveProjectStatePath(projectDir);
+  if (!fs.existsSync(statePath)) return 1;
+  const block = parseHandoffBlock(fs.readFileSync(statePath, 'utf8'));
+  if (!block) return 1;
+  const handoff = parseHandoffYaml(block.yaml);
+  return Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function emitDeny(reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  })}\n`);
+  process.stderr.write(`[playcraft-ring1-direct] ${reason}\n`);
+  process.exit(2);
+}
+
+export { readIteration, RING1_BLOCKED_TOOLS };
+
+async function main() {
+  const stdin = await readStdin();
+  if (!stdin.trim()) process.exit(0);
+
+  let input;
+  try {
+    input = JSON.parse(stdin);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || input.toolName || '';
+  if (!RING1_BLOCKED_TOOLS.has(toolName)) {
+    process.exit(0);
+  }
+
+  const projectDir = resolveProjectDir();
+  if (readIteration(projectDir) !== 1) {
+    process.exit(0);
+  }
+
+  emitDeny(
+    `Ring 1 Dispatch Path: internal Task lists are blocked during iteration 1 (${toolName}). `
+    + `Use Task / @game-designer / temporary ref-flow atom-selection subagent / @developer spawn instead. Run npm run state:get and follow CLAUDE.md § Ring 1 Dispatch Path.`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`[playcraft-ring1-direct] ${err.message}\n`);
+  process.exit(1);
+});

package/project-template/.claude/hooks/gate-dispatcher.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft Gate Dispatcher
+ *
+ * PostToolUse hook on AskUserQuestion. Identifies which gate was confirmed
+ * and executes gate.mjs with the gate context.
+ *
+ * Claude Code / CodeBuddy version — uses CODEBUDDY_PROJECT_DIR / CLAUDE_PROJECT_DIR.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const GATE_KW = {
+  'ring-1': ['ring gate 1', 'iteration 1', 'engine root', 'core gameplay', 'ring.*1'],
+  'ring-2': ['ring gate 2', 'iteration 2', 'periphery', 'hud', 'ring.*2'],
+  'ring-3': ['ring gate 3', 'iteration 3', 'hook', 'cta', 'playable ad', 'ring.*3'],
+  'ring-4': ['ring gate 4', 'iteration 4', 'production', 'final visual', 'ring.*4'],
+};
+
+function identify(toolInput) {
+  if (!toolInput?.questions?.length) return null;
+  const t = toolInput.questions
+    .map(q => `${q.header || ''} ${q.question || ''}`).join(' ').toLowerCase();
+  for (const [k, ws] of Object.entries(GATE_KW))
+    if (ws.some(w => new RegExp(w, 'i').test(t))) return k;
+  return null;
+}
+
+function resolveProjectDir() {
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw))
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  return path.resolve(raw);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+  let p;
+  try {
+    const raw = await readStdin();
+    if (!raw.trim()) return process.exit(0);
+    p = JSON.parse(raw);
+  } catch { return process.exit(0); }
+  if (p.tool_name !== 'AskUserQuestion') process.exit(0);
+
+  const gk = identify(p.tool_input);
+  if (!gk) return process.exit(0);
+
+  const pd = resolveProjectDir();
+  const gs = path.join(__dirname, 'gate.mjs');
+  if (!fs.existsSync(gs)) { process.stderr.write(`[disp] no gate.mjs\n`); return process.exit(0); }
+
+  const ctx = JSON.stringify({ gateKey: gk, toolInput: p.tool_input, toolResponse: p.tool_response, projectDir: pd });
+  const r = spawnSync('node', [gs], {
+    encoding: 'utf8', timeout: 30_000, stdio: ['pipe','pipe','pipe'], cwd: pd,
+    env: { ...process.env, GATE_KEY: gk, GATE_CTX: ctx }, input: ctx,
+  });
+  if (r.status !== 0) process.stderr.write(`[disp] gate err (${r.status}): ${r.stderr}\n`);
+  if (r.stdout) process.stderr.write(r.stdout.trim() + '\n');
+  process.exit(0);
+}
+main().catch((err) => {
+  process.stderr.write(`[gate-dispatcher] ${err.message}\n`);
+  process.exit(1);
+});