@playcraft/cli 0.0.55 → 0.0.56

package/project-template/fusion-patterns/catalog.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 2,
+  "patterns": [
+    {
+      "id": "arrow_pick_match_fusion",
+      "intentTags": ["arrow", "elimination", "fusion", "match-3", "消除", "箭头", "融合"],
+      "title": "Arrow slide-out + tray match-3",
+      "mechanics": "Paths slide into a tray; match-3 clears tray slots. Combines path puzzle dependency with elimination payoff.",
+      "playerFantasy": "Tap an arrow path — it slides out. Fill the tray strategically; match-3 clears space before overflow.",
+      "decisionMoment": "Choosing which blocked path to unlock first vs filling the tray for a combo clear.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "不要写「箭头+三消」就停；写清：棋盘哪一块先解锁、托盘峰值如何迫使颜色顺序、blocked 误点教什么。",
+      "antiPatternRef": "8×8 but ≤4 paths or all-free opening — no puzzle identity"
+    },
+    {
+      "id": "path_elimination_puzzle",
+      "intentTags": ["arrow", "path", "puzzle", "elimination", "箭头", "路径"],
+      "title": "Pure path elimination puzzle",
+      "mechanics": "Click arrow heads; paths slide out when unobstructed. Order matters — blocked paths teach dependency.",
+      "playerFantasy": "Read arrow directions, find the unlock sequence, clear the board.",
+      "decisionMoment": "First tap on a blocked path — shake/highlight feedback — then finding the correct unlock order.",
+      "skillRef": "path_elimination_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "用折线密度与依赖层数定难度，固定 8×8；至少 2 层解锁波次，禁止开局全部 FREE。",
+      "antiPatternRef": "All paths FREE at start — zero decision"
+    },
+    {
+      "id": "match3_board",
+      "intentTags": ["match-3", "match3", "swap", "三消", "消除"],
+      "title": "Classic match-3 board",
+      "mechanics": "Swap adjacent tiles; match-3 removes; gravity refills.",
+      "playerFantasy": "Swap to create matches; cascades and combos build excitement.",
+      "decisionMoment": "Choosing between an obvious match vs setting up a cascade.",
+      "skillRef": "match3_core.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "若与 path 融合，说明主手势是 swap 还是 tap-path，避免异基底双主手势。",
+      "antiPatternRef": "Auto-clear board with no player swap"
+    },
+    {
+      "id": "board_phase_unlock",
+      "intentTags": ["phase", "unlock", "mask", "分区", "解锁", "board", "fusion"],
+      "title": "Board phase unlock (same-grid mask)",
+      "mechanics": "Same 8×8 board; masked regions unlock after match clears or path milestones. New paths appear in unlocked zones — board changes via mask, not resize.",
+      "playerFantasy": "Clear the first zone to reveal more puzzle — the board grows in complexity without shrinking cells.",
+      "decisionMoment": "Spend a tray clear to unlock the next zone vs hoarding colors for a safer combo.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "写清每 phase 解锁条件与新增 path 条数；难度靠追加折线而非缩小棋盘。",
+      "antiPatternRef": "Resize board to 4×4 for difficulty — use path count instead"
+    },
+    {
+      "id": "match3_tray_puzzle_hybrid",
+      "intentTags": ["tray", "match-3", "puzzle", "hybrid", "托盘", "三消", "拼图"],
+      "title": "Tray-only match-3 + board path puzzle",
+      "mechanics": "Primary gesture: path tap on board. Match-3 happens only inside the tray. Board side is pure dependency puzzle — no swap on grid.",
+      "playerFantasy": "Solve the arrow maze; the tray is your pressure valve — match-3 is the relief, not the main puzzle.",
+      "decisionMoment": "Push a risky color into a nearly-full tray hoping the next two paths complete the triple.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "ring1_min",
+      "depthHint": "声明三消仅在托盘；棋盘侧禁止 swap。写托盘峰值曲线与颜色推出顺序。",
+      "antiPatternRef": "Board swap match-3 + path tap without interaction contract"
+    },
+    {
+      "id": "match3_board_phase",
+      "intentTags": ["match3", "phase", "path", "hybrid", "sequential", "双区"],
+      "title": "Match-3 main + path lock zone (high risk)",
+      "mechanics": "Primary zone: swap match-3. Secondary zone: path puzzle locked until match milestone. C-Sequential — document pseudo-fusion reducer.",
+      "playerFantasy": "Clear tiles to unlock the arrow zone — two systems, one win condition.",
+      "decisionMoment": "Finish the match-3 objective vs peeking at the locked path zone.",
+      "skillRef": "match3_core.aigameplay",
+      "recommendedProfile": "hard",
+      "depthHint": "Ring 2+ only.必须写 pseudo-fusion 与单 reducer，避免双主手势抢输入。",
+      "antiPatternRef": "Two equal primary gestures with no documented interaction contract"
+    }
+  ]
+}

