@bongos/core 1.19.275 → 1.19.277

package/tests/idea_routing.mjs

@@ -32,7 +32,7 @@ process.env.NODE_ENV = 'test';
 
 const require = createRequire(import.meta.url);
 const routing = require('../modules/ideas/routing.js');
-const { decideLanding, routedPriority, DEFAULT_ROUTED_PRIORITY } = routing;
+const { decideLanding, authorizeRoutedLanding, routedPriority, DEFAULT_ROUTED_PRIORITY, PROTECTED_SCOPE_FLOOR } = routing;
 
 // The lifecycle port is how the ideas module reaches createTask (never an
 // import — the one-way module rule, ADR 0083). Register a stub provider, the
@@ -568,4 +568,291 @@ await test('route: NO goal_id is still the plain old capture — 201, no task',
   assert.ok('kind_auto' in r.body);
 });
 
+// =========================================================================
+// 7. R05 — ENFORCEMENT: the rank floor and the scope wall (task 1003066)
+//
+// R01 decided the queue status. This is the half that BINDS: a routed task
+// declares no touches[], so createTask's ADR 0084/0085 floor derives from an
+// empty list and comes out 'xenos' — a bug routed into a goal scoped to the
+// PROTECTED core was born claimable by a Xenos the moment anyone nodded it.
+// =========================================================================
+
+await test('authorizeRoutedLanding: a protected-scope goal raises the rank floor', () => {
+  // filerRank must be a trusted tier here: a sub-Metic is refused outright by the
+  // protected_scope rule above, so the floor is only reachable for Metic+.
+  const landing = { route: true, status: 'ready', reason: 'bug_trusted_filer' };
+  assert.deepEqual(
+    authorizeRoutedLanding({ landing, scopeProtected: true, filerRank: 'archon' }),
+    { ok: true, status: 'ready', requiresRank: PROTECTED_SCOPE_FLOOR }
+  );
+  assert.equal(PROTECTED_SCOPE_FLOOR, 'metic');
+  // An ordinary goal says NOTHING, so createTask derives the floor exactly as it
+  // does for every other create vector. Speaking only when there is something to
+  // say is what keeps this from becoming a second, competing floor.
+  assert.deepEqual(
+    authorizeRoutedLanding({ landing, scopeProtected: false, filerRank: 'xenos' }),
+    { ok: true, status: 'ready', requiresRank: null }
+  );
+});
+
+await test('authorizeRoutedLanding: protected scope refuses a sub-Metic outright', () => {
+  const landing = { route: true, status: 'backlog', reason: 'bug_awaiting_nod' };
+  for (const rank of ['xenos', 'thetes', null, undefined, '', 'archon-ish']) {
+    const out = authorizeRoutedLanding({ landing, scopeProtected: true, filerRank: rank });
+    assert.equal(out.ok, false, `rank ${JSON.stringify(rank)} must be refused`);
+    assert.equal(out.code, 'protected_scope');
+    assert.equal(out.details.required_rank, PROTECTED_SCOPE_FLOOR);
+  }
+  for (const rank of ['metic', 'archon', 'ARCHON']) {
+    const out = authorizeRoutedLanding({ landing, scopeProtected: true, filerRank: rank });
+    assert.equal(out.ok, true, `rank ${rank} may route into protected scope`);
+    assert.equal(out.requiresRank, PROTECTED_SCOPE_FLOOR, 'and is still floored');
+  }
+  // An ordinary goal is untouched by this rule — a Xenos routes there freely.
+  assert.equal(authorizeRoutedLanding({ landing, scopeProtected: false, filerRank: 'xenos' }).ok, true);
+});
+
+await test('authorizeRoutedLanding: the wall\'s verdict passes through UNCHANGED', () => {
+  // One definition of "out of scope" — the routed refusal is the authored
+  // refusal, code, reason and details included.
+  const wall = { ok: false, code: 'out_of_scope', reason: 'a path is outside', details: { out_of_scope: ['x'] } };
+  const out = authorizeRoutedLanding({
+    landing: { route: true, status: 'backlog', reason: 'soft_landing' },
+    scopeProtected: true, scopeCheck: wall,
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.code, 'out_of_scope');
+  assert.equal(out.reason, wall.reason);
+  assert.deepEqual(out.details, wall.details);
+  // And note the wall is checked BEFORE the floor is granted: a refused filing
+  // never returns a status at all.
+  assert.equal(out.status, undefined);
+});
+
+await test('authorizeRoutedLanding: fail-closed on a non-routing or absent verdict', () => {
+  for (const landing of [null, undefined, { route: false, reason: 'no_goal' }, {}]) {
+    const out = authorizeRoutedLanding({ landing });
+    assert.equal(out.ok, false, `landing ${JSON.stringify(landing)}`);
+    assert.equal(out.code, 'not_routing');
+  }
+  assert.equal(authorizeRoutedLanding().ok, false, 'no args ⇒ refuse');
+  assert.equal(authorizeRoutedLanding(null).ok, false, 'null ⇒ refuse, not a throw');
+});
+
+await test('a protected-scope goal stamps requires_rank=metic on the routed task', async () => {
+  // goal 1000071\'s own shape: scope includes `lifecycle`, which is protected.
+  reset();
+  const pool = fakePool(routableHandler({
+    goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas', 'hall-ui', 'discord', 'lifecycle'] }],
+  }));
+  const out = await captureIdea(
+    { title: 'broken', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'archon' },
+    { pool }
+  );
+  assert.equal(createTaskCalls[0].args.requiresRank, 'metic',
+    'a routed task in protected territory can never be claimed by a sub-Metic');
+  assert.equal(out.routing.requires_rank, 'metic', 'and the verdict says so out loud');
+});
+
+await test('an ordinary goal passes NO floor — createTask derives it, as for any vector', async () => {
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas'] }] }));
+  const out = await captureIdea(
+    { title: 'broken', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'archon' },
+    { pool }
+  );
+  assert.equal('requiresRank' in createTaskCalls[0].args, false, 'the key is absent, not null');
+  assert.equal(out.routing.requires_rank, null);
+});
+
+await test('a sub-Metic cannot route into PROTECTED scope at all — it is refused', async () => {
+  // The narc's major on the first R05 round: with no touches[] the protected-path
+  // arm had nothing to inspect, so a sub-Metic could MINT a row in the
+  // permission/ship/deploy core's queue and only the rank floor stopped them
+  // CLAIMING it. POST /goals/:id/tasks refuses that author outright, and
+  // admission refuses them the goal entirely — the routed path was the odd one
+  // out. Now it refuses too.
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['lifecycle'] }] }));
+  await assert.rejects(
+    () => captureIdea({ title: 'broken', kind: 'bug', goalId: 7, capturedBy: 9, filerRank: 'xenos' }, { pool }),
+    (e) => e.code === 'ROUTE_NOT_AUTHORIZED' && e.gate === 'protected_scope'
+  );
+  assert.equal(createTaskCalls.length, 0, 'no row lands in protected territory');
+  assert.ok(find(pool.queries, /^ROLLBACK$/));
+});
+
+await test('...and the refusal costs the filer nothing they had before', async () => {
+  // The whole reason refusing is acceptable: the SAME report with no goal_id
+  // still files, exactly as it always did. Nobody loses the ability to report.
+  reset();
+  const pool = fakePool((s) => (/INSERT INTO idea_inbox/.test(s)
+    ? { rows: [{ ...IDEA_ROW, status: 'open', suggested_goal_id: null }] } : null));
+  const idea = await captureIdea({ title: 'broken', kind: 'bug', capturedBy: 9, filerRank: 'xenos' }, { pool });
+  assert.equal(idea.routing.reason, 'no_goal');
+  assert.equal(createTaskCalls.length, 0);
+});
+
+await test('a Metic+ filing into protected scope routes, and the floor still applies', async () => {
+  // Refusal and floor are LAYERS, not alternatives: the sub-Metic is refused
+  // above; a trusted filer gets through and the task is still born metic-floored,
+  // so a later nod cannot hand it to a newcomer.
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['lifecycle'] }] }));
+  await captureIdea({ title: 'broken', kind: 'bug', goalId: 7, capturedBy: 1, filerRank: 'metic' }, { pool });
+  assert.equal(createTaskCalls[0].args.status, 'ready');
+  assert.equal(createTaskCalls[0].args.requiresRank, 'metic');
+});
+
+await test('THE FLOOR CLAMPS UPWARD ONLY — createTask takes max(derived, explicit)', () => {
+  // The hacker's minor: R05's security claim rests on createTask's clamp, which
+  // lives in an unmodified file the panel could not open inside its read budget.
+  // Pin the real function here so the claim is checked in, not asserted in prose.
+  const lifecycleDb = require('../modules/lifecycle/db.js');
+  const { highestRank, deriveRequiredRank } = lifecycleDb;
+  // An empty touches[] — every routed task — derives the xenos floor. That is the
+  // hole R05's explicit 'metic' fills.
+  assert.equal(deriveRequiredRank([], false), 'xenos');
+  // The clamp: an explicit value can only RAISE.
+  assert.equal(highestRank('xenos', 'metic'), 'metic', 'explicit metic beats a xenos floor');
+  assert.equal(highestRank('metic', 'xenos'), 'metic', 'and an explicit xenos CANNOT lower a metic floor');
+  assert.equal(highestRank('archon', 'metic'), 'archon', 'a derived archon floor survives a lower explicit value');
+  // Which is exactly the composition createTask performs on a routed task:
+  assert.equal(highestRank(deriveRequiredRank([], false), 'metic'), 'metic');
+});
+
+await test('declared touches INSIDE the goal are allowed, and land on the task', async () => {
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas'] }] }));
+  await captureIdea({
+    title: 'broken', kind: 'bug', goalId: 7, filerRank: 'archon',
+    touches: ['modules/ideas/inbox.js'],
+  }, { pool });
+  assert.deepEqual(createTaskCalls[0].args.touches, ['modules/ideas/inbox.js']);
+});
+
+await test('declared touches OUTSIDE the goal are refused by the real wall', async () => {
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas'] }] }));
+  await assert.rejects(
+    () => captureIdea({
+      title: 'broken', kind: 'bug', goalId: 7, filerRank: 'archon',
+      touches: ['src/bongos/auth.js'],
+    }, { pool }),
+    (e) => e.code === 'ROUTE_NOT_AUTHORIZED' && e.gate === 'out_of_scope'
+  );
+  assert.equal(createTaskCalls.length, 0, 'nothing is created');
+  assert.ok(find(pool.queries, /^ROLLBACK$/), 'and the transaction rolls back');
+});
+
+await test('a sub-Metic naming a PROTECTED path is refused by the wall too', async () => {
+  // `kernel` is itself a protected MODULE, so a sub-Metic filing there is stopped
+  // one step earlier by protected_scope. To see the protected-PATH wall bite on
+  // its own, the goal's scope must be unprotected while still covering a
+  // protected path — which is exactly what an ordinary goal owning `config/`
+  // looks like. Two independent walls, checked independently.
+  const kernelPathInOrdinaryScope = { ...LIVE_GOAL, scope_modules: ['ideas'] };
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [kernelPathInOrdinaryScope] }));
+  await assert.rejects(
+    () => captureIdea({
+      title: 'broken', kind: 'bug', goalId: 7, filerRank: 'xenos',
+      touches: ['src/bongos/auth.js'],
+    }, { pool }),
+    // Outside the ideas scope entirely, so the subset arm answers first — which is
+    // the wall's own documented order (subset before protected-path).
+    (e) => e.code === 'ROUTE_NOT_AUTHORIZED' && e.gate === 'out_of_scope'
+  );
+  assert.equal(createTaskCalls.length, 0);
+
+  // And a Metic+ filing into a PROTECTED-scope goal with a protected touch
+  // clears both walls and is still floored — proving rank, not the path, decides.
+  reset();
+  const pool2 = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['kernel'] }] }));
+  await captureIdea({
+    title: 'broken', kind: 'bug', goalId: 7, filerRank: 'archon',
+    touches: ['src/bongos/auth.js'],
+  }, { pool: pool2 });
+  assert.equal(createTaskCalls.length, 1);
+  assert.equal(createTaskCalls[0].args.requiresRank, 'metic', 'kernel is protected scope, so the floor still applies');
+});
+
+await test('NO touches means NO wall — reporting does not require naming files', async () => {
+  // The deliberate divergence from POST /goals/:id/tasks, which denies
+  // `empty_touches`. Demanding a blast radius as the price of reporting is the
+  // triage tax this goal removes; the protection moves to the rank floor.
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['kernel'] }] }));
+  const out = await captureIdea(
+    { title: 'something is broken and I do not know where', kind: 'bug', goalId: 7, filerRank: 'archon' },
+    { pool }
+  );
+  assert.equal(out.routing.routed, true, 'a report with no touches still routes');
+  assert.deepEqual(createTaskCalls[0].args.touches, []);
+});
+
+await test('MEMBERSHIP IS NOT REQUIRED — reporting is not authoring (documented divergence)', async () => {
+  // authorizeGoalTaskCreate refuses a non-member with not_a_member. The routed
+  // path deliberately does not, because C5 promises the filer never has to know
+  // the goal map and C1 that a bug filed ANYWHERE lands in its home. This test
+  // exists so a later change has to argue with it rather than quietly reinstate
+  // the wall: nothing in the routed path reads goal_members at all.
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas'] }] }));
+  const out = await captureIdea(
+    { title: 'broken', kind: 'bug', goalId: 7, capturedBy: 999, filerRank: 'archon' },
+    { pool }
+  );
+  assert.equal(out.routing.routed, true);
+  assert.equal(find(pool.queries, /goal_members/), undefined,
+    'no membership lookup happens on the routed path — by design, not by omission');
+});
+
+await test('the goal SCOPE is read in the same locked statement as its status', async () => {
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, scope_modules: ['ideas'] }] }));
+  await captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool });
+  const sel = find(pool.queries, /FROM goals g JOIN versions v/);
+  assert.match(norm(sel.sql), /g\.scope_modules/,
+    'so a rescope cannot land between the wall check and the insert');
+  assert.match(norm(sel.sql), /FOR SHARE OF g/);
+});
+
+// =========================================================================
+// 8. R05 — the NOD QUEUE: a soft landing nobody can see is a silent drop
+// =========================================================================
+
+await test('the nod queue asks for routed filings at backlog, oldest first', async () => {
+  const pool = fakePool((s) => (/FROM ideas_task_lineage/.test(s)
+    ? { rows: [{ task_id: 1, title: 't', kind: 'bug', status: 'backlog', goal_id: 7 }] } : null));
+  const rows = await inbox.listRoutedAwaitingNod({ limit: 5 }, { pool });
+  assert.equal(rows.length, 1);
+  const q = norm(find(pool.queries, /FROM ideas_task_lineage/).sql);
+  assert.match(q, /l\.origin = 'route'/, "scoped by LINEAGE, not by status alone — a task sits at backlog for many reasons");
+  assert.match(q, /t\.status = 'backlog'/);
+  assert.match(q, /ORDER BY t\.created_at ASC/, 'oldest first: the longest-waiting report is the most overdue');
+  assert.match(q, /i\.captured_by/, "and it carries the filer, for Q3's kind + who-filed-it copy");
+});
+
+await test('the nod count uses the SAME predicate as the list', async () => {
+  const pool = fakePool((s) => (/COUNT/.test(s) ? { rows: [{ n: 4 }] } : null));
+  assert.equal(await inbox.countRoutedAwaitingNod({ pool }), 4);
+  const q = norm(pool.queries[0].sql);
+  assert.match(q, /l\.origin = 'route'/);
+  assert.match(q, /t\.status = 'backlog'/);
+  // A pill that disagrees with its own rows is worse than no pill.
+});
+
+await test('GET /inbox/awaiting-nod is registered BEFORE /inbox/:id, or it is unreachable', async () => {
+  // Express matches in registration order. Declared after the wildcard, this
+  // route arrives as /inbox/:id with id='awaiting-nod' and 400s on parseId —
+  // a bug with no symptom except an empty card.
+  const router = require('../modules/ideas/routes/inbox.js')({});
+  const paths = router.stack.filter((l) => l.route).map((l) => l.route.path);
+  const iNod = paths.indexOf('/inbox/awaiting-nod');
+  const iParam = paths.indexOf('/inbox/:id');
+  assert.ok(iNod >= 0, 'the route exists');
+  assert.ok(iNod < iParam, `literal segment must precede the wildcard (got ${iNod} vs ${iParam})`);
+});
+
 summary('idea_routing');

