@bongos/core 1.19.1001 → 1.19.1003

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1001",
-  "core_contract": "1.19.1001",
-  "source_commit": "e3841cdcf855bc3c78235929cb9b991fe6771293",
+  "core_version": "1.19.1003",
+  "core_contract": "1.19.1003",
+  "source_commit": "145db63a197eedb2b567473f622e1b208dc0fe00",
   "source_ref": "HEAD",
-  "built_at": "2026-09-24T14:59:23.930Z",
+  "built_at": "2026-09-24T15:36:25.098Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 521,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2957,
-  "tree_sha256": "316e3f355b647effab194c60ce7bd7be3e67446b6c021d7bf3c163987ac4a2a6",
+  "tree_sha256": "30960b9b7c273ac36ba63d380f5b2c8f31e832f5f702f57215ca4e9c27f50db2",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2722,7 +2722,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "9c37bc89b41410876a2d54f99781ff465a2cd106fd3cd8ef6502bb097e832afe"
+      "sha256": "bfcc1b1653c36c240cd5793aa5d483f7bd740c5681f2ed0600f01217c5d8937d"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8207,12 +8207,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ef44492854e8c7dc0bffd40525911500bb56a175d59d82d1807dc1e55c58d0bc"
+      "sha256": "f509ecfaca00e821fa21984c54d36121ff0cf2d40057b0bf98c2442edc6b74ab"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2687fb0dcd9a64ca3bc3d4d39f634ec22490bbc935df1d7aa1fc02826d8e76ca"
+      "sha256": "f2e41698e557ef6542dcc15b564de5cee94bfa8736097add3523fa5d665c60a6"
     },
     {
       "path": "public-docs/index.html",
@@ -8862,7 +8862,7 @@
     {
       "path": "scripts/gds/gen-file-map.js",
       "mode": "0000644",
-      "sha256": "a8531787384fc528eb75dde142ca8d24982e47e226c934d6e692c53e6e738a0a"
+      "sha256": "ac2308077104c2ff899f4b12ff9da7baa965a9c0d3e4ef2f92e6bdf9d3613fb6"
     },
     {
       "path": "scripts/gds/gen-freshness.js",
@@ -10257,7 +10257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "499b3d104f70faa2b9cc4252419f7ff3f08a645fcdf329ec9a26761a25289e65"
+      "sha256": "edd1b0444e04d5511e536f5991e87c8fc271b7a18f2ee3f3f6d2dc6d1fd88486"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11522,7 +11522,7 @@
     {
       "path": "tests/file_map.mjs",
       "mode": "0000644",
-      "sha256": "e426eea6852d2ea63b79d27e17b71c53031ca65ee22644192eb4807df26f7482"
+      "sha256": "c6a7da467336246652fae6db5b5d7faa147e71ac1db89a66ec143dcf03bf8013"
     },
     {
       "path": "tests/filing_abuse_matrix.mjs",

package/docs/module-api-changelog.md

@@ -2476,5 +2476,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.999 with no explicit bump. run 35943151697. (task 1002620)
   1.19.1001 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1000 with no explicit bump. run 36016738965. (task 1002620)
+  1.19.1002 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1001 with no explicit bump. run 36019839845. (task 1002620)
+  1.19.1003 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1002 with no explicit bump. run 36021332931. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1001",
+  "version": "1.19.1003",
   "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/gen-file-map.js

@@ -13,7 +13,7 @@
 // and .claude/scheduled-tasks/ — are now GENERATED from what is on disk. The per-entry one-line
 // notes (the prose after the ←, which no directory walk can know) live in a sidecar,
 // docs/file-map.notes.json, the ONE place a human writes them. The contract enforced by --check:
-//   • every skill/routine dir on disk MUST have a note  → a new skill can't land undescribed;
+//   • every TRACKED skill/routine dir MUST have a note  → a new skill can't land undescribed;
 //   • every note MUST map to a dir that exists           → the map can't carry ghosts;
 //   • the rendered block MUST match what's committed      → no stale tree.
 // MODULE COVERAGE (task 1004066). The same honor system that let a skill land unmapped let a whole
@@ -41,6 +41,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
 const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
 
@@ -87,6 +88,21 @@ function loadNotes() {
 const { readModuleSkillsManifest } = require('./claude-materialize.js');
 function materializedNames(absDir) { return new Set(Object.keys(readModuleSkillsManifest(absDir).skills)); }
 
+// The subdirs of `relDir` holding at least one TRACKED file (task 1004213). An untracked one is the
+// builder's own — a locally-installed plugin skill, or the empty husk a plugin extract leaves — and
+// listing it would publish one machine's tooling into a shared doc on every post-merge regen.
+// null when `root` is not the top of a git work tree (a packaged install, ADR 0108 §1): nothing to ask.
+function trackedSubdirs(root, relDir) {
+  const git = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  try {
+    if (git(['rev-parse', '--show-prefix']).trim() !== '') return null;
+    return new Set(git(['ls-files', '-z', '--', relDir]).split('\0')
+      .map((p) => p.slice(relDir.length + 1).split('/'))
+      .filter((segs) => segs.length > 1)
+      .map((segs) => segs[0]));
+  } catch { return null; }
+}
+
 // Immediate subdirectories of an absolute dir, sorted by name (deterministic); materialised
 // module copies excluded.
 function listSubdirs(absDir) {
@@ -103,7 +119,9 @@ function listSubdirs(absDir) {
 // classes the freshness contract enforces (a dir with no note; a note with no dir).
 function buildSection(section, notes) {
   const absDir = path.join(REPO_ROOT, section.dir);
-  const names = listSubdirs(absDir);
+  const present = listSubdirs(absDir);
+  const tracked = trackedSubdirs(REPO_ROOT, section.dir);
+  const names = tracked ? present.filter((n) => tracked.has(n)) : present;
   const sectionNotes = (notes && notes[section.notesKey]) || {};
   const entries = names.map((name) => {
     // Skills + scheduled-tasks each carry a SKILL.md; label it explicitly when present (matches the
@@ -114,7 +132,8 @@ function buildSection(section, notes) {
     return { name, label, note };
   });
   const missing = entries.filter((e) => e.note == null).map((e) => `${section.dir}/${e.name}`);
-  const onDisk = new Set(names);
+  // A note is a ghost only when its dir is gone from disk — one not yet `git add`ed is not.
+  const onDisk = new Set(present);
   const stale = Object.keys(sectionNotes).filter((k) => !onDisk.has(k)).map((k) => `${section.notesKey}.${k}`);
   return { ...section, absDir, entries, missing, stale };
 }

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

@@ -3,7 +3,8 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -40,8 +41,11 @@ test('EVERY skill + scheduled-task dir on disk is listed AND has a note — no s
     // A module skill materialised into this checkout (task 1003330) is an untracked copy the
     // module documents; the generator skips it by the manifest beside it, and so does this.
     const materialised = gen.materializedNames(path.join(ROOT, section.dir));
+    // An untracked dir is the builder's own (a plugin install, an empty husk — task 1004213).
+    const tracked = new Set(execFileSync('git', ['ls-files', '-z', '--', section.dir], { cwd: ROOT, encoding: 'utf8' })
+      .split('\0').map((p) => p.slice(section.dir.length + 1).split('/')).filter((s) => s.length > 1).map((s) => s[0]));
     const onDisk = readdirSync(path.join(ROOT, section.dir), { withFileTypes: true })
-      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !materialised.has(e.name))
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !materialised.has(e.name) && tracked.has(e.name))
       .map((e) => e.name)
       .sort();
     const listed = section.entries.map((e) => e.name).sort();
@@ -69,20 +73,68 @@ test('the generated blocks live between markers and carry one ← note per entry
   }
 });
 
-test('--check FAILS (exit 2) when a new skill has no note — a skill can no longer land undescribed', () => {
-  const probe = path.join(ROOT, '.claude', 'skills', '__filemap_test__');
+// A throwaway instance root (task 1004213). `new-skill` is staged, so git tracks it; `local-plugin`
+// is untracked with a SKILL.md, as a real plugin install is; `empty-husk` is the bare dir a plugin
+// extract leaves behind. The generator falls back to cwd for its root, so no env is needed.
+function fixtureRoot({ git }) {
+  const root = mkdtempSync(path.join(tmpdir(), 'file-map-'));
+  const skills = path.join(root, '.claude', 'skills');
+  for (const n of ['new-skill', 'local-plugin']) {
+    mkdirSync(path.join(skills, n), { recursive: true });
+    writeFileSync(path.join(skills, n, 'SKILL.md'), `---\nname: ${n}\n---\n`);
+  }
+  mkdirSync(path.join(skills, 'empty-husk'));
+  if (git) {
+    execFileSync('git', ['init', '-q'], { cwd: root, stdio: 'ignore' });
+    execFileSync('git', ['add', '.claude/skills/new-skill'], { cwd: root, stdio: 'ignore' });
+  }
+  return root;
+}
+const skillsSectionAt = (cwd) => JSON.parse(execFileSync(process.execPath,
+  ['-e', `process.stdout.write(JSON.stringify(require(${JSON.stringify(GEN)}).buildModel()))`],
+  { cwd, encoding: 'utf8' })).find((s) => s.id === 'skills');
+const skillNamesAt = (cwd) => skillsSectionAt(cwd).entries.map((e) => e.name);
+
+test('--check FAILS (exit 2) when a new tracked skill has no note — a skill can no longer land undescribed', () => {
+  const root = fixtureRoot({ git: true });
   try {
-    mkdirSync(probe, { recursive: true });
-    writeFileSync(path.join(probe, 'SKILL.md'), '---\nname: __filemap_test__\n---\n');
-    const r = run(['--check']);
+    let r;
+    try { execFileSync(process.execPath, [GEN, '--check'], { cwd: root, encoding: 'utf8', stdio: 'pipe' }); r = { code: 0, stderr: '' }; }
+    catch (e) { r = { code: e.status, stderr: String(e.stderr) }; }
     assert.equal(r.code, 2, 'an undescribed skill must fail the gate');
-    assert.match(r.stderr, /notes MISSING/);
-    assert.match(r.stderr, /__filemap_test__/);
+    assert.match(r.stderr, /notes MISSING for: \.claude\/skills\/new-skill(?! *,)/, 'the tracked skill, and only it, is missing a note');
+    assert.doesNotMatch(r.stderr, /local-plugin|empty-husk/);
   } finally {
-    rmSync(probe, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('an untracked skill dir is the builder\'s own — a plugin install and an empty husk never reach the map', () => {
+  const root = fixtureRoot({ git: true });
+  try {
+    assert.deepEqual(skillNamesAt(root), ['new-skill']);
+    // A note written before `git add` is not a ghost: its dir is on disk.
+    mkdirSync(path.join(root, 'docs'));
+    writeFileSync(path.join(root, 'docs', 'file-map.notes.json'), JSON.stringify({ skills: { 'local-plugin': 'x', gone: 'y' } }));
+    assert.deepEqual(skillsSectionAt(root).stale, ['skills.gone']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('outside a git work tree (a packaged install) every dir on disk is still listed', () => {
+  const root = fixtureRoot({ git: false });
+  const parent = fixtureRoot({ git: true });
+  const nested = path.join(parent, 'instance');
+  try {
+    assert.deepEqual(skillNamesAt(root), ['empty-husk', 'local-plugin', 'new-skill']);
+    // A root that is a SUBDIR of some repo is not that repo's top: its files are not the repo's to judge.
+    mkdirSync(path.join(nested, '.claude', 'skills', 'inner'), { recursive: true });
+    assert.deepEqual(skillNamesAt(nested), ['inner']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+    rmSync(parent, { recursive: true, force: true });
   }
-  // and clean again once removed
-  assert.equal(run(['--check']).code, 0, 'gate is clean after the probe dir is removed');
 });
 
 test('generation is deterministic + idempotent (a second run is a no-op)', () => {