package/project-template/package.json

@@ -54,6 +54,8 @@
     "placeholder:gen-audio": "python3 skills/_shared/scripts/gen-placeholder-audio.py",
     "verify:placeholders": "node skills/_shared/scripts/verify-placeholders.mjs --root=.",
     "verify:fusion": "node skills/playable-record/scripts/verify-fusion.mjs --root=. --use-dev",
+    "verify:design": "node skills/_shared/scripts/verify-design-consistency.mjs --root=.",
+    "levels:validate": "node skills/_shared/scripts/validate-level-sketch.mjs --root=.",
     "verify:visual-ring1": "node skills/playable-record/scripts/verify-visual-ring1.mjs --root=. --use-dev",
     "verify:visual-ring2": "node skills/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=2 --use-dev",
     "verify:visual-ring3": "node skills/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=3 --use-dev",

package/project-template/skills/_shared/scripts/create-playable.mjs

@@ -8,7 +8,7 @@
  */
 
 import { access, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
@@ -24,17 +24,27 @@ const COPY_EXCLUDES = new Set([
   'dist',
   'package-lock.json',
   'playable.ui.profile.yaml',
-  'playground',
-  'recordings',
-  'validate',
 ]);
 
+/**
+ * 仅在「模板根直接子目录」时才排除的运行时产物目录。
+ * 这些名字也会出现在 skills 内部（如 skills/playable-focus/templates/playground 与
+ * skills/playable-focus/templates/focus-lab），故只在顶层排除，避免误伤 skills 的模板素材
+ * （否则 bootstrap-playground.mjs 会因找不到 registry.template.json 而 ENOENT 退出）。
+ * 对齐 create.ts 的 shouldCopyTemplateEntry 行为。
+ */
+const TEMPLATE_ROOTLEVEL_EXCLUDES = new Set(['playground', 'recordings', 'validate']);
+
 function shouldCopy(src) {
   const name = basename(src);
   if (COPY_EXCLUDES.has(name)) return false;
-  if (src.includes(`${join('ta-workspace', 'logs')}`)) return name === '.gitkeep';
-  if (src.includes(`${join('ta-workspace', 'tmp')}`)) return name === '.gitkeep';
-  if (src.includes(`${join('focus-lab')}`)) return name === 'focus-lab' || name === '.gitkeep';
+  // 运行时产物目录只排除模板根这一层；skills 内的同名目录是模板素材，必须复制
+  if (TEMPLATE_ROOTLEVEL_EXCLUDES.has(name) && dirname(src) === TEMPLATE_ROOT) return false;
+  // 顶层 focus-lab/ 是运行时 lab 目录，只保留 .gitkeep 占位；
+  // 但 skills 内部（如 skills/playable-focus/templates/focus-lab）是模板素材，需正常复制
+  if (src.startsWith(join(TEMPLATE_ROOT, 'focus-lab') + sep)) return name === '.gitkeep';
+  if (src.includes(`${sep}ta-workspace${sep}logs${sep}`)) return name === '.gitkeep';
+  if (src.includes(`${sep}ta-workspace${sep}tmp${sep}`)) return name === '.gitkeep';
   return true;
 }
 
@@ -107,9 +117,10 @@ async function main() {
     });
     ensureResult = { status: r.status, stdout: r.stdout, stderr: r.stderr };
   }
