@bongos/core 1.19.816 → 1.19.818

package/modules/specialities/db.js

@@ -17,7 +17,8 @@ const exec = (executor) => executor || ((text, params) => pool.query(text, param
 
 const COLUMNS = `id, slug, name, discipline, summary, contract_md,
                  owner_kind, owner_builder_id, owner_project_id,
-                 visibility, sellable, created_by, created_at, updated_at`;
+                 visibility, sellable, offered, offered_by, offered_at,
+                 created_by, created_at, updated_at`;
 
 async function createSpeciality(row, executor) {
   const q = exec(executor);
@@ -225,8 +226,46 @@ async function taskDiscipline(taskId, executor) {
   return (r.rows[0] && r.rows[0].discipline) || null;
 }
 
+// Flip the recommendation. `offered_by` and `offered_at` are written together
+// with it so a suggestion always carries whose judgement it is — a builder
+// deciding whether to accept a standing instruction can see who stood behind it.
+// Clearing an offer clears the witness too rather than leaving a stale name on a
+// recommendation nobody is making any more.
+async function setOffered(id, { offered, builderId }, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `UPDATE specialities_catalog
+        SET offered = $2,
+            offered_by = CASE WHEN $2 THEN $3::bigint ELSE NULL END,
+            offered_at = CASE WHEN $2 THEN now() ELSE NULL END,
+            updated_at = now()
+      WHERE id = $1
+      RETURNING ${COLUMNS}, offered, offered_by, offered_at`,
+    [id, !!offered, builderId || null],
+  );
+  return r.rows[0] || null;
+}
+
+// Everything on offer that this viewer could see at all. The RULE that decides
+// what is actually suggested is specialities.offeredTo — this is the cheap
+// prefilter, exactly as listVisibleTo is for the catalogue.
+async function listOffered({ builderId, projectIds = [], discipline = null }, executor) {
+  const q = exec(executor);
+  const params = [builderId, projectIds.length ? projectIds : [null]];
+  let sql = `SELECT ${COLUMNS}, offered, offered_by, offered_at
+               FROM specialities_catalog
+              WHERE offered
+                AND (visibility = 'public'
+                     OR (owner_kind = 'builder' AND owner_builder_id = $1)
+                     OR (owner_kind = 'project' AND visibility = 'project' AND owner_project_id = ANY($2)))`;
+  if (discipline) { params.push(discipline); sql += ` AND discipline = $${params.length}`; }
+  sql += ' ORDER BY discipline ASC, name ASC';
+  const r = await q(sql, params);
+  return r.rows;
+}
+
 module.exports = {
-  UPDATABLE, taskDiscipline,
+  UPDATABLE, taskDiscipline, setOffered, listOffered,
   createSpeciality, getSpeciality, listVisibleTo, updateSpeciality,
   addDocument, listDocuments, getDocument, deleteDocument,
   linkLearning, countTraining,

package/modules/specialities/migrations/specialities_002_offered.sql

@@ -0,0 +1,57 @@
+-- specialities_002_offered.sql — a project OFFERS a speciality to its builders
+-- (task 1003972; the micro-roles residue of task 1003856, built on ADR 0296).
+--
+-- WHAT THIS IS. Task 1003855 let a builder or a project OWN a speciality and set
+-- who may adopt it. What it could not express is a recommendation: "this is the
+-- set we suggest you start from." That is what `offered` adds, and it is one
+-- column rather than a preset table because a preset IS a speciality — the list
+-- is just the specialities someone chose to put their name behind.
+--
+-- IT OFFERS. IT DOES NOT ADOPT. This is the whole design decision and it is not a
+-- convenience call. A speciality's `contract_md` is injected into every session
+-- where the adopter holds a claim in that craft, and ADR 0296's consent work
+-- (task 1003855's second grade) exists because that text is ANOTHER BUILDER'S
+-- text arriving in this builder's session. Auto-adopting a project's presets on
+-- join would hand every new builder a standing instruction they never read, which
+-- is precisely the failure that grade caught — so an offer is a suggestion a
+-- person accepts, every time, and there is no column here that could make it
+-- otherwise.
+--
+-- WHY NO MEMBERSHIP LOOKUP IS NEEDED FOR THE COMMON CASE. "Project" in the
+-- platform-identity sense is a HUB concept (ADR 0141 §3): a `client_id` in the
+-- hub's cross-project directory, keyed by `github_id`. A normal instance is not a
+-- hub and has no such rows — it simply IS the project. So an instance-level
+-- recommendation is a speciality at `visibility='public'` (already "anyone on
+-- this instance may adopt it") flagged `offered` — no membership resolution, no
+-- optional seam, nothing to be absent. The federated case rides the same column
+-- once the `project.membership` port exists: a project-owned speciality at
+-- `visibility='project'` and `offered` is a suggestion to that project's members.
+
+ALTER TABLE specialities_catalog
+  ADD COLUMN IF NOT EXISTS offered BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- You cannot recommend something nobody may adopt. Same shape as the `sellable`
+-- constraint beside it, and for the same reason: a private-but-offered row is
+-- incoherent rather than merely useless, and the DB is where that is cheapest to
+-- refuse. Named for what it protects.
+ALTER TABLE specialities_catalog
+  DROP CONSTRAINT IF EXISTS specialities_catalog_offered_needs_visibility;
+ALTER TABLE specialities_catalog
+  ADD CONSTRAINT specialities_catalog_offered_needs_visibility
+  CHECK (offered = FALSE OR visibility <> 'private');
+
+-- The suggestions read: "what does this instance/project recommend to me". Partial
+-- because the offered set is by nature small and the unoffered majority is never
+-- scanned by it.
+CREATE INDEX IF NOT EXISTS specialities_catalog_offered_idx
+  ON specialities_catalog (discipline) WHERE offered;
+
+-- WHO OFFERED IT, and when. Recorded because a recommendation carries someone's
+-- name by definition — the settings surface says who suggested it, so a builder
+-- deciding whether to accept a standing instruction can see whose judgement they
+-- are taking. Nullable: a row offered before this column existed has no witness,
+-- and inventing one would be worse than admitting it.
+ALTER TABLE specialities_catalog
+  ADD COLUMN IF NOT EXISTS offered_by BIGINT REFERENCES builders(id) ON DELETE SET NULL;
+ALTER TABLE specialities_catalog
+  ADD COLUMN IF NOT EXISTS offered_at TIMESTAMPTZ;

package/modules/specialities/routes/specialities.js

@@ -246,6 +246,22 @@ module.exports = function buildSpecialitiesRouter() {
     }
   }));
 
+  // GET /specialities/offered — the suggestions for THIS builder. Mounted before
+  // '/specialities/:id' would otherwise capture 'offered' as an id.
+  router.get('/specialities/offered', api.requireBuilder, asyncHandler('GET /specialities/offered', async (req, res) => {
+    const builder = req.builder;
+    const projectIds = await viewerProjectIds(builder);
+    const [rows, adoptions] = await Promise.all([
+      db.listOffered({ builderId: builder.id, projectIds, discipline: req.query.discipline || null }),
+      db.listAdoptions(builder.id),
+    ]);
+    // The SQL is the prefilter; offeredTo is the rule — it drops what this
+    // builder already holds and what would collide with a craft they have already
+    // chosen for. Nothing here adopts anything.
+    const suggestions = S.offeredTo(rows, { builderId: builder.id, projectIds }, adoptions);
+    res.json({ suggestions });
+  }));
+
   router.get('/specialities/:id', api.requireBuilder, asyncHandler('GET /specialities/:id', async (req, res) => {
     const id = parseId(req, res, { code: 'bad_id' });
     if (id === null) return;
@@ -371,6 +387,54 @@ module.exports = function buildSpecialitiesRouter() {
     res.json({ ok: true, was_active: dropped });
   }));
 
+  // ── offering: a project puts its name behind a speciality ─────────────────
+  //
+  // OFFERING IS CURATION, NOT OWNERSHIP, so it is gated differently from every
+  // other write here. Editing your own speciality is yours; recommending one to
+  // everybody on the instance is a claim on their attention and their sessions,
+  // which is the same act `project.curate` already governs for featuring a
+  // project (metic floor). An owner may therefore edit a speciality they cannot
+  // offer, and a curator may offer one they do not own — which is correct: the
+  // two decisions are about different things.
+  router.post('/specialities/:id/offer', api.requireBuilder, api.requirePermission('project.curate'),
+    asyncHandler('POST /specialities/:id/offer', async (req, res) => {
+      const id = parseId(req, res, { code: 'bad_id' });
+      if (id === null) return;
+      const s = await db.getSpeciality(id);
+      // visibleTo, like every sibling route. project.curate says "you may
+      // curate", NOT "you may curate this row" — without this a curator could
+      // offer a project-owned speciality belonging to a project they are not in,
+      // and the 403-vs-404 shape would confirm its existence besides.
+      if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+      // The DB refuses this too; refusing here as well turns a constraint
+      // violation into a sentence that says what to do about it.
+      if (s.visibility === 'private') {
+        return res.fail('offer_needs_visibility', {
+          status: 400,
+          message: 'A private speciality cannot be offered — nobody it is offered to could adopt it. Share it first.',
+        });
+      }
+      res.json({ speciality: await db.setOffered(id, { offered: true, builderId: req.builder.id }) });
+    }));
+
+  router.post('/specialities/:id/unoffer', api.requireBuilder, api.requirePermission('project.curate'),
+    asyncHandler('POST /specialities/:id/unoffer', async (req, res) => {
+      const id = parseId(req, res, { code: 'bad_id' });
+      if (id === null) return;
+      const s = await db.getSpeciality(id);
+      if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+      // Withdrawing a recommendation does NOT un-adopt anybody. A builder who
+      // accepted it chose it; taking that away silently would be the auto-adopt
+      // mistake in reverse.
+      //
+      // The actor is passed even though the row stores it only while an offer
+      // stands (setOffered nulls the witness on withdrawal, because a
+      // recommendation nobody is making has nobody behind it). WHO withdrew it is
+      // not lost: every authenticated POST through this router is recorded by
+      // src/bongos/middleware/audit.js with the builder, the body and the status.
+      res.json({ speciality: await db.setOffered(id, { offered: false, builderId: req.builder.id }) });
+    }));
+
   router.get('/me/specialities', api.requireBuilder, asyncHandler('GET /me/specialities', async (req, res) => {
     res.json({ adoptions: await db.listAdoptions(req.builder.id) });
   }));

package/modules/specialities/specialities.js

@@ -195,4 +195,33 @@ function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuth
   return { inject: contract.trim().length > 0, contract, speciality_id: active.id, slug: active.slug };
 }
 
-module.exports = { VISIBILITIES, LIMITS, slugify, validateDraft, canAdopt, describeForApi };
+// WHAT A BUILDER IS OFFERED. The suggestions half of task 1003972: a speciality
+// someone with project.curate has put the project's name behind.
+//
+// IT OFFERS, IT DOES NOT ADOPT — and this function is where that is enforced in
+// the read, not merely intended. It returns suggestions; nothing here adopts, and
+// the caller has no adoption path that does not go through the builder's own
+// explicit POST. A speciality's contract is injected into every session in its
+// craft, so handing someone a standing instruction they never accepted is the
+// exact failure ADR 0296's consent work exists to prevent.
+//
+// Three filters, in the order that makes each one cheap:
+//   1. offered      — somebody recommended it
+//   2. canAdopt     — and this viewer may actually take it (the SAME rule the
+//                     catalogue uses; never a second, looser copy)
+//   3. not already  — a speciality you already hold is not a suggestion, and one
+//                     in a craft you already have an ACTIVE speciality for is a
+//                     conflict rather than an offer (the adoption index allows one
+//                     active per craft), so it is surfaced as neither.
+function offeredTo(specialities, viewer, adoptions = []) {
+  const held = new Set((adoptions || []).map((a) => String(a.id ?? a.speciality_id)));
+  const activeCrafts = new Set((adoptions || []).filter((a) => a.active).map((a) => a.discipline));
+  return (specialities || []).filter((s) => {
+    if (!s || !s.offered) return false;
+    if (!canAdopt(s, viewer)) return false;
+    if (held.has(String(s.id))) return false;
+    return !activeCrafts.has(s.discipline);
+  });
+}
+
+module.exports = { VISIBILITIES, LIMITS, slugify, validateDraft, canAdopt, describeForApi, offeredTo };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.816",
+  "version": "1.19.818",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.816",
+      "version": "1.19.818",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.816",
+  "version": "1.19.818",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/category-advisory-guard.js

@@ -71,15 +71,56 @@ const FEATURE_ANCHORS = [
 // table name needs no boundary — nothing else is called that.
 const CATEGORY_RE = /\bcategor(y|ies|ised|ized|isation|ization)\b|\bcategory_id\b|work_categories/i;
 
-// Strip // line comments and /* */ blocks so a citation of the rule is legal and
-// only executable text is judged. Crude on purpose: it errs toward keeping text
-// (a `//` inside a string literal turns the rest of that line into a "comment"),
-// and erring toward keeping text would make the check LOUDER, not quieter — which
-// is the safe direction for a guard.
+// Strip // line comments and /* */ blocks so a citation of a rule is legal and only
+// executable text is judged.
+//
+// String-aware, and that is the whole point rather than a refinement. The direction
+// a stripper errs in is a safety property: keeping a comment only re-raises a false
+// alarm, which is LOUD and gets fixed, while dropping real code makes a guard report
+// clean over a live violation, which is indistinguishable from a tree that is
+// actually clean. So the scanner must never remove text it is not sure about.
+//
+// The previous regex pair claimed to err that way and did the opposite. `//` inside
+// an ordinary string literal — a protocol-relative URL, a path fragment — matched the
+// line-comment rule and erased the rest of the line, real code included:
+//
+//   router.post('//legacy', requirePermission('task.abandon.own'), handler);
+//
+// stripped to `router.post('`, so the guard scanning for that very call found nothing
+// (task 1003832; the equivalent hole in the ownership-scope scan in
+// tests/government_require_permission.mjs). Tracking quotes fixes it at the root, for
+// both callers, and makes the erring-toward-keeping promise above actually true.
+//
+// Unterminated constructs deliberately keep their text rather than swallowing to EOF.
+// A regex literal is not tracked: an unescaped `//` cannot appear in one (it would be
+// an empty regex), so the only way in is a `/`-delimited literal containing an escaped
+// pair, which reads as escaped here too.
 function stripComments(src) {
-  return src
-    .replace(/\/\*[\s\S]*?\*\//g, ' ')
-    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+  let out = '';
+  let quote = null; // ' " or ` — inside a string literal, nothing is a comment
+  for (let i = 0; i < src.length;) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (quote) {
+      if (c === '\\') { out += c + (d ?? ''); i += 2; continue; }
+      if (c === quote) quote = null;
+      out += c; i += 1; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i += 1; continue; }
+    if (c === '/' && d === '/') {
+      while (i < src.length && src[i] !== '\n') i += 1; // stop AT the newline, never past it
+      continue;
+    }
+    if (c === '/' && d === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) { out += src.slice(i); break; } // unterminated: keep it
+      out += ' ';
+      i = end + 2;
+      continue;
+    }
+    out += c; i += 1;
+  }
+  return out;
 }
 
 function readFromDisk(rel) {

package/scripts/gds/linkify-refs.js

@@ -115,6 +115,14 @@ const { API_BASE } = require('./cli-lib');
 // the root CLAUDE.md/README.md plus all of docs/** (session-logs included). A
 // "GENERATED FILE" marker means the bare refs reappear on the next regen, so
 // the generator — not its output — is where those get fixed; skip them here.
+// PATHS COME BACK POSIX-STYLE, on every platform (task 1003935). path.join gives
+// OS-native separators, so on Windows this used to return 'docs\\adr\\0001-….md'.
+// Three things read these paths and only one of them tolerates that: fs accepts
+// either separator on Windows, but the --check report PRINTS them (so CI output
+// differed by platform for identical content) and the test that pins recursion
+// into docs/ compares against 'docs/' — which is how a permanently-red case hid
+// for months in a file no lane ran. Normalising here, at the one boundary that
+// produces them, is cheaper than teaching every consumer to be separator-aware.
 function discoverDocs() {
   const out = [];
   const walk = (rel) => {
@@ -123,7 +131,7 @@ function discoverDocs() {
     if (fs.statSync(abs).isDirectory()) {
       for (const name of fs.readdirSync(abs).sort()) walk(path.join(rel, name));
     } else if (rel.endsWith('.md')) {
-      out.push(rel);
+      out.push(rel.split(path.sep).join('/'));
     }
   };
   for (const root of ['CLAUDE.md', 'README.md', 'docs']) walk(root);

package/scripts/gds/run-unit-tests.js

@@ -131,7 +131,14 @@ const INTEGRATION = new Set([
   // the --integration lane never saw them either, because it runs only this set. A
   // test that cannot fail in either lane is a file that looks like a gate.
   'handle_machinery', 'hub_profile_leak', 'profile_fields',
-  'linkify_refs', 'memory_isolation',
+  // task 1003935: 'linkify_refs' was swept in with the three above without the
+  // no-DB check they were being fixed for. It touches no Postgres at all — pure
+  // string work plus a filesystem walk — so the DB-free lane skipped it and the
+  // --integration lane, which runs only this set, never had a reason to. It ran in
+  // NEITHER lane, which is the exact failure the comment above describes, and it
+  // is why one permanently-red Windows case sat unnoticed. It is now in the unit
+  // gate, where it is the only coverage linkifyText has.
+  'memory_isolation',
   'memory_pull', 'needs_rebase', 'parallel-load', 'profile_rollup_consent',
   // task 1003145: whether the PLANNER uses the migration 225 index for the recall
   // freshness probe. The DB-free sibling (recall_corpus_health) pins the query

package/scripts/gds/stale-worktrees.js

@@ -13,6 +13,28 @@
 // deleted it). Both are pure git facts, so this runs in well under a second at
 // SessionStart. The primary checkout is never listed.
 //
+// THE THIRD LEAK — UNSTARTED CLAIM TREES (task 1003912). "Ancestor of origin/main"
+// is also true of a branch that is origin/main, which is exactly what
+// `worktree.js add` leaves behind: it branches off origin/main and commits
+// nothing. So between `worktree.js add` and the builder's FIRST COMMIT, a live
+// claim's worktree was reported as "merged into main". Observed 2026-09-13: the
+// session working task 1002594 saw its own tree listed as stale. The classifier
+// had the git fact right and the intent wrong — nothing had landed, nothing had
+// even started.
+//
+// That window is small and the consequence is not: /worktree-clean removes every
+// name on the stale list, so a cleanup run by another session (or the SessionStart
+// nag) inside it would take a live claim's tree. `worktree.js remove` refuses a
+// dirty tree, which bounds the damage — but a claim worktree that is still empty
+// is precisely the one that is NOT dirty, so the guard does not cover this case.
+//
+// The fix stays a pure git fact, keeping the "no API call" property this header is
+// explicit about wanting: a branch whose TIP EQUALS origin/main is zero commits
+// ahead, so it cannot have landed anything, and is reported live-but-unstarted.
+// The alternative — cross-checking branch names against active claims — would put
+// a network round trip in a SessionStart probe to learn something git already
+// knows.
+//
 // THE SECOND LEAK — HUSKS (task 1002594). Under OneDrive, `git worktree remove`
 // often errors 'Permission denied' / 'Device or resource busy' but still
 // DEREGISTERS the worktree, so `worktree.js remove` treats deregistration as
@@ -65,7 +87,12 @@ function parseWorktreeList(porcelain) {
 
 // Pure classifier so the decision is unit-testable without a repo: `isMerged(branch)`
 // and `branchExists(branch)` are the two git facts it needs.
-function classifyWorktrees(worktrees, { isMerged, branchExists }) {
+// `isUnstarted(branch)` is the task 1003912 guard: branch tip === origin/main tip.
+// It is checked BEFORE isMerged because every unstarted branch is also trivially
+// "merged" — that coincidence is the whole bug, and order is what separates them.
+// Optional, so a caller that does not supply it gets the old behaviour rather than
+// a crash.
+function classifyWorktrees(worktrees, { isMerged, branchExists, isUnstarted = () => false }) {
   const stale = [];
   const live = [];
   for (const wt of worktrees) {
@@ -73,6 +100,7 @@ function classifyWorktrees(worktrees, { isMerged, branchExists }) {
     const name = path.basename(wt.path);
     if (!wt.branch) { live.push({ name, path: wt.path, branch: null }); continue; } // detached: not ours to judge
     if (!branchExists(wt.branch)) stale.push({ name, path: wt.path, branch: wt.branch, why: 'branch gone' });
+    else if (isUnstarted(wt.branch)) live.push({ name, path: wt.path, branch: wt.branch, why: 'unstarted (no commits yet)' });
     else if (isMerged(wt.branch)) stale.push({ name, path: wt.path, branch: wt.branch, why: 'merged into main' });
     else live.push({ name, path: wt.path, branch: wt.branch });
   }
@@ -93,22 +121,38 @@ function classifyHusks({ dirNames, worktreePaths, worktreesRoot }) {
     .map((name) => ({ name, path: path.join(worktreesRoot, name) }));
 }
 
-// Three git calls total, whatever the worktree count: the list, every local branch,
-// every branch already merged into origin/main. Per-worktree subprocesses would be
-// N+1 over exactly the number this probe exists to shrink.
+// FOUR git calls total, whatever the worktree count: the worktree list, every local
+// branch WITH ITS TIP (one read, both facts — task 1003912), every branch already
+// merged into origin/main, and origin/main's own tip. Per-worktree subprocesses
+// would be N+1 over exactly the number this probe exists to shrink.
 function refNames(out) {
   return new Set(String(out).split('\n').map((s) => s.trim()).filter(Boolean));
 }
 
 function scan(cwd) {
   const worktrees = parseWorktreeList(git(['worktree', 'list', '--porcelain'], cwd));
-  const existing = refNames(git(['for-each-ref', '--format=%(refname:short)', 'refs/heads/'], cwd));
+  // ONE read of refs/heads/, carrying both facts it is asked for: which branches
+  // exist, and where each one points. The tip is what the task 1003912 guard needs
+  // (equal to origin/main's ⇒ zero commits ahead ⇒ nothing has landed from it,
+  // because nothing has been written in it) and asking for it separately would
+  // have spawned a second subprocess over the identical ref set — in the one file
+  // whose header makes a promise about its git-call count.
+  const tipOf = new Map();
+  for (const line of git(['for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/heads/'], cwd).split('\n')) {
+    const [name, sha] = line.trim().split(/\s+/);
+    if (name && sha) tipOf.set(name, sha);
+  }
+  const existing = new Set(tipOf.keys());
   let merged;
   try { merged = refNames(git(['branch', '--merged', MAIN_REF, '--format=%(refname:short)'], cwd)); }
   catch { merged = new Set(); } // no origin/main yet (fresh clone, no fetch) → nothing is provably stale
+  let mainTip = null;
+  try { mainTip = git(['rev-parse', MAIN_REF], cwd).trim(); }
+  catch { mainTip = null; } // same fail-open as `merged`: unknown ⇒ claim nothing
   const r = classifyWorktrees(worktrees, {
     branchExists: (b) => existing.has(b),
     isMerged: (b) => merged.has(b),
+    isUnstarted: (b) => Boolean(mainTip) && tipOf.get(b) === mainTip,
   });
   // The main checkout is always the first porcelain entry, so the husk directory is
   // derivable without a second git call.
@@ -157,7 +201,7 @@ function main() {
   console.log(`  Worktrees: ${r.live.length} live, ${r.stale.length} stale, ${husks.length} husks`);
   for (const s of r.stale) console.log(`    stale  ${s.name}  (${s.why})`);
   for (const h of husks) console.log(`    husk   ${h.name}  (on disk, not registered)`);
-  for (const l of r.live) console.log(`    live   ${l.name}  [${l.branch || 'detached'}]`);
+  for (const l of r.live) console.log(`    live   ${l.name}  [${l.branch || 'detached'}]${l.why ? `  (${l.why})` : ''}`);
   if (r.stale.length) console.log('  Remove with: node scripts/gds/worktree.js remove <name>   (or /worktree-clean)');
   if (husks.length) console.log('  Sweep husks with: node scripts/gds/worktree.js prune-husks');
   if (r.stale.length || husks.length) process.exit(1);

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.816'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.818'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/government_require_permission.mjs

@@ -24,6 +24,10 @@ const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
 const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
 const { classify } = require(path.join(ROOT, 'src', 'bongos', 'api-errors.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
+// The same stripper the category guard scans with, rather than a second copy: both
+// checks are answering "which text here is executable", and two answers in one tree
+// is how one of them quietly stops agreeing with the other (task 1003832).
+const { stripComments } = require(path.join(ROOT, 'scripts', 'gds', 'category-advisory-guard.js'));
 
 // Minimal res double capturing status + body, with res.fail() installed exactly
 // as the router installs it (mirrors tests/rank_gate.mjs).
@@ -479,29 +483,101 @@ test('a throwing isOwnershipScoped does not admit and does not crash the gate',
   assert.equal(res._status, 403);
 });
 
-test('no route in the tree is gated on an ownership-scoped key today', () => {
-  // The enumeration the fix was written against, kept honest. A new gate mounted on
-  // an own-scoped atom would now 403 at runtime; this fails at BUILD time instead,
-  // naming the file, so nobody ships a route that can only ever deny.
-  const owned = catalog.permissionKeys().filter((k) => catalog.isOwnershipScoped(k));
-  const dirs = [path.join(ROOT, 'src', 'bongos', 'routes'), path.join(ROOT, 'modules')];
+// The scan, with its file list and its reader INJECTED — the shape
+// category-advisory-guard's scanGates() uses, and for the same reason. A scan run
+// only against the live tree proves nothing about what it would REFUSE, because the
+// tree is clean today by construction; and a scan that can only be run against the
+// live tree cannot be shown to ignore a comment without dirtying a real file.
+//
+// Comments are stripped before the match because a gate is a CALL. This repo's guards
+// routinely CITE the spelling they forbid — that is how the rule stays legible at the
+// site it governs — and in task 1003194 exactly such a comment reds CI, on a file whose
+// executable text was clean. Stripping makes a citation legal and judges only code.
+function scanForOwnedGates(files, read, ownedKeys) {
+  // A gate is a call: requirePermission('<key>'), in any of its spellings. Compiled
+  // once per key rather than once per (file, key) pair.
+  const patterns = ownedKeys.map((key) => [
+    key,
+    new RegExp(`requirePermission\\s*\\([^)]*['"\`]${key.replace(/\./g, '\\.')}['"\`]`),
+  ]);
   const offenders = [];
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    const code = stripComments(src);
+    for (const [key, re] of patterns) {
+      if (re.test(code)) offenders.push(`${rel} :: ${key}`);
+    }
+  }
+  return offenders;
+}
+
+// ROOT-relative .js paths under `dirs`, so the reader and the offender labels speak
+// the same language the injected corpus below does.
+function jsFilesUnder(dirs) {
+  const out = [];
   const walk = (dir) => {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) { if (entry.name !== 'node_modules') walk(full); continue; }
-      if (!entry.name.endsWith('.js')) continue;
-      const text = fs.readFileSync(full, 'utf8');
-      for (const key of owned) {
-        // A gate is a call: requirePermission('<key>'), in any of its spellings.
-        if (new RegExp(`requirePermission\\s*\\([^)]*['"\`]${key.replace(/\./g, '\\.')}['"\`]`).test(text)) {
-          offenders.push(`${path.relative(ROOT, full)} :: ${key}`);
-        }
-      }
+      if (entry.name.endsWith('.js')) out.push(path.relative(ROOT, full));
     }
   };
   dirs.forEach(walk);
+  return out;
+}
+
+test('the own-gate scan reads a citation as prose and a call as a gate', () => {
+  // The half the live scan below cannot assert about itself. A scanner breaks by
+  // quietly finding NOTHING — a stripper that over-matches blanks the source and every
+  // file passes, which looks exactly like a clean tree. So this pins BOTH directions in
+  // one assertion: the two citations must be ignored AND the two calls must still be
+  // caught. Dropping either half is what makes the guard a green light over nothing.
+  const KEY = 'task.abandon.own';
+  const corpus = {
+    'cited-in-a-line-comment.js':
+      `// never mount requirePermission('${KEY}') here — it would admit unconditionally\n`
+      + "router.post('/a', requirePermission('task.abandon'), handler);\n",
+    'cited-in-a-block-comment.js':
+      `/*\n * requirePermission('${KEY}') cannot answer an ownership question.\n */\n`
+      + "router.post('/b', requirePermission('idea.triage'), handler);\n",
+    'a-real-gate.js': `router.post('/c', requirePermission('${KEY}'), handler);\n`,
+    // The over-strip canary: a line comment must end at its newline. If stripping ate
+    // the rest of the file this gate would vanish and the scan would report clean.
+    'a-real-gate-below-a-comment.js':
+      `// this module is documented first\nrouter.post('/d', requirePermission('${KEY}'), handler);\n`,
+    // The blind spot that failed this task's first grade. A `//` inside an ordinary
+    // STRING is not a comment, and a stripper that thinks it is erases the rest of the
+    // line — here, the live gate sitting right after it. The guard then reports clean
+    // over a real violation, which reads exactly like a clean tree.
+    'a-real-gate-after-a-string-holding-a-slash-slash.js':
+      `router.post('//legacy', requirePermission('${KEY}'), handler);\n`,
+    'a-real-gate-after-a-string-holding-a-block-open.js':
+      `const note = '/* not a comment */';\nrouter.post('/e', requirePermission('${KEY}'), handler);\n`,
+  };
+  const found = scanForOwnedGates(Object.keys(corpus), (rel) => corpus[rel], [KEY]);
+  assert.deepEqual(found.sort(), [
+    `a-real-gate-after-a-string-holding-a-block-open.js :: ${KEY}`,
+    `a-real-gate-after-a-string-holding-a-slash-slash.js :: ${KEY}`,
+    `a-real-gate-below-a-comment.js :: ${KEY}`,
+    `a-real-gate.js :: ${KEY}`,
+  ], 'a citation is documentation; a call is a gate');
+});
+
+test('no route in the tree is gated on an ownership-scoped key today', () => {
+  // The enumeration the fix was written against, kept honest. A new gate mounted on
+  // an own-scoped atom would now 403 at runtime; this fails at BUILD time instead,
+  // naming the file, so nobody ships a route that can only ever deny.
+  const owned = catalog.permissionKeys().filter((k) => catalog.isOwnershipScoped(k));
+  assert.ok(owned.length > 0, 'no ownership-scoped atoms — the scan would pass vacuously');
+  const files = jsFilesUnder([path.join(ROOT, 'src', 'bongos', 'routes'), path.join(ROOT, 'modules')]);
+  // A mis-pointed root is the other way this passes while scanning nothing, and it
+  // reads identically to a clean tree. Pin the corpus so the roots must still resolve.
+  assert.ok(files.length > 100, `expected the route corpus; scanned only ${files.length} files`);
+  const offenders = scanForOwnedGates(files, (rel) => {
+    try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; }
+  }, owned);
   assert.deepEqual(offenders, [],
     'requirePermission cannot answer an ownership-scoped key — the handler must call ' +
     'authorizeOwned() with the row\'s owner instead');

package/tests/linkify_refs.mjs

@@ -290,6 +290,23 @@ t('a known idea link is never unwrapped by the past-mislink pass', () => {
   assert.equal(runIds(s, ids), s);
 });
 
+// task 1003935: the separator contract, stated rather than assumed.
+//
+// discoverDocs builds with path.join, so on Windows it returned
+// 'docs\\adr\\0001-….md' and the recursion assertion below — which compares against
+// 'docs/' — was permanently red. Nobody saw it: this file was in run-unit-tests'
+// INTEGRATION exclusion set while touching no database, so it ran in neither lane
+// (fixed in the same task). The assertion was right and the walker was wrong to
+// hand it OS-native paths, so the fix is here at the boundary; this test exists so
+// the next reader does not have to rediscover which of the two was at fault.
+t('discoverDocs returns POSIX-style paths on every platform (task 1003935)', () => {
+  const docs = discoverDocs();
+  const native = docs.filter((d) => d.includes('\\'));
+  assert.equal(native.length, 0,
+    `paths must not carry OS-native separators; got ${JSON.stringify(native.slice(0, 3))}`);
+  assert.ok(docs.some((d) => d.includes('/')), 'and nested paths must still be nested');
+});
+
 t('discoverDocs finds CLAUDE.md, recurses docs/ subdirs (only .md), skips the generated ideas file', () => {
   const docs = discoverDocs();
   assert.ok(docs.includes('CLAUDE.md'), 'includes CLAUDE.md');