@bongos/core 1.21.70 → 1.21.71

package/modules/lifecycle/goal-spec-task.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// modules/lifecycle/goal-spec-task.js — a goal made in the hall carries its own
+// spec task, and the goal's other work waits behind it (task 1004585, ADR 0366 D3).
+//
+// WHY. The hall's goal form asks only what a person knows (a name, a description,
+// a version, a category). The rest of a goal — its scope wall, its criteria, its
+// first tasks — is inference, which /goal-create does in a session (ADR 0366 D2).
+// So a hall-made goal arrives with a task that says exactly that, and nothing else
+// in the goal can be claimed until it ships: an unspecced goal is visible as a
+// task on the board, not a silence.
+//
+// HOW, with no new permission and no migration:
+//   - The spec task is an ordinary task, recognised by (source, source_ref) =
+//     ('goal-spec', 'goal-<id>-spec'). That pair is also what makes creating it
+//     idempotent (findTaskBySourceRef).
+//   - "Waits behind it" is an ordinary task→task dependency, so the claim gate's
+//     existing DEPS_NOT_SHIPPED refusal and the auto-promotion on ship do the rest.
+//     A goal-level edge would be simpler, but every task in the goal inherits it
+//     (unsatisfiedDeps), the spec task included, which would block it on itself.
+//   - The edge is added at the two places a task ENTERS a goal: db-tasks.createTask
+//     (every create vector passes through it) and db-tasks.updateTaskGoal (a move).
+
+const SPEC_SOURCE = 'goal-spec';
+
+function specSourceRef(goalId) {
+  return `goal-${goalId}-spec`;
+}
+
+// The spec task's fields, for db.createTask. `ready` so it can be claimed at once;
+// a spike, because its output is a decision (the scope and the criteria) rather
+// than code; ideator, the craft whose pack covers "the scopes of work ideas become".
+function specTaskFields(goal, { createdBy = null } = {}) {
+  const id = goal.id;
+  return {
+    versionId: goal.version_id,
+    goalId: id,
+    title: `Spec goal ${id}: its scope, criteria and first tasks`,
+    description: [
+      `Goal ${id} ("${goal.title}") was created from the hall, which asks only for a name and a description. This task settles the rest, and every other task in the goal waits on it (ADR 0366 D3).`,
+      '',
+      'Settle, in a session (run /goal-create against this goal):',
+      `1. The scope wall: which code areas the goal's tasks may touch. Set it with POST /goals/${id}/scope (the goal's owner or a manager; a protected area needs an Archon).`,
+      `2. Two to four done-when criteria, with POST /versions/${goal.version_id}/done-when under the goal (ADR 0154: the goal's owner or a manager).`,
+      '3. The first tasks, with their dependencies.',
+      '',
+      'If you do not own or manage this goal, draft the scope and criteria and hand them to its owner rather than skipping them.',
+      '',
+      'DONE WHEN: the goal has its scope (or a written reason it needs none), its criteria, and at least one claimable task.',
+    ].join('\n'),
+    status: 'ready',
+    kind: 'spike',
+    discipline: 'ideator',
+    source: SPEC_SOURCE,
+    sourceRef: specSourceRef(id),
+    createdBy,
+  };
+}
+
+// The goal's spec task if it is still open, else null. An abandoned spec task
+// gates nothing new (the owner decided the goal needs no spec); a shipped one is done.
+async function openSpecTaskId(goalId, client) {
+  if (goalId == null) return null;
+  const { rows } = await client.query(
+    `SELECT id FROM tasks
+      WHERE goal_id = $1 AND source = $2 AND source_ref = $3
+        AND status NOT IN ('shipped', 'abandoned')
+      ORDER BY id ASC
+      LIMIT 1`,
+    [goalId, SPEC_SOURCE, specSourceRef(goalId)]
+  );
+  return rows[0] ? Number(rows[0].id) : null;
+}
+
+// Make a task that just entered a goal wait on that goal's open spec task.
+// Returns the spec task id it now waits on, or null. A task that IS the spec task
+// is left alone. Safe without a cycle check only for a brand-new task (nothing can
+// depend on it yet) — a moved task goes through addTaskDependency, which checks.
+async function gateOnSpecTask(task, client, { addTaskDependency = null } = {}) {
+  if (!task || task.goal_id == null) return null;
+  if (task.source === SPEC_SOURCE && task.source_ref === specSourceRef(task.goal_id)) return null;
+  const specId = await openSpecTaskId(task.goal_id, client);
+  if (specId == null || specId === Number(task.id)) return null;
+  if (addTaskDependency) {
+    try {
+      await addTaskDependency(task.id, specId);
+    } catch (err) {
+      // A cycle means the spec task already waits on this task; gating it would
+      // deadlock both, so the move stands without the edge.
+      if (err && err.code === 'CYCLE') return null;
+      throw err;
+    }
+  } else {
+    await client.query(
+      `INSERT INTO dependencies (from_kind, from_id, to_kind, to_id)
+       VALUES ('task', $1, 'task', $2)
+       ON CONFLICT DO NOTHING`,
+      [task.id, specId]
+    );
+  }
+  return specId;
+}
+
+// Give a goal its spec task, safely re-runnable: if the goal already has an OPEN
+// spec task, that one is returned and nothing is written, so a second run (a retry,
+// or a future "re-offer the spec" path) never files a duplicate. Run it inside the
+// caller's transaction so the read and the insert see the same snapshot.
+async function ensureSpecTask({ db, goal, client, createdBy = null }) {
+  const existing = await openSpecTaskId(goal.id, client);
+  if (existing != null) return { specTask: { id: existing }, created: false };
+  const specTask = await db.createTask(specTaskFields(goal, { createdBy }), { client });
+  return { specTask, created: true };
+}
+
+// POST /goals's create step. Without the opt-in it is exactly db.createGoal. With it,
+// the goal and its spec task land in ONE transaction: a goal without its spec task
+// would be ungated, which is the state D3 exists to end.
+async function createGoalWithSpec({ db, withTx, goalFields, withSpecTask = false }) {
+  if (!withSpecTask) return { goal: await db.createGoal(goalFields), specTask: null };
+  let goal;
+  let specTask = null;
+  await withTx(async (client) => {
+    goal = await db.createGoal(goalFields, { client });
+    ({ specTask } = await ensureSpecTask({ db, goal, client, createdBy: goalFields.createdBy }));
+  });
+  return { goal, specTask };
+}
+
+module.exports = { SPEC_SOURCE, specSourceRef, specTaskFields, openSpecTaskId, gateOnSpecTask, ensureSpecTask, createGoalWithSpec };

