@bongos/core 1.19.485 → 1.19.487

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/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/project-settings.js

@@ -0,0 +1,193 @@
+'use strict';
+
+// src/bongos/project-settings.js — the instance's live, DB-backed knobs, and the
+// typed accessor every reader goes through (task 1003279, goal 1000072).
+//
+// WHY THIS FILE EXISTS. Goal 1000072's rotting half needs a number — "untouched
+// for how long?" — and task 1003280 states where it must live: "STALE TIMER —
+// live, DB-backed", followed by "do not fork a second store". A knob an owner can
+// change from a page cannot be an env var that needs a redeploy, and it must not
+// become a THIRD place staleness is configured. So there is one table
+// (project_settings, migration core_231) and one accessor, here.
+//
+// HOW THIS RELATES TO src/stale-timer.js — READ THIS BEFORE ADDING A THIRD TIMER.
+// ADR 0226 collapsed four disagreeing answers to "how long may a CLAIM go silent"
+// into one resolver. This file does not reopen that. The two timers measure
+// different things, are owned by different surfaces, and have different
+// consequences:
+//
+//   src/stale-timer.js   a CLAIM goes silent      hours   env    the sweep RELEASES it
+//   this file            work goes UNTOUCHED      days    DB     a human is ASKED
+//
+// The distinction that keeps them from collapsing into each other: the claim timer
+// is about a builder who stopped responding, and the machine acts alone. The rot
+// timer is about work nobody picked up, and the machine only ever raises a
+// question. One enforces, one reports — which is exactly the asymmetry ADR 0226's
+// header names, applied one level up.
+//
+// This is why the rot read deliberately EXCLUDES tasks at 'active': a claimed task
+// that has gone quiet is the claim timer's question, and reporting it here too
+// would put the same rot in two inboxes with two different numbers — the precise
+// failure ADR 0226 exists to prevent.
+//
+// FAIL POSTURE: REPORTING, SO IT DEGRADES. Every caller of this file is a read
+// surface (the needs-attention inbox, the settings page). A knob typed wrong shows
+// up ON the screen of the person who can fix it, labelled, instead of 500-ing the
+// inbox they were using to find the problem. Nothing here throws on a bad value;
+// it reports one. (An enforcing caller would have to refuse instead — see the
+// stale-timer header. There is no enforcing caller of the rot timer, by design.)
+
+const { pool } = require('./pool');
+// The structured logger rather than console.* — both are kernel files (this one is on
+// fitness.js's KERNEL_FILES roster), a structured line is attributable and rides
+// ADR 0022's redaction, and the quality ratchet counts bare console calls.
+const { logger } = require('./logger');
+
+// The knob names. Namespaced by the surface that owns them so a settings page can
+// group rows without a second column, and so a future knob from another surface
+// cannot collide with this one.
+const SETTING_KEYS = {
+  ROT_DAYS: 'attention.rot_days',
+};
+
+// The last-resort rot timer, in days. 30 because that is the shortest window in
+// which "nobody has touched this" is evidence of rot rather than evidence of a
+// normal week — a fortnight would fire on every ordinary holiday, and a quarter is
+// long enough that the backlog has already stopped being read.
+const DEFAULT_ROT_DAYS = 30;
+
+// The accepted range, in days. 1 because "yesterday" is the shortest question worth
+// asking. 365 because past a year the timer is an off switch, and an off switch
+// should be asked for out loud rather than typed as a big number — the same
+// reasoning, and the same sentence, as the 720h bound in src/stale-timer.js.
+const MIN_ROT_DAYS = 1;
+const MAX_ROT_DAYS = 365;
+
+// Parse one candidate into whole days, or say why it is unusable. Pure, never
+// throws: both the DB tier and the override tier want to decide for themselves what
+// an unusable value means. Mirrors parseHours in src/stale-timer.js deliberately —
+// two timers with two different range checks would drift into two different ideas
+// of what "valid" means.
+function parseDays(raw) {
+  if (raw == null || raw === '') return { reason: 'empty' };
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { reason: 'not a number' };
+  if (!Number.isInteger(n)) return { reason: 'must be a whole number of days' };
+  if (n <= 0) return { reason: 'must be positive' };
+  if (n < MIN_ROT_DAYS || n > MAX_ROT_DAYS) {
+    return { reason: `out of range (${MIN_ROT_DAYS}..${MAX_ROT_DAYS})` };
+  }
+  return { days: n };
+}
+
+// getSetting(key) — the raw row, or null when the key has never been set.
+// NULL IS MEANINGFUL: absence means "never configured, use the code default", which
+// is what lets a fresh instance boot with an empty table and what lets the settings
+// page tell "never touched" apart from "deliberately set to the default value".
+// Never seed a default row to avoid the null.
+async function getSetting(key) {
+  const { rows } = await pool.query(
+    'SELECT key, value, updated_at, updated_by FROM project_settings WHERE key = $1',
+    [key]
+  );
+  return rows[0] || null;
+}
+
+// setSetting(key, value, builderId) — upsert one knob, returning the stored row.
+// The value is stored verbatim as text and validated by the typed resolver at READ
+// time, not here, so a value that was valid when written and later fell outside a
+// tightened range degrades on the screen rather than becoming unreadable.
+// builderId may be null for a system path with no builder in the request.
+async function setSetting(key, value, builderId = null) {
+  const { rows } = await pool.query(
+    `INSERT INTO project_settings (key, value, updated_by, updated_at)
+          VALUES ($1, $2, $3, now())
+     ON CONFLICT (key) DO UPDATE
+            SET value = EXCLUDED.value,
+                updated_by = EXCLUDED.updated_by,
+                updated_at = now()
+      RETURNING key, value, updated_at, updated_by`,
+    [key, String(value), builderId]
+  );
+  return rows[0];
+}
+
+// resolveRotDays({ override }) — the project's rot timer and where the number came
+// from, for any surface that reports staleness.
+//
+// Precedence, widest-scope last (the same shape as resolveStaleClaimHours):
+//   1. override — a per-request lens (?rot_days=). Someone asking "what would 7
+//                 days show me?" is not reconfiguring the project, so this never
+//                 becomes the project's answer and is never written back.
+//   2. the DB   — project_settings['attention.rot_days']. THIS is the project's
+//                 configured timer, the row task 1003280's page writes.
+//   3. default  — DEFAULT_ROT_DAYS.
+//
+// Returns { days, source, invalid }:
+//   days    — always a usable positive integer, whatever went wrong
+//   source  — 'override' | 'project_settings' | 'default'
+//   invalid — null, or { where, raw, reason }: something was SET and unusable.
+//             `days` has already fallen through to the next tier; a reporting
+//             caller should say so on screen.
+//
+// A DB that is unreachable is NOT an invalid value — it is a failure to read, and
+// this returns the default with source 'default' rather than taking the inbox down.
+// The inbox is how someone would notice the database is unhappy.
+async function resolveRotDays({ override } = {}) {
+  if (override != null && override !== '') {
+    const got = parseDays(override);
+    if (got.days != null) return { days: got.days, source: 'override', invalid: null };
+    return {
+      days: DEFAULT_ROT_DAYS,
+      source: 'default',
+      invalid: { where: 'override', raw: String(override), reason: got.reason },
+    };
+  }
+
+  let row = null;
+  try {
+    row = await getSetting(SETTING_KEYS.ROT_DAYS);
+  } catch (err) {
+    logger.error(`project_settings read failed; falling back to the default rot timer: ${err && err.message}`);
+    return { days: DEFAULT_ROT_DAYS, source: 'default', invalid: null };
+  }
+
+  if (row && row.value != null && row.value !== '') {
+    const got = parseDays(row.value);
+    if (got.days != null) return { days: got.days, source: 'project_settings', invalid: null };
+    return {
+      days: DEFAULT_ROT_DAYS,
+      source: 'default',
+      invalid: { where: `project_settings['${SETTING_KEYS.ROT_DAYS}']`, raw: String(row.value), reason: got.reason },
+    };
+  }
+
+  return { days: DEFAULT_ROT_DAYS, source: 'default', invalid: null };
+}
+
+// describeRotTimer(resolved) — one sentence naming the timer and its provenance, for
+// an API receipt or a settings row. A number with no provenance is what let a 6h and
+// a 24h coexist unnoticed for months (ADR 0226); every surface that prints the rot
+// timer prints this instead of printing the bare number.
+function describeRotTimer(resolved) {
+  const r = resolved || {};
+  const base = `${r.days}d (${r.source})`;
+  if (!r.invalid) return base;
+  return `${base} — ignoring ${r.invalid.where}="${r.invalid.raw}" (${r.invalid.reason})`;
+}
+
+// parseDays is exported for the tests only — the range check and the default are
+// asserted against the SAME constants the resolver reads, because a test that
+// re-typed 30 or 365 would be the second copy of the number this file exists to
+// keep singular.
+module.exports = {
+  SETTING_KEYS,
+  DEFAULT_ROT_DAYS,
+  MIN_ROT_DAYS,
+  MAX_ROT_DAYS,
+  parseDays,
+  getSetting,
+  setSetting,
+  resolveRotDays,
+  describeRotTimer,
+};

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

