@bongos/core 1.20.5 → 1.20.6

package/modules/specialities/specialities.js

@@ -204,7 +204,23 @@ function canAdopt(speciality, viewer) {
 // characters and a session cannot carry that; what the contract carries is the
 // speciality's terms plus an inventory of what it knows, so the agent knows to
 // GO AND SEARCH rather than believing the subject is undocumented.
-function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuthored = true, authorLabel = null } = {}) {
+// The one sentence naming the enabled skills, or null — SILENT when nothing is on
+// (the common state after part 2), never an empty list. Only a skill still both
+// OFFERED and (when `installed` is known) INSTALLED is named: the PUT checked
+// both, but an author can shrink the offer and a deploy can drop a skill later,
+// and advising a session to reach for a skill it cannot find is noise.
+function enabledSkillsLine(active, installed = null) {
+  const enabled = Array.isArray(active && active.enabled_skills) ? active.enabled_skills : [];
+  const offered = new Set(Array.isArray(active && active.skills) ? active.skills : []);
+  const names = [...new Set(enabled)].filter((n) => typeof n === 'string' && SKILL_NAME_RE.test(n)
+    && offered.has(n) && (!installed || installed.has(n)));
+  if (!names.length) return null;
+  return `In this speciality the builder chose to lean on these skills: ${names.map((n) => `/${n}`).join(', ')}. `
+    + 'Reach for them when the work calls for one. This is advice, not permission — '
+    + 'each still runs only if the builder\'s rank allows it.';
+}
+
+function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuthored = true, authorLabel = null, installed = null } = {}) {
   if (!active) return null;
   const parts = [];
   // Conditional, not unconditional: an unnamed speciality has nothing to announce,
@@ -243,6 +259,15 @@ function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuth
     );
   }
 
+  // THE ENABLED SKILLS (task 1004074, ADR 0310 part 3). What THIS builder turned
+  // on in the walkthrough, so the speciality changes what the session reaches for.
+  // After the provenance fence on purpose: the list is the adopter's own choice,
+  // not the author's prose. Advice only — naming a skill grants nothing, and the
+  // line says so, because a session told "use X" by a builder who cannot run X
+  // should hit the rank gate, not believe the speciality opened it.
+  const skillsLine = enabledSkillsLine(active, installed);
+  if (skillsLine) parts.push(skillsLine);
+
   const contract = parts.filter(Boolean).join('\n');
   // inject:false for an empty contract, matching how the wandering knob stays
   // silent on its permissive levels rather than spending context saying nothing.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.5",
+  "version": "1.20.6",
   "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

@@ -8066,9 +8066,27 @@
     }
   ],
   "1.20.5": [
+    {
+      "id": "1002456",
+      "text": "The list of decision records now says plainly which 20 numbers are shared by two documents, and tells everyone to cite a record by its file name so nobody opens the wrong one."
+    },
+    {
+      "id": "1004394",
+      "text": "Code tidy-up in the tweak editor: an out-of-date comment fixed. Nothing changes for artists."
+    },
+    {
+      "id": "1004074",
+      "text": "The skills you switch on for a speciality now follow you into your work sessions. Your assistant is told which ones you chose to lean on, and only in sessions for that craft. Switch nothing on and nothing extra is said. It is"
+    },
     {
       "id": "1004391",
       "text": "Wrote down a rule: when several linked tasks are claimed together, whoever claims them must finish them in order. Nothing enforces it yet, by the owner's choice."
     }
+  ],
+  "1.20.6": [
+    {
+      "id": "1004392",
+      "text": "A goal's checklist item no longer ticks itself off just because some linked work shipped. Once the work is done it now shows \"Awaiting UAT\", and it closes only when someone who did not build it tries it on the live site and up"
+    }
   ]
 }

package/scripts/gds/cli-lib.js

@@ -680,10 +680,13 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
   // account billing, so identity is not an auth boundary. anthropic_user_id is
   // still kept in the session as cosmetic attribution; it is simply not
   // transmitted as a header.
+  // opts.rawBody (a Buffer) + opts.contentType send bytes instead of JSON — a
+  // UAT recording upload (task 1004392), whose route reads a raw video body.
+  if (opts.rawBody) headers['Content-Type'] = opts.contentType || 'application/octet-stream';
   const res = await dispatchedFetch(`${base}${urlPath}`, {
     method,
     headers,
-    body: body ? JSON.stringify(body) : null,
+    body: opts.rawBody ? opts.rawBody : (body ? JSON.stringify(body) : null),
     dispatcher: noKeepAliveDispatcher(),
   });
   const text = await res.text();

package/scripts/gds/fitness-checks-write-validation.js