+  const ensureFailed = opts.ensure && ensureResult?.status !== 0;
 
   const result = {
-    ok: true,
+    ok: !ensureFailed,
     projectRoot: destRoot,
     templateRoot: TEMPLATE_ROOT,
     skillsRoot: SKILLS_ROOT,
@@ -125,13 +136,22 @@ async function main() {
     console.log(JSON.stringify(result, null, 2));
   } else {
     console.log(`[create-playable] created ${destRoot}`);
-    if (ensureResult?.status === 0) {
+    if (!opts.ensure) {
+      // 跳过 ensure，无事可报
+    } else if (!ensureFailed) {
       console.log('[create-playable] ensure-project OK');
-    } else if (opts.ensure) {
-      console.warn('[create-playable] ensure-project had issues — run npm run ensure:project');
+    } else {
+      // ensure-project 失败时透出子进程真实输出（如 ENOENT、缺失模板），
+      // 否则只会看到无意义的 "node exit 1"，无法定位漏文件根因。
+      console.error('[create-playable] ensure-project failed:');
+      if (ensureResult?.stderr) console.error(ensureResult.stderr.trimEnd());
+      if (ensureResult?.stdout) console.error(ensureResult.stdout.trimEnd());
+      console.error('  → 项目模板可能不完整，运行 npm run ensure:project 排查');
     }
     for (const step of result.next) console.log(`  → ${step}`);
   }
+
+  if (ensureFailed) process.exit(1);
 }
 
 main().catch((err) => {

package/project-template/skills/_shared/scripts/dev-start.mjs

@@ -3,7 +3,7 @@
  * Start (or stop) the persistent preview dev server and record the real devUrl.
  *
  * This removes the LLM from port handling entirely (docs/harness/experiment-lessons.md §9.2):
- * Vite runs with strictPort:false, so when 3000 is taken it auto-increments; this
+ * Vite runs with strictPort:false, so when 5173 is taken it auto-increments; this
  * script parses Vite's actual `Local:` URL from the log, appends `?debug=1`, and
  * writes it back to project-state via the same layer `state:set` uses. The agent
  * never reads or records a port by hand.
@@ -20,11 +20,11 @@ import { openSync, closeSync, existsSync, readFileSync, writeFileSync, rmSync }
 import { spawn } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { applyHandoffUpdates, resolveProjectStatePath } from './state-handoff.mjs';
-import { parseLocalUrl, waitForHttp } from '../../playable-record/scripts/lib/dev-server.mjs';
+import { parseLocalUrl, waitForHttp, DEFAULT_DEV_URL } from '../../playable-record/scripts/lib/dev-server.mjs';
 
 const PID_FILE = '.playcraft-dev.pid';
 const LOG_FILE = '.playcraft-dev.log';
-const PREFERRED_URL = 'http://127.0.0.1:3000/';
+const PREFERRED_URL = DEFAULT_DEV_URL;
 
 function parseArgs(argv) {
   const opts = { root: process.cwd(), stop: false, timeout: 30000 };

package/project-template/skills/_shared/scripts/disclosure-config.mjs

@@ -7,6 +7,11 @@
  * for that surface.
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { evaluateSliceQueueForRingGate } from './state-store.mjs';
+import { resolvePrimarySkillId } from './lib/skill-fidelity.mjs';
+
 const COMMON_REQUIRED = ['CLAUDE.md'];
 
 export const FUTURE_RING_FILES = [
@@ -22,51 +27,43 @@ export const FUTURE_RING_FILES = [
 const DISCLOSURE_BY_RING_LOOP = {
   '1:clarify': {
     currentAction:
-      'Orchestrator: invoke @game-designer for Ring 1 clarify — design-brief discovery + DESIGN seed + playcraft skills match compact refs + minimal developer slice queue (not layout/style/CTA/full plan).',
-    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
-    deferredFiles: FUTURE_RING_FILES.filter((f) => f !== 'docs/design-brief.md'),
+      'Orchestrator: invoke @game-designer with only the user\'s original intent. Do not add design decisions, engine hints, platform constraints, or workflow steps — designer reads its own role card.',
+    requiredFiles: [...COMMON_REQUIRED],
+    deferredFiles: FUTURE_RING_FILES,
     nextRole: 'game-designer',
-    artifactRefs: ['docs/DESIGN.md', 'docs/design-brief.md', 'docs/atom-tree.json', 'sliceState'],
-    requiredContextFields: ['ring.goal', 'lastRole.summary', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    artifactRefs: [],
+    requiredContextFields: [],
     allowedTasks: [
-      'Invoke @game-designer for ring 1 clarify',
-      'Game Designer: design-brief discovery + DESIGN seed + playcraft skills match + sliceState queue',
-      'Game Designer: run playcraft skills match and write meta.skillsMatch + compact selectedAtoms',
-      'Record fromScratchReason when core mechanic is novel',
-      'Define first-level win strategy and semantic placeholders (Game Designer subagent)',
+      'Invoke @game-designer with user intent only',
     ],
     forbiddenTasks: [
       'Do not write docs/DESIGN.md as orchestrator',
       'Do not implement game/ as orchestrator during clarify',
-      'Do not require layout-spec or full implementation-plan in Ring 1',
-      'Do not build a full atom graph in Ring 1 clarify — compact skillsMatch refs only',
-      'Do not design CTA polish or production assets in Ring 1',
-      'Do not claim skillRefs implement core mechanic without skills read',
-      'Do not run standalone record:mp4 as a Ring 1 blocker',
-      'Do not run verify:ui as Ring 1 blockers',
+      'Do not add design decisions, engine hints, or workflow steps to the designer dispatch',
+      'Do not describe what designer should produce — its role card defines outputs',
+      'Do not list designer CLI commands — its role card defines the construction chain',
     ],
     nextCommands: [
-      'Invoke @game-designer — ring 1 clarify (skills match + design-brief + DESIGN seed + slice queue)',
+      'Invoke @game-designer — pass only the user\'s original intent, nothing more',
     ],
   },
   '1:select': {
-    currentAction: 'Orchestrator: after Game Designer STOP, spawn a temporary ref-flow atom-selection subagent for compact Ring 1 atom-tree selection.',
+    currentAction: 'Orchestrator: after Game Designer STOP, spawn a temporary ref-flow atom-selection subagent.',
     requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
     deferredFiles: FUTURE_RING_FILES,
     nextRole: 'temporary-ref-flow',
     artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json'],
-    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    requiredContextFields: ['lastRole.summary', 'sharedDecisions.coreAction'],
     allowedTasks: [
-      'Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection',
-      'Pass DESIGN.md gameplay keywords and constraints to the temporary selector',
+      'Spawn temporary ref-flow atom-selection subagent',
     ],
     forbiddenTasks: [
       'Do not select atoms inline as orchestrator',
       'Do not run init-template before atom-selection STOP',
-      'Do not implement gameplay logic as orchestrator',
+      'Do not add engine or gameplay-trunk hints to the selector dispatch',
     ],
     nextCommands: [
-      'Spawn temporary ref-flow atom-selection subagent — ring 1 atom-tree selection (engine + compact gameplay trunk)',
+      'Spawn temporary ref-flow atom-selection subagent — read docs/DESIGN.md and follow skill-selector-guide.md',
     ],
   },
   '1:scaffold': {
@@ -95,29 +92,21 @@ const DISCLOSURE_BY_RING_LOOP = {
     ],
   },
   '1:build': {
-    currentAction: 'Orchestrator: invoke @developer for Ring 1 build. Developer: implement playable spine to first-level win.',
+    currentAction: 'Orchestrator: invoke @developer for Ring 1 build.',
     requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/atom-tree.json', 'docs/scaffold-manifest.md', 'game/'],
     deferredFiles: FUTURE_RING_FILES.filter((file) => file !== 'logs/review-report.md'),
     nextRole: 'developer',
     artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json', 'logs/developer-log.md', 'game/'],
-    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'nextRole.mustKnow', 'sharedDecisions.engine', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    requiredContextFields: ['lastRole.summary', 'sharedDecisions.engine', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
     allowedTasks: [
       'Invoke @developer for ring 1 build',
-      'Apply engine scaffold if needed (orchestrator only, before developer)',
-      'Implement core gameplay loop (Developer subagent)',
-      'Wire window.__playable runtime contract (Developer subagent)',
-      'Make autoPlay follow player-reachable actions (Developer subagent)',
-      'Record devUrl when ready (Developer subagent)',
     ],
     forbiddenTasks: [
       'Do not implement game/ as orchestrator when @developer should own build',
-      'Do not polish HUD',
-      'Do not implement CTA fallback as a Ring 1 blocker',
-      'Do not run full MP4 as a Ring 1 blocker',
-      'Do not produce production assets',
+      'Do not add implementation hints to the developer dispatch — developer reads its dispatchPacket + role card',
     ],
     nextCommands: [
-      'Invoke @developer — ring 1 build (placeholder art + core loop)',
+      'Invoke @developer — pass the active slice from sliceState, nothing more',
       'npm run placeholder:gen',
       'npm run verify:contract',
       'npm run verify:lifecycle',
@@ -349,6 +338,21 @@ function normalizeIteration(iteration) {
   return Number.isFinite(n) && n >= 1 && n <= 4 ? n : 1;
 }
 
+/** Compatibility export for STOP hook mechanism-phase detection. */
+export function isMechanismLocked(projectRoot, handoffContext = {}) {
+  const skill = resolvePrimarySkillId(projectRoot, handoffContext);
+  if (!skill) return false;
+  const treePath = join(projectRoot, 'docs/atom-tree.json');
+  if (!existsSync(treePath)) return false;
+  try {
+    const tree = JSON.parse(readFileSync(treePath, 'utf8'));
+    const items = tree?.meta?.skillsMatch?.items ?? [];
+    return items.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 function resolveDisclosureKey({ iteration = 1, loop = 'clarify', handoff = {} } = {}) {
   const ring = normalizeIteration(iteration);
   const normalizedLoop = normalizeLoop(loop);
@@ -407,6 +411,11 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
   const status = String(dispatchPacket.status || 'pending').trim();
   const allowedFiles = Array.isArray(dispatchPacket.allowedFiles) ? dispatchPacket.allowedFiles : [];
   const packetForbidden = Array.isArray(dispatchPacket.forbiddenTasks) ? dispatchPacket.forbiddenTasks : [];
+  const packetRequired = Array.isArray(dispatchPacket.requiredContext?.mustRead)
+    ? dispatchPacket.requiredContext.mustRead
+    : Array.isArray(dispatchPacket.requiredContext)
+      ? dispatchPacket.requiredContext
+      : [];
 
   const currentAction =
     `Orchestrator: invoke @${role} for slice "${sliceId}" — ${doWhat} (flow: ${flow}). ` +
@@ -429,7 +438,7 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
     ring,
     loop: flow,
     currentAction,
-    currentRingRequiredFiles: [...COMMON_REQUIRED, ...allowedFiles],
+    currentRingRequiredFiles: [...new Set([...COMMON_REQUIRED, ...packetRequired, ...allowedFiles])],
     deferredFiles: FUTURE_RING_FILES.filter((f) => !allowedFiles.includes(f)),
     allowedTasks: [
       `Invoke @${role} with dispatchPacket only (sliceId=${sliceId}, flow=${flow})`,
@@ -443,7 +452,7 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
     ],
     nextCommands,
     nextRole: role,
-    artifactRefs: allowedFiles.length ? allowedFiles : ['dispatchPacket'],
+    artifactRefs: [...new Set(['dispatchPacket', ...packetRequired, ...allowedFiles])],
     requiredContextFields: [
       'dispatchPacket.sliceId',
       'dispatchPacket.role',
@@ -455,11 +464,28 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
   };
 }
 
-/** Unified entry: active dispatchPacket wins; otherwise legacy ring:loop disclosure. */
-export function disclosureForProjectState({ iteration = 1, loop = 'clarify', handoff = {}, dispatchPacket = null } = {}) {
+/** Unified entry: active dispatchPacket wins; drained queue promotes to verify + ring:gate. */
+export function disclosureForProjectState({
+  iteration = 1,
+  loop = 'clarify',
+  handoff = {},
+  dispatchPacket = null,
+  sliceState = null,
+} = {}) {
   if (dispatchPacket) {
     return disclosureForSlice(dispatchPacket, { iteration });
   }
+  const ss = sliceState || {};
+  const gate = evaluateSliceQueueForRingGate(ss);
+  const ringGatePending = String(handoff.ringGate || 'pending').toLowerCase() !== 'passed';
+  if (
+    ss.activeSliceId === 'none'
+    && gate.applicable
+    && gate.ok
+    && ringGatePending
+  ) {
+    return disclosureForState({ iteration, loop: 'verify', handoff });
+  }
   return disclosureForState({ iteration, loop, handoff });
 }
 

package/project-template/skills/_shared/scripts/harness-smoke.mjs

@@ -25,6 +25,8 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { DEFAULT_DEV_URL } from '../../playable-record/scripts/lib/dev-server.mjs';
+
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_ROOT = resolve(__dirname, '../..');
@@ -171,7 +173,7 @@ async function checkContractLive(projectRoot) {
     const { runContractProbe } = await import(pathToFileURL(probePath).href);
     const res = await runContractProbe({
       root: projectRoot,
-      url: isVite ? 'http://localhost:3000/' : null,
+      url: isVite ? DEFAULT_DEV_URL : null,
       useDev: isVite,
       port: 8080,
       scene: 'MainScene',

package/project-template/skills/_shared/scripts/lib/fusion-intent.mjs

@@ -0,0 +1,88 @@
+/**
+ * Fusion intent detection — shared by verify:fusion and verify:design-consistency.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FUSION_KEYWORDS = [
+  '融合',
+  'fusion',
+  'hybrid',
+  'combine',
+  '组合',
+  'mix',
+  'mixed',
+  'plus',
+  '+',
+  '和',
+  '与',
+  '加',
+];
+
+const ELIMINATION_KEYWORDS = ['消除', 'elimination', 'eliminate', 'match-3', 'match3', '三消', 'match'];
+const ARROW_PATH_KEYWORDS = ['箭头', 'arrow', 'path', '路径', 'slide-out', 'slide'];
+
+/** @param {string[]} intentTags @param {string} [rawIntent] */
+export function detectFusionIntent(intentTags, rawIntent = '') {
+  const blob = `${rawIntent} ${(intentTags ?? []).join(' ')}`.toLowerCase();
+  if (FUSION_KEYWORDS.some((k) => blob.includes(k.toLowerCase()))) return true;
+  const hasElim = ELIMINATION_KEYWORDS.some((k) => blob.includes(k.toLowerCase()));
+  const hasArrow = ARROW_PATH_KEYWORDS.some((k) => blob.includes(k.toLowerCase()));
+  return hasElim && hasArrow;
+}
+
+/**
+ * Collect fusion-intent signals from project artifacts.
+ * @param {string} root
+ * @returns {{ intentTags: string[], rawIntent: string }}
+ */
+export function readFusionIntentFromProject(root) {
+  const tags = [];
+  let raw = '';
+
+  const configPath = join(root, 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+      if (cfg.prompt) raw += ` ${cfg.prompt}`;
+    } catch {
+      // ignore
+    }
+  }
+
+  const atomTreePath = join(root, 'docs/atom-tree.json');
+  if (existsSync(atomTreePath)) {
+    try {
+      const tree = JSON.parse(readFileSync(atomTreePath, 'utf8'));
+      const intent = tree?.meta?.skillsMatch?.intent;
+      if (Array.isArray(intent)) tags.push(...intent.map(String));
+      else if (typeof intent === 'string') tags.push(intent);
+    } catch {
+      // ignore
+    }
+  }
+
+  const statePath = join(root, 'docs/project-state.json');
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      if (Array.isArray(state.intentTags)) tags.push(...state.intentTags.map(String));
+      if (typeof state.rawIntent === 'string') raw += ` ${state.rawIntent}`;
+    } catch {
+      // ignore
+    }
+  }
+
+  const briefPath = join(root, 'docs/design-brief.md');
+  if (existsSync(briefPath)) {
+    try {
+      const brief = readFileSync(briefPath, 'utf8');
+      const userMatch = brief.match(/\[USER\][^\n]*/i);
+      if (userMatch) raw += ` ${userMatch[0]}`;
+    } catch {
+      // ignore
+    }
+  }
+
+  return { intentTags: tags, rawIntent: raw.trim() };
+}