@playcraft/cli 0.0.44 → 0.0.47

package/dist/atom-tree/build-skeleton.js

@@ -0,0 +1,180 @@
+/**
+ * Canonical atom-tree skeleton — SSOT aligned with docs/team/atom-tree-format.md
+ * and templates/atom-tree.template.json in project-template.
+ */
+export const RING_SPECS = {
+    '1': {
+        goal: 'first playable loop',
+        requiredPaths: ['engine'],
+        verifiers: ['contract', 'lifecycle', 'firstLevelWin', 'placeholders'],
+        acceptanceKeys: ['contract', 'lifecycle', 'firstLevelWin', 'placeholders'],
+    },
+    '2': {
+        goal: 'gameplay + periphery',
+        requiredPaths: ['engine'],
+        verifiers: ['contract', 'lifecycle', 'firstLevelWin', 'oneClickEndcard', 'verifyUi', 'fullPlaythrough', 'placeholders', 'fusion'],
+        acceptanceKeys: ['contract', 'lifecycle', 'firstLevelWin', 'oneClickEndcard', 'verifyUi', 'fullPlaythrough', 'placeholders', 'fusion'],
+    },
+    '3': {
+        goal: 'playable ad hook/CTA',
+        requiredPaths: ['engine'],
+        verifiers: [
+            'contract',
+            'lifecycle',
+            'firstLevelWin',
+            'oneClickEndcard',
+            'verifyUi',
+            'fullPlaythrough',
+            'hookCta',
+            'placeholders',
+            'fusion',
+        ],
+        acceptanceKeys: [
+            'contract',
+            'lifecycle',
+            'firstLevelWin',
+            'oneClickEndcard',
+            'verifyUi',
+            'fullPlaythrough',
+            'hookCta',
+            'placeholders',
+            'fusion',
+        ],
+    },
+    '4': {
+        goal: 'production + architecture',
+        requiredPaths: ['engine'],
+        verifiers: [
+            'contract',
+            'lifecycle',
+            'firstLevelWin',
+            'oneClickEndcard',
+            'verifyUi',
+            'fullPlaythrough',
+            'hookCta',
+            'uiDiff',
+            'visualDiff',
+            'bgClean',
+            'tileConsistency',
+            'textOverlap',
+            'assetBudget',
+            'assetCodeSync',
+            'atomConformance',
+            'fusion',
+        ],
+        acceptanceKeys: [
+            'contract',
+            'lifecycle',
+            'firstLevelWin',
+            'oneClickEndcard',
+            'verifyUi',
+            'fullPlaythrough',
+            'hookCta',
+            'uiDiff',
+            'visualDiff',
+            'bgClean',
+            'tileConsistency',
+            'textOverlap',
+            'assetBudget',
+            'assetCodeSync',
+            'atomConformance',
+            'fusion',
+        ],
+    },
+};
+function emptySkillsMatch() {
+    return {
+        engine: null,
+        engineSource: 'none',
+        intent: [],
+        items: [],
+        mediaGroups: [],
+    };
+}
+function defaultSelectionRevision(partial) {
+    return {
+        version: partial?.version ?? '1.0',
+        date: partial?.date ?? new Date().toISOString().split('T')[0],
+        changes: partial?.changes ?? 'Initial skeleton',
+        author: partial?.author ?? 'cli',
+    };
+}
+/** Uninitialized template skeleton (ensure-project / atom-tree.template.json). */
+export function buildUnsetAtomTreeSkeleton() {
+    return {
+        meta: {
+            atomTreeSchemaVersion: 1,
+            title: '',
+            idea: '',
+            gate: 1,
+            engineDecision: {
+                mode: 'unset',
+                engine: null,
+                engineAtom: null,
+                adapter: null,
+                reason: 'Run playcraft skills init-atom-tree after intent is known.',
+                runtimeContract: 'window.__playable',
+            },
+            skillsMatch: emptySkillsMatch(),
+            selectedAtoms: [],
+            selectionRevisions: [
+                defaultSelectionRevision({
+                    changes: 'Initial unset skeleton from template',
+                    author: 'template',
+                }),
+            ],
+            rings: { ...RING_SPECS },
+        },
+        engine: { atom: null },
+        globals: {},
+        scenes: [],
+        review: {},
+    };
+}
+/** Populated skeleton after skills match / init-atom-tree. */
+export function buildAtomTreeSkeleton(opts) {
+    const engine = opts.engine ?? null;
+    const engineSource = opts.engineSource ?? (engine ? 'explicit' : 'none');
+    const intent = opts.intent ?? [];
+    const skillsMatch = {
+        ...emptySkillsMatch(),
+        ...opts.skillsMatch,
+        engine: opts.skillsMatch?.engine ?? engine,
+        engineSource: opts.skillsMatch?.engineSource ?? engineSource,
+        intent: opts.skillsMatch?.intent ?? intent,
+        items: opts.skillsMatch?.items ?? [],
+        mediaGroups: opts.skillsMatch?.mediaGroups ?? [],
+    };
+    const mode = engineSource === 'explicit' || engineSource === 'inferred' ? engineSource : 'unset';
+    const rings = opts.ringsRing1Only
+        ? { '1': RING_SPECS['1'] }
+        : { ...RING_SPECS };
+    return {
+        meta: {
+            atomTreeSchemaVersion: 1,
+            title: opts.title ?? '',
+            idea: opts.idea ?? intent.join(', '),
+            gate: 1,
+            engineDecision: {
+                mode,
+                engine,
+                engineAtom: engine ? `${engine}.aicomponent` : null,
+                adapter: engine,
+                reason: engineSource === 'explicit'
+                    ? `--engine ${engine} was provided`
+                    : engineSource === 'inferred'
+                        ? `inferred from intent: ${intent.join(', ')}`
+                        : 'Run playcraft skills init-atom-tree after intent is known.',
+                runtimeContract: 'window.__playable',
+            },
+            skillsMatch,
+            selectedAtoms: [],
+            selectionRevisions: [defaultSelectionRevision(opts.selectionRevision)],
+            rings,
+        },
+        engine: engine ? `${engine}.aicomponent` : { atom: null },
+        globals: {},
+        scenes: [],
+        review: {},
+    };
+}

