@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/skills/_shared/scripts/render-project-state.mjs

@@ -0,0 +1,278 @@
+/**
+ * Deterministic JSON → markdown renderer for docs/project-state.md.
+ *
+ * The markdown is a GENERATED, read-only human view of docs/project-state.json
+ * (the machine source of truth). It is re-rendered after every write through
+ * state-store.mjs. The `## Agent handoff` YAML block is reproduced in the exact
+ * shape the workflow parsers expect (gate-runner / workflow-doctor /
+ * validate-workflow-stop), and the Dev Preview / Ring Gate Runner / Progress
+ * Checkpoint / Production Pipeline / File Index tables are ALWAYS emitted so STOP
+ * hooks never silently no-op on a missing table row.
+ *
+ * See docs/harness/experiment-lessons.md §9.1.
+ */
+
+import { REVIEW_VERIFIERS, SCRIPT_VERIFIERS } from './ring-config.mjs';
+
+const GENERATED_BANNER =
+  '<!-- GENERATED — do not hand-edit. Source of truth: docs/project-state.json. ' +
+  'Read via `npm run state:get`, write via `npm run state:set` / `npm run ring:gate`. -->';
+
+const HANDOFF_KEY_ORDER = [
+  'iteration',
+  'ringGoal',
+  'loop',
+  'subagent',
+  'subagent_stop',
+  'waiting_for',
+  'ringGate',
+];
+
+function ser(value) {
+  if (value == null) return 'null';
+  return String(value);
+}
+
+function serializeRingDoD(ringDoD) {
+  const pairs = Object.entries(ringDoD || {}).map(([k, v]) => `${k}: ${v}`);
+  return `{ ${pairs.join(', ')} }`;
+}
+
+function serializeArchivedRings(archived) {
+  const entries = Object.entries(archived || {});
+  if (entries.length === 0) return '{}';
+  const body = entries.map(([ring, dod]) => `${ring}: ${serializeRingDoD(dod)}`).join(', ');
+  return `{ ${body} }`;
+}
+
+function renderHandoffYaml(state) {
+  const h = state.handoff || {};
+  const lines = [];
+  for (const key of HANDOFF_KEY_ORDER) {
+    lines.push(`${key}: ${ser(h[key])}`);
+  }
+  lines.push(`ringDoD: ${serializeRingDoD(state.ringDoD)}`);
+  lines.push(`archivedRings: ${serializeArchivedRings(state.archivedRings)}`);
+  lines.push(`next_orchestrator_action: ${ser(h.next_orchestrator_action)}`);
+  lines.push(`last_completed_by: ${ser(h.last_completed_by)}`);
+  lines.push(`block_reason: ${ser(h.block_reason)}`);
+  return lines.join('\n');
+}
+
+/**
+ * The DoD key is NOT the npm script name (e.g. firstLevelWin → verify:firstwin,
+ * visualDiff → verify:visual, bgClean → verify:bg-clean), and review-backed gates
+ * (gameplayConformance / uiDiff / hookCta) have no script at all. Resolve the
+ * real verifier from the ring-config maps so the generated doc never tells the
+ * reader to run a command that does not exist.
+ */
+function verifierForKey(key) {
+  if (key in SCRIPT_VERIFIERS) return `\`npm run ${SCRIPT_VERIFIERS[key]}\``;
+  if (key in REVIEW_VERIFIERS) return `Reviewer (${REVIEW_VERIFIERS[key].mode})`;
+  return '—';
+}
+
+function renderRingDoDTable(state) {
+  const rows = Object.entries(state.ringDoD || {})
+    .map(([key, status]) => `| ${key} | ${status} | ${verifierForKey(key)} |`)
+    .join('\n');
+  return `## Ring DoD (current iteration)
+
+> Objective Definition-of-Done for the current growth ring. Machine source of truth is \`ringDoD:\` in the \`## Agent handoff\` block.
+
+| Check | Status | Verifier |
+| ----- | ------ | -------- |
+${rows}`;
+}
+
+function renderDevPreview(state) {
+  const d = state.devPreview || {};
+  const blockers =
+    Array.isArray(d.devBlockers) && d.devBlockers.length > 0 ? d.devBlockers.join('; ') : 'none';
+  return `## Dev Preview
+
+> Written programmatically by \`npm run dev:start\` (devUrl) and \`npm run state:set\`. Do not hand-edit.
+
+| Field | Value |
+| ----- | ----- |
+| devStatus | ${ser(d.devStatus)} |
+| devUrl | ${ser(d.devUrl)} |
+| devStartedBy | ${ser(d.devStartedBy)} |
+| devLastChecked | ${ser(d.devLastChecked)} |
+| loadCheck | ${ser(d.loadCheck)} |
+| loadCheckNotes | ${ser(d.loadCheckNotes)} |
+| uiReviewStatus | ${ser(d.uiReviewStatus)} |
+| uiDiffNotes | ${ser(d.uiDiffNotes)} |
+| uiReworkRound | ${ser(d.uiReworkRound)} |
+| devBlockers | ${blockers} |`;
+}
+
+function listItems(items) {
+  if (!Array.isArray(items) || items.length === 0) return 'none';
+  return items.map((item) => `\`${ser(item)}\``).join(', ');
+}
+
+function renderHandoffContext(state) {
+  const c = state.handoffContext || {};
+  const ring = c.ring || {};
+  const last = c.lastRole || {};
+  const next = c.nextRole || {};
+  const shared = c.sharedDecisions || {};
+  return `## Handoff Context
+
+> Structured shared working memory. Machine source of truth is \`handoffContext\` in \`docs/project-state.json\`; agents should read it through \`npm run state:get -- --json contextPacket\`.
+
+| Area | Value |
+| ---- | ----- |
+| ring.summary | ${ser(ring.summary)} |
+| ring.goal | ${ser(ring.goal)} |
+| ring.passedDoD | ${listItems(ring.passedDoD)} |
+| lastRole.role | ${ser(last.role)} |
+| lastRole.summary | ${ser(last.summary)} |
+| lastRole.artifactRefs | ${listItems(last.artifactRefs)} |
+| lastRole.validation | ${listItems(last.validation)} |
+| lastRole.blockers | ${listItems(last.blockers)} |
+| nextRole.role | ${ser(next.role)} |
+| nextRole.mustKnow | ${listItems(next.mustKnow)} |
+| nextRole.requiredFiles | ${listItems(next.requiredFiles)} |
+| nextRole.forbiddenFiles | ${listItems(next.forbiddenFiles)} |
+| shared.engine | ${ser(shared.engine)} |
+| shared.coreAction | ${ser(shared.coreAction)} |
+| shared.semanticPlaceholders | ${listItems(shared.semanticPlaceholders)} |
+| shared.assetContractRefs | ${listItems(shared.assetContractRefs)} |
+| openQuestions | ${listItems(c.openQuestions)} |`;
+}
+
+function renderRingGateRunner(state) {
+  const r = state.ringGateRunner || {};
+  return `## Ring Gate Runner
+
+> Written by \`npm run ring:gate\`. Do not hand-edit.
+
+| Field | Value |
+| ----- | ----- |
+| ringGateCurrent | ${ser(r.ringGateCurrent)} |
+| ringGateVerdict | ${ser(r.ringGateVerdict)} |
+| ringGateCheckedAt | ${ser(r.ringGateCheckedAt)} |
+| ringGateBlockingIssues | ${ser(r.ringGateBlockingIssues)} |
+| ringGateCanAskUser | ${ser(r.ringGateCanAskUser)} |
+| ringGateRouteTo | ${ser(r.ringGateRouteTo)} |
+| ringGateFailReason | ${ser(r.ringGateFailReason)} |
+| ringGateNonRegression | ${ser(r.ringGateNonRegression)} |`;
+}
+
+function renderProgressCheckpoint(state) {
+  const rows = (state.progressCheckpoint || [])
+    .map((c) => `| ${ser(c.at)} | ${ser(c.by)} | ${ser(c.iteration)} | ${ser(c.loop)} | ${ser(c.note)} |`)
+    .join('\n');
+  const body = rows || '| _no checkpoints yet_ |  |  |  |  |';
+  return `## Progress Checkpoint
+
+> Appended programmatically by STOP hooks / \`npm run state:set\`. Do not hand-edit.
+
+| At | By | Iteration | Loop | Note |
+| -- | -- | --------- | ---- | ---- |
+${body}`;
+}
+
+function renderProductionPipeline(state) {
+  const waves = state.productionPipeline?.waves || [];
+  const rows = waves
+    .map((w) => `| ${ser(w.id)} | ${ser(w.owner)} | ${ser(w.status)} | ${ser(w.notes)} |`)
+    .join('\n');
+  const body = rows || '| _no waves_ |  |  |  |';
+  return `## Production Pipeline
+
+> Set via \`npm run state:set\` structured wave updates. Do not hand-edit.
+
+| Wave | Owner | Status | Notes |
+| ---- | ----- | ------ | ----- |
+${body}`;
+}
+
+function renderFileIndex(state) {
+  const rows = (state.fileIndex || [])
+    .map((f) => `| ${ser(f.file)} | ${ser(f.description)} | ${ser(f.status)} |`)
+    .join('\n');
+  const body =
+    rows ||
+    '| [DESIGN.md](docs/DESIGN.md) | Player experience contract | pending |';
+  return `## File Index (current ring)
+
+| File | Description | Status |
+| ---- | ----------- | ------ |
+${body}`;
+}
+
+/**
+ * Render a full docs/project-state.md from a normalized state object.
+ * @param {object} state
+ * @returns {string}
+ */
+export function renderProjectState(state) {
+  const h = state.handoff || {};
+  const designerAutoDecide = state.settings?.designerAutoDecide ? 'true' : 'false';
+  const userIntent = state.userIntent && !/\{\{/.test(state.userIntent) ? state.userIntent : '{{user intent — ≤2 sentences}}';
+
+  return `# Project State
+
+${GENERATED_BANNER}
+
+> **Agent entry**: run \`npm run state:get\` first. Do **not** hand-edit this file — it is generated from \`docs/project-state.json\`. Write via \`npm run state:set\` / \`npm run ring:gate\` / STOP hooks.
+
+## Workflow spec
+
+| Field | Value |
+| ----- | ----- |
+| **templateVersion** | \`${ser(state.templateVersion)}\` |
+| **workflowSpecVersion** | \`${ser(state.workflowSpecVersion)}\` |
+
+## Settings
+
+| Field | Value |
+| ----- | ----- |
+| **designerAutoDecide** | \`${designerAutoDecide}\` |
+| selectedMcOption | ${ser(state.selectedMcOption)} |
+| assetMappingLocked | ${state.assetMappingLocked ? 'true' : 'false'} |
+
+## User Intent
+
+> ${userIntent}
+
+## Current Iteration
+
+**Iteration ${ser(h.iteration)}** — ${ser(h.ringGoal)}
+
+\`1 (engine-root → core gameplay)\` → \`2 (gameplay + periphery)\` → \`3 (playable ad hook/CTA)\` → \`4 (production + architecture)\` → \`done\`
+
+${renderRingDoDTable(state)}
+
+## Ring Gate
+
+| Field | Value |
+| ----- | ----- |
+| ringGate | ${ser(h.ringGate)} |
+| iteration | ${ser(h.iteration)} |
+| canAskUser | ${ser(state.ringGateRunner?.ringGateCanAskUser)} |
+
+${renderRingGateRunner(state)}
+
+${renderDevPreview(state)}
+
+${renderHandoffContext(state)}
+
+## Agent handoff
+
+> Machine source of truth lives in \`docs/project-state.json\`; this block is rendered for human + parser compatibility.
+
+\`\`\`yaml
+${renderHandoffYaml(state)}
+\`\`\`
+
+${renderProgressCheckpoint(state)}
+
+${renderProductionPipeline(state)}
+
+${renderFileIndex(state)}
+`;
+}

package/project-templates/phaser/skills/_shared/scripts/ring-config.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Growth-ring configuration — shared by ring-gate runner and workflow-doctor.
+ *
+ * slice-axis-v1 (Knife 9): `ring:gate` is an **outer** budget / non-regression /
+ * user-acceptance boundary. When `sliceState.slices[]` is non-empty, gate-runner
+ * injects a `sliceQueue` aggregation check — it does **not** replace per-slice
+ * verifiers (`verify:slice`, `verify:slice-artist`, `verify:slice-ta`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const WORKFLOW_SPEC = 'growth-rings-v1';
+
+export const LOOPS = ['clarify', 'build', 'verify'];
+
+export const RING_GOALS = {
+  1: 'engine-root + core gameplay (placeholder art)',
+  2: 'gameplay + periphery (HUD / flow skeleton)',
+  3: 'playable ad hook/CTA + style direction lock',
+  4: 'production + architecture (assetMapping freeze)',
+};
+
+/** DoD checks active per ring (prior ring checks remain via non-regression). */
+export const RING_DOD_BY_ITERATION = {
+  1: ['contract', 'lifecycle', 'firstLevelWin', 'placeholders'],
+  2: ['contract', 'lifecycle', 'ring2Visual', 'vlmVideo', 'oneClickEndcard', 'firstLevelWin', 'verifyUi', 'fullPlaythrough', 'gameplayConformance', 'placeholders', 'fusion'],
+  3: ['contract', 'lifecycle', 'ring2Visual', 'ring3Visual', 'vlmVideo', 'oneClickEndcard', 'firstLevelWin', 'verifyUi', 'fullPlaythrough', 'gameplayConformance', 'hookCta', 'placeholders', 'fusion'],
+  4: [
+    'contract',
+    'lifecycle',
+    'oneClickEndcard',
+    'firstLevelWin',
+    'verifyUi',
+    'fullPlaythrough',
+    'gameplayConformance',
+    'hookCta',
+    'vlmVideo',
+    'uiDiff',
+    'visualDiff',
+    'bgClean',
+    'tileConsistency',
+    'textOverlap',
+    'assetBudget',
+    'assetReview',
+    'assetCodeSync',
+    'atomConformance',
+    'fusion',
+  ],
+};
+
+/** Script-backed verifiers: key → npm script name */
+export const SCRIPT_VERIFIERS = {
+  contract: 'verify:contract',
+  lifecycle: 'verify:lifecycle',
+  firstLevelWin: 'verify:firstwin',
+  placeholders: 'verify:placeholders',
+  fusion: 'verify:fusion',
+  ring1Visual: 'verify:visual-ring1',
+  ring2Visual: 'verify:visual-ring2',
+  ring3Visual: 'verify:visual-ring3',
+  vlmVideo: 'verify:vlm-video',
+  oneClickEndcard: 'record:mp4',
+  verifyUi: 'verify:ui',
+  fullPlaythrough: 'record:mp4',
+  assetBudget: 'verify:ui:assets',
+  visualDiff: 'verify:visual',
+  bgClean: 'verify:bg-clean',
+  tileConsistency: 'verify:tile-consistency',
+  textOverlap: 'verify:text-overlap',
+  assetReview: 'verify:asset-review',
+  assetCodeSync: 'verify:asset-code-sync',
+  atomConformance: 'verify:atom-conformance',
+};
+
+/** Review-backed verifiers: key → review-report field */
+export const REVIEW_VERIFIERS = {
+  gameplayConformance: { mode: 'gameplay_conformance', field: 'gameplayConformance' },
+  hookCta: { mode: 'playable_validate', field: 'hookCta' },
+  uiDiff: { mode: 'ui_diff', field: 'uiDiff' },
+};
+
+export const DOD_LABELS = {
+  contract: 'verify:contract',
+  lifecycle: 'verify:lifecycle (HOOK → autoPlay → ENDCARD)',
+  oneClickEndcard: 'record:mp4 → ENDCARD',
+  firstLevelWin: 'verify:firstwin (headless autoPlay → ENDCARD)',
+  placeholders: 'verify:placeholders (load paths exist + assets/images non-empty)',
+  fusion: 'verify:fusion (≥2 aigameplay → both mechanics wired; otherwise no-op PASS)',
+  ring1Visual: 'verify:visual-ring1 (autoplay MP4 + CV frames in validate/ring1/)',
+  ring2Visual: 'verify:visual-ring2 (autoplay MP4 in validate/ring2/)',
+  ring3Visual: 'verify:visual-ring3 (autoplay MP4 in validate/ring3/)',
+  vlmVideo: 'verify:vlm-video (VLM semantic review of autoplay MP4)',
+  verifyUi: 'verify:ui',
+  fullPlaythrough: 'record:mp4 full session',
+  gameplayConformance: 'Reviewer gameplay_conformance (DESIGN drift + Skill usage + playwright path reachability)',
+  hookCta: 'playable_validate + hook/CTA scan',
+  uiDiff: 'Reviewer ui_diff (structured visual rubric)',
+  visualDiff: 'verify:visual (objective histogram/SSIM)',
+  bgClean: 'verify:bg-clean (background plate purity)',
+  tileConsistency: 'verify:tile-consistency (tile silhouette)',
+  textOverlap: 'verify:text-overlap (CTA text overlap)',
+  assetCodeSync: 'verify:asset-code-sync (manifest ↔ code wiring)',
+  assetBudget: 'verify:ui:assets',
+  assetReview: 'verify:asset-review (strict processed asset evidence)',
+  atomConformance: 'verify:atom-conformance',
+  sliceQueue:
+    'slice queue terminal (all slices verified or failed+routed; ring:gate does not replace verify:slice)',
+};
+
+export const DOD_ROUTES = {
+  contract: { routeTo: 'developer', nextAction: 'Re-invoke @developer for runtime contract fixes' },
+  lifecycle: { routeTo: 'developer', nextAction: 'Re-invoke @developer for lifecycle fixes' },
+  oneClickEndcard: { routeTo: 'developer', nextAction: 'Re-invoke @developer for one-click endcard fixes' },
+  firstLevelWin: { routeTo: 'developer', nextAction: 'Re-invoke @developer for first-level win fixes' },
+  placeholders: { routeTo: 'developer', nextAction: 'Re-invoke @developer for placeholder materialization fixes' },
+  fusion: { routeTo: 'developer', nextAction: 'Re-invoke @developer for gameplay fusion fixes' },
+  ring1Visual: { routeTo: 'developer', nextAction: 'Re-invoke @developer for Ring 1 visual / autoplay artifact fixes' },
+  ring2Visual: { routeTo: 'developer', nextAction: 'Re-invoke @developer for Ring 2 autoplay MP4 artifact fixes' },
+  ring3Visual: { routeTo: 'developer', nextAction: 'Re-invoke @developer for Ring 3 autoplay MP4 artifact fixes' },
+  vlmVideo: { routeTo: 'technical-artist', nextAction: 'Inspect validate/ringN/vlm-video.json and invoke the recommended skill for each finding' },
+  verifyUi: { routeTo: 'developer', nextAction: 'Re-invoke @developer for UI/layout verifier fixes' },
+  fullPlaythrough: { routeTo: 'developer', nextAction: 'Re-invoke @developer for full playthrough fixes' },
+  gameplayConformance: { routeTo: 'reviewer', nextAction: 'Re-invoke @reviewer gameplay_conformance after fixing review evidence' },
+  hookCta: { routeTo: 'reviewer', nextAction: 'Re-invoke @reviewer playable_validate after fixing hook/CTA evidence' },
+  uiDiff: { routeTo: 'reviewer', nextAction: 'Re-invoke @reviewer ui_diff after routed visual fixes' },
+  visualDiff: { routeTo: 'technical-artist', nextAction: 'Invoke routed visual owner, then @reviewer ui_diff' },
+  bgClean: { routeTo: 'technical-artist', nextAction: 'Invoke @technical-artist for background cleanup, then @developer integration' },
+  tileConsistency: { routeTo: 'technical-artist', nextAction: 'Invoke @technical-artist for tile consistency fixes, then @developer integration' },
+  textOverlap: { routeTo: 'developer', nextAction: 'Re-invoke @developer for text overlap fixes' },
+  assetBudget: { routeTo: 'technical-artist', nextAction: 'Invoke @technical-artist for asset budget fixes, then @developer integration' },
+  assetReview: { routeTo: 'technical-artist', nextAction: 'Invoke @technical-artist for processed asset review fixes, then rerun verify:asset-review' },
+  assetCodeSync: { routeTo: 'developer', nextAction: 'Re-invoke @developer for asset/code sync fixes' },
+  atomConformance: { routeTo: 'developer', nextAction: 'Re-invoke @developer for atom conformance fixes' },
+  sliceQueue: {
+    routeTo: 'developer',
+    nextAction:
+      'Resolve pending slices via per-slice verifiers + slice:set before rerunning npm run ring:gate',
+  },
+  nonRegression: { routeTo: 'none', nextAction: 'Resolve archivedRings non-regression before rerunning ring:gate' },
+};
+
+export const ROUTE_PRIORITY = ['game-designer', 'technical-artist', 'artist', 'developer', 'reviewer', 'none'];
+
+export function reviewDoDKeysForRing(iteration) {
+  const n = normalizeIteration(iteration) || 1;
+  const active = RING_DOD_BY_ITERATION[n] || [];
+  return active.filter((key) => key in REVIEW_VERIFIERS);
+}
+
+export function scriptDoDKeysForRing(iteration) {
+  const n = normalizeIteration(iteration) || 1;
+  const active = RING_DOD_BY_ITERATION[n] || [];
+  return active.filter((key) => key in SCRIPT_VERIFIERS);
+}
+
+export function ringDoDKeysForIteration(iteration, projectDir = process.cwd()) {
+  const n = normalizeIteration(iteration) || 1;
+  const defaults = RING_DOD_BY_ITERATION[n] || [];
+  const atomTreePath = path.join(path.resolve(projectDir), 'docs/atom-tree.json');
+  if (!fs.existsSync(atomTreePath)) return defaults;
+  try {
+    const tree = JSON.parse(fs.readFileSync(atomTreePath, 'utf8'));
+    const ring = tree?.meta?.rings?.[String(n)];
+    const raw = Array.isArray(ring?.acceptanceKeys)
+      ? ring.acceptanceKeys
+      : Array.isArray(ring?.verifiers)
+        ? ring.verifiers
+        : [];
+    const known = raw.map((key) => String(key).trim()).filter((key) => key in DOD_LABELS);
+    if (known.length === 0) return defaults;
+    // Atom-tree may add project-specific acceptance keys, but it cannot remove
+    // harness baseline gates for any ring.
+    return [...new Set([...defaults, ...known])];
+  } catch {
+    return defaults;
+  }
+}
+
+export function reviewDoDKeysForProjectRing(iteration, projectDir = process.cwd()) {
+  return ringDoDKeysForIteration(iteration, projectDir).filter((key) => key in REVIEW_VERIFIERS);
+}
+
+export function scriptDoDKeysForProjectRing(iteration, projectDir = process.cwd()) {
+  return ringDoDKeysForIteration(iteration, projectDir).filter((key) => key in SCRIPT_VERIFIERS);
+}
+
+export function routeForDoDKey(key) {
+  return DOD_ROUTES[key] || { routeTo: 'developer', nextAction: `Re-invoke @developer for ${key} fixes` };
+}
+
+export function routeForFailedDoDKeys(keys) {
+  const failed = Array.isArray(keys) ? keys.filter(Boolean) : [];
+  if (failed.length === 0) {
+    return { routeTo: 'none', nextAction: 'none' };
+  }
+
+  const candidates = failed.map((key) => ({ key, ...routeForDoDKey(key) }));
+  candidates.sort(
+    (a, b) => ROUTE_PRIORITY.indexOf(a.routeTo) - ROUTE_PRIORITY.indexOf(b.routeTo),
+  );
+  const primary = candidates[0];
+  const owners = [...new Set(candidates.map((c) => c.routeTo).filter((r) => r !== 'none'))];
+  if (owners.length > 1) {
+    return {
+      routeTo: primary.routeTo,
+      nextAction: `Route failed gates (${failed.join(', ')}) to ${owners.join(' → ')}, then rerun npm run ring:gate`,
+    };
+  }
+  return { routeTo: primary.routeTo, nextAction: primary.nextAction };
+}
+
+export function normalizeIteration(raw) {
+  const n = Number.parseInt(String(raw ?? '').trim(), 10);
+  if (!Number.isFinite(n) || n < 1 || n > 4) return null;
+  return n;
+}
+
+export function isPassed(status) {
+  const s = String(status ?? '').trim().toLowerCase();
+  return s === 'passed' || s === 'pass';
+}
+
+export function parseRingDoDFlow(raw) {
+  const dod = {};
+  if (!raw) return dod;
+  const body = raw.replace(/^\{/, '').replace(/\}$/, '');
+  for (const pair of body.split(',')) {
+    const m = pair.match(/["']?([A-Za-z0-9_]+)["']?\s*:\s*([A-Za-z]+)/i);
+    if (!m) continue;
+    dod[m[1]] = m[2].toLowerCase();
+  }
+  return dod;
+}
+
+export function parseArchivedRingsFlow(raw) {
+  // archivedRings: { 1: { contract: passed, ... } } — simplified parser for flat archived snapshot
+  const archived = {};
+  if (!raw || raw === '{}') return archived;
+  // Match ring number blocks: "1: { contract: passed, ... }"
+  const ringRe = /(\d+)\s*:\s*\{([^}]*)\}/g;
+  let match;
+  while ((match = ringRe.exec(raw)) !== null) {
+    const ringNum = Number(match[1]);
+    archived[ringNum] = parseRingDoDFlow(`{${match[2]}}`);
+  }
+  return archived;
+}
+
+export function allDoDPassed(dod, keys) {
+  return keys.every((key) => isPassed(dod[key]));
+}