@bongos/core 1.20.2 → 1.20.4

package/modules/hall-ui/public/settings.css

@@ -202,7 +202,9 @@ select.voices__select { min-width: 140px; }
 /* The adopted contract, shown in full before "Use this" — another builder's prose
    reaching your sessions is the one thing here that must never be folded away. */
 .speciality-contract { flex-basis: 100%; margin-top: 0.5rem; font-size: 0.85rem; }
-.speciality-contract > summary { cursor: pointer; opacity: 0.85; }
+/* 24px tall: the panel was never revealed until task 1004073, so the kit had
+   never measured this toggle; it came back 21px. */
+.speciality-contract > summary { cursor: pointer; opacity: 0.85; min-height: 24px; padding-block: 2px; box-sizing: border-box; }
 .speciality-contract__body {
   white-space: pre-wrap;
   margin: 0.4rem 0 0;
@@ -212,6 +214,55 @@ select.voices__select { min-width: 140px; }
   font-family: inherit;
   opacity: 0.92;
 }
+/* The skills walkthrough (task 1004073, ADR 0310 §3): one offered skill at a
+   time, three answers as a definition list, then a decision. It sits inside the
+   card like the train form, so it inherits the card's ground in both modes. */
+.skill-walk {
+  flex-basis: 100%;
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--rule);
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+}
+/* The measure caps the reading lines, never the section: a capped flex-basis
+   lets the section fit beside the card's actions instead of wrapping under them. */
+.skill-walk > * { max-width: var(--measure); }
+.skill-walk__progress { margin: 0; font-size: 0.8rem; color: var(--ink-soft); }
+.skill-walk__name { margin: 0; font-family: var(--font-mono); font-size: 1rem; color: var(--ink); }
+.skill-walk__facts { margin: 0; display: grid; gap: 0.2rem 0; }
+.skill-walk__facts dt { font-size: 0.8rem; color: var(--ink-soft); margin-top: 0.4rem; }
+.skill-walk__facts dt:first-child { margin-top: 0; }
+.skill-walk__facts dd { margin: 0; color: var(--ink); line-height: 1.5; }
+.skill-walk__note { font-size: 0.8rem; }
+/* "Leave it off" and "Turn it on" are the panel family's plain pill at EQUAL
+   weight: the default is off, so the page must not lean on the reader toward on.
+   Only "Save my choices" takes the accent. A decision already made reads through
+   aria-pressed when the person steps Back to it. */
+.skill-walk__actions { flex-wrap: wrap; }
+.skill-walk__actions .pbtn[aria-pressed="true"] { border-color: var(--ink-soft); }
+.skill-walk__recap { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.5rem; }
+.skill-walk__recap li { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0 0.4rem; }
+.skill-walk__recap .prow__hint { flex-basis: 100%; margin: 0; }
+.skill-walk__recap strong { font-family: var(--font-mono); font-weight: 600; }
+/* "Finish later" is a way out, not a choice about a skill, so it reads as a quiet
+   link below the decision rather than a third button beside it. */
+.skill-walk__later {
+  align-self: flex-start;
+  background: none;
+  border: 0;
+  padding: 0 0.25rem;
+  margin-inline-start: -0.25rem;
+  min-height: 24px;
+  font: inherit;
+  font-size: 0.8rem;
+  color: var(--ink-soft);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  cursor: pointer;
+}
+.skill-walk__later:hover { color: var(--ink); }
 
 /* ---- Software update (task 1004296) -------------------------------------- */
 /* A version is read digit by digit and compared against another, so it takes the mono

package/modules/hall-ui/public/settings.states.json

@@ -9,7 +9,8 @@
   "states": {
     "account": { "auth": true, "actions": [["wait", 900]], "expect": { "visible": ["#settings-h1", "#display-name-input", "#craft-chips"] } },
     "access": { "auth": true, "url": "/settings#access", "actions": [["wait", 900]], "expect": { "visible": ["#cli-reissue-btn", "#sessions-list", "#artkey-card"] } },
-    "preferences": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900]], "expect": { "visible": ["#wander-rows", "#render-rows"] } },
+    "preferences": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900]], "expect": { "visible": ["#wander-rows", "#render-rows", "#specialities-rows"] } },
+    "skills-walkthrough": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900], ["click", "#specialities-rows button[data-act=\"adopt\"]"], ["wait", 700]], "expect": { "visible": [".skill-walk", ".skill-walk__facts", "button[data-walk=\"on\"]", "button[data-walk=\"off\"]"] } },
     "sound": { "auth": true, "url": "/settings#sound", "actions": [["wait", 900]], "expect": { "visible": ["#voices-table", "#sound-rows", "#event-sound-rows"] } },
     "update": { "auth": true, "url": "/settings#software-update", "actions": [["wait", 1200]], "expect": { "visible": ["#software-update-h", "#su-body", "#su-update", ".su-versions"] } }
   },

package/modules/hall-ui/records/panel-family.md

@@ -26,3 +26,5 @@ Also fixed here, as the board task handed forward: the two sub-24px links on Hom
 - **"Up to date" is said only from an answer.** A failed registry read, an unnamed running version and unread release notes each render as what they are; unread notes are never drawn as a version with no changes.
 - **The notes are the soft ink, underlined, on the platform.** There every entry links to its task, and a list of accent-coloured sentences read as a warning. Elsewhere the ids belong to another project's ledger, so the entries are plain text.
 - **Kit:** `settings.states.json` `update`, ALL CLEAN at 1440/390/320 × dark/light against the harness with the fixture `software-update.json` (a live reading for 1.19.1033). Tests: `tests/software_update.mjs`.
+
+**Settings: adopting a speciality walks through its skills (task 1004073, ADR 0310 §3)** — the owner ruled an adopted speciality's skills start OFF "and you should walk through what comes with each". So adopting one that offers skills opens `.skill-walk` inside its card: one skill per step (what it does, when to reach for it, what it costs, what it needs, who can run it), "Leave it off" / "Turn it on" at EQUAL weight (plain `.pbtn`, no accent — the default is off, so the page must not lean toward on), Back, then a recap restating each skill in a line, then ONE `PUT` of the whole set. "Finish later" saves nothing. Focus moves to each new step heading. Two things found on the way: the specialities panel shipped `hidden` and nothing ever revealed it, so adoption was unreachable from the hall; and its contract `<summary>` measured 21px once visible (now 24). **Kit:** `settings.states.json` `skills-walkthrough` + `preferences`, ALL CLEAN at 1440/390/320 × dark/light against the harness, with fixtures `specialities*.json` built from the real skills on disk and canned answers for adopt and save. Tests: `tests/speciality_walkthrough_ui.mjs` (runs the real page script).

package/modules/specialities/routes/specialities.js

@@ -401,6 +401,33 @@ module.exports = function buildSpecialitiesRouter() {
     res.json({ adoption });
   }));
 
+  // GET /specialities/:id/skills — what the adoption WALKTHROUGH shows (task
+  // 1004073, ADR 0310 §3): each skill the speciality offers, explained for the
+  // person deciding (what it does, when to reach for it, what it costs, what it
+  // needs), plus the caller's own enabled set and whether they hold it at all.
+  // Same visibility as GET /specialities/:id — 404 for a row you cannot see. An
+  // offered skill this instance no longer has comes back `installed: false`, so
+  // the walkthrough can say so instead of offering something that would 404.
+  // Read-only; rank: any builder who may see the speciality.
+  router.get('/specialities/:id/skills', api.requireBuilder, asyncHandler('GET /specialities/:id/skills', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    const installed = installedSkills();
+    const offered = Array.isArray(s.skills) ? s.skills : [];
+    const skills = offered.map((name) => (installed.has(name)
+      ? { ...skillsLib.explainSkill({ name, ...installed.get(name) }), installed: true }
+      : { name, installed: false }));
+    const mine = (await db.listAdoptions(req.builder.id)).find((a) => String(a.id) === String(id) && a.active);
+    res.json({
+      speciality: { id: s.id, name: s.name, discipline: s.discipline },
+      adopted: !!mine,
+      enabled: mine && Array.isArray(mine.enabled_skills) ? mine.enabled_skills : [],
+      skills,
+    });
+  }));
+
   // PUT /specialities/:id/skills — the caller's ENABLED set for a speciality they
   // hold (task 1004072, ADR 0310 §2). Replaces the set whole: the walkthrough
   // (task 1004073) sends the decisions it collected, so a partial patch would

package/modules/specialities/skills.js

@@ -35,29 +35,125 @@ function listDirs(dir) {
   } catch { return []; }
 }
 
-// The description line from a SKILL.md's frontmatter, for the adoption
-// walkthrough (task 1004073) to show. Flat `description: ...` only, the grammar
-// every SKILL.md here uses; anything else reads as no description.
+// The top-level keys of a SKILL.md's frontmatter, as strings (a flow list
+// `[a, b]` as an array). Enough YAML for the grammar SKILL.md files use: a flat
+// `key: value`, a quoted value, and a folded or literal block (`>-`, `>`, `|`,
+// `|-`) whose indented lines follow. Part 1 read only the flat form, and almost
+// every skill here folds its description, so each read as `>-` (task 1004073).
+// Anything it cannot read is simply absent.
+function parseFrontmatter(text) {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+  if (!fm) return {};
+  const lines = fm[1].split(/\r?\n/);
+  const out = {};
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, key, rest] = m;
+    const block = /^([>|])([+-]?)\s*$/.exec(rest);
+    if (block) {
+      const body = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === '')) body.push(lines[++i].trim());
+      out[key] = block[1] === '>'
+        ? body.join('\n').split(/\n{2,}/).map((p) => p.split('\n').join(' ')).join('\n').trim()
+        : body.join('\n').trim();
+      continue;
+    }
+    const list = /^\[(.*)\]$/.exec(rest.trim());
+    if (list) { out[key] = list[1].split(',').map((s) => s.trim().replace(/^(['"])(.*)\1$/, '$2')).filter(Boolean); continue; }
+    out[key] = rest.trim().replace(/^(['"])([\s\S]*)\1$/, '$2');
+  }
+  return out;
+}
+
+function readFrontmatter(skillMd) {
+  try { return parseFrontmatter(fs.readFileSync(skillMd, 'utf8')); } catch { return {}; }
+}
+
+// The description a SKILL.md gives, for the adoption walkthrough (task 1004073).
 function readDescription(skillMd) {
-  try {
-    const text = fs.readFileSync(skillMd, 'utf8');
-    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
-    if (!fm) return '';
-    const line = fm[1].split(/\r?\n/).find((l) => /^description:\s*/.test(l));
-    if (!line) return '';
-    return line.replace(/^description:\s*/, '').replace(/^(['"])([\s\S]*)\1$/, '$2').trim();
-  } catch { return ''; }
+  const d = readFrontmatter(skillMd).description;
+  return typeof d === 'string' ? d : '';
 }
 
+// The optional PEOPLE-FACING fields (task 1004073). `description` is written to
+// be MATCHED by a model, so a skill's author may also say, for the person
+// deciding whether to turn it on: what it does (`plain`), when to reach for it
+// (`reach-for`) and what it costs (`cost`). Claude Code ignores keys it does not
+// know, as it already does `requires:`.
+const PEOPLE_KEYS = { plain: 'plain', 'reach-for': 'reachFor', cost: 'cost' };
+
 function collect(out, dir, source) {
   for (const name of listDirs(dir)) {
     if (!SKILL_NAME_RE.test(name) || out.has(name)) continue;
     const md = path.join(dir, name, 'SKILL.md');
     if (!fs.existsSync(md)) continue;
-    out.set(name, { name, description: readDescription(md), source });
+    const fm = readFrontmatter(md);
+    const entry = { name, description: typeof fm.description === 'string' ? fm.description : '', source };
+    for (const [key, field] of Object.entries(PEOPLE_KEYS)) if (typeof fm[key] === 'string' && fm[key]) entry[field] = fm[key];
+    if (Array.isArray(fm.requires) && fm.requires.length) entry.requires = fm.requires;
+    out.set(name, entry);
   }
 }
 
+// ONE SKILL, AS A PERSON DECIDING ABOUT IT READS IT (task 1004073; ADR 0310 §3:
+// "what it does, when its author reaches for it, what it costs"). Pure: takes an
+// installedSkills() entry and returns the three answers plus what the skill
+// needs. An author's own people-facing field always wins; without one each
+// answer is derived from the model-facing description, and `derived` says so,
+// so the walkthrough can be honest that the words were not written for them.
+//
+// The rank note is kept apart on purpose: enabling a skill GRANTS NOTHING
+// (ADR 0310 §1), so a Metic-only skill stays Metic-only after you turn it on,
+// and the person should be told that before they choose it, not after.
+function explainSkill(entry) {
+  const e = entry || {};
+  const desc = String(e.description || '').replace(/\s+/g, ' ').trim();
+  const cut = desc.search(/\bTriggers?:/i);
+  let does = (cut >= 0 ? desc.slice(0, cut) : desc).trim();
+  const triggers = cut >= 0 ? desc.slice(cut).replace(/^Triggers?:\s*/i, '') : '';
+
+  const rankMatch = /\b(Metic\+|Archon)[- ]only\b\.?/i.exec(does);
+  const rank = rankMatch ? (/archon/i.test(rankMatch[1]) ? 'archon' : 'metic') : null;
+  if (rankMatch) does = does.replace(rankMatch[0], '').replace(/\s{2,}/g, ' ').trim();
+
+  const quoted = [...triggers.matchAll(/"([^"]+)"/g)].map((m) => m[1].trim());
+  const commands = quoted.filter((q) => q.startsWith('/'));
+  const phrases = quoted.filter((q) => !q.startsWith('/'));
+  const otherwise = /\bor\s+(?!")([^"]+?)\.?$/i.exec(triggers);
+
+  let reachFor = e.reachFor || '';
+  if (!reachFor && (phrases.length || otherwise)) {
+    const said = phrases.slice(0, 3).map((p) => `“${p}”`).join(', ');
+    reachFor = [said && `When you would say something like ${said}`, otherwise && otherwise[1].trim()]
+      .filter(Boolean).join(' — or ');
+    reachFor = reachFor.charAt(0).toUpperCase() + reachFor.slice(1);
+    if (!/[.!?]$/.test(reachFor)) reachFor += '.';
+  }
+
+  let cost = e.cost || '';
+  if (!cost) {
+    const readOnly = /\bread-only\b|\bchanges nothing\b/i.test(desc);
+    const paid = /\bpaid\b/i.test(desc);
+    if (readOnly && paid) cost = 'Read-only as it normally runs, but its author flags a paid option — check before you use that one. Otherwise it uses your session like any other request.';
+    else if (readOnly) cost = 'Read-only: it looks things up and changes nothing. It uses your session like any other request.';
+    else if (paid) cost = 'Has a paid step — its author flags one in the description. Otherwise it uses your session like any other request.';
+    else cost = 'Its author has not written down what it costs. Running it uses your session like any other request.';
+  }
+
+  return {
+    name: e.name,
+    source: e.source || null,
+    does: e.plain || does,
+    reachFor,
+    cost,
+    commands,
+    needs: Array.isArray(e.requires) ? e.requires : [],
+    rank,
+    derived: { does: !e.plain, reachFor: !e.reachFor, cost: !e.cost },
+  };
+}
+
 /**
  * The skills this instance has: Map name -> { name, description, source }.
  * First root wins on a duplicate name (core, then instance, then modules), the
@@ -91,4 +187,4 @@ function installedSkillsCached(opts, now = Date.now()) {
 }
 function _resetCache() { cached = null; }
 
-module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, _resetCache };
+module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, parseFrontmatter, explainSkill, _resetCache };

package/modules/specialities/specialities.js

@@ -18,8 +18,10 @@
 //                                  OFFERS skills (`skills`), each adopter's ENABLED set
 //                                  starts empty (`enabled_skills`), and only a skill this
 //                                  instance has may be named (skills.js). The walkthrough
-//                                  that fills the enabled set is task 1004073; the session
-//                                  line naming it is task 1004074. Naming a skill grants
+//                                  that fills the enabled set was built in task 1004073
+//                                  (GET /specialities/:id/skills + the hall's settings
+//                                  panel); the session line naming it is task 1004074.
+//                                  Naming a skill grants
 //                                  nothing.
 // The genuinely new part is the knowledge bundle, which is why the migration adds
 // tables for it and this file carries the rules over them.

package/package-lock.json

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

package/package.json

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

@@ -8052,5 +8052,17 @@
       "id": "1003631",
       "text": "Closed a small consistency gap in the hall's needs-attention inbox: one link is now escaped like all the others. No visible change."
     }
+  ],
+  "1.20.3": [
+    {
+      "id": "1004073",
+      "text": "Adopting a speciality now walks you through its skills one at a time: what each does, when you'd use it, and what it costs, and you choose on or off for each before seeing the next. Nothing is switched on unless you choose it."
+    }
+  ],
+  "1.20.4": [
+    {
+      "id": "1003418",
+      "text": "The project's automatic checks now catch any document that describes a safety check which no longer exists. On its first run it found the README still telling people their code was scanned for leaked passwords by a tool that w"
+    }
   ]
 }

package/scripts/gds/control-manifest.js

@@ -141,6 +141,15 @@ const CONTROLS = [
     wiredIn: { file: 'scripts/gds/ship-flow.js', needle: 'ship-honesty' },
     alsoExists: ['tests/ship_cannot_lie.mjs'],
   },
+  {
+    // Task 1003418 (audit A14). The manifest's own blind spot: it covers the rows
+    // someone listed. This guard derives claims from the docs instead, so a
+    // described-but-absent control reds the gate with no row to add.
+    label: 'guard: a doc cannot describe a control that does not exist (A14)',
+    file: 'scripts/gds/doc-control-claims.js',
+    wiredIn: { file: 'scripts/gds/fitness.js', needle: 'doc-control-claims' },
+    alsoExists: ['tests/doc_control_claims.mjs'],
+  },
 ];
 
 // Pure evaluation — exported for the test. deps.exists/deps.read override fs.

package/scripts/gds/doc-control-claims.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// scripts/gds/doc-control-claims.js — prose cannot describe a control that does not
+// exist (task 1003418, audit ref A14 of the 2026-08-29 security audit, goal 1000084).
+//
+// WHY. control-manifest.js exists because ADR 0022 named three controls that had
+// silently stopped existing, and it works — for the 14 controls someone remembered
+// to list. Every phantom-control finding since (A6, A13, B31, B32, the row-8 patrol
+// that read green for months while never running) was the same failure one row
+// outside that list. A hand list only catches what a person already thought of, so
+// the manifest cannot be the whole answer. This check reads the claims FROM THE DOCS:
+// a doc sentence that says an enforcement artifact does something is a claim that
+// the artifact exists, and a claim whose artifact is gone reds the gate by
+// construction, with nobody having to add a row. The README's secrets section was
+// the proof on first run: it still sent readers to a TruffleHog workflow and a
+// pre-commit hook that had not existed since the core extraction — the ADR 0022
+// finding itself, one file over.
+//
+// WHAT COUNTS AS A CLAIM, deliberately narrow:
+//   · a backticked path to an ENFORCEMENT artifact — a hook, a workflow, a script
+//     under scripts/gds or a hooks dir (CONTROL_PATH_RE);
+//   · in a sentence that uses control vocabulary — enforce, gate, guard, block,
+//     refuse, scan, patrol, audit, fail the build (CONTROL_WORDS);
+//   · and does NOT speak of it in the past — removed, retired, replaced, used to,
+//     no longer (HISTORY_WORDS). An ADR recording what was deleted is history,
+//     which is not a claim; the same path in the present tense is.
+// Superseded / deprecated / rejected / withdrawn ADRs are skipped whole, and so are
+// the dated records (session logs, audits, limitations archives), which describe a
+// moment rather than the tree.
+//
+// WHAT IT DOES NOT PROVE: that an existing artifact is WIRED. That stays the
+// manifest's job (a file present but unhooked). The two halves are complementary:
+// this one scales to every doc and asks only "is it there"; the manifest asks
+// "is it connected" for the controls that matter most.
+//
+// ALLOWLIST. A true claim this scan cannot tell from history (an accepted ADR whose
+// design was later retired by a newer ADR) is listed in ALLOW with the reason. It
+// is shrink-only in practice: an entry that no longer matches anything is itself a
+// violation, so a fixed doc cannot leave a dead exception behind to hide the next.
+//
+// Its own file for the size-ratchet reason (the doc-cli-guard.js precedent);
+// fitness.js requires it in CHECKS, and control-manifest.js lists it, so this guard
+// cannot silently stop existing either.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { trackedMarkdown } = require('./doc-cli-guard.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a doc cannot describe an enforcement control that does not exist (task 1003418)';
+
+// Two shapes: a script or workflow with its extension, OR a git hook by its bare
+// name. Hooks under .husky/, .githooks/ and scripts/hooks/ carry no extension by
+// convention, and `.husky/pre-commit` is exactly the artifact ADR 0022 lost. The
+// names are git's whole documented set (githooks(5)), not a curated few.
+const GIT_HOOK_NAMES = [
+  'applypatch-msg', 'pre-applypatch', 'post-applypatch', 'pre-commit', 'pre-merge-commit',
+  'prepare-commit-msg', 'commit-msg', 'post-commit', 'pre-rebase', 'post-checkout', 'post-merge',
+  'pre-push', 'pre-receive', 'update', 'proc-receive', 'post-receive', 'post-update',
+  'reference-transaction', 'push-to-checkout', 'pre-auto-gc', 'post-rewrite', 'sendemail-validate',
+  'fsmonitor-watchman', 'p4-changelist', 'p4-prepare-changelist', 'p4-post-changelist',
+  'p4-pre-submit', 'post-index-change',
+];
+const CONTROL_PATH_RE = new RegExp(
+  '`((?:\\.claude/hooks|\\.github/workflows|scripts/gds|scripts/hooks|\\.githooks|\\.husky)/[A-Za-z0-9_.\\-/]+?\\.(?:js|mjs|cjs|sh|yml|yaml|ps1)'
+  + `|(?:\\.husky|\\.githooks|scripts/hooks)/(?:${GIT_HOOK_NAMES.join('|')}))\``,
+  'g',
+);
+const CONTROL_WORDS = /\b(enforc\w*|gates?|gated|gating|guards?|guarded|blocks?|blocked|refuses?|refused|hard[- ]?fails?|fails? (?:the )?(?:build|ci|merge|gate)|compensating control|pre-commit|pre-push|scans?|scanned|patrol\w*|audits?)\b/i;
+const HISTORY_WORDS = /\b(removed|deleted|retired|superseded|no longer|used to|never existed|did not exist|never survived|dropped|replaced|gone|historical|legacy|formerly|renamed)\b/i;
+const INACTIVE_STATUS_RE = /^\s*\**\s*status\s*\**\s*:?\s*\**\s*:?\s*\**\s*(superseded|deprecated|rejected|withdrawn)/im;
+const SKIP_PREFIXES = ['docs/session-logs/', 'docs/audits/', 'limitations/'];
+
+// `${doc}::${artifact}` -> why this present-tense mention is not a phantom control.
+const ALLOW = new Map([
+  ['docs/adr/0025-structured-criterion-task-link.md::scripts/gds/seed-v3-tasks.js',
+    'describes the grep a session HAD to do before this ADR; a seed script, not a control'],
+  ['docs/adr/0042-builder-self-deploy-ci-auto-merge.md::.github/workflows/grade-gate.yml',
+    'the CI grader gate this ADR designed; it was armed in the grader-off variant its own Status line records, and grading runs server-side (scripts/gds/ci-grade.js)'],
+  ['docs/adr/0111-instance-hosting-provisioning-module.md::scripts/gds/box.js',
+    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
+  ['docs/adr/0150-box-first-boot-bringup-vendored-instances.md::scripts/gds/box.js',
+    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
+]);
+
+// Sentence-ish units: prose sentences, blank-line paragraphs, and list/table rows.
+function sentencesOf(src) {
+  return String(src).split(/(?<=[.!?])\s+|\n\s*\n|\n(?=\s*(?:[-*|]|\d+\.)\s)/);
+}
+
+// Pure over its deps: docs is a list of repo-relative .md paths.
+function findPhantomClaims(docs, { read, exists }) {
+  const claims = [];
+  for (const doc of docs) {
+    if (SKIP_PREFIXES.some((p) => doc.startsWith(p))) continue;
+    const src = read(doc);
+    if (src == null) continue;
+    if (INACTIVE_STATUS_RE.test(src.slice(0, 2000))) continue;
+    const seen = new Set();
+    for (const s of sentencesOf(src)) {
+      // Judge the WORDING with every code span blanked: a path's own name must not
+      // decide the tense (`gone.yml` reads as "gone", `guard.js` as "guard").
+      const prose = s.replace(/`[^`]*`/g, ' ');
+      for (const m of s.matchAll(CONTROL_PATH_RE)) {
+        const artifact = m[1];
+        if (seen.has(artifact) || exists(artifact)) continue;
+        if (!CONTROL_WORDS.test(prose) || HISTORY_WORDS.test(prose)) continue;
+        seen.add(artifact);
+        claims.push({ doc, artifact, sentence: s.replace(/\s+/g, ' ').trim().slice(0, 160) });
+      }
+    }
+  }
+  return claims;
+}
+
+function evaluate(docs, deps, allow = ALLOW) {
+  const claims = findPhantomClaims(docs, deps);
+  const hit = new Set();
+  const violations = [];
+  for (const c of claims) {
+    const key = `${c.doc}::${c.artifact}`;
+    if (allow.has(key)) { hit.add(key); continue; }
+    violations.push(`${c.doc}: names \`${c.artifact}\` as a live control, and it does not exist — "${c.sentence}"`);
+  }
+  for (const key of allow.keys()) {
+    if (!hit.has(key)) violations.push(`stale allowance: ${key} no longer matches a claim — delete it from ALLOW in scripts/gds/doc-control-claims.js`);
+  }
+  return { violations, claims };
+}
+
+const readRel = (rel) => { try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; } };
+const existsRel = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+function checkDocControlClaims({ files = null } = {}) {
+  const docs = files || trackedMarkdown();
+  // A lint that reports on nothing is worse than one that fails (docs-entropy).
+  if (!docs.length) {
+    return { name: NAME, ok: false, hardFail: true, warnings: [],
+      violations: ['scan defect — enumerated 0 tracked markdown files; a broken enumeration, not a clean result.'],
+      note: 'static scan of enforcement artifacts named in docs.' };
+  }
+  const { violations, claims } = evaluate(docs, { read: readRel, exists: existsRel });
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: violations.length
+      ? 'restore the control, correct the doc to name what really enforces it, or (for an accepted ADR a newer one retired) add an ALLOW entry saying which'
+      : `${docs.length} tracked .md file(s) scanned; every enforcement artifact named in a present-tense control sentence exists (${claims.length} allowlisted, each with its reason).`,
+  };
+}
+
+function main() {
+  const r = checkDocControlClaims();
+  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 = {
+  checkDocControlClaims, findPhantomClaims, evaluate, sentencesOf,
+  ALLOW, GIT_HOOK_NAMES, CONTROL_PATH_RE, CONTROL_WORDS, HISTORY_WORDS, INACTIVE_STATUS_RE,
+};

package/scripts/gds/fitness.js

@@ -1342,6 +1342,7 @@ const CHECKS = [
   checkGovernmentRenameIdentity, checkPrelaunchVocabulary, // 19c task 1003120 (`X`→`X` rename arrow) + 19d task 1003152 ("stealth" is the product's word) — sharing a line: this file is AT the 1,500 budget (Check 23/24 precedent below; task 1003825 buys it back)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
   require('./fitness-ratchets.js').checkQualityRatchets, // Check 20 — task 1003129: quality budgets only tighten (mechanics + knip CI step live in fitness-ratchets.js)
+  require('./doc-control-claims.js').checkDocControlClaims, // Check 37 — task 1003418 / audit A14: a doc cannot describe an enforcement control that does not exist (derived from the docs, not a hand list)
   require('./doc-cli-guard.js').checkDocNamesRealCli, // Check 22 — task 1003165 / G01: a doc that names a CLI invocation must match the real CLI
   require('./skill-preflight.js').checkOpsSkillsDeclareMachine, // Check 23 — task 1003167 / G03: an ops skill declares the machine it needs
   // Check 24 — task 1003166 / G02: no ops script hardcodes a version id. It landed

package/scripts/hall-preview/server.js

@@ -160,6 +160,10 @@ const CANNED_WRITES = [
   // sent-back lines the artboard draws render too.
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/approve$/, 'copy-desk__pages__approve.post'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/send-back$/, 'copy-desk__pages__send-back.post'],
+  // a speciality's adopt and the walkthrough's save (task 1004073), so adopting
+  // opens the skills walkthrough and its recap can save in the harness.
+  ['POST', /^specialities\/\d+\/adopt$/, 'specialities__9__adopt.post'],
+  ['PUT', /^specialities\/\d+\/skills$/, 'specialities__9__skills.put'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

package/src/bongos/module-scope-map.js

@@ -435,7 +435,7 @@ const MODULE_GLOBS = {
     'scripts/gds/skill-lint.js', 'scripts/gds/run-routine.js',
     'scripts/gds/adr-namespace.js', 'scripts/gds/baseline-staleness.js',
     'scripts/gds/category-advisory-guard.js', 'scripts/gds/client-baseurl-guard.js',
-    'scripts/gds/doc-cli-guard.js', 'scripts/gds/doc-comment-coverage.js',
+    'scripts/gds/doc-cli-guard.js', 'scripts/gds/doc-control-claims.js', 'scripts/gds/doc-comment-coverage.js',
     'scripts/gds/exec-path-guard.js', 'scripts/gds/fitness-lib.js',
     'scripts/gds/fitness-checks-error-envelope.js', 'scripts/gds/fitness-checks-identity.js',
     'scripts/gds/fitness-checks-packaging.js', 'scripts/gds/fitness-checks-route-pins.js',

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