@bongos/core 1.19.486 → 1.19.488

package/modules/lifecycle/help-requests.js

@@ -20,10 +20,10 @@ const { pool } = require('../../src/module-api');
 // spells this same craft 'engineer', not 'builder'. THIS FUNCTION IS THE ONE PLACE
 // that knows the mapping — the matching surface (C02) must consume it rather than
 // re-deriving, or the two spellings drift and a builder silently matches nothing.
-const HELP_CRAFTS = Object.freeze(['artist', 'builder', 'ideator']);
-const CRAFT_TO_DISCIPLINE = Object.freeze({ artist: 'artist', ideator: 'ideator', builder: 'engineer' });
+const HELP_CRAFTS = Object.freeze(['artist', 'builder', 'ideator', 'ui']);
+const CRAFT_TO_DISCIPLINE = Object.freeze({ artist: 'artist', ideator: 'ideator', builder: 'engineer', ui: 'ui' });
 
-const DISCIPLINE_TO_CRAFT = Object.freeze({ artist: 'artist', ideator: 'ideator', engineer: 'builder' });
+const DISCIPLINE_TO_CRAFT = Object.freeze({ artist: 'artist', ideator: 'ideator', engineer: 'builder', ui: 'ui' });
 
 function helpCrafts() { return [...HELP_CRAFTS]; }
 function disciplineForCraft(craft) { return CRAFT_TO_DISCIPLINE[craft] || null; }

package/modules/lifecycle/migrations/lifecycle_006_help_requests_ui_craft.sql

@@ -0,0 +1,38 @@
+-- lifecycle_006_help_requests_ui_craft.sql — the `ui` craft becomes addressable in
+-- a help request (task 1003487, the routing half of goal 1000025's UI-reachability
+-- pair).
+--
+-- WHY THIS MIGRATION EXISTS AT ALL. lifecycle_004 fixed the craft vocabulary to
+-- ADR 0174's three (artist, builder, ideator) in a CHECK. `ui` became a real
+-- discipline later (migration 176 widened `builders.preferred_disciplines`, and
+-- discipline-modes.json routes a ui task to /design), and task 1003487 makes it
+-- selectable everywhere a builder chooses work. Every OTHER surface inherits that
+-- automatically because it validates against enabledDisciplines() at run time —
+-- this one does not, because a CHECK is compiled into the table. Without this the
+-- app would accept a help request addressed to `ui` (helpCrafts() now offers it)
+-- and Postgres would reject the INSERT, which is the worst shape of all: a
+-- constraint violation surfacing as a 500 on a feature that reads as supported.
+--
+-- THE VOCABULARY SEAM IS UNCHANGED. `builders.preferred_disciplines` spells the
+-- engineering craft 'engineer' while a help request spells it 'builder'; `ui` is
+-- spelled the same on both sides, so it simply joins the list. help-requests.js
+-- stays the single place that knows the mapping (CRAFT_TO_DISCIPLINE /
+-- DISCIPLINE_TO_CRAFT), and craftMapSql() generates its SQL CASE from that same
+-- object — so nothing here needs to restate it.
+--
+-- SAFE TO RE-RUN. Dropping by name and re-adding is idempotent in effect; existing
+-- rows all carry one of the three older values (or NULL) and satisfy the wider
+-- CHECK, so the ADD VALIDATE cannot fail on live data. No data is rewritten.
+
+ALTER TABLE lifecycle_help_requests
+  DROP CONSTRAINT IF EXISTS lifecycle_help_requests_craft_chk;
+
+ALTER TABLE lifecycle_help_requests
+  ADD CONSTRAINT lifecycle_help_requests_craft_chk
+    CHECK (needs_craft IS NULL OR needs_craft IN ('artist', 'builder', 'ideator', 'ui'));
+
+COMMENT ON COLUMN lifecycle_help_requests.needs_craft IS
+  'The craft this request is addressed to: ADR 0174''s three (artist, builder, ideator) plus ui, which the ui-design module contributes as a discipline (task 1003487). helpCrafts() in modules/lifecycle/help-requests.js is the single place that knows this vocabulary and its spelling seam with builders.preferred_disciplines.';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_006_help_requests_ui_craft')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/ship-card.js

@@ -159,7 +159,10 @@ function fmtMins(n) {
   return m ? `~${h}h${m}m` : `~${h}h`;
 }
 
