@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/.claude/hooks/validate-workflow-stop.mjs

@@ -0,0 +1,1889 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft workflow STOP validator — shared by Claude Code (SubagentStop) and Cursor (subagentStop).
+ * Ensures Artist / TA / Developer filled required workflow logs and valid project-state handoff before subagent may stop.
+ *
+ * Exit 0 = pass
+ * Exit 2 = block (Claude: decision block; Cursor: block stop)
+ * stdout (Claude): {"decision":"block","reason":"..."} on failure
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { validateArtistGate2b } from './asr-coverage-validate.mjs';
+import { diagnose } from '../../skills/_shared/scripts/workflow-doctor.mjs';
+import {
+  reviewDoDKeysForRing,
+} from '../../skills/_shared/scripts/ring-config.mjs';
+import { normalizeSliceState, readState, stateExists, isSliceResolved } from '../../skills/_shared/scripts/state-store.mjs';
+import { validateBuildArtifactForSlice } from '../../skills/playable-record/scripts/lib/build-artifact.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const require = createRequire(import.meta.url);
+
+const INTAKE_HEADING = '## Upstream Intake';
+const SKILL_PREFLIGHT_HEADING = '## Skill Preflight';
+const PLAN_HEADING = {
+  'technical-artist': '## Production Plan',
+  developer: SKILL_PREFLIGHT_HEADING,
+};
+const PLAN_HEADING_BY_LOOP = {
+  developer: {
+    build: SKILL_PREFLIGHT_HEADING,
+  },
+};
+const PLAN_REQUIRED_SUBS = {
+  developer: {
+    build: [],
+  },
+  'technical-artist': ['### Coverage Plan', '### Atlas Assembly Plan', '### Risk Checklist'],
+};
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+
+/** Required upstream docs scale with growth ring — ring 1 stays minimal (DESIGN only; design-brief is optional scratch). */
+const DEV_REQUIRED_DOCS_BY_RING = {
+  1: ['docs/project-state.md', 'docs/DESIGN.md'],
+  2: [
+    'docs/project-state.md',
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/implementation-plan.md',
+  ],
+  3: [
+    'docs/project-state.md',
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/implementation-plan.md',
+    'docs/style-exploration.md',
+  ],
+  4: [
+    'docs/project-state.md',
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/implementation-plan.md',
+    'docs/style-exploration.md',
+    'logs/artist-log.md',
+  ],
+};
+
+const TA_REQUIRED_DOCS_BY_RING = {
+  4: [
+    'docs/project-state.md',
+    'docs/design-brief.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/style-exploration.md',
+    'logs/artist-log.md',
+  ],
+};
+
+// Artist: Skill Preflight enforced in ring 3+ build and ring 4 Wave 1.
+const ARTIST_REQUIRED_DOCS = [];
+
+const ROLE_LOG = {
+  'technical-artist': { log: 'logs/ta-log.md', label: 'Technical Artist' },
+  developer: { log: 'logs/developer-log.md', label: 'Developer' },
+  artist: { log: 'logs/artist-log.md', label: 'Artist' },
+  reviewer: { log: 'logs/review-report.md', label: 'Reviewer' },
+  'game-designer': { log: null, label: 'Game Designer' },
+  'skill-selector': { log: null, label: 'Temporary Atom Selector' },
+};
+
+const DESIGNER_REQUIRED_DOCS_BY_RING = {
+  // Ring 1 = progressive disclosure: a single concise docs/DESIGN.md is the only
+  // required deliverable. design-brief.md is optional scratch (validated only if present).
+  1: ['docs/DESIGN.md'],
+  2: [
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+  ],
+  3: [
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/style-exploration.md',
+  ],
+  4: [
+    'docs/design-brief.md',
+    'docs/DESIGN.md',
+    'docs/layout-spec.md',
+    'docs/atom-tree.json',
+    'docs/style-exploration.md',
+  ],
+};
+
+const MIN_DOC_LEN = 120;
+
+// `[*_\s]*` tolerates markdown emphasis in the §6 template form `- **Fusion type**:`.
+const FUSION_TYPE_RE =
+  /Fusion\s+type[*_\s]*:\s*(Single|A-Visual|B1-Passive|B2-Active|C-Sequential|D-Parallel)/i;
+const HIGH_RISK_FUSION_TYPES = new Set(['C-Sequential', 'D-Parallel']);
+
+/**
+ * True only when a real pseudo-fusion / risk-accepted decision is documented.
+ *
+ * Judged by the *value* of the "Pseudo-fusion decision:" field — not the field
+ * label, which always contains "pseudo-fusion" in the §6 template (and the
+ * placeholder hint contains "risk accepted: …"). A naive substring match would
+ * make this high-risk gate a no-op for every template-derived DESIGN.md.
+ * @param {string} content
+ * @returns {boolean}
+ */
+function hasFusionDowngradeDecision(content) {
+  // Drop unfilled {…} template placeholders so their hint text cannot satisfy the gate.
+  const filled = content.replace(/\{[^}]*\}/g, '');
+  // `[*_\s]*` tolerates markdown emphasis in `- **Pseudo-fusion decision**:`.
+  const field = filled.match(/Pseudo-?fusion decision[*_\s]*:\s*(.*)/i);
+  if (field) {
+    const value = field[1].trim();
+    const lower = value.toLowerCase();
+    const isEmpty = lower === '' || lower === 'n/a' || lower === 'na' || lower === 'none';
+    if (!isEmpty) return true;
+    // Field present but n/a → no decision documented; fall through to scan the rest.
+  }
+  // No structured field (or n/a): scan with the bare label stripped so it cannot self-satisfy.
+  const scrubbed = filled.replace(/Pseudo-?fusion decision[*_\s]*:/gi, '');
+  return /pseudo-?fusion/i.test(scrubbed) || /risk\s+accepted/i.test(scrubbed);
+}
+
+/**
+ * Ring 1 DESIGN.md must declare fusion classification (Single is valid default).
+ * @param {string} content
+ * @returns {string[]}
+ */
+function validateDesignFusionSection(content) {
+  const errors = [];
+  const match = content.match(FUSION_TYPE_RE);
+  if (!match) {
+    errors.push(
+      'DESIGN.md: missing "Fusion type:" — add ## 6. Gameplay Fusion with Fusion type: Single (or A/B/C/D type for fusion intent)',
+    );
+    return errors;
+  }
+
+  const fusionType = match[1];
+  const normalized =
+    fusionType.startsWith('B1') ? 'B1-Passive' : fusionType.startsWith('B2') ? 'B2-Active' : fusionType;
+  if (HIGH_RISK_FUSION_TYPES.has(normalized) && !hasFusionDowngradeDecision(content)) {
+    errors.push(
+      `DESIGN.md: Fusion type ${normalized} is high risk — document pseudo-fusion downgrade or explicit "risk accepted" reason in ## 6. Gameplay Fusion`,
+    );
+  }
+
+  return errors;
+}
+
+function hasAnyPattern(content, patterns) {
+  return patterns.some((pattern) => pattern.test(content));
+}
+
+function validatePlayableSeedDesign(content) {
+  const errors = [];
+  const checks = [
+    {
+      label: 'player action',
+      patterns: [/Player Action/i, /玩家.*(动作|操作)/, /Player does/i],
+    },
+    {
+      label: 'immediate feedback',
+      patterns: [/Immediate Feedback/i, /即时反馈/, /First feedback/i, /100ms/i],
+    },
+    {
+      label: 'progress signal',
+      patterns: [/Progress Signal/i, /进展信号/, /Progression signal/i, /3-5/],
+    },
+    {
+      label: 'first win',
+      patterns: [/First[- ]Level Win/i, /First Win/i, /首胜|首关.*赢|首关.*胜/],
+    },
+    {
+      label: 'semantic placeholders',
+      patterns: [/Semantic Placeholders/i, /语义占位/],
+    },
+    {
+      label: 'engine hint',
+      patterns: [/Engine Hint/i, /Engine/i, /引擎/],
+    },
+  ];
+  for (const check of checks) {
+    if (!hasAnyPattern(content, check.patterns)) {
+      errors.push(`DESIGN.md playable seed: missing ${check.label}`);
+    }
+  }
+  if (/^##\s+(ENDCARD|CTA|Endcard|Call[- ]to[- ]Action|Hook\s*\+\s*CTA)/im.test(content)) {
+    errors.push(
+      'Ring 1 DESIGN.md must not include ENDCARD/CTA design sections — defer hook/CTA production to Ring 3+ (spine closeout slice only when orchestrator marks it)',
+    );
+  }
+  return errors;
+}
+
+function validateSkillUseHeuristic(slice) {
+  const errors = [];
+  const skillUse = String(slice.skillUse || '').trim();
+  const fromScratch = String(slice.fromScratchReason || '').trim();
+  if (!skillUse) return errors;
+  const claimsDefines = /\bdefines\b|定义了|实现了本 slice|defines the core|本 skill.*核心/i.test(skillUse);
+  if (fromScratch && claimsDefines) {
+    errors.push(
+      `slice "${slice.sliceId}": skillUse must not claim a skill defines the core mechanic when fromScratchReason is set`,
+    );
+  } else if (claimsDefines) {
+    errors.push(
+      `slice "${slice.sliceId}": skillUse must describe borrowed layout/lifecycle/input patterns only — do not claim a skill "defines" the core mechanic without playcraft skills read proof`,
+    );
+  }
+  if (fromScratch && /\b(implement|实现|covers?|覆盖)\b.*\b(core|核心|mechanic|机制)\b/i.test(skillUse)) {
+    errors.push(
+      `slice "${slice.sliceId}": skillUse must not claim skill coverage of the core mechanic when fromScratchReason is present`,
+    );
+  }
+  return errors;
+}
+
+function normalizeContextRole(role) {
+  const value = normalizeRole(role);
+  if (value === 'ref-flow' || value === 'temporary-ref-flow') return 'skill-selector';
+  return value;
+}
+
+function validateHandoffContext(projectDir, role) {
+  const errors = [];
+  const state = readState(projectDir);
+  const handoff = readHandoff(projectDir);
+  const shouldRequire = String(handoff.subagent_stop || '').toLowerCase() === 'true';
+  if (!shouldRequire) return errors;
+
+  const context = state.handoffContext || {};
+  const last = context.lastRole || {};
+  const next = context.nextRole || {};
+  const normalizedRole = normalizeContextRole(role);
+  const contextRole = normalizeContextRole(last.role);
+  if (!contextRole || contextRole === 'none') {
+    errors.push('handoffContext.lastRole.role is required on STOP');
+  } else if (contextRole !== normalizedRole) {
+    errors.push(`handoffContext.lastRole.role must match STOP role (${role}), found ${last.role}`);
+  }
+  if (!last.summary || String(last.summary).length < 20 || /No sub-agent has completed/i.test(last.summary)) {
+    errors.push('handoffContext.lastRole.summary must capture the completed work in one concrete sentence');
+  }
+  if (!Array.isArray(last.artifactRefs) || last.artifactRefs.length === 0) {
+    errors.push('handoffContext.lastRole.artifactRefs must list produced contract/evidence paths');
+  }
+  if (!next.role || String(next.role).toLowerCase() === 'none') {
+    errors.push('handoffContext.nextRole.role is required for orchestrator routing');
+  }
+  if (!Array.isArray(next.mustKnow) || next.mustKnow.length === 0) {
+    errors.push('handoffContext.nextRole.mustKnow must include the next role working-memory facts');
+  }
+  return errors;
+}
+
+function validateSkillsMatchSliceRefs(projectDir, ss) {
+  const errors = [];
+  const atomPath = path.join(projectDir, 'docs/atom-tree.json');
+  if (!fs.existsSync(atomPath)) {
+    errors.push('slice-axis slice seed requires docs/atom-tree.json with meta.skillsMatch snapshot');
+    return errors;
+  }
+  let atom;
+  try {
+    atom = JSON.parse(fs.readFileSync(atomPath, 'utf8'));
+  } catch {
+    errors.push('docs/atom-tree.json must be valid JSON');
+    return errors;
+  }
+  const meta = atom?.meta || {};
+  const items = Array.isArray(meta.skillsMatch?.items) ? meta.skillsMatch.items : [];
+  if (items.length === 0) {
+    errors.push(
+      'atom-tree.meta.skillsMatch.items must be non-empty (run playcraft skills match before slice seed)',
+    );
+  }
+  const selectedAtoms = Array.isArray(meta.selectedAtoms)
+    ? meta.selectedAtoms.map((a) => String(a).trim()).filter(Boolean)
+    : [];
+  const noMatchReason = String(meta.compactSelectionNoMatchReason || '').trim();
+  if (selectedAtoms.length === 0 && !noMatchReason) {
+    errors.push(
+      'atom-tree.meta.selectedAtoms must be non-empty or meta.compactSelectionNoMatchReason must explain why no compact atoms were selected',
+    );
+  }
+  const devSlices = ss.slices.filter((s) => s.role === 'developer');
+  for (const slice of devSlices) {
+    const skillRefs = Array.isArray(slice.skillRefs)
+      ? slice.skillRefs.map((r) => String(r).trim()).filter(Boolean)
+      : [];
+    const skillUse = String(slice.skillUse || '').trim();
+    const fromScratchReason = String(slice.fromScratchReason || '').trim();
+    if (skillRefs.length > 0) {
+      if (!skillUse) {
+        errors.push(`slice "${slice.sliceId}": skillRefs requires non-empty skillUse`);
+      }
+    } else if (!fromScratchReason) {
+      errors.push(
+        `slice "${slice.sliceId}": must include skillRefs + skillUse (skill-informed) or fromScratchReason (no matched skill)`,
+      );
+    }
+    errors.push(...validateSkillUseHeuristic(slice));
+  }
+  const activated = meta.activatedSlices;
+  if (!Array.isArray(activated) || activated.length === 0) {
+    errors.push('atom-tree.meta.activatedSlices must list sliceIds currently driving dispatch');
+  } else {
+    for (const id of activated) {
+      if (!ss.slices.some((s) => s.sliceId === id)) {
+        errors.push(`atom-tree.meta.activatedSlices "${id}" is not listed in sliceState.slices`);
+      }
+    }
+  }
+  return errors;
+}
+
+function validateGameDesignerSliceQueueSeed(projectDir) {
+  const errors = [];
+  const ss = normalizeSliceState(readState(projectDir).sliceState || {});
+  if (!ss.slices.length) return errors;
+
+  const ring = Math.min(Math.max(readIteration(projectDir) || 1, 1), 4);
+  const devSlices = ss.slices.filter((s) => s.role === 'developer');
+  if (devSlices.length === 0) {
+    errors.push('sliceState.slices must include at least one developer slice after Game Designer seed');
+  }
+  if (!ss.activeSliceId || ss.activeSliceId === 'none') {
+    errors.push('sliceState.activeSliceId must point at the first dispatchable slice after Game Designer seed');
+  } else {
+    const active = ss.slices.find((s) => s.sliceId === ss.activeSliceId);
+    if (!active) {
+      errors.push(`sliceState.activeSliceId "${ss.activeSliceId}" does not match any slice`);
+    } else if (active.role !== 'developer' && ring === 1) {
+      errors.push(`Ring 1 first active slice should be developer-owned (got "${active.role}")`);
+    }
+  }
+  for (const slice of devSlices) {
+    if (!String(slice.doWhat || '').trim()) {
+      errors.push(`slice "${slice.sliceId}": missing doWhat`);
+    }
+    if (!String(slice.verifier || '').trim()) {
+      errors.push(`slice "${slice.sliceId}": missing verifier`);
+    }
+    if (!Array.isArray(slice.acceptance) || slice.acceptance.length === 0) {
+      errors.push(`slice "${slice.sliceId}": missing acceptance criteria`);
+    }
+  }
+
+  errors.push(...validateSkillsMatchSliceRefs(projectDir, ss));
+
+  if (ring === 1) {
+    for (const rel of ['docs/layout-spec.md', 'docs/style-exploration.md']) {
+      if (fs.existsSync(path.join(projectDir, rel))) {
+        errors.push(`Ring 1 Game Designer must not create ${rel} yet`);
+      }
+    }
+    const briefPath = path.join(projectDir, 'docs/design-brief.md');
+    if (!fs.existsSync(briefPath)) {
+      errors.push('slice-axis Ring 1 requires docs/design-brief.md (progressive discovery log)');
+    }
+  }
+  if (ring === 2) {
+    if (devSlices.length < 2) {
+      errors.push('Ring 2 slice deepening requires at least 2 developer periphery slices');
+    }
+    if (devSlices.length > 4) {
+      errors.push('Ring 2 slice deepening allows at most 4 developer slices');
+    }
+    const briefPath = path.join(projectDir, 'docs/design-brief.md');
+    if (!fs.existsSync(briefPath)) {
+      errors.push('slice-axis Ring 2 requires docs/design-brief.md (periphery discovery log)');
+    }
+    if (fs.existsSync(path.join(projectDir, 'docs/style-exploration.md'))) {
+      errors.push('Ring 2 Game Designer clarify must not create docs/style-exploration.md yet (no Artist production)');
+    }
+  }
+  return errors;
+}
+
+function validateGameDesignerSeedContext(projectDir) {
+  const errors = [];
+  const state = readState(projectDir);
+  const ss = normalizeSliceState(state.sliceState || {});
+  if (ss.slices.length > 0) {
+    return validateGameDesignerSliceQueueSeed(projectDir);
+  }
+
+  const context = state.handoffContext || {};
+  const shared = context.sharedDecisions || {};
+  const next = context.nextRole || {};
+  if (!shared.coreAction || shared.coreAction === 'unset') {
+    errors.push('handoffContext.sharedDecisions.coreAction must describe the Ring 1 player action');
+  }
+  if (!Array.isArray(shared.semanticPlaceholders) || shared.semanticPlaceholders.length === 0) {
+    errors.push('handoffContext.sharedDecisions.semanticPlaceholders must list Ring 1 semantic placeholders');
+  }
+  const nextRole = normalizeContextRole(next.role);
+  if (nextRole !== 'skill-selector') {
+    errors.push('handoffContext.nextRole.role should route to temporary ref-flow atom-selection subagent');
+  }
+  return errors;
+}
+
+function requiredDocsForRole(role, iteration) {
+  const ring = Math.min(Math.max(iteration || 1, 1), 4);
+  if (role === 'developer') {
+    return DEV_REQUIRED_DOCS_BY_RING[ring] || DEV_REQUIRED_DOCS_BY_RING[1];
+  }
+  if (role === 'technical-artist') {
+    return TA_REQUIRED_DOCS_BY_RING[ring] || [];
+  }
+  return ARTIST_REQUIRED_DOCS;
+}
+
+/** @param {string} raw */
+function parseHookInput(raw) {
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} s */
+function normalizeRole(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-');
+}
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {'technical-artist' | 'developer' | 'artist' | 'reviewer' | 'game-designer' | 'skill-selector' | null}
+ */
+function detectRole(input) {
+  const candidates = [
+    input.agent_type,
+    input.agent_name,
+    input.subagent_name,
+    input.subagent_type,
+    input.subagent,
+    input.role,
+  ].filter(Boolean);
+
+  for (const c of candidates) {
+    const n = normalizeRole(String(c));
+    if (n.includes('technical-artist') || n === 'ta') return 'technical-artist';
+    if (n === 'developer-lead' || n === 'developer' || n === 'dev') return 'developer';
+    if (n === 'artist') return 'artist';
+    if (n === 'reviewer' || n === 'review') return 'reviewer';
+    if (n === 'game-designer' || n === 'game designer' || n === 'designer') return 'game-designer';
+    if (n === 'skill-selector' || n === 'skill selector' || n === 'ref-flow') return 'skill-selector';
+  }
+
+  const blobs = [
+    input.last_assistant_message,
+    input.last_message,
+    input.message,
+    input.output,
+  ]
+    .filter((v) => typeof v === 'string')
+    .join('\n');
+
+  const stopMatch = blobs.match(/---\s*PLAYCRAFT_STOP\s*---[\s\S]*?role:\s*([^\s\n]+)/i);
+  if (stopMatch) {
+    const r = normalizeRole(stopMatch[1]);
+    if (r in ROLE_LOG) return /** @type {keyof ROLE_LOG} */ (r);
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {Record<string, string>}
+ */
+function readHandoff(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) return {};
+  const content = fs.readFileSync(statePath, 'utf8');
+  const fence = content.match(/```yaml\n([\s\S]*?)```/);
+  if (!fence) return {};
+  /** @type {Record<string, string>} */
+  const handoff = {};
+  for (const line of fence[1].split('\n')) {
+    const m = line.match(/^(\w+):\s*(.+)$/);
+    if (m) handoff[m[1]] = m[2].trim();
+  }
+  return handoff;
+}
+
+/**
+ * @param {string} content
+ */
+function parseRingGateCanAskUser(content) {
+  const m = content.match(/\|\s*ringGateCanAskUser\s*\|\s*(\S+)/i);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string} relPath
+ */
+function validateDocFile(projectDir, relPath) {
+  const errors = [];
+  const abs = path.join(projectDir, relPath);
+  if (!fs.existsSync(abs)) {
+    errors.push(`Missing required doc: ${relPath}`);
+    return errors;
+  }
+  const content = fs.readFileSync(abs, 'utf8');
+  if (content.length < MIN_DOC_LEN) {
+    errors.push(`${relPath}: too short — fill with real contract content (≥${MIN_DOC_LEN} chars)`);
+  }
+  const placeholders = content.match(/\{\{[^}]+\}\}/g) || [];
+  if (placeholders.length >= 3 || (PLACEHOLDER_RE.test(content) && placeholders.length > 0)) {
+    errors.push(`${relPath}: still contains {{placeholders}} — replace with real data`);
+  }
+  return errors;
+}
+
+/**
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+function parseReviewReportDoD(content) {
+  const start = content.indexOf('## Ring DoD Fields');
+  if (start === -1) return {};
+  const after = content.slice(start);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Field/i.test(trimmed)) continue;
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 2) continue;
+    const key = parts[0];
+    if (/^(field|owner|verifier)$/i.test(key)) continue;
+    const value = parts.length >= 3 ? parts[parts.length - 1] : parts[1];
+    fields[key] = value;
+  }
+  return fields;
+}
+
+/**
+ * @param {string} projectDir
+ */
+function validateReviewerHandoff(projectDir) {
+  const errors = [];
+  const handoff = readHandoff(projectDir);
+  const waitingFor = (handoff.waiting_for || '').toLowerCase();
+  const nextAction = handoff.next_orchestrator_action || '';
+
+  if (waitingFor === 'user_gate') {
+    errors.push(
+      'Reviewer must not set waiting_for=user_gate — use waiting_for=orchestrator and next_orchestrator_action with npm run ring:gate',
+    );
+  }
+  if (/AskUserQuestion/i.test(nextAction) && !/ring:gate/i.test(nextAction)) {
+    errors.push(
+      'Reviewer next_orchestrator_action must not route AskUserQuestion — orchestrator runs ring:gate first',
+    );
+  }
+  if (/ring:gate/i.test(nextAction) && waitingFor !== 'orchestrator') {
+    errors.push('When routing ring:gate, waiting_for must be orchestrator');
+  }
+  if (handoff.subagent_stop !== 'true') {
+    errors.push('Reviewer STOP requires subagent_stop: true');
+  }
+  if (!nextAction || nextAction === 'null') {
+    errors.push('Reviewer STOP requires next_orchestrator_action');
+  }
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ * @param {number} iteration
+ */
+function validateReviewReportDoD(projectDir, iteration) {
+  const errors = [];
+  const reportPath = path.join(projectDir, 'logs/review-report.md');
+  if (!fs.existsSync(reportPath)) {
+    return ['Reviewer: create logs/review-report.md from templates/review-report.template.md before STOP'];
+  }
+  const content = fs.readFileSync(reportPath, 'utf8');
+  if (!content.includes('## Ring DoD Fields')) {
+    errors.push('review-report.md: missing "## Ring DoD Fields" section');
+    return errors;
+  }
+  const fields = parseReviewReportDoD(content);
+  const required = reviewDoDKeysForRing(iteration);
+  if (required.length === 0) {
+    return errors;
+  }
+  for (const key of required) {
+    const val = (fields[key] || '').toLowerCase();
+    if (!val || val.includes('{{') || val === 'pending' || val === 'n-a' || val === 'n/a') {
+      errors.push(
+        `review-report.md Reviewer evidence: ${key} must be pass or fail before STOP (script fields stay pending for ring:gate)`,
+      );
+    }
+  }
+  if (!content.includes('## Verdict')) {
+    errors.push('review-report.md: missing "## Verdict" section');
+  }
+  return errors;
+}
+
+const UI_DIFF_RUBRIC_IDS = [
+  'bg_clean',
+  'no_double_board',
+  'no_hud_ghost',
+  'no_fake_ui',
+  'tile_silhouette',
+  'text_no_overlap',
+  'mc_layout',
+];
+
+const EVIDENCE_SCREENSHOT_RE = /\.(png|jpe?g|webp)\b/i;
+
+/**
+ * Parse the Structured Visual Rubric table into `id → { result, evidence }`.
+ * @param {string} section
+ * @returns {Map<string, { result: string, evidence: string }>}
+ */
+function parseRubricRows(section) {
+  const rows = new Map();
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|[\s|:-]+\|?$/.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;
+    const id = parts[0].replace(/`/g, '').trim().toLowerCase();
+    if (!id || id === 'check id' || id === 'check') continue;
+    rows.set(id, { result: parts[1], evidence: parts.slice(2).join(' | ').trim() });
+  }
+  return rows;
+}
+
+/**
+ * Ring 4 ui_diff must include a structured visual rubric where each check row is
+ * actually filled — an explicit PASS/FAIL verdict and evidence that cites a
+ * screenshot path. Earlier this only checked that each row *id* appeared anywhere
+ * in the file, so a report full of `{{PASS/FAIL}}` / `{{...}}` placeholders passed
+ * (the test11 "forced look-at-the-screenshot" gate degraded into a format check).
+ * @param {string} content
+ */
+function validateUiDiffVisualRubric(content) {
+  const errors = [];
+  if (!/ui_diff|Structured Visual Rubric/i.test(content)) {
+    return errors;
+  }
+  if (!/###\s+Structured Visual Rubric/i.test(content)) {
+    errors.push(
+      'review-report.md ui_diff: missing "### Structured Visual Rubric" — Read each screenshot and fill PASS/FAIL + evidence',
+    );
+    return errors;
+  }
+
+  const section = extractMarkdownSection(content, '### Structured Visual Rubric') || '';
+  const rows = parseRubricRows(section);
+
+  for (const id of UI_DIFF_RUBRIC_IDS) {
+    const row = rows.get(id);
+    if (!row) {
+      errors.push(`review-report.md Structured Visual Rubric: missing check row "${id}"`);
+      continue;
+    }
+    const result = row.result || '';
+    if (PLACEHOLDER_RE.test(result) || !/\b(PASS|FAIL)\b/i.test(result)) {
+      errors.push(
+        `review-report.md Structured Visual Rubric: "${id}" Result must be an explicit PASS or FAIL (found "${result || 'empty'}")`,
+      );
+    }
+    const evidence = row.evidence || '';
+    if (!evidence || PLACEHOLDER_RE.test(evidence)) {
+      errors.push(
+        `review-report.md Structured Visual Rubric: "${id}" Evidence is empty or a {{placeholder}} — describe what you saw in the screenshot`,
+      );
+    } else if (!EVIDENCE_SCREENSHOT_RE.test(evidence) && !/logs\//i.test(evidence)) {
+      errors.push(
+        `review-report.md Structured Visual Rubric: "${id}" Evidence must cite a screenshot path (e.g. logs/ui-diff-game.png — what you see)`,
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * uiReviewStatus in project-state must align with uiDiff in review-report (B4 atomic writeback guard).
+ * @param {string} projectDir
+ * @param {string} reportContent
+ */
+function validateUiReviewStatusConsistency(projectDir, reportContent) {
+  const errors = [];
+  const fields = parseReviewReportDoD(reportContent);
+  const uiDiff = (fields.uiDiff || '').toLowerCase();
+  if (!uiDiff || uiDiff.includes('{{') || uiDiff === 'pending' || uiDiff === 'n-a') {
+    return errors;
+  }
+  const uiReviewStatusRaw = readState(projectDir).devPreview?.uiReviewStatus;
+  if (!uiReviewStatusRaw) return errors;
+  const uiReviewStatus = String(uiReviewStatusRaw).toLowerCase();
+  const passSet = new Set(['pass', 'passed']);
+  const failSet = new Set(['fail', 'failed']);
+  const uiDiffPass = passSet.has(uiDiff);
+  const uiDiffFail = failSet.has(uiDiff);
+  const statusPass = passSet.has(uiReviewStatus);
+  const statusFail = failSet.has(uiReviewStatus);
+  if (uiDiffPass && statusFail) {
+    errors.push(
+      'project-state uiReviewStatus=failed but review-report uiDiff=pass — align checkpoint with visual rubric verdict',
+    );
+  }
+  if (uiDiffFail && statusPass) {
+    errors.push(
+      'project-state uiReviewStatus=passed but review-report uiDiff=fail — align checkpoint with visual rubric verdict',
+    );
+  }
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ */
+function validateReviewerStop(projectDir) {
+  const iteration = readIteration(projectDir) || 1;
+  const loop = readLoop(projectDir);
+  const handoff = readHandoff(projectDir);
+  const nextAction = handoff.next_orchestrator_action || '';
+  const errors = [...validateReviewerHandoff(projectDir), ...validateHandoffContext(projectDir, 'reviewer')];
+
+  if (loop === 'verify' && /ring:gate/i.test(nextAction)) {
+    errors.push(...validateReviewReportDoD(projectDir, iteration));
+    const reportPath = path.join(projectDir, 'logs/review-report.md');
+    if (fs.existsSync(reportPath)) {
+      const reportContent = fs.readFileSync(reportPath, 'utf8');
+      if (iteration >= 4) {
+        errors.push(...validateUiDiffVisualRubric(reportContent));
+        errors.push(...validateUiReviewStatusConsistency(projectDir, reportContent));
+      }
+    }
+    const loadCheck = readState(projectDir).devPreview?.loadCheck;
+    if (loadCheck && String(loadCheck).toLowerCase() === 'pending' && iteration < 4) {
+      errors.push('Dev Preview loadCheck still pending — complete load_check before routing ring:gate');
+    }
+  } else if (!fs.existsSync(path.join(projectDir, 'logs/review-report.md'))) {
+    errors.push('Reviewer: create logs/review-report.md before STOP');
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ */
+function validateGameDesignerStop(projectDir) {
+  const iteration = readIteration(projectDir) || 1;
+  const loop = readLoop(projectDir);
+  const errors = [];
+  const handoff = readHandoff(projectDir);
+
+  if (handoff.subagent_stop !== 'true') {
+    errors.push('Game Designer STOP requires subagent_stop: true');
+  }
+  if ((handoff.waiting_for || '').toLowerCase() !== 'orchestrator') {
+    errors.push('Game Designer STOP requires waiting_for: orchestrator');
+  }
+  if (!handoff.next_orchestrator_action || handoff.next_orchestrator_action === 'null') {
+    errors.push('Game Designer STOP requires next_orchestrator_action (e.g. Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection)');
+  }
+
+  if (loop !== 'clarify') {
+    return errors;
+  }
+
+  const ring = Math.min(Math.max(iteration, 1), 4);
+  const state = readState(projectDir);
+  const ss = normalizeSliceState(state.sliceState || {});
+  const sliceAxisClarify = ss.slices.length > 0 && (ring === 1 || ring === 2);
+
+  const requiredDocs = sliceAxisClarify
+    ? ['docs/DESIGN.md', 'docs/design-brief.md']
+    : DESIGNER_REQUIRED_DOCS_BY_RING[ring] || DESIGNER_REQUIRED_DOCS_BY_RING[1];
+  for (const doc of requiredDocs) {
+    errors.push(...validateDocFile(projectDir, doc));
+  }
+
+  if (ring === 1) {
+    const designPath = path.join(projectDir, 'docs/DESIGN.md');
+    if (fs.existsSync(designPath)) {
+      errors.push(...validatePlayableSeedDesign(fs.readFileSync(designPath, 'utf8')));
+    }
+  }
+
+  if (sliceAxisClarify) {
+    errors.push(...validateHandoffContext(projectDir, 'game-designer'));
+    errors.push(...validateGameDesignerSeedContext(projectDir));
+    const refs = state.handoffContext?.lastRole?.artifactRefs || [];
+    if (!refs.some((r) => String(r).includes('atom-tree.json'))) {
+      errors.push('handoffContext.lastRole.artifactRefs must include docs/atom-tree.json');
+    }
+  } else if (ring === 1) {
+    errors.push(...validateHandoffContext(projectDir, 'game-designer'));
+    errors.push(...validateGameDesignerSeedContext(projectDir));
+  }
+
+  const briefPath = path.join(projectDir, 'docs/design-brief.md');
+  if (fs.existsSync(briefPath)) {
+    const brief = fs.readFileSync(briefPath, 'utf8');
+    if (!/##\s+(Brainstorm|Core Gameplay|Discovery|Core Discovery)/i.test(brief)) {
+      errors.push('design-brief.md: missing Discovery / Brainstorm / Core Gameplay section with process record');
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ */
+function validateSkillSelectorStop(projectDir) {
+  const errors = [];
+  const handoff = readHandoff(projectDir);
+  errors.push(...validateHandoffContext(projectDir, 'skill-selector'));
+
+  if (handoff.subagent_stop !== 'true') {
+    errors.push('Temporary atom-selection STOP requires subagent_stop: true');
+  }
+  if ((handoff.waiting_for || '').toLowerCase() !== 'orchestrator') {
+    errors.push('Temporary atom-selection STOP requires waiting_for: orchestrator');
+  }
+  const next = handoff.next_orchestrator_action || '';
+  if (!next || next === 'null') {
+    errors.push('Temporary atom-selection STOP requires next_orchestrator_action');
+  } else if (!/init-template|scaffold|developer/i.test(next)) {
+    errors.push('Temporary atom-selection STOP should route orchestrator to scaffold gate, then @developer');
+  }
+
+  const atomTreePath = path.join(projectDir, 'docs/atom-tree.json');
+  if (!fs.existsSync(atomTreePath)) {
+    errors.push('Temporary atom-selection STOP requires docs/atom-tree.json');
+    return errors;
+  }
+
+  let tree;
+  try {
+    tree = JSON.parse(fs.readFileSync(atomTreePath, 'utf8'));
+  } catch (e) {
+    errors.push(`docs/atom-tree.json parse failed: ${e.message}`);
+    return errors;
+  }
+
+  const engineDecision = tree?.meta?.engineDecision;
+  if (!engineDecision || typeof engineDecision !== 'object') {
+    errors.push('docs/atom-tree.json missing meta.engineDecision');
+  } else {
+    if (!engineDecision.adapter || engineDecision.adapter === 'unset') {
+      errors.push('meta.engineDecision.adapter must be set for init-template');
+    }
+    if (!engineDecision.engineAtom) {
+      errors.push('meta.engineDecision.engineAtom must be set');
+    }
+  }
+
+  const selectedAtoms = tree?.meta?.selectedAtoms;
+  if (!Array.isArray(selectedAtoms) || selectedAtoms.length === 0) {
+    errors.push('meta.selectedAtoms must be a non-empty compact atom list');
+  }
+  if (!tree?.engine) {
+    errors.push('docs/atom-tree.json missing top-level engine atom');
+  }
+
+  return errors;
+}
+
+/** @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
+ * @returns {{ rows: { doc: string, read: string, takeaway: string }[], errors: string[] }}
+ */
+function parseUpstreamIntake(content) {
+  const errors = [];
+  const start = content.indexOf(INTAKE_HEADING);
+  if (start === -1) {
+    return { rows: [], errors: [`Missing "${INTAKE_HEADING}" section`] };
+  }
+
+  const after = content.slice(start + INTAKE_HEADING.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  const rows = [];
+  const unmatchedRows = [];
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Doc(ument)?\s*\|/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;
+
+    const doc = parts[0].replace(/^`/, '').replace(/`$/, '').trim();
+    if (!doc.startsWith('docs/') && !doc.startsWith('logs/')) {
+      unmatchedRows.push(doc || '(empty)');
+      continue;
+    }
+
+    rows.push({ doc, read: parts[1], takeaway: parts[2] });
+  }
+
+  if (rows.length === 0) {
+    if (unmatchedRows.length > 0) {
+      errors.push(
+        `Upstream Intake table has ${unmatchedRows.length} row(s) but none start with "docs/" or "logs/" in the first column. Found: ${unmatchedRows.slice(0, 5).join(', ')}${unmatchedRows.length > 5 ? ` ... and ${unmatchedRows.length - 5} more` : ''}. Expected format: | \`docs/project-state.md\` | ✓ | one-line takeaway |`
+      );
+    } else {
+      errors.push(
+        'Upstream Intake table has no data rows. Expected format:\n| `docs/project-state.md` | ✓ | one-line takeaway |\n| `docs/implementation-plan.md` | ✓ | ... |\n(Repeat for each required doc — see templates/developer-log.template.md for the full list.)'
+      );
+    }
+  }
+
+  return { rows, errors };
+}
+
+/**
+ * @param {string} content
+ * @param {string[]} requiredDocs
+ */
+function validateIntakeContent(content, requiredDocs) {
+  const { rows, errors } = parseUpstreamIntake(content);
+  const byDoc = new Map(rows.map((r) => [r.doc, r]));
+
+  for (const doc of requiredDocs) {
+    const row = byDoc.get(doc);
+    if (!row) {
+      errors.push(`Missing row for ${doc}`);
+      continue;
+    }
+    if (!isReadChecked(row.read)) {
+      errors.push(`${doc}: mark Read column (✓) after reading`);
+    }
+    const takeaway = row.takeaway.trim();
+    if (!takeaway || PLACEHOLDER_RE.test(takeaway) || takeaway.length < MIN_TAKEAWAY_LEN) {
+      errors.push(`${doc}: add a concrete one-line takeaway (≥${MIN_TAKEAWAY_LEN} chars, no {{placeholders}})`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} content
+ * @param {'technical-artist' | 'developer'} role
+ * @param {'clarify'|'build'|'verify'|null} [loop]
+ */
+function validatePlan(content, role, loop) {
+  let heading = PLAN_HEADING[role];
+  /** @type {string[]} */
+  let requiredSubs = [];
+
+  if (role === 'developer') {
+    if (loop && PLAN_HEADING_BY_LOOP.developer[loop]) {
+      heading = PLAN_HEADING_BY_LOOP.developer[loop];
+      requiredSubs = PLAN_REQUIRED_SUBS.developer[loop] ?? [];
+    }
+  } else if (role === 'technical-artist') {
+    requiredSubs = PLAN_REQUIRED_SUBS['technical-artist'] ?? [];
+  }
+
+  const errors = [];
+  const start = content.indexOf(heading);
+  if (start === -1) {
+    return [`Missing "${heading}" section — write plan before STOP (loop: ${loop || 'unknown'})`];
+  }
+
+  const after = content.slice(start + heading.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  for (const sub of requiredSubs) {
+    if (!section.includes(sub)) {
+      errors.push(`${heading}: missing ${sub}`);
+    }
+  }
+
+  const checkboxes = section.match(/- \[[ xX]\]/gi) || [];
+  const unchecked = checkboxes.filter((c) => /\[ \]/i.test(c));
+  if (checkboxes.length > 0 && unchecked.length > 0) {
+    errors.push(`${heading} Risk Checklist: ${unchecked.length} unchecked item(s)`);
+  }
+
+  if (PLACEHOLDER_RE.test(section)) {
+    errors.push(`${heading}: contains {{placeholders}} — fill with real data`);
+  }
+
+  return errors;
+}
+
+const LOOP_NAMES = '(clarify|build|verify)';
+const LOOP_YAML_RE = new RegExp(`^\\s*loop:\\s*${LOOP_NAMES}\\s*$`, 'im');
+const ITERATION_YAML_RE = /^\s*iteration:\s*(\d+)\s*$/im;
+
+/**
+ * @param {string} projectDir
+ * @returns {number|null}
+ */
+function readIteration(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(ITERATION_YAML_RE);
+  if (!m) return null;
+  const n = Number.parseInt(m[1], 10);
+  return Number.isFinite(n) && n >= 1 && n <= 4 ? n : null;
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {'clarify'|'build'|'verify'|null}
+ */
+function readLoop(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(LOOP_YAML_RE);
+  return m ? /** @type {'clarify'|'build'|'verify'} */ (m[1].toLowerCase()) : null;
+}
+
+/** @deprecated use readLoop — maps build→development for legacy test imports only */
+function readStage(projectDir) {
+  const loop = readLoop(projectDir);
+  if (loop === 'build') return 'development';
+  if (loop === 'verify') return 'ui_review';
+  return 'pm';
+}
+
+function readGatePending(projectDir) {
+  return null;
+}
+
+/**
+ * Validate Artist Skill Preflight section (Phase 2 / production only).
+ * @param {string} content
+ */
+function validateArtistSkillPreflight(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;
+}
+
+/**
+ * Static runtime-contract gate for Developer: the recording/debug harness needs
+ * game/ to keep exposing its hooks. Feature-detected — silently skipped if the
+ * harness scanner is absent, and never hard-fails the hook itself on scanner error.
+ * @param {string} projectDir
+ * @returns {string[]}
+ */
+function validateDeveloperRuntimeContract(projectDir) {
+  const pending = path.join(projectDir, 'game', '.playcraft-scaffold-pending');
+  if (fs.existsSync(pending)) return [];
+
+  const libPath = path.join(
+    projectDir,
+    'skills/playable-verify-ui/scripts/lib/runtime_contract.js',
+  );
+  if (!fs.existsSync(libPath)) return [];
+  try {
+    const { scanRuntimeContract } = require(libPath);
+    const res = scanRuntimeContract(projectDir);
+    if (!res.ok) {
+      return res.missing.map((m) => `runtime contract broken — ${m}`);
+    }
+  } catch {
+    // Scanner failure must not block an otherwise-valid STOP.
+    return [];
+  }
+  return [];
+}
+
+/**
+ * @param {string} projectDir
+ * @param {'technical-artist' | 'developer' | 'artist'} role
+ */
+function validateNonRegression(projectDir, iteration) {
+  const errors = [];
+  if (!iteration || iteration <= 1) return errors;
+  const archived = readState(projectDir).archivedRings || {};
+  if (Object.keys(archived).length === 0) {
+    errors.push(`Non-regression: archivedRings empty while iteration=${iteration}`);
+    return errors;
+  }
+  for (let ring = 1; ring < iteration; ring += 1) {
+    if (!(ring in archived) && !(String(ring) in archived)) {
+      errors.push(`Non-regression: ring ${ring} not archived`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * slice-axis-v1: roles that EXECUTE (implement/verify) a dispatched slice. If one of
+ * these is stopped on a slice it does not own, that is a dispatch mismatch (the
+ * orchestrator spawned the wrong executor) and STOP is blocked. Non-executor roles
+ * (game-designer seeds the queue, reviewer/skill-selector) may legitimately STOP at a
+ * handoff point while another role's slice is pending, so they are not mismatch-gated.
+ * Knife 4 only wires developer; TA/artist slice execution can be added later.
+ */
+const SLICE_EXECUTOR_ROLES = new Set(['developer']);
+
+/** The active slice object, or null when none / drained. */
+function getActiveSliceFor(projectDir) {
+  if (!stateExists(projectDir)) return null;
+  try {
+    const ss = readState(projectDir).sliceState || {};
+    if (!ss.activeSliceId || ss.activeSliceId === 'none') return null;
+    return (ss.slices || []).find((s) => s.sliceId === ss.activeSliceId) || null;
+  } catch {
+    return null;
+  }
+}
+
+function hasUnresolvedActiveSlice(projectDir) {
+  const active = getActiveSliceFor(projectDir);
+  return !!active && !isSliceResolved(active);
+}
+
+/**
+ * slice-axis-v1: derive the dispatched role from the active slice when there is no
+ * explicit role marker on the hook input (top-level `claude -p` has no
+ * `subagent_type` / PLAYCRAFT_STOP). The dispatched role IS the owner of the
+ * active, UNRESOLVED slice — this guarantees an unverified (or failed-but-unrouted)
+ * slice cannot slip past STOP even without subagent context. Returns null when the
+ * active slice is resolved / absent, so those states fall back to normal detection.
+ */
+function roleFromActiveSlice(projectDir) {
+  const active = getActiveSliceFor(projectDir);
+  if (!active || isSliceResolved(active)) return null;
+  return normalizeRole(active.role || 'developer') || 'developer';
+}
+
+function validateActiveSliceResolved(projectDir, role) {
+  const active = getActiveSliceFor(projectDir);
+  if (!active) return [];
+  if (active.role && active.role !== role) return [];
+  if (isSliceResolved(active)) return [];
+  if (active.status === 'failed') {
+    return [
+      `slice "${active.sliceId}" is "failed" but has no route target — run \`npm run slice:set -- status=failed route=<role> reason="<failKey>"\` so the orchestrator has a precise recovery target. A failed slice without routeTo.role + routeTo.reason is unresolved.`,
+    ];
+  }
+  const buildHint =
+    active.role === 'developer' || !active.role
+      ? '`npm run build` (writes validate/build.json)'
+      : `\`npm run ${active.verifier || 'verify:build'}\``;
+  return [
+    `slice "${active.sliceId}" is "${active.status}" — before STOP run ${buildHint}, then \`npm run slice:set -- status=verified verification="build.json ok"\` on pass, or \`npm run slice:set -- status=failed route=<role> reason="..."\` to route. The active slice must be verified/failed/routed, not left ${active.status}.`,
+  ];
+}
+
+/**
+ * slice-axis-v1: after a slice is resolved the queue may drain (activeSliceId=none).
+ * The stopping role must not fall back to legacy ring STOP (e.g. review-report.md) when
+ * it just wrote a structured verdict via slice:set — lastResolvedForStop bridges drain → STOP.
+ */
+function validateResolvedSliceStop(projectDir, role) {
+  if (!stateExists(projectDir)) return null;
+  try {
+    const ss = readState(projectDir).sliceState || {};
+    const marker = ss.lastResolvedForStop;
+    if (!marker || marker.role !== role || !marker.sliceId) return null;
+    const slice = (ss.slices || []).find((s) => s.sliceId === marker.sliceId);
+    if (slice && isSliceResolved(slice)) {
+      if (role === 'developer' && slice.status === 'verified') {
+        const buildErrors = validateBuildArtifactForSlice(projectDir, slice);
+        if (buildErrors.length) return buildErrors;
+      }
+      return [];
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function validateRole(projectDir, role) {
+  // slice-axis-v1: when the stopping role OWNS an unresolved active slice, the slice
+  // state machine is the ONLY STOP gate — checked FIRST, ahead of every role-specific
+  // branch (reviewer/game-designer/skill-selector included), so a slice owned by ANY
+  // role (e.g. a future game-designer-owned slice) goes through the slice gate, not
+  // the legacy role STOP. Ring-era intake ceremony (developer-log Read✓/takeaway,
+  // plan, runtime-contract dup, ring-1 self-gate) is bypassed — verify:slice already
+  // judges the runtime contract semantically. With no unresolved active slice we fall
+  // through to the legacy ring flow, so existing ring:loop projects and tests are
+  // unaffected.
+  const sliceOwner = roleFromActiveSlice(projectDir);
+  if (sliceOwner) {
+    if (sliceOwner === role) {
+      return validateActiveSliceResolved(projectDir, role);
+    }
+    // dispatch mismatch (hardening): an EXECUTOR role was stopped on a slice it does
+    // not own → the orchestrator spawned the wrong executor. Block with a precise
+    // re-dispatch hint. Non-executor roles fall through (legitimate handoff STOP).
+    if (SLICE_EXECUTOR_ROLES.has(role)) {
+      const active = getActiveSliceFor(projectDir);
+      return [
+        `dispatch mismatch — active slice "${active?.sliceId}" is owned by "${sliceOwner}", but the stopping role is "${role}". Only @${sliceOwner} may resolve this slice; re-dispatch to @${sliceOwner} (or fix sliceState.slices[].role).`,
+      ];
+    }
+  }
+
+  const resolvedSliceStop = validateResolvedSliceStop(projectDir, role);
+  if (resolvedSliceStop !== null) return resolvedSliceStop;
+
+  if (role === 'reviewer') {
+    return validateReviewerStop(projectDir);
+  }
+  if (role === 'game-designer') {
+    return validateGameDesignerStop(projectDir);
+  }
+  if (role === 'skill-selector') {
+    return validateSkillSelectorStop(projectDir);
+  }
+
+  const cfg = ROLE_LOG[role];
+  const iteration = readIteration(projectDir) || 1;
+  const loop = readLoop(projectDir);
+  const logPath = path.join(projectDir, cfg.log);
+  const requiredDocs = requiredDocsForRole(role, iteration);
+
+  if (!fs.existsSync(logPath)) {
+    return [
+      `${cfg.label}: create ${cfg.log} from templates/${path.basename(cfg.log).replace('.md', '.template.md')} before STOP.`,
+    ];
+  }
+
+  const content = fs.readFileSync(logPath, 'utf8');
+  const regressionErrors = validateNonRegression(projectDir, iteration);
+  const contextErrors = validateHandoffContext(projectDir, role);
+
+  if (role === 'artist') {
+    if (iteration >= 3 && loop === 'build') {
+      return [...validateArtistSkillPreflight(content), ...regressionErrors, ...contextErrors];
+    }
+    if (iteration >= 3 && loop === 'verify') {
+      return [...validateArtistGate2b(projectDir), ...regressionErrors, ...contextErrors];
+    }
+    return [...regressionErrors, ...contextErrors];
+  }
+
+  const intakeErrors =
+    requiredDocs.length > 0 ? validateIntakeContent(content, requiredDocs) : [];
+  const planErrors = validatePlan(content, role, loop);
+  const contractErrors =
+    role === 'developer' && loop === 'build'
+      ? validateDeveloperRuntimeContract(projectDir)
+      : [];
+
+  if (role === 'developer' && loop === 'build') {
+    const checkpointErrors =
+      iteration >= 2 ? validateDeveloperCheckpoints(projectDir, content) : [];
+    const sliceErrors = validateActiveSliceResolved(projectDir, role);
+    let ring1SelfGateErrors = [];
+    // When a slice is active, slice verification supersedes the legacy ring-1
+    // whole-project self-gate (which is what the experiment showed lets semantic
+    // failures escape). Fall back to the ring-1 self-gate only with no active slice.
+    if (iteration === 1 && sliceErrors.length === 0 && !hasUnresolvedActiveSlice(projectDir)) {
+      const ring1 = validateDeveloperRing1SelfGate(projectDir, content, readHandoff(projectDir));
+      ring1SelfGateErrors = ring1.errors;
+      for (const w of ring1.warnings ?? []) {
+        process.stderr.write(`[playcraft-workflow-stop] advisory: ${w}\n`);
+      }
+    }
+    return [...regressionErrors, ...contextErrors, ...intakeErrors, ...planErrors, ...checkpointErrors, ...contractErrors, ...sliceErrors, ...ring1SelfGateErrors];
+  }
+
+  if (role === 'technical-artist' && iteration >= 4) {
+    const taErrors = [];
+    const handoff = readHandoff(projectDir);
+    const next = handoff.next_orchestrator_action || '';
+    if (/reviewer ui_diff/i.test(next) && !/developer/i.test(next)) {
+      taErrors.push(
+        'TA STOP must route to @developer (Ring 4 production integration) before @reviewer ui_diff',
+      );
+    }
+    return [...regressionErrors, ...contextErrors, ...intakeErrors, ...planErrors, ...taErrors];
+  }
+
+  return [...regressionErrors, ...contextErrors, ...intakeErrors, ...planErrors, ...contractErrors];
+}
+
+/** Selected atoms that must be linked into .claude/skills/ (excludes bundled playcraft-* skills). */
+function readSelectedAtomsForLink(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 [];
+  }
+}
+
+/** Extract a markdown section body from `heading` up to the next same-or-higher-level heading. */
+function extractMarkdownSection(content, heading) {
+  const start = content.indexOf(heading);
+  if (start === -1) return null;
+  const level = (heading.match(/^#+/) || ['##'])[0].length;
+  const after = content.slice(start + heading.length);
+  const lines = after.split('\n');
+  const body = [];
+  for (let i = 1; i < lines.length; i += 1) {
+    const m = lines[i].match(/^(#+)\s/);
+    if (m && m[1].length <= level) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+/** Count filled (non-template, non-header, non-separator) markdown table data rows. */
+function countFilledTableRows(section) {
+  let count = 0;
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|[\s|:-]+\|?$/.test(trimmed)) continue;
+    if (/selectedAtomRef|Read path|怎么用|Asset contract path|Tier \/ Source/.test(trimmed)) continue;
+    if (PLACEHOLDER_RE.test(trimmed)) continue;
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * Shared skill-link + Skill Preflight + placeholder materialization evidence gate.
+ * Applied at every ring's Developer build STOP so "use placeholders / implement per skill"
+ * is enforced from ring 1 onward, not just documented.
+ * @param {string} projectDir
+ * @param {string} content developer-log.md content
+ * @returns {string[]}
+ */
+function validateSkillAndPlaceholderEvidence(projectDir, content) {
+  const errors = [];
+  const atoms = readSelectedAtomsForLink(projectDir);
+
+  // 1. Skill link evidence: selected atoms materialized under .claude/skills/
+  const skillsDir = path.join(projectDir, '.claude/skills');
+  const unlinked = atoms.filter((atom) => !fs.existsSync(path.join(skillsDir, atom)));
+  if (unlinked.length > 0) {
+    errors.push(
+      `Skill link: selected atom skill(s) not linked into .claude/skills/: ${unlinked.join(', ')} — re-save docs/atom-tree.json (auto-links) or run playcraft skills link --from-atom-tree --prune`,
+    );
+  }
+
+  // 2. Skill Preflight filled (one non-template row per atom)
+  const preflight = extractMarkdownSection(content, '## Skill Preflight');
+  if (!preflight || countFilledTableRows(preflight) < Math.max(1, atoms.length)) {
+    errors.push(
+      'Skill Preflight: developer-log.md § Skill Preflight is not filled — add one non-template row per selected atom (read .claude/skills/<atom>/SKILL.md: what it provides + how you use it)',
+    );
+  }
+
+  // 3. Placeholder materialization evidence (placeholder-first, not code-draw-only)
+  const placeholder = extractMarkdownSection(content, '### Placeholder materialization');
+  if (!placeholder) {
+    errors.push(
+      'Placeholder: developer-log.md § Placeholder materialization missing — fill the materialization table + "Placeholder run result" (run npm run placeholder:gen)',
+    );
+  } else {
+    if (countFilledTableRows(placeholder) < 1) {
+      errors.push(
+        'Placeholder: § Placeholder materialization table has no filled row — record each placeholder asset (path / Tier / size / generated) before STOP; Ring 1 onward forbids pure code-drawn visuals',
+      );
+    }
+    if (!/Placeholder run result[^\n]*\b(success|partial)\b/i.test(placeholder)) {
+      errors.push(
+        'Placeholder: § Placeholder materialization "Placeholder run result" must be success or partial (run npm run placeholder:gen and record the outcome)',
+      );
+    }
+  }
+
+  // 4. verify:placeholders recorded as pass/OK in developer-log
+  if (!/verify:placeholders[\s\S]{0,120}\b(OK|pass|passed)\b/i.test(content)) {
+    errors.push(
+      'Placeholder: run npm run verify:placeholders and log pass/OK in developer-log § Dev self-check',
+    );
+  }
+
+  return errors;
+}
+
+/**
+ * The recorded devUrl must carry the `?debug=1` flag so opening it shows the
+ * on-screen one-click clear (debug) button by default. Only flags when a devUrl
+ * http(s) link is actually present (no false positive when none recorded yet).
+ * @param {string} content developer-log.md content
+ * @returns {string[]}
+ */
+function validateDevUrlDebugFlag(content) {
+  const errors = [];
+  const m = content.match(/devUrl[^\n]*?(https?:\/\/[^\s)<>"']+)/i);
+  if (m && !/[?&]debug=1\b/.test(m[1])) {
+    errors.push(
+      `devUrl: recorded devUrl (${m[1]}) must include ?debug=1 — every dev url is opened with debug=1 so the one-click clear debug button shows by default`,
+    );
+  }
+  return errors;
+}
+
+/**
+ * Ring 1 build STOP: Developer self-gates objective DoD via scripts (no Reviewer invoke).
+ * @param {string} projectDir
+ * @param {string} content
+ * @param {Record<string, string>} handoff
+ * @returns {string[]}
+ */
+function validateDeveloperRing1SelfGate(projectDir, content, handoff) {
+  const errors = [];
+  const warnings = [];
+  const nextAction = handoff.next_orchestrator_action || '';
+  if (!/ring:gate/i.test(nextAction)) {
+    errors.push(
+      'Ring 1 build STOP: next_orchestrator_action must route orchestrator to npm run ring:gate -- --iteration 1 after per-slice verify:slice + terminal slice queue (ring:gate aggregates; it does not replace verify:slice)',
+    );
+  }
+  if (!/\bverify:contract\b[\s\S]{0,120}\b(OK|pass|passed|satisfied)\b/i.test(content)) {
+    errors.push(
+      'Ring 1 build STOP: run npm run verify:contract and log pass/OK in developer-log § Dev self-check',
+    );
+  }
+  if (!/\bverify:lifecycle\b[\s\S]{0,120}\b(OK|pass|passed)\b/i.test(content)) {
+    errors.push(
+      'Ring 1 build STOP: run npm run verify:lifecycle and log pass/OK in developer-log § Dev self-check',
+    );
+  }
+  if (!/\bverify:firstwin\b[\s\S]{0,120}\b(OK|pass|passed)\b/i.test(content)) {
+    errors.push(
+      'Ring 1 build STOP: run npm run verify:firstwin and log pass/OK in developer-log § Dev self-check',
+    );
+  }
+  if (!/\bverify:placeholders\b[\s\S]{0,120}\b(OK|pass|passed)\b/i.test(content)) {
+    errors.push(
+      'Ring 1 build STOP: run npm run verify:placeholders and log pass/OK in developer-log § Dev self-check',
+    );
+  }
+  errors.push(...validateSkillAndPlaceholderEvidence(projectDir, content));
+  errors.push(...validateDevUrlDebugFlag(content));
+  const devStatus = readState(projectDir).devPreview?.devStatus;
+  if (String(devStatus || '').toLowerCase() !== 'ready') {
+    errors.push('Ring 1 build STOP: set devStatus: ready (npm run state:set -- devStatus=ready) before STOP');
+  }
+  const scenesDir = path.join(projectDir, 'game/scenes');
+  if (fs.existsSync(scenesDir)) {
+    const SCENE_LINE_WARN = 400;
+    for (const name of fs.readdirSync(scenesDir)) {
+      if (!/\.(ts|js)$/.test(name)) continue;
+      const abs = path.join(scenesDir, name);
+      if (!fs.statSync(abs).isFile()) continue;
+      const lineCount = fs.readFileSync(abs, 'utf8').split('\n').length;
+      if (lineCount > SCENE_LINE_WARN) {
+        warnings.push(
+          `Scene file ${name} has ${lineCount} lines (>${SCENE_LINE_WARN}) — split into game/gameplay/ submodules (hard target ≤350 lines/scene)`,
+        );
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+/**
+ * Developer STOP checkpoint — 4 items:
+ * 0. Feature Checklist existence (developer-log.md § Feature Checklist or § Feature Review)
+ * 1. Delivery Checklist coverage (implementation-plan.md § 8 vs developer-log.md § Feature Review)
+ * 2. Scaffold asset adoption (scaffold-manifest.md vs developer-log.md § Read / Load Log) + scaffold decision documented
+ * 3. Upstream blockers closed (no open blocker without resolution)
+ * @param {string} projectDir
+ * @param {string} devLogContent
+ */
+function validateDeveloperCheckpoints(projectDir, devLogContent) {
+  const errors = [];
+
+  // --- 0. Feature Checklist existence ---
+  const hasFeatureChecklist =
+    devLogContent.includes('## Feature Checklist') ||
+    devLogContent.includes('## Feature Review');
+  const hasFeatureItem =
+    /^\s*[-*]\s*\[[ xX]\]/.test(devLogContent.split('\n').find((l) => l.includes('## Feature')));
+  if (!hasFeatureChecklist) {
+    errors.push(
+      'Feature Checklist: missing "## Feature Checklist" or "## Feature Review" section in developer-log.md — create it from implementation-plan.md features before claiming readiness',
+    );
+  }
+
+  // --- 1. Delivery Checklist coverage ---
+  const implPlanPath = path.join(projectDir, 'docs/implementation-plan.md');
+  if (fs.existsSync(implPlanPath)) {
+    const implPlan = fs.readFileSync(implPlanPath, 'utf8');
+    const checklistStart = implPlan.indexOf('## 8. Delivery Checklist');
+    if (checklistStart !== -1) {
+      const checklistSection = implPlan.slice(checklistStart);
+      // Extract unchecked items: lines starting with "- [ ]"
+      const uncheckedItems = [];
+      for (const line of checklistSection.split('\n')) {
+        const trimmed = line.trim();
+        if (/^- \[ \]/.test(trimmed)) {
+          // Extract item text (strip "- [ ] " prefix and "— source: ..." suffix)
+          const itemText = trimmed
+            .replace(/^- \[ \]\s*/, '')
+            .replace(/\s*—\s*source:.*$/, '')
+            .trim();
+          uncheckedItems.push(itemText);
+        }
+      }
+      if (uncheckedItems.length > 0) {
+        // Check if Feature Review section exists and has content
+        const featureReviewStart = devLogContent.indexOf('## Feature Review');
+        if (featureReviewStart === -1) {
+          errors.push(
+            `Delivery Checklist: ${uncheckedItems.length} unchecked item(s) — add "## Feature Review" section to developer-log.md and mark each item done/partial(reason)`,
+          );
+        } else {
+          // Items exist but are unchecked — developer must address them
+          errors.push(
+            `Delivery Checklist: ${uncheckedItems.length} unchecked item(s) in implementation-plan.md § 8 — mark each [x] or add partial/blocked note in developer-log.md § Feature Review:\n  ${uncheckedItems.slice(0, 5).join('\n  ')}${uncheckedItems.length > 5 ? `\n  ... and ${uncheckedItems.length - 5} more` : ''}`,
+          );
+        }
+      }
+    }
+  }
+
+  // --- 2. Scaffold asset adoption + decision documentation ---
+  // Check scaffold decision is documented in Skill Preflight (whether or not scaffold was executed)
+  const skillPreflightStart = devLogContent.indexOf('## Skill Preflight');
+  const hasScaffoldDecision =
+    devLogContent.toLowerCase().includes('scaffold-candidate') ||
+    devLogContent.toLowerCase().includes('skip-with-reason') ||
+    devLogContent.toLowerCase().includes('scaffold decision') ||
+    devLogContent.toLowerCase().includes('本轮 scaffold');
+  if (skillPreflightStart !== -1 && !hasScaffoldDecision) {
+    errors.push(
+      'Scaffold decision: no scaffold decision found in developer-log.md § Skill Preflight — document per-atom decision (scaffold-candidate / skip-with-reason) and add a summary line (e.g. "本轮 scaffold: none, because ...")',
+    );
+  }
+
+  const manifestPath = path.join(projectDir, 'docs/scaffold-manifest.md');
+  if (fs.existsSync(manifestPath)) {
+    const manifest = fs.readFileSync(manifestPath, 'utf8');
+    // Count scaffold entries (lines with asset paths, e.g. "- game/assets/...")
+    const scaffoldAssets = [];
+    for (const line of manifest.split('\n')) {
+      const trimmed = line.trim();
+      if (/^-\s+game\/assets\//.test(trimmed) || /^-\s+`game\/assets\//.test(trimmed)) {
+        scaffoldAssets.push(trimmed.replace(/^-\s+`?/, '').replace(/`?$/, '').trim());
+      }
+    }
+    if (scaffoldAssets.length > 0) {
+      // Check if developer-log has any load evidence
+      const hasLoadLog =
+        devLogContent.includes('## Read / Load Log') ||
+        devLogContent.includes('this.load.') ||
+        devLogContent.includes('load.image') ||
+        devLogContent.includes('load.atlas') ||
+        devLogContent.includes('load.audio');
+      const hasAdoptionNote =
+        devLogContent.toLowerCase().includes('scaffold') &&
+        (devLogContent.toLowerCase().includes('unused') ||
+          devLogContent.toLowerCase().includes('replaced') ||
+          devLogContent.toLowerCase().includes('not used') ||
+          devLogContent.toLowerCase().includes('adoption'));
+      if (!hasLoadLog && !hasAdoptionNote) {
+        errors.push(
+          `Scaffold asset adoption: ${scaffoldAssets.length} scaffold asset(s) found in docs/scaffold-manifest.md but no load evidence or adoption note in developer-log.md — add load records or explain why assets were not used`,
+        );
+      }
+    }
+  }
+
+  // --- 3. Upstream blockers closed ---
+  const blockersStart = devLogContent.indexOf('## Upstream blockers');
+  if (blockersStart !== -1) {
+    const after = devLogContent.slice(blockersStart + '## Upstream blockers'.length);
+    const nextHeading = after.search(/\n##\s+/);
+    const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const openBlockers = [];
+    for (const line of section.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|')) continue;
+      if (/^\|\s*---/.test(trimmed)) continue;
+      if (/^\|\s*(Blocker|blocker|Item|item|Path)\b/i.test(trimmed)) continue;
+      const parts = trimmed
+        .split('|')
+        .map((p) => p.trim())
+        .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+      // Template: | Path(0) | Issue(1) | Resolution(2) | routeTo(3) | Status(4) |
+      if (parts.length < 5) continue;
+      const status = (parts[4] || '').toLowerCase();
+      const resolution = (parts[2] || '').trim();
+      // Valid resolutions that genuinely close a blocker:
+      // fixed, replaced(<reason>), escalated — anything else is a note, not a resolution.
+      const isValidResolution =
+        /^(fixed|replaced|escalated)\b/i.test(resolution) ||
+        resolution === '—' ||
+        resolution === '-' ||
+        resolution === '';
+      if (status === 'open' || !isValidResolution) {
+        openBlockers.push(parts[0]);
+      }
+    }
+    if (openBlockers.length > 0) {
+      errors.push(
+        `Upstream blockers: ${openBlockers.length} open blocker(s) without resolution — set resolution to fixed/replaced(reason)/escalated:\n  ${openBlockers.join('\n  ')}`,
+      );
+    }
+  }
+
+  // --- 4. Skill link + Skill Preflight + placeholder materialization evidence (ring 2+ parity with ring 1) ---
+  errors.push(...validateSkillAndPlaceholderEvidence(projectDir, devLogContent));
+
+  // --- 5. devUrl carries ?debug=1 (one-click clear debug button shown by default) ---
+  errors.push(...validateDevUrlDebugFlag(devLogContent));
+
+  return errors;
+}
+
+/** @param {string} projectDir */
+async function validateWorkflowState(projectDir) {
+  const result = await diagnose(projectDir, { strict: 'stop' });
+  return result.ok ? [] : result.errors;
+}
+
+/** @param {string} projectDir */
+function resolveProjectDir(projectDir) {
+  if (!stateExists(projectDir)) {
+    return { skip: true, reason: 'no docs/project-state.json or .md' };
+  }
+  return { skip: false };
+}
+
+function emitBlock(reason) {
+  const payload = { decision: 'block', reason };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stderr.write(`[playcraft-workflow-stop] ${reason}\n`);
+  process.exit(2);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export {
+  detectRole,
+  roleFromActiveSlice,
+  validateActiveSliceResolved,
+  validateResolvedSliceStop,
+  hasUnresolvedActiveSlice,
+  isSliceResolved,
+  parseUpstreamIntake,
+  validateIntakeContent,
+  validatePlan,
+  validateArtistSkillPreflight,
+  validateDeveloperRuntimeContract,
+  validateRole,
+  validateReviewerStop,
+  validateGameDesignerStop,
+  validateSkillSelectorStop,
+  validateUiDiffVisualRubric,
+  validatePlayableSeedDesign,
+  validateHandoffContext,
+  validateGameDesignerSeedContext,
+  validateGameDesignerSliceQueueSeed,
+  validateSkillsMatchSliceRefs,
+  validateDesignFusionSection,
+  validateReviewerHandoff,
+  validateReviewReportDoD,
+  readHandoff,
+  readIteration,
+  readLoop,
+  readStage,
+  readGatePending,
+  requiredDocsForRole,
+  validateWorkflowState,
+  DEV_REQUIRED_DOCS_BY_RING,
+  TA_REQUIRED_DOCS_BY_RING,
+  ARTIST_REQUIRED_DOCS,
+  DESIGNER_REQUIRED_DOCS_BY_RING,
+  reviewDoDKeysForRing,
+  PLAN_HEADING,
+  PLAN_REQUIRED_SUBS,
+  ROLE_LOG,
+  validateSkillAndPlaceholderEvidence,
+  validateDevUrlDebugFlag,
+  readSelectedAtomsForLink,
+  extractMarkdownSection,
+  countFilledTableRows,
+};
+
+async function main() {
+  const stdin = await readStdin();
+  const input = parseHookInput(stdin);
+
+  const projectDir =
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+
+  const { skip } = resolveProjectDir(projectDir);
+  if (skip) {
+    process.exit(0);
+  }
+
+  // slice-axis-v1: an explicit role marker (subagent_type / PLAYCRAFT_STOP
+  // self-declaration) wins; otherwise derive the dispatched role from an
+  // unresolved active slice so a top-level `claude -p` developer cannot STOP past
+  // an unverified slice even without subagent context.
+  const role = detectRole(input) || roleFromActiveSlice(projectDir);
+  if (!role) {
+    process.exit(0);
+  }
+
+  // slice mode = this role owns an unresolved active slice → the slice state
+  // machine is the only gate; ring intake/handoff ceremony is bypassed.
+  const sliceOwner = roleFromActiveSlice(projectDir);
+  const sliceMode = sliceOwner === role;
+  // dispatch mismatch = an executor role was stopped on someone else's slice.
+  const sliceMismatch = !!sliceOwner && sliceOwner !== role && SLICE_EXECUTOR_ROLES.has(role);
+
+  const errors = validateRole(projectDir, role);
+  if (errors.length > 0) {
+    const cfg = ROLE_LOG[role];
+    if (sliceMode || sliceMismatch) {
+      const label = cfg?.label || role;
+      const head = sliceMismatch ? 'dispatch mismatch' : 'resolve the active slice before STOP';
+      emitBlock(`${label} STOP blocked — ${head}:\n- ${errors.join('\n- ')}`);
+    }
+    const loop = readLoop(projectDir);
+    const iteration = readIteration(projectDir) || 1;
+    const section =
+      role === 'reviewer'
+        ? '§ Ring DoD Fields + handoff (no user_gate)'
+        : role === 'game-designer'
+          ? `§ ring ${iteration} clarify docs`
+          : role === 'skill-selector'
+            ? '§ atom-tree selection + handoff'
+          : role === 'artist'
+            ? loop === 'verify' && iteration >= 3
+              ? '§ Image Production Preflight / ASR Coverage Matrix'
+              : '§ Skill Preflight'
+            : '§ Upstream Intake / Plan';
+    const logRef = cfg.log ? `${cfg.log} ` : '';
+    const reason = `${cfg.label} STOP blocked — fix ${logRef}${section}:\n- ${errors.join('\n- ')}`;
+    emitBlock(reason);
+  }
+
+  // In slice mode the active slice is the sole authority — skip the ring/handoff
+  // workflow-state diagnosis (it carries ring-era expectations that do not apply
+  // to a single dispatched slice). Legacy (no active slice) keeps full diagnosis.
+  if (!sliceMode) {
+    const stateErrors = await validateWorkflowState(projectDir);
+    if (stateErrors.length > 0) {
+      const reason = `Workflow STOP blocked — fix docs/project-state.md handoff / ring state:\n- ${stateErrors.join('\n- ')}`;
+      emitBlock(reason);
+    }
+  }
+
+  process.exit(0);
+}
+
+// Use basename comparison — on Windows, CLAUDE_PROJECT_DIR may be POSIX-style
+// (/d/project/...), and path.resolve would mangle it to D:\d\project\...,
+// never matching the Windows-native __filename.
+const isMain =
+  process.argv[1] && path.basename(process.argv[1]) === path.basename(__filename);
+
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`[playcraft-workflow-stop] validator error: ${err.message}\n`);
+    process.exit(1);
+  });
+}