@bongos/core 1.19.638 → 1.19.639

package/scripts/gds/role-pack-guard.js

@@ -101,6 +101,27 @@ function checkRolePacks(fsImpl = fs) {
     }
   }
 
+  // Each pack's WRITTEN-RESPONSIBILITY block must match src/role-responsibilities.js
+  // (task 1003732). It lives with the other pack assertions rather than in
+  // checkGeneratedArtifactsFresh so one check owns "the packs are correct" — and the
+  // drift matters for the same reason the missing-pack case does: the profile and
+  // the grader read the source at runtime and cannot drift, but the pack is markdown,
+  // so its copy is the only one that can — and it is the copy a SESSION is instructed
+  // by. A stale block means the project teaches one standard, shows a second on the
+  // profile, and grades against a third. Skipped when the fs is stubbed (the negative
+  // tests inject a registry that names packs this generator would not find).
+  if (fsImpl === fs) {
+    try {
+      const { plan } = require('./gen-role-responsibilities.js');
+      const { writes } = plan();
+      for (const w of writes) {
+        violations.push(`${w.rel}: the written-responsibility block is STALE against src/role-responsibilities.js — run \`node scripts/gds/gen-role-responsibilities.js\` and commit (task 1003732).`);
+      }
+    } catch (e) {
+      violations.push(`could not check the packs' written-responsibility blocks (${e && e.message}) — run \`node scripts/gds/gen-role-responsibilities.js --check\`.`);
+    }
+  }
+
   // The split's own shape, asserted so a later edit cannot quietly drop a craft
   // back into the kernel: three core packs, and Governor deliberately absent
   // (criterion wa6-kernel-and-packs — "three packs, not four, until the owner decides").

package/src/module-api.js

@@ -41,6 +41,22 @@ const instanceConfig = require('./instance-config');
 const staleTimer = require('./stale-timer');
 const seams = require('./module-seams');
 const { buildInfo } = require('./build-info');
+// Eager and DESTRUCTURED on purpose, and inside the rule above rather than an
+// exception to it: role-responsibilities.js requires NOTHING (80 lines of the
+// owner's text plus three pure lookups), so it costs one file read and drags no
+// server file into a CLI subcommand's require-closure — the same footing as
+// `branding` and `instanceConfig` here.
+//
+// It has to be a NAMED require rather than `require(...).x` read inside a getter,
+// or CI's dead-code ratchet counts these exports as dead and no PR touching them
+// can merge — task 1003732 stranded on exactly that. `responsibilityFor`'s only
+// consumer is modules/grading/grader-prompt.js reaching through this doorway, and
+// modules/ sits outside knip's `project` globs by design, so the import HERE is
+// the only place that use can be seen. knip credits a destructured binding and
+// not a member access on a namespace object, which is why the sibling exports
+// (`responsibilitiesFor` via src/modules.js, `ROLE_RESPONSIBILITIES` via
+// scripts/gds/gen-role-responsibilities.js) were never flagged and this one was.
+const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibilities');
 
 // ---------------------------------------------------------------------------
 // CORE_VERSION — the version of THIS published surface (semver).
@@ -55,7 +71,7 @@ const { buildInfo } = require('./build-info');
 // 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.638'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.639'; // 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');
@@ -405,6 +421,19 @@ module.exports = {
   get pageMeta() { return require('./bongos/routes/_helpers').pageMeta; },
   get PAGINATION() { return require('./bongos/routes/_helpers').PAGINATION; },
 
+  // --- the written role responsibilities (task 1003732, criterion
+  //     wa6-written-responsibilities). ONE source for the sentence each craft is
+  //     answerable for; it reaches modules through the doorway because more than
+  //     one module needs the same text — grading references it when judging
+  //     role-shaped work, and the hall shows it to the person being judged — and
+  //     modules never import each other. `responsibilityFor(discipline)` returns
+  //     null for a craft with no statement (a module-contributed one, or an
+  //     unclassified task); that is a legitimate answer, not an error.
+  //     Plain entries rather than getters: the module is loaded eagerly at the
+  //     top of this file (it costs nothing), so there is nothing left to defer.
+  responsibilityFor,
+  ROLE_RESPONSIBILITIES,
+
   // --- logging
   logger,
 };