-const DISCIPLINE_SKILL = { engineer: 'dev', artist: 'paint', ideator: 'ideate' };
+// Mirrors scripts/gds/discipline-modes.json, which is what claim.js prints. 'ui'
+// was missing here, so a UI task's card sent the builder to /dev while the claim
+// had just sent them to /design (task 1003487).
+const DISCIPLINE_SKILL = { engineer: 'dev', artist: 'paint', ideator: 'ideate', ui: 'design' };
 
 // The next-action per stage: { kind:'prompt', label, cmd } or { kind:'link', label, url }.
 function nextActionFor(stage, { taskId, discipline, sandboxUrl } = {}) {

package/modules/onboarding/newcomer-restock.js

@@ -32,22 +32,48 @@ const TEMPLATES_PATH = path.join(REPO_ROOT, 'scripts/gds/newcomer-floor.template
 const CONFIG_PATH = path.join(REPO_ROOT, 'scripts/gds/newcomer-floor.config.json');
 const SOURCE_TAG = 'newcomer-template';
 const HARD_MAX_MINUTES = 60;
-const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator']);
+// The crafts THIS instance offers, read through the published doorway (the one
+// core file a module may require, ADR 0083). This was a hardcoded Set that did not
+// track enabledDisciplines(), so it silently diverged the moment a module
+// contributed a craft: the picker could offer it, a builder could save it, and
+// restock would still never stamp its chores — a newcomer whose only craft was that
+// one saw an empty board with nothing to self-heal it (task 1003487).
+function validDisciplines() {
+  const { enabledDisciplines } = require('../../src/module-api');
+  return new Set(enabledDisciplines());
+}
 
 // Each discipline -> ARRAY of chore templates. A bare object (the pre-1488 single-
 // chore shape) is tolerated and wrapped, so an older/other instance's templates.json
 // still loads. Only entries with the required fields survive.
+//
+// Keyed by whatever the FILE declares (a leading-underscore key is metadata, not a
+// craft) and deliberately NOT narrowed to what this instance offers: this is the
+// catalogue of chores that EXIST, and choosing which of them to restock is
+// restockAll's job. Narrowing here would drop a disabled craft's chores from the
+// catalogue outright, which is a different question from "should we stamp them".
 function loadTemplates() {
   const raw = JSON.parse(fs.readFileSync(TEMPLATES_PATH, 'utf8'));
   const out = {};
-  for (const d of VALID_DISCIPLINES) {
-    if (!raw[d]) continue;
-    const list = Array.isArray(raw[d]) ? raw[d] : [raw[d]];
+  for (const [d, v] of Object.entries(raw)) {
+    if (d.startsWith('_') || !v) continue;
+    const list = Array.isArray(v) ? v : [v];
     out[d] = list.filter((t) => t && t.template_id && t.version_id && t.title);
   }
   return out;
 }
 
+// The crafts that HAVE chores defined — the guard for "can this discipline be
+// restocked at all", as distinct from validDisciplines() ("does this instance
+// offer it"), which is what decides whether we actually stamp.
+//
+// Takes an ALREADY-LOADED map: every hot path reads the templates once and passes
+// it here and to restockDiscipline, so a single restock does one readFileSync of
+// newcomer-floor.templates.json rather than one per helper per call.
+function templateDisciplines(byDiscipline = loadTemplates()) {
+  return new Set(Object.keys(byDiscipline));
+}
+
 // Per-discipline DEFAULT floor from config (fallback when a template omits its own).
 function loadFloors() {
   try {
@@ -150,9 +176,9 @@ async function restockTemplate(discipline, template, floors) {
 
 // Restock EVERY chore of a discipline to its floor. Returns an ARRAY of per-template
 // results (so a discipline with several chores tops each one up independently).
-async function restockDiscipline(discipline) {
-  if (!VALID_DISCIPLINES.has(discipline)) return [{ discipline, skipped: 'invalid discipline' }];
-  const templates = loadTemplates()[discipline] || [];
+async function restockDiscipline(discipline, byDiscipline = loadTemplates()) {
+  const templates = byDiscipline[discipline];
+  if (!templates) return [{ discipline, skipped: 'invalid discipline' }];
   if (!templates.length) return [{ discipline, skipped: 'no usable template' }];
   const floors = loadFloors();
   const out = [];
@@ -166,31 +192,35 @@ async function restockDiscipline(discipline) {
 // be matched to a known template. Returns an array of per-template results, or
 // [{ skipped:true }] for any non-chore task (callers ignore the value).
 async function restockForClaim(task) {
-  if (!task || task.source !== SOURCE_TAG || !VALID_DISCIPLINES.has(task.discipline)) {
-    return [{ skipped: true }];
-  }
-  const templates = loadTemplates()[task.discipline] || [];
+  // The cheap rejections first: a non-chore task is the common case and must not
+  // pay a file read at all.
+  if (!task || task.source !== SOURCE_TAG) return [{ skipped: true }];
+  const byDiscipline = loadTemplates();
+  const templates = byDiscipline[task.discipline];
+  if (!templates || !templates.length) return [{ skipped: true }];
   const tid = templateIdFromRef(task.source_ref, task.discipline);
   const match = tid ? templates.find((t) => t.template_id === tid) : null;
   if (match) return [await restockTemplate(task.discipline, match, loadFloors())];
   // ref didn't resolve to a known template — top the whole discipline up (safe).
-  return restockDiscipline(task.discipline);
+  // Hand the map down: restockDiscipline's default param would otherwise re-read
+  // and re-parse the file we are already holding.
+  return restockDiscipline(task.discipline, byDiscipline);
 }
 
 // Seed / backstop: bring every chore THIS INSTANCE offers to floor in one shot.
-// R59 (task 1198): the restocked set is the intersection of the chore disciplines
-// with the modules this instance enables (a vanilla instance with the art pipeline
-// off offers no 'artist' discipline). Returns a FLAT array of per-template results.
+// R59 (task 1198): the restocked set is exactly the crafts this instance enables —
+// a vanilla instance with the art pipeline off offers no 'artist', one with
+// ui-design on offers 'ui'. A craft with no template in templates.json is simply
+// skipped by restockDiscipline. Returns a FLAT array of per-template results.
 async function restockAll() {
   // enabledDisciplines reaches through the published doorway (the one core file a
   // module may require, ADR 0083) — never a direct require of src/modules.js.
-  const { enabledDisciplines } = require('../../src/module-api');
-  const offered = new Set(enabledDisciplines());
+  const offered = validDisciplines();
+  const byDiscipline = loadTemplates(); // one read for the whole sweep, not one per craft
   const out = [];
-  for (const d of VALID_DISCIPLINES) {
-    if (offered.has(d)) {
-      for (const r of await restockDiscipline(d)) out.push(r);
-    }
+  for (const d of templateDisciplines(byDiscipline)) {
+    if (!offered.has(d)) continue;
+    for (const r of await restockDiscipline(d, byDiscipline)) out.push(r);
   }
   return out;
 }
@@ -207,6 +237,7 @@ module.exports = {
   templateIdFromRef,
   buildDescription,
   SOURCE_TAG,
-  VALID_DISCIPLINES,
+  validDisciplines,
+  templateDisciplines,
   HARD_MAX_MINUTES,
 };

package/modules/ui-design/module.json

@@ -5,7 +5,7 @@
   "coreVersion": "^1.19.0",
   "default": true,
   "maintenance": { "status": "core-maintained" },
-  "contributes": { "skills": ["design", "design-sync", "figma-design-sync", "design-taste-frontend", "design-taste-frontend-v1", "high-end-visual-design", "redesign-existing-projects", "impeccable", "style", "minimalist-ui", "industrial-brutalist-ui", "gpt-taste", "stitch-design-taste", "image-to-code", "imagegen-frontend-web", "imagegen-frontend-mobile", "brandkit"] },
+  "contributes": { "skills": ["design", "design-sync", "figma-design-sync", "design-taste-frontend", "design-taste-frontend-v1", "high-end-visual-design", "redesign-existing-projects", "impeccable", "style", "minimalist-ui", "industrial-brutalist-ui", "gpt-taste", "stitch-design-taste", "image-to-code", "imagegen-frontend-web", "imagegen-frontend-mobile", "brandkit"], "disciplines": ["ui"] },
   "provides": [],
   "consumes": []
 }

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.486",
+  "version": "1.19.488",
   "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/newcomer-floor.config.json

@@ -8,6 +8,7 @@
   "disciplines": {
     "engineer": { "floor": 2 },
     "artist": { "floor": 3 },
-    "ideator": { "floor": 2 }
+    "ideator": { "floor": 2 },
+    "ui": { "floor": 2 }
   }
 }

package/scripts/gds/newcomer-floor.js

@@ -58,7 +58,13 @@ const { cliClient, requireSession } = require('./cli-lib');
 const DEFAULT_CONFIG_PATH = path.join(__dirname, 'newcomer-floor.config.json');
 const SOURCE_TAG = 'newcomer-template';
 const HARD_MAX_MINUTES = 60; // newcomer scope ceiling, never exceeded (task 614)
-const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator']);
+// The crafts this seeder will stamp chores for. Deliberately a literal and NOT
+// enabledDisciplines(): this CLI seeds a REMOTE instance, whose enabled modules are
+// not this checkout's, so gating on the local module set would seed the wrong shelf.
+// It is the craft VOCABULARY, which is why 'unclassified' is absent. Keep in step
+// with the keys in newcomer-floor.templates.json ('ui' added by task 1003487); the
+// server-side restock reads the live offered set instead (newcomer-restock.js).
+const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator', 'ui']);
 // Every status a copy's source_ref could occupy — scanned so `seq` is globally
 // monotonic and never recycles a ref already used by a shipped/abandoned copy.
 const ALL_STATUSES = ['backlog', 'ready', 'active', 'completed', 'confirmed', 'shipped', 'blocked', 'abandoned'];

package/scripts/gds/newcomer-floor.templates.json

@@ -1,5 +1,5 @@
 {
-  "_doc": "The evergreen newcomer chores, grouped BY DISCIPLINE. Each discipline maps to a LIST of chore templates (was a single object before task 1488 — a discipline can now offer several first-builder chores so newcomers are not funnelled into one). The deterministic replenisher (scripts/gds/newcomer-floor.js) and the on-claim restock (modules/onboarding/newcomer-restock.js) stamp disposable claimable COPIES from each template; the TEMPLATE is never claimed and never ships. Each copy's source_ref is tmpl:<discipline>:<template_id>:<seq> (monotonic), so identical-title copies never collide with the dedup. Per-template `floor` sets that chore’s standing pool depth; if a template omits it, the discipline default in newcomer-floor.config.json applies. credits_reward, est_minutes and floor all live here (per chore). version_id is per-template so each chore lands on the correct track; it MUST point at an open (non-shipped) version — update it at version close, or the replenisher's open-version guard refuses to stamp and the floor silently stops refilling (task 1002958: the engineer pins still read the long-shipped GDS-V4 and artist+ideator read V2, a version this ladder never had, so NO discipline could restock). touches[] is intentionally empty so multiple same-discipline newcomers can claim copies concurrently; git-merge is the real collision detector. To ADD a chore: append an entry to the discipline's array. To CHANGE one: edit it here — no code change needed. Engineer offers a SAFE coding chore (add a unit test — touches only tests/, which auto-ships) and the docs-hygiene sweep (constrained to non-protected docs so a sub-Metic ship does not stall on the authority core).",
+  "_doc": "The evergreen newcomer chores, grouped BY DISCIPLINE. Each discipline maps to a LIST of chore templates (was a single object before task 1488 — a discipline can now offer several first-builder chores so newcomers are not funnelled into one). The deterministic replenisher (scripts/gds/newcomer-floor.js) and the on-claim restock (modules/onboarding/newcomer-restock.js) stamp disposable claimable COPIES from each template; the TEMPLATE is never claimed and never ships. Each copy's source_ref is tmpl:<discipline>:<template_id>:<seq> (monotonic), so identical-title copies never collide with the dedup. Per-template `floor` sets that chore’s standing pool depth; if a template omits it, the discipline default in newcomer-floor.config.json applies. credits_reward, est_minutes and floor all live here (per chore). version_id is per-template so each chore lands on the correct track; it MUST point at an open (non-shipped) version — update it at version close, or the replenisher's open-version guard refuses to stamp and the floor silently stops refilling (task 1002958: the engineer pins still read the long-shipped GDS-V4 and artist+ideator read V2, a version this ladder never had, so NO discipline could restock). touches[] is intentionally empty so multiple same-discipline newcomers can claim copies concurrently; git-merge is the real collision detector. To ADD a chore: append an entry to the discipline's array. To CHANGE one: edit it here — no code change needed. UI offers two browser-free chores (a token-drift fix measured by validate-design.js, and an accessible-name fix) so a newcomer whose only craft is ui is never starved for work on a machine with no Chrome/Edge for the kit — task 1003487. Engineer offers a SAFE coding chore (add a unit test — touches only tests/, which auto-ships) and the docs-hygiene sweep (constrained to non-protected docs so a sub-Metic ship does not stall on the authority core).",
   "engineer": [
     {
       "template_id": "unit-test-pass",
@@ -82,5 +82,47 @@
       "touches": [],
       "floor": 2
     }
+  ],
+  "ui": [
+    {
+      "template_id": "ui-token-drift-pass",
+      "version_id": "BONGOS-V1",
+      "discipline": "ui",
+      "kind": "cleanup",
+      "est_minutes": 40,
+      "credits_reward": 15,
+      "floor": 2,
+      "title": "Token-drift pass: replace one hardcoded colour in a platform stylesheet with the branding token it should have used",
+      "description": "## What you're doing\n\nEvery colour on a platform surface must come from the instance's branding pack — **the Fifteen Rule**: thirteen colours plus two font stacks in `theme.ui`, reached as a `var()` or a `color-mix()` of them. The only legal literal is pure black or white with alpha, used as a scrim, mask or halo. Drift happens anyway: someone types `#3b82f6` in a hurry and the surface stops following the instance's world. Your first ship as a UI builder: find **one** real hardcoded colour in **one** stylesheet and replace it with the right token.\n\nIt is identical for every newcomer and **always valuable** — the sheets are large, drift is continuous, and every literal you convert is one more thing that follows the pack when an instance changes its look. It is also **safe**: you change one declaration in one CSS file, which is not a protected surface.\n\n## Learn the fifteen first (five minutes, and the whole job depends on it)\n\n1. Open `config/branding.json` (falling back to `config/branding.neutral.json`) and read `theme.ui` — those thirteen colours and two font stacks are your entire palette.\n2. Open the root `DESIGN.md` — it names the derived tiers and which token means what (surface, ink, accent, hairline, danger…). If it names a rule, it wins.\n3. Skim `docs/recipes/ui-look-before-you-ship.md` for how the floors are measured.\n\n## Find a real target\n\nGrep a platform stylesheet for a raw colour and pick ONE that is genuinely wrong:\n\n```\ngrep -rnE '#[0-9a-fA-F]{3,8}\\b|rgba?\\(' modules/hall-ui/public/ modules/status-ui/public/ --include=*.css\n```\n\nGood targets: a hex or `rgb()` that duplicates a token's value, or one that is close to a token but slightly off (the worst kind — it looks fine until the pack changes).\n\n**Not a target, leave these alone:** `#000` / `#fff` / `rgba(0,0,0,…)` / `rgba(255,255,255,…)` used as a scrim, shadow, mask or halo — those are explicitly legal. A colour inside a vendored or generated file. Anything under `config/` (changing the pack itself is the owner's decision and an ADR, never a first ship).\n\n## Make the change\n\nReplace the literal with the token that carries the same MEANING, not merely the nearest number — `var(--ui-accent)` because the thing is an accent, not because the hex was blue-ish. If no token means what the literal meant, you have found a design question rather than drift: pick a different target and, if you like, file the question with `node scripts/gds/capture.js`.\n\n**Both modes.** If the rule you touch has a dark twin, the twin changes too and stays byte-identical — `:root[data-mode=\"dark\"]` and `@media (prefers-color-scheme: dark) { :root:not([data-mode=\"light\"]) }`. Never fix one and leave the other.\n\n## Verify + ship\n\n- `node scripts/gds/validate-design.js --strict` — exits 0.\n- `node scripts/gds/run-unit-tests.js` — still green.\n- Say in the ship notes which literal you replaced, with which token, and why that token is the right MEANING.\n\nHave a browser (Edge or Chrome) on the machine? Then also run `node modules/ui-design/kit/render.js --page <the page>` and look at the before/after — the work is judged by looking at it. Not required for this chore.\n\n## Stay clear of\n\nDo not edit `config/branding.json`, `config/branding.neutral.json`, `config/design-tokens*.json`, or the root `DESIGN.md` — the world is the owner's, and changing it needs an ADR. Do not add a sixteenth token. Do not restyle the component while you are in there: one literal, one meaning, one commit. Touch no permission, pipeline, migration or infra file.",
+      "done_when": [
+        "Exactly one hardcoded colour literal in ONE non-protected stylesheet was replaced with a branding token (a var() or a color-mix() of theme.ui) — a real literal, not a legal black/white scrim, shadow, mask or halo, and not a cosmetic no-op.",
+        "The token chosen matches the MEANING of what was styled (the ship notes say which token and why), and no sixteenth token was invented.",
+        "If the rule had a dark twin, the twin was changed too and the two remain byte-identical.",
+        "`node scripts/gds/validate-design.js --strict` exits 0 and `node scripts/gds/run-unit-tests.js` is green.",
+        "config/branding*.json, config/design-tokens*.json and the root DESIGN.md were NOT modified, and no permission, pipeline, migration or infra path was touched.",
+        "The ship notes name the file, the literal removed and the token that replaced it."
+      ],
+      "touches": []
+    },
+    {
+      "template_id": "ui-alt-text-pass",
+      "version_id": "BONGOS-V1",
+      "discipline": "ui",
+      "kind": "cleanup",
+      "est_minutes": 35,
+      "credits_reward": 15,
+      "floor": 1,
+      "title": "Accessibility pass: give one unlabelled control or image on a platform page a real accessible name",
+      "description": "## What you're doing\n\nA control a screen reader cannot name is a control some people cannot use. Icon-only buttons are the usual offenders — a `<button>` whose entire content is an `<i class=\"ti ti-x\">` announces as \"button\" and nothing else. Your first ship as a UI builder: find **one** genuinely unlabelled control or image on a platform page and give it a real accessible name.\n\nIt is identical for every newcomer and **always valuable** — the hall and status surfaces carry many icon buttons, new ones arrive constantly, and each label you add is permanent.\n\n## Find a real target\n\nLook in `modules/hall-ui/public/*.html` and `*.js`, and `modules/status-ui/public/`:\n\n```\ngrep -rnE '<button[^>]*>\\s*<i class=\"ti' modules/hall-ui/public/ modules/status-ui/public/\ngrep -rn '<img' modules/hall-ui/public/ modules/status-ui/public/ | grep -v 'alt='\n```\n\nA target is genuine when it has **no** `aria-label`, **no** `title`, **no** visible text inside it, and **no** `aria-labelledby`. Check before you \"fix\" it — many already have one.\n\n## Make the change\n\n- Icon-only button → add `aria-label=\"<what it does>\"`. Name the ACTION, not the icon: `aria-label=\"Close the dialog\"`, never `aria-label=\"x icon\"`.\n- Decorative icon sitting beside text that already says it → the right fix is `aria-hidden=\"true\"`, so it is not announced twice.\n- `<img>` → a real `alt` describing what it conveys; `alt=\"\"` only when it is purely decorative.\n- Text built by JavaScript goes through the same `escapeHtml` the surrounding code uses — match the file's existing idiom.\n\nOne control. Do not restyle it, do not rename its class, do not refactor the component.\n\n## Verify + ship\n\n- `node scripts/gds/run-unit-tests.js` — green.\n- Read the label back to yourself with the screen off: does it say what pressing this does? If not, rewrite it.\n- The ship notes name the file, the control, and the label you gave it.\n\n## Stay clear of\n\nDo not \"fix\" a control that already has an accessible name — that is a no-op ship. Do not touch the branding pack, `DESIGN.md`, or any permission, pipeline, migration or infra file.",
+      "done_when": [
+        "Exactly one control or image that genuinely had NO accessible name (no aria-label, no title, no visible text, no aria-labelledby, no alt) was given one, in one non-protected file.",
+        "The name describes the ACTION or the MEANING, not the icon ('Close the dialog', not 'x icon'); a purely decorative icon beside existing text was marked aria-hidden=\"true\" instead.",
+        "Nothing else about the control changed — no restyle, no class rename, no component refactor — and any generated text uses the file's existing escaping idiom.",
+        "`node scripts/gds/run-unit-tests.js` is green.",
+        "The branding pack, DESIGN.md, and every permission/pipeline/migration/infra path were untouched.",
+        "The ship notes name the file, the control and the accessible name added."
+      ],
+      "touches": []
+    }
   ]
 }

package/scripts/gds/ship-grade-steps.js

@@ -94,10 +94,31 @@ async function logGraderPanelCost(taskId, gradeResult) {
 //   audit    — the compact regrade block recorded into the new grade's signals
 //              so grade_attempts rounds read as remediation history (the
 //              task-1002661 reader consumes this).
+// The prior round's findings, from EITHER grade shape (task 1003488).
+//
+// A grade exists in two shapes and this function is handed both. The in-memory
+// result `validateAndScore`/`serverSideGuards` return carries `issues` at the top
+// level; a grade READ BACK from the API does not, because `task_grades` has no
+// `issues` column and `db-grade.js` deliberately writes them into the signals
+// jsonb instead. `--regrade` passes the DB row (`ship-flow.js`: `tRes.data.grade`),
+// so reading only the top-level key silently yielded [] on every re-grade — the
+// panel was told it was on round N while being handed nothing about round N-1,
+// and the "answered findings can only re-veto with NEW evidence" protection
+// (task 1002662) cannot hold when the answered findings are invisible.
+//
+// Top level wins when present so an in-memory result keeps its exact behaviour;
+// `signals.issues` is the stored fallback. Mirrors how the caller already reaches
+// for `signals.graded_head_sha` three lines from where it passes this row in.
+function priorFindings(storedGrade) {
+  if (Array.isArray(storedGrade.issues)) return storedGrade.issues;
+  const fromSignals = storedGrade.signals && storedGrade.signals.issues;
+  return Array.isArray(fromSignals) ? fromSignals : [];
+}
+
 const PRIOR_ROUND_TEXT_CAP = 4000;
 function buildPriorRoundContext({ storedGrade, responseText = '', interimCommits = '', interimDiffStat = '' }) {
   if (!storedGrade || typeof storedGrade !== 'object') return null;
-  const issues = Array.isArray(storedGrade.issues) ? storedGrade.issues : [];
+  const issues = priorFindings(storedGrade);
   const notes = typeof storedGrade.notes_md === 'string' ? storedGrade.notes_md.trim() : '';
   if (issues.length === 0 && !notes) return null;
   const verdictLine = `Prior verdict: ${storedGrade.passed ? 'PASS' : 'FAIL'} · score ${storedGrade.score ?? '?'}/10 · ${issues.length} finding(s)`;
@@ -436,6 +457,7 @@ function printCreditsAndAchievements({ postGradeStatus, credits, creditsRaw, cre
 module.exports = {
   buildGradePayload,
   buildPriorRoundContext,
+  priorFindings,
   computeGradeResult,
   formatGradeOutcome,
   gradeAndRecord,

package/scripts/gds/ship.js

@@ -145,6 +145,7 @@ const {
   buildGradePayload,
   buildPriorRoundContext,
   computeGradeResult,
+  priorFindings,
   formatGradeOutcome,
   gradeAndRecord,
 } = require('./ship-grade-steps.js');
@@ -195,6 +196,9 @@ module.exports = {
   // task 1002662: delta-aware re-grade — the prior-round payload builder,
   // exported pure so the panel/audit shapes are pinned without git/network.
   buildPriorRoundContext,
+  // task 1003488: the two-shape finding reader behind it (a stored grade keeps
+  // its findings in signals.issues; an in-memory one at the top level).
+  priorFindings,
   // #943: pure grade-outcome formatter — exported so the grader-unavailable vs
   // FAIL display branch is unit-tested without capturing stdout.
   formatGradeOutcome,

package/src/bongos/db.js

@@ -144,9 +144,9 @@ async function linkAnthropicAccount(builderId, { email, userId }) {
 // Replace a builder's preferred_disciplines (migrations 027 + 086). Input is
 // deduped, order-normalized, and validated against the disciplines THIS INSTANCE
 // offers — core (engineer, ideator) plus any enabled feature module's disciplines
-// (the art-pipeline module adds 'artist'), resolved via src/modules.js (R59 /
-// task 1198). The DB CHECK still enforces the full known enum
-// (engineer|artist|ideator) as a backstop; this is the instance-aware
+// (art-pipeline adds 'artist', ui-design adds 'ui'), resolved via src/modules.js
+// (R59 / task 1198; task 1003487). The DB CHECK still enforces the full known enum
+// (engineer|artist|ideator|ui, migration 176) as a backstop; this is the instance-aware
 // friendly-error layer, so a vanilla instance with the art pipeline off rejects
 // 'artist' instead of silently storing an unofferable discipline. Returns the
 // updated builder row, or throws { code: 'invalid_discipline', bad } if any

package/src/bongos/routes/me.js

@@ -373,7 +373,8 @@ module.exports = function buildMeRouter() {
 
   // Self-service edit of the authenticated builder's preferred disciplines
   // (migrations 027 + 086 / V3.R80). Body: { preferred_disciplines: ["artist", ...] }.
-  // Valid elements are engineer|artist|ideator; [] clears the preference (a
+  // Valid elements are whatever enabledDisciplines() offers — engineer|ideator core
+  // plus any enabled module's (artist, ui); [] clears the preference (a
   // multi-element set just means several lanes). No rank gate — a builder owns their own
   // profile. 422 invalid_discipline if any element is out of range.
   // rank: any-builder — self-service profile edit; documented "no rank gate" in the

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // 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.486'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.488'; // 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/grader_regrade_delta.mjs

@@ -184,5 +184,62 @@ test('buildPriorRoundContext caps oversized notes/response/interim text', () =>
   assert.ok(ctx.forPanel.interim_md.length < 5000, 'interim capped');
 });
 
+// ---- task 1003488: the prior round is read from a STORED grade, not just an
+// ---- in-memory one. A grade exists in two shapes and this function is handed
+// ---- both; reading only the top-level key made every --regrade run blind.
+
+test('prior round: a STORED grade carries its findings under signals.issues and they still reach the panel', () => {
+  // exactly what ship-flow.js passes on --regrade: tRes.data.grade, a DB row.
+  // task_grades has no issues column, so db-grade.js writes them into signals.
+  const dbRow = {
+    passed: false, score: 5, notes_md: '',
+    signals: {
+      issue_count: 2,
+      issues: [
+        { severity: 'major', worker: 'efficiency', file: 'a.js', summary: 'redundant sync reads' },
+        { severity: 'nit', worker: 'quality', file: 'b.js', summary: 'label drift' },
+      ],
+    },
+  };
+  const ctx = ship.buildPriorRoundContext({ storedGrade: dbRow });
+  assert.ok(ctx, 'a stored grade with findings is delta-aware context, not null');
+  assert.equal(ctx.audit.prior_findings_count, 2, 'the count is the stored findings, not 0');
+  assert.match(ctx.forPanel.findings_md, /2 finding\(s\)/);
+  assert.match(ctx.forPanel.findings_md, /redundant sync reads/, 'the finding text rides to the panel');
+  assert.match(ctx.forPanel.findings_md, /\[major\] efficiency · a\.js/, 'severity, worker and file survive');
+  assert.ok(!/no per-finding rows/.test(ctx.forPanel.findings_md),
+    'it must not fall through to the "no rows" placeholder');
+});
+
+test('prior round: an IN-MEMORY grade keeps its exact top-level behaviour', () => {
+  const inMemory = {
+    passed: false, score: 5, notes_md: '',
+    issues: [{ severity: 'major', worker: 'quality', file: 'c.js', summary: 'top level wins' }],
+    signals: { issues: [{ severity: 'nit', worker: 'x', file: 'd.js', summary: 'must not be preferred' }] },
+  };
+  const ctx = ship.buildPriorRoundContext({ storedGrade: inMemory });
+  assert.equal(ctx.audit.prior_findings_count, 1);
+  assert.match(ctx.forPanel.findings_md, /top level wins/);
+  assert.ok(!/must not be preferred/.test(ctx.forPanel.findings_md),
+    'top-level issues take precedence over signals.issues');
+});
+
+test('priorFindings: reads either shape, and never throws on a malformed one', () => {
+  const f = ship.priorFindings;
+  assert.deepEqual(f({ issues: [{ severity: 'nit' }] }).length, 1, 'top level');
+  assert.deepEqual(f({ signals: { issues: [{ severity: 'nit' }, { severity: 'major' }] } }).length, 2, 'stored');
+  for (const bad of [{}, { issues: null }, { signals: null }, { signals: {} },
+                     { signals: { issues: 'nope' } }, { issues: 'nope', signals: { issues: [{ severity: 'nit' }] } }]) {
+    const out = f(bad);
+    assert.ok(Array.isArray(out), `array for ${JSON.stringify(bad)}`);
+  }
+  // a non-array top level must fall through to the stored shape, not swallow it
+  assert.equal(f({ issues: 'nope', signals: { issues: [{ severity: 'nit' }] } }).length, 1);
+});
+
+test('prior round: a stored grade with NO findings anywhere is still null (unchanged)', () => {
+  assert.equal(ship.buildPriorRoundContext({ storedGrade: { passed: true, notes_md: '', signals: {} } }), null);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/help_requests.mjs

@@ -42,8 +42,27 @@ test('an unknown craft is refused', () => {
   assert.ok(reasons({ needs_craft: 'wizard', what_is_stuck: 'help' }).includes('unknown_craft'));
 });
 
-test('the crafts are ADR 0174\'s three', () => {
-  assert.deepEqual(help.helpCrafts().sort(), ['artist', 'builder', 'ideator']);
+test('the crafts are ADR 0174\'s three, plus the ui craft the ui-design module contributes', () => {
+  // 'ui' joined the vocabulary with task 1003487, which made the discipline
+  // selectable everywhere a builder chooses work. The DB CHECK is widened in
+  // lockstep by modules/lifecycle/migrations/lifecycle_006_help_requests_ui_craft.sql.
+  assert.deepEqual(help.helpCrafts().sort(), ['artist', 'builder', 'ideator', 'ui']);
+  assert.equal(help.disciplineForCraft('ui'), 'ui', 'ui is spelled the same on both sides of the seam');
+  assert.equal(help.craftForDiscipline('ui'), 'ui');
+});
+
+test('every craft the app offers is permitted by the help_requests CHECK', () => {
+  // The regression this pins: the vocabulary lives BOTH in JS (HELP_CRAFTS) and in
+  // a compiled-in CHECK, and widening one without the other is invisible until an
+  // INSERT fails in production as a 500 on a feature that reads as supported.
+  const sql = fs.readFileSync(
+    path.join(ROOT, 'modules', 'lifecycle', 'migrations', 'lifecycle_006_help_requests_ui_craft.sql'), 'utf8');
+  const m = sql.match(/needs_craft IN \(([^)]*)\)/);
+  assert.ok(m, 'the migration states the permitted craft list');
+  const allowed = m[1].split(',').map((x) => x.trim().replace(/^'|'$/g, ''));
+  for (const c of help.helpCrafts()) {
+    assert.ok(allowed.includes(c), `craft '${c}' is offered by helpCrafts() but the CHECK forbids it`);
+  }
 });
 
 test('THE VOCABULARY SEAM: builder maps to the discipline spelled engineer', () => {

package/tests/module_contributions.mjs

@@ -9,6 +9,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -153,6 +154,72 @@ test('settings-panel seam: ABSENT → empty; REGISTERED → present, sorted by o
 // third-party widget can't blank the hall — so these assert the RETURN VALUE and
 // that the widget never reached the registry.
 
+// ---- browser twin: the craft picker's options (task 1003487) ----------------
+// Both hall pickers (the onboarding pick_disciplines step and the Settings craft
+// chips) build their options from OTB.disciplines(), so this IS the rendered
+// option list. It used to be a hardcoded triple in each file, which is how a
+// module-contributed craft could be offered by the server and appear in neither.
+
+test('craft picker options: OTB.disciplines() mirrors the server list, and falls back to the core two', () => {
+  global.window = {};
+  // the IIFE assigns window.OTB once at load — evict it for a fresh binding
+  const domUtils = path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js');
+  delete require.cache[require.resolve(domUtils)];
+  require(domUtils);
+  const OTB = global.window.OTB;
+
+  // the server's list wins, in the server's order
+  global.window.__MODULES__ = { enabled: {}, disciplines: ['engineer', 'ideator', 'ui'] };
+  assert.deepEqual(OTB.disciplines(), ['engineer', 'ideator', 'ui']);
+  // a module-contributed craft is offered without any per-craft moduleOn() branch
+  global.window.__MODULES__ = { enabled: { 'art-pipeline': true }, disciplines: ['engineer', 'ideator', 'artist', 'ui'] };
+  assert.ok(OTB.disciplines().includes('ui') && OTB.disciplines().includes('artist'));
+  // withdrawn with its module
+  global.window.__MODULES__ = { enabled: {}, disciplines: ['engineer', 'ideator'] };
+  assert.deepEqual(OTB.disciplines(), ['engineer', 'ideator']);
+
+  // an older server that sends no list degrades to the core two, never to an
+  // empty picker (which would strand a builder with no way to pick a craft)
+  for (const m of [undefined, {}, { enabled: {} }, { disciplines: [] }, { disciplines: 'nope' }]) {
+    global.window.__MODULES__ = m;
+    assert.deepEqual(OTB.disciplines(), ['engineer', 'ideator'], `fallback for ${JSON.stringify(m)}`);
+  }
+
+  // returns a COPY — a picker mutating its options cannot corrupt the global
+  global.window.__MODULES__ = { disciplines: ['engineer', 'ideator', 'ui'] };
+  OTB.disciplines().push('bogus');
+  assert.deepEqual(OTB.disciplines(), ['engineer', 'ideator', 'ui']);
+});
+
+test('craft picker options: disciplineLabel names an acronym correctly', () => {
+  global.window = {};
+  // the IIFE assigns window.OTB once at load — evict it for a fresh binding
+  const domUtils = path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js');
+  delete require.cache[require.resolve(domUtils)];
+  require(domUtils);
+  const OTB = global.window.OTB;
+  assert.equal(OTB.disciplineLabel('ui'), 'UI', 'not "Ui"');
+  assert.equal(OTB.disciplineLabel('engineer'), 'Engineer');
+  assert.equal(OTB.disciplineLabel('artist'), 'Artist');
+  assert.equal(OTB.disciplineLabel('ideator'), 'Ideator');
+  // a craft a module adds later needs no new entry here
+  assert.equal(OTB.disciplineLabel('archivist'), 'Archivist');
+  for (const bad of ['', null, undefined]) assert.equal(OTB.disciplineLabel(bad), '');
+});
+
+test('craft picker options: neither picker hardcodes the craft list any more', () => {
+  // A regression pin with teeth: the bug was two independent literal triples that
+  // silently dropped a module-contributed craft. Whichever picker is edited next
+  // must keep reading the server list.
+  const read = (p) => readFileSync(path.join(ROOT, p), 'utf8');
+  for (const p of ['modules/hall-ui/public/settings.js', 'modules/hall-ui/public/hall-render.js']) {
+    const src = read(p);
+    assert.ok(/OTB\.disciplines\(\)/.test(src), `${p} builds its options from OTB.disciplines()`);
+    assert.ok(!/\['engineer',\s*'artist',\s*'ideator'\]/.test(src), `${p} no longer hardcodes the craft triple`);
+    assert.ok(!/discBtn\('engineer'/.test(src), `${p} no longer names a craft literally`);
+  }
+});
+
 test('hall-widget registry: placement rules reject bad registrations, accept good ones', () => {
   global.window = {};
   // The settings-panel test above already required dom-utils.js, and the IIFE