package/modules/lifecycle/routes/goals.js

@@ -29,6 +29,7 @@ const hierarchy = require('../hierarchy');
 const goalSuggest = require('../goal-suggest.js'); // task 1003062 — pre-creation goal suggester
 const goalEdits = require('../goal-edits.js'); // task 1003102 — goal self-edit handlers
 const goalCategory = require('../goal-category.js'); // task 1003275 — the ADVISORY human category (gates nothing)
+const goalSpecTask = require('../goal-spec-task.js'); // task 1004585 — a hall-made goal carries its own spec task (ADR 0366 D3)
 const goalRollup = require('../goal-rollup.js'); // task 1003278 — per-goal rollups computed in SQL, not in the browser
 const goalGraph = require('../goal-graph.js'); // task 1003479 — the goal graph: nodes + cross-goal edges, aggregated in SQL
 const goalForest = require('../goal-forest.js'); // task 1003480 — per-goal dependency forest
@@ -97,6 +98,7 @@ module.exports = function buildGoalsRouter() {
       // requested without stating a cause. minLength 8 because 'ok' / '.' is not
       // a reason, and the row is the only place the why survives.
       admit_reason: { type: 'string', minLength: 8, maxLength: 500 },
+      spec_task: { type: 'boolean' }, // task 1004585 / ADR 0366 D3 — the hall form's opt-in (goal-spec-task.js)
     })) return;
 
     const scopeModules = req.body.scope_modules || [];