package/dist/atom-tree/fusion-hints.js

@@ -0,0 +1,86 @@
+/**
+ * Gameplay×gameplay fusion hints for init-atom-tree / skills match.
+ * Reads `fusesWith` edges from atom-graph when available; falls back to embedded pairs.
+ */
+import { basicAtomSkillGraph } from '@playcraft/common/recommend';
+/** Fallback when linked @playcraft/common predates fusesWith edges in basicAtomSkillGraph. */
+const EMBEDDED_FUSION_EDGES = [
+    {
+        from: 'match3_core.aigameplay',
+        to: 'memory_match.aigameplay',
+        label: 'B2-Active, low risk',
+    },
+    {
+        from: 'match3_core.aigameplay',
+        to: 'screw_puzzle.aigameplay',
+        label: 'C-Sequential, high risk → prefer pseudo-fusion',
+    },
+    {
+        from: 'memory_match.aigameplay',
+        to: 'screw_puzzle.aigameplay',
+        label: 'C-Sequential, high risk → prefer pseudo-fusion',
+    },
+    {
+        from: 'match3_core.aigameplay',
+        to: 'arrow_escape_core.aigameplay',
+        label: 'C-Sequential, medium-high risk → prefer pseudo-fusion',
+    },
+];
+function fusionEdges() {
+    const fromGraph = basicAtomSkillGraph.edges.filter((edge) => String(edge.kind) === 'fusesWith');
+    return fromGraph.length > 0 ? fromGraph : EMBEDDED_FUSION_EDGES;
+}
+function parseFusionEdgeLabel(label) {
+    const raw = (label ?? '').trim();
+    const typeMatch = raw.match(/(Single|A-Visual|B1-Passive|B2-Active|C-Sequential|D-Parallel)/);
+    const recommendedType = typeMatch?.[1] ?? 'B2-Active';
+    const lower = raw.toLowerCase();
+    let risk = 'medium';
+    if (/extreme/.test(lower))
+        risk = 'extreme';
+    else if (/high/.test(lower))
+        risk = 'high';
+    else if (/low/.test(lower))
+        risk = 'low';
+    else if (/medium/.test(lower))
+        risk = 'medium';
+    const preferPseudoFusion = /prefer pseudo-fusion/i.test(raw) ||
+        recommendedType === 'C-Sequential' ||
+        recommendedType === 'D-Parallel' ||
+        risk === 'high' ||
+        risk === 'extreme';
+    return { recommendedType, risk, preferPseudoFusion };
+}
+/** Resolve gameplay×gameplay fusion hints (order-independent pairs). */
+export function getFusionHintsForGameplayAtoms(atomIds) {
+    const gameplayIds = atomIds.filter((id) => id.endsWith('.aigameplay'));
+    if (gameplayIds.length < 2)
+        return [];
+    const hints = [];
+    const seen = new Set();
+    const edges = fusionEdges();
+    for (let i = 0; i < gameplayIds.length; i += 1) {
+        for (let j = i + 1; j < gameplayIds.length; j += 1) {
+            const a = gameplayIds[i];
+            const b = gameplayIds[j];
+            const key = [a, b].sort().join('::');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const edgeHit = edges.find((edge) => edge.from === a && edge.to === b) ??
+                edges.find((edge) => edge.from === b && edge.to === a);
+            if (!edgeHit)
+                continue;
+            const parsed = parseFusionEdgeLabel(edgeHit.label);
+            hints.push({
+                from: a,
+                to: b,
+                recommendedType: parsed.recommendedType,
+                risk: parsed.risk,
+                preferPseudoFusion: parsed.preferPseudoFusion,
+                label: edgeHit.label ?? `${parsed.recommendedType}, ${parsed.risk} risk`,
+            });
+        }
+    }
+    return hints;
+}

