@futurelastic/colab-handbook 1.14.0-rc.8 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/tools/colab CHANGED
@@ -70,6 +70,8 @@ const shipBatch = require('./lib/ship-batch');
70
70
  const batchStats = require('./lib/batch-stats');
71
71
  const conflictMarkers = require('./lib/conflict-markers');
72
72
  const docsOnly = require('./lib/docs-only');
73
+ const integrationProfile = require('./lib/integration-profile');
74
+ const secretScan = require('./lib/secret-scan'); // #606
73
75
  const configSet = require('./lib/config-set'); // #561
74
76
  const cureDiff = require('./lib/cure-diff');
75
77
  const codeowners = require('./lib/codeowners');
@@ -87,6 +89,7 @@ const localAdopt = require('./lib/local-adopt'); // #393
87
89
  const ownerBranch = require('./lib/owner-branch'); // #394
88
90
  const humanDoor = require('./lib/ship-human-door'); // #525
89
91
  const instructionGate = require('./lib/instruction-gate'); // #588
92
+ const instructionFile = require('./lib/instruction-file'); // #602
90
93
  const {
91
94
  HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
92
95
  parseArgs, table, shortRepo,
@@ -1708,8 +1711,17 @@ function cmdReleaseCut(argv) {
1708
1711
  }
1709
1712
  }
1710
1713
 