@@ -17,6 +17,17 @@ const { pool, instanceDbName } = require('./bongos/pool');
 const branding = require('./branding');
 const instanceConfig = require('./instance-config');
 const staleTimer = require('./stale-timer');
+// Destructured, not namespaced, deliberately — the same form src/bongos/routes/
+// builders.js uses for stale-timer.js. knip attributes a named export to a
+// destructured binding but not to a property read off a required namespace, so the
+// namespace form reports every export here as dead and regresses the ratchet.
+const {
+  resolveRotDays,
+  SETTING_KEYS: PROJECT_SETTING_KEYS,
+  getSetting: getProjectSetting,
+  setSetting: setProjectSetting,
+  describeRotTimer,
+} = require('./bongos/project-settings');
 const seams = require('./module-seams');
 const { buildInfo } = require('./build-info');
 const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePagination, pageMeta, PAGINATION } = require('./bongos/routes/_helpers');
@@ -34,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.485'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.487'; // 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');
@@ -250,6 +261,23 @@ module.exports = {
   //     a direct require in scripts/ rather than joining the published surface.
   resolveStaleClaimHours: staleTimer.resolveStaleClaimHours,
   staleClaimMinutes: staleTimer.staleClaimMinutes,
+  // --- the project's ROT TIMER + the knob store behind it (task 1003279, goal
+  //     1000072) — how long a GOAL or TASK may go untouched before the hall's
+  //     needs-attention inbox raises a line about it. A DIFFERENT question from the
+  //     stale-claim timer directly above, and the two must not be confused: that one
+  //     counts hours, is read from the env, is about a builder who went quiet, and
+  //     the sweeper ACTS on it alone. This one counts days, is read from the DB
+  //     (task 1003280 puts it on a settings page, and "do not fork a second store"),
+  //     is about work nobody picked up, and it only ever ASKS a human. The rot read
+  //     deliberately skips tasks at 'active' so the two never report the same rot
+  //     with two different numbers. See src/bongos/project-settings.js.
+  resolveRotDays,
+  projectSettings: {
+    KEYS: PROJECT_SETTING_KEYS,
+    get: getProjectSetting,
+    set: setProjectSetting,
+    describeRotTimer,
+  },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,
   configPath: instanceConfig.configPath,

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_api.mjs

@@ -34,6 +34,7 @@ const PUBLISHED_SURFACE = [
   'llmPricing', // BV1.R77: shared token→USD pricing (1.7.0; tracked domain leak — economy carve)
   'branding', 'clientBranding', 'userAgent', 'resolveEnv', 'readConfigFileSync', 'configHome', 'configPath', // userAgent added 1.12.0 (BV1.R86; github-push UA)
   'resolveStaleClaimHours', 'staleClaimMinutes', // added by task 1003476 (ADR 0226; goal 1000072): the PROJECT's stale-claim timer — the sweep that releases a silent claim and the Archon roster that reports one read the same number through here, after eighteen hours of disagreeing (6 vs 24)
+  'resolveRotDays', 'projectSettings', // added by task 1003279 (ADR 0232; goal 1000072): the ROT timer + the live knob store behind it. A DIFFERENT question from the stale-claim timer above — days not hours, DB not env, work nobody picked up rather than a builder who went quiet, and it only ever ASKS a human where that one ACTS. Both ride the doorway so no module hardcodes either.
   'joinabilityMode', // added by task 1003044 (ADR 0194; the carrier after 1.19.374): the project's membership door, one reader for the sign-in gate AND the onboarding module's public POST
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',

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

package/tests/modules.mjs

@@ -140,6 +140,21 @@ test('disciplines: vanilla offers engineer + ideator (core); art-pipeline adds a
   assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator', 'artist']);
 });
 
+test('disciplines: ui-design contributes `ui` — the manifest key IS the unlock (task 1003487)', () => {
+  // enabledDisciplines() already merged contributes.disciplines; ui-design simply
+  // never declared any, so the craft existed in the DB CHECK, in discipline-modes
+  // and on tasks while staying unreachable from every surface a builder chooses with.
+  if (!EFFECTIVE['ui-design']) return; // only meaningful where the module is installed
+  assert.deepEqual(EFFECTIVE['ui-design'].contributes.disciplines, ['ui'],
+    'the module declares the craft it owns');
+  const on = resolveModules({ instance: { modules: { 'ui-design': true } }, registry: EFFECTIVE });
+  assert.ok(enabledDisciplines(on).includes('ui'),
+    'a builder can save it, because updateBuilderDisciplines validates against this very list');
+  // and it withdraws with the module, exactly as artist does with art-pipeline
+  const off = resolveModules({ instance: { modules: { 'ui-design': false } }, registry: EFFECTIVE });
+  assert.ok(!enabledDisciplines(off).includes('ui'), 'module off => craft withdrawn');
+});
+
 test('clientModules is a safe boolean projection covering every known module + disciplines', () => {
   const c = clientModules(resolveModules({ instance: OTB, registry: SAMPLE_REG }));
   for (const k of KNOWN_MODULES) assert.equal(typeof c.enabled[k], 'boolean');
@@ -180,5 +195,8 @@ test('a branded sibling (GDS_BRANDING_FILE set, no GDS_MODULES_FILE) defaults to
   // A non-default brand must fall through to the neutral (all-off) module set.
   const m = loadModules({ env: { GDS_BRANDING_FILE: 'config/branding.cloudbongos.json' } });
   for (const k of KNOWN_MODULES) assert.equal(m[k], false, `${k} must be off for a branded sibling`);
-  assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator']);
+  // The two core crafts, plus 'ui' from ui-design — which is default-on for EVERY
+  // instance ("every instance has a face") and is not one of KNOWN_MODULES, so the
+  // all-off assertion above never reaches it (task 1003487).
+  assert.deepEqual(enabledDisciplines(m), ['engineer', 'ideator', 'ui']);
 });

package/tests/newcomer_restock.mjs

@@ -68,6 +68,82 @@ t('loadFloors: real config keeps floor >= 2 per discipline (a spare on every cla
   }
 });
 