package/dist/atom-tree/selection.js

@@ -0,0 +1,402 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../config.js';
+const PROTECTED_SKILL_PREFIX = 'playcraft-';
+function normalizeAtomRef(ref) {
+    if (typeof ref !== 'string')
+        return null;
+    const trimmed = ref.trim();
+    return trimmed ? trimmed : null;
+}
+function normalizeSelectedAtomRef(ref) {
+    const direct = normalizeAtomRef(ref);
+    if (direct)
+        return direct;
+    if (ref && typeof ref === 'object') {
+        const record = ref;
+        return normalizeAtomRef(record.atomId) ?? normalizeAtomRef(record.id);
+    }
+    return null;
+}
+export function resolveSkillsDirs(customDir, configDir) {
+    if (customDir)
+        return [path.resolve(customDir)];
+    const dirs = [];
+    if (configDir)
+        dirs.push(path.resolve(configDir));
+    const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+    dirs.push(...envPaths);
+    const cwdSkillsBase = path.join(process.cwd(), 'node_modules', '@playcraft', 'skills');
+    const cwdModulesPath = path.join(cwdSkillsBase, 'playcraft-skills');
+    if (fs.existsSync(cwdModulesPath))
+        dirs.push(cwdModulesPath);
+    const cwdModulesPathLegacy = path.join(cwdSkillsBase, 'skills');
+    if (fs.existsSync(cwdModulesPathLegacy))
+        dirs.push(cwdModulesPathLegacy);
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const monoSkillsPath = path.resolve(__dirname, '..', '..', '..', '..', 'skills', 'playcraft-skills');
+    if (fs.existsSync(monoSkillsPath))
+        dirs.push(monoSkillsPath);
+    const monoSkillsPathLegacy = path.resolve(__dirname, '..', '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(monoSkillsPathLegacy) && monoSkillsPathLegacy !== monoSkillsPath) {
+        dirs.push(monoSkillsPathLegacy);
+    }
+    const distSkillsPath = path.resolve(__dirname, '..', '..', '..', 'skills', 'playcraft-skills');
+    if (fs.existsSync(distSkillsPath) && distSkillsPath !== monoSkillsPath) {
+        dirs.push(distSkillsPath);
+    }
+    const distSkillsPathLegacy = path.resolve(__dirname, '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(distSkillsPathLegacy) && distSkillsPathLegacy !== monoSkillsPathLegacy && distSkillsPathLegacy !== distSkillsPath) {
+        dirs.push(distSkillsPathLegacy);
+    }
+    return [...new Set(dirs)];
+}
+export async function resolveProjectSkillsDirs(projectDir, skillsDirOverride) {
+    const root = path.resolve(projectDir);
+    const config = await loadConfig({ dir: root }).catch(() => ({ skillsDir: undefined }));
+    return resolveSkillsDirs(skillsDirOverride, config.skillsDir);
+}
+export function loadSkillManifestIndex(skillsDirs) {
+    const manifestIndex = new Map();
+    for (const dir of skillsDirs) {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            continue;
+        for (const name of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!name.isDirectory())
+                continue;
+            const manifestPath = path.join(dir, name.name, 'manifest.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (manifest.atomId)
+                    manifestIndex.set(manifest.atomId, manifest);
+            }
+            catch {
+                // Ignore invalid manifests during discovery.
+            }
+        }
+    }
+    return manifestIndex;
+}
+export function loadSkillAtomIdSet(skillsDirs) {
+    return new Set(loadSkillManifestIndex(skillsDirs).keys());
+}
+function snapshotItemAtomIds(tree) {
+    const ids = new Set();
+    for (const item of tree.meta?.skillsMatch?.items ?? []) {
+        if (item.atomId)
+            ids.add(item.atomId);
+    }
+    return ids;
+}
+export function parseAtomTreeJson(content) {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('atom-tree JSON 必须是对象');
+    }
+    if (!parsed.meta || typeof parsed.meta !== 'object') {
+        throw new Error('atom-tree JSON 缺少 meta 对象');
+    }
+    if (!Array.isArray(parsed.meta.selectedAtoms)) {
+        throw new Error('atom-tree JSON 缺少 meta.selectedAtoms 数组');
+    }
+    const selectedAtoms = parsed.meta.selectedAtoms.map((atomRef, index) => {
+        const normalized = normalizeSelectedAtomRef(atomRef);
+        if (!normalized) {
+            throw new Error(`atom-tree JSON meta.selectedAtoms[${index}] 必须是非空字符串，或包含 atomId/id 的对象`);
+        }
+        return normalized;
+    });
+    return {
+        ...parsed,
+        meta: {
+            ...parsed.meta,
+            selectedAtoms,
+        },
+    };
+}
+/** True when atom-tree.json is still the create-template skeleton (safe to rewrite without --force). */
+export function isUninitializedAtomTreeSkeleton(tree) {
+    const selected = tree.meta?.selectedAtoms ?? [];
+    if (selected.length > 0)
+        return false;
+    const items = tree.meta?.skillsMatch?.items ?? [];
+    const engine = tree.meta?.skillsMatch?.engine;
+    if (items.length > 0 && engine)
+        return false;
+    return true;
+}
+export function collectAtomRefsFromAtomTree(tree) {
+    const refs = new Set();
+    const collect = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                collect(item);
+            return;
+        }
+        const record = value;
+        const atom = record.atom;
+        if (typeof atom === 'string')
+            refs.add(atom);
+        else if (atom && typeof atom === 'object') {
+            const id = atom.id;
+            const substitute = atom.substitute;
+            if (typeof id === 'string')
+                refs.add(id);
+            if (typeof substitute === 'string')
+                refs.add(substitute);
+        }
+        for (const child of Object.values(record))
+            collect(child);
+    };
+    if (typeof tree.engine === 'string')
+        refs.add(tree.engine);
+    else
+        collect(tree.engine);
+    collect(tree.meta?.remixSpec);
+    collect(tree.globals);
+    collect(tree.scenes);
+    collect(tree.review);
+    return [...refs].sort();
+}
+function getEffectiveBindingRoles(manifest) {
+    if (manifest.bindingRoles && manifest.bindingRoles.length > 0) {
+        return [...new Set(manifest.bindingRoles.map((role) => String(role).trim()).filter(Boolean))];
+    }
+    const fallbackRole = manifest.binding?.role;
+    return fallbackRole ? [fallbackRole] : [];
+}
+function buildRoleProviderIndex(manifestIndex, atomIds) {
+    const roleProviders = new Map();
+    const ids = atomIds ? [...atomIds] : [...manifestIndex.keys()];
+    for (const atomId of ids) {
+        const manifest = manifestIndex.get(atomId);
+        if (!manifest)
+            continue;
+        for (const role of getEffectiveBindingRoles(manifest)) {
+            const providers = roleProviders.get(role) ?? new Set();
+            providers.add(atomId);
+            roleProviders.set(role, providers);
+        }
+    }
+    return new Map([...roleProviders.entries()].map(([role, providers]) => [role, [...providers].sort()]));
+}
+function collectImportedRoleResolutionWarnings(atomRefs, manifestIndex) {
+    const warnings = new Set();
+    const selectedProvidersByRole = buildRoleProviderIndex(manifestIndex, atomRefs);
+    const libraryProvidersByRole = buildRoleProviderIndex(manifestIndex);
+    for (const atomRef of atomRefs) {
+        const manifest = manifestIndex.get(atomRef);
+        if (!manifest)
+            continue;
+        for (const imp of manifest.imports ?? []) {
+            if (imp.pinAtomId || !imp.matchBindingRoles?.length)
+                continue;
+            if (imp.cardinality === 'many')
+                continue;
+            if (typeof imp.cardinality === 'number' && imp.cardinality !== 1)
+                continue;
+            const roles = [...new Set(imp.matchBindingRoles.map((role) => String(role).trim()).filter(Boolean))];
+            for (const role of roles) {
+                const selectedProviders = selectedProvidersByRole.get(role) ?? [];
+                if (selectedProviders.length === 1)
+                    continue;
+                const slotLabel = `${atomRef}.${imp.slot}`;
+                if (selectedProviders.length === 0) {
+                    const libraryProviders = libraryProvidersByRole.get(role) ?? [];
+                    if (libraryProviders.length > 0) {
+                        warnings.add(`${slotLabel} 未选择 role "${role}" 对应 atom；可选：${libraryProviders.join(', ')}`);
+                    }
+                    continue;
+                }
+                warnings.add(`${slotLabel} 的 role "${role}" 命中多个 selected atom：${selectedProviders.join(', ')}`);
+            }
+        }
+    }
+    return [...warnings];
+}
+export function validateSelectedAtomRefs(options) {
+    const errors = [];
+    const warnings = [];
+    const { atomRefs, skillIndex, snapshotItemIds } = options;
+    const seen = new Set();
+    for (const atomRef of atomRefs) {
+        if (seen.has(atomRef)) {
+            errors.push(`meta.selectedAtoms 中存在重复的 atom ref：${atomRef}`);
+            continue;
+        }
+        seen.add(atomRef);
+        if (atomRef.startsWith(PROTECTED_SKILL_PREFIX)) {
+            errors.push(`atom ref 不得使用平台 skill（playcraft-*）：${atomRef}`);
+            continue;
+        }
+        if (!skillIndex.has(atomRef)) {
+            errors.push(`atom ref 不在 skills 库中：${atomRef}（运行 playcraft skills list --json 核对）`);
+            continue;
+        }
+        if (snapshotItemIds && snapshotItemIds.size > 0 && !snapshotItemIds.has(atomRef)) {
+            errors.push(`atom ref 未出现在 meta.skillsMatch.items 中：${atomRef}`);
+        }
+    }
+    if (atomRefs.length === 0) {
+        warnings.push('meta.selectedAtoms 为空 — 先运行 playcraft skills select-atom 添加 selected atom refs');
+    }
+    return { errors, warnings };
+}
+/** Structural checks aligned with atom-tree-format.md (non-selection). */
+export function validateAtomTreeShape(tree) {
+    const errors = [];
+    const warnings = [];
+    const meta = tree.meta;
+    if (!meta) {
+        errors.push('atom-tree JSON 缺少 meta 对象');
+        return { errors, warnings };
+    }
+    if (tree.engine !== undefined && tree.engine !== null) {
+        if (typeof tree.engine !== 'string' && !(typeof tree.engine === 'object' && tree.engine !== null)) {
+            errors.push('engine 必须是 string atom ref 或 { atom: null } 占位对象');
+        }
+        if (typeof tree.engine === 'object' &&
+            tree.engine !== null &&
+            !('atom' in tree.engine)) {
+            errors.push('engine 对象占位必须使用 { atom: null } 形态');
+        }
+    }
+    const runtimeContract = meta.engineDecision?.runtimeContract;
+    if (!runtimeContract || typeof runtimeContract !== 'string') {
+        warnings.push('meta.engineDecision.runtimeContract 缺失 — 期望 window.__playable');
+    }
+    else if (runtimeContract !== 'window.__playable') {
+        warnings.push(`meta.engineDecision.runtimeContract 非标准值: ${runtimeContract}`);
+    }
+    const revisions = meta.selectionRevisions;
+    if (Array.isArray(revisions) && revisions.length > 0) {
+        for (let i = 0; i < revisions.length; i += 1) {
+            const rev = revisions[i];
+            if (!rev || typeof rev !== 'object')
+                continue;
+            const r = rev;
+            if ('revision' in r && !('version' in r)) {
+                warnings.push(`meta.selectionRevisions[${i}] 使用旧 schema (revision/summary) — 请迁移为 version/date/changes/author`);
+            }
+        }
+    }
+    const rings = meta.rings;
+    if (!rings || typeof rings !== 'object' || !rings['1']) {
+        warnings.push('meta.rings 缺少 ring "1" 定义');
+    }
+    return { errors, warnings };
+}
+export function parseSelectedAtomRefsFromAtomTreeProject(projectDir) {
+    const root = path.resolve(projectDir);
+    const jsonPath = path.join(root, 'docs', 'atom-tree.json');
+    if (!fs.existsSync(jsonPath))
+        return [];
+    const tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+    return [...(tree.meta?.selectedAtoms ?? [])];
+}
+export function collectPinnedDependencies(atomId, manifestIndex, engine, visited = new Set(), depth = 0) {
+    const maxDepth = 100;
+    if (depth > maxDepth) {
+        throw new Error(`依赖收集递归深度超过限制 (${maxDepth})，当前 atom: ${atomId}`);
+    }
+    if (visited.has(atomId))
+        return [];
+    visited.add(atomId);
+    const manifest = manifestIndex.get(atomId);
+    if (!manifest)
+        return [];
+    const engineVariants = manifest['engineVariants'];
+    const variantImports = engineVariants?.[engine]?.imports;
+    const deps = [];
+    if (variantImports?.length) {
+        for (const pinId of variantImports) {
+            if (visited.has(pinId))
+                continue;
+            deps.push(pinId);
+            deps.push(...collectPinnedDependencies(pinId, manifestIndex, engine, visited, depth + 1));
+        }
+        return deps;
+    }
+    for (const imp of manifest.imports ?? []) {
+        if (!imp.pinAtomId || visited.has(imp.pinAtomId))
+            continue;
+        deps.push(imp.pinAtomId);
+        deps.push(...collectPinnedDependencies(imp.pinAtomId, manifestIndex, engine, visited, depth + 1));
+    }
+    return deps;
+}
+export async function validateAtomTreeSelectionProject(options) {
+    const projectDir = path.resolve(options.projectDir);
+    const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+    const dirs = await resolveProjectSkillsDirs(projectDir, options.skillsDir);
+    const manifestIndex = loadSkillManifestIndex(dirs);
+    const skillIndex = new Set(manifestIndex.keys());
+    if (dirs.length === 0) {
+        return {
+            ok: false,
+            errors: ['未找到 skills 目录。请安装 @playcraft/skills 或设置 AGENT_SKILLS_PATHS / playcraft.config.json skillsDir'],
+            warnings: [],
+            selectedAtomRefsChecked: [],
+            treeAtomRefsChecked: [],
+            source: 'atom-tree',
+        };
+    }
+    if (!fs.existsSync(jsonPath)) {
+        return {
+            ok: false,
+            errors: ['缺少 docs/atom-tree.json（先运行 playcraft skills init-atom-tree）'],
+            warnings: [],
+            selectedAtomRefsChecked: [],
+            treeAtomRefsChecked: [],
+            source: 'atom-tree',
+        };
+    }
+    let tree;
+    try {
+        tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+    }
+    catch (e) {
+        return {
+            ok: false,
+            errors: [`docs/atom-tree.json 解析失败：${e.message}`],
+            warnings: [],
+            selectedAtomRefsChecked: [],
+            treeAtomRefsChecked: [],
+            source: 'atom-tree',
+        };
+    }
+    const atomRefs = tree.meta?.selectedAtoms ?? [];
+    const snapshotIds = snapshotItemAtomIds(tree);
+    const { errors, warnings } = validateSelectedAtomRefs({
+        atomRefs,
+        skillIndex,
+        snapshotItemIds: snapshotIds,
+    });
+    const shape = validateAtomTreeShape(tree);
+    errors.push(...shape.errors);
+    warnings.push(...shape.warnings);
+    warnings.push(...collectImportedRoleResolutionWarnings(atomRefs, manifestIndex));
+    if (!tree.meta?.skillsMatch?.items?.length) {
+        warnings.push('meta.skillsMatch.items 为空 — 先运行 playcraft skills init-atom-tree 生成匹配快照');
+    }
+    const treeAtomRefs = collectAtomRefsFromAtomTree(tree);
+    for (const atomRef of treeAtomRefs) {
+        if (!skillIndex.has(atomRef)) {
+            errors.push(`atom-tree 引用未知 atom：${atomRef}`);
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        selectedAtomRefsChecked: atomRefs,
+        treeAtomRefsChecked: treeAtomRefs,
+        source: 'atom-tree',
+    };
+}