@bongos/core 1.19.1032 → 1.19.1033

package/scripts/gds/release-notes.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// scripts/gds/release-notes.js — what each core release brought in, as the summaries its
+// ships wrote, generated when the core is PACKED and shipped inside the package as
+// release-notes.json (task 1004218).
+//
+// WHY INSIDE THE PACKAGE. The Deploy page's "what this brings in" list used to be read out
+// of a core git checkout on the machine asking (task 1004173), and no tenant box will ever
+// have one: every project the wizard creates is a checkout of its OWN repo with the core
+// vendored in at node_modules. The one machine that always has the full history is the one
+// that builds the package — publish.yml checks out at fetch-depth 0 because package-core
+// archives from git — so that is where the notes are written down, once, and every project
+// that can download a core version can read what it carries.
+//
+// THREE PARTS, NO I/O OF ITS OWN. The PARSER (parseChangeRecords, moved here from
+// provision-core-upgrade.js so there is exactly one), the GENERATOR (package-core.js hands
+// it the ref's history), and the RANGE READER (the upgrade runner asks it for from→to).
+// Git is injected, never required, so loading this costs package-core nothing.
+//
+// THE SHAPE. `{ "<version>": [ { id?, text }, … ] }`, ascending by version, one key per
+// release — including a release whose merges were all housekeeping, which keeps an EMPTY
+// list. That is the difference between "nothing landed" and "not covered": a range is
+// answerable only when its target is a key, so a missing key can never be read as silence.
+
+const CHANGE_TEXT_MAX = 400;
+
+// The file's name at the package root, beside package.json.
+const RELEASE_NOTES_FILE = 'release-notes.json';
+
+// THE BOUND. The whole history to 1.19.1029 is ~400 KB pretty-printed (1,033 releases,
+// 1,399 summaries, measured 2026-09-25), growing roughly 200 KB a month at 20–30 releases a
+// day. Nothing needs trimming today; the bound exists so the file cannot grow unwatched.
+// Past it, the OLDEST releases are dropped — the ranges an owner asks about are recent ones
+// — and the reader then says those older ranges are not covered, rather than guessing.
+const RELEASE_NOTES_MAX_BYTES = 1024 * 1024;
+
+// A release commit's subject — the lane's own carrier AND a human release both begin this
+// way. The same marker findCoreCheckout's probe uses to recognise core history.
+const RELEASE_SUBJECT_RE = /^release: core (\d+\.\d+\.\d+) /;
+const CORE_VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+// One record per commit: sha, parents, subject, body. `--topo-order` is load-bearing — see
+// buildReleaseNotes for why the order releases are visited in must be topological.
+const LOG_ARGS = ['log', '--topo-order', '--format=%H%x1f%P%x1f%s%x1f%b%x1e'];
+
+/**
+ * The merge summaries in a `git log --merges --format=%s%x1f%b%x1e` dump. PURE.
+ *
+ * TWO MERGE SHAPES CARRY A SUMMARY AND THE SECOND IS THE COMMON ONE. A hand-landed ship
+ * writes `Merge <branch>: <summary>`; the CI auto-merge writes `Merge pull request #N
+ * from <owner>/<branch>` with `task <id>: <summary>` in the BODY. Measured over
+ * 1.19.881→1.19.972: 114 usable summaries, of which 98 were the second shape. A parser
+ * that read subjects only would have found eleven of them and quietly called that the
+ * release.
+ *
+ * EVERYTHING ELSE IS DROPPED, and the drops are the majority: `Merge origin/main into
+ * <branch> (pre-stage freshness…)`, `Merge remote-tracking branch…`, a regen chore. Those
+ * are the mechanics of landing work, not the work, and listing them would bury the
+ * eleven sentences the owner actually wants under a hundred they do not.
+ */
+function parseChangeRecords(stdout) {
+  const out = [];
+  const seen = new Set();
+  for (const rec of String(stdout || '').split('\x1e')) {
+    const r = rec.trim();
+    if (!r) continue;
+    const i = r.indexOf('\x1f');
+    const subject = (i < 0 ? r : r.slice(0, i)).trim();
+    const body = i < 0 ? '' : r.slice(i + 1);
+    let text = null;
+    let id = null;
+    // The negative lookahead is what keeps the two housekeeping shapes out: both begin
+    // "Merge " and both would otherwise match a `<token>:` somewhere later in the line.
+    let m = /^Merge\s+(?!pull request\b|remote-tracking\b)([^\s:]+):\s*(\S.*)$/.exec(subject);
+    if (m) {
+      text = m[2];
+    } else {
+      const first = body.split('\n').map((l) => l.trim()).find(Boolean) || '';
+      m = /^task\s+(\d+):\s*(\S.*)$/.exec(first);
+      if (m) { id = m[1]; text = m[2]; }
+    }
+    if (!text) continue;
+    // It reaches a DOM, and a ship summary is occasionally a paragraph.
+    text = boundText(text);
+    if (seen.has(text)) continue;   // a branch merged twice says its sentence once
+    seen.add(text);
+    out.push(id ? { id, text } : { text });
+  }
+  return out;
+}
+
+function boundText(text) {
+  return text.length > CHANGE_TEXT_MAX ? `${text.slice(0, CHANGE_TEXT_MAX - 1)}…` : text;
+}
+
+/** Order two three-number core versions. PURE; both must already match CORE_VERSION_RE. */
+function compareCoreVersions(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+/** Split a LOG_ARGS dump into `{ sha, parents, subject, body }` records, in log order. PURE. */
+function parseLogRecords(stdout) {
+  const out = [];
+  for (const rec of String(stdout || '').split('\x1e')) {
+    const r = rec.replace(/^\n+/, '');   // git terminates each record with a newline
+    if (!r.trim()) continue;
+    const [sha, parents, subject, ...body] = r.split('\x1f');
+    out.push({
+      sha: sha.trim(),
+      parents: String(parents || '').split(' ').filter(Boolean),
+      subject: subject || '',
+      body: body.join('\x1f'),
+    });
+  }
+  return out;
+}
+
+function uniqueByText(entries) {
+  const seen = new Set();
+  return entries.filter((e) => (seen.has(e.text) ? false : seen.add(e.text)));
+}
+
+/**
+ * What each release brought in, from a whole history. PURE.
+ *
+ * `commits` is every commit the packed ref reaches, NEWEST FIRST in topological order (what
+ * LOG_ARGS asks git for). Returns `{ notes, releases, tail }`.
+ *
+ * EXACTLY `git log --merges <previous release>..<release>`, FOR EVERY RELEASE AT ONCE — the
+ * range the checkout-based reader asks for one pair at a time. Splitting the log wherever a
+ * release subject appears would be simpler and is wrong: a PR branch's commits are not
+ * ordered against main's by the log, so a merge made on a branch before one release but
+ * landed after it would be credited to the earlier release. So each release, oldest first,
+ * claims everything it can reach that no earlier release reached. The visiting order has to
+ * be topological for that to be the previous-release range — hence `--topo-order`.
+ *
+ * THE UNRELEASED TAIL — commits the ref reaches that no release commit does — belongs to the
+ * version being packed when that version has no release commit of its own yet (a pack of a
+ * hand-declared version), and to nobody otherwise: on a work merge the tail is the NEXT
+ * release's, whose number does not exist yet.
+ */
+function buildReleaseNotes(commits, { version = null } = {}) {
+  const bySha = new Map(commits.map((c) => [c.sha, c]));
+  const position = new Map(commits.map((c, i) => [c.sha, i]));
+  const claimed = new Set();
+  const claim = (tip) => {
+    const mine = [];
+    const stack = [tip];
+    while (stack.length) {
+      const sha = stack.pop();
+      if (claimed.has(sha) || !bySha.has(sha)) continue;
+      claimed.add(sha);
+      const c = bySha.get(sha);
+      mine.push(c);
+      for (const p of c.parents) if (!claimed.has(p)) stack.push(p);
+    }
+    return mine;
+  };
+  // Newest first within a release, as `git log` itself would list them.
+  const summarize = (segment) => parseChangeRecords(segment
+    .filter((c) => c.parents.length > 1)
+    .sort((a, b) => position.get(a.sha) - position.get(b.sha))
+    .map((c) => `${c.subject}\x1f${c.body}\x1e`)
+    .join(''));
+
+  const byVersion = new Map();
+  let releases = 0;
+  for (let i = commits.length - 1; i >= 0; i--) {
+    const m = RELEASE_SUBJECT_RE.exec(commits[i].subject);
+    if (!m) continue;
+    releases++;
+    // A version released twice keeps both halves; the second claims only what the first
+    // could not reach.
+    byVersion.set(m[1], uniqueByText([...(byVersion.get(m[1]) || []), ...summarize(claim(commits[i].sha))]));
+  }
+  const tail = commits.filter((c) => !claimed.has(c.sha));
+  if (version && CORE_VERSION_RE.test(version) && !byVersion.has(version)
+      && [...byVersion.keys()].every((v) => compareCoreVersions(v, version) < 0)) {
+    byVersion.set(version, summarize(tail));
+  }
+  const notes = {};
+  for (const v of [...byVersion.keys()].sort(compareCoreVersions)) notes[v] = byVersion.get(v);
+  return { notes, releases, tail: tail.length };
+}
+
+/**
+ * Read a ref's history through an injected `git(args) → stdout` and build its notes.
+ * Returns `{ notes, releases, tail }`, or `{ skipped }` saying why there are none — never
+ * a partial answer presented as a whole one.
+ */
+function generateReleaseNotes({ git, ref, version }) {
+  let shallow;
+  try { shallow = String(git(['rev-parse', '--is-shallow-repository'])).trim() === 'true'; }
+  catch (e) { return { skipped: `could not ask git about this clone (${firstLine(e)})` }; }
+  // A depth-limited clone reaches a handful of commits, and notes built from it would
+  // credit the newest release with everything the clone happens to hold.
+  if (shallow) return { skipped: 'this is a shallow clone, so it carries no release history' };
+  let out;
+  try { out = git([...LOG_ARGS, ref]); }
+  catch (e) { return { skipped: `could not read the history of ${ref} (${firstLine(e)})` }; }
+  const built = buildReleaseNotes(parseLogRecords(out), { version });
+  if (!built.releases) return { skipped: 'this history holds no release commits' };
+  return built;
+}
+
+function firstLine(e) {
+  return String((e && e.message) || e || '').trim().split('\n')[0].slice(0, 160);
+}
+
+/** The file's bytes: the same pretty-printed JSON the package's other generated files use. */
+function serializeReleaseNotes(notes) {
+  return Buffer.from(`${JSON.stringify(notes, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Hold the file under `maxBytes` by dropping the OLDEST releases. PURE.
+ * Returns `{ notes, dropped }`; the newest release is always kept.
+ */
+function boundReleaseNotes(notes, maxBytes = RELEASE_NOTES_MAX_BYTES) {
+  const versions = Object.keys(notes);
+  const keep = (from) => Object.fromEntries(versions.slice(from).map((v) => [v, notes[v]]));
+  const fits = (from) => serializeReleaseNotes(keep(from)).length <= maxBytes;
+  if (versions.length <= 1 || fits(0)) return { notes, dropped: [] };
+  // The fewest drops that fit, by bisection — the size only shrinks as more are dropped.
+  let lo = 1;
+  let hi = versions.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (fits(mid)) hi = mid; else lo = mid + 1;
+  }
+  return { notes: keep(lo), dropped: versions.slice(0, lo) };
+}
+
+/**
+ * The entries for every release in `(from, to]`, newest release first. PURE.
+ *
+ * Returns `{ entries }` or `{ uncovered }` — a phrase saying why these notes cannot answer,
+ * worded to follow "the release notes …". NEVER an empty list for a range the notes do not
+ * reach: an empty list reads as "nothing changed", which is exactly what a restart must not
+ * be sold as. They reach a range when they list its target and begin at or before its
+ * start: the oldest release they hold is where their knowledge begins.
+ *
+ * The file may have come off the network, so every entry is re-checked here, not trusted.
+ */
+function notesBetween(notes, from, to) {
+  if (!notes || typeof notes !== 'object' || Array.isArray(notes)) return { uncovered: 'are not a list of releases' };
+  const versions = Object.keys(notes)
+    .filter((v) => CORE_VERSION_RE.test(v) && Array.isArray(notes[v]))
+    .sort(compareCoreVersions);
+  if (!versions.includes(to)) return { uncovered: `do not list core ${to}` };
+  if (compareCoreVersions(versions[0], from) > 0) return { uncovered: `begin at core ${versions[0]}, after ${from}` };
+  const inRange = versions.filter((v) => compareCoreVersions(v, from) > 0 && compareCoreVersions(v, to) <= 0);
+  const entries = [];
+  for (const v of inRange.reverse()) {
+    for (const e of notes[v]) {
+      if (!e || typeof e.text !== 'string' || !e.text.trim()) continue;
+      const text = boundText(e.text.trim());
+      entries.push(/^\d+$/.test(String(e.id || '')) ? { id: String(e.id), text } : { text });
+    }
+  }
+  return { entries: uniqueByText(entries) };
+}
+
+module.exports = {
+  RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES,
+  parseChangeRecords, parseLogRecords, buildReleaseNotes,
+  generateReleaseNotes, serializeReleaseNotes, boundReleaseNotes, notesBetween,
+};

package/scripts/gds/seed-board-room-tasks.js

@@ -43,7 +43,7 @@ const TASKS = [
   // ---- Phase A — decide + foundation (P5) ----
   { ref:'R01', kind:'decision', disc:'engineer', prio:5, est:150, crit:[C1,C3,C4], deps:[],
     title:'R01 · ADR: the Board Room government model',
-    desc:`Record the government model as one decision so the schema has something to encode.\n\nMUST STATE: the board's TWO subjects (a Full Idea, and a change to the constitution itself) and why nothing else is votable; membership as a configured predicate resolved per request and uncached; the timed SITTING (absent votes are nulled, not blocking) and why that replaces quorum — the clock IS the deadlock exit; CONSENT rather than majority, with silence as consent and one reasoned objection returning the idea; a zero-vote close PASSING; the OPEN ballot; Discord as an outbound notification mirror that casts nothing; and the amendment rule — a constitutional change is decided under whatever rule the CURRENT constitution names, so flipping out of monarchy is a legal monarchy act.\n\nAlso record the two owner decisions taken against recommendation with their trade-offs intact: vote-karma (yes-clicking bias, accepted because item volume is too low to farm) and automatic window-open on grade pass (author loses timing control; concurrent windows become normal).\n\nGrounding: idea 1000738, idea 1000754, the Six Variables of Governance synthesis, ADR 0151 (permissions-as-atoms), ADR 0157, ADR 0162 (verdicts advisory), ADR 0174 (government/ranks/roles). ${SPEC}` },
+    desc:`Record the government model as one decision so the schema has something to encode.\n\nMUST STATE: the board's TWO subjects (a Full Idea, and a change to the constitution itself) and why nothing else is votable; membership as a configured predicate resolved per request and uncached; the timed SITTING (absent votes are nulled, not blocking) and why that replaces quorum — the clock IS the deadlock exit; CONSENT rather than majority, with silence as consent and one reasoned objection returning the idea; a zero-vote close PASSING; the OPEN ballot; Discord as an outbound notification mirror that casts nothing; and the amendment rule — a constitutional change is decided under whatever rule the CURRENT constitution names, so flipping out of monarchy is a legal monarchy act.\n\nAlso record the two owner decisions taken against recommendation with their trade-offs intact: vote-karma (yes-clicking bias, accepted because item volume is too low to farm) and automatic window-open on grade pass (author loses timing control; concurrent windows become normal).\n\nGrounding: idea 1000738, idea 1000754, the Six Variables of Governance synthesis, ADR 0151 (permissions-as-atoms), ADR 0157, ADR 0158 §2 (verdicts advisory), ADR 0162 (no human approval in the land path), ADR 0174 (government/ranks/roles). ${SPEC}` },
 
   { ref:'R02', kind:'decision', disc:'engineer', prio:5, est:90, crit:[C1], deps:['R01'],
     title:'R02 · The pass-event contract the ideator credit lane consumes',

package/scripts/gds/ship-flow.js

@@ -18,7 +18,7 @@ const { captureSurpriseLearning, promptSurprise } = require('./ship-surprise.js'
 // task 1003109: the optional `--visual` leg of a ship (goal 1000072).
 const shipVisual = require('./ship-visual.js');
 const { gitOk } = require('./ship-git.js');
-const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight } = require('./ship-preflight-steps.js');
+const { autoLinkifyChangedDocs, mergeMainIntoBranch, preflight, shipInputPaths } = require('./ship-preflight-steps.js');
 const { applyBaseOverride, computeChangedFiles, computeGraderBaseline, runSmokeAsync } = require('./ship-grade.js');
 const { buildPriorRoundContext, computeGradeResult, gradeAndRecord, printCreditsAndAchievements, printGradeOutcome } = require('./ship-grade-steps.js');
 const { apiErrorLine, normalizeApiError, isUnknownFieldRejection } = require('./ship-io.js');
@@ -196,7 +196,9 @@ async function shipMain() {
   // ---- Step 0: preflight (working tree + branch freshness) ----
   console.log(`Verifying claim #${ac.claim_id} on task #${ac.task_id}: ${ac.title}`);
   console.log('Preflight (working tree + branch freshness)...');
-  const pre = preflight(ac, { force });
+  // task 1001436: inputFiles keeps --notes-file/--summary-file/--visual out of the
+  // preflight's untracked-file warning — they are this ship's input, not its artifact.
+  const pre = preflight(ac, { force, inputFiles: shipInputPaths(args) });
   if (!pre.ok) {
     console.error('');
     console.error(`Ship aborted: ${pre.reason}. No claim resolved, no credits awarded.`);
@@ -929,7 +931,7 @@ async function regradeMain() {
   // if the local ship/grade tooling is behind main (a stale grader silently
   // fails the same way — the #662 lesson). --force overrides the freshness leg.
   console.log('Preflight (working tree + branch freshness)...');
-  const pre = preflight(claimLike, { force });
+  const pre = preflight(claimLike, { force, inputFiles: shipInputPaths(args) });
   if (!pre.ok) {
     console.error('');
     console.error(`Re-grade aborted: ${pre.reason}. Task stays at completed.`);

package/scripts/gds/ship-land.js

@@ -354,6 +354,59 @@ function redPrLines(md) {
   return red ? [red, ...plainCardLines((md && md.reason) || 'failing_check')] : [];
 }
 
+// task 1003499 — a CONFLICTING PR is a land that cannot happen, however green it is.
+// GitHub's auto-merge waits for a clean merge as well as for green checks, so a PR
+// whose branch conflicts with main sits open under a fully green rollup and never
+// merges. PR #497 sat like that for ~25 minutes while both polls below said nothing
+// and then printed "auto-merge is armed ... NOT a failure", the banner a land that IS
+// on its way gets. The server already knew (mergeBlockReason -> 'merge_conflict'); the
+// ship never asked. Pure + exported. Takes both shapes it is handed: `gh pr view`'s
+// camelCase (mergeable, mergeStateStatus) and publish-status's snake_case merge_driver
+// (mergeable, merge_state, reason). A read that failed (null) is not a conflict.
+function prConflicting(pr) {
+  if (!pr) return false;
+  const state = pr.mergeStateStatus ?? pr.merge_state;
+  return pr.mergeable === 'CONFLICTING' || state === 'DIRTY' || pr.reason === 'merge_conflict';
+}
+
+// What the poll says the moment it sees the conflict. Pure + exported so the wording
+// is pinned by tests/ship_land_conflict.mjs. The poll keeps waiting afterwards on
+// purpose: a conflict only in generated files is healed by the server's own resolver
+// on its next sweep (ADR 0082), and the PR then merges inside this same window.
+function conflictPrLines(taskId) {
+  return [
+    '  ci-land: the PR CONFLICTS with main, so auto-merge cannot fire until that is resolved, however green its checks are.',
+    '  ci-land: a conflict only in generated files is healed by the server on its next sweep (~5 min), so this keeps waiting.',
+    '  ci-land: anything hand-written waits for you. From this worktree:',
+    '    git fetch -q origin && git merge origin/main   # resolve the conflicts, commit',
+    `    node scripts/gds/ship.js ${taskId}               # resumes the land; it does not re-grade`,
+    ...plainCardLines('merge_conflict'),
+  ];
+}
+
+// noteConflict — one poll's worth of conflict tracking, shared by both loops. Prints
+// the lines above when the PR BECOMES conflicting (not on every 10s poll, and once
+// more if main moves on and undoes a heal), and returns what the PR looks like now.
+// A failed read keeps the last answer rather than inventing a new one.
+function noteConflict(taskId, pr, wasConflicting) {
+  if (!pr) return wasConflicting;
+  const now = prConflicting(pr);
+  if (now && !wasConflicting) for (const line of conflictPrLines(taskId)) console.log(line);
+  return now;
+}
+
+// landConflicted — the verdict when the wait ends with the PR STILL conflicting. It is
+// not landing on its own, so it must not print the "landing automatically" banner or
+// the land_pending card ("Nothing to do. This is normal, not a failure."): task
+// 1002541's rule that a land which is not happening must not announce itself as
+// success. No bailId, so ship-merge never reroutes it: the PR already exists and is
+// the problem. /strand-fix walks the cure (its case C: merge main in, resolve, re-ship).
+function landConflicted(taskId) {
+  console.log('');
+  console.log(`  ci-land: still CONFLICTING when the wait ended, so this will NOT land on its own. The task stays at 'confirmed' until the conflict is resolved (/strand-fix ${taskId} walks it).`);
+  return landBailed('the PR conflicts with main, so it cannot merge until the conflict is resolved', `/strand-fix ${taskId}`);
+}
+
 // One module-scope sleep command shared by both poll loops (task 1093 / C9). A
 // child `node -e setTimeout` is used (not `await new Promise`) so it blocks
 // identically in the SYNCHRONOUS pollCiDeploy and the async pollServerPublish —
@@ -366,8 +419,12 @@ const POLL_SLEEP_CMD = 'node -e "setTimeout(()=>{}, 10000)"';
 // reconciles the task to shipped when it observes merge+deploy — task 1049) until
 // the PR merges + deploy-prod succeeds. Returns true when prod is confirmed live;
 // a timeout with an armed PR is success-PENDING (the publish worked), not failure.
-async function pollServerPublish(taskId, branch) {
+// A timeout with a CONFLICTING PR is not (task 1003499): see landConflicted.
+// `deps` exists for tests/ship_land_conflict.mjs; a real ship passes none.
+async function pollServerPublish(taskId, branch, deps = {}) {
   const TRIES = 54; // ~9 min at 10s — checks + auto-merge + Actions deploy
+  const readStatus = deps.readStatus || (async (q) => (await cliClient()).tasks.getTasksIdPublishStatus(q));
+  const pause = deps.pause || (() => shellOk(POLL_SLEEP_CMD));
   console.log('  ci-land: waiting for auto-merge + prod deploy (polling the server)...');
   // task 1002645: GitHub can report merged+deployed while the SERVER refused the
   // confirmed→shipped flip (reconcile_blocked — the task-1547 land proof missed).
@@ -376,14 +433,16 @@ async function pollServerPublish(taskId, branch) {
   // pushed tip, so the proof usually heals within the window.
   let blockedReason = null;
   let redLine = null;
+  let conflicting = false;
   for (let i = 0; i < TRIES; i++) {
-    const r = await (await cliClient()).tasks.getTasksIdPublishStatus({ id: taskId, query: { branch } });
+    const r = await readStatus({ id: taskId, query: { branch } });
     if (r.ok && r.data) {
       const red = redPrLine(r.data.merge_driver);
       if (red && red !== redLine) {
         redLine = red;
         for (const line of redPrLines(r.data.merge_driver)) console.log(line);
       }
+      conflicting = noteConflict(taskId, r.data.merge_driver, conflicting);
       const outcome = classifyLandOutcome(r.data);
       if (outcome === 'shipped') {
         if (r.data.reconcile_blocked) {
@@ -401,7 +460,7 @@ async function pollServerPublish(taskId, branch) {
         return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
       }
     }
-    shellOk(POLL_SLEEP_CMD);
+    pause();
   }
   if (blockedReason) {
     console.log('');
@@ -409,6 +468,7 @@ async function pollServerPublish(taskId, branch) {
     for (const line of plainCardLines('reconcile_blocked')) console.log(line);
     return landBailed(`the PR merged but the server could not prove the land is this task's: ${blockedReason}`, `node scripts/gds/ship.js ${taskId}`);
   }
+  if (conflicting) return landConflicted(taskId);
   printLandPending(taskId);
   return landPending();
 }
@@ -723,14 +783,22 @@ async function ciLandLocal(taskId, branch, valueSummary) {
 //   3. public edge healthz -> 200 (belt-and-braces, a different vantage).
 // Times out conservatively; on any timeout the task stays at confirmed with a
 // precise next step rather than a false "shipped".
-function pollCiDeploy(taskId, branch, headSha) {
+// `deps` exists for tests/ship_land_conflict.mjs; a real ship passes none.
+function pollCiDeploy(taskId, branch, headSha, deps = {}) {
   const MERGE_TRIES = 30; // ~5 min at 10s — checks + auto-merge
   const DEPLOY_TRIES = 24; // ~4 min at 10s — Actions deploy
+  const readJson = deps.ghJson || ghJson;
+  const pause = deps.pause || (() => shellOk(POLL_SLEEP_CMD));
 
   console.log('  ci-land: waiting for auto-merge (checks + branch protection)...');
   let mergeSha = null;
+  let conflicting = false;
   for (let i = 0; i < MERGE_TRIES; i++) {
-    const pr = ghJson(['pr', 'view', branch, '--json', 'state,mergeCommit']);
+    // task 1003499: mergeable + mergeStateStatus ride the same read, so a conflict is
+    // named on the poll it appears; the two-field read is the fallback for a gh that
+    // predates those fields, which keeps this no worse than before on any machine.
+    const pr = readJson(['pr', 'view', branch, '--json', 'state,mergeCommit,mergeable,mergeStateStatus'])
+      || readJson(['pr', 'view', branch, '--json', 'state,mergeCommit']);
     if (pr && pr.state === 'MERGED') {
       mergeSha = pr.mergeCommit && pr.mergeCommit.oid;
       break;
@@ -739,11 +807,14 @@ function pollCiDeploy(taskId, branch, headSha) {
       console.log(`  ci-land: PR was CLOSED without merging (a required check failed, or it was closed manually). Fix it and re-run \`node scripts/gds/ship.js ${taskId}\` to resume. Task stays at 'confirmed'.`);
       return landBailed('the PR was closed without merging (a check failed, or it was closed manually)', `node scripts/gds/ship.js ${taskId}`);
     }
-    shellOk(POLL_SLEEP_CMD);
+    conflicting = noteConflict(taskId, pr, conflicting);
+    pause();
   }
   if (!mergeSha) {
     // task 1049: PR open + auto-merge armed but not merged in-window = the publish
-    // SUCCEEDED and is still in CI — success-pending, not a failure.
+    // SUCCEEDED and is still in CI — success-pending, not a failure. Unless it is
+    // CONFLICTING (task 1003499): then nothing is still in CI, and it never merges.
+    if (conflicting) return landConflicted(taskId);
     printLandPending(taskId);
     return landPending();
   }
@@ -811,6 +882,14 @@ module.exports = {
   prAssigneeLine,
   redPrLine,
   redPrLines,
+  // task 1003499: a CONFLICTING PR is named while the land waits, and a wait that
+  // ends conflicting is a bail, not "landing automatically". The polls are exported
+  // with their optional `deps` so the test drives the real loops.
+  prConflicting,
+  conflictPrLines,
+  landConflicted,
+  pollCiDeploy,
+  pollServerPublish,
   reconciledCardStatus,
   strandCommand,
   strandNextStep,

package/scripts/gds/ship-preflight-steps.js

@@ -11,7 +11,8 @@
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { trackedDirty, cleanupMacFinderDupRefs } = require('../../modules/lifecycle/ship-preflight');
+const { trackedDirty, cleanupMacFinderDupRefs, untrackedLeftBehind, untrackedWarningLines } = require('../../modules/lifecycle/ship-preflight');
+const { arg } = require('./cli-lib');
 const mergeRegen = require('./git-merge-regen');
 const { argvOut, gitArgvOk, gitOk } = require('./ship-git.js');
 const { pushVia } = require('./ship-deploy-target.js');
@@ -40,6 +41,36 @@ function parseDeletedUpstreamPaths(rawLogOutput) {
   return [...new Set(rawLogOutput.split('\n').map((s) => s.trim()).filter(Boolean))];
 }
 
+// shipInputPaths — the repo-relative paths of the files a ship was HANDED as input
+// (task 1001436), so preflight's untracked-file warning never lists them. The
+// builder-ship skill writes notes.md + summary.txt into the worktree and passes them
+// here; left in, they would put the warning on nearly every ship and teach everyone
+// to skip it. `-` (stdin), a missing value and a path outside the checkout add
+// nothing — a file outside the tree cannot be an untracked file in it. Both sides go
+// through realpath, so a /var vs /private/var spelling of one file still matches.
+// `cwd`, `repoRoot` and `realpath` are injectable for the unit test.
+const SHIP_INPUT_FLAGS = ['--notes-file', '--summary-file', '--response-file', '--visual'];
+
+function safeRealpath(p) {
+  try { return fs.realpathSync.native(p); } catch (_) { return path.resolve(p); }
+}
+
+function shipInputPaths(args, { cwd = process.cwd(), repoRoot = null, realpath = safeRealpath } = {}) {
+  const root = realpath(repoRoot || gitOk('git rev-parse --show-toplevel') || cwd);
+  const out = [];
+  for (const flag of SHIP_INPUT_FLAGS) {
+    const value = arg(flag, args || []);
+    if (typeof value !== 'string' || value === '' || value === '-' || value.startsWith('--')) continue;
+    const rel = path.relative(root, realpath(path.resolve(cwd, value)));
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    out.push(rel.split(path.sep).join('/'));
+  }
+  return out;
+}
+
+// opts: { force, inputFiles } — inputFiles is shipInputPaths(args) from the caller;
+// omitted (the resume path has no prose flags), nothing is excluded from the
+// untracked-file warning.
 function preflight(claim, opts = {}) {
   // (a) Working-tree check — refuse if any TRACKED file carries an uncommitted
   // modification or staged change. This fires post-commit, so a clean tree
@@ -145,8 +176,29 @@ function preflight(claim, opts = {}) {
     }
   }
 
-  console.log(`  preflight: working tree clean, branch ${behind} commits behind main, ship tooling current — OK`);
-  return { ok: true };
+  // (e) Untracked-file warning (task 1001436) — WARN-ONLY, never blocks, never
+  // changes the exit code. Step (a) ignores untracked files so scratch cannot
+  // false-refuse a ship, which also meant a NEW deliverable left un-added beside
+  // committed work shipped without it, in silence (the residual of the task-1363
+  // phantom ship). This names those files while stopping is still free. It needs
+  // committed work to warn about — upstreamDelTouched is this branch's committed
+  // diff from step (d); with none, the empty-diff guard already refuses and lists
+  // them. Its own `git status`, on purpose: --untracked-files=all names each file
+  // rather than a collapsed `dir/`, so the ship's input files can be excluded
+  // exactly; and a failed or oversized read here stays a skipped warning, never a
+  // blank porcelain for the refusal in step (a).
+  const untrackedPorcelain = gitOk('git status --porcelain --untracked-files=all', { maxBuffer: 64 * 1024 * 1024 });
+  const leftBehind = untrackedLeftBehind(untrackedPorcelain, {
+    committedFileCount: upstreamDelTouched.length,
+    inputs: opts.inputFiles || [],
+  });
+  for (const line of untrackedWarningLines(leftBehind, { taskId: claim && claim.task_id })) console.error(line);
+
+  const treeState = leftBehind.length > 0
+    ? `tracked files clean (${leftBehind.length} untracked file(s) will not ship — see the warning)`
+    : 'working tree clean';
+  console.log(`  preflight: ${treeState}, branch ${behind} commits behind main, ship tooling current — OK`);
+  return { ok: true, untrackedLeftBehind: leftBehind };
 }
 
 // mergeMainIntoBranch — pull origin/main INTO the current feature branch BEFORE
@@ -320,4 +372,5 @@ module.exports = {
   mergeMainIntoBranch,
   parseDeletedUpstreamPaths,
   preflight,
+  shipInputPaths,
 };

package/scripts/gds/stray-unit-sweep.sh

@@ -31,7 +31,9 @@ ETC=/etc/systemd/system
 CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 case "$CORE_DIR" in */node_modules/@bongos/core) INSTANCE_DIR="${INSTANCE_DIR:-${CORE_DIR%/node_modules/@bongos/core}}" ;; esac
 [ -n "${PROVISION_APP_USER:-}${INSTANCE_DIR:-}" ] || { echo "set INSTANCE_DIR to the control plane's instance checkout (or PROVISION_APP_USER) — this sweep is not running from one"; exit 1; }
-APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null)}"
+# Owner by name: GNU stat `-c %U`, else BSD/macOS stat `-f %Su` — each refuses the other's
+# flag (task 1004170), the same lookup address-park-sweep.sh makes.
+APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null || stat -f %Su "$INSTANCE_DIR" 2>/dev/null)}"
 if [ "$APP_USER" = root ] || ! [[ "$APP_USER" =~ ^[a-z_][a-z0-9_-]{0,31}$ ]]; then
   echo "cannot use '$APP_USER' as the app account — set PROVISION_APP_USER to the unprivileged account that owns ${INSTANCE_DIR:-the instance checkout}"; exit 1
 fi

package/scripts/gds/upgrade-migrate.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// scripts/gds/upgrade-migrate.js — WHICH command `bongos upgrade` migrates an instance
+// with (task 1004274, found preparing the task 1004047 catch-up pass). Kept out of
+// upgrade.js, which sits at the 1500-line cap.
+//
+// THE GAP. upgrade.js migrated with `npm run migrate`, and that only works where the
+// instance's package.json DECLARES a migrate script. A greenfield scaffold always does
+// (init.js buildInstancePackageJson writes INSTANCE_MIGRATE_SCRIPT), but the ADOPT layer
+// does not: init.js mergeCoreDependency adds the core dependency and nothing else, and
+// for a repo that had no package.json of its own it mints `{ name, private,
+// dependencies }`. So an adopted project that is not a JavaScript app has no scripts at
+// all. There `npm run migrate` answers "Missing script" — AFTER the pin has moved and
+// the new core is installed — and the upgrade rolls itself back, restarting someone's
+// live app to change nothing. mercury (a Python/Flask project; its package.json is
+// exactly name/private/dependencies) is that shape, and it is why the catch-up pass
+// could not reach it. The dry run could not warn either, because it never looked.
+//
+// THE FALLBACK IS NOT A NEW MIGRATION PATH. It is the command a scaffold's own script
+// IS, and the one the control plane ran to create that instance's database at stand-up
+// (provision-repo.js standaloneMigrateCmd): the installed core's scripts/migrate.sh,
+// run from the instance root. A declared script still wins, whatever it says — an
+// owner who wrote their own migrate step meant it — and `--skip-migrate` stays the
+// only way to run no migration at all, which on a real jump leaves the new code
+// running against the old schema.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Relative to the instance root, POSIX on purpose: it is an argument to bash, and it
+// must stay byte-identical to the scaffold's script (tests/upgrade_migrate.mjs pins it
+// against init.js INSTANCE_MIGRATE_SCRIPT).
+const CORE_MIGRATE_SCRIPT = 'node_modules/@bongos/core/scripts/migrate.sh';
+
+/**
+ * How this instance is migrated: its own declared script, or the core's migrate.sh.
+ *
+ * Only a package.json we could READ, and that names no migrate script, earns the
+ * fallback. A missing or unparseable one keeps the old command, which then fails the
+ * way it always did — guessing at a file this could not parse would be worse.
+ *
+ * `env` exists only on the fallback, and only to hand migrate.sh what `npm run` would:
+ * migrate.sh finds the instance from INIT_CWD before its own cwd (task 2180), and npm
+ * sets it to the directory the script runs in. Launched directly, a stray INIT_CWD
+ * inherited from whoever started this upgrade would aim it at the wrong project.
+ *
+ * `note` is a pre-flight line, so the dry run says which command the move will run.
+ */
+function migratePlan(instanceDir, { fsImpl = fs, env = process.env } = {}) {
+  let pkg = null;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(instanceDir, 'package.json'), 'utf8')); } catch { /* absent or unreadable */ }
+  const scripts = pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
+  const declared = typeof scripts.migrate === 'string' && scripts.migrate.trim() !== '';
+  if (!pkg || declared) {
+    return { via: 'npm-script', cmd: 'npm', args: ['run', 'migrate'], label: 'npm run migrate', env: null, note: null };
+  }
+  return {
+    via: 'core-script',
+    cmd: 'bash',
+    args: [CORE_MIGRATE_SCRIPT],
+    label: `bash ${CORE_MIGRATE_SCRIPT}`,
+    env: { ...env, INIT_CWD: instanceDir },
+    note: 'migrate: this project declares no migrate script (an adopted repo), so the core\'s own scripts/migrate.sh will run — the command a scaffold\'s script runs',
+  };
+}
+
+module.exports = { migratePlan, CORE_MIGRATE_SCRIPT };