@playcraft/cli 0.0.55 → 0.0.57

package/project-template/skills/_shared/scripts/verify-design-consistency.mjs

@@ -0,0 +1,728 @@
+#!/usr/bin/env node
+/**
+ * Semantic + consistency checks for Game Designer Ring 1 deliverables.
+ * Does NOT require GD to fill KPI numbers — metrics are derived.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { detectFusionIntent, readFusionIntentFromProject } from './lib/fusion-intent.mjs';
+import { validateSkillFidelity } from './lib/skill-fidelity.mjs';
+import { validateLevelSketch } from './validate-level-sketch.mjs';
+import { parseDesignFusionType } from '../../playable-record/scripts/verify-fusion.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false };
+  for (const arg of argv) {
+    if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) opts.root = resolve(arg.slice('--root='.length));
+  }
+  return opts;
+}
+
+function readFile(root, rel) {
+  const p = join(root, rel);
+  return existsSync(p) ? readFileSync(p, 'utf8') : '';
+}
+
+/** @param {string} design */
+export function validateAnimationSpine(design) {
+  const problems = [];
+  const hasSpineHeader =
+    /Feedback\s*&\s*Animation\s*Spine|Animation\s*Spine|Event\s*Catalog/i.test(design);
+  if (!hasSpineHeader) {
+    problems.push('DESIGN.md missing §8 Feedback & Animation Spine (Event Catalog table)');
+    return problems;
+  }
+  const tableRows = design.match(/^\|[^|\n]+\|/gm) ?? [];
+  const eventRows = tableRows.filter(
+    (row) =>
+      /slide_out|blocked|fly_to_tray|match_clear|win/i.test(row) &&
+      !/Event\s*\|/i.test(row) &&
+      !/^[-| ]+$/.test(row.trim()),
+  );
+  if (eventRows.length < 4) {
+    problems.push('§8 Event Catalog must include at least 4 event rows (slide_out, blocked, match_clear, …)');
+  }
+  const blob = design.toLowerCase();
+  for (const ev of ['slide_out', 'blocked', 'match_clear']) {
+    if (!blob.includes(ev)) {
+      problems.push(`§8 Animation Spine missing required event: ${ev}`);
+    }
+  }
+  return problems;
+}
+
+const GENERIC_FILLER_PATTERNS = [
+  /解谜.*箭头/i,
+  /tap.*三消/i,
+  /找出.*移除/i,
+  /像解谜一样/i,
+  /像.*一样找出/i,
+  /安全移除的箭头/i,
+  /普通.*三消/i,
+];
+
+const MECHANISM_VERB_RE = /tap|click|watch|feed|slide|match|clear|remove|push|drag|点|推|消|移/i;
+const MECHANISM_NOUN_RE =
+  /arrow|path|tray|board|tile|color|block|puzzle|elim|箭头|路径|托盘|棋盘|方块|消除/i;
+const EMOTION_TENSION_RE =
+  /debt|tension|stakes|panic|relief|thrill|satisf|fear|hope|bet|wire|walk|钢丝|债务|压力|赌|紧张|爽|险|排雷|走钢丝/i;
+
+/** @param {string} text */
+export function isMechanismChainOneLiner(text) {
+  const t = String(text || '').trim();
+  if (t.length < 15) return false;
+  const hasMechanism = MECHANISM_VERB_RE.test(t) && MECHANISM_NOUN_RE.test(t);
+  const hasEmotion = EMOTION_TENSION_RE.test(t);
+  const segments = t.split(/[,，;；—–-]/).filter((s) => MECHANISM_VERB_RE.test(s));
+  return hasMechanism && !hasEmotion && segments.length >= 2;
+}
+
+/** @param {string} northStarMd */
+function extractNorthStarOneLinerFromFile(northStarMd) {
+  const section = northStarMd.match(/##\s*One-liner([\s\S]*?)(?=\n##\s|$)/i)?.[1] ?? northStarMd;
+  const labeled = extractLabeledLine(section, 'One-liner') || extractLabeledLine(section, '一句话');
+  if (labeled) return labeled;
+  const lines = section
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return lines[0] ?? '';
+}
+
+/** @returns {boolean} */
+export function isCreativeDirectorSplitEnabledForVerify() {
+  const raw = String(process.env.CREATIVE_DIRECTOR_SPLIT ?? '1').trim().toLowerCase();
+  return raw !== '0' && raw !== 'false' && raw !== 'off';
+}
+
+const NORTH_STAR_STOP_WORDS = new Set([
+  'the',
+  'and',
+  'this',
+  'that',
+  'with',
+  'player',
+  'game',
+  '玩家',
+  '游戏',
+  '一个',
+  '进行',
+  '通过',
+]);
+
+/** @returns {'off' | 'warn' | 'block'} */
+export function getNorthStarMode() {
+  const raw = String(process.env.NORTH_STAR_MODE ?? 'warn').trim().toLowerCase();
+  if (raw === 'off' || raw === '0' || raw === 'false') return 'off';
+  if (raw === 'block' || raw === 'error') return 'block';
+  return 'warn';
+}
+
+/** @param {string} text */
+function tokenizeMeaningful(text) {
+  const tokens = new Set();
+  const parts = text.toLowerCase().match(/[\u4e00-\u9fff]{2,}|[a-z]{3,}/g) ?? [];
+  for (const part of parts) {
+    if (!NORTH_STAR_STOP_WORDS.has(part)) tokens.add(part);
+  }
+  return tokens;
+}
+
+/** @param {string} text */
+function chineseBigrams(text) {
+  const chars = text.replace(/[^\u4e00-\u9fff]/g, '');
+  const bg = new Set();
+  for (let i = 0; i < chars.length - 1; i += 1) {
+    bg.add(chars.slice(i, i + 2));
+  }
+  return bg;
+}
+
+/** @param {string} a @param {string} b */
+export function keywordOverlapScore(a, b) {
+  const ta = tokenizeMeaningful(a);
+  const tb = tokenizeMeaningful(b);
+  let score = 0;
+  if (ta.size > 0 && tb.size > 0) {
+    let shared = 0;
+    for (const t of ta) {
+      if (tb.has(t)) shared += 1;
+    }
+    score = shared / Math.min(ta.size, tb.size);
+  }
+  const ba = chineseBigrams(a);
+  const bb = chineseBigrams(b);
+  if (ba.size > 0 && bb.size > 0) {
+    let sharedBg = 0;
+    for (const bg of ba) {
+      if (bb.has(bg)) sharedBg += 1;
+    }
+    score = Math.max(score, sharedBg / Math.min(ba.size, bb.size));
+  }
+  return score;
+}
+
+/** @param {string} text */
+function countGenericFillerHits(text) {
+  return GENERIC_FILLER_PATTERNS.filter((re) => re.test(text)).length;
+}
+
+/** @param {string} design */
+function extractNorthStarSection(design) {
+  const m = design.match(/##\s*0[^\n]*Creative North Star([\s\S]*?)(?=\n##\s|$)/i);
+  return m?.[1] ?? '';
+}
+
+/** @param {string} section */
+function extractLabeledLine(section, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^\\*\\*${escaped}\\*\\*\\s*:+\\s*(.+)$`, 'im');
+  return section.match(re)?.[1]?.trim() ?? '';
+}
+
+/** @returns {'off' | 'warn' | 'block'} */
+export function getStorySpineMode() {
+  const raw = String(process.env.STORY_SPINE_MODE ?? 'warn').trim().toLowerCase();
+  if (raw === 'off' || raw === '0' || raw === 'false') return 'off';
+  if (raw === 'block' || raw === 'error') return 'block';
+  return 'warn';
+}
+
+/** @param {string} md */
+function extractMicroStorySpineSection(md) {
+  const m = md.match(/##\s*Micro-Story\s*Spine([\s\S]*?)(?=\n##\s|$)/i);
+  return m?.[1] ?? '';
+}
+
+/** @param {string} md */
+export function extractStorySpineFields(md) {
+  const section = extractMicroStorySpineSection(md);
+  if (!section.trim()) return null;
+  return {
+    narrativeLevel: extractLabeledLine(section, 'Narrative level'),
+    who: extractLabeledLine(section, 'Who'),
+    situation: extractLabeledLine(section, 'Situation'),
+    stakes: extractLabeledLine(section, 'Stakes'),
+    payoffImage:
+      extractLabeledLine(section, 'Payoff image') || extractLabeledLine(section, 'Payoff'),
+    emotionalArc: extractLabeledLine(section, 'Emotional arc'),
+  };
+}
+
+/** @param {string} raw */
+function normalizeNarrativeLevel(raw) {
+  const t = String(raw || '').trim().toUpperCase();
+  const m = t.match(/\b(L[0-3])\b/);
+  return m?.[1] ?? '';
+}
+
+/** @param {string} text */
+function storyFieldLen(text) {
+  const t = String(text || '').trim();
+  if (!t || /^n\/a$/i.test(t)) return 0;
+  return t.length;
+}
+
+/** @param {string} creativeProcess */
+function hasL0OptOutInCreativeProcess(creativeProcess) {
+  if (!creativeProcess.trim()) return false;
+  const phase3 =
+    creativeProcess.match(/Phase\s*3[\s\S]*?(?=Phase\s*4|\n##\s|$)/i)?.[0] ?? creativeProcess;
+  return /纯机制|不要故事|no story|pure mechanic|\bL0\b|opt-out|opt out|用户.*(不要|无需|明确).*(故事|叙事)/i.test(
+    phase3,
+  );
+}
+
+/**
+ * Micro-Story Spine validation — independent from validateNorthStar.
+ * @param {string} northStarMd
+ * @param {string} [design]
+ * @param {string} [creativeProcess]
+ * @param {string} [oneLiner]
+ */
+export function validateStorySpine(northStarMd, design = '', creativeProcess = '', oneLiner = '') {
+  const problems = [];
+  const warnings = [];
+  const metrics = {
+    storySpineComplete: false,
+    narrativeLevel: /** @type {string | null} */ (null),
+    spinePresent: false,
+  };
+
+  const nsFields = northStarMd ? extractStorySpineFields(northStarMd) : null;
+  metrics.spinePresent = Boolean(nsFields);
+
+  if (!nsFields) {
+    problems.push('docs/north-star.md missing ## Micro-Story Spine section');
+    return { ok: false, problems, warnings, metrics };
+  }
+
+  const level = normalizeNarrativeLevel(nsFields.narrativeLevel);
+  metrics.narrativeLevel = level || null;
+
+  if (!level || !/^L[0-3]$/.test(level)) {
+    problems.push('Micro-Story Spine: Narrative level must be L0, L1, or L2');
+  } else if (level === 'L3') {
+    warnings.push('Micro-Story Spine: L3 not supported — suggest downgrade to L2');
+  }
+
+  if (level === 'L0') {
+    if (storyFieldLen(nsFields.situation) < 8) {
+      problems.push('Micro-Story Spine L0: Situation must be ≥8 chars');
+    }
+    if (storyFieldLen(nsFields.payoffImage) < 8) {
+      problems.push('Micro-Story Spine L0: Payoff image must be ≥8 chars');
+    }
+    if (!hasL0OptOutInCreativeProcess(creativeProcess)) {
+      problems.push(
+        'Micro-Story Spine L0: creative-process Phase 3 must cite user opt-out of story',
+      );
+    }
+  } else if (level === 'L1' || level === 'L2') {
+    for (const [label, val] of [
+      ['Who', nsFields.who],
+      ['Situation', nsFields.situation],
+      ['Stakes', nsFields.stakes],
+      ['Payoff image', nsFields.payoffImage],
+    ]) {
+      if (storyFieldLen(val) < 8) {
+        problems.push(`Micro-Story Spine ${level}: ${label} must be ≥8 chars`);
+      }
+    }
+  }
+
+  const designFields = design ? extractStorySpineFields(design) : null;
+  if (designFields) {
+    for (const [label, nsVal, designVal] of [
+      ['Narrative level', nsFields.narrativeLevel, designFields.narrativeLevel],
+      ['Who', nsFields.who, designFields.who],
+      ['Situation', nsFields.situation, designFields.situation],
+      ['Stakes', nsFields.stakes, designFields.stakes],
+      ['Payoff image', nsFields.payoffImage, designFields.payoffImage],
+      ['Emotional arc', nsFields.emotionalArc, designFields.emotionalArc],
+    ]) {
+      const trimmedDesign = String(designVal || '').trim();
+      const trimmedNs = String(nsVal || '').trim();
+      if (trimmedDesign && trimmedNs !== trimmedDesign) {
+        problems.push(`DESIGN §0 Micro-Story ${label} must match north-star.md`);
+      }
+    }
+  }
+
+  if ((level === 'L1' || level === 'L2') && oneLiner) {
+    const hasTension = EMOTION_TENSION_RE.test(oneLiner);
+    const hasEntity =
+      storyFieldLen(nsFields.who) >= 8 || storyFieldLen(nsFields.situation) >= 8;
+    if (hasTension && !hasEntity) {
+      warnings.push(
+        'One-liner has tension vocabulary but lacks Who/Situation entity grounding',
+      );
+    }
+  }
+
+  const levelOk = level === 'L0' || level === 'L1' || level === 'L2';
+  metrics.storySpineComplete = problems.length === 0 && levelOk;
+
+  const mode = getStorySpineMode();
+  const blocking = mode === 'block' ? [...problems, ...warnings] : problems;
+  return {
+    ok: blocking.length === 0,
+    problems,
+    warnings,
+    metrics,
+  };
+}
+
+/** @param {string} design */
+function extractPlayerFantasy(design) {
+  const m = design.match(/Player Fantasy[:\s]*([\s\S]*?)(?=\n(?:Decision Moment|First Level|##\s*\d|$))/i);
+  return m?.[1]?.trim().replace(/\n+/g, ' ') ?? '';
+}
+
+/** @param {string} design @param {string} brief @param {string} creativeProcess @param {string} [northStarMd] */
+export function validateNorthStar(design, brief, creativeProcess, northStarMd = '') {
+  const mode = getNorthStarMode();
+  const metrics = {
+    northStarPresent: false,
+    oneLinerLength: 0,
+    genericFillerHit: false,
+    mechanismChainLikely: false,
+    northStarSyncOk: null,
+    creativePhase1Candidates: 0,
+    intentSyncScore: 0,
+    playerFantasyOverlap: 0,
+    mode,
+  };
+  const problems = [];
+  const warnings = [];
+
+  if (mode === 'off') {
+    return { problems, warnings, metrics, ok: true };
+  }
+
+  const hasHeader = /Creative North Star|创意锚点/i.test(design);
+  const section = extractNorthStarSection(design);
+  const oneLiner = extractLabeledLine(section, 'One-liner') || extractLabeledLine(section, '一句话');
+  metrics.oneLinerLength = oneLiner.length;
+  metrics.northStarPresent = hasHeader && oneLiner.length >= 15;
+
+  if (!hasHeader) problems.push('missing §0 Creative North Star section');
+  else if (oneLiner.length < 15) problems.push('§0 One-liner too short (need ≥15 chars)');
+
+  const playerFantasy = extractPlayerFantasy(design);
+  if (oneLiner && playerFantasy) {
+    metrics.playerFantasyOverlap = keywordOverlapScore(oneLiner, playerFantasy);
+    if (metrics.northStarPresent && metrics.playerFantasyOverlap < 0.15) {
+      problems.push('Player Fantasy shares no keywords with §0 One-liner');
+    }
+  }
+
+  const genericHits = countGenericFillerHits(`${oneLiner}\n${playerFantasy}`);
+  metrics.genericFillerHit = genericHits >= 2;
+  if (metrics.genericFillerHit) {
+    problems.push('generic filler patterns in One-liner + Player Fantasy (≥2 hits)');
+  }
+
+  const nsSpineFields = northStarMd ? extractStorySpineFields(northStarMd) : null;
+  const narrativeLevel = nsSpineFields ? normalizeNarrativeLevel(nsSpineFields.narrativeLevel) : '';
+
+  metrics.mechanismChainLikely = isMechanismChainOneLiner(oneLiner);
+  if (metrics.mechanismChainLikely && narrativeLevel !== 'L0') {
+    problems.push('§0 One-liner reads like a mechanism chain — add feeling/tension vocabulary');
+  }
+
+  const candidateCount = (creativeProcess.match(/###\s*Candidate\s+[ABC]/gi) || []).length;
+  metrics.creativePhase1Candidates = candidateCount;
+  if (creativeProcess && candidateCount < 3) {
+    warnings.push('creative-process Phase 1 needs ≥3 candidates (Candidate A/B/C)');
+  }
+
+  if (isCreativeDirectorSplitEnabledForVerify() && northStarMd.trim()) {
+    const nsOneLiner = extractNorthStarOneLinerFromFile(northStarMd);
+    metrics.northStarSyncOk = nsOneLiner.length > 0 && nsOneLiner === oneLiner;
+    if (oneLiner && nsOneLiner && !metrics.northStarSyncOk) {
+      problems.push('DESIGN §0 One-liner must verbatim match docs/north-star.md');
+    }
+  } else if (isCreativeDirectorSplitEnabledForVerify() && !northStarMd.trim() && oneLiner) {
+    warnings.push('docs/north-star.md missing — spec mode expects standalone north star file');
+  }
+
+  const designIntent =
+    creativeProcess.match(/\*\*Design Intent\*\*[:\s]*([^\n]+)/i)?.[1]?.trim() ?? '';
+  if (designIntent && oneLiner) {
+    metrics.intentSyncScore = keywordOverlapScore(designIntent, oneLiner);
+    if (metrics.intentSyncScore < 0.3) {
+      warnings.push('creative-process Design Intent weakly synced with §0 One-liner');
+    }
+  }
+
+  const fusionSec = design.match(/##\s*6\.?\s*Gameplay Fusion([\s\S]*?)(?=\n##\s*7|$)/i)?.[1] ?? '';
+  const servesIdea = /serves|服务|because|因为|This fusion serves/i.test(fusionSec);
+  if (metrics.northStarPresent && !servesIdea) {
+    problems.push('§6 Gameplay Fusion must explain how fusion serves §0 (serves/because/服务/因为)');
+  }
+
+  if (brief && !/Creative Angle|Idea hook|Anti-generic/i.test(brief)) {
+    warnings.push('design-brief missing Creative Angle section');
+  }
+
+  const blocking = mode === 'block' ? [...problems, ...warnings] : problems;
+  return {
+    problems: blocking,
+    warnings: mode === 'warn' ? [...problems, ...warnings].map((p) => `[north-star-warn] ${p}`) : [],
+    metrics,
+    ok: mode === 'warn' ? true : blocking.length === 0,
+  };
+}
+
+/** @param {string} content @param {string} brief @param {boolean} fusionIntent */
+function validateSemantic(content, brief, fusionIntent) {
+  const problems = [];
+  if (!/Player Fantasy|Player Promise|玩家.*(幻想|承诺)/i.test(content + brief)) {
+    problems.push('missing Player Fantasy / Player Promise');
+  }
+  if (!/Decision Moment|决策时刻|啊哈|误点|blocked/i.test(content + brief)) {
+    problems.push('missing Decision Moment (describe one aha/mis-tap moment)');
+  }
+  const fusion = parseDesignFusionType(content);
+  if (!fusion.type) {
+    problems.push('DESIGN.md missing Fusion type: (## 6. Gameplay Fusion)');
+  } else if (fusionIntent && fusion.type === 'Single' && !fusion.isPseudoFusion) {
+    problems.push('fusion intent but Fusion type is Single without pseudo-fusion / downgrade reason');
+  }
+  const hasReference =
+    /Reference insight|Pattern picked|playcraft patterns match/i.test(brief) ||
+    /researchSkippedReason/i.test(brief);
+  if (!hasReference) {
+    problems.push('design-brief missing Reference insight or Pattern picked (or researchSkippedReason)');
+  }
+  return problems;
+}
+
+/** @param {string} content */
+function extractFirstLevelScenario(content) {
+  const m = content.match(/First Level Scenario[*_\s]*:?\s*([\s\S]*?)(?=\n###|\n## |$)/i);
+  return m?.[1]?.trim() ?? '';
+}
+
+/** @param {string} design */
+function extractDesignProseBundle(design) {
+  const scenario = extractFirstLevelScenario(design);
+  const sec7 = design.match(/##\s*7\.[\s\S]*?(?=\n##\s*\d|$)/i)?.[0] ?? '';
+  return `${scenario}\n${sec7}`;
+}
+
+/**
+ * @param {Record<string, unknown>} obj
+ * @param {{ pathCount?: number, openingRemovableCount?: number, hasBlockedPaths?: boolean }} [levelMetrics]
+ */
+export function deriveSketchTopology(obj, levelMetrics) {
+  const arrows = Array.isArray(obj.arrows) ? obj.arrows : [];
+  const pathPuzzle = arrows.some((a) => Array.isArray(a) && a.length > 1);
+  const serialized = JSON.stringify(obj);
+  const hasTray =
+    typeof obj.trayCapacity === 'number' ||
+    typeof obj.matchCount === 'number' ||
+    /trayCapacity|matchCount|"tray"|match-3/i.test(serialized);
+  return {
+    pathPuzzle,
+    hasTray,
+    boardSize: `${obj.row ?? 0}x${obj.col ?? 0}`,
+    pathCount: levelMetrics?.pathCount ?? arrows.length,
+    openingRemovableCount: levelMetrics?.openingRemovableCount ?? 0,
+    hasBlockedPaths: levelMetrics?.hasBlockedPaths ?? false,
+  };
+}
+
+/** @param {string} text */
+export function deriveProseProfile(text) {
+  const t = text.toLowerCase();
+  return {
+    claimsAllFree:
+      /all free|all paths free|zero blocking|无阻挡|均可推出|任意顺序|any tap order|all unblocked|全部.*free|无遮挡.*均可|均可.*点击/i.test(
+        text,
+      ),
+    claimsBlocked:
+      /blocked|阻挡|遮挡|dependency|依赖|unlock|解锁|puzzle|顺序依赖|blocked path|解谜|unlock sequence/i.test(
+        text,
+      ),
+    claimsTrayMatch: /tray|托盘|match-3|三消|match3|elimination burst|凑齐.*3/i.test(text),
+    claimsGridPlacement:
+      /tap empty|place arrow|grid.?plac|empty cell|点击空格放置|格子.*放置|convergence.*grid|highlight.*cell/i.test(
+        text,
+      ),
+  };
+}
+
+/** Merge prose profiles — any source claiming a trait counts. */
+function mergeProseProfiles(profiles) {
+  return {
+    claimsAllFree: profiles.some((p) => p.claimsAllFree),
+    claimsBlocked: profiles.some((p) => p.claimsBlocked),
+    claimsTrayMatch: profiles.some((p) => p.claimsTrayMatch),
+    claimsGridPlacement: profiles.some((p) => p.claimsGridPlacement),
+  };
+}
+
+/**
+ * @param {ReturnType<typeof deriveSketchTopology>} sketch
+ * @param {ReturnType<typeof mergeProseProfiles>} prose
+ */
+export function validateTopologyConsistency(sketch, prose) {
+  const problems = [];
+
+  if (sketch.pathPuzzle && sketch.hasBlockedPaths) {
+    if (prose.claimsAllFree && !prose.claimsBlocked) {
+      problems.push(
+        '[consistency] level-sketch is blocked path-puzzle but prose claims all-free / no blocking',
+      );
+    }
+    if (prose.claimsGridPlacement && !prose.claimsBlocked && !prose.claimsTrayMatch) {
+      problems.push(
+        '[consistency] level-sketch is path-puzzle but prose describes grid-placement without path/blocked semantics',
+      );
+    }
+  }
+
+  if (sketch.pathPuzzle && prose.claimsGridPlacement && !prose.claimsBlocked && !prose.claimsTrayMatch) {
+    problems.push(
+      '[consistency] level-sketch is path-puzzle but prose describes grid-placement without path puzzle semantics',
+    );
+  }
+
+  if (sketch.hasTray && !prose.claimsTrayMatch) {
+    problems.push('[consistency] level-sketch includes tray/match-3 but prose omits tray or match-3');
+  }
+
+  if (
+    sketch.pathCount > 1 &&
+    !sketch.hasBlockedPaths &&
+    prose.claimsBlocked &&
+    !prose.claimsAllFree
+  ) {
+    problems.push('[consistency] prose claims blocked/dependency but level-sketch has no blocked paths');
+  }
+
+  return problems;
+}
+
+/** @param {string} root */
+function readHandoffSummary(root) {
+  const raw = readFile(root, 'docs/project-state.json');
+  if (!raw) return '';
+  try {
+    const state = JSON.parse(raw);
+    return String(state.handoffContext?.lastRole?.summary ?? '');
+  } catch {
+    return '';
+  }
+}
+
+export function verifyDesignConsistency(root) {
+  const problems = [];
+  const consistency = [];
+  const design = readFile(root, 'docs/DESIGN.md');
+  const brief = readFile(root, 'docs/design-brief.md');
+  const creativeProcess = readFile(root, 'docs/creative-process.md');
+  const northStarMd = readFile(root, 'docs/north-star.md');
+  if (!design) problems.push('docs/DESIGN.md missing');
+  if (!brief) problems.push('docs/design-brief.md missing');
+  if (problems.length) {
+    return { ok: false, problems, semantic: [], consistency: [], topology: { sketch: null, prose: null, consistent: false } };
+  }
+
+  const { intentTags, rawIntent } = readFusionIntentFromProject(root);
+  const fusionIntent = detectFusionIntent(intentTags, rawIntent);
+
+  const semantic = validateSemantic(design, brief, fusionIntent);
+  problems.push(...semantic.map((p) => `[semantic] ${p}`));
+  problems.push(...validateAnimationSpine(design).map((p) => `[animation-spine] ${p}`));
+
+  const northStar = validateNorthStar(design, brief, creativeProcess, northStarMd);
+  if (!northStar.ok) {
+    problems.push(...northStar.problems.map((p) => `[north-star] ${p}`));
+  }
+
+  const oneLinerForSpine =
+    extractNorthStarOneLinerFromFile(northStarMd) ||
+    extractLabeledLine(extractNorthStarSection(design), 'One-liner');
+  const storySpine = validateStorySpine(northStarMd, design, creativeProcess, oneLinerForSpine);
+  const storySpineMode = getStorySpineMode();
+  if (storySpineMode === 'block') {
+    if (!storySpine.ok) {
+      problems.push(...storySpine.problems.map((p) => `[story-spine] ${p}`));
+      problems.push(...storySpine.warnings.map((p) => `[story-spine] ${p}`));
+    }
+  } else if (storySpineMode === 'warn') {
+    // Rollout: collect metrics only; do not fail verify:design yet
+  } else if (!storySpine.ok) {
+    problems.push(...storySpine.problems.map((p) => `[story-spine] ${p}`));
+  }
+
+  const mechanismFidelity = validateSkillFidelity(root);
+  if (!mechanismFidelity.skipped && !mechanismFidelity.pass) {
+    for (const reason of mechanismFidelity.driftReasons) {
+      problems.push(`[mechanism-fidelity] ${reason}`);
+    }
+  }
+
+  let topology = { sketch: null, prose: null, consistent: true };
+
+  const sketchPath = 'docs/level-sketch.json';
+  if (existsSync(join(root, sketchPath))) {
+    const levelResult = validateLevelSketch(root, sketchPath);
+    if (!levelResult.ok) {
+      problems.push(...levelResult.problems.map((p) => `[level-sketch] ${p}`));
+    }
+
+    let sketchObj;
+    try {
+      sketchObj = JSON.parse(readFileSync(join(root, sketchPath), 'utf8'));
+    } catch (err) {
+      problems.push(`[level-sketch] parse error: ${err instanceof Error ? err.message : String(err)}`);
+      sketchObj = { arrows: [] };
+    }
+
+    const sketchTopo = deriveSketchTopology(sketchObj, levelResult.metrics);
+    const designBundle = extractDesignProseBundle(design);
+    const briefFirstWin = brief.match(/First[- ]?win|First Level|首关|第一关|Level 1[\s\S]{0,400}/i)?.[0] ?? brief;
+    const handoffSummary = readHandoffSummary(root);
+
+    const proseMerged = mergeProseProfiles([
+      deriveProseProfile(designBundle),
+      deriveProseProfile(briefFirstWin),
+      deriveProseProfile(handoffSummary),
+    ]);
+
+    const topoProblems = validateTopologyConsistency(sketchTopo, proseMerged);
+    consistency.push(...topoProblems);
+    problems.push(...topoProblems);
+
+    if (handoffSummary) {
+      const handoffOnly = deriveProseProfile(handoffSummary);
+      if (sketchTopo.hasBlockedPaths && handoffOnly.claimsAllFree && !handoffOnly.claimsBlocked) {
+        const msg = '[consistency] handoffContext.summary contradicts level-sketch (claims all-free but sketch has blocked paths)';
+        if (!problems.includes(msg)) {
+          problems.push(msg);
+          consistency.push(msg);
+        }
+      }
+    }
+
+    const scenario = extractFirstLevelScenario(design);
+    if (scenario && /blocked|阻挡|dependency|依赖|puzzle|遮挡/i.test(scenario)) {
+      if (levelResult.metrics && !levelResult.metrics.hasBlockedPaths) {
+        problems.push(
+          '[consistency] First Level Scenario claims blocked/dependency but level-sketch has no blocked paths',
+        );
+      }
+    }
+
+    topology = {
+      sketch: sketchTopo,
+      prose: proseMerged,
+      consistent: topoProblems.length === 0,
+    };
+  } else if (
+    existsSync(join(root, 'game/levels/ring1Level.ts')) ||
+    existsSync(join(root, 'game/levels/level1.json'))
+  ) {
+    // Dev phase: level file exists without sketch — optional warn only
+  } else {
+    problems.push('[level-sketch] docs/level-sketch.json missing for Ring 1 clarify');
+    topology.consistent = false;
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    fusionIntent,
+    semantic,
+    consistency,
+    topology,
+    northStar: northStar.metrics,
+    northStarWarnings: northStar.warnings,
+    storySpine: storySpine.metrics,
+    storySpineWarnings: storySpine.warnings,
+    storySpineProblems: storySpine.problems,
+    mechanismFidelity,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = verifyDesignConsistency(opts.root);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else if (result.ok) {
+    process.stdout.write('[verify:design] OK — semantic + consistency pass\n');
+  } else {
+    process.stderr.write(`[verify:design] FAIL\n  - ${result.problems.join('\n  - ')}\n`);
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+if (process.argv[1] && basename(process.argv[1]) === 'verify-design-consistency.mjs') {
+  main();
+}