@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/seed-v2-world-tasks.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// Seed the world-building tasks from Builder #25's planning package
+// (idea_inbox 416-427), reviewed + adjusted with Lars and folded into V2.
+// Backed by task 1569 (source_ref V2-world-planning-1).
+//
+// Companion migration 172_v2_world_planning_seed.sql lands the 4 goals, 7
+// criteria, V2/V3 done_when text, +35 karma to #25, and the idea bookkeeping.
+// RUN THIS ONLY AFTER 172 has deployed — task creates resolve criterion_ids
+// by slug against the live criteria.
+//
+// This script handles:
+//   * 16 V2 world tasks + 6 V3 editor tasks + 2 GDS-V4 skill-fix tasks
+//   * each linked to its done-when criteria (criterion_ids, by slug)
+//   * the dependency spine (POST /tasks/:id/dependencies, after all exist)
+//   * promotion of ideas 425/426 to their GDS-V4 tasks
+//
+// Idempotent: POST /tasks resolves an existing source_ref to the original task
+// (200 idempotent), and dependency / criterion links are insert-if-absent.
+//
+// Usage:  node scripts/bongos/seed-v2-world-tasks.js [--dry-run]
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+const DRY = process.argv.includes('--dry-run');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Throttled call that backs off and retries on a per-session 429. Takes a thunk
+// that performs a single client call and resolves to { status, ok, data }.
+async function withRetry(fn) {
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const res = await fn();
+    if (res.status === 429) {
+      const wait = ((res.data && res.data.retry_after_seconds) || 15) + 1;
+      console.error(`      rate-limited; waiting ${wait}s…`);
+      await sleep(wait * 1000);
+      continue;
+    }
+    await sleep(350); // gentle inter-call throttle
+    return res;
+  }
+  return { status: 429, ok: false, data: { error: 'rate_limited_giveup' } };
+}
+
+// Engineering/server/editor/level work touches protected game code → Metic+.
+// Art runs in the open art-pipeline → default xenos (requires_rank omitted).
+// MOD1 edits the kernel module map → Archon.
+const TASKS = [
+  // =========================================================================
+  // V2 — LANE 1: engineering, shared format + client rendering (Metic+)
+  // =========================================================================
+  { ref: 'S1', version: 'V2', title: 'V2.W01 — Map-format spike: JSON schema + derived-collision rule',
+    description: 'Pin the map-file format: design the layered JSON shape (ground/decoration/objects/overlay + structures/warps/spawns) and the rule that derives collision from it. Deliver a `mapFormat` parse/validate stub + one fixture. Output feeds E1 (V2.W05). See criterion world-data.',
+    kind: 'spike', discipline: 'engineer', priority: 5, est_minutes: 150, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['world-data'], depends_on_refs: [] },
+
+  { ref: 'E1', version: 'V2', title: 'V2.W05 — mapFormat.js shared module (parse + derived collision)',
+    description: 'Build the shared `mapFormat` module both client and server read; retire the hand-mirrored map twins; ship a real `olympia.json` fixture. Per the S1 (V2.W01) spike. Criterion world-data.',
+    kind: 'feature', discipline: 'engineer', priority: 5, est_minutes: 300, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['world-data'], depends_on_refs: ['S1'] },
+
+  { ref: 'E2', version: 'V2', title: 'V2.W08 — WorldScene loads a map by id + camera follow',
+    description: 'Load a map by id (replace the hardcoded initial map); camera setBounds + startFollow so a map larger than the viewport scrolls. Depends on E1 (V2.W05). Criteria world-data, walk-olympia.',
+    kind: 'feature', discipline: 'engineer', priority: 5, est_minutes: 240, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['world-data', 'walk-olympia'], depends_on_refs: ['E1'] },
+
+  { ref: 'E3', version: 'V2', title: 'V2.W09 — depth render: foot-Y y-sort for objects + sprites',
+    description: '4-pass depth render with foot-Y y-sort (depth = base*1000 + footY) + an always-above overlay band; reconcile the interior-tile transforms. Depends on E2 (V2.W08). Criterion depth-sort.',
+    kind: 'feature', discipline: 'engineer', priority: 5, est_minutes: 240, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['depth-sort'], depends_on_refs: ['E2'] },
+
+  { ref: 'E4', version: 'V2', title: 'V2.W11 — structure registry + loader (the art↔engine contract)',
+    description: 'Structure registry: expand {kind,anchor,variant} into object/overlay/collision grids and render via E3. This defines the cell ids the Olympia art (A2, V2.W12) targets. Depends on E3 (V2.W09) + S2 (V2.W02). Criteria depth-sort, olympia-art-set.',
+    kind: 'feature', discipline: 'engineer', priority: 5, est_minutes: 360, manual_degree: 3,
+    credits_reward: 60, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['depth-sort', 'olympia-art-set'], depends_on_refs: ['E3', 'S2'] },
+
+  // =========================================================================
+  // V2 — LANE 2: engineering, server / networking — the warp (Metic+)
+  // =========================================================================
+  { ref: 'S4', version: 'V2', title: 'V2.W03 — warp-into-full-room spike: queue handoff at destination cap',
+    description: 'Design the hard case: warping into a destination map already at its 100-cap (graceful queue handoff). Output feeds E5 (V2.W10). Criterion connected-warps.',
+    kind: 'spike', discipline: 'engineer', priority: 4, est_minutes: 150, manual_degree: 3,
+    credits_reward: 30, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['connected-warps'], depends_on_refs: [] },
+
+  { ref: 'E5', version: 'V2', title: 'V2.W10 — per-map Colyseus rooms + warp join/leave + per-map queue',
+    description: 'One room instance per map; `mapId` in player state; warp join/leave moves players between rooms; per-map seating + queue (100-cap becomes per-map). Where the warp and "visible other players" become one system. Depends on E2 (V2.W08) + S4 (V2.W03). Criterion connected-warps.',
+    kind: 'feature', discipline: 'engineer', priority: 4, est_minutes: 240, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['connected-warps'], depends_on_refs: ['E2', 'S4'] },
+
+  // =========================================================================
+  // V2 — LANE 3: design / art assets (art-pipeline, open to any builder)
+  // =========================================================================
+  { ref: 'S2', version: 'V2', title: 'V2.W02 — multi-tile structure spike: slice the temple reference to 32×32',
+    description: 'Slice the Olympia temple reference into 32×32 `structures/` members; verify the seam row lines up and the 64-color palette holds. Informs E4 (V2.W11). Criterion olympia-art-set.',
+    kind: 'spike', discipline: 'artist', priority: 4, est_minutes: 180, manual_degree: 4,
+    credits_reward: 40, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: [] },
+
+  { ref: 'A0', version: 'V2', title: 'V2.W04 — ingest the 4 reference sheets + capture style rules',
+    description: 'Ingest the 4 reference sheets into `art/references/`; capture style rules via otb-feedback-capture (3/4 tilt, orange-tile roofs, marble tone, river/forest). Gates the rest of the art lane. Criterion olympia-art-set.',
+    kind: 'feature', discipline: 'artist', priority: 4, est_minutes: 90, manual_degree: 3,
+    credits_reward: 15, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: [] },
+
+  { ref: 'A1', version: 'V2', title: 'V2.W06 — terrain set: marble/flagstone, stone & cliff, water, forest, grass',
+    description: 'Terrain set as autotile families where they tile: marble plaza/flagstone, stone & cliff, river/water, forest + palm, grass variants. Depends on A0 (V2.W04). Criterion olympia-art-set.',
+    kind: 'feature', discipline: 'artist', priority: 4, est_minutes: 240, manual_degree: 4,
+    credits_reward: 40, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: ['A0'] },
+
+  { ref: 'A3', version: 'V2', title: 'V2.W07 — decor props: statues, altar-with-fire, amphorae, fountains',
+    description: 'Decor props: Zeus/Hera statues, altar-with-fire, amphorae, fountains. Depends on A0 (V2.W04). Criterion olympia-art-set.',
+    kind: 'feature', discipline: 'artist', priority: 4, est_minutes: 240, manual_degree: 4,
+    credits_reward: 40, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: ['A0'] },
+
+  { ref: 'A2', version: 'V2', title: 'V2.W12 — temple building kit: walls, columns, roof slopes, steps',
+    description: 'Temple kit (Pattern-B continuous illustrations sliced to the E4 structure registry): walls, columns/colonnade, orange-tile roof slopes, steps. Depends on A0 (V2.W04) + E4 (V2.W11). Criterion olympia-art-set.',
+    kind: 'feature', discipline: 'artist', priority: 4, est_minutes: 360, manual_degree: 4,
+    credits_reward: 60, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: ['A0', 'E4'] },
+
+  { ref: 'A4', version: 'V2', title: 'V2.W13 — atlas integration: pack members + autotile_xverify green',
+    description: 'build_tilesheet.py + build_atlas.py; confirm all members land in the packed atlas + manifest; `tests/autotile_xverify.mjs` stays green. Depends on A1 (V2.W06) + A2 (V2.W12) + A3 (V2.W07). Criterion olympia-art-set.',
+    kind: 'feature', discipline: 'artist', priority: 4, est_minutes: 120, manual_degree: 3,
+    credits_reward: 20, module_key: 'art-pipeline',
+    criterion_ids: ['olympia-art-set'], depends_on_refs: ['A1', 'A2', 'A3'] },
+
+  // =========================================================================
+  // V2 — LANE 4: design / level authoring + proof
+  // =========================================================================
+  { ref: 'M1', version: 'V2', title: 'V2.W14 — author the Olympia map by hand (temple district + Altis + plaza + stadium)',
+    description: 'Hand-author `public/assets/maps/olympia.json` (temple district + Altis grove + plaza + stadium frontage). The slice first becomes walkable here. Without the editor this is JSON by hand → Metic+. Depends on E4 (V2.W11) + A4 (V2.W13). Criterion walk-olympia.',
+    kind: 'feature', discipline: 'engineer', priority: 5, est_minutes: 240, manual_degree: 4,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['walk-olympia'], depends_on_refs: ['E4', 'A4'] },
+
+  { ref: 'M2', version: 'V2', title: 'V2.W15 — second connected map + warp (approach road → Olympia gate)',
+    description: 'A second connected map and the warp between it and Olympia (overworld approach tile → Olympia gate). Depends on M1 (V2.W14) + E5 (V2.W10). Criterion connected-warps.',
+    kind: 'feature', discipline: 'engineer', priority: 4, est_minutes: 180, manual_degree: 4,
+    credits_reward: 30, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['connected-warps'], depends_on_refs: ['M1', 'E5'] },
+
+  { ref: 'P1', version: 'V2', title: 'V2.W16 — stage, screenshot, score vs reference (before/after to docs/reviews/)',
+    description: 'Stage the slice via /builder-stage, screenshot, score the new tiles with otb-design-review against the reference, and land a before/after writeup in `docs/reviews/`. Depends on M1 (V2.W14). Criterion scored-vs-reference.',
+    kind: 'feature', discipline: 'artist', priority: 3, est_minutes: 120, manual_degree: 3,
+    credits_reward: 20, module_key: 'game',
+    criterion_ids: ['scored-vs-reference'], depends_on_refs: ['M1'] },
+
+  // =========================================================================
+  // V3 — map editor (deferred out of V2; depends on the V2 engine)
+  // =========================================================================
+  { ref: 'MOD1', version: 'V3', title: 'V3.W01 — extend the `game` module glob to cover public-editor/',
+    description: 'Kernel prep: extend the `game` module glob in `module-scope-map.js` to cover `public-editor/` (and confirm map data under `public/assets/maps/`). Gates editor task-authoring. Criterion map-editor.',
+    kind: 'infra', discipline: 'engineer', priority: 3, est_minutes: 90, manual_degree: 2,
+    credits_reward: 15, module_key: 'kernel', requires_rank: 'archon',
+    criterion_ids: ['map-editor'], depends_on_refs: [] },
+
+  { ref: 'S3', version: 'V3', title: 'V3.W02 — editor save-model spike: branch/PR vs download',
+    description: 'Decide how the editor saves: branch/PR via `github-push.js` vs download — NOT a live write to served `public/`. Output feeds ED4 (V3.W06). Criterion map-editor.',
+    kind: 'spike', discipline: 'engineer', priority: 3, est_minutes: 150, manual_degree: 3,
+    credits_reward: 30, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['map-editor'], depends_on_refs: [] },
+
+  { ref: 'ED1', version: 'V3', title: 'V3.W03 — editor scaffold: auth-gated, loads live atlas + renders a map grid',
+    description: 'Scaffold `public-editor/`, auth-gated; load the live atlas + manifest; render a map grid. Depends on E1 (V2.W05) + MOD1 (V3.W01). Criterion map-editor.',
+    kind: 'feature', discipline: 'engineer', priority: 3, est_minutes: 180, manual_degree: 3,
+    credits_reward: 30, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['map-editor'], depends_on_refs: ['E1', 'MOD1'] },
+
+  { ref: 'ED2', version: 'V3', title: 'V3.W04 — ground paint with live autotile preview',
+    description: 'Paint ground tiles with live autotile preview (imports the game picker — no new autotile code). Depends on ED1 (V3.W03). Criterion map-editor.',
+    kind: 'feature', discipline: 'engineer', priority: 2, est_minutes: 240, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['map-editor'], depends_on_refs: ['ED1'] },
+
+  { ref: 'ED3', version: 'V3', title: 'V3.W05 — place objects + multi-tile structures; set warps/spawns/collision',
+    description: 'Place objects + multi-tile structures; set warps, spawns, collision. Depends on ED2 (V3.W04) + E4 (V2.W11). Criterion map-editor.',
+    kind: 'feature', discipline: 'engineer', priority: 2, est_minutes: 240, manual_degree: 3,
+    credits_reward: 40, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['map-editor'], depends_on_refs: ['ED2', 'E4'] },
+
+  { ref: 'ED4', version: 'V3', title: 'V3.W06 — save: rank-gated POST /api/bongos/maps/:id validated by mapFormat',
+    description: 'Save maps back to the game: rank-gated `POST /api/bongos/maps/:id`, validated by `mapFormat`, persisted per the S3 (V3.W02) save-model spike. Depends on ED3 (V3.W05) + S3 (V3.W02). Criterion map-editor.',
+    kind: 'feature', discipline: 'engineer', priority: 2, est_minutes: 180, manual_degree: 3,
+    credits_reward: 30, module_key: 'game', requires_rank: 'metic',
+    criterion_ids: ['map-editor'], depends_on_refs: ['ED3', 'S3'] },
+
+  // =========================================================================
+  // GDS-V4 — planning-session skill fixes (from Builder #25's friction notes)
+  // =========================================================================
+  { ref: 'SKILL425', version: 'GDS-V4', title: 'planning-session skill: document the net-new-version Metic path',
+    description: 'Document the net-new-version Metic path in the /planning-session skill: omit suggested_version (FK), keep target_version inside the criterion-proposal JSON (plain text, ratifiable once an Archon creates the version), file one umbrella feature idea with the version+goals+seed spec. From idea 425.',
+    kind: 'feature', discipline: 'engineer', priority: 3, est_minutes: 60, manual_degree: 2,
+    credits_reward: 15, requires_rank: 'metic',
+    criterion_ids: [], depends_on_refs: [], promoted_idea_id: 425 },
+
+  { ref: 'SKILL426', version: 'GDS-V4', title: 'planning-session Phase 2.5: show module keys, flag protected, prompt module-map prep',
+    description: 'Fix Phase 2.5 of /planning-session: scope_modules are module KEYS (from module-scope-map.js), not paths. Show the valid key list, flag which keys are protected, and prompt for a module-map prep task when a plan introduces uncovered paths. From idea 426.',
+    kind: 'feature', discipline: 'engineer', priority: 3, est_minutes: 60, manual_degree: 2,
+    credits_reward: 15, requires_rank: 'metic',
+    criterion_ids: [], depends_on_refs: [], promoted_idea_id: 426 },
+];
+
+async function main() {
+  await requireSession();
+  const api = await cliClient();
+
+  const idByRef = {};
+  let created = 0, idempotent = 0, errors = 0, promoted = 0, deps = 0;
+
+  // -- Pass 1: create every task (idempotent on source_ref). ----------------
+  for (const t of TASKS) {
+    const source_ref = `v2world-${t.ref}`;
+    const body = {
+      version_id: t.version,
+      title: t.title,
+      description: t.description,
+      kind: t.kind,
+      discipline: t.discipline,
+      priority: t.priority,
+      est_minutes: t.est_minutes,
+      manual_degree: t.manual_degree,
+      credits_reward: t.credits_reward,
+      source: 'planning-session',
+      source_ref,
+      criterion_ids: t.criterion_ids,
+    };
+    if (t.module_key) body.module_key = t.module_key;
+    if (t.requires_rank) body.requires_rank = t.requires_rank;
+
+    if (DRY) {
+      console.log(`DRY   ${t.ref.padEnd(8)} ${t.version.padEnd(6)} P${t.priority} ${t.kind.padEnd(7)} ${t.credits_reward}d  crit=[${t.criterion_ids.join(',')}] deps=[${t.depends_on_refs.join(',')}]`);
+      continue;
+    }
+
+    const res = await withRetry(() => api.tasks.postTasks({ body }));
+    if (res.status !== 201 && res.status !== 200) {
+      console.error(`FAIL  ${t.ref}: status=${res.status} ${JSON.stringify(res.data).slice(0, 240)}`);
+      errors++;
+      continue;
+    }
+    const id = res.data.task.id;
+    idByRef[t.ref] = id;
+    if (res.data.idempotent) { idempotent++; console.log(`SKIP  ${t.ref} → existing task ${id}`); }
+    else { created++; console.log(`OK    ${t.ref} → task ${id}  (criteria: ${(res.data.criteria || []).map(c => c.criterion_id).join(',') || 'none'})`); }
+
+    if (t.promoted_idea_id) {
+      const p = await withRetry(() => api.inbox.patchInboxId({ id: t.promoted_idea_id, body: { status: 'promoted', promoted_to_task_id: Number(id) } }));
+      if (p.status === 200) { promoted++; console.log(`      promoted idea #${t.promoted_idea_id} → task ${id}`); }
+      else console.error(`      FAIL promote idea #${t.promoted_idea_id}: ${p.status} ${JSON.stringify(p.data).slice(0, 160)}`);
+    }
+  }
+
+  if (DRY) { console.log(`\nDRY total: ${TASKS.length} tasks`); return; }
+
+  // -- Pass 2: wire dependencies now that every ref has an id. --------------
+  for (const t of TASKS) {
+    if (!t.depends_on_refs.length) continue;
+    const id = idByRef[t.ref];
+    if (!id) { console.error(`DEPSKIP ${t.ref}: no id (create failed)`); continue; }
+    const depIds = t.depends_on_refs.map(r => idByRef[r]).filter(Boolean);
+    if (depIds.length !== t.depends_on_refs.length) {
+      console.error(`DEPWARN ${t.ref}: unresolved deps ${JSON.stringify(t.depends_on_refs)} → ${JSON.stringify(depIds)}`);
+    }
+    if (!depIds.length) continue;
+    const res = await withRetry(() => api.tasks.postTasksIdDependencies({ id, body: { depends_on_task_ids: depIds } }));
+    if (res.status === 200 || res.status === 201) { deps += depIds.length; console.log(`DEP   ${t.ref} (${id}) ← [${t.depends_on_refs.join(',')}]`); }
+    else console.error(`DEPFAIL ${t.ref}: ${res.status} ${JSON.stringify(res.data).slice(0, 200)}`);
+  }
+
+  console.log(`\nDONE  created=${created} idempotent=${idempotent} deps_written=${deps} ideas_promoted=${promoted} errors=${errors}  (manifest: ${TASKS.length})`);
+  process.exit(errors === 0 ? 0 : 1);
+}
+
+main().catch((err) => { console.error('FATAL', err); process.exit(1); });

