@bongos/core 1.21.151 → 1.21.153

package/modules/public-landing/public/projects.html

@@ -1140,6 +1140,7 @@ summary{min-height:24px;padding:3px 0;}
              stripFor/errMarkup/canRetry/canRevive the list row reads -->
         <div id="mStrip"></div>
         <div class="projMsg err" id="mErr" hidden></div>
+        <div class="projMsg" id="mGh" hidden></div>
         <div class="projMsg" id="mMsg" role="status" aria-live="polite"></div>
         <div class="actions" id="mActs" hidden></div>
       </div>
@@ -8357,6 +8358,8 @@ summary{min-height:24px;padding:3px 0;}
        (renderCard) — a project the owner is being told about cannot sit under
        Live. The intent-vs-status contract is deliberately left alone. */
     if (inst.error_note && !inst.open_intent) return 'attention';
+    /* an app nobody installed blocks every ship until the owner acts (task 1004763) */
+    if (ghInstallRow(inst)) return 'attention';
     return STATE_GROUP[inst.status] || 'all';
   }
   function findText(inst) {
@@ -8828,6 +8831,21 @@ summary{min-height:24px;padding:3px 0;}
       '">Say what it is</a> and it goes on.';
   }
 
+  /* the standing GitHub install nudge (task 1004763). A project whose app was made but never
+     installed on its repo cannot have finished work added: the platform cannot read the
+     repo, so every ship stops short. The wizard's checklist shows only while a project is
+     being made, so the card and the project's own page say it, with GitHub's own install
+     link, until the runner has seen the install. The click also asks for a fresh look
+     (the a[data-gh-install] handler below). '' when there is nothing to install. */
+  function ghInstallRow(inst) {
+    var g = inst && inst.github_install;
+    if (!g || !/^https:\/\/github\.com\/apps\//.test(String(g.install_url || ''))) return '';
+    if (inst.status === 'torn_down' || inst.status === 'tearing_down') return '';
+    return 'Finished work can’t be added to ' + (g.repo ? '<code>' + esc(g.repo) + '</code>' : 'its repo') +
+      ' until the GitHub App is installed on it. <a class="btn small" href="' + esc(g.install_url) +
+      '" target="_blank" rel="noopener" data-gh-install="' + esc(String(inst.id)) + '">Install the GitHub App ↗</a>';
+  }
+
   function renderCard(inst) {
     /* iid is for MARKUP interpolation only (esc() = HTML escape); the DOM
        lookup goes through liFor(), which CSS-escapes — the two escapes are
@@ -8851,6 +8869,8 @@ summary{min-height:24px;padding:3px 0;}
     if (addr) body += '<div class="addr">' + addr + '</div>';
     var pub = publishRow(inst);
     if (pub) body += '<div class="projMsg">' + pub + '</div>';
+    var gh = ghInstallRow(inst);
+    if (gh) body += '<div class="projMsg">' + gh + '</div>';
     if ((inst.status === 'error' || inst.error_note) && !inst.open_intent) {
       /* once a retry is queued the strip tells the story — the stale error
          paragraph would just contradict it (owner walk, 2026-08-12). Also
@@ -9198,6 +9218,9 @@ summary{min-height:24px;padding:3px 0;}
     var snag = (inst.status === 'error' || inst.error_note) && !inst.open_intent;
     $('mErr').innerHTML = snag ? errMarkup(inst) : '';
     $('mErr').hidden = !snag;
+    var gh = ghInstallRow(inst);
+    $('mGh').innerHTML = gh;
+    $('mGh').hidden = !gh;
     var acts = [];
     if (inst.status === 'active' && addressReady(inst)) acts.push('<a class="btn small ghost" href="https://' + esc(inst.domain) + '" target="_blank" rel="noopener">Open site →</a>');
     if (canRetry(inst)) acts.push('<button type="button" class="btn small" data-m-retry>Try again</button>');
@@ -11231,6 +11254,16 @@ summary{min-height:24px;padding:3px 0;}
     return e.message || 'The restart could not be queued — try again in a moment.';
   }
 
+  /* the install nudge's click (task 1004763), on the card and the project's own page alike:
+     GitHub opens in its own tab as the link says, and the platform is asked to look again.
+     GitHub's hand-back from this link carries no attempt, so without the ask nothing would
+     re-check and the nudge would never clear. Best-effort: a refused ask changes nothing. */
+  document.addEventListener('click', function (ev) {
+    var a = ev.target.closest && ev.target.closest('a[data-gh-install]');
+    if (!a) return;
+    fetch(API + '/provisioning/instances/' + encodeURIComponent(a.getAttribute('data-gh-install')) + '/github-app/pick-up', { method: 'POST', credentials: 'same-origin' }).catch(function () {});
+  });
+
   /* the list's one delegated handler. A row holds no sender since task 1003355
      — only its two doors — so the Manage link is all there is to upgrade: it is
      a real anchor, a modified click keeps its browser meaning and a plain one

package/modules/render-deploy/module.json

@@ -4,6 +4,7 @@
   "description": "The deploy page for a project whose app deploys through Render: the service's Render deploys, each tied to its commit and the Bongos tasks it carried, what is live now, and deploy and roll back behind a two-step confirm (task 1004270). Off in every hall until its owner turns it on.",
   "version": "1.0.0",
   "coreVersion": "^1.19.0",
+  "category": { "parent": "hosting" },
   "default": false,
   "author": "Cloud Bongos",
   "origin": "Cloud Bongos core",

package/modules/security/module.json

@@ -4,6 +4,7 @@
   "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule. Also owns the scan-before-install surface (goal 1000055): the artifact-scan engine (quarantine/manifest/mirror) and the security_tool_scans record — POST Metic+, GET every rank.",
   "version": "1.0.0",
   "coreVersion": "^1.8.0",
+  "category": { "parent": "quality" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["reports", "scans"], "migrations": true },

package/modules/sessions/module.json

@@ -4,6 +4,7 @@
   "description": "The session-records corpus + its data plane (POST /sessions upload, the Archon-gated cross-builder /sessions/search + /sessions/:id deep-dive + /sessions/upload-health, the server-side signal that a builder's session uploads have silently stopped), the BFG 'read-the-room' cross-builder scorer (ADR 0026 §6B), and the session-pulse / stale-claim heartbeat helpers. A core-domain module carved out of the GDS core in BV1.R82 (ADR 0093 §1); default-on because every instance records its builders' sessions for the BFG. Like the memory module, sessions registers no port — core never calls back into it: the ship-time digest write is an HTTP POST to the module's own /sessions route, and the only outward dependency is the economy `reward` kernel PORT it resolves (session token reward + sumCreditsForTasks) at upload time.",
   "version": "1.0.0",
   "coreVersion": "^1.10.0",
+  "category": { "parent": "knowledge" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["sessions"], "pollers": ["session-reward-reconcile", "session-upload-health"] },

package/modules/specialities/module.json

@@ -4,6 +4,7 @@
   "description": "Role SUB-SPECIALITIES — a named bundle of knowledge, skills and an interaction contract that sits UNDER a craft (task 1003855; ADR 0296). A craft says how you work (engineer / ideator / artist / ui); a speciality says what you work ON and how a subject-matter expert wants to be engaged inside it. Deliberately a thin layer over three surfaces that already exist — discipline-modes.json for craft->playbook, behavior_prefs.interaction for the per-session contract (a speciality contract rides that SAME GET /me -> Conductor path rather than adding a second one), and the ADR 0083 manifest for declared skills; the only new machinery is the knowledge bundle. Training is two-fold per the owner's 2026-09-17 ruling: documents the builder supplied, plus learnings captured from sessions worked in the speciality (pointing at existing `learnings` rows, never a second corpus). Owned per-builder OR per-project, each carrying its owner's sharing decision (private / project / public) and an explicit sellable flag — the flag records intent only, because ADR 0107 defers the marketplace and there is nothing to list on. default-on: a speciality is how an instance's expertise enters the platform, so it ships like the hall and the status page.",
   "version": "1.0.0",
   "coreVersion": "^1.19.0",
+  "category": { "parent": "people" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "migrations": true,

package/modules/status-ui/module.json

@@ -4,6 +4,7 @@
   "description": "The public build-status dashboard served at status.<apex> (status.example.com) — the live up/down banner, version-progress rollups, cost summary, recent ships, leaderboard, and the ecosystem fingerprint, all polling the read-only /api/bongos/public/* surface every 60s. A WEB-SURFACE core-domain module carved out of the GDS core in BV1.R84 (ADR 0093 §1; 02-module-map §6 — a web surface is first-class). default-on: a Cloud Bongos instance ships its status page like it ships its hall. Registers no port and contributes no routes — it declares a webSurface (host prefix + static dir) the loader hands serve-internal, which serves the module's public/ dir on the matching host exactly as it served public-status/ before. The public read endpoints it renders stay SHARED core in routes/public.js (the hall + the off-box mirror read them too).",
   "version": "1.0.0",
   "coreVersion": "^1.11.0",
+  "category": { "parent": "pages" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": {

package/modules/ui-design/module.json

@@ -4,6 +4,7 @@
   "description": "The platform capability that lets any builder on any instance create and design good-looking, functional UIs in line with that instance's world (scoped with the owner 2026-08-28; task 1003324, ADR 0197). It ships METHOD and never a world: the neutral design contract of ADR 0081 with its tool adapters (Claude Design, Figma), their sync CLIs and the validator; the /design playbook for ui-discipline work; the look-before-you-ship kit (kit/) and the style library (styles/). The thirteen design-style skills that lived in skills/ are the opt-in design-styles module since task 1004470; /design reaches them when that module is on. The instance's world — its branding pack, config/design-tokens.*, config/design-sources.json and its DESIGN.md — stays in config/ and at the repo root as the host boundary this module reads and never owns (ADR 0062 §7). Cloud Bongos's own front door is this module's first customer, not its owner. default-on because every instance has a face. No routes, no migrations, no port: declaration-only like character-anim, so disabling it withdraws only the skills it contributes and touches no served surface.",
   "version": "1.0.0",
   "coreVersion": "^1.19.0",
+  "category": { "parent": "pages" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "skills": ["design", "design-sync", "figma-design-sync"], "disciplines": ["ui"] },

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.151",
+  "version": "1.21.153",
   "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/release-notes.json

@@ -9920,5 +9920,25 @@
       "id": "1004739",
       "text": "The module test runner can now test against the private core: the server sends its own copy of the core into the private test repo, once per version."
     }
+  ],
+  "1.21.152": [
+    {
+      "id": "1003784",
+      "text": "Every module now says which of the eight categories it belongs to, and the module list in the terminal and the hall's Modules tab both show it and let you search by it."
+    }
+  ],
+  "1.21.153": [
+    {
+      "id": "1004763",
+      "text": "Project owners whose GitHub App was never installed now see an \"Install the GitHub App\" button on their project until GitHub confirms it."
+    },
+    {
+      "id": "1003799",
+      "text": "Two store modules with the same score no longer look identical: each now shows what it is strong at and weak at (tests, installs, reliability, testers, how-to), in the store listing and in the hall's Modules tab."
+    },
+    {
+      "id": "1004766",
+      "text": "When a project's server can't talk to GitHub, the land-status check now says which step failed and what GitHub answered, instead of a bare error."
+    }
   ]
 }

package/scripts/gds/module.js

@@ -452,14 +452,16 @@ function formatCatalog(rows, { catalogOnly = false, query = '', core = null, del
     return out.join('\n');
   }
 
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('CATEGORY', 28)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
   for (const r of shown) {
     const mark = r.enabled ? '[x]' : '[ ]';
     // An inferred credit is marked so it never reads as something the author
     // typed — the catalog's whole job is honest attribution (ADR 0107 §2).
     const suffix = r.credit.inferred ? '*' : '';
     const upkeep = ((r.maintenance && r.maintenance.status) || 'undeclared') + (delisted.has(r.key) ? ' · DELISTED' : '');
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
+    // The parent key, plus the sub-category once one is approved (ADR 0342).
+    const cat = r.category ? r.category.parent + (r.category.sub ? `/${r.category.sub}` : '') : '—';
+    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip(cat, 27), 28)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
   }
   out.push('');
   out.push('  [x] enabled here · [ ] available, not enabled');

package/src/bongos/module-listing.js

@@ -35,6 +35,63 @@ function placeVersion(score, floor = QUALITY_FLOOR) {
   return { placement: 'listed', reason: 'at_or_above_floor' };
 }
 
+// ---------------------------------------------------------------------------
+// Strengths and weaknesses (task 1003799, ADR 0343 D4)
+// ---------------------------------------------------------------------------
+//
+// The overall number sorts the listing; the parts explain it. Two modules that both
+// score 74 can be good at different things, and a buyer who cares about reliability
+// should be able to see which one is. So each listed entry carries its parts and a
+// short reading of them:
+//
+//   strength    a part scored at or above STRONG_AT
+//   weakness    a part scored below the floor — the same bar the listing uses
+//   unmeasured  a part with no score yet (no installs, no testers, still running).
+//               Never a weakness: a missing part is never a zero (D3/D5).
+//
+// Security is not on the list: it is a pass/fail gate (D2), and every listed
+// version has passed it. The thresholds are fixed numbers on purpose, so an author
+// can check why a part reads as strong or weak, the same way the floor works.
+const STRONG_AT = 80;
+
+// The parts a buyer compares, in the order they are shown, with what their
+// sample size counts. `docs` is shown but never averaged (ADR 0347).
+const PARTS = [
+  { part: 'tests', title: 'Tests', counts: 'test cases' },
+  { part: 'install', title: 'Clean installs', counts: 'installs' },
+  { part: 'reliability', title: 'Reliability', counts: 'installs' },
+  { part: 'tester_feedback', title: 'Tester feedback', counts: 'testers' },
+  { part: 'docs', title: 'How-to', counts: null },
+];
+
+// One reading of one version's current part results. `signals` is the newest
+// module_assessment_signals row per part ({ part, outcome, score, sample_size });
+// a part with no row is unmeasured. Pure.
+function readParts(signals = [], { floor = QUALITY_FLOOR } = {}) {
+  const byPart = new Map(signals.map((s) => [s.part, s]));
+  const parts = {};
+  const strengths = [];
+  const weaknesses = [];
+  const unmeasured = [];
+  for (const { part, title, counts } of PARTS) {
+    const s = byPart.get(part);
+    const scored = s && s.outcome === 'scored' && Number.isFinite(Number(s.score));
+    parts[part] = s
+      ? { outcome: s.outcome, score: scored ? Number(s.score) : null, sample_size: s.sample_size == null ? null : Number(s.sample_size) }
+      : { outcome: 'no_data', score: null, sample_size: null };
+    if (!scored) { unmeasured.push({ part, title }); continue; }
+    const score = Number(s.score);
+    const n = parts[part].sample_size;
+    const from = counts && n ? `, from ${n} ${n === 1 ? counts.replace(/s$/, '') : counts}` : '';
+    const item = { part, title, score, detail: `${title} scored ${score} out of 100${from}.` };
+    if (score >= STRONG_AT) strengths.push(item);
+    else if (score < floor) weaknesses.push(item);
+  }
+  strengths.sort((a, b) => b.score - a.score);
+  weaknesses.sort((a, b) => a.score - b.score);
+  return { parts, strengths, weaknesses, unmeasured };
+}
+
 // The newest version row per module key, in semver order (a version that does not
 // parse is skipped, as latestVersions does in module-store.js).
 function newestPerModule(rows) {
@@ -50,7 +107,8 @@ function newestPerModule(rows) {
 }
 
 // The catalog: { floor, listed: [...], new: [...] }, each entry
-// { key, title, version, published_at, overall, is_new }. Excluded versions are left
+// { key, title, version, published_at, overall, is_new, parts, strengths, weaknesses,
+// unmeasured } (the last four from readParts). Excluded versions are left
 // out entirely: a module below the bar is not listed at all. Both lists are in key
 // order; ranking is a separate task (1003808) and does not happen here.
 async function listCatalog({ db, floor = QUALITY_FLOOR } = {}) {
@@ -69,6 +127,21 @@ async function listCatalog({ db, floor = QUALITY_FLOOR } = {}) {
         ORDER BY version_id, computed_at DESC, id DESC`, [newest.map((r) => r.version_id)]);
     for (const s of rows) scores.set(String(s.version_id), s);
   }
+  // Each version's current result per part: the newest row per (version, part),
+  // the read idx_module_assessment_signals_current exists for (core_265).
+  const signals = new Map();
+  if (newest.length) {
+    const { rows } = await pool.query(
+      `SELECT DISTINCT ON (version_id, part) version_id, part, outcome, score, sample_size
+         FROM module_assessment_signals
+        WHERE version_id = ANY($1)
+        ORDER BY version_id, part, measured_at DESC, id DESC`, [newest.map((r) => r.version_id)]);
+    for (const s of rows) {
+      const k = String(s.version_id);
+      if (!signals.has(k)) signals.set(k, []);
+      signals.get(k).push(s);
+    }
+  }
   const out = { floor, listed: [], new: [] };
   for (const r of newest.sort((a, b) => a.module_key.localeCompare(b.module_key))) {
     const score = scores.get(String(r.version_id)) || null;
@@ -77,9 +150,10 @@ async function listCatalog({ db, floor = QUALITY_FLOOR } = {}) {
     out[placement].push({
       key: r.module_key, title: r.title, version: r.version, published_at: r.published_at,
       overall: placement === 'new' ? null : score.overall, is_new: placement === 'new',
+      ...readParts(signals.get(String(r.version_id)) || [], { floor }),
     });
   }
   return out;
 }
 
-module.exports = { QUALITY_FLOOR, placeVersion, listCatalog };
+module.exports = { QUALITY_FLOOR, STRONG_AT, placeVersion, readParts, listCatalog };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.151'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.153'; // 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('discord'); log.info('mounted');

package/src/module-loader/catalog.js

@@ -30,6 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { deriveProvenance } = require('./provenance');
+const { CATEGORY_PARENTS } = require('./manifest-schema');
 
 // The core's own published + source package names. A checkout whose package.json
 // says one of these IS the core, so its modules/ IS the catalog (see
@@ -99,6 +100,17 @@ function creditFor(manifest = {}, { source = 'instance', coreProjectName = CORE_
   };
 }
 
+// Where a module is browsed (ADR 0342): its parent key, that parent's label, and its
+// sub-category key — or null when the manifest declares none. The label is resolved
+// HERE so the hall and the CLI never keep their own copy of the parent list. A parent
+// outside the closed list cannot reach this (the validator refuses it), so an unknown
+// one is null rather than shown under a label nobody chose.
+function categoryFor(manifest = {}) {
+  const c = manifest.category;
+  if (!c || typeof c !== 'object' || !Object.hasOwn(CATEGORY_PARENTS, c.parent)) return null;
+  return { parent: c.parent, parentTitle: CATEGORY_PARENTS[c.parent], sub: c.sub || null };
+}
+
 // One catalog row per discovered module. `loaded` is the loader's
 // discoverModules().loaded ([{ key, dir, manifest }]); `enabled` is the resolved
 // enablement map (src/modules.js modules()).
@@ -138,6 +150,7 @@ function buildCatalog({
         license: manifest.license || null,
         maintainer: manifest.maintainer || null,
         maintenance: manifest.maintenance || null,
+        category: categoryFor(manifest),
       };
     })
     .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
@@ -160,7 +173,8 @@ function instanceRows(rows = []) {
 function searchCatalog(rows = [], query = '') {
   const q = String(query || '').trim().toLowerCase();
   if (!q) return rows;
-  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license]
+  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license,
+    r.category && r.category.parentTitle, r.category && r.category.sub]
     .some((f) => f && String(f).toLowerCase().includes(q)));
 }
 

package/src/module-loader/manifest-schema.js

@@ -53,6 +53,10 @@
 //                                       //   actually declares in `contributes`, and every entry must be
 //                                       //   one it actually lists there — a typo'd exemption is an error,
 //                                       //   never a silent pass.
+//     "category": {                     // OPTIONAL. Where the module is browsed and ranked (ADR 0342).
+//       "parent": "money",              //   REQUIRED in-block: one of the eight CATEGORY_PARENTS keys.
+//       "sub":    "stripe-payments"     //   OPTIONAL. An approved sub-category key — the comparable set
+//     },                                //   the store's cap of ten counts within; absent while pending.
 //     "howto": {                        // OPTIONAL. Extras beside the module's HOWTO.md (ADR 0347 D3).
 //       "artifactUrl": "https://claude.ai/…" //   A Claude page with the same how-to, shown as an extra,
 //     },                                //   never graded and never required — the file is the how-to.
@@ -106,6 +110,24 @@ const SPEND_KEYS = ['requiresPayer'];
 // The `howto` block (ADR 0347 D3) — closed for the same reason; not exported either.
 const HOWTO_KEYS = ['artifactUrl'];
 
+// The eight fixed parent categories (ADR 0342 D1), key → the label a catalog shows.
+// A parent is for browsing only: the cap of ten counts within a SUB-category, never a
+// parent (D2). The list is closed so a typo'd "monye" fails loud rather than filing
+// the module under a ninth parent nobody browses; changing it needs a new ADR.
+// `sub` is shape-checked only — which sub-categories are approved is ledger state
+// (task 1004355), not something a pure validator can know.
+const CATEGORY_PARENTS = Object.freeze({
+  work: 'Work & planning',
+  people: 'Team & people',
+  quality: 'Quality & review',
+  money: 'Money',
+  communication: 'Communication',
+  pages: 'Pages & design',
+  hosting: 'Hosting & deploy',
+  knowledge: 'Knowledge',
+});
+const CATEGORY_KEYS = ['parent', 'sub'];
+
 // An https link on claude.ai (or a subdomain). Shape only: the store never fetches it.
 function isClaudeArtifactUrl(v) {
   if (!isStr(v)) return false;
@@ -320,6 +342,23 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional category (ADR 0342) ---
+  if ('category' in obj) {
+    const c = obj.category;
+    const parents = Object.keys(CATEGORY_PARENTS);
+    if (!isObj(c)) E('category: must be an object (e.g. { "parent": "money", "sub": "stripe-payments" })');
+    else {
+      for (const k of Object.keys(c)) {
+        if (!CATEGORY_KEYS.includes(k)) E(`category.${k}: unknown key (allowed: ${CATEGORY_KEYS.join(', ')}) — a module has exactly one sub-category (ADR 0342 D4)`);
+      }
+      if (!isStr(c.parent)) E(`category.parent: required — one of ${parents.join(', ')}`);
+      else if (!parents.includes(c.parent)) E(`category.parent: "${c.parent}" is not one of ${parents.join(', ')} (ADR 0342 D1)`);
+      if ('sub' in c && (!isStr(c.sub) || !KEY_RE.test(c.sub))) {
+        E('category.sub: must be a sub-category key (lowercase kebab-case) when present — leave it out while a new one is pending approval');
+      }
+    }
+  }
+
   // --- optional how-to extras (ADR 0347 D3) ---
   if ('howto' in obj) {
     const h = obj.howto;
@@ -370,5 +409,5 @@ function assertValidManifest(obj, label = 'module.json') {
 
 module.exports = {
   validateManifest, assertValidManifest, declaredEntries, entryLabel, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS,
-  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES,
+  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES, CATEGORY_PARENTS,
 };

package/tests/github_failure.mjs

@@ -0,0 +1,79 @@
+// tests/github_failure.mjs — a failed GitHub call says WHICH step broke and what
+// GitHub answered (task 1004766).
+//
+// On the toast instance every GET /tasks/:id/publish-status answered a bare 502
+// `status_failed` with no message, and the server log carried one word. The thrown
+// errors already held the step (code) and GitHub's reply (status, detail).
+//
+// Run:  node tests/github_failure.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+const { describeGithubFailure } = require(path.join(ROOT, 'modules/lifecycle/github-failure.js'));
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); }
+}
+const thrown = (code, extra = {}) => Object.assign(new Error(code), { code }, extra);
+
+t('an App token refusal names the step and GitHub\'s answer', () => {
+  const r = describeGithubFailure(thrown('APP_TOKEN_FAILED', { status: 401, detail: '{"message":"A JSON web token could not be decoded"}' }));
+  assert.match(r.message, /GitHub App token/);
+  assert.match(r.message, /HTTP 401: \{"message":"A JSON web token could not be decoded"\}/);
+  assert.equal(r.details.cause, 'APP_TOKEN_FAILED');
+  assert.equal(r.details.github_status, 401);
+  assert.match(r.log, /APP_TOKEN_FAILED \(GitHub HTTP 401/);
+});
+
+t('a refused repository read is told apart from a token failure', () => {
+  const r = describeGithubFailure(thrown('STATUS_FETCH_FAILED', { status: 403 }));
+  assert.match(r.message, /refused a read of the repository/);
+  assert.match(r.message, /HTTP 403\./);
+  assert.equal(r.details.github_detail, null);
+});
+
+t('an unknown error still says something, and never invents a GitHub status', () => {
+  const r = describeGithubFailure(new Error('fetch failed'));
+  assert.match(r.message, /unexpected error/);
+  assert.doesNotMatch(r.message, /HTTP/);
+  assert.equal(r.details.cause, null);
+  assert.equal(r.log, 'fetch failed');
+});
+
+t('GitHub\'s detail is capped', () => {
+  const r = describeGithubFailure(thrown('APP_TOKEN_FAILED', { status: 500, detail: 'x'.repeat(5000) }));
+  assert.ok(r.details.github_detail.length <= 300);
+});
+
+t('publish-status sends the description, not a bare 502', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/tasks.js'), 'utf8');
+  const i = src.indexOf("router.get('/tasks/:id/publish-status'");
+  const handler = src.slice(i, src.indexOf('router.', i + 20));
+  assert.match(handler, /failGithubStatus\(res, log, e\)/);
+  assert.doesNotMatch(handler, /res\.fail\('status_failed', 502\)/);
+});
+
+t('the route answer carries the message and logs the step', () => {
+  const { failGithubStatus } = require(path.join(ROOT, 'modules/lifecycle/github-failure.js'));
+  let sent = null;
+  const logged = [];
+  const res = { fail: (code, opts) => { sent = { code, ...opts }; return 'sent'; } };
+  const out = failGithubStatus(res, { error: (...a) => logged.push(a.join(' ')) }, thrown('APP_TOKEN_FAILED', { status: 401 }));
+  assert.equal(out, 'sent');
+  assert.equal(sent.code, 'status_failed');
+  assert.equal(sent.status, 502);
+  assert.match(sent.message, /GitHub App token.*HTTP 401/);
+  assert.match(logged[0], /APP_TOKEN_FAILED \(GitHub HTTP 401\)/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);