@playcraft/cli 0.0.42 → 0.0.44

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

@@ -0,0 +1,381 @@
+/**
+ * ASR Coverage validation — shared by validate-workflow-stop.mjs and playcraft skills validate-asr-coverage.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+
+export const IMAGE_PRODUCTION_PREFLIGHT_HEADING = '## Image Production Preflight';
+export const ASR_COVERAGE_HEADING = '## ASR Coverage Matrix';
+export const REQUIRED_IMAGE_SKILLS = [
+  'playcraft-storyboard',
+  'playcraft-asset-state-sheet',
+  'playcraft-image-generation',
+];
+
+/**
+ * @param {string} content
+ */
+export function readSelectedMcOption(content) {
+  const m =
+    content.match(/selectedMcOption:\s*["']?([ABC])["']?/i) ||
+    content.match(/selectedMcOption\s*=\s*([ABC])/i);
+  return m ? m[1].toUpperCase() : null;
+}
+
+/**
+ * @param {string} layoutSpec
+ * @returns {{ elementIds: string[], staticTextIds: string[] }}
+ */
+export function parseLayoutSpecContractIds(layoutSpec) {
+  /** @type {string[]} */
+  const elementIds = [];
+  /** @type {string[]} */
+  const staticTextIds = [];
+
+  const assetSection = extractSection(layoutSpec, '## Asset Mapping');
+  if (assetSection) {
+    for (const line of assetSection.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|')) continue;
+      if (/^\|\s*---/.test(trimmed)) continue;
+      if (/^\|\s*elementId/i.test(trimmed)) continue;
+
+      const parts = trimmed
+        .split('|')
+        .map((p) => p.trim())
+        .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+      if (parts.length < 1) continue;
+      const id = parts[0].replace(/`/g, '');
+      if (!id || id === '—' || id === '-' || PLACEHOLDER_RE.test(id)) continue;
+      elementIds.push(id);
+    }
+  }
+
+  const textSection = extractSection(layoutSpec, '### Static Text');
+  if (textSection) {
+    for (const line of textSection.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|')) continue;
+      if (/^\|\s*---/.test(trimmed)) continue;
+      if (/^\|\s*id/i.test(trimmed)) continue;
+
+      const parts = trimmed
+        .split('|')
+        .map((p) => p.trim())
+        .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+      if (parts.length < 1) continue;
+      const id = parts[0].replace(/`/g, '');
+      if (!id || id === '—' || PLACEHOLDER_RE.test(id)) continue;
+      staticTextIds.push(id);
+    }
+  }
+
+  return { elementIds, staticTextIds };
+}
+
+/**
+ * @param {string} content
+ * @param {string} heading
+ */
+function extractSection(content, heading) {
+  const start = content.indexOf(heading);
+  if (start === -1) return '';
+  const after = content.slice(start + heading.length);
+  const next = after.search(/\n##\s+/);
+  return next === -1 ? after : after.slice(0, next);
+}
+
+/**
+ * @param {string} cell
+ */
+function isReadChecked(cell) {
+  const t = cell.trim();
+  if (/[✓✔☑]/.test(t)) return true;
+  if (/\[x\]/i.test(t)) return true;
+  if (/^(yes|done|true|read)$/i.test(t)) return true;
+  return false;
+}
+
+/**
+ * @param {string} content
+ */
+export function validateImageProductionPreflight(content) {
+  const errors = [];
+  const start = content.indexOf(IMAGE_PRODUCTION_PREFLIGHT_HEADING);
+  if (start === -1) {
+    return [`Missing "${IMAGE_PRODUCTION_PREFLIGHT_HEADING}" section`];
+  }
+
+  const after = content.slice(start + IMAGE_PRODUCTION_PREFLIGHT_HEADING.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  /** @type {{ skill: string, read: string, summary: string }[]} */
+  const rows = [];
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Skill/i.test(trimmed)) continue;
+
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 3) continue;
+    rows.push({ skill: parts[0], read: parts[1], summary: parts[2] });
+  }
+
+  if (rows.length === 0) {
+    errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: table has no data rows`);
+    return errors;
+  }
+
+  for (const required of REQUIRED_IMAGE_SKILLS) {
+    const row = rows.find((r) => r.skill.includes(required));
+    if (!row) {
+      errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: missing row for ${required}`);
+      continue;
+    }
+    if (!isReadChecked(row.read)) {
+      errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — mark 已读 (✓)`);
+    }
+    if (!row.summary || PLACEHOLDER_RE.test(row.summary) || row.summary.length < MIN_TAKEAWAY_LEN) {
+      errors.push(
+        `${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — add decision summary (≥${MIN_TAKEAWAY_LEN} chars)`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} content
+ */
+export function parseCoverageMatrixRows(content) {
+  const section = extractSection(content, ASR_COVERAGE_HEADING);
+  const coverageStart = section.indexOf('### Coverage');
+  const coverageBlock = coverageStart === -1 ? section : section.slice(coverageStart);
+
+  /** @type {{ contractId: string, elementType: string, coverageLayer: string }[]} */
+  const rows = [];
+  for (const line of coverageBlock.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Contract id/i.test(trimmed)) continue;
+
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 4) continue;
+
+    const contractId = parts[0].replace(/`/g, '');
+    if (!contractId || PLACEHOLDER_RE.test(contractId)) continue;
+
+    const typeValues = new Set(['visual', 'audio', 'text', 'digit', 'sfx']);
+    let elementType = '';
+    let coverageLayer = '';
+
+    if (parts.length >= 4 && typeValues.has(parts[2]?.toLowerCase())) {
+      elementType = parts[1];
+      coverageLayer = parts[3];
+    } else if (parts.length >= 3 && typeValues.has(parts[1]?.toLowerCase())) {
+      coverageLayer = parts[2];
+    } else {
+      elementType = parts.length >= 6 ? parts[1] : '';
+      coverageLayer = parts.length >= 4 ? parts[3] : parts[1] || '';
+    }
+
+    rows.push({
+      contractId,
+      elementType: elementType.replace(/`/g, ''),
+      coverageLayer: coverageLayer.toLowerCase(),
+    });
+  }
+  return rows;
+}
+
+/**
+ * @param {string} content
+ */
+export function validateSheetGridMetadata(content) {
+  const errors = [];
+  const section = extractSection(content, ASR_COVERAGE_HEADING);
+  if (!section.includes('### Sheet grid metadata')) {
+    errors.push('ASR Coverage Matrix: missing ### Sheet grid metadata table');
+    return errors;
+  }
+
+  const gridStart = section.indexOf('### Sheet grid metadata');
+  const gridBlock = section.slice(gridStart);
+  const gridEnd = gridBlock.search(/\n###\s+/);
+  const gridSection = gridEnd === -1 ? gridBlock : gridBlock.slice(0, gridEnd);
+
+  if (PLACEHOLDER_RE.test(gridSection)) {
+    errors.push('Sheet grid metadata: contains {{placeholders}} — fill real rows/cols/cell dimensions');
+  }
+
+  let dataRows = 0;
+  for (const line of gridSection.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Sheet/i.test(trimmed)) continue;
+    dataRows++;
+  }
+  if (dataRows < 2) {
+    errors.push('Sheet grid metadata: need at least ui + element sheet rows');
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} designerLog
+ * @param {string} layoutSpec
+ */
+export function validateCoverageRowCount(designerLog, layoutSpec) {
+  const errors = [];
+  const { elementIds, staticTextIds } = parseLayoutSpecContractIds(layoutSpec);
+  const expected = elementIds.length + staticTextIds.length;
+  const matrixRows = parseCoverageMatrixRows(designerLog);
+
+  if (expected === 0) {
+    errors.push('layout-spec: could not parse assetMapping/static text ids — fill Asset Mapping table');
+    return errors;
+  }
+
+  if (matrixRows.length < expected) {
+    errors.push(
+      `Coverage Matrix: ${matrixRows.length} rows but layout-spec expects ${expected} (assetMapping + static text)`,
+    );
+  }
+
+  const contractSet = new Set([...elementIds, ...staticTextIds]);
+  const matrixIds = new Set(matrixRows.map((r) => r.contractId));
+  for (const id of contractSet) {
+    if (!matrixIds.has(id)) {
+      errors.push(`Coverage Matrix: missing row for contract id "${id}"`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} designerLog
+ */
+export function validateTypeRepresentatives(designerLog) {
+  const errors = [];
+  const rows = parseCoverageMatrixRows(designerLog);
+  /** @type {Map<string, Set<string>>} */
+  const typeLayers = new Map();
+
+  for (const row of rows) {
+    const type = row.elementType && row.elementType !== '—' ? row.elementType : row.contractId.split('_')[0];
+    if (!type) continue;
+    if (!typeLayers.has(type)) typeLayers.set(type, new Set());
+    typeLayers.get(type).add(row.coverageLayer);
+  }
+
+  for (const [type, layers] of typeLayers) {
+    const hasRep =
+      [...layers].some((l) => l.includes('on-asr')) || [...layers].some((l) => l.includes('mc-crop'));
+    if (!hasRep && layers.size > 0) {
+      const allExtends = [...layers].every((l) => l.includes('ta-extends') || l.includes('ta extends'));
+      if (allExtends) {
+        errors.push(
+          `Coverage Matrix: elementType "${type}" has no on-asr or mc-crop representative`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string} option
+ * @param {string} [designerLog]
+ */
+export function validateAsrPngFiles(projectDir, option, designerLog) {
+  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`);
+  const mc = path.join(
+    projectDir,
+    `assets/images/storyboard/master_composite_option_${option}.png`,
+  );
+
+  if (!fs.existsSync(mc)) {
+    errors.push(`Missing MC: assets/images/storyboard/master_composite_option_${option}.png`);
+  }
+  if (!fs.existsSync(ui)) {
+    errors.push(`Missing ASR: assets/images/reference/ui_state_sheet_${option}.png`);
+  }
+  if (!fs.existsSync(el)) {
+    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)) {
+    const el2 = path.join(
+      projectDir,
+      `assets/images/reference/element_state_sheet_${option}_2.png`,
+    );
+    if (!fs.existsSync(el2)) {
+      errors.push(
+        `Missing ASR overflow board: assets/images/reference/element_state_sheet_${option}_2.png`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {string[]}
+ */
+export function validateDesignerGate2b(projectDir) {
+  const errors = [];
+  const logPath = path.join(projectDir, 'logs/designer-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'];
+  }
+  if (!fs.existsSync(layoutPath)) {
+    return ['Missing docs/layout-spec.md'];
+  }
+
+  const designerLog = fs.readFileSync(logPath, 'utf8');
+  const layoutSpec = fs.readFileSync(layoutPath, 'utf8');
+
+  errors.push(...validateImageProductionPreflight(designerLog));
+
+  if (!designerLog.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));
+  }
+
+  let option = 'A';
+  if (fs.existsSync(statePath)) {
+    const opt = readSelectedMcOption(fs.readFileSync(statePath, 'utf8'));
+    if (opt) option = opt;
+  }
+  errors.push(...validateAsrPngFiles(projectDir, option, designerLog));
+
+  return errors;
+}

package/project-template/.claude/hooks/validate-workflow-stop.mjs

@@ -11,10 +11,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { validateDesignerGate2b } from './asr-coverage-validate.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 
 const INTAKE_HEADING = '## Upstream Intake';
+const SKILL_PREFLIGHT_HEADING = '## Skill Preflight';
 const PLAN_HEADING = {
   'technical-artist': '## Production Plan',
   developer: '## UI Pass Plan', // default; gameplay_pass uses ## Gameplay Pass Plan
@@ -49,9 +51,13 @@ const TA_REQUIRED_DOCS = [
 
 const DEV_REQUIRED_DOCS = [...TA_REQUIRED_DOCS, 'logs/ta-log.md'];
 
+// Designer does not perform Upstream Intake (Designer is the upstream itself). Only Skill Preflight is enforced in Phase 2 (stage = production).
+const DESIGNER_REQUIRED_DOCS = [];
+
 const ROLE_LOG = {
   'technical-artist': { log: 'logs/ta-log.md', docs: TA_REQUIRED_DOCS, label: 'Technical Artist' },
   developer: { log: 'logs/developer-log.md', docs: DEV_REQUIRED_DOCS, label: 'Developer' },
+  designer: { log: 'logs/designer-log.md', docs: DESIGNER_REQUIRED_DOCS, label: 'Designer' },
 };
 
 /** @param {string} raw */
@@ -74,7 +80,7 @@ function normalizeRole(s) {
 
 /**
  * @param {Record<string, unknown>} input
- * @returns {'technical-artist' | 'developer' | null}
+ * @returns {'technical-artist' | 'developer' | 'designer' | null}
  */
 function detectRole(input) {
   const candidates = [
@@ -90,6 +96,7 @@ function detectRole(input) {
     const n = normalizeRole(String(c));
     if (n.includes('technical-artist') || n === 'ta') return 'technical-artist';
     if (n === 'developer' || n === 'dev') return 'developer';
+    if (n === 'designer') return 'designer';
   }
 
   const blobs = [
@@ -235,20 +242,93 @@ function validatePlan(content, role, stage) {
   return errors;
 }
 
-/** @param {string} projectDir */
+// All convergence-v1 stages
+const STAGE_NAMES =
+  '(pm|style_exploration|production|ui_pass|ui_review|ui_rework|gameplay_pass|done)';
+const STAGE_MARKDOWN_BOLD_RE = new RegExp(`\\*\\*${STAGE_NAMES}\\*\\*`, 'i');
+const STAGE_BACKTICK_RE = new RegExp(`stage[=:\\s]+\`${STAGE_NAMES}\``, 'i');
+// YAML form inside ```yaml ... ``` block: `stage: ui_pass` (no backticks around value)
+const STAGE_YAML_RE = new RegExp(`^\\s*stage:\\s*${STAGE_NAMES}\\s*$`, 'im');
+
+/**
+ * Extract current `stage` value from `docs/project-state.md`. Returns null if not found.
+ * Tries three forms (in order):
+ *   1. Markdown bold:   `**ui_pass**` — used in Current Stage header
+ *   2. Backtick form:   `` stage: `ui_pass` `` — used in prose
+ *   3. YAML form:       `stage: ui_pass` — used in `## Agent handoff` YAML fence (most authoritative)
+ * @param {string} projectDir
+ */
 function readStage(projectDir) {
   const statePath = path.join(projectDir, 'docs/project-state.md');
   if (!fs.existsSync(statePath)) return null;
   const content = fs.readFileSync(statePath, 'utf8');
   const m =
-    content.match(/\*\*(ui_pass|ui_rework|gameplay_pass|production|pm)\*\*/i) ||
-    content.match(/stage[=:\s]+`(ui_pass|ui_rework|gameplay_pass|production|pm)`/i);
+    content.match(STAGE_YAML_RE) ||
+    content.match(STAGE_MARKDOWN_BOLD_RE) ||
+    content.match(STAGE_BACKTICK_RE);
+  return m ? m[1].toLowerCase() : null;
+}
+
+function readGatePending(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) return null;
+  const content = fs.readFileSync(statePath, 'utf8');
+  const m =
+    content.match(/gate_pending:\s*["']?(1|2a|2b|3)["']?/i) ||
+    content.match(/gate_pending:\s*(1|2a|2b|3)/i);
   return m ? m[1].toLowerCase() : null;
 }
 
+/**
+ * Validate Designer Skill Preflight section (Phase 2 / production only).
+ * @param {string} content
+ */
+function validateDesignerSkillPreflight(content) {
+  const errors = [];
+  const start = content.indexOf(SKILL_PREFLIGHT_HEADING);
+  if (start === -1) {
+    return [`Missing "${SKILL_PREFLIGHT_HEADING}" section — fill before Phase 2 STOP`];
+  }
+  const after = content.slice(start + SKILL_PREFLIGHT_HEADING.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  // Each non-header data row: | Skill | 已读 | 关键决策摘要 |
+  const rows = [];
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Skill/i.test(trimmed)) continue;
+
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 3) continue;
+    rows.push({ skill: parts[0], read: parts[1], summary: parts[2] });
+  }
+
+  if (rows.length === 0) {
+    errors.push(`${SKILL_PREFLIGHT_HEADING}: table has no data rows`);
+    return errors;
+  }
+  for (const row of rows) {
+    if (!isReadChecked(row.read)) {
+      errors.push(`${SKILL_PREFLIGHT_HEADING}: "${row.skill}" — mark Read column (✓) after reading`);
+    }
+    if (!row.summary || PLACEHOLDER_RE.test(row.summary) || row.summary.length < MIN_TAKEAWAY_LEN) {
+      errors.push(
+        `${SKILL_PREFLIGHT_HEADING}: "${row.skill}" — add a concrete decision summary (≥${MIN_TAKEAWAY_LEN} chars, no {{placeholders}})`,
+      );
+    }
+  }
+  return errors;
+}
+
 /**
  * @param {string} projectDir
- * @param {'technical-artist' | 'developer'} role
+ * @param {'technical-artist' | 'developer' | 'designer'} role
  */
 function validateRole(projectDir, role) {
   const cfg = ROLE_LOG[role];
@@ -256,11 +336,26 @@ function validateRole(projectDir, role) {
 
   if (!fs.existsSync(logPath)) {
     return [
-      `${cfg.label}: create ${cfg.log} from templates/${path.basename(cfg.log).replace('.md', '.template.md')} and complete § Upstream Intake before STOP.`,
+      `${cfg.label}: create ${cfg.log} from templates/${path.basename(cfg.log).replace('.md', '.template.md')} before STOP.`,
     ];
   }
 
   const content = fs.readFileSync(logPath, 'utf8');
+
+  if (role === 'designer') {
+    const stage = readStage(projectDir);
+    if (stage === 'production') {
+      return validateDesignerSkillPreflight(content);
+    }
+    if (stage === 'style_exploration') {
+      const gatePending = readGatePending(projectDir);
+      if (gatePending === '2b') {
+        return validateDesignerGate2b(projectDir);
+      }
+    }
+    return [];
+  }
+
   const intakeErrors = validateIntakeContent(content, cfg.docs);
   const stage = role === 'developer' ? readStage(projectDir) : undefined;
   const planErrors = validatePlan(content, role, stage ?? undefined);
@@ -296,12 +391,16 @@ export {
   parseUpstreamIntake,
   validateIntakeContent,
   validatePlan,
+  validateDesignerSkillPreflight,
   validateRole,
   readStage,
+  readGatePending,
   TA_REQUIRED_DOCS,
   DEV_REQUIRED_DOCS,
+  DESIGNER_REQUIRED_DOCS,
   PLAN_HEADING,
   PLAN_REQUIRED_SUBS,
+  ROLE_LOG,
 };
 
 async function main() {
@@ -325,7 +424,14 @@ async function main() {
 
   const errors = validateRole(projectDir, role);
   if (errors.length > 0) {
-    const reason = `${ROLE_LOG[role].label} STOP blocked — fix logs/${role === 'technical-artist' ? 'ta' : 'developer'}-log.md § Upstream Intake:\n- ${errors.join('\n- ')}`;
+    const logPath = ROLE_LOG[role].log;
+    const section =
+      role === 'designer'
+        ? readStage(projectDir) === 'style_exploration'
+          ? '§ Image Production Preflight / ASR Coverage Matrix'
+          : '§ Skill Preflight'
+        : '§ Upstream Intake / Plan';
+    const reason = `${ROLE_LOG[role].label} STOP blocked — fix ${logPath} ${section}:\n- ${errors.join('\n- ')}`;
     emitBlock(reason);
   }