@bongos/core 1.19.794 → 1.19.795

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.794",
-  "core_contract": "1.19.794",
-  "source_commit": "58b6a9cb74826c4f1f72ca3cede882e22cd7a692",
+  "core_version": "1.19.795",
+  "core_contract": "1.19.795",
+  "source_commit": "59f35c05e7edb8428f4c532e5032e9333bd7a0b9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T00:45:35.726Z",
+  "built_at": "2026-09-17T00:54:38.883Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 486,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2179,
+    "functional_verbatim": 2182,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2690,
-  "tree_sha256": "d3110e81291c49d143518eb1ef7e4e7a9d98ecbc08b176a4da98f589a27fd00d",
+  "file_count": 2693,
+  "tree_sha256": "bb912c280be9ea67a9825f8ee7e6bbc68b2be165c826b3fb40185a0badd7cd9d",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2527,7 +2527,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "72aa54d05b8b21077bb6616513d99cb5f4c15ff3134c015024609d265a73efee"
+      "sha256": "d9df5939232118367f1db9c0127c514a19f625aa46a8375e65dda21705e84671"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3614,6 +3614,11 @@
       "mode": "0000644",
       "sha256": "8e3e2db2ab3b7775bddf12f3a7ec3ed74477334b6388487ecd919cd61a62b0ba"
     },