1714
+ // #610: on a final route the heavy lane must be green at this sha. Under --auto (the release
1715
+ // workflow) a missing run is started here, once, and the run no-ops until it is green.
1716
+ let heavy = null;
1717
+ if (fast || library) {
1718
+ const lane = heavyLaneAt(repoAbs, doc, sha);
1719
+ heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
1720
+ if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1721
+ }
1722
+
1711
1723
  const verdict = releaseCut.decide({
1712
- policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
1724
+ policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
1713
1725
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1714
1726
  finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1715
1727
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
@@ -1994,6 +2006,16 @@ function readRegressionEdges(repoAbs, num) {
1994
2006
  }
1995
2007
  }
1996
2008
 
2009
+ /**
2010
+ * #610: the heavy lane at a release candidate, as release-finalize.js decide()'s `heavy` fact. Read
2011
+ * the same way ship's gated landing reads it (heavyLaneAt). Inside the release workflow the heavy
2012
+ * lane is a separate workflow, never the one running, so #425's own-workflow filter does not apply.
2013
+ */
2014
+ function releaseHeavyFact(repoAbs, doc, cand) {
2015
+ const lane = heavyLaneAt(repoAbs, doc, cand.sha);
2016
+ return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
2017
+ }
2018
+
1997
2019
  function cmdReleaseFinalize(argv) {
1998
2020
  const opts = parseArgs(argv, {
1999
2021
  values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
@@ -2136,6 +2158,7 @@ function cmdReleaseFinalize(argv) {
2136
2158
  const verdict = releaseFinalize.decide({
2137
2159
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2138
2160
  ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2161
+ heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
2139
2162
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2140
2163
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2141
2164
  });
@@ -9315,6 +9338,13 @@ async function cmdAdopt(argv) {
9315
9338
  : `detected (the repo's default branch, ${nowDate})`;
9316
9339
  entries.push({ key: 'trunk', value: extra.trunk, comment: `# trunk: ${trunkNote}` });
9317
9340
  }
9341
+ // #602: on a fork, the instruction-file check cannot see the `upstream` remote in CI — so the
9342
+ // fork verdict above (adoptDetectFork, the one fork test) is recorded as the key CI reads.
9343
+ // Detected, never asked, like trunk and stack; never written over an existing declaration.
9344
+ if (extra.fork && !(instructionFile.INSTRUCTION_FILES_KEY in cfg)) {
9345
+ entries.push({ key: instructionFile.INSTRUCTION_FILES_KEY, value: 'upstream',
9346
+ comment: `# instruction-files: detected — a fork (${extra.fork.source === 'flag' ? '--fork' : `remote "${extra.fork.remote}"`}, ${nowDate}); CLAUDE.md/AGENTS.md are the upstream's, so the instruction-file check leaves them unjudged (CONVENTIONS.md §9, #602)` });
9347
+ }
9318
9348
  if (!('stack' in cfg)) {
9319
9349
  if (opts.stack !== undefined) {
9320
9350
  const stackNote = stackAnsweredInteractively
@@ -9972,7 +10002,9 @@ What this command will NOT do, by design:
9972
10002
  • It skips the handbook repo itself.
9973
10003
 
9974
10004
  Exit code: 0 when nothing is behind, 1 when anything is behind — the frozen copy included,
9975
- since a stale CLI is as much a thing to act on as a stale workflow. 2 on usage error.
10005
+ since a stale CLI is as much a thing to act on as a stale workflow — except a CI template
10006
+ (\`ci-*\`) copy: CI templates are guidance, so one behind is reported but never exits 1 (#607).
10007
+ 2 on usage error.
9976
10008
  `;
9977
10009
 
9978
10010
  function cmdUpdate(argv) {
@@ -10047,7 +10079,11 @@ function cmdUpdate(argv) {
10047
10079
  skippedRepos: repos.filter((r) => !r.artifacts.length).length,
10048
10080
  refreshable: all.filter((a) => a.state === 'behind' && a.applicable && !a.written).length,
10049
10081
  written: written.length,
10082
+ // #607: a CI template is guidance — a `ci-*` copy behind its template is a suggestion, counted in
10083
+ // `behind` (it can still be refreshed) but never what makes this command exit 1.
10084
+ suggestions: all.filter((a) => a.state === 'behind' && /^ci-/.test(a.template || '')).length,
10050
10085
  };
10086
+ const actionable = summary.behind - summary.suggestions;
10051
10087
 
10052
10088
  if (opts.json) {
10053
10089
  print(JSON.stringify({
@@ -10057,7 +10093,7 @@ function cmdUpdate(argv) {
10057
10093
  applied: !!opts.apply,
10058
10094
  repos, written, failed, frozen, summary,
10059
10095
  }, null, 2));
10060
- return summary.behind > 0 || frozen.state === 'behind' ? 1 : 0;
10096
+ return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
10061
10097
  }
10062
10098
 
10063
10099
  // --- report ------------------------------------------------------------
@@ -10100,6 +10136,9 @@ function cmdUpdate(argv) {
10100
10136
  `${summary.current} current, ${summary.behind} behind, ${summary.diverged} diverged, ` +
10101
10137
  `${summary.unstamped} unstamped, ${summary.na} n-a` +
10102
10138
  (summary.unrelated ? `, ${summary.unrelated} unrelated (name clash only — not ours).` : '.'));
10139
+ if (summary.suggestions) {
10140
+ print(`${summary.suggestions} of the behind copies are CI templates — guidance, adopt what helps; they never fail this command (#607).`);
10141
+ }
10103
10142
  if (summary.skippedRepos) {
10104
10143
  print(`${summary.skippedRepos} repo(s) had nothing to assess (nothing adopted, an audit-only slug, a missing path, or the handbook itself).`);
10105
10144
  }
@@ -10134,7 +10173,7 @@ function cmdUpdate(argv) {
10134
10173
  print(' --apply never touches it: it is the toolchain your always-on services are running.');
10135
10174
  }
10136
10175
 
10137
- return summary.behind > 0 || frozen.state === 'behind' ? 1 : 0;
10176
+ return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
10138
10177
  }
10139
10178
 
10140
10179
  // ---------------------------------------------------------------------------
@@ -10484,7 +10523,12 @@ function migDetail(migrations, grants, target, branch, ctx) {
10484
10523
  * from its base. An empty result is now left empty; the caller decides what to say about it
10485
10524
  * (buildSquashMessage below), rather than this layer inventing a commit to hide it.
10486
10525
  */
10487
- function branchCommits(mainRoot, trunk, branch) {
10526
+ function branchCommits(mainRoot, trunk, branchName) {
10527
+ // #603: read the branch through the ref it resolves to. A hand-off branch (or any --branch with no
10528
+ // local ref) is remote-only on the lander, and a bare name does not DWIM to refs/remotes/<remote>/
10529
+ // — the log failed, the list came back empty, and the squash subject read "(none …)" on a branch
10530
+ // that has commits. shipRefFor is local || remote || the name itself, so a sha passes unchanged.
10531
+ const branch = shipRefFor(mainRoot, branchName);
10488
10532
  const mb = git.git(['merge-base', trunk, branch], mainRoot);
10489
10533
  const base = mb.ok && mb.stdout ? mb.stdout : trunk;
10490
10534
  const logShas = git.git(['log', '--first-parent', `${base}..${branch}`, '--no-merges', '--format=%H'], mainRoot);
@@ -10508,7 +10552,7 @@ function commitFiles(mainRoot, sha) {
10508
10552
 
10509
10553
  /** Files the whole branch changed against its base — the denominator for the same signal. */
10510
10554
  function branchChangedFiles(mainRoot, base, branch) {
10511
- const r = git.git(['diff', '--name-only', `${base}...${branch}`], mainRoot);
10555
+ const r = git.git(['diff', '--name-only', `${base}...${shipRefFor(mainRoot, branch)}`], mainRoot); // #603: same remote-only gap
10512
10556
  return r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : [];
10513
10557
  }
10514
10558
 
@@ -10582,7 +10626,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10582
10626
  }
10583
10627
 
10584
10628
  const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
10585
- colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10629
+ colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
10586
10630
 
10587
10631
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10588
10632
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10627,6 +10671,10 @@ Sequence (each step gated; any failure aborts before the push — the target is
10627
10671
  and worktree untouched. Re-run the same command once an account other than the
10628
10672
  author approved the branch's CURRENT head: it lands by the ordinary squash below
10629
10673
  and closes the PR. Accounts sharing one login cannot approve each other.
10674
+ b5. heavy lane (#610) only with integration-profile: gated, never for a docs-only change:
10675
+ the heavy workflow (heavy-workflow:, default ci-heavy.yml) green at the
10676
+ branch's remote head. None yet → a real ship dispatches it and PAUSES —
10677
+ "⏸ HEAVY-PENDING", exit 3, nothing merged; running → the same pause; red → ✗.
10630
10678
  c. B0 sync merge the target INTO the branch; non-generated conflict → abort (human merge);
10631
10679
  generated-only conflict → repo's .colab/hooks/pre-ship regenerates, else abort
10632
10680
  d. B1 squash re-check CI green, then squash-merge branch → target (Closes every claimed issue,
@@ -10871,7 +10919,20 @@ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref
10871
10919
  combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
10872
10920
  \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
10873
10921
  'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
10874
- A red batch, or one with no run / not landed past that grace, holds nothing.
10922
+ A red batch, or one with no run / not landed past that grace, holds nothing. A TRUNK RED: cure is never held.
10923
+ SPECULATIVE CHAIN (#605): --onto ship-batch/<sha7> builds the batch on that in-flight batch's HEAD
10924
+ instead of trunk's tip, named ship-batch/<parent-head-sha7> (one batch per base still holds). The chain
10925
+ is read from ls-remote alone: a ref's parent is the ref whose head its name starts with, and it is kept
10926
+ while that chain ends at a batch on trunk's tip (at most ${shipBatch.MAX_CHAIN_DEPTH} deep); a ref whose parent is gone or rebuilt,
10927
+ or whose root trunk moved past, is deleted by the next --batch call (its run cancelled if still going).
10928
+ - refused (1): the named ref has no combined run in flight or green, is not rooted at trunk's tip,
10929
+ or is already ${shipBatch.MAX_CHAIN_DEPTH} deep; a member the chain below already carries does not join (✗, the rest go on);
10930
+ - lands in order: green and its parent not landed yet → ⏸ BATCH-CHAINED (exit 3); once trunk's tip IS
10931
+ the parent's head, the same command (with or without --onto) lands it — no second build, no second run;
10932
+ - declined (4): the parent is red, gone, or trunk moved some other way — the child is deleted, → SERIAL.
10933
+ Every ref of a chain rooted at trunk's tip holds the lane, exactly as one batch does.
10934
+ --dry --json: one JSON document on stdout ({ batch: { ref, parentRef, rootSha, base, depth, step, exit,
10935
+ members: [{ branch, sha, eligible, inBatch, why }] } }), the prose on stderr.
10875
10936
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
10876
10937
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
10877
10938
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
@@ -11444,6 +11505,13 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
11444
11505
  via = `${trunk} (by commit — the branch-filtered read was empty)`;
11445
11506
  }
11446
11507
  }
11508
+ // #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
11509
+ // docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
11510
+ // newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
11511
+ if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
11512
+ const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
11513
+ if (door) return door;
11514
+ }
11447
11515
  const at = `${via}@${shortSha(run.sha)}`;
11448
11516
  let verdict = classifyCiRun(repoAbs, run, at);
11449
11517
  // #413: still no run anywhere at a trunk sha committed minutes ago — the run may not exist YET
@@ -11622,6 +11690,75 @@ function baseCiAdvisory(repoAbs, gh, base, branch) {
11622
11690
  };
11623
11691
  }
11624
11692
 
11693
+ /**
11694
+ * #606: trunk's tip is docs-only and has no finished run — read trunk CI at the newest first-parent
11695
+ * ancestor that is NOT docs-only (tools/lib/docs-only.js commitChanges, narrowed by trunk's
11696
+ * `ci-docs-skip`). Returns a readCiVerdict result, or null when the door does not apply: the repo
11697
+ * declared `ci-docs-skip: off` (or an invalid value), the tip is not local or not docs-only, no code
11698
+ * commit within DOCS_TIP_WALK commits, or that commit's runs are unreadable. A null keeps every
11699
+ * existing reading of the tip unchanged — the door only ever answers for a docs-only tip.
11700
+ */
11701
+ const DOCS_TIP_WALK = 50;
11702
+ function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
11703
+ if (!tipSha) return null;
11704
+ const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
11705
+ if (!setting.on) return null;
11706
+ const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
11707
+ if (!list.ok) return null;
11708
+ let skipped = 0;
11709
+ let code = null;
11710
+ for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
11711
+ const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
11712
+ if (!c.docsOnly) { code = sha; break; }
11713
+ skipped++;
11714
+ }
11715
+ if (!code || skipped === 0) return null;
11716
+ const run = git.ghRunForCommitAnyRef(repoAbs, code, undefined, readOpts);
11717
+ if (!run) return null;
11718
+ const at = `${trunk}@${shortSha(code)}`;
11719
+ const v = classifyCiRun(repoAbs, run, at);
11720
+ const note = `docs-only tip (#606): ${trunk}@${shortSha(tipSha)}${skipped > 1 ? ` and ${skipped - 1} commit(s) below it` : ''} change only documentation, so trunk CI is read at the newest code commit — `;
11721
+ const verdict = { ...v, detail: note + v.detail, docsOnlyTip: { tip: tipSha, read: code, skipped } };
11722
+ return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
11723
+ }
11724
+
11725
+ /**
11726
+ * #606: is this branch DOCS-ONLY for CI purposes — so `colab ship` lands it without waiting for CI?
11727
+ * tools/lib/docs-only.js shipDocsOnly (the #345 rule, narrowed by `ci-docs-skip`, off by `off`),
11728
+ * measured on the ref ship would land. When it applies, the secret check runs too
11729
+ * (tools/lib/secret-scan.js) — the suite's own secret scan may never see this change.
11730
+ * Returns `{ applies, files, reason, scan }`; `scan` only when `applies`.
11731
+ */
11732
+ function shipDocsOnlyCi(repoAbs, doc, target, branch) {
11733
+ const ref = shipRefFor(repoAbs, branch);
11734
+ const d = docsOnly.shipDocsOnly(git, repoAbs, target, ref, doc);
11735
+ if (!d.docsOnly) return { applies: false, files: d.files, reason: d.reason, scan: null };
11736
+ return { applies: true, files: d.files, reason: d.reason, scan: secretScan.scanBranch(git, repoAbs, target, ref) };
11737
+ }
11738
+
11739
+ /** #606: the 🚢 comment's evidence clause for a docs-only ship — files, and the trunk sha CI was read at. */
11740
+ function docsOnlyEvidence(dc, ci) {
11741
+ if (!dc || !dc.applies) return '';
11742
+ const tip = ci && ci.docsOnlyTip;
11743
+ const read = tip ? ` — trunk CI read at ${shortSha(tip.read)}, the newest code commit below the docs-only tip ${shortSha(tip.tip)}` : ' — trunk CI read at its tip';
11744
+ return ` — docs-only: CI not required (${dc.files} files)${read}; secret check clean`;
11745
+ }
11746
+
11747
+ /**
11748
+ * #606: the branch-run row for a docs-only branch, in place of #395's stale-base row. CI is not
11749
+ * required, so no run, a run in flight, or a run measured on an older base is fine — but a run that
11750
+ * EXISTS at the pushed head and finished red still refuses: ship never overrides a red verdict.
11751
+ */
11752
+ function docsOnlyBranchRow(dc, stale) {
11753
+ const run = stale && stale.run;
11754
+ const red = !!run && run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
11755
+ if (red) {
11756
+ return { ok: false, class: HUMAN_GATED,
11757
+ detail: `docs-only (${dc.files} files), but the branch's own run at ${shortSha(stale.headSha)} finished ${run.conclusion || 'red'} — CI is not required here, and a red verdict is still never overridden (#606)` };
11758
+ }
11759
+ return { ok: true, class: null, detail: `docs-only: CI not required (${dc.files} files) — the branch's own run is not awaited (#606; ${stale ? stale.verdict : 'unread'})` };
11760
+ }
11761
+
11625
11762
  /**
11626
11763
  * #395: does the branch's CI verdict cover the CURRENT `base`? A PRECONDITION, unlike
11627
11764
  * `baseCiAdvisory` above: serial ship syncs the base in locally (B0) and squashes without the synced
@@ -11650,7 +11787,8 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
11650
11787
  if (contains === false && git.git(['diff', '--quiet', `${baseTip}...${headSha}`], repoAbs).code === 0) contains = 'no-change';
11651
11788
  }
11652
11789
  if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
11653
- return staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh });
11790
+ // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
11791
+ return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh }), run, headSha };
11654
11792
  }
11655
11793
 
11656
11794
  /**
@@ -12455,13 +12593,28 @@ function cmdShipDryJson(opts) {
12455
12593
  // read is exempt: the batch grades the COMBINED head (trunk + every member), which is exactly the
12456
12594
  // re-run this row demands of a serial land, so a member behind trunk is the ordinary case there.
12457
12595
  const staleJson = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
12458
- if (opts._batchMember) {
12596
+ // #606: a docs-only branch needs no CI of its own — its row replaces the stale-base one, and the
12597
+ // secret check stands in for the suite's secret scan. Same producers as the prose path.
12598
+ const docsCiJson = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
12599
+ if (docsCiJson.applies) {
12600
+ const row = docsOnlyBranchRow(docsCiJson, staleJson);
12601
+ checks.push({ name: 'branch CI (docs-only, #606)', ok: row.ok, class: row.class, verdict: staleJson.verdict, detail: row.detail });
12602
+ checks.push({ name: 'docs-only secret check (#606)', ok: docsCiJson.scan.ok, class: docsCiJson.scan.ok ? null : HUMAN_GATED, detail: docsCiJson.scan.reason });
12603
+ } else if (opts._batchMember) {
12459
12604
  checks.push({ name: 'branch run contains current base (#395)', ok: true, class: null, verdict: staleJson.verdict,
12460
12605
  detail: `batch member — the combined run grades it (${staleJson.detail})` });
12461
12606
  } else {
12462
12607
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
12463
12608
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
12464
12609
  }
12610
+ // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
12611
+ // its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
12612
+ const heavyJson = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCiJson.applies, batchMember: !!opts._batchMember });
12613
+ if (heavyJson) {
12614
+ checks.push({ name: 'heavy lane green (integration-profile: gated, #610)', ok: heavyJson.ok,
12615
+ class: heavyJson.ok ? null : (heavyJson.action === 'refuse' ? HUMAN_GATED : SELF_CLEARING),
12616
+ action: heavyJson.action, detail: heavyJson.detail });
12617
+ }
12465
12618
 
12466
12619
  // #350: same single producer as the prose path. 'pending' is not a failure — it is `mode`.
12467
12620
  const coreReviewJson = shipCoreReview(repoAbs, gh, target, sess.branch);
@@ -12547,7 +12700,7 @@ function cmdShipDryJson(opts) {
12547
12700
  // lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
12548
12701
  // Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
12549
12702
  if (!dryMode.evidenceClose && !opts._batchMember) {
12550
- const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
12703
+ const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResultJson);
12551
12704
  if (laneJson) {
12552
12705
  checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
12553
12706
  detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
@@ -13422,7 +13575,7 @@ function shipRefFor(repoAbs, branch) {
13422
13575
 
13423
13576
  function cmdShip(argv) {
13424
13577
  const opts = parseArgs(argv, {
13425
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
13578
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff', '--onto': 'onto' },
13426
13579
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
13427
13580
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
13428
13581
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -13442,6 +13595,9 @@ function cmdShip(argv) {
13442
13595
  if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-url> (#591, see `colab ship --help`)');
13443
13596
  if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
13444
13597
  if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
13598
+ if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
13599
+ if (opts.onto && !shipBatch.parseBatchRef(opts.onto)) throw new UserError(`--onto ${opts.onto}: not a batch ref — expected ship-batch/<sha7> (#605)`);
13600
+ if (opts.batch && opts.json) return cmdShipBatchJson(opts); // #605: the batch's facts as JSON, prose on stderr
13445
13601
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
13446
13602
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
13447
13603
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -13633,7 +13789,24 @@ function cmdShip(argv) {
13633
13789
  // #395: the branch's run must have been measured on a head that contains the base's CURRENT tip —
13634
13790
  // B0 below syncs locally and never re-runs CI, so this is the only place a stale verdict is caught.
13635
13791
  const staleResult = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
13636
- checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13792
+ // #606: a docs-only branch needs no CI of its own — this row replaces the stale-base one (a red
13793
+ // run that exists still refuses), and the secret check stands in for the suite's secret scan.
13794
+ const docsCi = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
13795
+ let docsRowOk = true;
13796
+ if (docsCi.applies) {
13797
+ const row = docsOnlyBranchRow(docsCi, staleResult);
13798
+ checks.push([row.ok ? '✓' : '✗', 'branch CI (docs-only, #606)', row.detail]);
13799
+ checks.push([docsCi.scan.ok ? '✓' : '✗', 'docs-only secret check (#606)', docsCi.scan.reason]);
13800
+ docsRowOk = row.ok && docsCi.scan.ok;
13801
+ } else {
13802
+ checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13803
+ }
13804
+ // #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
13805
+ // heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
13806
+ // heavy lane at all, fails the table.
13807
+ const heavyGate = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCi.applies });
13808
+ if (heavyGate) checks.push([heavyGate.ok ? '✓' : (heavyGate.action === 'refuse' ? '✗' : '⏸'), 'heavy lane green (integration-profile: gated, #610)', heavyGate.detail]);
13809
+ const heavyOk = !heavyGate || heavyGate.action !== 'refuse';
13637
13810
 
13638
13811
  // #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
13639
13812
  // taken below once every real precondition has passed, so it is the ONLY thing between the branch
@@ -13644,7 +13817,7 @@ function cmdShip(argv) {
13644
13817
 
13645
13818
  // #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
13646
13819
  // hold is not a failed precondition — it is a pause, taken below once every real one has passed.
13647
- const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
13820
+ const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult);
13648
13821
  if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
13649
13822
  for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
13650
13823
 
@@ -13659,7 +13832,7 @@ function cmdShip(argv) {
13659
13832
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
13660
13833
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
13661
13834
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
13662
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && staleResult.ok && coreOk && recOk;
13835
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
13663
13836
 
13664
13837
  // ---- report the table ----
13665
13838
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -13882,6 +14055,8 @@ function cmdShip(argv) {
13882
14055
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
13883
14056
  } else if (lane && lane.held && coreReview.verdict !== 'pending') {
13884
14057
  print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
14058
+ } else if (heavyGate && !heavyGate.ok && coreReview.verdict !== 'pending') {
14059
+ print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${heavyGate.action === 'dispatch' ? `a real ship dispatches ${heavyGate.file} at ${shortSha(heavyGate.sha)}` : 'the heavy lane is not green yet'} (integration-profile: gated, #610); run again once it is green`);
13885
14060
  } else if (coreReview.verdict === 'pending') {
13886
14061
  print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
13887
14062
  'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
@@ -13950,6 +14125,14 @@ function cmdShip(argv) {
13950
14125
  // ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
13951
14126
  if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
13952
14127
 
14128
+ // ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
14129
+ if (heavyGate && !heavyGate.ok) {
14130
+ print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
14131
+ if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
14132
+ else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
14133
+ return 3;
14134
+ }
14135
+
13953
14136
  // ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
13954
14137
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
13955
14138
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
@@ -14024,6 +14207,18 @@ function cmdShip(argv) {
14024
14207
  return 1;
14025
14208
  }
14026
14209
  }
14210
+ // #606: the same for the docs-only CI path — B0 may have made the change something CI must see,
14211
+ // or added a line the secret check has not read. Re-measured on the synced branch.
14212
+ if (docsCi.applies) {
14213
+ const again = docsOnly.shipDocsOnly(git, repoAbs, mergeRef, sess.branch, doc);
14214
+ const rescan = again.docsOnly ? secretScan.scanBranch(git, repoAbs, mergeRef, sess.branch) : null;
14215
+ if (!again.docsOnly || !rescan.ok) {
14216
+ cleanupEphemeral();
14217
+ process.stderr.write(`✗ B1: the docs-only CI path (#606) no longer holds after B0 sync — ${again.docsOnly ? rescan.reason : again.reason}. Nothing pushed.\n`);
14218
+ process.stderr.write(` Push the synced branch and re-run once its CI run completes (\`git push origin ${sess.branch}\`, then \`colab ship\` again) — or remove the finding first if the secret check refused.\n`);
14219
+ return 1;
14220
+ }
14221
+ }
14027
14222
  if (autonomyGate.via === 'tuning') {
14028
14223
  const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
14029
14224
  if (!again.tuning) {
@@ -14097,7 +14292,7 @@ function cmdShip(argv) {
14097
14292
  }
14098
14293
  // #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
14099
14294
  // built in that window is exactly as live as one the table saw.
14100
- const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
14295
+ const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciCureForTrailer ? { cureVerdict: ciCureForTrailer } : null) : null;
14101
14296
  if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
14102
14297
  // WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
14103
14298
  // (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
@@ -14460,7 +14655,7 @@ function cmdShip(argv) {
14460
14655
  // same block, and re-assigning the collector here would silently discard them.
14461
14656
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
14462
14657
  skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14463
- evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
14658
+ evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
14464
14659
 
14465
14660
  print('');
14466
14661
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -14671,21 +14866,29 @@ function shipDryJsonReport(opts) {
14671
14866
  * Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
14672
14867
  * trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
14673
14868
  */
14674
- function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14869
+ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
14675
14870
  if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
14871
+ // #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
14872
+ // way out; no batch can land on a red trunk anyway.
14873
+ if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
14874
+ return { held: false, released: [], detail: 'a TRUNK RED: cure is never held by a batch (#605)' };
14875
+ }
14676
14876
  const remote = git.remoteFor(repoAbs);
14677
14877
  const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
14678
14878
  if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
14679
14879
  const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
14680
14880
  const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
14681
- const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
14682
- .filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
14881
+ // #605: the lane holder is the CHAIN rooted at trunk's tip — a batch built --onto another batch's head
14882
+ // reaches trunk only through it, so its run holds the lane exactly as the root's does.
14883
+ const refs = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) })).filter((x) => x.parsed);
14884
+ const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
14885
+ const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
14683
14886
  const batches = atTip.map((x) => {
14684
14887
  const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
14685
14888
  let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
14686
14889
  if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
14687
14890
  const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
14688
- return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
14891
+ return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
14689
14892
  builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
14690
14893
  });
14691
14894
  const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
@@ -14696,14 +14899,90 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14696
14899
  }
14697
14900
 
14698
14901
  /** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
14902
+ /**
14903
+ * #610: the heavy lane at one sha — which workflow it is, whether the tree there has it, and its
14904
+ * verdict. The heavy workflow is named by FILE (`heavy-workflow:`, default ci-heavy.yml); its run
14905
+ * rows carry the workflow's `name:`, so the file at that sha is read to learn which rows are heavy.
14906
+ * `rows: null` (gh unreadable) stays `unread` — never "no heavy run", which would dispatch.
14907
+ */
14908
+ function heavyLaneAt(repoAbs, doc, sha) {
14909
+ const file = integrationProfile.parseHeavyWorkflow(doc).file;
14910
+ const rel = `.github/workflows/${file}`;
14911
+ let present = false, name = rel;
14912
+ if (sha) {
14913
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
14914
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
14915
+ if (show.ok) {
14916
+ present = true;
14917
+ const t = verifyRuns.workflowTriggers(show.stdout);
14918
+ if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
14919
+ }
14920
+ }
14921
+ const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
14922
+ const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
14923
+ return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
14924
+ }
14925
+
14926
+ /**
14927
+ * #610: `integration-profile: gated` — a serial landing waits on a green heavy run at the branch's
14928
+ * remote head. Null under every other profile (ship reads the light lane, as before), for a docs-only
14929
+ * change (no CI wait at all, #606), and for a batch member read (the batch head is graded instead).
14930
+ */
14931
+ function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMember = false } = {}) {
14932
+ const profile = integrationProfile.parseProfile(doc).profile;
14933
+ if (profile !== 'gated' || docsOnlyApplies || batchMember) return null;
14934
+ const refs = git.branchRefs(repoAbs, branch);
14935
+ const sha = refs.remoteSha || null;
14936
+ const at = sha ? `${branch}@${shortSha(sha)}` : branch;
14937
+ if (!sha) return { ok: false, action: 'wait', detail: `integration-profile: gated — ${branch} is not on the remote yet, so the heavy lane cannot run at its head (push it)`, sha: null, file: null };
14938
+ if (refs.localSha && refs.localSha !== sha && !git.git(['merge-base', '--is-ancestor', refs.localSha, sha], repoAbs).ok) {
14939
+ return { ok: false, action: 'wait', detail: `integration-profile: gated — local ${branch} has commits the remote head ${shortSha(sha)} does not; the heavy lane would test the wrong code (push it)`, sha: null, file: null };
14940
+ }
14941
+ const lane = heavyLaneAt(repoAbs, doc, sha);
14942
+ const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
14943
+ return { ...gate, sha, file: lane.file, name: lane.name };
14944
+ }
14945
+
14946
+ /** #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits. */
14947
+ function dispatchHeavyLane(repoAbs, file, ref, sha) {
14948
+ const d = git.ghWorkflowDispatch(repoAbs, file, ref, { ref: sha });
14949
+ if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
14950
+ else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: gh workflow run ${file} --ref ${ref} -f ref=${sha}`);
14951
+ return d.ok;
14952
+ }
14953
+
14699
14954
  function printBatchLanePause(lane, trunk) {
14700
14955
  print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
14701
14956
  print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
14702
14957
  print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
14703
14958
  }
14704
14959
 
14960
+ /**
14961
+ * #605: `colab ship --batch … --dry --json` — the same single step as the prose path (it IS the prose
14962
+ * path, with its prose moved to stderr), plus one JSON document on stdout carrying the facts a caller
14963
+ * keys on: the batch ref, the ref it is chained onto, the trunk sha its chain is rooted at, the step
14964
+ * taken and the exit class, and one row per member. A caller never parses prose for the chain.
14965
+ */
14966
+ function cmdShipBatchJson(opts) {
14967
+ const batch = { trunk: null, trunkSha: null, ref: null, parentRef: null, rootSha: null, base: null, depth: null, step: null, exit: null, error: null, members: [] };
14968
+ const was = PRINT_TO_STDERR;
14969
+ PRINT_TO_STDERR = true;
14970
+ let code;
14971
+ try { code = cmdShipBatch({ ...opts, _json: batch }); }
14972
+ catch (e) {
14973
+ if (!(e instanceof UserError)) throw e;
14974
+ process.stderr.write(`✗ ${e.message}\n`);
14975
+ batch.error = e.message;
14976
+ batch.step = batch.step || 'refused';
14977
+ code = 1;
14978
+ } finally { PRINT_TO_STDERR = was; }
14979
+ batch.exit = code;
14980
+ process.stdout.write(`${JSON.stringify({ batch }, null, 2)}\n`);
14981
+ return code;
14982
+ }
14983
+
14705
14984
  function cmdShipBatch(opts) {
14706
- for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
14985
+ for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ...(opts._json ? [] : [['json', '--json']])]) {
14707
14986
  if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
14708
14987
  }
14709
14988
  const repoAbs = resolveRepo(opts);
@@ -14717,7 +14996,12 @@ function cmdShipBatch(opts) {
14717
14996
  const members = entries.members;
14718
14997
  const handoffs = entries.handoffs;
14719
14998
  if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
14999
+ const J = opts._json || {}; // #605: the --dry --json report, filled as the facts are read
15000
+ J.trunk = trunk;
14720
15001
  const serial = (why, list = members) => {
15002
+ J.step = J.step && J.step !== 'build' ? J.step : 'serial';
15003
+ J.reason = why;
15004
+ if (!J.members || !J.members.length) J.members = list.map((b) => ({ branch: b, sha: null, eligible: null, inBatch: false, why }));
14721
15005
  print(`✗ ship-batch: ${why}`);
14722
15006
  print(shipBatch.serialLine(list));
14723
15007
  return 4;
@@ -14778,6 +15062,7 @@ function cmdShipBatch(opts) {
14778
15062
  const lsTrunk = git.git(['ls-remote', remote, `refs/heads/${trunk}`], repoAbs);
14779
15063
  const trunkNow = lsTrunk.ok ? (lsTrunk.stdout.split('\t')[0] || '').trim() : '';
14780
15064
  if (!trunkNow) throw new UserError(`could not read ${trunk} on ${remote}`);
15065
+ J.trunkSha = trunkNow;
14781
15066
  const lsBatch = git.git(['ls-remote', remote, 'refs/heads/ship-batch/*'], repoAbs);
14782
15067
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
14783
15068
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
@@ -14789,14 +15074,102 @@ function cmdShipBatch(opts) {
14789
15074
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
14790
15075
  return d.ok;
14791
15076
  };
14792
- for (const b of batchRefs.filter((x) => !trunkNow.startsWith(x.parsed.base7))) {
14793
- print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
15077
+ // #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
15078
+ // ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
15079
+ // whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
15080
+ // is exactly the old sweep: every ref not built on trunk's tip goes.
15081
+ const chains = shipBatch.batchChains({ refs: batchRefs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
15082
+ const carriedBy = (ref, from, sha) => {
15083
+ const lg = git.git(['log', '--format=%B%x00', `${from}..${sha}`], repoAbs);
15084
+ return shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === ref).reverse();
15085
+ };
15086
+ const swept = [];
15087
+ for (const b of batchRefs.filter((x) => !chains.get(x.parsed.ref).rooted)) {
15088
+ const c = chains.get(b.parsed.ref);
15089
+ // A ref built on a head trunk never reached (an orphaned chain link) may still have its run going;
15090
+ // nothing can ever land it, so cancel that run. A ref on an OLD trunk tip is today's case, untouched.
15091
+ const baseFull = git.git(['rev-parse', '--verify', '-q', `${b.parsed.base7}^{commit}`], repoAbs);
15092
+ const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
15093
+ if (offTrunk) {
15094
+ print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
15095
+ for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
15096
+ if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
15097
+ const cx = git.ghRunCancel(repoAbs, r.databaseId);
15098
+ if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
15099
+ }
15100
+ } else {
15101
+ print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
15102
+ }
15103
+ swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
14794
15104
  deleteRef(b.parsed.ref);
14795
15105
  }
14796
- const atBase = batchRefs.find((x) => trunkNow.startsWith(x.parsed.base7)) || null;
15106
+ const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
15107
+ // Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
15108
+ const carriedByChain = (sha) => new Map(shipBatch.parseMemberTrailers((() => {
15109
+ const lg = git.git(['log', '--format=%B%x00', `${trunkNow}..${sha}`], repoAbs);
15110
+ return lg.ok ? lg.stdout.split('\0') : [];
15111
+ })()).map((m) => [m.branch, m.ref]));
15112
+
15113
+ // #605: --onto <ship-batch ref> builds on that ref's HEAD instead of trunk's tip. `base` is what the
15114
+ // batch sits on from here on; without --onto it is trunk's tip, and nothing below changes.
15115
+ let base = trunkNow;
15116
+ let parent = null; // { ref, sha, chain, verdict } while the parent has not landed
15117
+ if (opts.onto) {
15118
+ const want = shipBatch.parseBatchRef(opts.onto).ref;
15119
+ const p = batchRefs.find((x) => x.parsed.ref === want) || null;
15120
+ const ours = swept.find((x) => x.members.some((m) => members.includes(m.branch)));
15121
+ if (p && p.sha === trunkNow) {
15122
+ print(` ${want} has landed — ${trunk} is at its head ${shortSha(trunkNow)}; this batch sits on ${trunk}'s tip`);
15123
+ } else if (!p || !chains.get(want).rooted) {
15124
+ if (ours) {
15125
+ print(`✗ ship-batch: ${ours.ref} was built on ${want}, which ${p ? `is no longer rooted at ${trunk}'s tip (${chains.get(want).why})` : `is gone from ${remote}`} — nothing landed; ${ours.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
15126
+ J.step = 'chained-decline';
15127
+ return serial('its parent batch was discarded, or trunk moved some other way — the chain cannot land in order', ours.members.map((m) => m.branch));
15128
+ }
15129
+ // The parent landed and its lander deleted the ref: our batch (if staged) now sits on trunk's tip.
15130
+ const atTip = rooted.find((x) => trunkNow.startsWith(x.parsed.base7));
15131
+ const landedParent = !p && atTip && carriedBy(atTip.parsed.ref, trunkNow, atTip.sha).some((m) => members.includes(m.branch));
15132
+ if (!landedParent && p) {
15133
+ throw new UserError(`--onto ${want}: it is not rooted at ${trunk}'s tip (${chains.get(want).why}) — build on ${trunk} instead (drop --onto)`);
15134
+ }
15135
+ if (!landedParent) {
15136
+ // ls-remote cannot tell "never existed" from "discarded" or "trunk moved some other way" — and
15137
+ // for the last two the issue's rule is a decline. So a missing parent declines: nothing of
15138
+ // this chain can land in order, and the members go back to the queue (#605).
15139
+ J.step = 'chained-decline';
15140
+ print(`✗ ship-batch: --onto ${want}: no such batch ref on ${remote} — it was discarded, landed under other members, or never existed.`);
15141
+ return serial(`nothing to chain onto — build on ${trunk} instead (the same command without --onto)`);
15142
+ }
15143
+ print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
15144
+ } else {
15145
+ const pc = chains.get(want);
15146
+ const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
15147
+ const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
15148
+ if (verdict.state === 'red') {
15149
+ if (child) {
15150
+ const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
15151
+ print(`✗ ship-batch: ${want} is red (${verdict.why}) — it will not land at ${shortSha(p.sha)}, so ${child.parsed.ref} built on it cannot land in order. Nothing landed; ${child.parsed.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto once ${want} is settled.`);
15152
+ deleteRef(child.parsed.ref);
15153
+ J.step = 'chained-decline';
15154
+ return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
15155
+ }
15156
+ throw new UserError(`--onto ${want}: its combined run is red (${verdict.why}) — nothing to chain onto; build on ${trunk} instead (drop --onto)`);
15157
+ }
15158
+ if (verdict.state === 'none' && !child) {
15159
+ throw new UserError(`--onto ${want}: it has no combined run in flight or green yet — wait for its run to start, then run this command again`);
15160
+ }
15161
+ if (!child && pc.depth >= shipBatch.MAX_CHAIN_DEPTH) {
15162
+ throw new UserError(`--onto ${want}: it is already ${pc.depth} deep from ${trunk}'s tip — a chain is at most ${shipBatch.MAX_CHAIN_DEPTH} batches (#605); wait for its root to land`);
15163
+ }
15164
+ base = p.sha;
15165
+ parent = { ref: want, sha: p.sha, chain: pc, verdict };
15166
+ }
15167
+ }
15168
+ Object.assign(J, { base, parentRef: parent ? parent.ref : null, rootSha: trunkNow, depth: parent ? parent.chain.depth + 1 : 1, ref: shipBatch.batchRefName(base) });
15169
+ const atBase = rooted.find((x) => (!parent || x.parsed.ref !== parent.ref) && base.startsWith(x.parsed.base7)) || null;
14797
15170
  let existing = null;
14798
15171
  if (atBase) {
14799
- const log = git.git(['log', '--format=%B%x00', `${trunkNow}..${atBase.sha}`], repoAbs);
15172
+ const log = git.git(['log', '--format=%B%x00', `${base}..${atBase.sha}`], repoAbs);
14800
15173
  const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
14801
15174
  const foreign = inBatch.filter((m) => !members.includes(m.branch));
14802
15175
  // #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
@@ -14825,8 +15198,24 @@ function cmdShipBatch(opts) {
14825
15198
  }
14826
15199
  }
14827
15200
  }
14828
- const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14829
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
15201
+ let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15202
+ // #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
15203
+ // heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
15204
+ // the same re-run / split path a light red does, and the split walks toward the culprit.
15205
+ let heavyWave = null;
15206
+ if (verdict && integrationProfile.parseProfile(doc).profile === 'gated') {
15207
+ heavyWave = heavyLaneAt(repoAbs, doc, existing.sha);
15208
+ if (!heavyWave.present) {
15209
+ print(`✗ ship-batch: integration-profile: gated, but no .github/workflows/${heavyWave.file} at ${existing.ref}@${shortSha(existing.sha)} — a wave lands only on a green heavy run, and there is no heavy lane to run. Nothing landed.`);
15210
+ print(' Add one: `colab template ci-<stack>-heavy --dest .github/workflows/ci-heavy.yml` (or name yours with heavy-workflow:), land it, then re-run once it is on trunk.');
15211
+ return 4;
15212
+ }
15213
+ verdict = integrationProfile.waveVerdict(verdict, heavyWave.verdict);
15214
+ }
15215
+ // #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
15216
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
15217
+ J.step = step.step;
15218
+ if (existing) J.members = existing.members.map((m) => ({ branch: m.branch, sha: m.sha, eligible: true, inBatch: true, why: `staged in ${existing.ref}` }));
14830
15219
  if (opts.split && !(verdict && verdict.state === 'red')) {
14831
15220
  print(` --split ignored: ${existing ? `${existing.ref} is not red (${verdict ? verdict.state : 'members changed'})` : 'no batch is staged at this base'} — only a red combined run splits (#557)`);
14832
15221
  }
@@ -14839,6 +15228,7 @@ function cmdShipBatch(opts) {
14839
15228
  }
14840
15229
  if (step.step === 'wait-run') {
14841
15230
  print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
15231
+ if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
14842
15232
  print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
14843
15233
  return 3;
14844
15234
  }
@@ -14875,15 +15265,33 @@ function cmdShipBatch(opts) {
14875
15265
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
14876
15266
  return 4;
14877
15267
  }
15268
+ if (step.step === 'land' && parent) {
15269
+ // #605: land in order — only once trunk's tip IS the parent's head. Until then the parent is in
15270
+ // flight (wait, exit 3); a parent that is red will never land at that sha (delete, exit 4).
15271
+ const ls = shipBatch.chainedLandStep({ parent: parent.chain, parentVerdict: parent.verdict });
15272
+ J.step = ls.step === 'wait' ? 'chained-wait' : 'chained-decline';
15273
+ J.reason = ls.why;
15274
+ if (ls.step === 'wait') {
15275
+ print(`⏸ BATCH-CHAINED ${existing.ref}@${shortSha(existing.sha)} — combined run green; it lands after ${parent.ref}: ${ls.why}. Nothing landed.`);
15276
+ print(` Wait for ${parent.ref} to land (bounded, B1a), then run this command again — it lands with no second run.`);
15277
+ return 3;
15278
+ }
15279
+ print(`✗ ship-batch: ${existing.ref} cannot land in order — ${ls.why}. Nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
15280
+ deleteRef(existing.ref);
15281
+ return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
15282
+ }
14878
15283
  if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
14879
15284
 
14880
15285
  // ---- (d) pick the members — each through its OWN ship gates ----
14881
15286
  const st = state.loadState();
14882
15287
  const evaluated = [];
15288
+ // #605: a member the chain below already carries lands with that batch — it never joins a second one.
15289
+ const inChain = parent ? carriedByChain(parent.sha) : new Map();
14883
15290
  for (const b of members) {
14884
15291
  const refs = git.branchRefs(repoAbs, b, remote);
14885
15292
  let why = null, report = null, ciClass = null, files = [];
14886
15293
  if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
15294
+ else if (inChain.has(b)) why = `already in ${inChain.get(b)} — it lands with that batch, not this one`;
14887
15295
  else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
14888
15296
  if (!why) {
14889
15297
  // #591: a hand-off member is read through the SAME door a single --handoff ship uses
@@ -14916,12 +15324,13 @@ function cmdShipBatch(opts) {
14916
15324
  return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
14917
15325
  })()
14918
15326
  : shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
14919
- print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
15327
+ print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)}${parent ? ` · onto ${parent.ref}@${shortSha(parent.sha)} (depth ${parent.chain.depth + 1}, lands after it)` : ''} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
14920
15328
  print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
14921
15329
  e.ok && !selected.includes(e) ? (splitHalf ? 'eligible — held by the split for the next batch' : `eligible — waits for the next batch (cap ${size})`) : e.why]), ['', 'MEMBER', 'DETAIL']));
14922
15330
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
15331
+ J.members = evaluated.map((e) => ({ branch: e.branch, sha: e.sha || null, eligible: e.ok, inBatch: selected.includes(e), why: e.why }));
14923
15332
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14924
- if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
15333
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf && !parent) {
14925
15334
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14926
15335
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14927
15336
  const lone = selected[0];
@@ -14940,10 +15349,11 @@ function cmdShipBatch(opts) {
14940
15349
  if (step.step === 'serial') return serial('no member can join — each one above says why');
14941
15350
 
14942
15351
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14943
- const ref = shipBatch.batchRefName(trunkNow);
15352
+ // #605: on a chain, the batch is built on the parent's head and named after it — one batch per base.
15353
+ const ref = shipBatch.batchRefName(base);
14944
15354
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-ship-batch-'));
14945
- const add = git.git(['worktree', 'add', '--detach', dir, trunkNow], repoAbs);
14946
- if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(trunkNow)} to build the batch: ${git.gitFailureLine(add.stderr)}`); }
15355
+ const add = git.git(['worktree', 'add', '--detach', dir, base], repoAbs);
15356
+ if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(base)} to build the batch: ${git.gitFailureLine(add.stderr)}`); }
14947
15357
  const cleanup = () => git.git(['worktree', 'remove', '--force', dir], repoAbs);
14948
15358
  const machineLine = shipMachineTrailerDecision(repoAbs, doc).line;
14949
15359
  const built = [];
@@ -15011,6 +15421,8 @@ function cmdShipBatch(opts) {
15011
15421
  built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
15012
15422
  }
15013
15423
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
15424
+ for (const d of dropped) Object.assign(J.members.find((r) => r.branch === d.branch) || {}, { inBatch: false, why: d.why });
15425
+ J.step = 'build';
15014
15426
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
15015
15427
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
15016
15428
  // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
@@ -15036,8 +15448,10 @@ function cmdShipBatch(opts) {
15036
15448
  }
15037
15449
  if (opts.dry) {
15038
15450
  cleanup();
15039
- print(`→ READY: would push ${ref} = ${shortSha(trunkNow)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15040
- print(' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15451
+ print(`→ READY: would push ${ref} = ${shortSha(base)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
15452
+ print(parent
15453
+ ? ` then wait on ONE combined run, and fast-forward trunk to it only once ${parent.ref} has landed at ${shortSha(parent.sha)} (#605).`
15454
+ : ' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
15041
15455
  if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
15042
15456
  return 0;
15043
15457
  }
@@ -15045,7 +15459,7 @@ function cmdShipBatch(opts) {
15045
15459
  const push = git.run('git', ['push', '--force', remote, `${head}:refs/heads/${ref}`], { cwd: repoAbs });
15046
15460
  cleanup();
15047
15461
  if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
15048
- print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
15462
+ print(` pushed ${ref} = ${shortSha(base)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})${parent ? ` — chained onto ${parent.ref}; it lands after it` : ''}`);
15049
15463
  if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
15050
15464
  print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
15051
15465
  return 3;
@@ -16087,6 +16501,10 @@ workflow \`.github/workflows/instruction-files.yml\`.
16087
16501
  --repo <path> repo to run in (default: cwd)
16088
16502
  --json { ok, error?, mode, base, fail, reason, files: [{ path, conforming, message }], changed }
16089
16503
 
16504
+ A fork whose CLAUDE.md/AGENTS.md belong to its upstream declares \`instruction-files: upstream\` in
16505
+ .github/project.yml (read on the judged side — HEAD, the index or the working tree): nothing is judged
16506
+ and the verdict is a pass (\`--json\`: \`exempt: "upstream"\`) — CONVENTIONS.md §9 "A fork of an upstream", #602.
16507
+
16090
16508
  Exit: 0 pass · 1 fail · 2 cannot judge (not a repo, base not fetched — never read as a pass).
16091
16509
  The fix for a failure is always the same: move the prose to AGENTS.md (handbook-sync's graft step
16092
16510
  does the move), keeping CLAUDE.md to \`@AGENTS.md\`, blank lines and tool blocks.
@@ -16564,6 +16982,23 @@ function cmdPromote(argv) {
16564
16982
  else checks.push(['✗', 'trunk CI green', `${trunk}@${shortSha(run.sha)}: status=${run.status} conclusion=${run.conclusion || 'none'} (fail-to-start counts as not green)`]);
16565
16983
  }
16566
16984
 
16985
+ // #610: integration-profile: promote — the heavy lane gates the promotion: green at the exact sha
16986
+ // being promoted (origin's trunk tip). Never dispatched from here: promotion is a human act, and
16987
+ // the command to start the heavy lane is printed instead.
16988
+ let heavyOk = true;
16989
+ if (integrationProfile.parseProfile(doc).profile === 'promote') {
16990
+ const tipR = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16991
+ const tip = tipR.ok ? tipR.stdout : null;
16992
+ const lane = tip ? heavyLaneAt(repoAbs, doc, tip) : null;
16993
+ const at = tip ? `${trunk}@${shortSha(tip)}` : trunk;
16994
+ let detail;
16995
+ if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
16996
+ else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
16997
+ else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
16998
+ else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: gh workflow run ${lane.file} --ref ${trunk} -f ref=${tip}` : ''}`; }
16999
+ checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
17000
+ }
17001
+
16567
17002
  const localTrunk = git.git(['rev-parse', trunk], repoAbs);
16568
17003
  const originTrunk = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16569
17004
  const trunkSyncOk = localTrunk.ok && originTrunk.ok && localTrunk.stdout === originTrunk.stdout;
@@ -16593,7 +17028,7 @@ function cmdPromote(argv) {
16593
17028
  ahead > 0 ? `${ahead} commit(s) to promote` : `could not count ${remote}/${MAIN}..${remote}/${trunk}`]);
16594
17029
  }
16595
17030
 
16596
- const preOk = ciOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
17031
+ const preOk = ciOk && heavyOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
16597
17032
 
16598
17033
  // ---- report ----
16599
17034
  say(`promote ${shortRepo(repoAbs)} · ${trunk} → ${MAIN}` + (opts.dry ? ' [DRY RUN]' : ''));
@@ -16837,7 +17272,9 @@ re-running install.sh; \`colab update\` reports it when it is behind. \`colab --
16837
17272
  which of the two you are talking to.
16838
17273
  `;
16839
17274
 
16840
- function print(s) { process.stdout.write(s.endsWith('\n') ? s : s + '\n'); return 0; }
17275
+ // #605: `ship --batch --dry --json` keeps stdout for its one JSON document; the prose goes to stderr.
17276
+ let PRINT_TO_STDERR = false;
17277
+ function print(s) { (PRINT_TO_STDERR ? process.stderr : process.stdout).write(s.endsWith('\n') ? s : s + '\n'); return 0; }
16841
17278
  function warn(s) { process.stderr.write(`! ${s}\n`); }
16842
17279
  /**
16843
17280
  * `colab ship` sets this to an array while it runs B3 (worktree teardown) through B4 (per-issue