@playcraft/cli 0.0.53 → 0.0.56

package/project-template/skills/_shared/scripts/lib/skill-fidelity.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Mechanism fidelity — DESIGN + north-star vs primary gameplay skill PGS.
+ * Authority: SKILL.md + ref/pgs-schema.json (no mechanism-spine.md).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** @param {string} root */
+function readJson(root, rel) {
+  const p = join(root, rel);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} root @param {object} [handoffContext] */
+export function resolvePrimarySkillId(root, handoffContext = {}) {
+  const fromCtx = String(handoffContext.primaryGameplaySkill ?? '').trim();
+  if (fromCtx && fromCtx !== 'unset') return fromCtx;
+
+  const state = readJson(root, 'docs/project-state.json');
+  const fromState = String(state?.handoffContext?.primaryGameplaySkill ?? '').trim();
+  if (fromState && fromState !== 'unset') return fromState;
+
+  const tree = readJson(root, 'docs/atom-tree.json');
+  const items = tree?.meta?.skillsMatch?.items ?? [];
+  const gameplay =
+    items.find((i) => (i.role ?? []).some((r) => /gameplay|core|mechanic/i.test(String(r)))) ??
+    items.find((i) => String(i.atomId ?? '').includes('.aigameplay')) ??
+    items[0];
+  return String(gameplay?.atomId ?? '').trim() || null;
+}
+
+/** @param {string} fromRoot */
+function monorepoSkillCandidates(fromRoot, skillId) {
+  const roots = [
+    join(fromRoot, '.claude/skills', skillId),
+    join(fromRoot, 'skills', skillId),
+    join(fromRoot, 'node_modules/@playcraft/skills/skills', skillId),
+    join(fromRoot, '../../../skills/skills', skillId),
+    join(fromRoot, '../../../../skills/skills', skillId),
+    join(fromRoot, '../../../../../skills/skills', skillId),
+  ];
+  const envRoot = String(process.env.PLAYCRAFT_SKILLS_ROOT ?? '').trim();
+  if (envRoot) roots.unshift(join(envRoot, skillId));
+  return roots;
+}
+
+/** @param {string} root @param {string} skillId */
+export function resolveSkillPackageDir(root, skillId) {
+  if (!skillId) return null;
+  for (const dir of monorepoSkillCandidates(root, skillId)) {
+    if (existsSync(join(dir, 'SKILL.md'))) return dir;
+  }
+  return null;
+}
+
+/** @param {string} text */
+function extractPayoffBlob(text) {
+  const section = text.match(/##\s*0[\s\S]*?(?=\n##\s|$)/i)?.[0] ?? text;
+  const payoff =
+    section.match(/\*\*Payoff image\*\*:\s*(.+)/i)?.[1] ??
+    section.match(/\*\*Payoff\*\*:\s*(.+)/i)?.[1] ??
+    '';
+  return payoff;
+}
+
+const ROTATE_CORE_RE =
+  /(?:rotate|rotation|rotating|clockwise|counter-?clockwise|90\s*°|90\s*度|顺时针|逆时针|旋转(?:瞄准|箭头|方向)?(?:作为|为核心|为主|核心操作|主要操作))/i;
+
+const PGS_REQUIRED_GROUPS = [
+  {
+    id: 'path',
+    label: 'path tap / click',
+    re: /path|路径|pathclick|path_click|点击路径|点路径|折线/i,
+  },
+  {
+    id: 'slide',
+    label: 'slide out',
+    re: /slide\s*out|slide_out|滑出|推出|沿方向滑/i,
+  },
+  {
+    id: 'tray',
+    label: 'tray / fly to tray',
+    re: /tray|托盘|fly\s*to\s*tray|flytotray|飞入.*托|篮子/i,
+  },
+];
+
+const PAYOFF_SLIDE_TRAY_RE = /slide|滑出|推出|tray|托盘|飞入|篮子|burst|爆/i;
+const CASCADE_ONLY_PAYOFF_RE = /(?:board|棋盘).{0,40}(?:cascade|连锁|清盘)|(?:cascade|连锁).{0,40}(?:board|棋盘)/i;
+
+/** @param {string} blob @param {string} scope */
+function missingPgsGroups(blob, scope) {
+  const missing = [];
+  for (const g of PGS_REQUIRED_GROUPS) {
+    if (!g.re.test(blob)) missing.push(`${scope}: missing ${g.label}`);
+  }
+  return missing;
+}
+
+/**
+ * @param {string} root
+ * @param {{ design?: string, northStarMd?: string, handoffContext?: object, payoffOnly?: boolean }} [opts]
+ */
+export function validateSkillFidelity(root, opts = {}) {
+  const driftReasons = [];
+  const primarySkillId = resolvePrimarySkillId(root, opts.handoffContext ?? {});
+  if (!primarySkillId) {
+    return { pass: true, primarySkillId: null, driftReasons: [], skipped: true, reason: 'no primary skill' };
+  }
+
+  const skillDir = resolveSkillPackageDir(root, primarySkillId);
+  if (!skillDir) {
+    return {
+      pass: false,
+      primarySkillId,
+      driftReasons: [`skill package not found for ${primarySkillId}`],
+      skipped: false,
+    };
+  }
+
+  const design = opts.design ?? (existsSync(join(root, 'docs/DESIGN.md')) ? readFileSync(join(root, 'docs/DESIGN.md'), 'utf8') : '');
+  const northStarMd =
+    opts.northStarMd ??
+    (existsSync(join(root, 'docs/north-star.md')) ? readFileSync(join(root, 'docs/north-star.md'), 'utf8') : '');
+
+  const designBlob = design.toLowerCase();
+  const northBlob = northStarMd.toLowerCase();
+  const payoffBlob = extractPayoffBlob(northStarMd || design).toLowerCase();
+
+  driftReasons.push(...missingPgsGroups(designBlob, 'DESIGN'));
+  if (!opts.payoffOnly) {
+    driftReasons.push(...missingPgsGroups(northBlob, 'north-star'));
+  }
+
+  const coreActionSection =
+    design.match(/##\s*7[\s\S]*?(?=\n##\s|$)/i)?.[0] ??
+    design.match(/##\s*1[\s\S]*?(?=\n##\s|$)/i)?.[0] ??
+    design;
+
+  if (ROTATE_CORE_RE.test(coreActionSection)) {
+    driftReasons.push('DESIGN: rotate / clockwise rotation appears as core player action (PGS drift)');
+  }
+
+  if (payoffBlob) {
+    if (!PAYOFF_SLIDE_TRAY_RE.test(payoffBlob)) {
+      driftReasons.push('Payoff: must reference slide-out or tray moment (not abstract only)');
+    }
+    if (CASCADE_ONLY_PAYOFF_RE.test(payoffBlob) && !PAYOFF_SLIDE_TRAY_RE.test(payoffBlob)) {
+      driftReasons.push('Payoff: board cascade alone does not satisfy tray/slide payoff for arrow_pick_match PGS');
+    }
+  } else if (!opts.payoffOnly) {
+    driftReasons.push('Payoff: missing Payoff image field for PGS fidelity check');
+  }
+
+  const pgsPath = join(skillDir, 'ref/pgs-schema.json');
+  if (existsSync(pgsPath)) {
+    try {
+      const pgs = JSON.parse(readFileSync(pgsPath, 'utf8'));
+      const gameplayType = String(pgs.gameplayType ?? '');
+      if (gameplayType === 'arrow_pick_match' && ROTATE_CORE_RE.test(designBlob)) {
+        if (!driftReasons.some((d) => d.includes('rotate'))) {
+          driftReasons.push('DESIGN: rotate-as-core conflicts with arrow_pick_match PGS (tap path → slide → tray)');
+        }
+      }
+    } catch {
+      driftReasons.push(`PGS schema parse failed: ${pgsPath}`);
+    }
+  }
+
+  return {
+    pass: driftReasons.length === 0,
+    primarySkillId,
+    driftReasons,
+    skipped: false,
+    skillDir,
+  };
+}

package/project-template/skills/_shared/scripts/slice-set.mjs

@@ -14,7 +14,13 @@
  * See docs/harness/slice-axis-design.md.
  */
 import { resolve } from 'node:path';
-import { getActiveSlice, readState, updateActiveSlice } from './state-store.mjs';
+import {
+  applyStateUpdates,
+  flatHandoff,
+  getActiveSlice,
+  readState,
+  updateActiveSlice,
+} from './state-store.mjs';
 import { validateBuildArtifactForSlice } from '../../playable-record/scripts/lib/build-artifact.mjs';
 
 function parseArgs(argv) {
@@ -71,7 +77,28 @@ function main() {
   if (slice.verification.length) console.log(`  verification: ${slice.verification[slice.verification.length - 1]}`);
   if (slice.routeTo) console.log(`  routeTo: ${slice.routeTo.role} — ${slice.routeTo.reason}`);
   if (promotedTo) console.log(`  ✓ auto-promoted: activeSliceId now ${promotedTo}`);
-  else if (slice.status === 'verified') console.log('  (no further slice to promote — queue drained)');
+  else if (slice.status === 'verified') {
+    console.log('  (no further slice to promote — queue drained)');
+    const state = readState(root);
+    const handoff = flatHandoff(state);
+    const iteration = Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
+    const ringGate = String(nullishValue(handoff.ringGate) || 'pending').toLowerCase();
+    if (iteration === 1 && ringGate === 'pending') {
+      applyStateUpdates(root, {
+        loop: 'verify',
+        next_orchestrator_action: `npm run ring:gate -- --iteration ${iteration}`,
+        waiting_for: 'orchestrator',
+        subagent_stop: 'false',
+      });
+      console.log(`  ✓ handoff updated: loop=verify, next_orchestrator_action=ring:gate --iteration ${iteration}`);
+    }
+  }
+}
+
+function nullishValue(value) {
+  if (value == null) return null;
+  const s = String(value).trim().toLowerCase();
+  return s === '' || s === 'null' || s === 'none' ? null : value;
 }
 
 main();

package/project-template/skills/_shared/scripts/state-get.mjs

@@ -10,12 +10,24 @@
  *   node skills/_shared/scripts/state-get.mjs --root=. --json iteration loop
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+
 import { DOD_LABELS, parseRingDoDFlow, ringDoDKeysForIteration } from './ring-config.mjs';
 import {
   disclosureForProjectState,
   recommendedActionForDispatch,
 } from './disclosure-config.mjs';
-import { flatHandoff, getActiveSlice, readState, serializeRingDoD, serializeArchivedRings, stateExists } from './state-store.mjs';
+import {
+  evaluateSliceQueueForRingGate,
+  flatHandoff,
+  getActiveSlice,
+  readState,
+  serializeRingDoD,
+  serializeArchivedRings,
+  stateExists,
+  normalizeRequiredContext,
+} from './state-store.mjs';
 
 function nullishValue(value) {
   if (value == null) return null;
@@ -40,11 +52,25 @@ function parseArgs(argv) {
   return opts;
 }
 
+function isRingGatePending(handoff, state) {
+  const ringGate = String(nullishValue(handoff.ringGate) || 'pending').toLowerCase();
+  if (ringGate === 'passed') return false;
+  const verdict = String(state.ringGateRunner?.ringGateVerdict || '').toLowerCase();
+  return verdict !== 'pass';
+}
+
+function shouldRouteRingGate({ handoff, state }) {
+  if (!isRingGatePending(handoff, state)) return false;
+  const ss = state.sliceState || {};
+  if (ss.activeSliceId && ss.activeSliceId !== 'none') return false;
+  const gate = evaluateSliceQueueForRingGate(ss);
+  return gate.applicable && gate.ok;
+}
+
 function recommendedNextAction({ handoff, state, disclosure, iteration, dispatchPacket }) {
   if (dispatchPacket) {
     return recommendedActionForDispatch(dispatchPacket);
   }
-  const explicit = nullishValue(handoff.next_orchestrator_action);
   const runner = state.ringGateRunner || {};
   const routeTo = nullishValue(runner.ringGateRouteTo);
   const canAsk = String(runner.ringGateCanAskUser || '').toLowerCase() === 'yes';
@@ -54,16 +80,24 @@ function recommendedNextAction({ handoff, state, disclosure, iteration, dispatch
   if (verdict === 'fail' && routeTo) {
     return `Route ring gate failure to ${routeTo}: ${runner.ringGateFailReason || 'see ring:gate output'}`;
   }
+  if (shouldRouteRingGate({ handoff, state })) {
+    return `npm run ring:gate -- --iteration ${iteration}`;
+  }
+  const explicit = nullishValue(handoff.next_orchestrator_action);
   if (explicit) return explicit;
   return disclosure.nextCommands?.[0] ?? null;
 }
 
+function requiredContextMustRead(requiredContext) {
+  return normalizeRequiredContext(requiredContext).mustRead;
+}
+
 function buildContextPacket({ state, disclosure, iteration, loop, dispatchPacket }) {
   const context = state.handoffContext || {};
   const nextRole = context.nextRole || {};
   const dispatchRequired = dispatchPacket
     ? [
-        ...(Array.isArray(dispatchPacket.requiredContext) ? dispatchPacket.requiredContext : []),
+        ...requiredContextMustRead(dispatchPacket.requiredContext),
         ...(Array.isArray(dispatchPacket.allowedFiles) ? dispatchPacket.allowedFiles : []),
       ]
     : [];
@@ -111,9 +145,79 @@ function buildContextPacket({ state, disclosure, iteration, loop, dispatchPacket
  * single dispatch entry — agents read this instead of inferring ring/loop scope.
  * Returns null when no slice is active (harness falls back to ring:loop disclosure).
  */
-function buildDispatchPacket(state) {
+function readAtomTreeDisclosure(root) {
+  const jsonPath = path.join(path.resolve(root), 'docs', 'atom-tree.json');
+  if (!fs.existsSync(jsonPath)) {
+    return {
+      mustRead: [],
+      atomTreeFocus: null,
+      selectedAtoms: [],
+    };
+  }
+  try {
+    const tree = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    const selectedAtoms = Array.isArray(tree?.meta?.selectedAtoms)
+      ? tree.meta.selectedAtoms
+        .map((atom) => (typeof atom === 'string' ? atom.trim() : ''))
+        .filter((atom) => atom && !atom.startsWith('{{') && !atom.startsWith('playcraft-'))
+      : [];
+    return {
+      mustRead: [
+        'docs/atom-tree.json',
+        ...selectedAtoms.map((atom) => `.claude/skills/${atom}/SKILL.md`),
+      ],
+      atomTreeFocus: {
+        readFields: [
+          'meta.engineDecision',
+          'meta.selectedAtoms',
+          'meta.skillsMatch.mediaGroups',
+          'meta.rings',
+        ],
+        selectedAtomsPolicy: 'read-all-selected-skills-before-game-edit',
+        selectedAtoms,
+        sliceSkillRefsPolicy: 'skillRefs narrow implementation focus; selectedAtoms remain mandatory preflight context',
+      },
+      selectedAtoms,
+    };
+  } catch {
+    return {
+      mustRead: ['docs/atom-tree.json'],
+      atomTreeFocus: {
+        readFields: ['meta.engineDecision', 'meta.selectedAtoms', 'meta.skillsMatch.mediaGroups', 'meta.rings'],
+        selectedAtomsPolicy: 'read-all-selected-skills-before-game-edit',
+        selectedAtoms: [],
+        parseError: true,
+      },
+      selectedAtoms: [],
+    };
+  }
+}
+
+function mergeRequiredContext(sliceContext, atomTreeDisclosure) {
+  const normalized = normalizeRequiredContext(sliceContext);
+  const atomTreeFocus = {
+    ...(atomTreeDisclosure.atomTreeFocus || {}),
+    ...(normalized.atomTreeFocus || {}),
+  };
+  return {
+    ...normalized,
+    mustRead: [
+      ...new Set([
+        ...atomTreeDisclosure.mustRead,
+        ...normalized.mustRead,
+      ]),
+    ],
+    atomTreeFocus: Object.keys(atomTreeFocus).length ? atomTreeFocus : null,
+  };
+}
+
+function buildDispatchPacket(state, { root = process.cwd() } = {}) {
   const active = getActiveSlice(state);
   if (!active) return null;
+  const atomTreeDisclosure = active.role === 'developer'
+    ? readAtomTreeDisclosure(root)
+    : { mustRead: [], atomTreeFocus: null, selectedAtoms: [] };
+  const requiredContext = mergeRequiredContext(active.requiredContext, atomTreeDisclosure);
   const queue = (state.sliceState.slices || []).map((s) => ({
     sliceId: s.sliceId,
     status: s.status,
@@ -125,11 +229,15 @@ function buildDispatchPacket(state) {
     doWhat: active.doWhat,
     flow: active.flow,
     hypothesis: active.hypothesis,
-    requiredContext: active.requiredContext,
+    requiredContext,
     allowedFiles: active.allowedFiles,
     forbiddenTasks: active.forbiddenTasks,
     acceptance: active.acceptance,
     evidenceTier: active.evidenceTier,
+    skillRefs: active.skillRefs,
+    skillUse: active.skillUse,
+    fromScratchReason: active.fromScratchReason,
+    selectedAtoms: atomTreeDisclosure.selectedAtoms,
     verifier: active.verifier,
     fallbackRoute: active.fallbackRoute,
     status: active.status,
@@ -149,8 +257,16 @@ function main() {
   const handoff = flatHandoff(state);
   const iteration = Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
   const loop = nullishValue(handoff.loop);
-  const dispatchPacket = buildDispatchPacket(state);
-  const disclosure = disclosureForProjectState({ iteration, loop, handoff, dispatchPacket });
+  const dispatchPacket = buildDispatchPacket(state, { root: opts.root });
+  const disclosure = disclosureForProjectState({
+    iteration,
+    loop,
+    handoff,
+    dispatchPacket,
+    sliceState: state.sliceState,
+    projectRoot: opts.root,
+    handoffContext: state.handoffContext || {},
+  });
   const ringDoD = parseRingDoDFlow(serializeRingDoD(state.ringDoD));
   const contextPacket = buildContextPacket({ state, disclosure, iteration, loop, dispatchPacket });
   const dev = state.devPreview || {};
@@ -170,6 +286,7 @@ function main() {
     nextRole: disclosure.nextRole,
     artifactRefs: disclosure.artifactRefs,
     requiredContextFields: disclosure.requiredContextFields,
+    referenceReads: disclosure.referenceReads || [],
     evidencePaths: disclosure.evidencePaths,
     contextPacket,
     currentRingVerifiers: ringDoDKeysForIteration(iteration, opts.root).map((key) => ({

package/project-template/skills/_shared/scripts/state-store.mjs

@@ -143,6 +143,7 @@ export function defaultState() {
         assetContractRefs: [],
       },
       openQuestions: [],
+      primaryGameplaySkill: 'unset',
     },
     ringArtifacts: {},
     archivedRings: {},
@@ -183,6 +184,26 @@ export function defaultState() {
   };
 }
 
+/** Default disclosure shape for one slice. */
+export function defaultRequiredContext() {
+  return {
+    mustRead: [],
+    atomTreeFocus: null,
+  };
+}
+
+export function normalizeRequiredContext(value) {
+  if (Array.isArray(value) || typeof value === 'string') {
+    return { ...defaultRequiredContext(), mustRead: parseStringList(value) };
+  }
+  if (!isPlainObject(value)) return defaultRequiredContext();
+  return {
+    ...value,
+    mustRead: parseStringList(value.mustRead),
+    recommendedRead: parseStringList(value.recommendedRead),
+  };
+}
+
 /** A single slice's full default shape (dispatchPacket fields + runtime state). */
 export function defaultSlice() {
   return {
@@ -191,7 +212,7 @@ export function defaultSlice() {
     doWhat: '',
     flow: 'implement',
     hypothesis: '',
-    requiredContext: [],
+    requiredContext: defaultRequiredContext(),
     allowedFiles: [],
     forbiddenTasks: [],
     acceptance: [],
@@ -291,7 +312,7 @@ export function normalizeSliceState(sliceState) {
     .filter((s) => isPlainObject(s) && String(s.sliceId || '').trim())
     .map((s) => {
       const slice = { ...defaultSlice(), ...s };
-      slice.requiredContext = parseStringList(slice.requiredContext);
+      slice.requiredContext = normalizeRequiredContext(slice.requiredContext);
       slice.allowedFiles = parseStringList(slice.allowedFiles);
       slice.forbiddenTasks = parseStringList(slice.forbiddenTasks);
       slice.acceptance = parseStringList(slice.acceptance);
@@ -625,6 +646,8 @@ export function applyStateUpdates(root, updates) {
       state.handoffContext.sharedDecisions.semanticPlaceholders = parseStringList(value);
     } else if (key === 'contextAssetContractRefs') {
       state.handoffContext.sharedDecisions.assetContractRefs = parseStringList(value);
+    } else if (key === 'contextPrimaryGameplaySkill' || key === 'primaryGameplaySkill') {
+      state.handoffContext.primaryGameplaySkill = value;
     } else {
       state.handoff[key] = value;
     }