package/scripts/bongos/seed-verify-criteria.js

@@ -0,0 +1,124 @@
+// scripts/bongos/seed-verify-criteria.js — the seed-script self-check: did the
+// criterion links actually land where the plan said (task 1003076, retro on
+// goal 1000071 — the idea-routing seeder linked all 15 tasks to the WRONG
+// criteria via positional "Cn" tokens (learning 1000188) and still printed
+// success; only a manual GET /goals rollup caught it, after the fact). A seed
+// script tallies the criterion_ids it actually POSTed per task into its own
+// plan, then calls verifySeedCriteriaLinks() as its LAST step to fetch
+// GET /api/bongos/goals/<id> and diff `criteria[].linked_tasks` against that
+// plan — loud and non-zero-exit on any mismatch, zero included.
+//
+// Transport-agnostic on purpose: seed scripts don't share one HTTP client
+// (some use cli-lib's apiCall, others a local throttled fetch — see the
+// scripts/bongos/CLAUDE.md roster), so this takes a `fetchGoal(goalId)` callback
+// rather than assuming a client shape.
+//
+// WHY A BASELINE (task 1004668). A seed into a goal that already carries linked
+// work used to cry wolf: every criterion the seed did not touch was compared
+// against an expected count of zero, so goal 1000095 (six criteria already linked)
+// would have reported six false mismatches and exit(1) on a correct run — and a
+// check that fails correct runs trains the next builder to ignore it. A seed now
+// snapshots the goal's counts BEFORE its first write (baselineSeedCriteria) and
+// verifies `baseline + plan`, which still catches a stray link on a criterion the
+// seed was never meant to touch. Without a baseline only the plan's own criteria
+// are checked; nothing else is assumed to be zero.
+//
+// With a baseline, the plan is the links THIS RUN CREATED, not every task the seed
+// names. A seed is resumable (POST /tasks is idempotent on source_ref and replays
+// an existing task with `idempotent: true`), and a replayed task's links are
+// already inside the baseline — tally it again and a correct re-run expects them
+// twice. So a baselined seed skips replays when it tallies (see
+// seed-bv2-ideator-surface-tasks.js).
+
+// countsByCriterion — { criterion_id: linked_tasks } from GET /goals/:id rows.
+function countsByCriterion(criteriaRows) {
+  const counts = {};
+  for (const row of criteriaRows || []) counts[row.criterion_id] = Number(row.linked_tasks) || 0;
+  return counts;
+}
+
+// diffCriterionLinks — pure comparison: expected (slug -> count, tallied from
+// the criterion_ids actually POSTed) vs actual (the `criteria` rows
+// GET /goals/:id returns, each carrying criterion_id + linked_tasks). Returns
+// every mismatching slug.
+//
+// With `baseline` (the pre-seed snapshot) every criterion on the goal is checked
+// against baseline + plan — a criterion created after the snapshot starts at 0.
+// Without it, only the plan's own criteria are checked: a criterion the seed
+// does not cite has an unknown prior count, and guessing zero is the false alarm.
+function diffCriterionLinks(expectedCounts, criteriaRows, { baseline = null } = {}) {
+  const actual = countsByCriterion(criteriaRows);
+  const plan = expectedCounts || {};
+  const slugs = new Set(Object.keys(plan));
+  if (baseline) for (const slug of [...Object.keys(baseline), ...Object.keys(actual)]) slugs.add(slug);
+  const mismatches = [];
+  for (const slug of slugs) {
+    const expected = ((baseline && baseline[slug]) || 0) + (plan[slug] || 0);
+    const got = actual[slug] || 0;
+    if (expected !== got) mismatches.push({ criterion_id: slug, expected, actual: got });
+  }
+  return mismatches.sort((a, b) => a.criterion_id.localeCompare(b.criterion_id));
+}
+
+// expectedCriterionCounts — tally a seed script's per-task criterion_ids
+// (already resolved to real slugs, post any "Cn" -> slug mapping) into
+// { slug: count }. Callers pass one array per task so the plan is derived from
+// exactly what got POSTed, not a second hand-maintained total.
+function expectedCriterionCounts(criterionIdListsPerTask) {
+  const counts = {};
+  for (const ids of criterionIdListsPerTask || []) {
+    for (const slug of ids || []) counts[slug] = (counts[slug] || 0) + 1;
+  }
+  return counts;
+}
+
+function readCriteria(r) {
+  const body = (r && (r.json || r.data)) || null;
+  return r && r.ok && body && Array.isArray(body.criteria) ? body.criteria : null;
+}
+
+// baselineSeedCriteria — call BEFORE the seed's first write. Returns the goal's
+// current { criterion_id: linked_tasks } snapshot to hand to
+// verifySeedCriteriaLinks, or exit(1)s: a seed that cannot read the goal it is
+// about to write into must not seed blind.
+async function baselineSeedCriteria({ goalId, fetchGoal, log = console.log, exit = process.exit }) {
+  const r = await fetchGoal(goalId);
+  const criteria = readCriteria(r);
+  if (!criteria) {
+    log(`BASELINE FAILED: GET goal ${goalId} did not return a criteria list (status ${r && r.status}). Refusing to seed blind.`);
+    return exit(1);
+  }
+  const baseline = countsByCriterion(criteria);
+  const linked = Object.values(baseline).filter((n) => n > 0).length;
+  log(`Baselined goal ${goalId}: ${criteria.length} criteria, ${linked} already carrying linked tasks.`);
+  return baseline;
+}
+
+// verifySeedCriteriaLinks — Phase-5 self-check: fetch the goal, diff its
+// linked_tasks against the plan (plus the pre-seed `baseline` when given), and
+// exit(1) loudly on any mismatch (a zero where tasks were expected is the shape
+// that shipped silently in the RETRO2 incident, but any drift is worth stopping
+// the seed for).
+async function verifySeedCriteriaLinks({ goalId, expectedCounts, baseline = null, fetchGoal, log = console.log, exit = process.exit }) {
+  const r = await fetchGoal(goalId);
+  const criteria = readCriteria(r);
+  if (!criteria) {
+    log(`VERIFY FAILED: GET goal ${goalId} did not return a criteria list (status ${r && r.status}). Cannot confirm criterion links landed.`);
+    return exit(1);
+  }
+  const mismatches = diffCriterionLinks(expectedCounts, criteria, { baseline });
+  if (mismatches.length) {
+    log(`VERIFY FAILED: criterion links on goal ${goalId} do not match the plan (${mismatches.length} mismatch${mismatches.length === 1 ? '' : 'es'}):`);
+    for (const m of mismatches) log(`  ${m.criterion_id}: expected ${m.expected} linked task(s), got ${m.actual}`);
+    log('Likely cause: a criterion_ids mapping bug (e.g. a positional "Cn" token resolved against the wrong scope — learning 1000188). Fix and re-run before trusting this seed.');
+    return exit(1);
+  }
+  if (baseline) {
+    log(`VERIFY OK: all ${criteria.length} criteria on goal ${goalId} carry their pre-seed count plus the planned links.`);
+  } else {
+    log(`VERIFY OK: all ${Object.keys(expectedCounts || {}).length} planned criteria on goal ${goalId} carry their planned task count.`);
+    log('  (No baseline was taken, so criteria this seed does not cite were not checked — pass baselineSeedCriteria() output as `baseline` to cover them.)');
+  }
+}
+
+module.exports = { diffCriterionLinks, expectedCriterionCounts, baselineSeedCriteria, verifySeedCriteriaLinks };