@bongos/core 1.21.69 → 1.21.71

package/tests/claude_materialize.mjs

@@ -41,24 +41,24 @@ function t(name, fn) {
 
 // ---- bongosify -------------------------------------------------------------
 t('bongosify: a script WITH a dedicated verb → bongos <verb> (args preserved)', () => {
-  assert.equal(m.bongosify('run `node scripts/gds/ship.js 1885 --force`'), 'run `bongos ship 1885 --force`');
-  assert.equal(m.bongosify('node scripts/gds/start.js --json'), 'bongos start --json');
+  assert.equal(m.bongosify('run `node scripts/gds/ship.js 1885 --force`'), 'run `npx bongos ship 1885 --force`');
+  assert.equal(m.bongosify('node scripts/gds/start.js --json'), 'npx bongos start --json');
 });
 
 t('bongosify: a script WITHOUT a dedicated verb → bongos exec (args preserved)', () => {
-  assert.equal(m.bongosify('node scripts/gds/api.js GET /api/gds/me'), 'bongos exec scripts/gds/api.js GET /api/gds/me');
-  assert.equal(m.bongosify('node scripts/gds/capture.js "x"'), 'bongos exec scripts/gds/capture.js "x"');
+  assert.equal(m.bongosify('node scripts/gds/api.js GET /api/gds/me'), 'npx bongos exec scripts/gds/api.js GET /api/gds/me');
+  assert.equal(m.bongosify('node scripts/gds/capture.js "x"'), 'npx bongos exec scripts/gds/capture.js "x"');
 });
 
 t('bongosify: $CLAUDE_PROJECT_DIR + surrounding quotes are stripped', () => {
-  assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'npx bongos exec scripts/gds/session-cost.js');
 });
 
 t('bongosify: the run-node.sh resolver form (task 1003548) collapses to the same bongos form', () => {
   const wrap = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"';
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'bongos exec scripts/gds/session-cost.js');
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'bongos ship 1885');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'npx bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'npx bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'npx bongos ship 1885');
   // …and a resolver call whose target is a .claude/hooks/*.js stays instance-local, like the bare-node form.
   const hook = `${wrap} "$CLAUDE_PROJECT_DIR/.claude/hooks/secret-gate.js"`;
   assert.equal(m.bongosify(hook), hook);
@@ -100,7 +100,7 @@ t('transformSettings: rewrites scripts/gds hook commands, keeps .claude/hooks/ o
   const out = JSON.parse(m.transformSettings(p));
   const cmds = out.hooks.Stop[0].hooks.map((h) => h.command);
   assert.deepEqual(cmds, [
-    'bongos exec scripts/gds/session-cost.js',
+    'npx bongos exec scripts/gds/session-cost.js',
     'node "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-sound.js"',
   ]);
   rmSync(dir, { recursive: true, force: true });
@@ -121,12 +121,12 @@ t('transformSettings: permission rules are rewritten to the form the instance\'s
     },
   }, null, 2));
   const out = JSON.parse(m.transformSettings(p)).permissions;
-  assert.deepEqual(out.allow, ['Bash(bongos ship:*)', 'Bash(bongos exec scripts/gds/me.js:*)', 'Bash(git status:*)'],
+  assert.deepEqual(out.allow, ['Bash(npx bongos ship:*)', 'Bash(npx bongos exec scripts/gds/me.js:*)', 'Bash(git status:*)'],
     'allow takes the ONE spelling the skills use, and two spellings of a command collapse to one rule');
   // An instance can reach a script two ways — `bongos release` and `bongos exec scripts/gds/release.js` —
   // so a restrictive rule that named only one would still LOOK like a guard while guarding half.
-  assert.deepEqual(out.deny, ['Bash(bongos release:*)', 'Bash(bongos exec scripts/gds/release.js:*)', 'Bash(bongos exec scripts/gds/me.js:*)', 'Read(./.env)']);
-  assert.deepEqual(out.ask, ['Bash(bongos claim:*)', 'Bash(bongos exec scripts/gds/claim.js:*)']);
+  assert.deepEqual(out.deny, ['Bash(npx bongos release:*)', 'Bash(npx bongos exec scripts/gds/release.js:*)', 'Bash(npx bongos exec scripts/gds/me.js:*)', 'Read(./.env)']);
+  assert.deepEqual(out.ask, ['Bash(npx bongos claim:*)', 'Bash(npx bongos exec scripts/gds/claim.js:*)']);
   assert.equal(out.defaultMode, 'acceptEdits', 'a non-list permission key passes through untouched');
   rmSync(dir, { recursive: true, force: true });
 });