package/tests/session_boundary_handoff.mjs

@@ -0,0 +1,184 @@
+// tests/session_boundary_handoff.mjs
+//
+// THE SESSION BOUNDARY — task 1003150 (goal 1000053 "Session efficiency").
+//
+// The mirror of that goal's session-START series (1002435-1002438): those
+// front-load what a session can know at open; this stops a session dragging what
+// it no longer needs at close. A shipped task is the one moment the system KNOWS
+// the work is finished, and the moment almost all of that context becomes dead
+// weight.
+//
+// TWO HALVES, both pinned here:
+//   1. ship-card.js handoffAdvice — PURE, so every branch is a real assertion with
+//      no card, no DB, no session.
+//   2. .claude/skills/builder-sequence/SKILL.md — a DOC-CONTRACT check. The skill
+//      is the only place the between-links handoff can live (a hook cannot clear a
+//      conversation), and a prose step with nothing asserting it is exactly the
+//      kind of instruction that gets tidied away in a later edit. This is the same
+//      posture as the fitness doc checks: assert the RULE is stated, not its wording.
+//
+// WHY A THRESHOLD TEST AT ALL. The failure mode here is not a crash, it is
+// wallpaper: advice that prints on every ship stops being read (the
+// deploy-divergence footer is the in-repo cautionary tale — 21 core versions of
+// identical warning that nobody acted on). So "stays silent on a normal ship" is
+// the assertion that matters most, and it is first.
+//
+// Run:  node tests/session_boundary_handoff.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const card = require('../modules/lifecycle/ship-card.js');
+const { handoffAdvice, HEAVY_SESSION_CACHED_TOKENS, buildCardModel, renderMonospaceCard, renderCardHtml } = card;
+
+const { test, summary } = makeRunner();
+
+// The three real sessions the threshold was calibrated against (2026-08-21).
+const MEASURED = { light: 11.3e6, dragging: 36.1e6, heavy: 78.1e6 };
+
+// =========================================================================
+// 1. handoffAdvice — the decision
+// =========================================================================
+
+await test('SILENT on an ordinary ship — the whole design rests on this', () => {
+  // Advice that fires every time is wallpaper. A short session must never see it.
+  for (const cached of [0, 1, 1e6, MEASURED.light, HEAVY_SESSION_CACHED_TOKENS - 1]) {
+    assert.equal(handoffAdvice({ stage: 'shipped', cachedTokens: cached }), null,
+      `${cached} cached must stay silent`);
+  }
+});
+
+await test('SPEAKS once the session is genuinely heavy', () => {
+  for (const cached of [HEAVY_SESSION_CACHED_TOKENS, MEASURED.dragging, MEASURED.heavy]) {
+    const advice = handoffAdvice({ stage: 'shipped', cachedTokens: cached });
+    assert.ok(advice, `${cached} cached should advise`);
+    assert.match(advice, /session-handoff/, 'and names the command that does something about it');
+    assert.match(advice, /fresh session/, 'and says what to do with it');
+  }
+});
+
+await test('the advice quotes the ACTUAL figure, so it is arguable', () => {
+  // A builder who disagrees can check the number rather than take it on faith.
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }), /78\.1M cached/);
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.dragging }), /36\.1M cached/);
+});
+
+await test('NEVER mid-task — resetting inside a claim is actively wrong', () => {
+  // Mid-task the context is what the work is standing on. Only a stage where the
+  // task has left the builder's hands may advise a reset.
+  for (const stage of ['claimed', 'review', 'built', 'completed', 'failed']) {
+    assert.equal(handoffAdvice({ stage, cachedTokens: MEASURED.heavy }), null,
+      `stage '${stage}' must not advise a reset`);
+  }
+  // ...and the two that may.
+  assert.ok(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }));
+  assert.ok(handoffAdvice({ stage: 'confirmed', cachedTokens: MEASURED.heavy }),
+    'confirmed counts: the task is out of the builder\'s hands even though it has not landed');
+});
+
+await test('hostile or absent input is silence, never a throw', () => {
+  // This runs inside the ship card. A card that CRASHES at the end of a
+  // successful ship would turn a landed task into a scary traceback.
+  for (const args of [undefined, {}, null, { stage: 'shipped' }, { stage: 'shipped', cachedTokens: null },
+    { stage: 'shipped', cachedTokens: 'lots' }, { stage: 'shipped', cachedTokens: NaN },
+    { stage: 'shipped', cachedTokens: -1 }, { stage: null, cachedTokens: 1e9 }]) {
+    assert.doesNotThrow(() => handoffAdvice(args), `${JSON.stringify(args)} must not throw`);
+    assert.equal(handoffAdvice(args), null, `${JSON.stringify(args)} ⇒ silence`);
+  }
+  assert.equal(handoffAdvice(null), null, 'explicit null ⇒ silence, not a crash');
+});
+
+await test('the threshold sits between the session that felt fine and the one that dragged', () => {
+  // Documents the calibration as an assertion: if someone retunes the constant,
+  // this says what the number was chosen to separate.
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS > MEASURED.light,
+    'the 11.3M session was fine and must stay quiet');
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS < MEASURED.dragging,
+    'the 36.1M session had begun to drag and should be caught');
+});
+
+// =========================================================================
+// 2. The card — the advice has to actually reach the builder
+// =========================================================================
+
+await test('a heavy ship card carries the nudge, in BOTH renderers', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1003150, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy, newTokens: 891e3, costUsd: 49.81 },
+  });
+  assert.ok(model.handoff, 'it is on the model');
+  const mono = renderMonospaceCard(model);
+  assert.match(mono, /heavy session/, 'terminal card shows it');
+  assert.match(mono, /Next →/, 'and it sits with the Next action it qualifies');
+  // Position matters: the nudge must come AFTER Next, as a qualifier, not above it.
+  assert.ok(mono.indexOf('Next →') < mono.indexOf('heavy session'), 'below the action, not shouting over it');
+  assert.match(renderCardHtml(model), /heavy session/, 'in-feed card shows it too');
+});
+
+await test('a normal ship card is BYTE-IDENTICAL to before the nudge existed', () => {
+  // The regression that matters: every ordinary ship must look exactly as it did.
+  const usage = { cachedTokens: MEASURED.light, newTokens: 262e3, costUsd: 8.06 };
+  const model = buildCardModel({ stage: 'shipped', taskId: 1003148, title: 'A task', usage });
+  assert.equal(model.handoff, null);
+  const mono = renderMonospaceCard(model);
+  assert.doesNotMatch(mono, /heavy session/);
+  assert.doesNotMatch(mono, /session-handoff/);
+  assert.doesNotMatch(renderCardHtml(model), /heavy session/);
+  // A card with no usage data at all (old breadcrumbs) must also stay clean.
+  const bare = buildCardModel({ stage: 'shipped', taskId: 1, title: 'A task' });
+  assert.equal(bare.handoff, null);
+  assert.doesNotMatch(renderMonospaceCard(bare), /heavy session/);
+});
+
+await test('the nudge is not a Usage/Deploy ROW — it is guidance, not a task fact', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy },
+  });
+  assert.equal(model.rows.some((r) => /heavy session/.test(String(r.v))), false,
+    'rows report facts about the TASK; this is advice about the SESSION');
+  assert.equal(model.facts.some((f) => /heavy session/.test(String(f.value))), false);
+});
+
+// =========================================================================
+// 3. /builder-sequence — the doc contract
+//
+// A hook cannot clear a conversation and /session-handoff is read-only, so the
+// runner skill is the ONLY place the between-links handoff can live. That makes
+// its prose load-bearing, and load-bearing prose needs a test.
+// =========================================================================
+
+const SEQ = fs.readFileSync(path.join(ROOT, '.claude/skills/builder-sequence/SKILL.md'), 'utf8');
+
+await test('the sequence runner states the between-links handoff step', () => {
+  assert.match(SEQ, /\/session-handoff/, 'it names the command');
+  assert.match(SEQ, /fresh session/i, 'and that the chain continues in a fresh one');
+  assert.match(SEQ, /heavy session/i, 'and the ship-card signal it keys off');
+});
+
+await test('...and tells the runner to STOP rather than claim the next link', () => {
+  // The failure mode: a runner that emits the prompt and then helpfully carries on
+  // in the same window has done the paperwork and none of the work.
+  assert.match(SEQ, /do not claim the next task in this window/i,
+    'the halt must be explicit — emitting a prompt and continuing anyway is the trap');
+});
+
+await test('...and says WHY, with the measurement, not just what', () => {
+  // An unexplained instruction is the first thing dropped in a later edit.
+  assert.match(SEQ, /re-?read/i, 'names the mechanism (context re-read per turn)');
+  assert.match(SEQ, /11\.3M|36\.1M|78\.1M/, 'carries the measured figures');
+  assert.match(SEQ, /durable|GDS/, 'and why a fresh window is safe: the chain state is durable');
+});
+
+await test('the runner is warned against running a chain to exhaustion', () => {
+  assert.match(SEQ, /What NOT to do/, 'the section exists');
+  assert.match(SEQ, /exhaustion|one window/i, 'and names the anti-pattern this step prevents');
+});
+
+summary('session_boundary_handoff');