package/src/modules.js

@@ -28,6 +28,7 @@ const path = require('node:path');
 // until a module is moved into modules/ — so this is a no-op on the current tree.
 const loader = require('./module-loader/loader');
 const { resolveCoreRoot, resolveInstanceRoot } = require('./instance-config');
+const { responsibilitiesFor } = require('./role-responsibilities');
 
 // ADR 0108 §1: the neutral starter ships WITH the core package; the instance
 // pack is host content. Both resolvers return the repo root today, so this is
@@ -250,10 +251,20 @@ function enabledDisciplines(set = modules()) {
 
 // CLIENT-SAFE projection — module flags are just booleans, all safe to expose.
 // The hall/status front-ends read this to hide UI sections for off modules.
+//
+// `responsibilities` rides here (task 1003732) because this projection is already
+// injected into every served page as a global (serve-internal.injectBrandingGlobal),
+// and it already carries the discipline roster the statements are keyed by — so the
+// profile gets the owner's text with no new route, no fetch, and no second copy to
+// drift. Scoped to the disciplines this instance actually offers: a craft the
+// instance does not have must not appear in its UI, and a module-contributed craft
+// has no statement by design (src/role-responsibilities.js says why).
 function clientModules(set = modules()) {
+  const disciplines = enabledDisciplines(set);
   return {
     enabled: knownModules().reduce((o, k) => { o[k] = set[k] === true; return o; }, {}),
-    disciplines: enabledDisciplines(set),
+    disciplines,
+    responsibilities: responsibilitiesFor(disciplines),
   };
 }
 

package/src/role-responsibilities.js

@@ -0,0 +1,80 @@
+// src/role-responsibilities.js
+//
+// WHAT. The one source of each craft's written responsibility — the sentence that
+// says what a person holding that role is actually answerable for. Three consumers
+// read this file and nothing else: the hall profile shows it to the person, the
+// role pack under docs/packs/ teaches a session from it, and the grader references
+// it when it judges role-shaped work.
+//
+// WHY IT IS ONE FILE. Criterion wa6-written-responsibilities (goal 1000095) is
+// explicit that there is ONE source — "shown on the profile, injected into the
+// pack, referenced by grading" — and the reason is not tidiness. The promise made
+// to a builder on their profile and the text their session is actually held to
+// must be the same text; two copies that drift mean the project judged someone
+// against a standard it never showed them. The pack half is enforced rather than
+// promised: the packs carry a GENERATED block written by
+// scripts/gds/gen-role-responsibilities.js, and fitness.js fails CI when it drifts
+// from this file (the gen-diagrams / gen-session-index pattern, ADR 0062 §8).
+//
+// THE TEXT IS THE OWNER'S, VERBATIM. Fixed by the area owner on 2026-09-08 and
+// recorded in the criterion. Do not paraphrase, tighten, or "improve" these
+// sentences — a role's responsibility is the owner's to write, and the whole point
+// of a single source is that it says what they said. Per-project sub-specialities
+// (idea 1000733) build on this later and are deliberately not modelled here.
+//
+// KERNEL FILE. On the fitness.js KERNEL_FILES roster: three different modules read
+// it (hall-ui, grading) plus the core's own client projection, and modules never
+// import each other, so shared vocabulary has to sit in the kernel. It imports
+// nothing, which is what makes that placement free.
+'use strict';
+
+// discipline key (tasks.discipline / builders.preferred_disciplines) → the owner's
+// sentence. Keys mirror CORE_DISCIPLINES order (engineer | artist | ideator), the
+// migration 176 enum order. A module-contributed discipline (ui-design → 'ui') has
+// no statement here on purpose: a craft a module brings is that module's to
+// describe, and inventing one for it would be exactly the paraphrase this file
+// forbids. Consumers must therefore treat "no statement" as normal, not as an error.
+const ROLE_RESPONSIBILITIES = Object.freeze({
+  engineer: 'Running and optimizing the running of Claude nonstop, and ensuring Ideators and Artists can continue to interface with that system effectively.',
+  artist: 'No slop in the appearance and text of the project; the story, emotion and ideology of the project are communicated effectively; project purpose and gravitas are upheld.',
+  ideator: 'Make good ideas; be a philosopher / thought leader for the project; enable Engineers to scope and Artists to create with maximum efficiency — a baseline for creating scopes of work.',
+});
+
+// Provenance, carried with the text so every rendering can say where it came from
+// rather than looking like a platform opinion someone typed.
+const RESPONSIBILITIES_SOURCE = Object.freeze({
+  criterion: 'wa6-written-responsibilities',
+  goalId: '1000095',
+  authoredOn: '2026-09-08',
+  authoredBy: 'the area owner',
+});
+
+// The statement for one discipline, or null when the craft has none (a
+// module-contributed discipline, an unclassified task, a stray value from an older
+// row). Null is a legitimate answer every consumer must render as absence — never
+// as a blank quote or a placeholder sentence.
+function responsibilityFor(discipline) {
+  if (typeof discipline !== 'string') return null;
+  return ROLE_RESPONSIBILITIES[discipline.toLowerCase()] || null;
+}
+
+// The subset of statements an instance actually offers, so a client projection
+// never ships a craft the instance does not have. Takes the discipline roster the
+// caller already resolved (modules.enabledDisciplines()) rather than reaching for
+// the module registry itself — that would make this file import domain and cost it
+// its place on the kernel roster.
+function responsibilitiesFor(disciplines) {
+  const out = {};
+  for (const d of Array.isArray(disciplines) ? disciplines : []) {
+    const text = responsibilityFor(d);
+    if (text) out[d] = text;
+  }
+  return out;
+}
+
+module.exports = {
+  ROLE_RESPONSIBILITIES,
+  RESPONSIBILITIES_SOURCE,
+  responsibilityFor,
+  responsibilitiesFor,
+};

package/tests/module_api.mjs

@@ -46,6 +46,7 @@ const PUBLISHED_SURFACE = [
   'contribute', 'contributions', 'collectContributions', 'listContributionPoints',
   'buildInfo', 'validateOrRespond', 'LIMITS', 'parseId', 'asyncHandler', 'corsPublicGet', // parseId added 1.8.0 (BV1.R78); asyncHandler + corsPublicGet added 1.12.0 (BV1.R86; lifecycle routes)
   'parsePagination', 'pageMeta', 'PAGINATION', // R14 (#2001, 1.17.0): shared pagination contract for module list routes (ADR 0119)
+  'responsibilityFor', 'ROLE_RESPONSIBILITIES', // added by task 1003732 (ADR 0275; criterion wa6-written-responsibilities): the ONE source for the sentence each craft is answerable for. It rides the doorway because two modules need the same text — grading judges role-shaped work against it, the hall shows it to the person being judged — and modules never import each other. Declared here deliberately: this list is what makes adding to the doorway a decision rather than a side effect
   'logger',
 ];
 

package/tests/role_responsibilities.mjs

@@ -0,0 +1,187 @@
+// tests/role_responsibilities.mjs
+//
+// task 1003732 (goal 1000095, criterion wa6-written-responsibilities) — the three
+// written role responsibilities land as ONE source with three consumers.
+//
+// WHAT IS WORTH PINNING HERE. The criterion's whole content is "one source, shown
+// on the profile, injected into the pack, referenced by grading". So the failure to
+// guard against is not a typo — it is a SECOND COPY. If the packs, the hall and the
+// grader can each hold their own wording, the project can show a builder one
+// standard and judge them by another, which is the specific unfairness the single
+// source exists to prevent. Every test below is a leg of that.
+//
+// The text itself is the owner's, verbatim (fixed 2026-09-08). It is asserted here
+// character-for-character on purpose: a well-meaning tidy-up of someone else's
+// authored sentence is exactly the drift this task forbids, and a test is the only
+// thing that makes "do not paraphrase" survive contact with a future editor.
+//
+// Run:  node tests/role_responsibilities.mjs
+
+import { strict as assert } from 'node:assert';
+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 src = require(path.join(ROOT, 'src', 'role-responsibilities.js'));
+const modules = require(path.join(ROOT, 'src', 'modules.js'));
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+const gen = require(path.join(ROOT, 'scripts', 'gds', 'gen-role-responsibilities.js'));
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// --- the source ---------------------------------------------------------
+
+// The owner's sentences, verbatim from criterion wa6-written-responsibilities.
+// Duplicated here deliberately — a test that read the value it is checking would
+// assert nothing. This copy is the fixture; the source file is the subject.
+const OWNER_TEXT = {
+  engineer: 'Running and optimizing the running of Claude nonstop, and ensuring Ideators and Artists can continue to interface with that system effectively.',
+  artist: 'No slop in the appearance and text of the project; the story, emotion and ideology of the project are communicated effectively; project purpose and gravitas are upheld.',
+  ideator: 'Make good ideas; be a philosopher / thought leader for the project; enable Engineers to scope and Artists to create with maximum efficiency — a baseline for creating scopes of work.',
+};
+
+test('the three statements are the owner\'s text, character for character', () => {
+  assert.deepEqual({ ...src.ROLE_RESPONSIBILITIES }, OWNER_TEXT);
+});
+
+test('exactly the three CORE crafts carry a statement — no more, no fewer', () => {
+  assert.deepEqual(Object.keys(src.ROLE_RESPONSIBILITIES), ['engineer', 'artist', 'ideator']);
+  // Governor is deferred (ADR 0274) and `ui` is module-contributed (ADR 0272):
+  // inventing a sentence for either is the paraphrase this task forbids.
+  assert.equal(src.responsibilityFor('ui'), null);
+  assert.equal(src.responsibilityFor('governor'), null);
+});
+
+test('the map is frozen — a consumer cannot edit the standard at runtime', () => {
+  assert.ok(Object.isFrozen(src.ROLE_RESPONSIBILITIES));
+});
+
+test('responsibilityFor: case-insensitive, and absence is null not a placeholder', () => {
+  assert.equal(src.responsibilityFor('ENGINEER'), OWNER_TEXT.engineer);
+  for (const bad of [null, undefined, '', 'unclassified', 42, {}]) {
+    assert.equal(src.responsibilityFor(bad), null, `${JSON.stringify(bad)} must be null`);
+  }
+});
+
+test('responsibilitiesFor scopes to the disciplines an instance offers', () => {
+  assert.deepEqual(src.responsibilitiesFor(['artist', 'ui']), { artist: OWNER_TEXT.artist });
+  assert.deepEqual(src.responsibilitiesFor([]), {});
+  assert.deepEqual(src.responsibilitiesFor(null), {});
+});
+
+// --- consumer 1: the hall (via the injected client projection) ----------
+
+test('clientModules carries the statements for the offered crafts only', () => {
+  const c = modules.clientModules();
+  for (const d of Object.keys(c.responsibilities)) {
+    assert.ok(c.disciplines.includes(d), `${d} is offered a statement but is not an offered discipline`);
+    assert.equal(c.responsibilities[d], OWNER_TEXT[d], `${d}: the projection must not reword the source`);
+  }
+  // `ui` is offered by the ui-design module but has no statement — the projection
+  // must carry the craft without inventing a standard for it.
+  if (c.disciplines.includes('ui')) assert.equal(c.responsibilities.ui, undefined);
+});
+
+// --- consumer 2: the grader (via the module doorway) --------------------
+
+test('the doorway exposes it, so a module never deep-requires the source', () => {
+  assert.equal(api.responsibilityFor('artist'), OWNER_TEXT.artist);
+  assert.deepEqual({ ...api.ROLE_RESPONSIBILITIES }, OWNER_TEXT);
+});
+
+test('the grader prompt states the standard for a craft, and stays silent without one', () => {
+  const { buildPrompt } = require(path.join(ROOT, 'modules', 'grading', 'grader-prompt.js'));
+  const build = (discipline) => buildPrompt({
+    task: { id: 1, title: 't', kind: 'feature', discipline },
+    valueSummary: 'v', changedFiles: ['a.js'], diff: 'x',
+  });
+  assert.ok(build('artist').includes(OWNER_TEXT.artist), 'the artist statement must reach the prompt verbatim');
+  // A craft with no written standard must not get an invented one — a grader told
+  // "this role has no standard" would supply its own.
+  for (const d of ['ui', 'unclassified', undefined]) {
+    assert.ok(!build(d).includes('What this craft is answerable for'), `${d} must add no responsibility line`);
+  }
+});
+
+// --- consumer 3: the packs (generated, so they cannot drift) ------------
+
+test('every pack the registry names carries the block, matching the source', () => {
+  const { writes, warnings } = gen.plan();
+  assert.deepEqual(writes.map((w) => w.rel), [], `a pack block is stale: ${writes.map((w) => w.rel).join(', ')}`);
+  assert.deepEqual(warnings, [], `every registered pack must carry the marker pair: ${warnings.join(' | ')}`);
+});
+
+test('the block carries the statement verbatim and says it is generated', () => {
+  for (const t of gen.packTargets()) {
+    const text = fs.readFileSync(t.abs, 'utf8');
+    const expected = OWNER_TEXT[t.discipline];
+    if (!expected) continue;
+    assert.ok(text.includes(expected), `${t.rel} must quote the ${t.discipline} statement verbatim`);
+    assert.ok(text.includes(gen.BEGIN) && text.includes(gen.END), `${t.rel} must keep the marker pair`);
+    assert.ok(/do not hand-edit/i.test(text), `${t.rel} must warn that the block is generated`);
+  }
+});
+
+test('the generator is idempotent and preserves a CRLF pack\'s line endings', () => {
+  // The packs are .md: CRLF on a Windows checkout, LF in CI. A generator that
+  // always wrote '\n' would make the committed bytes platform-dependent, so the
+  // freshness gate would be red on one checkout and green on the other.
+  const block = gen.blockFor('artist');
+  const crlf = `head\r\n${gen.BEGIN}\r\nstale\r\n${gen.END}\r\ntail\r\n`;
+  const out = gen.inject(crlf, block);
+  assert.ok(!/[^\r]\n/.test(out), 'a CRLF file must stay pure CRLF');
+  assert.equal(gen.inject(out, block), out, 'a second pass must change nothing');
+
+  const lf = `head\n${gen.BEGIN}\nstale\n${gen.END}\ntail\n`;
+  const outLf = gen.inject(lf, block);
+  assert.ok(!outLf.includes('\r'), 'an LF file must stay pure LF');
+  assert.equal(gen.inject(outLf, block), outLf, 'a second pass must change nothing');
+});
+
+test('a pack with no markers is reported, never silently skipped', () => {
+  assert.equal(gen.inject('no markers here', gen.blockFor('artist')), null);
+});
+
+// --- the whole point: there is no second copy ---------------------------
+
+test('no consumer hardcodes a statement — the packs\' generated blocks are the only copies', () => {
+  // Anything that repeats a statement outside the source, its generated blocks, the
+  // criterion record, or this fixture is a second copy that can drift.
+  const ALLOWED = new Set([
+    'src/role-responsibilities.js',   // the source
+    'docs/packs/engineer.md',         // generated blocks
+    'docs/packs/artist.md',
+    'docs/packs/ideator.md',
+    'tests/role_responsibilities.mjs', // this fixture
+  ]);
+  const scan = ['src', 'scripts', 'modules', 'tests', 'docs/packs'];
+  const offenders = [];
+  const walk = (dir) => {
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(ROOT, dir), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const rel = `${dir}/${e.name}`;
+      if (e.isDirectory()) { if (e.name !== 'node_modules') walk(rel); continue; }
+      if (!/\.(js|mjs|md|json|html)$/.test(e.name)) continue;
+      if (ALLOWED.has(rel)) continue;
+      let text;
+      try { text = fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { continue; }
+      for (const [craft, sentence] of Object.entries(OWNER_TEXT)) {
+        if (text.includes(sentence)) offenders.push(`${rel} repeats the ${craft} statement`);
+      }
+    }
+  };
+  for (const d of scan) walk(d);
+  assert.deepEqual(offenders, [], `a second copy can drift from the source:\n  ${offenders.join('\n  ')}`);
+});
+
+console.log(`\nrole_responsibilities: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);