@bongos/core 1.19.814 → 1.19.816

package/tests/discord_channels.mjs

@@ -24,6 +24,9 @@
 // Run:  node tests/discord_channels.mjs
 
 import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const ch = require('../modules/discord/discord-channels.js');
@@ -365,5 +368,168 @@ await t('the real config plans cleanly against an empty guild and never deletes'
   assert.ok(!ops.some((o) => String(o.op).startsWith('delete')), 'reconcile must never delete');
 });
 
+// ---- seeding channels.json from a live guild (task 1003841) ----------------
+//
+// WHY THESE EXIST. Seeding hangs on one subtle rule, and I read it wrong the
+// first time: an omitted `view` has TWO possible causes that look identical in
+// the config, and only one of them is a problem.
+//
+//   • the channel's view EQUALS its category's  -> omitted, NO warning  (fine)
+//   • the channel has no managed VIEW overwrite -> omitted, WITH a warning
+//
+// configFromSnapshot emits `view` only when it differs from the parent, because
+// the planner reads `ch.view || cat.view` and repeating the value is noise that
+// drifts later. So "the field is missing" is NOT evidence that a channel is
+// unmanaged — the WARNING is. These pin that distinction, because acting on the
+// wrong one means writing view values into the file that the module deliberately
+// omits, which is a diff against the guild rather than a record of it.
+
+const V_ALLOW = String(ch.VIEW_CHANNEL);
+const allowEveryone = [{ id: EVERYONE, type: 0, allow: V_ALLOW, deny: '0' }];
+const publicCat = (catOverwrites, chOverwrites) => ({
+  categories: [{ id: 'CAT_PUB', name: 'PUBLIC', overwrites: catOverwrites }],
+  channels: [{ id: 'CH_NEWS', type: 0, name: '📯-ship-news', parentId: 'CAT_PUB', topic: 'Ships land here.', overwrites: chOverwrites }],
+});
+
+await t('an omitted view means INHERITS when the channel matches its category — and warns nothing (task 1003841)', () => {
+  const { config, warnings } = ch.configFromSnapshot(publicCat(allowEveryone, allowEveryone), CTX);
+  const news = config.categories[0].channels[0];
+  assert.equal(news.view, undefined, 'a view identical to the category is deliberately omitted');
+  assert.deepEqual(warnings, [], 'and nothing is wrong, so nothing is warned about');
+});
+
+await t('an omitted view means UNMANAGED when the channel has no overwrite — and that WARNS (task 1003841)', () => {
+  // The distinguishing signal. Same missing field, different meaning.
+  const { config, warnings } = ch.configFromSnapshot(publicCat(allowEveryone, []), CTX);
+  assert.equal(config.categories[0].channels[0].view, undefined, 'also omitted — the config alone cannot tell them apart');
+  assert.equal(warnings.length, 1, 'but the warning does');
+  assert.match(warnings[0], /no VIEW overwrite/);
+});
+
+await t('the seeded file round-trips to ZERO ops for every channel that exists (task 1003841)', () => {
+  // The done-when, demonstrated rather than argued. Feeding the snapshot-derived
+  // config back against the same guild must plan to nothing — that is the whole
+  // correctness property of configFromSnapshot, and it is what makes committing
+  // the snapshot safe: applying it cannot edit a live channel.
+  const guild = publicCat(allowEveryone, allowEveryone);
+  const { config } = ch.configFromSnapshot(guild, CTX);
+  assert.deepEqual(ch.planChannelReconcile(guild, config, CTX).ops, [], 'a faithful snapshot is a no-op plan');
+});
+
+await t('writing view:everyone where the snapshot omitted it would ADD an op — which is why it is not written (task 1003841)', () => {
+  // The mistake this file avoids. Spelling out a value identical to the category
+  // is harmless to READ, but it is not what the module emits, and on a channel
+  // that genuinely lacks an overwrite it turns a record into an edit of the live
+  // guild. Pinned so nobody "tidies" the omitted fields back in.
+  const guild = publicCat(allowEveryone, []);
+  const spelled = {
+    categories: [{
+      name: 'PUBLIC', view: 'everyone',
+      channels: [{ key: 'ship-news', name: '📯-ship-news', view: 'everyone', topic: 'Ships land here.' }],
+    }],
+  };
+  const { ops } = ch.planChannelReconcile(guild, spelled, CTX);
+  assert.ok(ops.some((o) => o.op === 'edit-channel'), 'it edits the live channel');
+});
+
+await t('the committed file is the guild, plus board-room (task 1003841)', () => {
+  const cfg = ch.loadConfig();
+  const keys = cfg.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.ok(keys.length >= 15, `expected the seeded guild, got ${keys.length} channels`);
+  assert.ok(keys.includes('board-room'), 'board-room stays declared — the bot never deletes');
+  for (const cat of cfg.categories) {
+    assert.ok(cat.view, `category ${cat.name} needs a view`);
+    for (const c of cat.channels) assert.ok(c.key && c.name, 'every channel carries its key and real name');
+  }
+  // The four PUBLIC channels inherit deliberately; asserting they have no view
+  // is what stops a later edit from spelling them out and creating a diff.
+  const pub = cfg.categories.find((c) => c.name === 'PUBLIC');
+  assert.equal(pub.view, 'everyone');
+  for (const c of pub.channels) assert.equal(c.view, undefined, `${c.key} must inherit, not repeat, its category view`);
+});
+
+// ---- the config path on a DEPLOYED instance (task 1003973) ---------------
+//
+// channels.json describes ONE guild, so it is instance identity and is NOT
+// published in the neutral core (ADR 0062 §7). The module used to resolve it
+// against its OWN directory, which on a deployed instance is
+// node_modules/@bongos/core/modules/discord/ — the file is not there, readFileSync
+// threw ENOENT, computePlan() threw, and the route returned a bare 500 that was
+// indistinguishable from a bot outage. These pin both halves of the fix.
+
+await t('resolveConfigPath prefers the INSTANCE root over the core package', () => {
+  // Point the instance root somewhere that is NOT the core checkout and give it
+  // its own channels.json. If resolution still lands on the core copy, a deployed
+  // instance would read cloudbongos.com's channel names — the thing ADR 0062 §7
+  // forbids — so this must fail loudly rather than pass because the two roots
+  // happen to coincide in a single checkout.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-inst-1003973-'));
+  const own = path.join(root, 'docs', 'discord', 'channels.json');
+  fs.mkdirSync(path.dirname(own), { recursive: true });
+  fs.writeFileSync(own, JSON.stringify({ categories: [{ name: 'X', channels: [] }] }));
+  const prev = process.env.BONGOS_INSTANCE_ROOT;
+  process.env.BONGOS_INSTANCE_ROOT = root;
+  try {
+    assert.equal(ch.resolveConfigPath(), own,
+      'a deployed instance must read its OWN docs/discord/channels.json, not the core package copy');
+    assert.notEqual(ch.resolveConfigPath(), ch.CORE_CONFIG_PATH);
+    assert.deepEqual(ch.loadConfig().categories.map((c) => c.name), ['X'],
+      'loadConfig must follow the same resolution, not a stale module-scope constant');
+  } finally {
+    if (prev === undefined) delete process.env.BONGOS_INSTANCE_ROOT;
+    else process.env.BONGOS_INSTANCE_ROOT = prev;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  // and with no pointer set, a single checkout still resolves to the repo file
+  assert.ok(fs.existsSync(ch.resolveConfigPath()), 'the single-checkout path must still resolve');
+});
+
+await t('loadConfig on a missing file throws a TAGGED error naming the path', () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  assert.throws(() => ch.loadConfig(missing), (err) => {
+    assert.equal(err.code, 'CONFIG_NOT_FOUND', 'ENOENT must be tagged, not left as a raw fs error');
+    assert.equal(err.configPath, missing);
+    assert.ok(err.message.includes(missing), 'the message must name the path the operator should fix');
+    return true;
+  });
+});
+
+await t('computePlan with no config returns {ok:false, no_config} instead of throwing', () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  const deps = {
+    getGuild: () => ({ id: '1', channels: { cache: new Map() } }),
+    loadConfig: () => ch.loadConfig(missing),
+    loadRoleMap: () => ({}),
+  };
+  const r = ch.computePlan(deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_config', 'a missing layout file must be its own reason, never a thrown 500');
+  assert.equal(r.configPath, missing, 'the caller needs the path to report it');
+  assert.deepEqual(r.ops, []);
+});
+
+await t('reconcileChannels with no config returns {ok:false, no_config} and writes nothing', async () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  const deps = {
+    getGuild: () => ({ id: '1', channels: { cache: new Map() } }),
+    loadBotToken: () => 'tok',
+    loadConfig: () => ch.loadConfig(missing),
+    loadRoleMap: () => ({}),
+  };
+  const r = await ch.reconcileChannels(deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_config');
+  assert.equal(r.applied, 0);
+});
+
+await t('a non-ENOENT read failure still propagates — only ENOENT is tagged', () => {
+  // A directory reads as EISDIR: a genuine internal error must NOT be laundered
+  // into the friendly 'put the file here' path.
+  assert.throws(() => ch.loadConfig(os.tmpdir()), (err) => {
+    assert.notEqual(err.code, 'CONFIG_NOT_FOUND');
+    return true;
+  });
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/goal_suggest.mjs

@@ -199,13 +199,23 @@ await test('the handler clamps limit into a sane range', async () => {
 // confident answer and declines whenever "confident" is not available.
 // =========================================================================
 
-const fakeDb = ({ versions = [], goals = [], throws = null, calls = null } = {}) => ({
+const fakeDb = ({ versions = [], goals = [], throws = null, calls = null, criteria = null } = {}) => ({
   listVersions: async () => { if (throws === 'versions') throw new Error('boom'); return versions; },
   listGoals: async (args) => {
     if (calls) calls.push(args);
     if (throws === 'goals') throw new Error('boom');
     return goals;
   },
+  // task 1003859: the criterion prose the ranker reads alongside the title.
+  // Omitted (criteria: null) it is absent from the fake ENTIRELY, which is also
+  // the pinned shape for a db that predates this read.
+  ...(criteria ? {
+    listCriterionTextForGoals: async (ids) => {
+      if (throws === 'criteria') throw new Error('boom');
+      if (calls) calls.push({ criteriaFor: ids.map(String) });
+      return new Map(Object.entries(criteria));
+    },
+  } : {}),
 });
 
 const BUILDING = { id: 'BONGOS-V1', status: 'building' };
@@ -298,4 +308,141 @@ await test('suggestGoalForCapture: the catch-all is never offered as a home', as
   assert.equal(got, null, 'a bucket is not a workspace — dropped for EVERY open version, not just one');
 });
 
+// ---------------------------------------------------------------------------
+// ranking on DONE-WHEN CRITERIA (task 1003859)
+// ---------------------------------------------------------------------------
+//
+// The real failure: since ADR 0264 every open BONGOS-V2 goal is titled
+// 'Working area N — <subject>'. A subject word in a draft had nothing to overlap
+// in the title, every goal scored 0, and the suggester returned [] for every idea
+// walked at the 2026-09-12 triage — which also left suggested_goal_id NULL on
+// every filing. These reproduce that board rather than a convenient one.
+
+const WORKING_AREAS = [
+  { id: 1000091, title: 'Working area 7', scope_modules: [], version_id: 'BONGOS-V2' },
+  { id: 1000094, title: 'Working area 10', scope_modules: [], version_id: 'BONGOS-V2' },
+];
+const WA_CRITERIA = {
+  1000091: 'A release is published and an instance can move its pin to it. The grader runs and its findings are readable.',
+  1000094: 'Every authenticated route re-checks the caller rank. A credential never reaches a log.',
+};
+
+await test('the real board: title-only ranking scores every Working area goal ZERO', () => {
+  const got = suggestGoals(WORKING_AREAS, { title: 'the grader returns no findings' }, { versionId: 'BONGOS-V2', includeZero: true });
+  assert.deepEqual(got.map((g) => g.score), [0, 0],
+    'this is the bug, pinned: the naming convention left the ranker nothing to match');
+  assert.deepEqual(suggestGoals(WORKING_AREAS, { title: 'the grader returns no findings' }, { versionId: 'BONGOS-V2' }), [],
+    'and so the suggester returned nothing at all');
+});
+
+await test('with criteria, the same draft finds its goal, with the matched terms shown', () => {
+  const got = suggestGoals(
+    WORKING_AREAS,
+    { title: 'the grader returns no findings' },
+    { versionId: 'BONGOS-V2', criteriaByGoal: new Map(Object.entries(WA_CRITERIA)) }
+  );
+  assert.equal(got.length, 1, 'only the goal whose criteria talk about grading');
+  assert.equal(got[0].id, 1000091);
+  assert.ok(got[0].score > 0);
+  assert.ok(got[0].matched_terms.includes('grader'), `expected 'grader' among ${JSON.stringify(got[0].matched_terms)}`);
+});
+
+await test('a criterion match weighs LESS than the same word in the title', () => {
+  const byTitle = { id: 10, title: 'Grader health', scope_modules: [], version_id: 'BONGOS-V2' };
+  const byCriteria = { id: 11, title: 'Working area 7', scope_modules: [], version_id: 'BONGOS-V2' };
+  const got = suggestGoals(
+    [byCriteria, byTitle],
+    { title: 'grader' },
+    { versionId: 'BONGOS-V2', criteriaByGoal: new Map([['11', 'the grader runs nightly']]) }
+  );
+  assert.equal(got[0].id, 10, 'a goal NAMED for the subject still outranks one that merely mentions it');
+  assert.ok(got[0].score > got[1].score);
+});
+
+await test('a term in both title and criteria is counted ONCE, at the title weight', () => {
+  const g = { id: 12, title: 'Grader health', scope_modules: [], version_id: 'BONGOS-V2' };
+  const withCriteria = suggestGoals([g], { title: 'grader' }, { versionId: 'BONGOS-V2', criteriaByGoal: new Map([['12', 'grader grader grader']]) });
+  const without = suggestGoals([g], { title: 'grader' }, { versionId: 'BONGOS-V2' });
+  assert.equal(withCriteria[0].score, without[0].score, 'repeating itself must not inflate a goal');
+});
+
+await test('no criteriaByGoal: ranking is EXACTLY what it was before (the pure function stays DB-free)', () => {
+  const draft = { title: 'the hall sidebar collapses on mobile' };
+  const a = suggestGoals([HALL_GOAL, ECON_GOAL], draft, { versionId: 'BONGOS-V1' });
+  const b = suggestGoals([HALL_GOAL, ECON_GOAL], draft, { versionId: 'BONGOS-V1', criteriaByGoal: null });
+  assert.deepEqual(a, b);
+  assert.equal(a[0].id, 81);
+});
+
+await test('suggestGoalForCapture reads the criteria, so suggested_goal_id is populated on the real board', async () => {
+  const calls = [];
+  const got = await suggestGoalForCapture(
+    { title: 'the grader returns no findings', body: '' },
+    { db: fakeDb({ versions: [{ id: 'BONGOS-V2', status: 'building' }], goals: WORKING_AREAS, criteria: WA_CRITERIA, calls }) }
+  );
+  assert.ok(got, 'this returned NULL before task 1003859 — which is why suggested_goal_id was null on every filing');
+  assert.equal(got.id, 1000091);
+  assert.equal(got.version_id, 'BONGOS-V2');
+  assert.ok(calls.some((c) => c && c.criteriaFor), 'the criteria read must actually be issued');
+});
+
+await test('a criteria read that THROWS degrades to title-only ranking, never to a lost filing', async () => {
+  const got = await suggestGoalForCapture(
+    { title: 'the hall sidebar collapses on mobile', body: '' },
+    { db: fakeDb({ versions: [BUILDING], goals: [HALL_GOAL, ECON_GOAL], criteria: {}, throws: 'criteria' }) }
+  );
+  assert.ok(got, 'a bug report must survive a criteria read that fails');
+  assert.equal(got.id, 81, 'and still rank on what it can see');
+});
+
+await test('a db with NO listCriterionTextForGoals at all still works (older core, or a lean fake)', async () => {
+  const got = await suggestGoalForCapture(
+    { title: 'the hall sidebar collapses on mobile', body: '' },
+    { db: fakeDb({ versions: [BUILDING], goals: [HALL_GOAL, ECON_GOAL] }) }
+  );
+  assert.equal(got.id, 81);
+});
+
+// ---------------------------------------------------------------------------
+// a PRIVATE goal's criteria are never ranked on (task 1003859, grade round 1)
+// ---------------------------------------------------------------------------
+//
+// score + matched_terms make a ranker into a word-guessing oracle: one candidate
+// word per request tells you whether that word appears in the ranked text. The
+// suggester already exposes private goals' TITLES (GET /goals does too — a wider
+// status quo this task does not settle), but their done-when prose is a different
+// order of exposure, so the criteria read stops at the visibility line.
+
+const PRIVATE_GOAL = { id: 900, title: 'Working area 12', scope_modules: [], version_id: 'BONGOS-V2', visibility: 'private' };
+const PUBLIC_GOAL = { id: 901, title: 'Working area 13', scope_modules: [], version_id: 'BONGOS-V2', visibility: 'public' };
+
+await test('the criteria of a PRIVATE goal are never fetched — not even to rank', async () => {
+  const asked = [];
+  const db = {
+    listGoals: async () => [PRIVATE_GOAL, PUBLIC_GOAL],
+    listCriterionTextForGoals: async (ids) => { asked.push(...ids.map(String)); return new Map(); },
+  };
+  const res = fakeRes();
+  await goalSuggestHandler({ db, LIMITS: { TITLE: 200 } })(
+    { query: { version: 'BONGOS-V2', title: 'embargo' } }, res
+  );
+  assert.deepEqual(asked, ['901'], 'only the public goal may contribute criterion text');
+  assert.ok(!asked.includes('900'), 'a private goal must not be probeable one word at a time');
+});
+
+await test('a private goal still ranks on its TITLE — this narrows nothing that already worked', () => {
+  const got = suggestGoals([PRIVATE_GOAL], { title: 'working area 12' }, { versionId: 'BONGOS-V2' });
+  assert.equal(got.length, 1, 'the title-level status quo is a separate decision, left exactly as it was');
+});
+
+await test('every goal private ⇒ no criteria read is issued at all', async () => {
+  let called = 0;
+  const db = {
+    listGoals: async () => [PRIVATE_GOAL],
+    listCriterionTextForGoals: async () => { called++; return new Map(); },
+  };
+  await goalSuggestHandler({ db, LIMITS: { TITLE: 200 } })({ query: { version: 'BONGOS-V2', title: 'x y z' } }, fakeRes());
+  assert.equal(called, 0, 'a query with nothing rankable must not be issued');
+});
+
 summary();

package/tests/idea_cascade.mjs

@@ -0,0 +1,211 @@
+// tests/idea_cascade.mjs — the SECOND cross-role cascade: an ideator lands a Full
+// Idea, an engineer gets a scoping task (task 1003856, part 1's residue).
+//
+// The first cascade (artist-review-on-ship, task 1003549) is covered by
+// modules/lifecycle/tests/cascade.mjs. This file covers what the second one added:
+// a trigger that is not a ship. The mechanism was ship-only, and an idea reaching
+// grade 'full' emitted nothing at all — so the rule could not be a table entry.
+//
+// The runner guarantees are the same four the ship runner's header names, and the
+// one that matters most here is the first: an ideator grading their own idea must
+// never be able to fail on a follow-up task's account.
+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 require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const C = require(path.join(ROOT, 'modules', 'lifecycle', 'cascade.js'));
+
+const idea = (over = {}) => ({
+  id: '1001030',
+  title: 'Price swaps from mechanism',
+  grade: 'full',
+  status: 'open',
+  completeness_score: 4,
+  captured_by: '1000025',
+  suggested_goal_id: '1000095',
+  suggested_version: 'BONGOS-V2',
+  ...over,
+});
+
+const deps = (over = {}) => {
+  const created = [];
+  return {
+    created,
+    findTaskBySourceRef: async () => null,
+    createTask: async (spec) => { created.push(spec); return { id: '9001' }; },
+    ...over,
+  };
+};
+
+// ---------- the rule ----------
+test('the declaration is well-formed — a malformed rule is a wiring bug, not a silent skip', () => {
+  assert.deepEqual(C.validateCascades(C.IDEA_CASCADES), []);
+});
+
+test('a Full Idea matches, and files for the ENGINEER', () => {
+  const { matched, errors } = C.cascadesFor(idea(), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  assert.deepEqual(errors, []);
+  assert.equal(matched.length, 1);
+  assert.equal(matched[0].rule.discipline, 'engineer');
+  assert.match(matched[0].spec.title, /Scope the Full Idea: Price swaps from mechanism/);
+});
+
+test('a spark or quick idea does NOT match — Full is the hand-off point', () => {
+  for (const grade of ['quick', 'spark', undefined]) {
+    const { matched } = C.cascadesFor(idea({ grade }), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+    assert.equal(matched.length, 0, `grade=${grade} should not file a scoping task`);
+  }
+});
+
+test('a CLOSED idea does not file — triage got there first', () => {
+  for (const status of ['discarded', 'merged', 'promoted']) {
+    const { matched } = C.cascadesFor(idea({ status }), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+    assert.equal(matched.length, 0, `status=${status} should not file`);
+  }
+});
+
+test('a cascade-sourced idea cannot file another cascade — the anti-recursion guard', () => {
+  const { matched } = C.cascadesFor(idea({ source: C.CASCADE_SOURCE }), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  assert.equal(matched.length, 0);
+});
+
+// ---------- the generated task ----------
+test('the task inherits the version but NEVER the advisory goal hint', () => {
+  // idea_inbox.suggested_goal_id documents itself as "Strictly advisory: no rank
+  // check, no scope wall, and no payout may read it... The BINDING home for
+  // 'which goal' is tasks.goal_id". A generated task's goal IS binding, so
+  // inheriting it from the hint would be exactly the read that column forbids.
+  // A version is a label and carries no such rule.
+  const { matched } = C.cascadesFor(idea(), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  const spec = matched[0].spec;
+  assert.equal(spec.versionId, 'BONGOS-V2');
+  assert.equal(spec.goalId, null, 'an advisory hint must not place a task');
+  assert.equal(spec.allowCatchAll, true, 'so it lands in the catch-all and gets triaged like any other homeless work');
+});
+
+test('the hint is surfaced for a human rather than silently dropped', () => {
+  // Not acting on it is the rule; losing it would be a different mistake.
+  const body = C.fullIdeaScopingBody(idea());
+  assert.match(body, /routing hint/);
+  assert.match(body, /goal 1000095/);
+  assert.match(body, /advisory/);
+});
+
+test('an idea with no hint says nothing about goals at all', () => {
+  const body = C.fullIdeaScopingBody(idea({ suggested_goal_id: null }));
+  assert.doesNotMatch(body, /routing hint/);
+});
+
+test('a goal-less idea still opts into the catch-all rather than vanishing', () => {
+  // The exact regression task 1003598 closed for ships: under the goal guard a
+  // null goalId THROWS, and the throw is caught per-rule — so the task would
+  // disappear with only a console line.
+  const { matched } = C.cascadesFor(idea({ suggested_goal_id: null }), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  assert.equal(matched[0].spec.allowCatchAll, true);
+});
+
+test('the preamble says what actually happened — an idea was graded, not a task shipped', () => {
+  const { matched } = C.cascadesFor(idea(), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  const d = matched[0].spec.description;
+  assert.match(d, /idea 1001030 was graded Full/);
+  assert.doesNotMatch(d, /shipped/, 'the ship preamble would be a lie on this trigger');
+});
+
+test('the body tells the engineer what is already settled and what is being asked', () => {
+  const body = C.fullIdeaScopingBody(idea());
+  assert.match(body, /reached \*\*Full\*\*/);
+  assert.match(body, /completeness 4/);
+  assert.match(body, /What would building it actually touch/);
+  // A scoping that concludes "don't build it" is a real answer; say so.
+  assert.match(body, /why it should not be built/);
+});
+
+test('the source_ref pins one rule to one idea, so a re-grade cannot double-file', () => {
+  const { matched } = C.cascadesFor(idea(), C.IDEA_CASCADES, {}, C.TRIGGERS.idea);
+  assert.equal(matched[0].spec.sourceRef, C.cascadeSourceRef('engineer-scoping-on-full-idea', '1001030'));
+  assert.equal(matched[0].spec.source, C.CASCADE_SOURCE);
+});
+
+// ---------- the runner ----------
+test('the runner files the task from the event payload alone', async () => {
+  const d = deps();
+  const report = await C.runCascadesForIdea(idea(), d);
+  assert.deepEqual(report.errors, []);
+  assert.equal(report.created.length, 1);
+  assert.equal(d.created.length, 1);
+  assert.equal(d.created[0].discipline, 'engineer');
+});
+
+test('an already-filed cascade is SKIPPED, not filed twice', async () => {
+  const d = deps({ findTaskBySourceRef: async () => ({ id: '8001' }) });
+  const report = await C.runCascadesForIdea(idea(), d);
+  assert.equal(report.created.length, 0);
+  assert.deepEqual(report.skipped.map((s) => s.reason), ['already filed']);
+  assert.equal(d.created.length, 0);
+});
+
+test('a payload with no id is reported, never thrown', async () => {
+  const report = await C.runCascadesForIdea({}, deps());
+  assert.equal(report.created.length, 0);
+  assert.match(report.errors.join(' '), /carried no idea id/);
+});
+
+test('createTask throwing costs that rule its task and NOTHING else', async () => {
+  // Property 1: the ideator's grade is already written. A follow-up task failing
+  // must never surface as a failure of the thing that triggered it.
+  const d = deps({ createTask: async () => { throw new Error('db down'); } });
+  const report = await C.runCascadesForIdea(idea(), d);
+  assert.equal(report.created.length, 0);
+  assert.match(report.errors.join(' '), /db down/);
+});
+
+test('the runner never rejects, whatever the deps do', async () => {
+  const report = await C.runCascadesForIdea(idea(), { findTaskBySourceRef: async () => { throw new Error('boom'); }, createTask: async () => ({ id: '1' }) });
+  assert.ok(Array.isArray(report.errors) && report.errors.length > 0);
+});
+
+test('an injected reader that finds nothing is an error, not a silent fall-back', async () => {
+  const report = await C.runCascadesForIdea(idea(), deps({ getIdea: async () => null }));
+  assert.match(report.errors.join(' '), /not readable after grading/);
+  assert.equal(report.created.length, 0);
+});
+
+// ---------- the wiring, which fails silently when it breaks ----------
+const src = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+
+test('the event is in the catalog AND something dispatches it', () => {
+  // The catalog's own comment: widening it is deliberate and must land together
+  // with a real dispatcher. Both halves asserted, because either alone is dead.
+  assert.match(src('modules/agents/lib/validate.js'), /'idea\.graded\.full'/);
+  assert.match(src('modules/ideas/inbox.js'), /api\.emit\('idea\.graded\.full'/);
+});
+
+test('the emit carries the whole idea, not just an id', () => {
+  // The listener lives in lifecycle, which owns no idea table and has no read
+  // port for one — so a bare {id} payload would leave the rules nothing to match.
+  const inbox = src('modules/ideas/inbox.js');
+  assert.match(inbox, /const idea = await getIdea\(ideaId\)/);
+  assert.match(inbox, /\.\.\.\(idea \|\| \{\}\)/);
+});
+
+test('lifecycle subscribes to the idea trigger and tears it down again', () => {
+  const lc = src('modules/lifecycle/routes/lifecycle.js');
+  assert.match(lc, /api\.on\('idea\.graded\.full'/);
+  assert.match(lc, /if \(_ideaCascadeListenerOff\) _ideaCascadeListenerOff\(\)/);
+  // It must NOT reach into the ideas module's table to do it.
+  assert.doesNotMatch(lc, /getIdeaForCascade/, 'lifecycle must not query another module\'s rows');
+});
+
+test('the emit only fires on a REAL transition', () => {
+  // The UPDATE carries `AND grade = 'spark'`, so a no-op re-grade returns null.
+  // The emit is inside `if (graded)`, so it cannot repeat for one idea.
+  const inbox = src('modules/ideas/inbox.js');
+  const at = inbox.indexOf("api.emit('idea.graded.full'");
+  assert.ok(at > 0);
+  assert.match(inbox.slice(0, at).split('\n').slice(-25).join('\n'), /if \(graded\) \{/);
+});

package/tests/task_goal_required.mjs

@@ -134,11 +134,23 @@ test('cascade opts in ONLY when inheritance actually failed', () => {
   // general. A blanket `true` here would quietly re-open the hole for every
   // follow-up task the system files.
   const body = src('modules/lifecycle/cascade.js');
-  assert.match(body, /allowCatchAll: task\.goal_id == null,/);
+  // Pinned on the RULE, not on one spelling of it: task 1003856 added an
+  // idea-triggered cascade whose subject carries its goal as `suggested_goal_id`,
+  // so the condition legitimately grew a term. What must stay true is that the
+  // hatch is conditional and covers every source the spec can inherit from.
+  const hatch = (body.match(/allowCatchAll:.*$/m) || [''])[0];
+  assert.match(hatch, /task\.goal_id == null/, 'the hatch still turns on a missing inherited goal');
   assert.equal(/allowCatchAll: true/.test(body), false,
     'an unconditional hatch here would cover every cascade, not just the legacy ones');
-  assert.match(body, /goalId: task\.goal_id != null \? Number\(task\.goal_id\) : null,/,
-    'inheritance stays the primary path');
+
+  // Every field the spec inherits a goal FROM must also be a field the hatch
+  // checks, or a subject shape could arrive with a real goal and still opt into
+  // the catch-all — the hole this test exists to keep shut.
+  const goalLine = (body.match(/^\s*goalId:[\s\S]*?,$/m) || [''])[0];
+  assert.match(goalLine, /task\.goal_id != null \? Number\(task\.goal_id\)/, 'inheritance stays the primary path');
+  for (const field of (goalLine.match(/task\.[a-z_]*goal[a-z_]*/g) || [])) {
+    assert.ok(hatch.includes(field), `${field} is inherited as a goal but is not checked by the catch-all hatch`);
+  }
 });
 
 test('a goal-less parent does not silently lose its cascade task', async () => {