@bongos/core 1.19.322 → 1.19.324

package/scripts/gds/version-literal-guard.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// scripts/gds/version-literal-guard.js — no ops script names a version id
+// (task 1003166 / G02, goal 1000077; criterion guards-no-hardcoded-version).
+//
+// THE INCIDENT. smoke-write.sh hardcoded 'PMS-V1'. That version shipped, so
+// `version_closed` refused every create and the write-path smoke COULD NOT PASS
+// — while /merge-mode Step 5 went on telling the operator "4/4 expected". The
+// failure reads as a broken smoke, not a stale constant, which is why it sat
+// (idea 1000823). Nine scripts carried the same bomb; four of the versions they
+// named (PMS-V1, PMS-V2, GDS-V3, GDS-V4) had ALREADY shipped when this ran.
+//
+// WHAT IT CHECKS, narrowly: a version-shaped literal ASSIGNED TO A VERSION FIELD
+// or used as a version DEFAULT, in an executable script. Not any mention of a
+// version anywhere — smoke-claim-consistency.sh legitimately says "PMS-V2 P6 not
+// live yet" in a comment and an echo, and flagging that would be the over-broad
+// source assertion this repo has learned to avoid (learning 1000196). Comment
+// lines are stripped before matching for the same reason.
+//
+// EXCLUDED BY PATH, not by allowlist: seeders and tests. A seeder's whole subject
+// IS a specific historical version — `seed-v3-tasks.js` naming GDS-V3 is correct,
+// and asking it to resolve one at runtime would break it.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Any prefix, so a version scheme invented next year is covered too — better
+// than enumerating PMS/GDS/BONGOS/CB and finding out later that OTB-V2 slipped.
+const VERSION_LITERAL = String.raw`['"][A-Z][A-Z0-9]*-V\d+['"]`;
+// A version FIELD or a version DEFAULT — the two shapes that actually rot.
+const VERSION_FIELD = String.raw`version_id|versionId|suggested_version|target_version|DEFAULT_VERSION|VERSION_ID`;
+const ASSIGNED = new RegExp(`(?:${VERSION_FIELD})\\s*['"]?\\s*[:=][^,;)]*${VERSION_LITERAL}`);
+const DEFAULTED = new RegExp(`--version[^\\n]*?\\|\\|\\s*${VERSION_LITERAL}`);
+
+// path::reason. A justified entry, one line, like every other guard here.
+const VERSION_LITERAL_ALLOW = new Map([
+  ['scripts/gds/grade-smoke.js',
+    'GOOD_TASK / BAD_TASK are in-memory fixtures handed to grader.gradeSubagent; they are never POSTed, so no version_closed can refuse them and the literal cannot rot into a failure.'],
+  ['scripts/gds/status.js',
+    'DEFAULT_VERSION is an owner-facing dashboard default with an env override, and TWO versions are currently building — so "most recent building" is not a derivable answer here. Retargeting what /status shows by default is an owner decision, not a refactor.'],
+]);
+
+function isExempt(rel) {
+  return /(^|\/)seed-[^/]*\.js$/.test(rel)         // a seeder's subject IS that version
+    || /\.test\.js$/.test(rel)                     // fixtures pinned to a historical version
+    || /(^|\/)fixtures\//.test(rel)
+    || /(^|\/)version-literal-guard\.js$/.test(rel); // this file names the shapes it hunts
+}
+
+// Drop comment lines only — never inline content, which is where real code lives.
+function stripComments(src, rel) {
+  const lineComment = rel.endsWith('.sh') ? /^\s*#/ : /^\s*(\/\/|\*|\/\*)/;
+  return String(src).split('\n').map((l) => (lineComment.test(l) ? '' : l));
+}
+
+function scanScripts(files, read) {
+  const violations = [];
+  let scanned = 0;
+  for (const rel of files) {
+    if (isExempt(rel)) continue;
+    const src = read(rel);
+    if (src === null) continue;
+    scanned += 1;
+    if (VERSION_LITERAL_ALLOW.has(rel)) continue;
+    stripComments(src, rel).forEach((line, i) => {
+      if (ASSIGNED.test(line) || DEFAULTED.test(line)) {
+        violations.push(
+          `${rel}:${i + 1} names a version id where one should be RESOLVED: ${line.trim().slice(0, 90)}`
+          + ' — a literal works until that version ships, then version_closed refuses every write and the'
+          + ' failure reads as broken code. Use resolveDefaultVersion() from version-select.js'
+          + ' (bash: VERSION_ID=$(node scripts/gds/version-select.js)), or allowlist it with a reason.'
+        );
+      }
+    });
+  }
+  return { violations, scanned };
+}
+
+function trackedScripts() {
+  const out = execFileSync('git', ['ls-files', 'scripts/*.js', 'scripts/*.sh', 'scripts/**/*.js', 'scripts/**/*.sh'], {
+    cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return String(out || '').split('\n').map((f) => f.trim()).filter(Boolean);
+}
+
+const NAME = 'no ops script hardcodes a version id (G02)';
+
+function checkNoVersionLiterals({ files = null, read = null } = {}) {
+  const list = files || trackedScripts();
+  if (!list.length) {
+    return { name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked scripts; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of scripts/ for hardcoded version ids.' };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned } = scanScripts(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} executable script(s) under scripts/ scanned: none may assign a version-shaped literal to a version field or use one as a --version default. Seeders, *.test.js and fixtures are exempt by path (their subject IS a historical version); ${VERSION_LITERAL_ALLOW.size} justified allowlist entr${VERSION_LITERAL_ALLOW.size === 1 ? 'y' : 'ies'}.`,
+  };
+}
+
+function main() {
+  const r = checkNoVersionLiterals();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkNoVersionLiterals, scanScripts, stripComments, isExempt, VERSION_LITERAL_ALLOW, ASSIGNED, DEFAULTED };

package/scripts/gds/version-select.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// scripts/gds/version-select.js — resolve "the version to use" at RUNTIME
+// (task 1003166 / G02, goal 1000077; criterion guards-no-hardcoded-version).
+//
+// THE BUG THIS ENDS. scripts/gds/smoke-write.sh hardcoded 'PMS-V1'. That version
+// shipped, so `version_closed` correctly refuses the create — meaning the
+// write-path smoke CANNOT pass — while /merge-mode Step 5 still tells the
+// operator "4/4 expected". A literal version id is a time bomb with a long fuse:
+// it works until the version ships, and then it fails in a way that reads as a
+// broken smoke rather than a stale constant (idea 1000823).
+//
+// Nine scripts carried one. The rule they now share is capture.js's, which was
+// already right: the most recent BUILDING version. Extracted here so there is one
+// implementation rather than nine, and exposed as a CLI so the bash smokes get
+// the same answer as the JS callers instead of reimplementing the sort in python.
+//
+//   const { resolveDefaultVersion } = require('./version-select.js');   // JS
+//   VERSION_ID=$(node scripts/gds/version-select.js) || exit 1          # bash
+
+'use strict';
+
+const { cliExit } = require('./cli-lib');
+
+// PURE, so the selection rule is unit-tested without a session or a network.
+// Returns a version id, or null when nothing is building — never a guess.
+function pickDefaultVersion(versions) {
+  if (!Array.isArray(versions)) return null;
+  const building = versions.filter((v) => v && v.status === 'building');
+  if (building.length === 0) return null;
+  // Most recent by started_at. A null started_at sorts last rather than
+  // throwing, so a half-filled row cannot decide the answer (capture.js's
+  // original behaviour, kept deliberately).
+  building.sort((a, b) => {
+    const ta = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const tb = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return tb - ta;
+  });
+  return building[0].id;
+}
+
+async function resolveDefaultVersion(deps = {}) {
+  const client = deps.cliClient || require('./cli-lib').cliClient;
+  const api = await client();
+  const r = await api.versions.getVersions();
+  if (!r.ok) return null;
+  return pickDefaultVersion(r.data?.versions ?? []);
+}
+
+// A version id is interpolated by bash callers into a quoted Python string, so
+// the ONE place that can guarantee it is safe is here, at the source, rather than
+// four escaping fixes downstream. Ids are `[A-Za-z][A-Za-z0-9._-]*` in practice;
+// anything else is refused rather than printed. Defense in depth: writing a
+// versions.id is already a privileged operation.
+const SAFE_ID = /^[A-Za-z][A-Za-z0-9._-]*$/;
+
+async function main() {
+  const id = await resolveDefaultVersion();
+  if (!id) {
+    // Exit non-zero rather than printing something a caller would interpolate:
+    // a smoke that creates a task against the empty string is worse than one
+    // that stops and says why.
+    console.error('version-select: no version is currently `building` — cannot resolve a default.');
+    console.error('  Open one, or pass an explicit --version to the caller.');
+    return cliExit(1);
+  }
+  if (!SAFE_ID.test(id)) {
+    console.error(`version-select: refusing to emit ${JSON.stringify(id)} — not a plain version id.`);
+    console.error('  Callers splice this into a quoted string; an id with a quote or backslash could break out.');
+    return cliExit(1);
+  }
+  process.stdout.write(id);
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error(`version-select: ${err && err.message}`); cliExit(1); });
+}
+
+module.exports = { pickDefaultVersion, resolveDefaultVersion, SAFE_ID };

package/src/module-api.js

@@ -1071,8 +1071,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.320 with no explicit bump. run 32679324013. (task 1002620)
 //   1.19.322 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.321 with no explicit bump. run 32679604360. (task 1002620)
+//   1.19.323 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.322 with no explicit bump. run 32680138776. (task 1002620)
+//   1.19.324 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.323 with no explicit bump. run 32737868129. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.322'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.324'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/goal_subtitle.mjs

@@ -0,0 +1,237 @@
+// tests/goal_subtitle.mjs — a goal's explanation stops living inside its name
+// (task 1003224, goal 1000072, criterion legibility-goal-names-and-claude-text).
+//
+// Owner directive, three parts: the TITLE is a name; the SUBTITLE is a separate,
+// subordinate, on-demand field; and the bulk prose Claude writes into the
+// description is presented as Claude's text, absent from the default reading
+// path until someone asks for it.
+//
+// These tests pin the parts a future edit could quietly undo: that subtitle is
+// carried by the same prose-edit path as title (so it inherits the audit trail
+// rather than getting a private one), that the disclosure is CLOSED by default,
+// and that task creation did NOT gain a subtitle — the identical validator pair
+// appears in POST /goals and POST /goals/:id/tasks, and only the first should
+// have changed.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const goalEdits = require(path.join(ROOT, 'modules', 'lifecycle', 'goal-edits.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const fakeReqRes = ({ body }) => {
+  const res = { code: null, statusCode: null, payload: null,
+    fail(code, status, extra) { this.code = code; this.statusCode = typeof status === 'number' ? status : status?.status ?? 400; this.payload = { error: code, ...(extra || {}) }; return this; },
+    status(c) { this.statusCode = c; return this; },
+    json(p) { this.payload = p; return this; } };
+  return { req: { params: { id: '7' }, body, builder: { id: 1, rank: 'archon' } }, res };
+};
+const deps = {
+  db: { getGoal: async () => ({ id: 7, status: 'open', created_by: 1 }), getGoalMember: async () => null },
+  authorizeGoalManagement: () => ({ ok: true }),
+  validateOrRespond: () => false,
+  parseId: () => 7,
+  LIMITS: { TITLE: 200, DESCRIPTION: 50000 },
+};
+
+// ---- the field travels the existing prose path -----------------------------
+test('a subtitle-only PATCH is accepted and recorded', () => {
+  // Not a private write path: subtitle rides title's handler so the prose-edit
+  // audit trail (deltas + record) covers it identically.
+  let patched = null; const recorded = [];
+  const handler = goalEdits.goalProseHandler({
+    ...deps,
+    update: async ({ patch }) => { patched = patch; return { goal: { id: 7, ...patch }, deltas: [goalEdits.proseDelta('subtitle', null, patch.subtitle)] }; },
+    record: async (...a) => { recorded.push(a); },
+  });
+  const { req, res } = fakeReqRes({ body: { subtitle: 'the grep path' } });
+  return handler(req, res).then(() => {
+    assert.equal(res.code, null, `must not fail — got ${res.code}`);
+    assert.deepEqual(patched, { subtitle: 'the grep path' }, 'only the named field is patched');
+    assert.equal(res.payload.deltas[0].field, 'subtitle');
+    assert.equal(recorded.length, 1, 'the edit is audit-recorded like any other prose edit');
+  });
+});
+
+test('an EMPTY subtitle is a legal value, not a no-op', () => {
+  // '' means deliberately blank; NULL means never set. The column has no
+  // default precisely so the UI can tell them apart, so '' must reach the patch.
+  let patched = null;
+  const handler = goalEdits.goalProseHandler({
+    ...deps,
+    update: async ({ patch }) => { patched = patch; return { goal: { id: 7 }, deltas: [] }; },
+    record: async () => {},
+  });
+  const { req, res } = fakeReqRes({ body: { subtitle: '' } });
+  return handler(req, res).then(() => {
+    assert.equal(res.code, null);
+    assert.ok(Object.prototype.hasOwnProperty.call(patched, 'subtitle'), 'empty string must still be a patch');
+    assert.equal(patched.subtitle, '');
+  });
+});
+
+test('nothing_to_update names subtitle as editable', () => {
+  const handler = goalEdits.goalProseHandler(deps);
+  const { req, res } = fakeReqRes({ body: { nope: 1 } });
+  return handler(req, res).then(() => {
+    assert.equal(res.code, 'nothing_to_update');
+    assert.deepEqual(res.payload.editable, ['title', 'subtitle', 'description']);
+  });
+});
+
+test('title and description still work — subtitle is additive', () => {
+  let patched = null;
+  const handler = goalEdits.goalProseHandler({
+    ...deps,
+    update: async ({ patch }) => { patched = patch; return { goal: { id: 7, ...patch }, deltas: [] }; },
+    record: async () => {},
+  });
+  const { req, res } = fakeReqRes({ body: { title: 'Findability', description: 'long prose' } });
+  return handler(req, res).then(() => {
+    assert.deepEqual(patched, { title: 'Findability', description: 'long prose' });
+    assert.ok(!Object.prototype.hasOwnProperty.call(patched, 'subtitle'), 'an unsent field is not patched to null');
+  });
+});
+
+// ---- the data layer --------------------------------------------------------
+test('the migration is additive, core-numbered, and sets no default', () => {
+  const raw = read('migrations', 'core_224_goal_subtitle.sql');
+  assert.match(raw, /ADD COLUMN IF NOT EXISTS subtitle text/);
+  // Assert over the STATEMENTS, not the prose. The first version of this test
+  // matched /DEFAULT ''/ anywhere in the file and failed on the migration's own
+  // comment explaining why it does NOT set a default — the same over-broad-source
+  // -assertion mistake this session has made repeatedly (learning 1000196).
+  const ddl = raw.split('\n').filter((l) => !/^\s*--/.test(l)).join('\n');
+  assert.ok(!/\bDROP\b/i.test(ddl), 'no destructive DDL');
+  assert.ok(!/SET NOT NULL/i.test(ddl), 'stays nullable');
+  assert.ok(!/ADD COLUMN[^;]*DEFAULT/i.test(ddl), 'the added column takes no default');
+  assert.match(ddl, /schema_migrations/, 'records itself');
+});
+
+test('subtitle is in GOAL_COLS, so every read returns it', () => {
+  // One column list drives getGoal, the list query and createGoal's RETURNING —
+  // adding it anywhere else would be a second source that can drift.
+  const src = read('modules', 'lifecycle', 'db-goals.js');
+  const cols = /const GOAL_COLS\s*=\s*\n?\s*'([^']+)'/.exec(src);
+  assert.ok(cols, 'GOAL_COLS is still a single string literal');
+  assert.ok(cols[1].split(',').map((c) => c.trim()).includes('subtitle'), 'subtitle is selected');
+});
+
+test('POST /goals gained subtitle and POST /goals/:id/tasks did NOT', () => {
+  // The identical `title` + `description` validator pair appears in both routes.
+  // A blind replace-all would have given task creation a subtitle; this pins the
+  // boundary. (The first attempt at this edit tripped on exactly that ambiguity.)
+  const src = read('modules', 'lifecycle', 'routes', 'goals.js');
+  const goalRoute = src.slice(src.indexOf("router.post('/goals',"), src.indexOf("router.get('/goals',"));
+  assert.match(goalRoute, /subtitle: \{ type: 'string'/, 'the goal route takes a subtitle');
+  const taskRoute = src.slice(src.indexOf("router.post('/goals/:id/tasks',"));
+  const taskValidator = taskRoute.slice(0, taskRoute.indexOf('})) return;'));
+  assert.ok(!/subtitle/.test(taskValidator), 'task creation must NOT accept a subtitle');
+});
+
+// ---- the default reading path ---------------------------------------------
+test("Claude's prose is a CLOSED disclosure, not visible body text", () => {
+  const html = read('modules', 'hall-ui', 'public', 'goals.html');
+  assert.match(html, /<details class="claude-text"[^>]*hidden/, 'a <details>, hidden until it has content');
+  assert.ok(!/<p class="goal-detail__desc" id="goal-detail-desc"><\/p>/.test(html),
+    'the description is no longer a bare always-visible paragraph');
+  // the description element must now live INSIDE the disclosure
+  const det = html.slice(html.indexOf('<details class="claude-text"'));
+  const inner = det.slice(0, det.indexOf('</details>'));
+  assert.match(inner, /id="goal-detail-desc"/, 'the description renders inside the disclosure');
+});
+
+// applyGoalProse is pure enough to RUN, so these two assert behaviour rather
+// than source text — a stronger pin, and the reason the rules were moved out of
+// goals-page.js (which is 500 lines over the excess-lines ratchet) in the first
+// place. Fake elements stand in for the DOM.
+const el = () => ({ textContent: null, hidden: null, open: null });
+function applyProse(goal) {
+  const lib = read('modules', 'hall-ui', 'public', 'goals-lib.js');
+  const els = { sub: el(), desc: el(), claude: el() };
+  const fn = new Function('window', `${lib}; return window.OTBGoalsLib.applyGoalProse;`)({ OTB: { escapeHtml: (x) => x } });
+  fn(els, goal);
+  return els;
+}
+
+test('the disclosure is CLOSED on render, never opened for the user', () => {
+  const els = applyProse({ description: 'Claude wrote a lot here', subtitle: 'sub' });
+  assert.equal(els.claude.open, false, 'closed');
+  assert.equal(els.claude.hidden, false, 'present, because there is prose to reveal');
+  assert.equal(els.desc.textContent, 'Claude wrote a lot here');
+});
+
+test('a goal with no description shows no empty disclosure', () => {
+  const els = applyProse({ description: '   ', subtitle: 'sub' });
+  assert.equal(els.claude.hidden, true, 'an empty disclosure invites a dead click');
+});
+
+test('an unset subtitle is hidden; a set one is shown trimmed', () => {
+  assert.equal(applyProse({}).sub.hidden, true, 'NULL subtitle renders nothing');
+  const els = applyProse({ subtitle: '  the grep path  ' });
+  assert.equal(els.sub.hidden, false);
+  assert.equal(els.sub.textContent, 'the grep path');
+});
+
+test('on a LIST the subtitle is a tooltip, never a second visible line', () => {
+  const js = read('modules', 'hall-ui', 'public', 'goals-page.js');
+  // The helper lives in goals-lib.js — the file that exists because
+  // goals-page.js is over the excess-lines ratchet (task 1003135).
+  const lib = read('modules', 'hall-ui', 'public', 'goals-lib.js');
+  assert.match(lib, /function subtitleAttr/);
+  assert.match(lib, /escapeHtml\(t\)/, 'escaped, since it lands in an attribute');
+  for (const anchor of ['class="gr-title"', 'class="goal-card__title gr-title"']) {
+    const i = js.indexOf(anchor);
+    assert.ok(i > 0, `${anchor} still rendered`);
+    assert.match(js.slice(i, i + 160), /subtitleAttr\(g\)/, `${anchor} carries the tooltip`);
+  }
+});
+
+test('every CSS token the new styles use actually exists', () => {
+  // copy-desk.css shipped with --line and --panel, which style.css never
+  // defines, so its fallbacks rendered as nothing (idea 1000821).
+  const css = read('modules', 'hall-ui', 'public', 'goals.css');
+  const style = read('modules', 'hall-ui', 'public', 'style.css');
+  const block = css.slice(css.indexOf('task 1003224'));
+  const used = new Set([...block.matchAll(/var\((--[a-z-]+)\)/g)].map((m) => m[1]));
+  assert.ok(used.size >= 4, 'the new block does use tokens');
+  for (const t of used) {
+    assert.ok(new RegExp(`^\\s*${t}:`, 'm').test(style), `${t} must be defined in style.css`);
+  }
+});
+
+test('the subtitle style is subordinate to the title style', () => {
+  const css = read('modules', 'hall-ui', 'public', 'goals.css');
+  const size = (sel) => {
+    const i = css.indexOf(sel);
+    assert.ok(i > 0, `${sel} exists`);
+    const m = /font-size:\s*([\d.]+)px/.exec(css.slice(i, i + 300));
+    return m ? Number(m[1]) : null;
+  };
+  const title = size('.goal-detail__title');
+  const sub = size('.goal-detail__subtitle');
+  assert.ok(title && sub, 'both declare a size');
+  assert.ok(sub < title, `subtitle (${sub}px) must read smaller than the name (${title}px)`);
+});
+
+test("the PATCH route's own comment names every field it accepts", () => {
+  // The API reference is GENERATED from this comment, so the generator
+  // faithfully republishes a stale one: after subtitle was added the docs still
+  // advertised 'title/description', which the grader caught as a blocker. This
+  // pins comment and validator together so the next added field cannot drift.
+  const routes = read('modules', 'lifecycle', 'routes', 'goals.js');
+  const i = routes.indexOf("router.patch('/goals/:id',");
+  assert.ok(i > 0, 'the PATCH route still exists');
+  const comment = routes.slice(routes.lastIndexOf('// PATCH /goals/:id', i), i);
+  const edits = read('modules', 'lifecycle', 'goal-edits.js');
+  const validator = edits.slice(edits.indexOf('function goalProseHandler'));
+  for (const field of ['title', 'subtitle', 'description']) {
+    assert.match(validator, new RegExp(`${field}: \\{ `), `${field} is validated`);
+    assert.ok(comment.includes(field), `the route comment must name ${field} — the API reference is generated from it`);
+  }
+});

package/tests/goal_tier.mjs

@@ -65,8 +65,10 @@ await test('createGoal: INSERT binds all six fields in order and returns the row
   );
   assert.deepEqual(out, GOAL_ROW, 'returns the inserted row');
   const ins = find(pool.queries, /INSERT INTO goals/);
-  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42],
-    'version_id, title, description, scope_modules, status, created_by — in that order');
+  // task 1003224 appended `subtitle` as $7 rather than inserting it next to
+  // title, so $1–$6 keep the positions this test has always pinned.
+  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42, null],
+    'version_id, title, description, scope_modules, status, created_by, then subtitle — in that order');
   assert.match(ins.sql, /RETURNING/, 'returns the row, not just inserts');
 });
 
@@ -87,8 +89,8 @@ await test('createGoal: defaults — null description/createdBy, empty scope, op
   const pool = fakePool((s) => (/INSERT INTO goals/.test(s) ? { rows: [GOAL_ROW] } : null));
   await createGoal({ versionId: 'V1', title: 'general' }, { pool });
   const ins = find(pool.queries, /INSERT INTO goals/);
-  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null],
-    'unspecified fields fall back to null / [] / open');
+  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null, null],
+    'unspecified fields fall back to null / [] / open — subtitle ($7) defaults to null too');
 });
 
 // =========================================================================