@@ -222,7 +222,7 @@ t('copyTreeTransformed: overwrite:false LEAVES a pre-existing dest file (reports
   const res = m.copyTreeTransformed(src, dest, { overwrite: false });
   assert.equal(res.files, 1, 'only the absent file was written');
   assert.deepEqual(res.skipped, ['b.md']);
-  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'bongos ship 1', 'absent file materialized + rewritten');
+  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'npx bongos ship 1', 'absent file materialized + rewritten');
   assert.equal(readFileSync(join(dest, 'b.md'), 'utf8'), ownerB, 'pre-existing file left byte-untouched');
   rmSync(src, { recursive: true, force: true });
   rmSync(dest, { recursive: true, force: true });
@@ -236,7 +236,7 @@ t('copyTreeTransformed: overwrite defaults true → greenfield still clobbers (r
   const res = m.copyTreeTransformed(src, dest);       // default overwrite:true
   assert.equal(res.files, 1);
   assert.deepEqual(res.skipped, []);
-  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'bongos start', 'greenfield overwrites as before');
+  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'npx bongos start', 'greenfield overwrites as before');
   rmSync(src, { recursive: true, force: true });
   rmSync(dest, { recursive: true, force: true });
 });
@@ -772,8 +772,8 @@ t('every allow-rule names a verb the CLI actually registers', () => {
   const checkedByTool = {};
   for (const rule of m.STARTER_ALLOW) {
     const [, tool, inner] = rule.match(/^(\w+)\((.*?)(?::\*)?\)$/); // any shell tool (task 1004014)
-    if (!inner.startsWith('bongos ')) continue; // the git/gh reads (task 1003992) name no verb
-    const verb = inner.split(' ')[1];
+    if (!inner.startsWith('npx bongos ')) continue; // the git/gh reads (task 1003992) name no verb
+    const verb = inner.split(' ')[2];
     assert.ok(cliVerbs[verb], `allow-rule "${rule}" names "${verb}", which is not a registered bongos verb`);
     checkedByTool[tool] = (checkedByTool[tool] || 0) + 1;
   }
@@ -784,7 +784,7 @@ t('every allow-rule names a verb the CLI actually registers', () => {
 t('the escape hatch is NOT blanket-allowed', () => {
   // `bongos exec` runs any script inside the core by path. Allow-listing it bare
   // would be a blanket grant wearing a narrow rule's clothes.
-  assert.deepEqual(m.STARTER_ALLOW.filter((r) => /^\w+\(bongos exec(:\*| \*)?\)$/.test(r)), [],
+  assert.deepEqual(m.STARTER_ALLOW.filter((r) => /^\w+\((?:npx )?bongos exec(:\*| \*)?\)$/.test(r)), [],
     'bongos exec must never be allowed bare — under any shell tool');
   const execRules = m.STARTER_ALLOW.filter((r) => r.includes('bongos exec'));
   for (const r of execRules) {
@@ -1065,7 +1065,7 @@ t('a checkout-materialized instance gets allow-rules in the bongos form, end to
   const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
   assert.equal(res.settings, true);
   const allow = JSON.parse(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8')).permissions.allow;
-  assert.deepEqual(allow, ['Bash(bongos claim:*)', 'Bash(bongos exec scripts/gds/api.js:*)', 'Bash(gh pr list:*)']);
+  assert.deepEqual(allow, ['Bash(npx bongos claim:*)', 'Bash(npx bongos exec scripts/gds/api.js:*)', 'Bash(gh pr list:*)']);
   for (const rule of allow) assert.ok(m.STARTER_ALLOW.includes(rule), `${rule} is the starter's spelling too — one form, two sources`);
   rmSync(core, { recursive: true, force: true });
   rmSync(inst, { recursive: true, force: true });
@@ -1154,5 +1154,182 @@ t('materializeClaude: a broken core settings.json reaches the instance unchanged
   rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- task 1004621: a project runs the CLI as `npx bongos`, never a bare `bongos` ---------------
+// The bin ships at node_modules/.bin/bongos, which is not on PATH, so every bare `bongos …` a
+// project's assistant read was a guaranteed `command not found` on the session's first call.
+
+// A bare `bongos <verb>` (not preceded by `npx `) anywhere in text an assistant reads.
+const BARE_VERB = new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${Object.keys(cliVerbs).join('|')})(?![\w-])`);
+
+t('bongosify: a hand-written bare `bongos <verb>` takes the npx spelling too', () => {
+  assert.equal(m.bongosify('paste `bongos paste-token <token>` back'), 'paste `npx bongos paste-token <token>` back');
+  assert.equal(m.bongosify('run bongos upgrade --to 1.2.3'), 'run npx bongos upgrade --to 1.2.3');
+  assert.equal(m.bongosify('`bongos exec scripts/gds/api.js GET /x`'), '`npx bongos exec scripts/gds/api.js GET /x`');
+});
+
+t('bongosify: never double-prefixes, and is idempotent over its own output', () => {
+  for (const s of ['npx bongos ship 1', 'node scripts/gds/ship.js 1', 'bongos ship 1', '`bongos dev` then `node scripts/gds/start.js`']) {
+    const once = m.bongosify(s);
+    assert.ok(!once.includes('npx npx'), `double prefix from: ${s}`);
+    assert.equal(m.bongosify(once), once, `a second run changed: ${s}`);
+    assert.ok(!BARE_VERB.test(once), `a bare bongos verb survived: ${once}`);
+  }
+});
+
+t('bongosify: names and prose that merely contain "bongos" are left alone', () => {
+  for (const s of ['`@bongos/core`', '/bongos-feedback', '`bongos: command not found`', 'the Bongos status page',
+    'the bongos CLI', 'the bongos database', 'src/bongos/routes/x.js', 'GET /api/bongos/me', 'bongos-ship-card']) {
+    assert.equal(m.bongosify(s), s, s);
+  }
+});
+
+t('every core skill + routine, as a project receives it, carries no bare `bongos <verb>`', () => {
+  const offenders = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      if (!/\.(md|txt|sh)$/.test(e.name)) continue;
+      const out = m.bongosify(readFileSync(p, 'utf8'));
+      if (out.includes('npx npx')) offenders.push(`${relative(ROOT, p)}: npx npx`);
+      const hit = out.match(BARE_VERB);
+      if (hit) offenders.push(`${relative(ROOT, p)}: ${hit[0]}`);
+    }
+  };
+  walk(join(ROOT, '.claude', 'skills'));
+  walk(join(ROOT, '.claude', 'scheduled-tasks'));
+  assert.deepEqual(offenders, []);
+});
+
+t('the core checkout\'s OWN skills are not rewritten: they still run node scripts/gds/*.js', () => {
+  const ship = readFileSync(join(ROOT, '.claude', 'skills', 'builder-ship', 'SKILL.md'), 'utf8');
+  assert.match(ship, /node scripts\/gds\/ship\.js/, 'the source skill keeps the checkout spelling');
+  assert.ok(!ship.includes('npx bongos ship'), 'npx only appears on the way INTO a project');
+});
+
+t('the starter allow-list is the npx spelling: no rule for a bare `bongos` nothing runs', () => {
+  const bongosRules = m.STARTER_ALLOW.filter((r) => /bongos /.test(r));
+  assert.ok(bongosRules.length > 10, 'the blessed commands are there');
+  for (const r of bongosRules) assert.match(r, /^\w+\(npx bongos [a-z]/, `not the npx spelling: ${r}`);
+  assert.ok(m.STARTER_ALLOW.includes('Bash(npx bongos ship:*)') && m.STARTER_ALLOW.includes('PowerShell(npx bongos ship:*)'));
+});
+
+t('the starter CLAUDE.md names only `npx bongos …` commands and keeps the npm install first-run note', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } });
+  assert.equal(md.match(BARE_VERB), null, 'a bare bongos command is a command-not-found in a project');
+  assert.ok(md.includes('npx bongos start') && md.includes('npx bongos ship') && md.includes('npx bongos doctor'));
+  assert.ok(md.indexOf('npm install') < md.indexOf('npx bongos start'), 'npm install still comes first');
+  assert.match(md, /not on your PATH/, 'says WHY it runs through npx');
+});
+
+// The pre-1004621 starter, rebuilt from the template by undoing each refresh pair. If the template
+// changes a CLI sentence without adding its pair, this round trip stops being exact and fails.
+const legacyStarter = (branding) => {
+  let md = tmpl.renderInstanceClaudeMd(branding);
+  for (const [legacy, current] of tmpl.LEGACY_CLI_LINES) md = md.split(current).join(legacy);
+  return md;
+};
+
+t('refreshStarterCliLines: an unedited old starter comes back byte-identical to today\'s', () => {
+  const b = { identity: { productName: 'Acme' }, domains: { buildersOrigin: 'https://b.acme.example.org' } };
+  const old = legacyStarter(b);
+  assert.ok(BARE_VERB.test(old), 'the fixture really is the old bare-bongos starter');
+  const r = tmpl.refreshStarterCliLines(old);
+  assert.equal(r.text, tmpl.renderInstanceClaudeMd(b));
+  assert.equal(r.changed, tmpl.LEGACY_CLI_LINES.length);
+  assert.deepEqual(tmpl.refreshStarterCliLines(r.text), { text: r.text, changed: 0 }, 'idempotent');
+});
+
+t('refreshStarterCliLines: an owner-reworded sentence and the rest of the file are left alone; CRLF works', () => {
+  const old = legacyStarter({ identity: { productName: 'Acme' } })
+    .replace('- **`bongos claim <id>`** locks a task to your session.', '- We claim with `bongos claim <id>` (our wording).')
+    + '\n## Our own notes\n\nKeep `bongos start` here verbatim.\n';
+  const r = tmpl.refreshStarterCliLines(old);
+  assert.ok(r.text.includes('- We claim with `bongos claim <id>` (our wording).'), 'an edited line is the owner\'s');
+  assert.ok(r.text.endsWith('\n## Our own notes\n\nKeep `bongos start` here verbatim.\n'), 'owner prose untouched');
+  assert.equal(r.changed, tmpl.LEGACY_CLI_LINES.length - 1);
+  const crlf = tmpl.refreshStarterCliLines(legacyStarter({ identity: { productName: 'Acme' } }).replace(/\n/g, '\r\n'));
+  assert.equal(crlf.changed, tmpl.LEGACY_CLI_LINES.length, 'a Windows (autocrlf) checkout is matched too');
+  assert.ok(!/(?<!\r)\n/.test(crlf.text), 'and keeps its CRLF endings');
+});
+
+// The upgrade path. `bongos upgrade` calls materializeClaude({ coreRoot, instanceDir, log }) —
+// default overwrite — after moving the pin (scripts/gds/upgrade.js), so an EXISTING project picks
+// all of this up on its next upgrade. This drives exactly that call against a project scaffolded
+// before task 1004621: old CLAUDE.md, the bare-`bongos` starter settings.json, old skills.
+function oldProjectFixture() {
+  const core = mkdtempSync(join(tmpdir(), 'npx-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'npx-inst-'));
+  mkdirSync(join(core, '.claude', 'skills', 'alpha'), { recursive: true }); // package-only: no settings.json at the core root
+  writeFileSync(join(core, '.claude', 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\n---\nrun `node scripts/gds/ship.js 1`, or paste `bongos paste-token <token>`\n');
+  mkdirSync(join(inst, '.claude', 'skills', 'alpha'), { recursive: true });
+  writeFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\n---\nrun `bongos ship 1`\n'); // what the old materialize wrote
+  writeFileSync(join(inst, 'CLAUDE.md'), legacyStarter({ identity: { productName: 'Acme' } }));
+  const oldAllow = m.STARTER_ALLOW.map((r) => r.replace('(npx bongos ', '(bongos '))
+    .filter((r) => r !== 'Bash(bongos recall:*)' && r !== 'PowerShell(bongos recall:*)'); // the owner removed one
+  writeFileSync(join(inst, '.claude', 'settings.json'), JSON.stringify({ permissions: { allow: oldAllow, deny: [] } }, null, 2));
+  const settings = () => JSON.parse(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'));
+  return { core, inst, oldAllow, settings, cleanup: () => { rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true }); } };
+}
+
+t('upgrade path: an existing project\'s skills, CLAUDE.md and allow-list all move to `npx bongos`', () => {
+  const f = oldProjectFixture();
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  const skill = readFileSync(join(f.inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8');
+  assert.match(skill, /`npx bongos ship 1`/);
+  assert.match(skill, /`npx bongos paste-token <token>`/);
+  assert.equal(skill.match(BARE_VERB), null);
+  const md = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  assert.equal(md, tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } }), 'the unedited starter sentences were refreshed');
+  assert.equal(res.claudeMdCliLines, tmpl.LEGACY_CLI_LINES.length);
+  assert.ok(res.writtenPaths.includes('CLAUDE.md'), 'reported, so the pin commit carries it');
+  const allow = f.settings().permissions.allow;
+  for (const r of f.oldAllow) assert.ok(allow.includes(r), `the owner's own rule is kept: ${r}`);
+  assert.ok(allow.includes('Bash(npx bongos ship:*)') && allow.includes('PowerShell(npx bongos ship:*)'), 'each bare rule gained its npx twin');
+  assert.ok(!allow.includes('Bash(npx bongos recall:*)'), 'a rule the owner removed is not brought back by its twin');
+  assert.equal(res.settingsAllowTwinsAdded.length, f.oldAllow.filter((r) => /\(bongos /.test(r)).length);
+  f.cleanup();
+});
+
+t('upgrade path: a second upgrade adds nothing more (no npx npx, no duplicate rule)', () => {
+  const f = oldProjectFixture();
+  m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  const after1 = readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8');
+  const md1 = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  const res2 = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  assert.equal(readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8'), after1);
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), md1);
+  assert.equal(res2.settingsAllowTwinsAdded, undefined);
+  assert.ok(!after1.includes('npx npx') && !md1.includes('npx npx'));
+  f.cleanup();
+});
+
+t('upgrade path: a dry run reports the changes and writes nothing', () => {
+  const f = oldProjectFixture();
+  const before = readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8');
+  const mdBefore = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: true, log: () => {} });
+  assert.ok(res.settingsAllowTwinsAdded.length > 0 && res.claudeMdCliLines > 0);
+  assert.equal(readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8'), before);
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), mdBefore);
+  assert.ok(!res.writtenPaths.includes('CLAUDE.md'), 'a content-preserving rewrite is not waived for the pre-flight');
+  f.cleanup();
+});
+
+t('adopt mode (overwrite:false) never touches the owner\'s CLAUDE.md', () => {
+  const f = oldProjectFixture();
+  const mdBefore = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, overwrite: false, log: () => {} });
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), mdBefore);
+  f.cleanup();
+});
+
+t('topUpNpxAllowTwins: an unreadable shape is reported, never rewritten', () => {
+  assert.match(m.topUpNpxAllowTwins('{nope').reason, /not valid JSON/);
+  assert.match(m.topUpNpxAllowTwins('{"permissions":{"allow":"x"}}').reason, /permissions\.allow/);
+  assert.deepEqual(m.topUpNpxAllowTwins('{"permissions":{"allow":["Bash(git status:*)"]}}'), { text: null, added: [], reason: null });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/cli_allowlist_permissions.mjs

@@ -308,8 +308,12 @@ perTool('the read-only subset is pre-allowed', (tool) => {
   }
 });
 
-test('the instance starter mirrors this list in verb form (claude-materialize.js STARTER_ALLOW)', () => {
-  assert.deepEqual([...STARTER_ALLOW].sort(), allowList().map((rule) => bongosify(rule)).sort());
+// Compared as SETS: the core carries both `node scripts/gds/paste-token.js:*` (what its skills
+// run) and `npx bongos paste-token:*` (what Settings → CLI access hands out, task 1004575), and
+// in a project both are the one `npx bongos paste-token:*` rule (task 1004621).
+test('the instance starter mirrors this list in its `npx bongos` form (claude-materialize.js STARTER_ALLOW)', () => {
+  assert.equal(new Set(STARTER_ALLOW).size, STARTER_ALLOW.length, 'the starter carries no duplicate rule');
+  assert.deepEqual([...STARTER_ALLOW].sort(), [...new Set(allowList().map((rule) => bongosify(rule)))].sort());
 });
 
 console.log('');

package/tests/cli_surface.mjs

@@ -49,9 +49,9 @@ test('the surface is never inferred from isTTY', () => {
 
 test('actions name a command the reader can actually run', () => {
   assert.equal(surface.action('ship', 123, AGENT_ENV), '/builder-ship 123');
-  assert.equal(surface.action('ship', 123, TERM_ENV), 'bongos ship 123');
+  assert.equal(surface.action('ship', 123, TERM_ENV), 'npx bongos ship 123'); // not on PATH in a project (task 1004621)
   assert.equal(surface.action('start', null, AGENT_ENV), '/builder-start');
-  assert.equal(surface.action('start', null, TERM_ENV), 'bongos start');
+  assert.equal(surface.action('start', null, TERM_ENV), 'npx bongos start');
 });
 
 test('task refs stay hall links for agents and go plain for terminals', () => {

package/tests/fixtures/page-ledger.mjs

@@ -231,6 +231,11 @@ export function installPageLedger(api, { builders }) {
       for (const x of hit) Object.assign(x, { status: 'resolved', resolved_task_id: String(p[1]), resolved_by: String(p[2]), resolution_note: p[4] });
       return { rows: hit.map((x) => ({ id: x.id })) };
     }
+    // createTask's spec-task lookup (task 1004585, goal-spec-task.js): a page's tweak
+    // goal is never made in the hall form, so it has no spec task and gates nothing.
+    if (/^SELECT id FROM tasks WHERE goal_id = \$1 AND source = \$2 AND source_ref = \$3/.test(q)) {
+      return { rows: db.tasks.filter((t) => t.goal_id === p[0] && t.source === p[1] && t.source_ref === p[2] && !['shipped', 'abandoned'].includes(t.status)).map((t) => ({ id: t.id })) };
+    }
     throw new Error(`unexpected SQL: ${q.slice(0, 160)}`);
   }
 

package/tests/goal_admission_override.mjs

@@ -156,7 +156,7 @@ test('reading a goal shows whether it was admitted', () => {
 });
 
 test('the create response says whether the override took effect', () => {
-  assert.match(postGoals(), /admitted \}\);/);
+  assert.match(postGoals(), /admitted(, spec_task: specTask)? \}\);/);
 });
 
 // ---- ADR 0250 §3: the exception is counted, or it is not an exception --------

package/tests/goal_category.mjs

@@ -169,7 +169,7 @@ test('the advisory is advice on a 201, never a refusal', () => {
   // and never fails the create over it (best-effort, wrapped in try).
   const routes = read('modules', 'lifecycle', 'routes', 'goals.js');
   assert.match(routes, /category_advisory = goalCategory\.adviseCategory/);
-  assert.match(routes, /res\.status\(201\)\.json\(\{ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted \}\)/,
+  assert.match(routes, /res\.status\(201\)\.json\(\{ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted(, spec_task: specTask)? \}\)/,
     'it rides the 201 — advice appended to a request that already succeeded');
 });
 

package/tests/goal_create_spec_entry.mjs

@@ -0,0 +1,61 @@
+// tests/goal_create_spec_entry.mjs — /goal-create's "finish a hall-made goal's spec
+// task" entry (task 1004586, ADR 0366 D3) names real routes, fields and identifiers.
+// A skill is prose an agent follows literally; when the code it cites moves, the agent
+// follows a path that no longer exists. So every load-bearing claim in the new section
+// is held against the code it describes, not against a copy of it.
+//
+// Run:  node --test tests/goal_create_spec_entry.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require_ = createRequire(import.meta.url);
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const skill = read('.claude/skills/goal-create/SKILL.md');
+const section = skill.slice(skill.indexOf("## Finishing a hall-made goal's spec task"), skill.indexOf('## The sibling advisory'));
+const spec = require_(path.join(ROOT, 'modules/lifecycle/goal-spec-task.js'));
+const goalsRoutes = read('modules/lifecycle/routes/goals.js');
+
+test('the section exists and the description carries its trigger', () => {
+  assert.ok(section.length > 500, 'the spec-task section is present');
+  assert.match(skill.split('\n---')[0], /"spec goal N"/, 'the trigger phrase is in the description');
+});
+
+test('the spec task it tells you to find is the one the server files', () => {
+  assert.match(section, /`source: goal-spec`/);
+  assert.equal(spec.SPEC_SOURCE, 'goal-spec');
+  assert.match(section, /`source_ref: goal-<N>-spec`/);
+  assert.equal(spec.specSourceRef(7), 'goal-7-spec');
+  assert.match(spec.specTaskFields({ id: 7, version_id: 'V', title: 't' }).title, /^Spec goal 7: its scope, criteria and first tasks$/);
+  assert.match(section, /"Spec goal N: its scope, criteria and first tasks"/);
+});
+
+test('the scope write it names is the real route and body', () => {
+  assert.match(section, /POST \/api\/bongos\/goals\/<N>\/scope --body '\{"add":\["<key>"\]\}'/);
+  assert.match(goalsRoutes, /router\.post\('\/goals\/:id\/scope'/);
+  const scopeRoute = goalsRoutes.slice(goalsRoutes.indexOf("router.post('/goals/:id/scope'"));
+  assert.match(scopeRoute.slice(0, 3000), /add:/, 'the route reads an `add` list');
+});
+
+test('"do not promote them" is true: new tasks in the goal wait on the open spec task', () => {
+  assert.match(section, /do not promote them/);
+  assert.match(read('modules/lifecycle/db-tasks.js'), /await gateOnSpecTask\(rows\[0\], deps\.client \|\| pool\)/);
+});
+
+test('the strict-fields note lists spec_task and the validator accepts it', () => {
+  assert.match(skill, /plus admit_reason[\s\S]{0,40}and spec_task, which ONLY the hall form sends/);
+  assert.match(goalsRoutes, /spec_task: \{ type: 'boolean' \}/);
+  assert.match(goalsRoutes, /admit_reason: \{ type: 'string'/);
+});
+
+test('skill-lint passes on the edited skill (the same lint fitness runs in CI)', async () => {
+  const { spawnSync } = await import('node:child_process');
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'scripts/gds/skill-lint.js')], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(r.status, 0, `skill-lint failed:\n${r.stdout}\n${r.stderr}`);
+  assert.match(r.stdout, /0 error\(s\)/);
+});

package/tests/goal_spec_task.mjs

@@ -0,0 +1,197 @@
+// tests/goal_spec_task.mjs — a goal made in the hall carries its own spec task, and
+// its other work waits behind it (task 1004585, ADR 0366 D3). DB-free: the gate
+// against a SQL-aware fake client, createTask's hook through its own client seam, and
+// POST /goals through the assembled router. The real-Postgres half (the claim gate's
+// read and the ship-time auto-promotion) is tests/goal_spec_task_db.mjs.
+//
+// Run:  node --test tests/goal_spec_task.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+process.env.NODE_ENV = 'test';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require_ = createRequire(import.meta.url);
+const spec = require_(path.join(ROOT, 'modules/lifecycle/goal-spec-task.js'));
+
+// A fake client that knows one goal's spec task and records every edge written.
+function fakeClient({ specId = null, specStatus = 'ready' } = {}) {
+  const edges = [];
+  return {
+    edges,
+    async query(sql, params) {
+      const s = String(sql).replace(/\s+/g, ' ');
+      if (/SELECT id FROM tasks WHERE goal_id = \$1 AND source = \$2 AND source_ref = \$3/.test(s)) {
+        assert.match(s, /status NOT IN \('shipped', 'abandoned'\)/, 'only an OPEN spec task gates');
+        const open = specId != null && !['shipped', 'abandoned'].includes(specStatus);
+        return { rows: open && params[1] === spec.SPEC_SOURCE && params[2] === spec.specSourceRef(params[0]) ? [{ id: String(specId) }] : [] };
+      }
+      if (/INSERT INTO dependencies/.test(s)) {
+        assert.match(s, /VALUES \('task', \$1, 'task', \$2\)/, 'a plain task→task edge, the shape unsatisfiedDeps reads');
+        edges.push([Number(params[0]), Number(params[1])]);
+        return { rows: [] };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+test('the spec task is a ready spike in the goal, keyed for idempotency', () => {
+  const f = spec.specTaskFields({ id: 42, version_id: 'V9', title: 'Hall goal' }, { createdBy: 7 });
+  assert.equal(f.status, 'ready');
+  assert.equal(f.kind, 'spike');
+  assert.equal(f.goalId, 42);
+  assert.equal(f.versionId, 'V9');
+  assert.equal(f.source, 'goal-spec');
+  assert.equal(f.sourceRef, 'goal-42-spec');
+  assert.equal(f.createdBy, 7);
+  assert.match(f.title, /^Spec goal 42: /);
+  assert.match(f.description, /POST \/goals\/42\/scope/);
+  assert.match(f.description, /POST \/versions\/V9\/done-when/);
+});
+
+test('a task entering a goal with an open spec task waits on it', async () => {
+  const c = fakeClient({ specId: 500 });
+  assert.equal(await spec.gateOnSpecTask({ id: 501, goal_id: 42 }, c), 500);
+  assert.deepEqual(c.edges, [[501, 500]]);
+});
+
+test('the spec task never waits on itself', async () => {
+  const c = fakeClient({ specId: 500 });
+  assert.equal(await spec.gateOnSpecTask({ id: 500, goal_id: 42, source: 'goal-spec', source_ref: 'goal-42-spec' }, c), null);
+  assert.deepEqual(c.edges, []);
+});
+
+test('no edge when the goal has no spec task, or it shipped, or it was abandoned, or the task has no goal', async () => {
+  for (const c of [fakeClient(), fakeClient({ specId: 500, specStatus: 'shipped' }), fakeClient({ specId: 500, specStatus: 'abandoned' })]) {
+    assert.equal(await spec.gateOnSpecTask({ id: 501, goal_id: 42 }, c), null);
+    assert.deepEqual(c.edges, []);
+  }
+  const c = fakeClient({ specId: 500 });
+  assert.equal(await spec.gateOnSpecTask({ id: 501, goal_id: null }, c), null);
+});
+
+test('a MOVED task goes through the cycle-checked path, and a cycle leaves the move without the edge', async () => {
+  const calls = [];
+  const ok = await spec.gateOnSpecTask({ id: 501, goal_id: 42 }, fakeClient({ specId: 500 }), {
+    addTaskDependency: async (a, b) => { calls.push([a, b]); },
+  });
+  assert.equal(ok, 500);
+  assert.deepEqual(calls, [[501, 500]]);
+  const cyc = await spec.gateOnSpecTask({ id: 501, goal_id: 42 }, fakeClient({ specId: 500 }), {
+    addTaskDependency: async () => { throw { code: 'CYCLE', path: [500, 501] }; },
+  });
+  assert.equal(cyc, null);
+  await assert.rejects(spec.gateOnSpecTask({ id: 501, goal_id: 42 }, fakeClient({ specId: 500 }), {
+    addTaskDependency: async () => { throw { code: 'TASK_NOT_FOUND' }; },
+  }), (e) => e.code === 'TASK_NOT_FOUND', 'any other failure is not swallowed');
+});
+
+test('createTask itself adds the edge — every create vector inherits it', async () => {
+  const db = require_(path.join(ROOT, 'modules/lifecycle/db-tasks.js'));
+  const c = fakeClient({ specId: 500 });
+  const inner = c.query.bind(c);
+  c.query = async (sql, params) => {
+    if (/INSERT INTO tasks/.test(sql)) return { rows: [{ id: '777', goal_id: params[22], source: params[11], source_ref: params[12] }] };
+    return inner(sql, params);
+  };
+  const row = await db.createTask({ versionId: 'V9', goalId: 42, title: 'Build the page', kind: 'feature', discipline: 'engineer', creditsReward: 5 }, { client: c });
+  assert.equal(row.id, '777');
+  assert.deepEqual(c.edges, [[777, 500]]);
+});
+
+// ── POST /goals through the assembled router ─────────────────────────────────
+
+async function withGoalsServer(fn) {
+  const r2 = createRequire(import.meta.url);
+  const authPath = r2.resolve(path.join(ROOT, 'src/bongos/auth.js'));
+  const routePath = r2.resolve(path.join(ROOT, 'modules/lifecycle/routes/goals.js'));
+  const auth = r2(authPath);
+  const api = r2(path.join(ROOT, 'src/module-api.js'));
+  const db = r2(path.join(ROOT, 'modules/lifecycle/db.js'));
+  const saved = { rb: auth.requireBuilder, rp: auth.requirePermission, tx: api.withTx, gv: db.getVersion, cg: db.createGoal, ct: db.createTask };
+  const calls = { createGoal: [], createTask: [], tx: 0 };
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: 7, rank: 'metic' }; next(); };
+  auth.requirePermission = () => (_req, _res, next) => next();
+  const txClient = { query: async () => ({ rows: [] }) };
+  api.withTx = async (f) => { calls.tx += 1; return f(txClient); };
+  db.getVersion = async (id) => ({ id, status: 'planning' });
+  db.createGoal = async (fields, deps = {}) => { calls.createGoal.push({ fields, client: deps.client || null }); return { id: 42, version_id: fields.versionId, title: fields.title }; };
+  db.createTask = async (fields, deps = {}) => { calls.createTask.push({ fields, client: deps.client || null }); return { id: 500, ...fields }; };
+  delete r2.cache[routePath];
+  const express = r2('express');
+  const { attachFail } = r2(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use(r2(routePath)());
+  const server = app.listen(0);
+  await new Promise((res) => server.once('listening', res));
+  const post = (body) => fetch(`http://127.0.0.1:${server.address().port}/goals`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
+  });
+  try { await fn(post, calls, txClient); } finally {
+    server.close();
+    auth.requireBuilder = saved.rb; auth.requirePermission = saved.rp; api.withTx = saved.tx;
+    db.getVersion = saved.gv; db.createGoal = saved.cg; db.createTask = saved.ct;
+    delete r2.cache[routePath];
+  }
+}
+
+test('POST /goals with spec_task creates the goal and its spec task in ONE transaction', async () => {
+  await withGoalsServer(async (post, calls, txClient) => {
+    const res = await post({ version_id: 'V9', title: 'Hall goal', category_id: undefined, spec_task: true });
+    assert.equal(res.status, 201, await res.clone().text());
+    const body = await res.json();
+    assert.equal(calls.tx, 1);
+    assert.equal(calls.createGoal[0].client, txClient, 'the goal is written inside the transaction');
+    assert.equal(calls.createTask.length, 1);
+    assert.equal(calls.createTask[0].client, txClient, 'and so is its spec task');
+    assert.equal(calls.createTask[0].fields.sourceRef, 'goal-42-spec');
+    assert.equal(body.spec_task.id, 500);
+  });
+});
+
+test('POST /goals without spec_task behaves exactly as before', async () => {
+  await withGoalsServer(async (post, calls) => {
+    const res = await post({ version_id: 'V9', title: 'CLI goal' });
+    assert.equal(res.status, 201);
+    assert.equal(calls.tx, 0);
+    assert.equal(calls.createGoal[0].client, null);
+    assert.equal(calls.createTask.length, 0);
+    assert.equal((await res.json()).spec_task, null);
+  });
+});
+
+test('spec_task must be a boolean', async () => {
+  await withGoalsServer(async (post, calls) => {
+    const res = await post({ version_id: 'V9', title: 'Hall goal', spec_task: 'yes' });
+    assert.equal(res.status, 400);
+    assert.equal(calls.createGoal.length, 0);
+  });
+});
+
+test('ensureSpecTask is safe to run twice: the second run returns the first spec task and writes nothing', async () => {
+  // A stateful fake: the spec task the first run creates is what the second run's read finds.
+  const created = [];
+  const client = {
+    async query(sql, params) {
+      if (/SELECT id FROM tasks WHERE goal_id = \$1 AND source = \$2 AND source_ref = \$3/.test(String(sql).replace(/\s+/g, ' '))) {
+        const hit = created.find((t) => t.goalId === params[0] && t.source === params[1] && t.sourceRef === params[2]);
+        return { rows: hit ? [{ id: String(hit.id) }] : [] };
+      }
+      return { rows: [] };
+    },
+  };
+  const db = { createTask: async (fields) => { const t = { id: 600 + created.length, ...fields }; created.push(t); return t; } };
+  const goal = { id: 42, version_id: 'V9', title: 'Hall goal' };
+  const first = await spec.ensureSpecTask({ db, goal, client, createdBy: 7 });
+  const second = await spec.ensureSpecTask({ db, goal, client, createdBy: 7 });
+  assert.equal(first.created, true);
+  assert.equal(second.created, false);
+  assert.equal(second.specTask.id, first.specTask.id);
+  assert.equal(created.length, 1, 'exactly one spec task for the goal');
+});