+// ---- the ui craft is stocked, so a ui-only newcomer is never starved (task 1003487) ----
+t('ui: the craft is offered, has chores, and none of them needs a browser', () => {
+  assert.ok(r.validDisciplines().has('ui'),
+    'ui-design is default-on, so enabledDisciplines() offers ui and restockAll will stamp it');
+  assert.ok(r.templateDisciplines().has('ui'), 'ui has chores defined, so restockDiscipline accepts it');
+  const chores = r.loadTemplates().ui;
+  assert.ok(Array.isArray(chores) && chores.length >= 1, 'at least one ui chore exists');
+  for (const c of chores) {
+    assert.ok(c.template_id && c.version_id && c.title, `${c.template_id || '?'} has id/version/title`);
+    assert.equal(c.discipline, 'ui');
+    assert.ok(c.est_minutes <= 60, `${c.template_id} is inside the newcomer scope ceiling`);
+    // Xenos-safe: a design chore necessarily READS the branding pack, so the
+    // property that matters is that every one of them says, in its done_when,
+    // that the world and the pipeline core are not what gets edited.
+    const dw = (c.done_when || []).join(' ');
+    assert.ok(/NOT modified|were untouched|untouched/i.test(dw),
+      `${c.template_id} states what must stay untouched`);
+    assert.ok(/permission|infra|migration/i.test(dw),
+      `${c.template_id} names the protected core as off-limits`);
+  }
+  // The kit needs Chrome/Edge, which a newcomer's machine may not have — so at
+  // least one ui chore must be verifiable without a browser, or the craft starves
+  // exactly the people it was opened for.
+  assert.ok(chores.some((c) => !/kit\/render\.js/.test((c.done_when || []).join(' '))),
+    'a ui newcomer with no browser still has a chore they can finish');
+});
+
+t('ui: the floor config stocks the craft', () => {
+  assert.ok(r.loadFloors().ui >= 1, 'ui declares a standing pool, so the shelf refills');
+});
+
+// ---- one file read per operation (task 1003487 re-grade: the efficiency finding) ----
+// The templates file was being re-read and re-parsed by every helper on the path —
+// templateDisciplines() and loadTemplates() back to back per call, and once per
+// craft inside restockAll. These pin the single-read contract so it cannot regress.
+{
+  const nodefs = require('node:fs');
+  const realRead = nodefs.readFileSync;
+  let reads = 0;
+  nodefs.readFileSync = (p, ...rest) => {
+    if (String(p).includes('newcomer-floor.templates.json')) reads += 1;
+    return realRead(p, ...rest);
+  };
+  try {
+    reads = 0;
+    await r.restockForClaim({ source: 'not-a-chore', discipline: 'ui' });
+    assert.equal(reads, 0, 'a non-chore task is rejected before any file read');
+
+    reads = 0;
+    const byDisc = r.loadTemplates();
+    assert.equal(reads, 1, 'loadTemplates reads once');
+    r.templateDisciplines(byDisc);
+    assert.equal(reads, 1, 'templateDisciplines re-uses an already-loaded map');
+    await r.restockDiscipline('bogus-craft', byDisc);
+    assert.equal(reads, 1, 'restockDiscipline re-uses it too');
+  } finally {
+    nodefs.readFileSync = realRead;
+  }
+  passed += 1;
+  console.log('  PASS  restock reads newcomer-floor.templates.json once per operation');
+}
+
+t('restockForClaim threads its loaded map into the no-match fallback', () => {
+  // The read-counting block above drives the helpers directly; this pins the real
+  // call chain it cannot reach without a database — the fallback branch taken when
+  // a chore's source_ref does not resolve to a known template.
+  const src = require('node:fs').readFileSync(
+    new URL('../modules/onboarding/newcomer-restock.js', import.meta.url), 'utf8');
+  const body = src.slice(src.indexOf('async function restockForClaim'),
+                         src.indexOf('async function restockAll'));
+  assert.ok(/const byDiscipline = loadTemplates\(\);/.test(body), 'it loads the templates once');
+  assert.ok(!/loadTemplates\(\)\[/.test(body), 'and never re-indexes a second fresh load');
+  assert.ok(/restockDiscipline\(task\.discipline, byDiscipline\)/.test(body),
+    'the fallback re-uses that map rather than letting the default param re-read the file');
+});
+
 // ---- restockForClaim: skip path is DB-free (awaited) ----
 // (returns an array of per-template results; the skip path is a 1-element array.)
 assert.deepEqual(await r.restockForClaim(null), [{ skipped: true }]);