@@ -50,6 +50,10 @@ const WRITE_VALIDATION_EXEMPT = new Set([
   // the route's express.raw parser and read by module-artifact.verifyModuleArtifact, which
   // recomputes every hash and refuses anything that is not a well-formed module version.
   'POST /store/modules/:key/versions',
+  // Not a JSON body: the raw UAT recording (task 1004392, ADR 0351), capped by the
+  // route's express.raw parser and read by criterion-uat.screenRecording, which
+  // refuses anything that is not a bounded mp4/webm whose bytes match its type.
+  'POST /done-when/:criterionId/uat/recording',
 ]);
 
 // KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).

package/scripts/gds/status.js

@@ -37,6 +37,17 @@
 const { API_BASE, cliClient, assertInstanceMatch, cliExit } = require('./cli-lib');
 const { resolveEnv } = require('../../src/instance-config');
 const { resolveDefaultVersion } = require('./version-select.js');
+// task 1004392 (ADR 0351): the criterion's UAT state, in the same words the
+// server and /goal-uat use. Dependency-free, so this public CLI pays nothing.
+const { stateLabel } = require('../../modules/lifecycle/criterion-uat.js');
+
+// One criterion's state as a short phrase. A server older than the UAT rule
+// sends no uat_state, and then the old satisfied/not answer is the truth.
+function criterionStateText(c) {
+  if (!c.uat_state) return c.satisfied ? 'satisfied ✓' : 'not satisfied';
+  const label = stateLabel(c.uat_state);
+  return c.satisfied ? `${label} ✓` : label;
+}
 const {
   looksLikeVersionId,
   resolveCriterionIn,
@@ -270,7 +281,7 @@ function renderStatusWidget(data, criterion) {
     return `${STATUS_WIDGET_STYLE}
 <h2 class="st-sr">${sesc(data.version_id)} criterion ${sesc(criterionLabel(c))} ${c.satisfied ? 'is satisfied' : 'is not yet satisfied'}: ${c.counts.shipped} of ${c.counts.total} gating tasks shipped.</h2>
 <div class="st-card">
-  <div class="st-head"><span class="st-title"><i class="ti ti-checklist" aria-hidden="true"></i>${sesc(data.version_id)} · ${sesc(criterionLabel(c))}</span><span class="st-meta">${c.satisfied ? '<span class="st-ok">satisfied</span>' : 'not satisfied'} · ${c.counts.shipped}/${c.counts.total} shipped</span></div>
+  <div class="st-head"><span class="st-title"><i class="ti ti-checklist" aria-hidden="true"></i>${sesc(data.version_id)} · ${sesc(criterionLabel(c))}</span><span class="st-meta">${c.satisfied ? `<span class="st-ok">${sesc(criterionStateText(c))}</span>` : sesc(criterionStateText(c))} · ${c.counts.shipped}/${c.counts.total} shipped</span></div>
   <div class="st-crit">${sesc(c.criterion_md.replace(/\*\*/g, '').slice(0, 160))}</div>
   ${body}
   <div class="st-foot">remaining: ${sesc(remainingSummary(c.remaining))}${claimHint}</div>
@@ -314,7 +325,7 @@ function renderStatusMarkdown(data, criterion) {
   const lines = [];
   if (criterion) {
     const c = criterion;
-    lines.push(`**/status · ${data.version_id} · ${criterionLabel(c)}** — ${c.satisfied ? 'satisfied ✓' : 'not satisfied'}`);
+    lines.push(`**/status · ${data.version_id} · ${criterionLabel(c)}** — ${criterionStateText(c)}`);
     lines.push(`_${c.criterion_md.replace(/\*\*/g, '').slice(0, 160)}_`);
     lines.push('');
     if (c.tasks.length) {
@@ -405,7 +416,7 @@ function printAll(data) {
 }
 
 function printOne(data, c) {
-  console.log(`\n${data.version_id} · ${c.criterion_id}  (C${c.cnum})   [${c.satisfied ? 'satisfied ✓' : 'not satisfied'}]`);
+  console.log(`\n${data.version_id} · ${c.criterion_id}  (C${c.cnum})   [${criterionStateText(c)}]`);
   console.log(`"${c.criterion_md.replace(/\*\*/g, '').slice(0, 120)}"\n`);
   if (c.tasks.length === 0) {
     console.log('  (no tasks linked — this criterion has no structured gating tasks yet)\n');

package/scripts/gds/uat.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// scripts/gds/uat.js — see, and sign off, a criterion's UAT from a session
+// (task 1004392, goal 1000089; ADR 0351). The CLI half of /goal-uat.
+//
+// WHY. A criterion no longer closes because its linked tasks shipped. It reads
+// "Awaiting UAT" until someone who did not ship the work performs it on the live
+// site and signs it off with a recording (or, for a criterion marked
+// backend-only, a recording-free sign-off). This is how a session does that
+// before the hall has buttons for it (task 1004402), and what /goal-uat drives.
+//
+// Usage:
+//   node scripts/gds/uat.js --queue [--version V]            every criterion awaiting UAT
+//   node scripts/gds/uat.js <criterion-id>                    its three checks + sign-offs
+//   node scripts/gds/uat.js <criterion-id> --recording <file.mp4|.webm> [--live-attested] [--note "..."]
+//   node scripts/gds/uat.js <criterion-id> --backend-signoff [--live-attested] [--note "..."]
+//   node scripts/gds/uat.js <criterion-id> --backend-only on|off
+//
+// <criterion-id> is the criterion's numeric id (the `id` /status and the queue
+// print), not its slug. --live-attested is only needed where this site cannot
+// tell on its own whether the work is live; the server says so when it is.
+
+const { apiCall, arg, argText, hasFlag, cliExit } = require('./cli-lib');
+const uat = require('../../modules/lifecycle/criterion-uat');
+
+const API = '/api/bongos';
+
+function refusalText(data) {
+  const e = data && data.error;
+  if (!e) return 'the server refused it.';
+  const msg = typeof e === 'string' ? e : (e.message || e.code);
+  const extra = [];
+  const details = (typeof e === 'object' && e.details) || data;
+  if (details && Array.isArray(details.remaining) && details.remaining.length) {
+    extra.push(`still open: ${details.remaining.map((t) => `task ${t.id} (${t.status})`).join(', ')}`);
+  }
+  if (details && Array.isArray(details.not_live) && details.not_live.length) {
+    extra.push(`not live yet: ${details.not_live.map((t) => `task ${t.task_id}${t.stage ? ` (${t.stage})` : ''}`).join(', ')}`);
+  }
+  return [msg, ...extra].join('\n  ');
+}
+
+async function showQueue() {
+  const version = arg('--version');
+  const q = version ? `?version=${encodeURIComponent(version)}` : '';
+  const r = await apiCall('GET', `${API}/done-when/pending-review${q}`);
+  if (!r.ok) { console.error(`Could not read the queue: ${refusalText(r.data)}`); return 1; }
+  const rows = (r.data.criteria || []).filter((c) => c.awaiting_uat);
+  if (!rows.length) { console.log('Nothing is awaiting UAT.'); return 0; }
+  console.log(`${rows.length} criteri${rows.length === 1 ? 'on' : 'a'} awaiting UAT:\n`);
+  for (const c of rows) {
+    const tag = c.backend_only ? '  [backend-only]' : '';
+    console.log(`  criterion ${c.id}  ${c.criterion_id}${tag}`);
+    console.log(`    goal ${c.goal_id ?? '-'}${c.goal_title ? ` "${c.goal_title}"` : ''}${c.is_last_in_goal ? '  (last open criterion: signing it off can achieve the goal)' : ''}`);
+  }
+  return 0;
+}
+
+async function showOne(id) {
+  const r = await apiCall('GET', `${API}/done-when/${id}/uat`);
+  if (!r.ok) { console.error(`Could not read criterion ${id}: ${refusalText(r.data)}`); return 1; }
+  const v = r.data;
+  console.log(`criterion ${v.criterion.id}  ${v.criterion.criterion_id}  — ${v.uat_label}${v.backend_only ? '  [backend-only]' : ''}\n`);
+  console.log(String(v.criterion.criterion_md || '').trim());
+  console.log('');
+  console.log(`  Code  ${v.checks.code ? 'passed' : 'not yet'}  (${v.linked_tasks.length} linked: ${v.linked_tasks.map((t) => `${t.id} ${t.status}`).join(', ') || 'none'})`);
+  const live = v.checks.live;
+  console.log(`  Live  ${live == null ? '-' : !live.available ? 'this site cannot tell; the signer confirms it' : live.live ? 'running on the site' : `not yet: ${(live.not_live || []).map((t) => t.task_id).join(', ')}`}`);
+  const s = v.checks.uat;
+  console.log(`  UAT   ${s ? `${s.kind === 'uat' ? 'recorded' : 'backend sign-off'} by ${s.signed_off_by_login || s.signed_off_by} on ${String(s.created_at).slice(0, 10)}` : 'not yet'}`);
+  return 0;
+}
+
+async function signOff(id, kind) {
+  let recording = null;
+  if (kind === 'uat') {
+    const file = arg('--recording');
+    const read = uat.readRecordingFile(file);
+    if (!read.ok) { console.error(`Recording refused: ${read.message}`); return 1; }
+    const up = await apiCall('POST', `${API}/done-when/${id}/uat/recording`, null, { rawBody: read.buf, contentType: read.contentType });
+    if (!up.ok) { console.error(`Upload refused: ${refusalText(up.data)}`); return 1; }
+    recording = up.data.recording;
+    console.log(`Uploaded the recording (${Math.round(up.data.bytes / 1024 / 1024 * 10) / 10} MB).`);
+  }
+  const body = { kind };
+  if (recording) body.recording = recording;
+  if (hasFlag('--live-attested')) body.live_attested = true;
+  const note = argText('--note');
+  if (note) body.note = note;
+  const r = await apiCall('POST', `${API}/done-when/${id}/uat`, body);
+  if (!r.ok) { console.error(`Sign-off refused: ${refusalText(r.data)}`); return 1; }
+  console.log(r.data.criterion_closed ? `Signed off. Criterion ${id} is now closed.` : `Signed off, but criterion ${id} did not close yet.`);
+  for (const g of r.data.achieved_goals || []) console.log(`  That was the goal's last criterion: goal ${g} is achieved.`);
+  return 0;
+}
+
+async function setBackendOnly(id, value) {
+  if (value !== 'on' && value !== 'off') { console.error('--backend-only takes on or off.'); return 1; }
+  const r = await apiCall('PUT', `${API}/done-when/${id}/backend-only`, { backend_only: value === 'on' });
+  if (!r.ok) { console.error(`Refused: ${refusalText(r.data)}`); return 1; }
+  console.log(`Criterion ${id} is ${r.data.backend_only ? 'now marked backend-only' : 'no longer backend-only'}.`);
+  return 0;
+}
+
+async function main() {
+  if (hasFlag('--queue')) return showQueue();
+  const id = process.argv[2];
+  if (!id || !/^\d{1,12}$/.test(id)) {
+    console.error('usage: node scripts/gds/uat.js <criterion-id> [--recording f | --backend-signoff | --backend-only on|off]  |  --queue');
+    return 2;
+  }
+  if (arg('--backend-only')) return setBackendOnly(id, arg('--backend-only'));
+  if (hasFlag('--backend-signoff')) return signOff(id, 'backend_signoff');
+  if (arg('--recording')) return signOff(id, 'uat');
+  return showOne(id);
+}
+
+main().then((code) => cliExit(code), (err) => {
+  console.error(`uat: ${err && err.message}`);
+  cliExit(1);
+});

package/src/bongos/route-rank-check.js

@@ -425,6 +425,15 @@ const MODULE_EXPECTED_RANKS = {
     // — but it is scope disposition, not an authority grant, so it delegates with the
     // rest. Pinned by atom so the guarded invariant is the permission, not its floor.
     'POST /done-when/:criterionId/unsatisfy': 'perm:criterion.unsatisfy',
+    // task 1004392 (ADR 0351): a criterion closes on a UAT sign-off. Uploading
+    // the recording and signing off ride `criterion.review`, the review queue's
+    // own atom, because the sign-off IS that review now; the wall that matters is
+    // in-handler (nobody who shipped the linked work may sign it off). Marking a
+    // criterion backend-only decides whether a recording is needed at all, so it
+    // is an AUTHORING act: `criterion.create` plus authorizeCriterionCreate.
+    'POST /done-when/:criterionId/uat/recording': 'perm:criterion.review',
+    'POST /done-when/:criterionId/uat': 'perm:criterion.review',
+    'PUT /done-when/:criterionId/backend-only': 'perm:criterion.create',
     // gate-surface PR approval from the hall (task 1179, ADR 0058 amendment). ADR 0157
     // SPLIT these two: the list route is `gate_approval.read` (metic — the Gate page
     // opens to the working rank), while APPROVING still clears the gate-review hard

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

@@ -139,12 +139,14 @@ await test('EXEC: shipTask passes its transaction CLIENT, and the reconciler pas
 await test('SCOPED vs UNSCOPED: the taskId parameter is what narrows the candidate set', async () => {
   const scoped = fakeExec({ rows: [] });
   await autoSatisfyShippedCriteria(scoped, { taskId: 42 });
-  assert.deepEqual(scoped.calls[0].params, [42]);
+  // task 1004392 added a second scope ($2, the sign-off route's criterionId); the ship
+  // hook leaves it null.
+  assert.deepEqual(scoped.calls[0].params, [42, null]);
   assert.match(scoped.calls[0].sql, /\$1::bigint IS NULL OR c\.id IN/, 'one SQL serves both shapes');
 
   const sweep = fakeExec({ rows: [] });
   await autoSatisfyShippedCriteria(sweep, {});
-  assert.deepEqual(sweep.calls[0].params, [null], 'unscoped passes NULL, which disables the narrowing clause');
+  assert.deepEqual(sweep.calls[0].params, [null, null], 'unscoped passes NULL, which disables the narrowing clause');
 });
 
 await test('NO-OP: nothing closed means no cascade query at all', async () => {