+    {
+      "path": "migrations/core_244_skill_friction_kind.sql",
+      "mode": "0000644",
+      "sha256": "e298a5b2e9ffade95fae0e68910a25396fab560e6e54dd745cfc122c0dfdf403"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -5377,7 +5382,7 @@
     {
       "path": "modules/ideas/inbox.js",
       "mode": "0000644",
-      "sha256": "8c0792629df6d9587bce828a0f3743b8c86bdb31ba226d31211b9c6623574395"
+      "sha256": "6c619200312b32cbc268c44b41c4f3f574f7917a31187b69cfeba105c804ddee"
     },
     {
       "path": "modules/ideas/migrations/ideas_001_grades.sql",
@@ -5429,6 +5434,11 @@
       "mode": "0000644",
       "sha256": "da653f475d6c91db8e84bff46c797bb68b61e48d561eacf7bfd228a119ac7266"
     },
+    {
+      "path": "modules/ideas/skill-friction.js",
+      "mode": "0000644",
+      "sha256": "eb6a5cecb3ce54aeb0c85ffb752eb12a2400d0d4f5c7d48e4e05ff3cf7baf712"
+    },
     {
       "path": "modules/ideas/templates.js",
       "mode": "0000644",
@@ -7692,12 +7702,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "a8e7ddfcf220286f226ac9f1dd0f32247942c46b5518630a3610c68f47d541a2"
+      "sha256": "abe39cacffdf6a8359f19b7e7a5a06a7055f99637edc556db2124968bdae5eb8"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2439337546b7731e96d15362371d002a51fd2d7112f6aa09abf53c05a88549ca"
+      "sha256": "6f9922b6e8c2eb446a10daa28bd6a34da2097b36098a70db45f16010c8529217"
     },
     {
       "path": "public-docs/index.html",
@@ -7987,7 +7997,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "9ab25dfe2ce4e2910ab9b5558105a6ee24f095c4e03c1e6a92b2d1a2e94ce703"
+      "sha256": "8cf425aed2764fc043c8a8757f178f7514a907567d559e7f0b11e091f33b66e5"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -8932,7 +8942,7 @@
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "56857161a882d20a4d45a04f20bd53bce0e6d946002a7cd3d4548cbed7f2855c"
+      "sha256": "fe64da47ac66f589d0245e02b321dbd708e695dd3875e75e8b4ac36e6aa31636"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -8952,7 +8962,7 @@
     {
       "path": "scripts/gds/ship-honesty.js",
       "mode": "0000644",
-      "sha256": "29116265032b48115c31df794aa4689e7ce3f5eaeef152ea1ca2390dc2078c39"
+      "sha256": "3ab4816fdd43d589cda73698a514f8e23103be166c1650fd24beeee9f529bb5b"
     },
     {
       "path": "scripts/gds/ship-io.js",
@@ -9577,7 +9587,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9d386b35a316f8ab344ad96e48ed473560ada963d7b33699576b1325afe6be03"
+      "sha256": "e21607486d5b15d09ea4e0f1ad1a3a626c9dbaf3713aa601dd113e5e3d7bd13e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10247,7 +10257,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "8292d8c7a788e7839599d38f6c78a5dbb68f6ae50a58771a66e6481a562f0ace"
+      "sha256": "7acfe432856010881b234b258d45fcf65f976e0e711d01b823d90990a0c7179c"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -12892,7 +12902,7 @@
     {
       "path": "tests/ship_cannot_lie.mjs",
       "mode": "0000644",
-      "sha256": "18a3bb613fff3dcc0dfbffb2283a866726af4347c161fc28853b36b5bdd75512"
+      "sha256": "55e94ed59bc1bd19e4a3dd0e9a9a415dde659c5d71af0dd827d1b288e66de3c7"
     },
     {
       "path": "tests/ship_card.mjs",
@@ -12984,6 +12994,11 @@
       "mode": "0000644",
       "sha256": "0eeccae9320f419667cf9ede3c13671a5b03571f7f2f17067bff1857234ddf91"
     },
+    {
+      "path": "tests/skill_friction_kind.mjs",
+      "mode": "0000644",
+      "sha256": "baaf5935cc748e7eb9596d1c96c3c20aa2ee3917377d32b9104408b7b07165a4"
+    },
     {
       "path": "tests/skill_grade_audit.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2062,5 +2062,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.792 with no explicit bump. run 35167484049. (task 1002620)
   1.19.794 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.793 with no explicit bump. run 35167814500. (task 1002620)
+  1.19.795 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.794 with no explicit bump. run 35168408728. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_244_skill_friction_kind.sql

@@ -0,0 +1,74 @@
+-- core_244_skill_friction_kind.sql — 'skill-friction' becomes a real kind
+-- (task 1003105, goal 1000095, promoted from idea 1000759).
+--
+-- WHY. Two skills instruct the agent to file a retrospective finding as
+-- `kind='skill-friction'` — `.claude/skills/planning-session/SKILL.md` ("After
+-- the session — improvements pass") and `.claude/skills/priority-session/
+-- SKILL.md`. Neither works: the CHECK constraint on `idea_inbox.kind` (migration
+-- 006, extended by 042) admits only the fixed task-kind enum, so `POST /inbox`
+-- fails with BAD_KIND. Hit live on 2026-08-16 — all three retrospective ideas
+-- from the Board Room planning session failed on the first attempt and had to be
+-- re-homed under unrelated kinds. The cost is not the error message: this is the
+-- step that makes the planning skill self-improving, and because it fails closed
+-- the findings are either dropped or filed somewhere nobody looks for them.
+--
+-- WHY NOW, AND NOT AS A TITLE PREFIX. The nightly `skill-usage-review` routine
+-- already files these rows, and it works — by tagging a `[skill-friction]`
+-- title prefix over a valid enum `kind`. That workaround names its own exit
+-- condition, in `modules/ideas/inbox.js` and in the routine's SKILL.md: "when
+-- the rank system lands a real builders.rank column + idea_inbox.kind
+-- migration, this prefix convention can be promoted to a first-class kind."
+-- The rank system HAS landed — `builders.rank` is live and enforced server-side
+-- (ADR 0016), and `viewerRank` is threaded into all four inbox read paths from
+-- `req.builder.rank`. So the condition the workaround was waiting on is met,
+-- and this is the migration it asked for.
+--
+-- WHAT THIS DOES NOT DO. It does not backfill the existing `[skill-friction]`-
+-- prefixed rows, and it does not change what the nightly routine writes. Both
+-- are deliberate: the deployed core pin runs behind `main` by design (gate 3 of
+-- docs/recipes/core-release-pipeline.md), so between this landing and the pin
+-- moving there is a window in which the DB accepts the new kind and the running
+-- instance's VALID_KINDS does not offer it. A filer flipped to the new kind in
+-- that window would start failing where it currently succeeds — strictly worse
+-- than the bug being fixed. So the marker stays DUAL: `inbox.js` recognises a
+-- row as skill-friction by its kind OR its legacy title prefix, permanently and
+-- by design, and flipping the routine is a follow-up for after the pin moves.
+--
+-- WHY CORE AND NOT modules/ideas/migrations/. `idea_inbox` is a CORE table: it
+-- was created by migration 006 and every later change to it — 042 (the last
+-- widening of this same constraint), core_195, core_222, core_228 — is a core
+-- migration. The `ideas` module owns the `ideas_*` tables, not this one, and a
+-- module migration may only touch its own namespace and must be additive.
+-- Widening a CHECK requires dropping it, so this could not have been a module
+-- migration even if the table had been the module's. `fitness.js` enforces both
+-- rules and caught the first attempt at this file in the wrong place.
+--
+-- The constraint is dropped by LOOKUP rather than by name, exactly as 042 does
+-- it, and for 042's reason: a database that somehow never ran 042 still carries
+-- the 006-era constraint under its original name, and a `DROP CONSTRAINT IF
+-- EXISTS idea_inbox_kind_check` there would silently no-op and leave the old,
+-- narrower constraint in force — which rejects the very kind this adds.
+--
+-- REVERSIBILITY. Dropping back is the same DO block with 'skill-friction'
+-- removed from the list, and is safe only while no row carries the kind.
+
+DO $$
+DECLARE cname text;
+BEGIN
+  SELECT conname INTO cname
+    FROM pg_constraint
+   WHERE conrelid = 'idea_inbox'::regclass
+     AND contype = 'c'
+     AND pg_get_constraintdef(oid) ILIKE '%kind%IN%';
+  IF cname IS NOT NULL THEN
+    EXECUTE format('ALTER TABLE idea_inbox DROP CONSTRAINT %I', cname);
+  END IF;
+END $$;
+
+ALTER TABLE idea_inbox
+  ADD CONSTRAINT idea_inbox_kind_check
+  CHECK (kind IN (
+    'feature','bug','infra','refactor','spike',
+    'learning-capture','cleanup','decision','blocker-resolution',
+    'unclassified','criterion-proposal','skill-friction'
+  ));

package/modules/ideas/inbox.js

@@ -42,6 +42,12 @@ const VALID_KINDS = [
   // ratify endpoint (assert kind='criterion-proposal' before promotion).
   // CHECK constraint updated in migration 042.
   'criterion-proposal',
+  // task 1003105 — `/planning-session` and `/priority-session` both instruct the
+  // agent to file a retrospective finding as kind='skill-friction', and both
+  // failed BAD_KIND until now. The DB CHECK constraint is widened to match in
+  // migrations/core_244_skill_friction_kind.sql, which also
+  // explains why the legacy title-prefix marker below stays alongside it.
+  'skill-friction',
 ];
 const VALID_STATUSES = ['open', 'promoted', 'discarded', 'merged'];
 
@@ -121,45 +127,13 @@ function ungradedProjection() {
 }
 
 // -------------------------------------------------------------------------
-// Skill-friction tagging (task V3.R70 / #289)
-//
-// The nightly `skill-usage-review` routine files one idea_inbox row per
-// friction pattern it detects. The done-when calls these "kind='skill-friction'"
-// rows, but the DB CHECK constraint on idea_inbox.kind (migration 006) only
-// admits the fixed task-kind enum — adding a literal 'skill-friction' kind
-// would need a new migration, and migrations are explicitly out of scope for
-// this task. So we tag friction rows the same way overnight-code-review tags
-// its findings: a stable title prefix. The underlying `kind` stays a valid
-// enum value (cleanup), and SKILL_FRICTION_TAG is the machine-checkable marker.
-//
-// When the GDS-V3 rank system (V3.R04) lands a real builders.rank column +
-// idea_inbox.kind migration, this prefix convention can be promoted to a
-// first-class kind value and this marker collapses to a kind check.
-const SKILL_FRICTION_TAG = '[skill-friction]';
-
-// -------------------------------------------------------------------------
-// Rank visibility (task V3.R70 / #289)
-//
-// Three ranks are planned in GDS-V3 (V3.R04): Xenos (default for any
-// GitHub-authed person), Metic (Archon-approved), Archon. Skill-friction
-// ideas are a system-evolution signal meant for trusted builders — Xenos
-// must NOT see them in their inbox view; Metic and Archon may.
-//
-// `builders.rank` does not exist in the schema yet (it lands with R04), and
-// requireBuilder does not yet populate req.builder.rank — so today every
-// caller passes viewerRank=null. The gate is written to be correct the moment
-// rank is threaded through: it hides skill-friction rows ONLY when the viewer
-// is positively known to be Xenos. Unknown/absent rank (today's reality, where
-// no Xenos exist yet) is treated as Metic+ and sees everything — so wiring this
-// in does not regress current all-builders behavior.
-const XENOS_RANK = 'xenos';
-
-function rankCanSeeSkillFriction(viewerRank) {
-  // Hide only when we KNOW the viewer is Xenos. null/undefined/anything else
-  // (Metic, Archon, or "rank system not deployed") => allowed.
-  if (viewerRank == null) return true;
-  return String(viewerRank).toLowerCase() !== XENOS_RANK;
-}
+// Skill-friction: the marker a row carries and the rank gate that hides it.
+// Pure, and its own file (./skill-friction.js) for the reason written there —
+// re-exported below so every existing caller keeps working.
+const {
+  SKILL_FRICTION_TAG, SKILL_FRICTION_KIND, XENOS_RANK,
+  rankCanSeeSkillFriction, skillFrictionHiddenClause,
+} = require('./skill-friction');
 
 // -------------------------------------------------------------------------
 // Fallback classifier — keyword heuristics over title+body.
@@ -511,9 +485,8 @@ async function routeIdeaToGoal({
 // see skill-friction rows; Metic+ (or unknown rank, pre-R04) see everything.
 // We filter in SQL when the viewer is positively Xenos so the LIMIT still
 // returns up to `limit` *visible* rows rather than `limit` rows that then get
-// thinned out in JS. The skill-friction marker is a title prefix (see
-// SKILL_FRICTION_TAG above) because the kind enum cannot take a new value
-// without a migration.
+// thinned out in JS. The marker is a kind OR a legacy title prefix — see
+// skillFrictionHiddenClause, which is the only place that knows that.
 async function listOpenIdeas({ kind = null, limit = 50, viewerRank = null } = {}) {
   const params = [];
   const where = [`i.status = 'open'`];
@@ -521,10 +494,8 @@ async function listOpenIdeas({ kind = null, limit = 50, viewerRank = null } = {}
     params.push(kind);
     where.push(`i.kind = $${params.length}`);
   }
-  if (!rankCanSeeSkillFriction(viewerRank)) {
-    params.push(`${SKILL_FRICTION_TAG}%`);
-    where.push(`i.title NOT LIKE $${params.length}`);
-  }
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
+  if (hideFriction) where.push(hideFriction);
   params.push(limit);
   const { rows } = await pool.query(
     `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q}
@@ -570,10 +541,8 @@ async function getIdea(id) {
 async function countOpenIdeas({ viewerRank = null } = {}) {
   const params = [];
   const where = [`status = 'open'`];
-  if (!rankCanSeeSkillFriction(viewerRank)) {
-    params.push(`${SKILL_FRICTION_TAG}%`);
-    where.push(`title NOT LIKE $${params.length}`);
-  }
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params);
+  if (hideFriction) where.push(hideFriction);
   const { rows } = await pool.query(
     `SELECT count(*)::int AS n FROM idea_inbox WHERE ${where.join(' AND ')}`,
     params
@@ -619,10 +588,8 @@ const IDEA_TRAIL_MAX_LIMIT = 100;
 function ideaTrailWhere(builderId, viewerRank, params) {
   params.push(builderId);
   const where = [`i.captured_by = $${params.length}`];
-  if (!rankCanSeeSkillFriction(viewerRank)) {
-    params.push(`${SKILL_FRICTION_TAG}%`);
-    where.push(`i.title NOT LIKE $${params.length}`);
-  }
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
+  if (hideFriction) where.push(hideFriction);
   return where.join(' AND ');
 }
 
@@ -1029,10 +996,8 @@ async function countRoutedAwaitingNod(deps = {}) {
 // agreeing by construction beats them agreeing by accident.
 function sparkQueueWhere(viewerRank, params) {
   const where = [`g.grade = 'spark'`, `i.status = 'open'`];
-  if (!rankCanSeeSkillFriction(viewerRank)) {
-    params.push(`${SKILL_FRICTION_TAG}%`);
-    where.push(`i.title NOT LIKE $${params.length}`);
-  }
+  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
+  if (hideFriction) where.push(hideFriction);
   return where;
 }
 
@@ -1455,10 +1420,13 @@ module.exports = {
   DEFAULT_TEMPLATE_KEY,
   TEMPLATE_KEY_MAX,
   FIELD_VALUES_MAX,
-  // skill-friction tagging + rank visibility gate (V3.R70 / #289)
+  // skill-friction marker + rank visibility gate (V3.R70 / #289; the kind
+  // itself landed in task 1003105 — both markers are live, see above)
   SKILL_FRICTION_TAG,
+  SKILL_FRICTION_KIND,
   XENOS_RANK,
   rankCanSeeSkillFriction,
+  skillFrictionHiddenClause,
   // capture
   captureIdea,
   // read

package/modules/ideas/skill-friction.js

@@ -0,0 +1,97 @@
+// modules/ideas/skill-friction.js — the skill-friction marker and the rank
+// gate that hides those rows, extracted from inbox.js (task 1003105).
+//
+// WHY ITS OWN FILE. Two reasons, and the second is the real one.
+//
+// `inbox.js` sits against the repo's per-file size budget, and adding the kind
+// plus the reasoning for keeping the legacy marker pushed it over — the fitness
+// ratchet's whole job. Trimming the explanation to fit would have deleted the
+// part a later reader needs most: WHY there are two markers rather than one.
+//
+// And this was always a separable concern. It is pure — no pool, no I/O, no
+// knowledge of a query beyond emitting a fragment — which is the same test
+// `./routing.js` and `./homeless-home.js` already passed when they were split
+// out of the same file. `inbox.js` re-exports everything here, so nothing that
+// reached these through it has to change.
+
+'use strict';
+
+// Skill-friction tagging (task V3.R70 / #289)
+//
+// A skill-friction row carries TWO markers, both first-class, both permanent.
+//
+// The nightly `skill-usage-review` routine files one idea_inbox row per
+// friction pattern it detects, and it has always worked — by tagging a stable
+// title prefix over a valid enum `kind`, because the CHECK constraint on
+// idea_inbox.kind admitted no such value. That workaround named its own exit
+// condition, here and in the routine's SKILL.md: promote the prefix to a real
+// kind once the rank system lands a `builders.rank` column and a migration.
+//
+// Both have landed — rank is live and enforced server-side (ADR 0016), and
+// `viewerRank` reaches all four read paths below from `req.builder.rank` — so
+// task 1003105 added the kind (core_244_skill_friction_kind.sql). What it did
+// NOT do is retire the prefix, and that is the part worth reading twice: the
+// deployed core pin runs behind `main` BY DESIGN (gate 3 of the release
+// pipeline), so there is a window where the database accepts the new kind and
+// the running instance does not yet offer it. A filer flipped inside that
+// window starts failing where it currently succeeds. So the prefix is not a
+// deprecated alias to be swept later — it is the marker every historical row
+// carries and the one the nightly routine still writes, and
+// `skillFrictionHiddenClause` below is the single place that knows both.
+const SKILL_FRICTION_TAG = '[skill-friction]';
+const SKILL_FRICTION_KIND = 'skill-friction';
+
+// -------------------------------------------------------------------------
+// Rank visibility (task V3.R70 / #289)
+//
+// Three ranks are planned in GDS-V3 (V3.R04): Xenos (default for any
+// GitHub-authed person), Metic (Archon-approved), Archon. Skill-friction
+// ideas are a system-evolution signal meant for trusted builders — Xenos
+// must NOT see them in their inbox view; Metic and Archon may.
+//
+// `builders.rank` does not exist in the schema yet (it lands with R04), and
+// requireBuilder does not yet populate req.builder.rank — so today every
+// caller passes viewerRank=null. The gate is written to be correct the moment
+// rank is threaded through: it hides skill-friction rows ONLY when the viewer
+// is positively known to be Xenos. Unknown/absent rank (today's reality, where
+// no Xenos exist yet) is treated as Metic+ and sees everything — so wiring this
+// in does not regress current all-builders behavior.
+const XENOS_RANK = 'xenos';
+
+function rankCanSeeSkillFriction(viewerRank) {
+  // Hide only when we KNOW the viewer is Xenos. null/undefined/anything else
+  // (Metic, Archon, or "rank system not deployed") => allowed.
+  if (viewerRank == null) return true;
+  return String(viewerRank).toLowerCase() !== XENOS_RANK;
+}
+
+// skillFrictionHiddenClause — the ONE predicate meaning "this row is not a
+// skill-friction row", for the four read paths that hide them from a Xenos.
+// It tests BOTH markers (see SKILL_FRICTION_TAG above).
+//
+// It exists as a function rather than four copied conditions because the four
+// gates have to agree and nothing made them: a copy that learned about the new
+// kind while its siblings did not would leak skill-friction rows into exactly
+// one Xenos-facing listing, which is the kind of gap nobody notices until it is
+// in front of the wrong reader. Filtering stays in SQL so a LIMIT still returns
+// up to `limit` VISIBLE rows rather than `limit` rows thinned out afterwards.
+//
+// Pushes its own params onto `params`. Returns null when the viewer may see
+// everything — callers push the clause only when it is non-null, so a viewer
+// with no rank restriction costs no bind parameters at all.
+function skillFrictionHiddenClause(viewerRank, params, alias = '') {
+  if (rankCanSeeSkillFriction(viewerRank)) return null;
+  const col = alias ? `${alias}.` : '';
+  params.push(SKILL_FRICTION_KIND);
+  const kindParam = params.length;
+  params.push(`${SKILL_FRICTION_TAG}%`);
+  return `(${col}kind <> $${kindParam} AND ${col}title NOT LIKE $${params.length})`;
+}
+
+module.exports = {
+  SKILL_FRICTION_TAG,
+  SKILL_FRICTION_KIND,
+  XENOS_RANK,
+  rankCanSeeSkillFriction,
+  skillFrictionHiddenClause,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.794",
+  "version": "1.19.795",
   "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/claude-materialize.js

@@ -16,8 +16,12 @@
 // package; this module copies+transforms them when they ARE present at the core root (today's single
 // checkout, and the core repo itself), and no-ops with a note when they aren't (an installed package).
 // Hooks self-resolve their core require()s at RUNTIME via the copied _core-resolve.js sibling
-// (task 2139, the former W3 follow-up), so no require-path rewriting happens here; shipping a
-// topology STARTER for a package-only install (hooks absent at the core root) stays a follow-up (task 1883).
+// (task 2139, the former W3 follow-up), so no require-path rewriting happens here. The topology
+// STARTER for a package-only install is now HALF built: settings.json is written from
+// renderStarterSettings() below — permissions only, no hooks — because an instance that received
+// the skills but no permissions met the classifier on every blessed command (task 1003962). A hooks
+// starter remains a follow-up (task 1883), and is a different question: hooks ARE gate machinery,
+// where a list of allowed command names is not.
 //
 // SELF-COPY GUARD. When the instance dir IS the core root (running init inside the core checkout /
 // OTB today), there is nothing to materialize — a self-copy would be a no-op at best and corrupting
@@ -296,6 +300,50 @@ function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true
 
 // Transform settings.json: parse, rewrite every hook command through bongosify, re-serialize. Keeps
 // .claude/hooks/*.js commands (instance-local) untouched and rewrites the scripts/gds/*.js ones.
+// The blessed commands an instance builder runs to do the methodology, one rule
+// each (task 1003962). This MIRRORS the core repo's own `.claude/settings.json`
+// allow-list (ADR 0104 / task 1051), translated from `node scripts/gds/<x>.js`
+// into the verb form a materialized instance actually invokes — bongosify()
+// rewrites every skill to `bongos <verb>`, so a path-shaped rule would match
+// nothing there.
+//
+// THE GAP THIS CLOSES. `.claude/settings.json` is excluded from the published
+// package on purpose (PROTECTED_TOPOLOGY_EXCLUDE, beside infra/ and .github/):
+// the core's own copy is deploy and gate machinery that means nothing on an
+// instance. But the skills ship, so an instance received the methodology and
+// none of the permissions that let it run — every instance builder met the
+// auto-mode classifier on the normal workflow, which is how a live builder came
+// to be stuck mid-re-auth with no way forward.
+//
+// WHY THIS IS NOT AN AUTHORITY GRANT (ADR 0016). An allow-rule stops the local
+// agent REFUSING to run a command; it changes nothing about what the server
+// permits. Rank is read fresh from the database on every request by
+// `requireRank`, so a builder who edits this file grants themselves exactly
+// nothing. That is the distinction that makes shipping a list of command names
+// safe where shipping hooks — actual local gate machinery — is not.
+//
+// DELIBERATELY ABSENT: `bongos exec`. It runs any script inside the core by
+// path and is the agent's escape hatch, so allow-listing it would be a blanket
+// grant wearing a narrow rule's clothes. The one script the core's own list
+// blesses (`api.js`) is named in full instead.
+const STARTER_ALLOW = [
+  'Bash(bongos claim:*)',
+  'Bash(bongos ship:*)',
+  'Bash(bongos release:*)',
+  'Bash(bongos reauth:*)',
+  'Bash(bongos paste-token:*)',
+  'Bash(bongos exec scripts/gds/api.js:*)',
+];
+
+// The starter an instance gets when the core root carries no settings.json — a
+// package-only install. Permissions ONLY: no hooks (they are topology), no env.
+function renderStarterSettings() {
+  return `${JSON.stringify({
+    _doc: 'Starter written by scripts/gds/claude-materialize.js (task 1003962). Permissions only — the blessed Bongos commands, mirroring the core repo\'s own allow-list (ADR 0104). An allow-rule lets the local agent RUN a command; it grants no authority, which the server decides per request from your live rank (ADR 0016). Yours to edit: a later materialize never clobbers this file.',
+    permissions: { allow: STARTER_ALLOW },
+  }, null, 2)}\n`;
+}
+
 function transformSettings(srcPath) {
   const raw = fs.readFileSync(srcPath, 'utf8');
   let json;
@@ -484,7 +532,25 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands→bongos, identity rebranded)`);
     }
   } else {
-    summary.notes.push('.claude/settings.json not present at the core root (topology, excluded from the package) — provide it from a starter.');
+    // Package-only install: the core root carries no settings.json to copy, so
+    // write the STARTER instead of leaving the instance with no permissions at
+    // all (task 1003962 — the note that used to sit here said "provide it from a
+    // starter" and nothing ever did). Written only when ABSENT, the same rule
+    // the starter CLAUDE.md below follows: an instance that has grown its own
+    // permissions owns them, and a later materialize must never clobber them.
+    const settingsDest = path.join(destClaude, 'settings.json');
+    if (fs.existsSync(settingsDest)) {
+      summary.skippedFiles.push('settings.json');
+      log('  • .claude/settings.json already present — left untouched (the instance owns it).');
+    } else {
+      if (!dryRun) {
+        fs.mkdirSync(destClaude, { recursive: true });
+        fs.writeFileSync(settingsDest, renderStarterSettings());
+      }
+      summary.settings = true;
+      summary.notes.push(`.claude/settings.json written from the starter — ${STARTER_ALLOW.length} blessed command(s), permissions only.`);
+      log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (starter: ${STARTER_ALLOW.length} blessed commands, no hooks)`);
+    }
   }
 
   // 3. hooks — topology; copied WITH an identity rebrand (their .js internals carried
@@ -650,4 +716,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, transformSettings, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/ship-flow.js

@@ -9,7 +9,7 @@
 'use strict';
 
 const { cliClient, requireSession, arg, detectWorktreeName, cardFlagsFromMe } = require('./cli-lib');
-const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal } = require('./ship-honesty.js');
+const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal, staleSummaryNotice } = require('./ship-honesty.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
 const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
 const { matchOne } = require('../../src/bongos/path-match');
@@ -826,6 +826,12 @@ async function regradeMain() {
   // PATCH /tasks/:id is the route it uses, and `value_summary` was added to that
   // schema by this same task. tests/ship_cannot_lie.mjs pins the wiring.
   const summary = summaryArg || task.value_summary || '';
+  // task 1003693: the fallback above is silent, and on a re-grade silence means
+  // re-publishing the failed attempt's sentence. Say so while it can still be
+  // corrected — see staleSummaryNotice for the incident this comes from.
+  if (!summaryArg) {
+    for (const line of staleSummaryNotice(taskId, task.value_summary)) console.log(line);
+  }
 
   // The grader helpers want a claim-like object for touches[] (preflight's
   // working-tree-drift check) and head_sha (baseline fallback). The claim is

package/scripts/gds/ship-honesty.js

@@ -195,9 +195,63 @@ function regradeNotesRefusal(taskId) {
   ];
 }
 
+// THE FOURTH WAY TO LOSE THE BUILDER'S PROSE — and the only one where what
+// survives is worse than nothing, because it is a sentence that was true once.
+//
+// regradeMain falls back to the stored value_summary when --summary is omitted
+// (`summaryArg || task.value_summary`), and persistRegradeSummary deliberately
+// writes nothing on an omission. Both postures are right alone: a re-grade with
+// no summary must not blank the row, and an empty broadcast would be worse than
+// a stale one. Together they mean the DEFAULT re-grade re-publishes the first
+// attempt's sentence with nothing saying so.
+//
+// That is the task-1002343 incident exactly. Shipped 2026-09-04 asserting "No
+// project was created and nothing on the live system was left changed"; parked
+// at completed on a failing grade; redone 2026-09-07, when a project WAS created
+// (instance 40, r24-proof). The re-grade omitted --summary, so the ledger and the
+// #ship-news post both announced the opposite of what landed. Nobody ignored a
+// correction — there was no prompt to make one.
+//
+// So this is a NOTICE, not a refusal and not a behaviour change. The fallback is
+// correct and stays; task 1003817 already built the correction path (--summary on
+// a re-grade now reaches the row, the hall, /status and the broadcast). What was
+// missing is the moment that tells the builder that path exists, while the run
+// can still be corrected. Printed BEFORE the grade spend for the reason the
+// --notes refusal is: a warning that first costs a 4-worker panel run is barely
+// a warning at all.
+//
+// Returns [] when the row holds no stored summary — there is no stale text to
+// warn about then, and an empty summary is the merge leg's problem, not this
+// one. Pure, so the WORDING is testable: a notice that fails to name the fix is
+// noise with a warning sign on it.
+function staleSummaryNotice(taskId, storedSummary) {
+  // Control characters are stripped BEFORE the whitespace collapse, which only
+  // matches \s and would leave an ESC through. The stored summary is builder prose
+  // that has already been server-side stored and is already bound for Discord and
+  // the hall, so this crosses no new trust boundary — but this is the one place it
+  // reaches a TERMINAL, where an escape sequence could repaint the notice around it.
+  const stored = String(storedSummary || '')
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!stored) return [];
+  const shown = stored.length > 140 ? `${stored.slice(0, 139)}…` : stored;
+  return [
+    '⚠ No --summary given — this re-grade reuses the summary stored at the FIRST ship:',
+    `      "${shown}"`,
+    '  That sentence describes the attempt that FAILED its grade. A re-grade usually means the',
+    '  work changed since, and this text is what the panel reads, what the merge commit and PR',
+    '  say, and what goes to Discord #ship-news as the durable record of this ship.',
+    '',
+    '  If it still describes what landed, ignore this. If not, correct it in this same run:',
+    `    node scripts/gds/ship.js ${taskId} --regrade --summary-file summary.txt`,
+    '  (the -file form is the safe one for prose — a shell eats backticks in an inline value)',
+  ];
+}
+
 module.exports = {
   resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
-  proseFlagPresent, regradeNotesRefusal,
+  proseFlagPresent, regradeNotesRefusal, staleSummaryNotice,
   _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
   _peekForTest: () => shipProgress,
 };

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.794'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.795'; // 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/claude_materialize.mjs

@@ -26,6 +26,9 @@ const require = createRequire(import.meta.url);
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const m = require('../scripts/gds/claude-materialize.js');
 const claim = require('../scripts/gds/claim.js');
+// The live verb table, so a starter allow-rule naming a verb that does not exist
+// fails here rather than shipping as an inert permission (task 1003962).
+const { VERBS: cliVerbs } = require('../bin/bongos.js');
 
 let passed = 0;
 let failed = 0;
@@ -704,5 +707,73 @@ t('materializeModeSkills lands the real module-owned skills, self-ignored, and i
   rmSync(core, { recursive: true, force: true });
 });
 
+// ---------------------------------------------------------------------------
+// task 1003962 — the starter settings.json for a package-only install.
+//
+// THE GAP: `.claude/skills/` ships in the core package but `.claude/settings.json`
+// is excluded as topology, so an instance received the methodology and none of the
+// permissions that let it run — every blessed command met the auto-mode classifier.
+// ---------------------------------------------------------------------------
+
+t('the starter carries PERMISSIONS ONLY — no hooks, no env (those are topology)', () => {
+  const parsed = JSON.parse(m.renderStarterSettings());
+  assert.ok(Array.isArray(parsed.permissions.allow), 'must carry permissions.allow');
+  assert.ok(!('hooks' in parsed), 'hooks are gate machinery and must NOT ship to an instance');
+  assert.ok(!('env' in parsed), 'env is topology and must NOT ship to an instance');
+  assert.ok(parsed._doc.includes('grants no authority'),
+    'the file must say out loud that it grants no authority (ADR 0016)');
+});
+
+t('every allow-rule names a verb the CLI actually registers', () => {
+  // The drift this catches: a rule naming a verb that was renamed or never existed
+  // is silently inert — it looks like a permission and grants nothing, so the
+  // builder still meets the classifier and nobody can see why.
+  for (const rule of m.STARTER_ALLOW) {
+    const inner = rule.replace(/^Bash\(/, '').replace(/:\*\)$/, '');
+    const verb = inner.split(' ')[1];
+    assert.ok(cliVerbs[verb], `allow-rule "${rule}" names "${verb}", which is not a registered bongos verb`);
+  }
+});
+
+t('the escape hatch is NOT blanket-allowed', () => {
+  // `bongos exec` runs any script inside the core by path. Allow-listing it bare
+  // would be a blanket grant wearing a narrow rule's clothes.
+  assert.ok(!m.STARTER_ALLOW.includes('Bash(bongos exec:*)'),
+    'bongos exec must never be allowed bare');
+  const execRules = m.STARTER_ALLOW.filter((r) => r.includes('bongos exec'));
+  for (const r of execRules) {
+    assert.match(r, /bongos exec scripts\/gds\/[a-z-]+\.js/,
+      `an exec rule must name its script in full, got: ${r}`);
+  }
+});
+
+t('a package-only install (no settings.json at the core root) GETS the starter', () => {
+  const core = mkdtempSync(join(tmpdir(), 'w3-starter-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'w3-starter-inst-'));
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true });   // skills ship; settings.json does not
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(res.settings, true, 'materialize should report it wrote settings');
+  const written = join(inst, '.claude', 'settings.json');
+  assert.ok(existsSync(written), 'instance must receive a starter settings.json');
+  const parsed = JSON.parse(readFileSync(written, 'utf8'));
+  assert.deepEqual(parsed.permissions.allow, m.STARTER_ALLOW);
+  rmSync(core, { recursive: true, force: true });
+  rmSync(inst, { recursive: true, force: true });
+});
+
+t("an instance's OWN settings.json is never clobbered", () => {
+  const core = mkdtempSync(join(tmpdir(), 'w3-keep-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'w3-keep-inst-'));
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true });
+  mkdirSync(join(inst, '.claude'), { recursive: true });
+  const mine = JSON.stringify({ permissions: { allow: ['Bash(echo hello:*)'] } }, null, 2);
+  writeFileSync(join(inst, '.claude', 'settings.json'), mine);
+  m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'), mine,
+    'an upgrade must never overwrite permissions the instance has grown');
+  rmSync(core, { recursive: true, force: true });
+  rmSync(inst, { recursive: true, force: true });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/ship_cannot_lie.mjs

@@ -17,6 +17,10 @@
 //
 // (3) --regrade must not swallow --notes. Same shape as (1): prose handed to
 //     ship.js that reaches nothing, silently (task 1003702).
+//
+// (4) --regrade must not silently REUSE the failed attempt's summary. The same
+//     silence as (3) from the other side: prose the builder never handed over,
+//     published as though they had (task 1003693).
 import { strict as assert } from 'node:assert';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
@@ -26,7 +30,7 @@ const require = createRequire(import.meta.url);
 const { argText } = require('../scripts/gds/cli-lib.js');
 const {
   fatalRecoveryLines, markShipProgress, _peekForTest,
-  proseFlagPresent, regradeNotesRefusal,
+  proseFlagPresent, regradeNotesRefusal, staleSummaryNotice,
 } = require('../scripts/gds/ship-honesty.js');
 
 // Injected IO so no case touches the filesystem.
@@ -297,3 +301,73 @@ test('a re-grade that omits --summary leaves the stored value_summary alone', ()
   // And a failed write never aborts the re-grade — no process.exit, no throw.
   assert.ok(!/process\.exit/.test(code), 'a summary that will not persist must not kill the re-grade');
 });
+
+// ── (4) an omitted --summary on a re-grade says so (task 1003693) ────────────
+//
+// The sibling of the ACCEPTANCE 2 test above. That one pins that an omitted
+// --summary does not OVERWRITE the row; this one pins that it does not pass in
+// SILENCE. Both postures were already right and the gap was between them: the
+// default re-grade re-publishes the failed attempt's sentence to #ship-news
+// with nothing saying so (task 1002343, 2026-09-07).
+
+test('the stale-summary notice quotes the sentence and names the fix', () => {
+  const lines = staleSummaryNotice(1002343, 'No project was created and nothing on the live system was left changed.');
+  const text = lines.join('\n');
+  // The builder cannot judge a summary they are not shown — the whole point is
+  // that the stored sentence is plausible until you read it next to the work.
+  assert.match(text, /No project was created and nothing on the live system was left changed\./,
+    'quotes the stored sentence verbatim');
+  // A notice that names no fix is noise with a warning sign on it.
+  assert.match(text, /--regrade --summary-file/, 'names the correcting flag');
+  assert.match(text, /ship\.js 1002343 --regrade/, 'as a runnable command with the real task id');
+  // WHY it matters: this text becomes the durable public record, not just a log line.
+  assert.match(text, /#ship-news/, 'says where the sentence ends up');
+  assert.match(text, /FAILED its grade/, 'says which attempt the stored sentence describes');
+});
+
+test('the notice stays silent when there is no stored summary to go stale', () => {
+  // No stored text means nothing can be re-published wrongly; an empty summary
+  // is the merge leg's problem. Warning here would train the builder to skip it.
+  for (const empty of ['', '   ', null, undefined]) {
+    assert.deepEqual(staleSummaryNotice(1, empty), [], `silent for ${JSON.stringify(empty)}`);
+  }
+});
+
+test('the quoted sentence is always one readable line', () => {
+  // value_summary allows up to LIMITS.VALUE_SUMMARY characters and may hold
+  // newlines. Either would break the quoted line out of the notice block and
+  // bury the runnable command that follows it.
+  const long = staleSummaryNotice(7, 'x'.repeat(400));
+  assert.ok(long[1].length < 160, 'a long summary is truncated');
+  assert.match(long[1], /…/, 'and says it was truncated');
+  const multi = staleSummaryNotice(9, 'line one\n\nline two\ttabbed');
+  assert.equal(multi[1].split('\n').length, 1, 'newlines collapse');
+  assert.match(multi[1], /"line one line two tabbed"/, 'into single spaces');
+
+  // This is the one place a stored summary reaches a TERMINAL. \s does not match
+  // ESC, so the collapse above would pass an escape sequence straight through and
+  // let it repaint the notice around itself.
+  const esc = staleSummaryNotice(11, 'safe\u001b[31mred\u0007 text');
+  assert.ok(!/[\u0000-\u001f\u007f-\u009f]/.test(esc.join(' ')),
+    'terminal control characters are stripped before display');
+  assert.match(esc[1], /"safe \[31mred text"/, 'and the readable text survives');
+});
+
+test('the notice is wired into the regrade path, before any grade spend', () => {
+  // The (1) lesson again: a helper nothing calls is not a fix. And the ORDER is
+  // load-bearing for the same reason the --notes refusal's is — a warning the
+  // builder reads only after a 4-worker panel has run cannot change that run.
+  const src = readFileSync(new URL('../scripts/gds/ship-flow.js', import.meta.url), 'utf8');
+  const regrade = src.slice(src.indexOf('async function regradeMain'));
+  const code = regrade.replace(/\/\/[^\n]*/g, ''); // comments describe, they do not print
+
+  const call = code.indexOf('staleSummaryNotice(taskId, task.value_summary)');
+  assert.ok(call !== -1, 'regradeMain emits the notice');
+  // Keyed on the RAW flag, like persistRegradeSummary — `summary` has already
+  // absorbed the fallback by this point, so testing it would never be falsy.
+  // Brace-form or one-liner, but it must branch on summaryArg and nothing else.
+  assert.match(code, /if \(!summaryArg\)\s*\{?\s*(\n\s*)?for \(const line of staleSummaryNotice/,
+    'it fires on the raw omitted flag, not the resolved fallback');
+  const preflight = code.indexOf('preflight(claimLike');
+  assert.ok(preflight !== -1 && call < preflight, 'and prints before the preflight and the panel');
+});

package/tests/skill_friction_kind.mjs

@@ -0,0 +1,163 @@
+// tests/skill_friction_kind.mjs
+//
+// 'skill-friction' as a real idea kind, and the one predicate that hides those
+// rows from a Xenos (task 1003105, goal 1000095, from idea 1000759).
+//
+// Two things are pinned here, and they fail in different directions.
+//
+// THE DRIFT TRIPWIRE. `VALID_KINDS` in JS and the CHECK constraint in SQL are
+// two lists that must say the same thing, and nothing made them. Widening one
+// and not the other is silent in both directions: a kind added only to JS gets
+// past validation and dies on INSERT with a constraint violation instead of a
+// clean BAD_KIND, and a kind added only to SQL is unreachable. That is the exact
+// shape of the bug this task fixed, so the fix ships with the tripwire.
+//
+// THE FOUR GATES. Skill-friction rows are hidden from Xenos-rank builders in
+// four separate read paths. They used to be four hand-copied conditions testing
+// a title prefix; now that the marker can ALSO be a kind, four copies would be
+// four chances for one to learn about the kind and the others not to — and a
+// gate that silently stops hiding is invisible until the wrong reader sees the
+// row. So there is one predicate, and these tests hold it to both markers, to
+// correct bind-parameter numbering, and to costing nothing for a viewer who may
+// see everything.
+//
+// Pure: no DB, no network.
+//
+// Run:  node tests/skill_friction_kind.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const inbox = require('../modules/ideas/inbox.js');
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// The migration that currently defines the constraint. If a later migration
+// widens it again, point this at that file — forcing that edit is the job.
+const CONSTRAINT_MIGRATION = path.join(
+  ROOT, 'migrations', 'core_244_skill_friction_kind.sql'
+);
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+// ---- the kind exists at all ------------------------------------------------
+
+test('skill-friction is a valid kind, so the two skills that file one stop failing BAD_KIND', () => {
+  assert.ok(
+    inbox.VALID_KINDS.includes('skill-friction'),
+    "/planning-session and /priority-session both instruct kind='skill-friction'"
+  );
+  assert.equal(inbox.SKILL_FRICTION_KIND, 'skill-friction');
+});
+
+test('widening the enum did not drop anything that was already in it', () => {
+  for (const k of [
+    'feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture',
+    'cleanup', 'decision', 'blocker-resolution', 'unclassified', 'criterion-proposal',
+  ]) {
+    assert.ok(inbox.VALID_KINDS.includes(k), `${k} missing from VALID_KINDS`);
+  }
+});
+
+// ---- JS and SQL say the same thing -----------------------------------------
+
+test('the SQL CHECK constraint and VALID_KINDS list exactly the same kinds', () => {
+  const sql = fs.readFileSync(CONSTRAINT_MIGRATION, 'utf8');
+  const m = /CHECK\s*\(\s*kind\s+IN\s*\(([\s\S]*?)\)\s*\)/i.exec(sql);
+  assert.ok(m, 'the migration declares a CHECK (kind IN (...)) constraint');
+
+  const fromSql = [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
+  assert.ok(fromSql.length > 0, 'the constraint lists at least one kind');
+
+  const a = [...fromSql].sort();
+  const b = [...inbox.VALID_KINDS].sort();
+  assert.deepEqual(
+    a, b,
+    `SQL and JS disagree — only in SQL: [${a.filter((k) => !b.includes(k))}], ` +
+    `only in JS: [${b.filter((k) => !a.includes(k))}]`
+  );
+});
+
+// ---- the visibility gate ---------------------------------------------------
+
+test('a viewer who may see everything costs no clause and no bind parameters', () => {
+  for (const rank of [null, undefined, 'metic', 'archon', 'Archon', 'something-new']) {
+    const params = [];
+    assert.equal(inbox.skillFrictionHiddenClause(rank, params), null, `rank=${rank}`);
+    assert.equal(params.length, 0, `rank=${rank} pushed no params`);
+  }
+});
+
+test('a Xenos is hidden from BOTH markers — the kind and the legacy title prefix', () => {
+  const params = [];
+  const clause = inbox.skillFrictionHiddenClause('xenos', params);
+  assert.ok(clause, 'a Xenos gets a clause');
+  assert.match(clause, /kind <> \$1/, 'the kind marker is tested');
+  assert.match(clause, /title NOT LIKE \$2/, 'the legacy prefix marker is tested too');
+  assert.deepEqual(params, [inbox.SKILL_FRICTION_KIND, `${inbox.SKILL_FRICTION_TAG}%`]);
+});
+
+test('the rank test is case-insensitive, so a capitalised Xenos is still hidden', () => {
+  const params = [];
+  assert.ok(inbox.skillFrictionHiddenClause('XENOS', params), 'XENOS is still a Xenos');
+  assert.equal(inbox.rankCanSeeSkillFriction('Xenos'), false);
+  assert.equal(inbox.rankCanSeeSkillFriction('metic'), true);
+  assert.equal(inbox.rankCanSeeSkillFriction(null), true);
+});
+
+test('bind parameters are numbered from where the caller already was, not from 1', () => {
+  const params = ['open', 42];
+  const clause = inbox.skillFrictionHiddenClause('xenos', params, 'i');
+  assert.match(clause, /i\.kind <> \$3/, 'continues the caller\'s numbering');
+  assert.match(clause, /i\.title NOT LIKE \$4/);
+  assert.equal(params.length, 4, 'and appended exactly two');
+});
+
+test('the table alias is applied to both columns or to neither', () => {
+  const withAlias = inbox.skillFrictionHiddenClause('xenos', [], 'i');
+  assert.match(withAlias, /i\.kind/);
+  assert.match(withAlias, /i\.title/);
+  const bare = inbox.skillFrictionHiddenClause('xenos', []);
+  assert.doesNotMatch(bare, /\bi\./, 'no alias means no alias on either column');
+  assert.match(bare, /\bkind <>/);
+  assert.match(bare, /\btitle NOT LIKE/);
+});
+
+test('the clause is parenthesised, so ANDing it into a WHERE cannot change the other terms', () => {
+  const clause = inbox.skillFrictionHiddenClause('xenos', []);
+  assert.ok(clause.startsWith('(') && clause.endsWith(')'), `not parenthesised: ${clause}`);
+  assert.match(clause, / AND /, 'both markers must hold for the row to be shown');
+});
+
+// ---- the legacy marker is not quietly retired ------------------------------
+
+test('the legacy title prefix is still exported and still the nightly routine\'s marker', () => {
+  assert.equal(inbox.SKILL_FRICTION_TAG, '[skill-friction]');
+  const routine = fs.readFileSync(
+    path.join(ROOT, '.claude', 'scheduled-tasks', 'skill-usage-review', 'SKILL.md'), 'utf8'
+  );
+  assert.ok(
+    routine.includes('[skill-friction]'),
+    'skill-usage-review still tags the prefix — the gate must keep recognising it'
+  );
+});
+
+console.log('');
+console.log(`skill-friction kind + visibility gate (task 1003105): ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);