@bongos/core 1.19.697 → 1.19.698

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.697",
-  "core_contract": "1.19.697",
-  "source_commit": "bfb9b4492d0f0057725db35914055204f148c032",
+  "core_version": "1.19.698",
+  "core_contract": "1.19.698",
+  "source_commit": "8fb86a2225d9ed2a99fe253ea3886c7b2e7bcfc9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T02:32:59.182Z",
+  "built_at": "2026-09-13T02:48:21.644Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2627,
-  "tree_sha256": "aecd13ccb73fd1082fe45b3aa23bab026afc2c358c584c4e188cb8caafcc1199",
+  "tree_sha256": "53de7b22ab854dd4a788f5ce3827fca83328bb1f43e0415eae9528923e68596b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8862b2feb53917b00597c8a2a32d75fedbbe24cdb78c12998209f9de39395c15"
+      "sha256": "5c48de96a5d2d3ed794c4f503a665f0c4defc7d06f384ba4012eeb02cf3036aa"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4267,7 +4267,7 @@
     {
       "path": "modules/dev-box/box-access.js",
       "mode": "0000644",
-      "sha256": "7bc7c746f2518cb465773a205c8e9fe7efc30852c857001255be92ad8e340bca"
+      "sha256": "7271dc2c3eab6c8ed274dc90f855ec813eef4e401180a300e31de31dce30aa6c"
     },
     {
       "path": "modules/dev-box/box-credential.js",
@@ -7772,12 +7772,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b8fa92bf72071648e7a68331fcd48c316d5f42b4dd22ac58de8c69fa91cdbefb"
+      "sha256": "0faabe7f40491c6ab374488d6ae4a244694e1fbf40c280ad98ef0a249c207b80"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1c2dd79228c1d4d99779ed0526734e6f75a68e40026db6665e800862b95cccc5"
+      "sha256": "f623a28e95671e15f28bc19bc1b29f26f00312c5f0dc5e8761b872dd42e85923"
     },
     {
       "path": "public-docs/index.html",
@@ -8072,7 +8072,7 @@
     {
       "path": "scripts/gds/context-pack.js",
       "mode": "0000644",
-      "sha256": "caa5dd1628b00569a5593964f1831641ac12c9a85b8ec132964a1baf67c77350"
+      "sha256": "7863284f9d81a9cf77a5d01cff82d119207637090f9ef14012c8689625e93a49"
     },
     {
       "path": "scripts/gds/control-manifest.js",
@@ -9542,7 +9542,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "aceceda426abd1aa9dd04fdfc69a225e7b33a91b790a823cf10d206698f24c1e"
+      "sha256": "f03b116eece1a5517cda1bf812627f7148aaf2827806d53d70f3b67d343026ab"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9922,7 +9922,7 @@
     {
       "path": "tests/box_access.mjs",
       "mode": "0000644",
-      "sha256": "911a764f72976298daa17855acb836d0ada3215b480961ae8607e1fc3634f882"
+      "sha256": "85b0f479d16d53eea0442cab9ea8aa2dd09d95926765b47a142c609af22f6927"
     },
     {
       "path": "tests/box_auth_check.mjs",
@@ -10232,7 +10232,7 @@
     {
       "path": "tests/context_pack.mjs",
       "mode": "0000644",
-      "sha256": "09f956c01f169ab7384204a5d43deefa3e57a7d57924072dfa8215f0942c2513"
+      "sha256": "159661396a274740d9164dce8532b54e283ead733301c841078334033784d04f"
     },
     {
       "path": "tests/control_manifest.mjs",

package/docs/module-api-changelog.md

@@ -1853,5 +1853,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.695 with no explicit bump. run 34733145358. (task 1002620)
   1.19.697 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.696 with no explicit bump. run 34733301156. (task 1002620)
+  1.19.698 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.697 with no explicit bump. run 34733917938. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/box-access.js

@@ -178,6 +178,24 @@ const BASE_SPARSE_PATHS = [
   // config/government.json) is host content the box's own builder authors — no
   // credentials live here (ADR 0022); those are in /etc and the box env.
   'config',
+  // modules/lifecycle — task 1003085. BASE's whole charter is "enough to run the
+  // /builder-* CLI", and the CLI does not run without this module:
+  // scripts/gds/context-pack.js reads the task enums from
+  // modules/lifecycle/task-classifier, and context-pack is on the /builder-start
+  // AND /builder-claim paths. On a task-scoped box with NO active claim nothing
+  // put lifecycle in scope, so both commands died at import with MODULE_NOT_FOUND
+  // — and neither could be used to fix it, because a CLAIM is what fetches the
+  // module. The only way out was POST /claims by hand.
+  //
+  // This is the structural half; context-pack.js also degrades now if the module
+  // is absent for any OTHER reason. Both, deliberately: the degrade keeps the CLI
+  // alive against a future module gap, and this line is what makes the pack
+  // actually COMPLETE on every box rather than quietly reduced.
+  //
+  // Same posture as the entries above — core-domain work-tracking code, which is
+  // methodology and not product runtime, so it belongs in BASE by the same reading
+  // that put scripts/ and src/bongos/ here. No secrets; a cone-mode directory.
+  'modules/lifecycle',
 ];
 
 // sparsePathsForScopeKeys — PURE. Given the module KEYS a builder's active claims

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.697",
+  "version": "1.19.698",
   "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/scripts/gds/context-pack.js

@@ -30,11 +30,30 @@ const path = require('node:path');
 // The live validators. task-classifier is a pure module (no DB, no network),
 // so importing it from a CLI is safe — same precedent as next-number.js reading
 // the repo tree directly. This is the "not hand-maintained" guarantee.
-const {
-  VALID_KINDS,
-  VALID_DISCIPLINES,
-  TASK_FIELD_BOUNDS,
-} = require('../../modules/lifecycle/task-classifier');
+//
+// OPTIONAL, because the file may not be ON DISK (task 1003085). A task-scoped box
+// (ADR 0148) materializes modules/<key> only for the modules the CLAIM puts in
+// scope, so on a box with NO active claim modules/lifecycle is absent and this
+// require threw MODULE_NOT_FOUND at import time. That killed /builder-start AND
+// /builder-claim — the exact two commands needed to escape the state, since the
+// claim is what would fetch the module. A deadlock, escapable only by calling
+// POST /claims with curl. The header's FAIL-OPEN promise ("must NEVER throw or
+// block a claim") was already the right rule; this require was the line that did
+// not keep it.
+//
+// Degrade by OMITTING the enums, NEVER by hard-coding a copy. A local list of
+// kinds is precisely the drift the "generated from the live validators" design
+// exists to prevent, and it would be WORSE than absence: absence costs the
+// planner one /docs lookup, while a stale list reads as authoritative and is
+// discovered only when POST /tasks rejects it — the guess-and-retry turn this
+// whole pack was built to save.
+let classifier = null;
+try {
+  // eslint-disable-next-line global-require
+  classifier = require('../../modules/lifecycle/task-classifier');
+} catch (_) {
+  // Not materialized on this box. apiContract() reports it honestly below.
+}
 
 // Single source of truth for the API prefix (src/bongos/api-prefix.js) so the URL
 // rename (Part B) flips one constant and this pack follows. Importing a pure src
@@ -46,17 +65,31 @@ const { API_PREFIX } = require('../../src/bongos/api-prefix');
 // The API contract a planner needs to file/claim without guessing. 'unclassified'
 // is dropped from both enums: it's the classifier's fallback bucket, never a
 // value a human should pick.
+//
+// The SHAPE is the same either way — empty arrays and null bounds, never missing
+// keys — because every consumer here and in start.js reads these fields
+// positionally. Returning a short object instead would move the crash from the
+// require to the formatter and fix nothing. `enums_available` is what the
+// formatters branch on, so "we don't know" is said once, in words, rather than
+// rendered as an empty list that looks like "there are none".
 function apiContract() {
-  const kinds = [...VALID_KINDS].filter((k) => k !== 'unclassified');
-  const disciplines = [...VALID_DISCIPLINES].filter((d) => d !== 'unclassified');
-  return {
+  const base = {
     api_prefix: API_PREFIX,
     docs_url: '/docs',
     openapi_url: '/docs/openapi.json',
-    task_kinds: kinds,
-    disciplines,
-    priority: TASK_FIELD_BOUNDS.priority,
-    manual_degree: TASK_FIELD_BOUNDS.manual_degree,
+    enums_available: Boolean(classifier),
+    task_kinds: [],
+    disciplines: [],
+    priority: null,
+    manual_degree: null,
+  };
+  if (!classifier) return base;
+  return {
+    ...base,
+    task_kinds: [...classifier.VALID_KINDS].filter((k) => k !== 'unclassified'),
+    disciplines: [...classifier.VALID_DISCIPLINES].filter((d) => d !== 'unclassified'),
+    priority: classifier.TASK_FIELD_BOUNDS.priority,
+    manual_degree: classifier.TASK_FIELD_BOUNDS.manual_degree,
   };
 }
 
@@ -212,13 +245,20 @@ function formatContextPack(pack) {
   lines.push(`  Held claims:    ${formatClaims(claims)}`);
   lines.push(`  API prefix:     ${api.api_prefix}   (e.g. POST ${api.api_prefix}/tasks, GET ${api.api_prefix}/me)`);
   lines.push(`  API reference:  ${api.docs_url} (rendered) · ${api.openapi_url} (OpenAPI 3.1)`);
-  lines.push(`  Task kinds:     ${api.task_kinds.join(', ')}`);
-  lines.push(`  Disciplines:    ${api.disciplines.join(', ')}`);
-  const conv = api.priority.convention;
-  lines.push(
-    `  Numeric fields: priority int ${api.priority.min}–${api.priority.max} ` +
-    `(use ${conv.label}) · manual_degree int ${api.manual_degree.min}–${api.manual_degree.max}`
-  );
+  if (api.enums_available) {
+    lines.push(`  Task kinds:     ${api.task_kinds.join(', ')}`);
+    lines.push(`  Disciplines:    ${api.disciplines.join(', ')}`);
+    const conv = api.priority.convention;
+    lines.push(
+      `  Numeric fields: priority int ${api.priority.min}–${api.priority.max} ` +
+      `(use ${conv.label}) · manual_degree int ${api.manual_degree.min}–${api.manual_degree.max}`
+    );
+  } else {
+    // Say WHY and WHERE to look. The one thing this line must not do is imply the
+    // enums are empty — a planner who reads "kinds:" with nothing after it will
+    // invent one.
+    lines.push(`  Task kinds:     unavailable here — modules/lifecycle is not on this box; see ${api.docs_url}`);
+  }
   lines.push(`  OS:             ${formatOs(os)}`);
   return lines.join('\n');
 }
@@ -230,7 +270,9 @@ function formatContextPack(pack) {
 // noise beyond the shared compass.
 function formatContextPackCompact(pack) {
   const { worktree, api } = pack;
-  const kinds = api.task_kinds.slice(0, 4).join(', ') + (api.task_kinds.length > 4 ? ', …' : '');
+  const kinds = api.enums_available
+    ? api.task_kinds.slice(0, 4).join(', ') + (api.task_kinds.length > 4 ? ', …' : '')
+    : `see ${api.docs_url}`;
   return [
     `🧭 Worktree: ${worktree.root}  (edit + git here, not the main checkout)`,
     `   API ${api.api_prefix} · kinds: ${kinds} · full pack on /builder-claim`,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.697'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.698'; // 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');

package/tests/box_access.mjs

@@ -196,7 +196,12 @@ console.log('\nBASE_SPARSE_PATHS — the non-product base a task-scoped box laye
 t('BASE carries the methodology + tooling, NOT the product/game', () => {
   // clients/ is load-bearing: cli-lib.js hard-imports clients/bongos-client, so a
   // cone without it has a fully dead builder CLI on the box (task 1002745).
-  for (const p of ['.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra', 'tests', 'clients']) {
+  // modules/lifecycle is load-bearing for the same reason (task 1003085):
+  // scripts/gds/context-pack.js reads the task enums from its task-classifier,
+  // and context-pack sits on BOTH /builder-start and /builder-claim. A box with
+  // no active claim put nothing in scope, so both commands died at import — and
+  // neither could fix it, because a CLAIM is what fetches the module.
+  for (const p of ['.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra', 'tests', 'clients', 'modules/lifecycle']) {
     assert.ok(BASE.includes(p), `BASE must include ${p}`);
   }
   for (const p of ['src/world', 'src/rooms', 'public', 'art', 'modules/status-ui']) {

package/tests/context_pack.mjs

@@ -339,5 +339,85 @@ t('formatContextPackCompact: two lines, worktree + prefix, no undefined', () =>
   assert.ok(!/undefined/.test(out));
 });
 
+// ---- the task-scoped box with no claim (task 1003085) ----------------------
+//
+// A box scoped to a claim materializes modules/<key> only for the modules that
+// claim put in scope (ADR 0148). With NO active claim, modules/lifecycle is not
+// on disk — and this file's hard `require` of task-classifier threw
+// MODULE_NOT_FOUND at IMPORT time, which killed /builder-start and
+// /builder-claim: the two commands needed to escape the state, because a claim
+// is what fetches the module. The live escape was POST /claims by curl.
+//
+// This reproduces the condition for real rather than asserting on source text:
+// a temp tree holding context-pack.js and the one other thing it imports, with
+// NO modules/ directory at all. A regression re-introducing a bare top-level
+// require fails here at `require(...)`, before any assertion runs.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const url = require('node:url');
+
+function boxWithoutLifecycle() {
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ctxpack-nolifecycle-'));
+  fs.mkdirSync(path.join(root, 'scripts', 'gds'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'src', 'bongos'), { recursive: true });
+  fs.copyFileSync(path.join(here, '..', 'scripts', 'gds', 'context-pack.js'),
+    path.join(root, 'scripts', 'gds', 'context-pack.js'));
+  // The ONLY other import. Deliberately copied rather than stubbed: if
+  // context-pack grows a second hard dependency, this test fails and that new
+  // coupling has to be looked at — which is the point.
+  fs.copyFileSync(path.join(here, '..', 'src', 'bongos', 'api-prefix.js'),
+    path.join(root, 'src', 'bongos', 'api-prefix.js'));
+  // No modules/ — that IS the box condition.
+  assert.ok(!fs.existsSync(path.join(root, 'modules')), 'the fixture must not carry modules/');
+  return { root, mod: require(path.join(root, 'scripts', 'gds', 'context-pack.js')) };
+}
+
+t('a box with no modules/lifecycle can still LOAD the pack (the deadlock)', () => {
+  const { mod } = boxWithoutLifecycle();
+  const api = mod.apiContract();
+  assert.equal(api.enums_available, false, 'it must say so, not pretend');
+  assert.equal(api.api_prefix, '/api/bongos', 'everything not behind the module still works');
+  // Shape preserved, so every positional consumer survives.
+  assert.deepEqual(api.task_kinds, []);
+  assert.deepEqual(api.disciplines, []);
+  assert.equal(api.priority, null);
+  assert.equal(api.manual_degree, null);
+});
+
+t('both formatters render on that box instead of throwing', () => {
+  const { mod } = boxWithoutLifecycle();
+  const pack = mod.buildContextPack({
+    activeClaims: [], cwd: '/fallback', platform: 'linux',
+    runGit: () => '/work/tree\n', runWhich: () => '',
+  });
+  // The crash this moves is subtle: omitting the keys instead of emptying them
+  // would just relocate the failure from the require to `api.priority.convention`
+  // here — still a dead CLI, one stack frame later.
+  const full = mod.formatContextPack(pack);
+  assert.ok(!/undefined/.test(full), 'no undefined leaks into the pack');
+  assert.match(full, /unavailable here/, 'it names the gap');
+  assert.match(full, /\/docs/, 'and says where the real answer is');
+  assert.doesNotMatch(full, /Task kinds: {5}$/m, 'never an EMPTY kinds line — that reads as "there are none"');
+  const compact = mod.formatContextPackCompact(pack);
+  assert.equal(compact.split('\n').length, 2);
+  assert.ok(!/undefined/.test(compact));
+});
+
+t('with the module present the enums are still the LIVE ones, not a local copy', () => {
+  // The guard on the fix: degrading must not have introduced a hand-maintained
+  // fallback list. This is the original design promise, re-pinned against the
+  // new code path.
+  const api = apiContract();
+  assert.equal(api.enums_available, true);
+  const live = require('../modules/lifecycle/task-classifier');
+  assert.deepEqual(api.task_kinds, [...live.VALID_KINDS].filter((k) => k !== 'unclassified'));
+  assert.deepEqual(api.disciplines, [...live.VALID_DISCIPLINES].filter((d) => d !== 'unclassified'));
+  const src = fs.readFileSync(new URL('../scripts/gds/context-pack.js', import.meta.url), 'utf8');
+  assert.doesNotMatch(src, /'(bug|feature|chore|cleanup|verify)'\s*,\s*'/,
+    'a literal kind list in this file is the drift the generated design exists to prevent');
+});
+
 console.log(`\ncontext_pack: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);