@bongos/core 1.21.124 → 1.21.126

package/tests/core_pin_sync.mjs

@@ -0,0 +1,237 @@
+// tests/core_pin_sync.mjs — `bongos <verb>` runs the core the checkout pins (task 1004632)
+//
+// The bug: an instance's task worktree has no node_modules of its own, so after a
+// core-update task lands the next task's `bongos ship` resolved the MAIN checkout's
+// older core and failed on a bug the new pin had already fixed. These cases pin the
+// decision (planCoreSync), the pin reader, and the install-then-re-run path with an
+// injected runner — no npm, no network. The last case is end to end on a real temp
+// git repo with a fake installed core.
+//
+// Run:  node tests/core_pin_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const sync = require('../scripts/gds/core-pin-sync.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const CORE = { name: '@bongos/core', version: '1.21.20' };
+
+test('versionFromSpec reads a vendored tarball and a registry semver', () => {
+  assert.equal(sync.versionFromSpec('file:vendor/bongos-core-1.21.71.tgz'), '1.21.71');
+  assert.equal(sync.versionFromSpec('^1.21.71'), '1.21.71');
+  assert.equal(sync.versionFromSpec('1.21.71'), '1.21.71');
+  assert.equal(sync.versionFromSpec('file:../somewhere'), null);
+  assert.equal(sync.versionFromSpec(undefined), null);
+});
+
+test('parseSpec: only the shapes the core writes itself are safe to auto-install', () => {
+  assert.equal(sync.parseSpec('file:vendor/bongos-core-1.21.71.tgz').safe, true);
+  assert.equal(sync.parseSpec('1.21.71').safe, true);
+  assert.equal(sync.parseSpec('^1.21.71').safe, false, 'a range is not an exact pin');
+  assert.equal(sync.parseSpec('file:../evil/bongos-core-1.21.71.tgz').safe, false);
+  assert.equal(sync.parseSpec('git+https://x/y.git').safe, false);
+});
+
+test('planCoreSync: a pin that has not landed on main refuses — a branch cannot choose what gets installed', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '9.9.9', specSafe: true, landed: false, env: {} });
+  assert.equal(p.action, 'refuse');
+  assert.equal(p.reason, 'pin-not-landed');
+});
+
+test('planCoreSync: an unrecognised spec refuses with the remedy, never installs', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', specSafe: false, env: {} });
+  assert.equal(p.action, 'refuse');
+});
+
+test('installArgs: never runs install scripts; ci with a lockfile, install without', () => {
+  assert.deepEqual(sync.installArgs(true).slice(0, 2), ['ci', '--ignore-scripts']);
+  assert.deepEqual(sync.installArgs(false).slice(0, 2), ['install', '--ignore-scripts']);
+});
+
+test('planCoreSync: the core repo itself is never touched', () => {
+  const p = sync.planCoreSync({ runningPkg: { name: 'cloud-bongos', version: '0.0.2' }, root: '/r', pinned: '1.21.71', env: {} });
+  assert.equal(p.action, 'none');
+});
+
+test('planCoreSync: in sync, no git, no pin → carry on', () => {
+  assert.equal(sync.planCoreSync({ runningPkg: { ...CORE, version: '1.21.71' }, root: '/r', pinned: '1.21.71', env: {} }).action, 'none');
+  assert.equal(sync.planCoreSync({ runningPkg: CORE, root: null, pinned: '1.21.71', env: {} }).action, 'none');
+  assert.equal(sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: null, env: {} }).action, 'none');
+});
+
+test('planCoreSync: the task-49 shape (pinned 1.21.71, running 1.21.20) syncs', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', specSafe: true, landed: true, env: {} });
+  assert.equal(p.action, 'sync');
+  assert.equal(p.pinned, '1.21.71');
+  assert.equal(p.running, '1.21.20');
+});
+
+test('planCoreSync: a re-run that is STILL mismatched refuses instead of looping', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', env: { [sync.SYNCED_ENV]: '1' } });
+  assert.equal(p.action, 'refuse');
+  assert.match(sync.remedyLine(p), /npm ci/);
+});
+
+function tmpCheckout({ pinSpec, lockVersion }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-sync-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), '' + JSON.stringify({ name: 'inst', dependencies: { '@bongos/core': pinSpec } }));
+  if (lockVersion) {
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), JSON.stringify({ packages: { 'node_modules/@bongos/core': { version: lockVersion } } }));
+  }
+  return dir;
+}
+
+test('pinnedCoreVersion prefers the lockfile, falls back to package.json (BOM tolerated)', () => {
+  const a = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.72' });
+  assert.equal(sync.pinnedCoreVersion(a), '1.21.72');
+  const b = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz' });
+  assert.equal(fs.readFileSync(path.join(b, 'package.json'), 'utf8').charCodeAt(0), 0xFEFF, 'fixture really carries a BOM');
+  assert.equal(sync.pinnedCoreVersion(b), '1.21.71');
+});
+
+test('syncAndRerun: npm ci in the checkout, then re-run the same argv under its own core with the loop guard', () => {
+  const root = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.71' });
+  const calls = [];
+  const run = (cmd, args, opts) => {
+    calls.push({ cmd, args, opts });
+    if (cmd === 'npm') {
+      const d = path.join(root, 'node_modules', '@bongos', 'core', 'bin');
+      fs.mkdirSync(d, { recursive: true });
+      fs.writeFileSync(path.join(d, 'bongos.js'), '');
+      return { status: 0 };
+    }
+    return { status: 7 };
+  };
+  const code = sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship', '49'], run, log: () => {}, env: {}, platform: 'linux', npmCli: null });
+  assert.equal(code, 7, 'the re-run exit code is passed through');
+  assert.equal(calls[0].cmd, 'npm');
+  assert.equal(calls[0].args[0], 'ci');
+  assert.equal(path.resolve(calls[0].opts.cwd), path.resolve(root));
+  assert.equal(calls[1].cmd, process.execPath);
+  assert.deepEqual(calls[1].args.slice(1), ['ship', '49']);
+  assert.ok(calls[1].args[0].includes(path.join('node_modules', '@bongos', 'core', 'bin', 'bongos.js')));
+  assert.equal(calls[1].opts.env[sync.SYNCED_ENV], '1');
+});
+
+test('syncAndRerun: a failed install exits 1 with the one-line remedy, and never re-runs', () => {
+  const root = tmpCheckout({ pinSpec: '1.21.71' });
+  const logs = [];
+  const calls = [];
+  const run = (cmd, args) => { calls.push(cmd); return { status: 1 }; };
+  const code = sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship'], run, log: (s) => logs.push(s), env: {}, platform: 'linux', npmCli: null });
+  assert.equal(code, 1);
+  assert.deepEqual(calls, ['npm']);
+  assert.equal(calls.length, 1);
+  assert.ok(logs.some((l) => /Run `npm install` in /.test(l)), 'no lockfile → remedy names npm install: ' + logs.join('\n'));
+});
+
+test('syncAndRerun: a node_modules LINK is detached first, never installed through', () => {
+  const root = tmpCheckout({ pinSpec: '1.21.71', lockVersion: '1.21.71' });
+  const shared = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-shared-'));
+  fs.writeFileSync(path.join(shared, 'keep.txt'), 'shared');
+  fs.symlinkSync(shared, path.join(root, 'node_modules'), 'junction');
+  const run = (cmd) => {
+    if (cmd === 'npm') {
+      assert.ok(!fs.existsSync(path.join(root, 'node_modules')), 'link must be gone before npm runs');
+      return { status: 1 };
+    }
+    return { status: 0 };
+  };
+  sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship'], run, log: () => {}, env: {}, npmCli: null });
+  assert.equal(fs.readFileSync(path.join(shared, 'keep.txt'), 'utf8'), 'shared', 'the shared install is untouched');
+});
+
+function git(cwd, ...args) {
+  const r = spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...args], { cwd, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  return r.stdout;
+}
+
+// A real repo: main carries the 1.21.71 pin (the core update landed); the checkout is
+// on a task branch. The running core is the older 1.21.20.
+function landedRepo() {
+  const root = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.71' });
+  fs.mkdirSync(path.join(root, 'vendor'));
+  fs.writeFileSync(path.join(root, 'vendor', 'bongos-core-1.21.71.tgz'), 'tarball-bytes');
+  git(root, 'init', '-q', '-b', 'main');
+  git(root, 'add', '-A');
+  git(root, 'commit', '-qm', 'pin 1.21.71');
+  git(root, 'checkout', '-qb', 'task-49');
+  const coreRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-running-'));
+  fs.writeFileSync(path.join(coreRoot, 'package.json'), JSON.stringify(CORE));
+  const installs = [];
+  const run = (cmd, args, opts) => {
+    if (cmd === 'git') return spawnSync(cmd, args, opts);
+    if (cmd === 'npm' || String(args[0] || '').endsWith('npm-cli.js')) installs.push(args);
+    return { status: 1 };
+  };
+  return { root, coreRoot, installs, run };
+}
+
+test('ensurePinnedCore end to end: a pin that LANDED on main gets installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  assert.equal(sync.pinLanded(root, { run }), true);
+  const code = sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} });
+  assert.equal(code, 1, 'the fake install fails, so the remedy exit');
+  assert.equal(installs.length, 1, 'npm ran once');
+  // in sync → null (carry on), no install
+  fs.writeFileSync(path.join(coreRoot, 'package.json'), JSON.stringify({ ...CORE, version: '1.21.71' }));
+  installs.length = 0;
+  assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), null);
+  assert.equal(installs.length, 0);
+});
+
+test('ensurePinnedCore end to end: a branch-swapped tarball (committed or not) is refused, never installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  fs.writeFileSync(path.join(root, 'vendor', 'bongos-core-1.21.71.tgz'), 'attacker-bytes');
+  assert.equal(sync.pinLanded(root, { run }), false, 'uncommitted swap');
+  git(root, 'commit', '-qam', 'swap');
+  assert.equal(sync.pinLanded(root, { run }), false, 'committed on the branch only');
+  const logs = [];
+  const code = sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: (l) => logs.push(l) });
+  assert.equal(code, 1);
+  assert.equal(installs.length, 0);
+  assert.ok(logs.some((l) => /Run `npm ci`/.test(l)), logs.join('\n'));
+});
+
+test('ensurePinnedCore end to end: a branch-only version bump is refused, never installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'inst', dependencies: { '@bongos/core': '9.9.9' } }));
+  fs.rmSync(path.join(root, 'package-lock.json'));
+  git(root, 'commit', '-qam', 'bump');
+  assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), 1);
+  assert.equal(installs.length, 0);
+});
+
+test('ensurePinnedCore end to end: deleting the lockfile or adding an .npmrc on the branch is refused', () => {
+  for (const tamper of [
+    (root) => fs.rmSync(path.join(root, 'package-lock.json')),
+    (root) => fs.writeFileSync(path.join(root, '.npmrc'), 'registry=https://evil.example/\n'),
+  ]) {
+    const { root, coreRoot, installs, run } = landedRepo();
+    tamper(root);
+    assert.equal(sync.pinLanded(root, { run }), false);
+    assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), 1);
+    assert.equal(installs.length, 0);
+  }
+});
+
+test('the dispatcher runs the check for ship only', () => {
+  const src = fs.readFileSync(new URL('../bin/bongos.js', import.meta.url), 'utf8');
+  assert.match(src, /if \(!COMPILED && verb === 'ship'\) \{\s*const synced = require\('\.\.\/scripts\/gds\/core-pin-sync\.js'\)\.ensurePinnedCore/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/goal_forest_lib.mjs

@@ -141,6 +141,34 @@ await test('describe states the numbers plainly, and an empty forest says so', (
   assert.equal(L.describe(L.analyse({})), 'No task in this goal depends on another task in this goal.');
 });
 
+// ---- the band card's summary (task 1004738) ---------------------------------------
+
+await test('brief is the short form of describe, and falls back to it for an empty forest', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(5, 4)] });
+  assert.equal(L.brief(a), '5 tasks linked by dependencies, in 2 chains.');
+  assert.equal(L.brief(L.analyse({})), L.describe(L.analyse({})));
+});
+
+await test('shipFirst ranks the open tasks nothing open blocks by how many open tasks wait on them, down the chain', () => {
+  // 1 ← 2 ← 3 and 1 ← 4: task 1 unblocks three. 5 ← 6: task 5 unblocks one.
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(4, 1), edge(6, 5)] });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => [r.id, r.unblocks]), [['1', 3], ['5', 1]],
+    'a task still waiting on an open one is never "first"; one that unblocks nothing is left off');
+});
+
+await test('shipFirst: a shipped dependency frees what waits on it, and closed work is never listed or counted', () => {
+  const a = L.analyse({
+    nodes: [node(1, { status: 'shipped' }), node(2), node(3), node(4, { status: 'abandoned' })],
+    edges: [edge(2, 1), edge(3, 2), edge(4, 2)],
+  });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => [r.id, r.unblocks]), [['2', 1]], 'task 2 is up next and unblocks only the open task 3');
+});
+
+await test('shipFirst stops at the limit and breaks ties by task id', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6, 7, 8].map((i) => node(i)), edges: [edge(5, 4), edge(6, 3), edge(7, 2), edge(8, 1)] });
+  assert.deepEqual(L.shipFirst(a, 3).map((r) => r.id), ['1', '2', '3']);
+});
+
 // ---- purity -----------------------------------------------------------------------
 
 await test('the lib is pure: no DOM, no fetch, no cross-goal input', () => {

package/tests/goal_forest_page.mjs

@@ -36,10 +36,11 @@ const settle = async () => { for (let i = 0; i < 20; i++) await tick(); };
 const t = (id, extra = {}) => ({ task_id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
 const e = (from, to) => ({ from: String(from), to: String(to) });
 
-async function boot({ status = 200, fail = false, payload = { nodes: [], edges: [] } } = {}) {
+async function boot({ status = 200, fail = false, payload = { nodes: [], edges: [] }, conflictPairs = null, view = 'dependencies' } = {}) {
   const root = makeEl('div');
   const reg = (id) => { const el = makeEl('div', { id }); root.appendChild(el); return el; };
-  ['goal-deps-h', 'goal-deps-count', 'goal-deps-lede', 'goal-deps-body'].forEach(reg);
+  ['goal-deps-h', 'goal-deps-count', 'goal-deps-lede', 'goal-deps-body', 'goal-deps-back',
+    'goal-deps-card-count', 'goal-deps-card-lede', 'goal-deps-card-body', 'goal-deps-card-foot'].forEach(reg);
 
   const documentObj = {
     getElementById: (id) => walk(root, (el) => (el.id === id ? el : null)),
@@ -83,7 +84,7 @@ async function boot({ status = 200, fail = false, payload = { nodes: [], edges:
   vm.runInContext(read('bulk-toolbar.js'), sandbox, { filename: 'bulk-toolbar.js' }); // task 1003141
   vm.runInContext(RENDER_JS, sandbox, { filename: 'goals-render.js' });
 
-  const state = { current: 7, forest: null, forestError: false };
+  const state = { current: 7, view, forest: null, forestError: false, conflictPairs };
   const ctx = {
     API: '/api/bongos',
     state,
@@ -96,7 +97,10 @@ async function boot({ status = 200, fail = false, payload = { nodes: [], edges:
     },
   };
   const renderers = windowObj.OTBGoalsRender(ctx);
-  return { $: documentObj.getElementById, requests, state, renderers };
+  // The band card's renderer is the forest module's own export — goals-render.js
+  // reaches it through its private `forestRender`, so the test makes its own.
+  const card = windowObj.OTBGoalForestRender(ctx);
+  return { $: documentObj.getElementById, requests, state, renderers, card };
 }
 
 // ---- the honest states (ADR 0227) ---------------------------------------------
@@ -217,14 +221,105 @@ await test('renderDetail calls loadDependencyForest, beside loadGoalTasks, for t
   assert.match(RENDER_JS, /loadGoalTasks\(g\.id\);\s*\n\s*loadDependencyForest\(g\.id\);/);
 });
 
-await test('the section is its OWN full-width block, not squeezed into the three-column band', () => {
+// ---- the band card + the full view (task 1004738) ----------------------------
+
+const sectionOf = (html, id) => {
+  const start = html.indexOf(`<section id="${id}"`);
+  return start < 0 ? '' : html.slice(start, html.indexOf('</section>', start));
+};
+
+await test('the band\'s third column is the compact Dependencies card, where Conflicts was — no long block before Tasks', () => {
   const html = fs.readFileSync(path.join(HALL, 'goals.html'), 'utf8');
-  const bandAt = html.indexOf('class="scroll goal-band"');
-  const depsAt = html.indexOf('id="goal-deps-scroll"');
-  const tasksAt = html.indexOf('<h2 class="scroll__h">Tasks</h2>');
-  assert.ok(bandAt > -1 && depsAt > -1 && tasksAt > -1);
-  assert.ok(bandAt < depsAt && depsAt < tasksAt, 'band, then dependencies, then tasks');
-  assert.equal(/id="goal-deps-scroll"[\s\S]{0,400}goal-band__col/.test(html), false, 'not inside a band column');
+  const detail = sectionOf(html, 'goal-detail-view');
+  const cols = detail.split('class="goal-band__col"').slice(1);
+  assert.equal(cols.length, 3, 'still three columns');
+  assert.match(cols[2], /^\s*id="goal-deps-card"/, 'Dependencies takes the third slot');
+  assert.equal(/>Conflicts</.test(cols.join('')), false, 'no Conflicts column left in the band');
+  assert.equal(detail.includes('id="goal-deps-scroll"'), false, 'the forest is off the goal page');
+});
+
+await test('the full picture is #/goal/N/dependencies: the forest, then the whole conflict set; the old /conflicts lands there', () => {
+  const html = fs.readFileSync(path.join(HALL, 'goals.html'), 'utf8');
+  const view = sectionOf(html, 'goal-dependencies-view');
+  const depsAt = view.indexOf('id="goal-deps-scroll"');
+  const conflictsAt = view.indexOf('id="goal-conflicts-full"');
+  assert.ok(view.includes('id="goal-deps-back"') && depsAt > -1 && depsAt < conflictsAt, 'back link, forest, then conflicts');
+  assert.equal(sectionOf(html, 'goal-conflicts-view'), '', 'no separate conflicts view any more');
+  const page = read('goals-page.js');
+  assert.match(page, /dependencies: '#goal-dependencies-view'/);
+  assert.match(page, /\(dependencies\|conflicts\|members\|completion\)/);
+  assert.match(page, /mSub\[2\] === 'conflicts' \? 'dependencies'/, 'the inbox\'s /conflicts links keep working');
+  assert.match(RENDER_JS, /function renderConflicts\(\) \{[\s\S]*?forestRender\.renderDependencyCard\(\);/, 'the card re-renders when the conflicts land');
+});
+
+await test('the card states the shape, lists what to ship first, counts conflicts, and links to the full view', async () => {
+  const h = await boot({
+    payload: { nodes: [t(1, { title: 'Base' }), t(2), t(3), t(4, { title: 'Other root' }), t(5)], edges: [e(2, 1), e(3, 2), e(5, 4)] },
+    conflictPairs: [{ a: 2, b: 5 }, { a: 3, b: 5 }],
+  });
+  await h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-card-count').hidden, false);
+  assert.equal(h.$('goal-deps-card-count').textContent, '5');
+  assert.equal(h.$('goal-deps-card-lede').textContent, '5 tasks linked by dependencies, in 2 chains.');
+  const body = h.$('goal-deps-card-body');
+  const rows = body.querySelectorAll('.gf-brief__row');
+  assert.deepEqual(rows.map((r) => r.querySelector('a').getAttribute('href')), ['#/task/1', '#/task/4']);
+  assert.deepEqual(rows.map((r) => r.querySelector('.gf-brief__n').textContent), ['unblocks 2', 'unblocks 1']);
+  const line = body.querySelector('.gf-brief__conflicts');
+  assert.equal(line.textContent, '2 file conflicts between open tasks.');
+  assert.match(line.className, /gf-brief__conflicts--live/);
+  const foot = h.$('goal-deps-card-foot');
+  assert.equal(foot.hidden, false);
+  assert.equal(foot.querySelector('a').getAttribute('href'), '#/goal/7/dependencies');
+  assert.equal(h.$('goal-deps-back').getAttribute('href'), '#/goal/7');
+});
+
+await test('on the goal page only the card is drawn — the forest waits for its own view, where its titles can be measured', async () => {
+  const h = await boot({ view: 'detail', payload: { nodes: [t(1), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-body').querySelector('svg'), null, 'no forest drawn into the hidden view');
+  assert.equal(h.$('goal-deps-body').innerHTML, '');
+  assert.equal(h.$('goal-deps-card-lede').textContent, '2 tasks linked by dependencies, in 1 chain.');
+  h.state.view = 'dependencies';
+  h.renderers.renderDependencyForest();
+  assert.ok(h.$('goal-deps-body').querySelector('svg'), 'opening the view draws it');
+});
+
+await test('the card: no conflicts says so, unknown conflicts says nothing, and an empty goal has no door to an empty page', async () => {
+  const none = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: [] });
+  await none.renderers.loadDependencyForest(7);
+  assert.match(none.$('goal-deps-card-lede').textContent, /No task in this goal depends on another/);
+  assert.equal(none.$('goal-deps-card-count').hidden, true);
+  assert.equal(none.$('goal-deps-card-body').querySelector('.gf-brief__conflicts').textContent, 'No file conflicts between open tasks.');
+  assert.equal(none.$('goal-deps-card-foot').hidden, true);
+
+  const unknown = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: null });
+  await unknown.renderers.loadDependencyForest(7);
+  assert.equal(unknown.$('goal-deps-card-body').querySelector('.gf-brief__conflicts'), null, 'a failed or pending conflicts read draws no line, not a zero');
+
+  const onlyConflicts = await boot({ payload: { nodes: [], edges: [] }, conflictPairs: [{ a: 1, b: 2 }] });
+  await onlyConflicts.renderers.loadDependencyForest(7);
+  assert.equal(onlyConflicts.$('goal-deps-card-foot').hidden, false, 'conflicts alone still earn the full view');
+});
+
+await test('the card: while reading, and after a failed read, it says so — and a late conflicts list re-renders it', async () => {
+  const h = await boot({ fail: true });
+  const p = h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-card-lede').textContent, 'Reading…');
+  await p;
+  assert.match(h.$('goal-deps-card-lede').textContent, /Couldn.t load this goal.s task dependencies/);
+  h.state.conflictPairs = [{ a: 1, b: 2 }];
+  h.card.renderDependencyCard();
+  assert.equal(h.$('goal-deps-card-body').querySelector('.gf-brief__conflicts').textContent, '1 file conflict between open tasks.');
+});
+
+await test('a "ship first" title is builder-authored text and never becomes markup in the card either', async () => {
+  const evil = '<img src=x onerror=alert(1)>';
+  const h = await boot({ payload: { nodes: [t(1, { title: evil }), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  const body = h.$('goal-deps-card-body');
+  assert.equal(body.querySelector('img'), null);
+  assert.ok(body.textContent.includes(evil));
 });
 
 summary();

package/tests/howto_guide.mjs

@@ -0,0 +1,96 @@
+// tests/howto_guide.mjs — the in-session how-to guide's shape + plain-language rule (task 1004627)
+//
+// The guide's step ids are stored as per-person read marks (task 1004634) and matched to
+// moments (task 1004635), so they must be unique, stable-shaped, and every step must
+// belong to a known moment and carry all three parts (what / when / try). It is written
+// for people who may not be technical, so no step may use the accessibility scorer's
+// jargon list (the same list tests/plain_cards.mjs holds the failure cards to).
+//
+// Run:  node tests/howto_guide.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const guide = require('../modules/onboarding/howto-guide.js');
+const { JARGON_TERMS } = require('../modules/sessions/accessibility.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+test('about 25 steps, each with a unique snake_case id', () => {
+  assert.ok(guide.STEPS.length >= 20 && guide.STEPS.length <= 32, `got ${guide.STEPS.length}`);
+  const ids = guide.STEPS.map((s) => s.id);
+  assert.equal(new Set(ids).size, ids.length, 'duplicate step id');
+  for (const id of ids) assert.match(id, /^[a-z][a-z0-9_]{2,39}$/, id);
+});
+
+test('every step has a known moment and all three parts', () => {
+  for (const s of guide.STEPS) {
+    assert.ok(guide.MOMENT_IDS.has(s.moment), `${s.id}: unknown moment ${s.moment}`);
+    for (const f of ['title', 'what', 'when', 'try']) assert.ok(String(s[f] || '').trim().length > 5, `${s.id}.${f} empty`);
+  }
+});
+
+test('every moment has at least one step and a trigger', () => {
+  for (const m of guide.MOMENTS) {
+    assert.ok(guide.stepsForMoment(m.id).length > 0, `${m.id} has no steps`);
+    assert.ok(m.trigger, `${m.id} has no trigger`);
+  }
+});
+
+test('the moments the owner named are covered', () => {
+  for (const m of ['first_open', 'setup', 'goal', 'task', 'find_work', 'first_ship', 'invite', 'settings']) {
+    assert.ok(guide.MOMENT_IDS.has(m), m);
+  }
+  assert.ok(guide.stepById('where_to_start'), 'the "where to start" step exists');
+  assert.ok(guide.stepById('ship_mode'), 'settings covers the ship mode');
+});
+
+test('steps are short and in plain language (no jargon)', () => {
+  const hits = [];
+  for (const s of guide.STEPS) {
+    for (const f of ['title', 'what', 'when', 'try']) {
+      const text = s[f];
+      if (f !== 'try') assert.ok(text.length <= 240, `${s.id}.${f} is ${text.length} chars — keep a step short`);
+      for (const term of JARGON_TERMS) {
+        const re = new RegExp(`(^|[^A-Za-z])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z]|$)`, /^[A-Z+-]+$/.test(term) ? '' : 'i');
+        if (re.test(text)) hits.push(`${s.id}.${f}: "${term}"`);
+      }
+    }
+  }
+  assert.deepEqual(hits, []);
+});
+
+test('every slash command a step names is a core skill an instance gets', async () => {
+  const fs = await import('node:fs');
+  const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+  for (const s of guide.STEPS) {
+    for (const m of s.try.matchAll(/\/([a-z][a-z-]+)/g)) {
+      const skill = `.claude/skills/${m[1]}/SKILL.md`;
+      assert.ok(fs.existsSync(new URL(`../${skill}`, import.meta.url)), `${s.id}: /${m[1]} is not a skill`);
+      assert.ok(isPublishable(skill), `${s.id}: /${m[1]} does not ship to an instance`);
+    }
+  }
+});
+
+test('nextUnread walks the guide in order and ends at null', () => {
+  assert.equal(guide.nextUnread([]).id, guide.STEPS[0].id);
+  assert.equal(guide.nextUnread([guide.STEPS[0].id]).id, guide.STEPS[1].id);
+  assert.equal(guide.nextUnread(guide.STEPS.map((s) => s.id)), null);
+});
+
+test('formatGuide renders every step, and one moment on request', () => {
+  const all = guide.formatGuide();
+  for (const s of guide.STEPS) assert.ok(all.includes(`[${s.id}]`), s.id);
+  const one = guide.formatGuide({ moment: 'first_ship' });
+  assert.ok(one.includes('[what_ship_does]'));
+  assert.ok(!one.includes('[welcome]'));
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/module_assess_price_parity.mjs

@@ -87,7 +87,7 @@ function fakeDb() {
     async query(sql, params = []) {
       sqlSeen.push(sql);
       if (PRICE_WORD.test(sql)) throw new Error(`the assessment read price: ${sql.slice(0, 120)}`);
-      if (/^SELECT id, module_key, version FROM store_module_versions WHERE id/.test(sql)) {
+      if (/^SELECT id, module_key, version(, artifact_path)? FROM store_module_versions WHERE id/.test(sql)) {
         const v = CASES.find((c) => String(c.id) === String(params[0]));
         return { rows: v ? [{ id: v.id, module_key: v.module_key, version: v.version }] : [] };
       }
@@ -162,7 +162,7 @@ test('assessVersion on publish runs the same steps for every case, and never rea
   const recordDocs = async (id, { db: d }) => { steps.push(['docs', id]); return { ok: true, signal: d.add(id, 'docs', 'scored', 50) }; };
   const out = [];
   for (const c of CASES) {
-    const res = await assessVersion(c.id, { db, recordSecurity, recordDocs });
+    const res = await assessVersion(c.id, { db, dispatchTests: async () => null, recordSecurity, recordDocs });
     assert.equal(res.ok, true, c.module_key);
     out.push(shape(res.score));
   }

package/tests/module_assess_score.mjs

@@ -18,6 +18,9 @@ const { composeScore, recomposeScore } = require('../scripts/gds/module-assess-s
 const { assessVersion, queueAssessment, QUEUE_MAX } = require('../scripts/gds/module-assess-version.js');
 
 const sig = (id, part, outcome, score = null) => ({ id, part, outcome, score });
+// Every assessVersion call here stubs the test-runner dispatch, so a shell with
+// MODULE_TEST_REPO/MODULE_TEST_TOKEN set can never make this suite reach GitHub.
+const noDispatch = async () => null;
 
 // ---------------------------------------------------------------------------
 // composeScore — the rule, pure
@@ -98,7 +101,7 @@ function fakeDb({ versions = [{ id: 7, module_key: 'weather', version: '1.0.0' }
   const db = {
     signals, scores,
     async query(sql, params = []) {
-      if (/^SELECT id, module_key, version FROM store_module_versions WHERE id/.test(sql)) {
+      if (/^SELECT id, module_key, version(, artifact_path)? FROM store_module_versions WHERE id/.test(sql)) {
         return { rows: versions.filter((v) => String(v.id) === String(params[0])) };
       }
       if (/SELECT DISTINCT ON \(part\)/.test(sql)) {
@@ -158,7 +161,7 @@ test('assessVersion on publish: Tests pending, the Security gate, Docs, then the
   const seen = [];
   const recordSecurity = async (id, { db: d }) => { seen.push(id); const row = d.add(id, 'security', 'passed'); return { ok: true, signal: row }; };
   const recordDocs = async (id, { db: d }) => { seen.push(`docs:${id}`); return { ok: true, signal: d.add(id, 'docs', 'scored', 20) }; };
-  const res = await assessVersion(7, { db, recordSecurity, recordDocs });
+  const res = await assessVersion(7, { db, dispatchTests: noDispatch, recordSecurity, recordDocs });
   assert.equal(res.ok, true);
   assert.deepEqual(seen, [7, 'docs:7'], 'Security, then Docs');
   assert.equal(res.docs.part, 'docs');
@@ -173,11 +176,18 @@ test('assessVersion on publish: Tests pending, the Security gate, Docs, then the
 test('re-assessing never hides a real Tests score behind a newer "pending"', async () => {
   const db = fakeDb();
   db.add(7, 'tests', 'scored', 85);
-  const res = await assessVersion(7, { db, recordSecurity: async (id, { db: d }) => ({ ok: true, signal: d.add(id, 'security', 'passed') }), recordDocs: async () => null });
+  const res = await assessVersion(7, { db, dispatchTests: noDispatch, recordSecurity: async (id, { db: d }) => ({ ok: true, signal: d.add(id, 'security', 'passed') }), recordDocs: async () => null });
   assert.equal(db.signals.filter((s) => s.part === 'tests').length, 1);
   assert.equal(res.score.overall, 85);
 });
 
+test('assessVersion hands the version to the test-runner dispatch before recording Tests pending', async () => {
+  const db = fakeDb();
+  const sent = [];
+  await assessVersion(7, { db, dispatchTests: async (ver, { db: d }) => { sent.push(ver.id); assert.equal(d, db); return null; }, recordSecurity: async () => null, recordDocs: async () => null });
+  assert.deepEqual(sent, [7]);
+});
+
 test('assessVersion on an unknown version writes nothing', async () => {
   const db = fakeDb({ versions: [] });
   const res = await assessVersion(99, { db, recordSecurity: async () => { throw new Error('must not run'); } });