@@ -156,15 +158,11 @@ module.exports = function buildGoalsRouter() {
       const admission = versionDecision.overrideApplied
         ? { admittedBy: req.builder.id, reason: admitReason }
         : null;
-      const goal = await db.createGoal({
-        versionId: req.body.version_id,
-        title: req.body.title,
+      const { goal, specTask } = await goalSpecTask.createGoalWithSpec({ db, withTx: api.withTx, withSpecTask: req.body.spec_task === true, goalFields: {
+        versionId: req.body.version_id, title: req.body.title,
         subtitle: (req.body.subtitle || '').trim() || null, description: (req.body.description || '').trim() || null,
-        scopeModules,
-        createdBy: req.builder.id,
-        categoryId,
-        admission,
-      });
+        scopeModules, createdBy: req.builder.id, categoryId, admission,
+      } });
       // Stamp the predecessor's succeeded_by pointer at the new goal (the lineage).
       if (succeedsId != null) {
         await db.setGoalSuccessor({ goalId: succeedsId, successorId: goal.id });
@@ -182,7 +180,7 @@ module.exports = function buildGoalsRouter() {
       // waved into a building version, by whom and why — the caller should not
       // have to re-read the goal to find out whether their override took effect.
       const admitted = admission ? await db.getGoalAdmission(goal.id) : null;
-      return res.status(201).json({ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted });
+      return res.status(201).json({ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted, spec_task: specTask });
     } catch (err) {
       log.error('[gds] POST /goals', err);
       return res.fail('goal_create_failed', { status: 500, message: 'internal error' });

package/modules/lifecycle/routes/task-write-routes.js

@@ -29,6 +29,7 @@ const { validateOrRespond, LIMITS, parseId } = api;
 const { badKind, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
+const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 
@@ -189,10 +190,18 @@ module.exports = function registerTaskWriteRoutes(router) {
     // nobody reads. This is the human/agent door, and it always has a goal to
     // name — /builder-start lists work by goal, and POST /goals/:id/tasks has
     // required one since BV1.R60.
+    // task 1004597: the one exception is PLATFORM UPKEEP (a core upgrade, Bongos
+    // maintenance), which fits no product goal. An explicit kind 'infra' with no
+    // goal lands in the version's maintenance goal — see upkeep-home.js.
+    const upkeepHome = await resolveUpkeepHome(body, { ensureMaintenanceGoal: db.ensureMaintenanceGoal, withTx: api.withTx });
+    if (upkeepHome) body.goal_id = Number(upkeepHome.id);
     if (body.goal_id == null) {
       return res.fail('goal_id_required', {
         status: 400,
-        message: 'goal_id is required — every task belongs to a goal. List them at GET /goals?version=<id>, or author under one directly with POST /goals/:id/tasks.',
+        message: 'goal_id is required — every task belongs to a goal. List them at GET /goals?version=<id>, or author under one directly with POST /goals/:id/tasks. ' +
+          (isUpkeepFiling(body)
+            ? `Version '${body.version_id}' is not being built right now, so it has no maintenance goal for upkeep — file it against the version that is.`
+            : UPKEEP_HINT),
       });
     }
     if (body.goal_id != null) {
@@ -297,6 +306,7 @@ module.exports = function registerTaskWriteRoutes(router) {
         needs_migration: needsMigration,
         criteria,
         suggested_criteria,
+        ...(upkeepHome ? { goal_home: 'maintenance' } : {}), // task 1004597
         goal_advisory, dependency_advisory, est_advisory: await require('../est-advisory').buildEstAdvisory({ db, task }), // task 1003148
       });
     } catch (err) {

package/modules/lifecycle/upkeep-home.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// modules/lifecycle/upkeep-home.js — WHERE PLATFORM UPKEEP GOES WHEN NO PRODUCT
+// GOAL FITS (task 1004597).
+//
+// THE CONTRADICTION THIS CLOSES. The ledger rule says record a change before you
+// make it; the goal rule (ADR 0250 D4, BV1.R11) says every task belongs to a
+// goal. A project's goals are product goals ("Marketing", "Live Floor"), so a
+// builder about to upgrade the Bongos core had nowhere honest to file it: POST
+// /tasks refused `goal_id_required`, and the only ways forward were to misfile
+// the upgrade under a product goal or skip the record. One session (mercury,
+// 2026-10-06) chose the latter.
+//
+// THE ANSWER REUSES THE HOMELESS-BUG HOME. Every building version already has a
+// find-or-create MAINTENANCE goal (ADR 0262, `ensureMaintenanceGoal`): open, no
+// scope wall, exempt from the version-close count, carried forward on close.
+// Platform upkeep is maintenance in exactly that sense, so a task filed with
+// NO goal and kind 'infra' lands there.
+//
+// ONLY AN EXPLICIT kind COUNTS — never the classifier's guess. The defect
+// BV1.R11 fixed was SILENT bucketing (53 tasks filed out of sight by a default).
+// A caller who writes kind 'infra' has said out loud what the work is; a feature
+// whose text merely reads like infra must still name its goal.
+//
+// RANK AND APPROVAL ARE UNTOUCHED. This only answers "which goal"; the route's
+// own permission check (task.create, Metic+) and status rules run exactly as for
+// any other goal.
+
+const UPKEEP_KIND = 'infra';
+
+// isUpkeepFiling — true when a create names no goal and explicitly says it is
+// platform upkeep. PURE; exported so the rule has one spelling.
+function isUpkeepFiling(body) {
+  return !!body && body.goal_id == null && body.kind === UPKEEP_KIND;
+}
+
+// resolveUpkeepHome — the maintenance goal row an upkeep filing lands in, or
+// null when it is not an upkeep filing or the version cannot take work (not
+// `building`). The find-or-create runs inside its own transaction so the
+// advisory lock in ensureMaintenanceGoal actually serialises concurrent filers
+// (outside a transaction it would release at the end of its own statement).
+async function resolveUpkeepHome(body, deps) {
+  if (!isUpkeepFiling(body)) return null;
+  const { ensureMaintenanceGoal, withTx } = deps;
+  return withTx((client) => ensureMaintenanceGoal(body.version_id, { client }));
+}
+
+// The plain-words half of the goal_id_required refusal: what to do when the work
+// is upkeep rather than product work. Shared by the route and the CLI so the two
+// never drift.
+const UPKEEP_HINT =
+  'Platform upkeep — a Bongos upgrade or other maintenance — has a standing home: ' +
+  `file it with kind "${UPKEEP_KIND}" and no goal, and it goes into this version's maintenance goal.`;
+
+module.exports = { UPKEEP_KIND, UPKEEP_HINT, isUpkeepFiling, resolveUpkeepHome };

package/package-lock.json

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

package/package.json

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

@@ -9199,5 +9199,42 @@
     {
       "text": "Reporting a problem with Bongos now works from every project, including ones like Will's that could not send feedback before. It takes a second, needs no extra sign-in, and the Bongos team can see who really sent each report."
     }
+  ],
+  "1.21.71": [
+    {
+      "id": "1004595",
+      "text": "A hosted project's Software update page no longer stops at \"Update ready\". When the people who run its server do the upgrade, the owner now sees who that is and an \"Ask for this upgrade\" button; one press reaches the Cloud Bon"
+    },
+    {
+      "id": "1004621",
+      "text": "The assistant in a Bongos project no longer starts every session with a failed command. Its instructions now say `npx bongos …`, which works as soon as the project is installed, instead of a bare `bongos` that the computer cou"
+    },
+    {
+      "id": "1004586",
+      "text": "The goal-planning assistant can now finish a goal that was started in the hall: it works out the goal's scope, its 'done when' checks and its first tasks, then releases the goal's work."
+    },
+    {
+      "id": "1004622",
+      "text": "Fixed a broken test that was stopping every new Bongos release from being published."
+    },
+    {
+      "id": "1004596",
+      "text": "When someone on a hosted project (like Will's) asks to upgrade from their own computer, Bongos now tells them plainly that the project's operator does upgrades, and how to ask for one — from the Software update page or with on"
+    },
+    {
+      "id": "1004619",
+      "text": "Bongos now has a written plan for red and blue security teams: attacks happen on a separate practice server, never on the live site, and every release gets checked there."
+    },
+    {
+      "id": "1004597",
+      "text": "Recording routine Bongos upkeep, such as a core upgrade, no longer gets refused just because none of a project's goals fit. Filed as upkeep with no goal, it now goes into the version's standing maintenance goal. Any other task"
+    },
+    {
+      "id": "1004585",
+      "text": "A goal created from the hall now arrives with a 'Spec goal N' task. Nothing else in that goal can be picked up until someone finishes it, so a goal never sits half-defined."
+    },
+    {
+      "text": "Hosted projects like Will's now get a working Update button in Settings, instead of being told to run a command on a server they don't have access to."
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -33,7 +33,7 @@ const { spawnSync } = require('node:child_process');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
 const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
-const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
+const { renderInstanceClaudeMd, refreshStarterCliLines } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
 
 // script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
 // NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
@@ -61,16 +61,40 @@ const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJ
 // A non-gds core script under scripts/ (rare in skills, but keep the transform total).
 const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
 
-// Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
-// Idempotent (a string with no matching invocation is returned unchanged).
+// How a project runs the CLI (task 1004621). The `bongos` bin ships inside the @bongos/core
+// dependency (node_modules/.bin/bongos), which is NOT on PATH, so a bare `bongos ship` written
+// into a project's skills failed with `command not found` on every session's first call and the
+// assistant had to recover by retrying through npx. `npx` finds the project's own bin right after
+// `npm install`, with no setup, on every OS and shell — so that is the spelling a project reads.
+const PROJECT_CLI = 'npx bongos';
+
+// A hand-written bare `bongos <verb>` in skill prose (e.g. "`bongos paste-token <token>`"), so it
+// takes the npx spelling too. Case-sensitive on purpose ("Bongos status" is a product noun), only a
+// KNOWN verb, and never when already prefixed by `npx ` or glued to a path/name (`@bongos/core`,
+// `bongos-feedback`, `bongos: command not found` all stay). The `npx ` lookbehind is what keeps a
+// second run from writing `npx npx bongos`.
+function bareVerbRe(verbs) {
+  const names = Object.keys(verbs || {}).filter((v) => /^[a-z][a-z-]*$/.test(v));
+  if (!names.length) return null;
+  names.sort((a, b) => b.length - a.length); // `paste-token` before a shorter prefix of it
+  return new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${names.join('|')})(?![\w-])`, 'g');
+}
+
+// Pure: rewrite core-script invocations in a skill/settings command string to the project's CLI
+// spelling (`npx bongos <verb>`, else `npx bongos exec scripts/gds/<x>.js`), and give any bare
+// `bongos <verb>` the same npx prefix. Idempotent: its own output contains neither a
+// `node scripts/…` invocation nor an un-prefixed `bongos <verb>`, so a second run changes nothing.
 function bongosify(text, verbs = VERBS) {
   const map = scriptToVerb(verbs);
-  return String(text == null ? '' : text)
+  const bare = bareVerbRe(verbs);
+  let out = String(text == null ? '' : text);
+  if (bare) out = out.replace(bare, (_whole, verb) => `${PROJECT_CLI} ${verb}`);
+  return out
     .replace(GDS_INVOCATION_RE, (_whole, script) => {
       const verb = map[`${script}.js`];
-      return verb ? `bongos ${verb}` : `bongos exec scripts/gds/${script}.js`;
+      return verb ? `${PROJECT_CLI} ${verb}` : `${PROJECT_CLI} exec scripts/gds/${script}.js`;
     })
-    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `bongos exec scripts/${rel}`);
+    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `${PROJECT_CLI} exec scripts/${rel}`);
 }
 
 // ---- instance rebrand (task 2103) -----------------------------------------
@@ -340,34 +364,38 @@ function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true
 // path and is the agent's escape hatch, so allow-listing it would be a blanket
 // grant wearing a narrow rule's clothes. The one script the core's own list
 // blesses (`api.js`) is named in full instead.
+//
+// EVERY RULE IS THE `npx bongos` SPELLING (task 1004621): a project has no bare
+// `bongos` on PATH, so its skills, its CLAUDE.md and Settings → CLI access
+// (task 1004575) all say `npx bongos …`, and a bare-`bongos` rule would allow a
+// command nothing runs. An instance that took the older bare starter gains the
+// npx twin of each bare rule it still holds on its next upgrade
+// (topUpNpxAllowTwins below).
 const STARTER_COMMANDS = [
-  'bongos claim:*',
-  'bongos ship:*',
-  'bongos release:*',
-  'bongos reauth:*',
-  'bongos paste-token:*',
-  // What Settings → CLI access hands out since task 1004575: a clone has no
-  // bare `bongos` on PATH, so the copied command runs through npx.
+  'npx bongos claim:*',
+  'npx bongos ship:*',
+  'npx bongos release:*',
+  'npx bongos reauth:*',
   'npx bongos paste-token:*',
-  'bongos exec scripts/gds/api.js:*',
+  'npx bongos exec scripts/gds/api.js:*',
   // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
   // are exact forms on purpose: a flag turns either into a write or an exec. No
   // `git diff|log|show` rule, also on purpose: the harness already runs their
   // read-only forms unprompted, and a prefix rule would switch off its flag check
   // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
   // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
-  'bongos start:*',
-  'bongos status:*',
-  'bongos recall:*',
-  'bongos exec scripts/gds/me.js:*',
-  'bongos doctor:*',
-  'bongos exec scripts/gds/preflight.js:*',
-  'bongos exec scripts/gds/skill-preflight.js:*',
-  'bongos exec scripts/gds/ship-check.js:*',
-  'bongos exec scripts/gds/fitness.js:*',
-  'bongos exec scripts/gds/strand-watch.js:*',
-  'bongos exec scripts/gds/stale-worktrees.js:*',
-  'bongos exec scripts/gds/read-session-export.js:*',
+  'npx bongos start:*',
+  'npx bongos status:*',
+  'npx bongos recall:*',
+  'npx bongos exec scripts/gds/me.js:*',
+  'npx bongos doctor:*',
+  'npx bongos exec scripts/gds/preflight.js:*',
+  'npx bongos exec scripts/gds/skill-preflight.js:*',
+  'npx bongos exec scripts/gds/ship-check.js:*',
+  'npx bongos exec scripts/gds/fitness.js:*',
+  'npx bongos exec scripts/gds/strand-watch.js:*',
+  'npx bongos exec scripts/gds/stale-worktrees.js:*',
+  'npx bongos exec scripts/gds/read-session-export.js:*',
   'git status:*',
   'git branch --list',
   'git branch --show-current',
@@ -473,6 +501,37 @@ function topUpStarterDeny(existingText, wanted) {
   return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
 }
 
+// topUpNpxAllowTwins — the `npx bongos` twin of every bare-`bongos` allow rule an instance's OWN
+// settings.json holds (task 1004621). The skills an upgrade lands now say `npx bongos ship`, and a
+// `Bash(bongos ship:*)` rule does not match that, so without the twin the upgrade would trade a
+// `command not found` for a permission prompt on every blessed command. This is NOT the shell-rule
+// top-up task 1004158 ruled out: nothing new is offered. Each twin is a rule the owner already
+// holds, respelled for the one launcher that reaches the same project-local bin — a rule they
+// removed gets no twin, and nothing they wrote is removed or rewritten. Same { text, added, reason }
+// contract as topUpStarterDeny; an unreadable shape is left alone and reported.
+const BARE_BONGOS_RULE_RE = /^(\w+)\(bongos (.+)\)$/;
+function topUpNpxAllowTwins(existingText) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const allow = perms.allow === undefined ? [] : perms.allow;
+  if (!Array.isArray(allow)) return cannotCheck('its "permissions.allow" is not an array');
+  const have = new Set(allow);
+  const added = [];
+  for (const rule of allow) {
+    const m = typeof rule === 'string' && rule.match(BARE_BONGOS_RULE_RE);
+    const twin = m && `${m[1]}(${PROJECT_CLI} ${m[2]})`;
+    if (twin && !have.has(twin)) { have.add(twin); added.push(twin); }
+  }
+  if (!added.length) return { text: null, added: [], reason: null };
+  const next = { ...doc, permissions: { ...perms, allow: [...allow, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
 // The starter an instance gets when the core root carries no settings.json — a
 // package-only install. Permissions ONLY: no hooks (they are topology), no env.
 function renderStarterSettings(branding = {}) {
@@ -778,9 +837,26 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       // The read is guarded: existsSync passing does not mean readable (a directory at that path,
       // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
       // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
+      // The npx twins of the owner's own bare-`bongos` allow rules ride the same single read and
+      // write (task 1004621): applied first, so the deny top-up below works on — and writes — the
+      // text that already carries them. An unparseable file trips both the same way and is
+      // reported once, by the deny half.
       let topUp;
-      try { topUp = topUpStarterDeny(fs.readFileSync(settingsDest, 'utf8'), credentialDeny(toBranding)); }
-      catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      let twins = { text: null, added: [], reason: null };
+      try {
+        const raw = fs.readFileSync(settingsDest, 'utf8');
+        twins = topUpNpxAllowTwins(raw);
+        topUp = topUpStarterDeny(twins.text || raw, credentialDeny(toBranding));
+      } catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      if (twins.added.length) {
+        summary.settingsAllowTwinsAdded = twins.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED the \`npx bongos\` twin of ${twins.added.length} bare-\`bongos\` allow rule(s) it held — the skills now say \`npx bongos …\`, which a bare rule does not match: ${twins.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} the npx twin of ${twins.added.length} bare-bongos allow rule(s) to .claude/settings.json (skills now run \`npx bongos …\`; every rule you wrote is kept): ${twins.added.join(', ')}`);
+        if (!topUp.text && !topUp.reason) {
+          if (!dryRun) fs.writeFileSync(settingsDest, twins.text);
+          if (!dryRun) addWritten('.claude/settings.json'); // real run only — the same reasoning as the deny write below
+        }
+      }
       if (topUp.text) {
         if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
         // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
@@ -803,7 +879,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         summary.settingsDenyUncheckable = topUp.reason;
         summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
         log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
-      } else {
+      } else if (!twins.added.length) {
         summary.skippedFiles.push('settings.json');
         log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
       }
@@ -859,9 +935,27 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   //    branding. Written only when ABSENT — never clobber a CLAUDE.md the instance has
   //    grown (safe for init, adopt, and upgrade alike; the self-copy guard above already
   //    keeps this from ever touching the core/OTB checkout's own CLAUDE.md).
+  //    One narrow exception (task 1004621): the starter's OWN sentences that told the assistant to
+  //    type a bare `bongos …` — not on PATH in a project — are swapped for their `npx bongos …` form
+  //    where they still read exactly as the starter wrote them (refreshStarterCliLines). Not in
+  //    adopt mode, which never touches what the owner already had.
   const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
   if (fs.existsSync(claudeMdPath)) {
-    summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    let refreshed = { changed: 0 };
+    if (overwrite) {
+      try { refreshed = refreshStarterCliLines(fs.readFileSync(claudeMdPath, 'utf8')); } catch { /* unreadable: leave it, as before */ }
+    }
+    if (refreshed.changed) {
+      if (!dryRun) fs.writeFileSync(claudeMdPath, refreshed.text);
+      // Real run only, like the settings top-up: it preserves content, so the upgrade pre-flight's
+      // "materialize overwrites this anyway" waiver must not cover an owner's uncommitted edit.
+      if (!dryRun) addWritten('CLAUDE.md');
+      summary.claudeMdCliLines = refreshed.changed;
+      summary.notes.push(`CLAUDE.md kept as the instance's own, except ${refreshed.changed} unedited starter sentence(s) now say \`npx bongos …\` — the CLI is not on PATH in a project, so a bare \`bongos\` failed with command not found.`);
+      log(`  ${dryRun ? '[dry-run] would update' : '✓ updated'} ${refreshed.changed} unedited starter sentence(s) in CLAUDE.md to \`npx bongos …\` (everything else untouched)`);
+    } else {
+      summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    }
   } else {
     if (!dryRun) {
       fs.mkdirSync(instanceDir, { recursive: true });
@@ -1018,4 +1112,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };