@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
package/tools/colab CHANGED
@@ -43,6 +43,7 @@ const decisionRecord = require('./lib/decision-record');
43
43
  const blockedBy = require('./lib/blocked-by');
44
44
  const ciGrant = require('./lib/ci-grant');
45
45
  const trustHumans = require('./lib/trust-humans');
46
+ const ownerPolicy = require('./lib/owner-policy');
46
47
  const ciCure = require('./lib/ci-cure');
47
48
  const ciVerdict = require('./lib/ci-verdict');
48
49
  const baseCiVerdict = require('./lib/base-ci-verdict');
@@ -77,11 +78,14 @@ const releaseCut = require('./lib/release-cut');
77
78
  const releaseFinalize = require('./lib/release-finalize');
78
79
  const releaseChannel = require('./lib/release-channel');
79
80
  const shippedBranch = require('./lib/shipped-branch');
81
+ const landedPrs = require('./lib/landed-prs');
80
82
  const shipRoles = require('./lib/ship-roles'); // #372
83
+ const shipHandoff = require('./lib/ship-handoff'); // #578
81
84
  const refsBrake = require('./lib/refs-brake'); // #385
82
85
  const localAdopt = require('./lib/local-adopt'); // #393
83
86
  const ownerBranch = require('./lib/owner-branch'); // #394
84
87
  const humanDoor = require('./lib/ship-human-door'); // #525
88
+ const instructionGate = require('./lib/instruction-gate'); // #588
85
89
  const {
86
90
  HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
87
91
  parseArgs, table, shortRepo,
@@ -2001,7 +2005,7 @@ function cmdReleaseFinalize(argv) {
2001
2005
  const issues = readAllIssuesForSwitches(repoAbs);
2002
2006
  const labelNames = (i) => (i.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
2003
2007
  const records = (issues || [])
2004
- .map((i) => ({ number: i.number, url: i.url || null, state: String(i.state || '').toUpperCase(), createdAt: i.createdAt || null, held: labelNames(i).includes(releaseFinalize.HOLD_LABEL), version: releaseFinalize.parseReleaseMarker(i.body) }))
2008
+ .map((i) => ({ number: i.number, url: i.url || null, title: i.title == null ? null : String(i.title), state: String(i.state || '').toUpperCase(), createdAt: i.createdAt || null, held: labelNames(i).includes(releaseFinalize.HOLD_LABEL), version: releaseFinalize.parseReleaseMarker(i.body) }))
2005
2009
  .filter((r) => r.version);
2006
2010
  const trackingFor = (version, { isCandidate }) => {
2007
2011
  if (issues === null) return { error: 'the issue list could not be read (or may be truncated) — the tracking issue cannot be found' };
@@ -2009,7 +2013,7 @@ function cmdReleaseFinalize(argv) {
2009
2013
  const open = mine.filter((r) => r.state === 'OPEN');
2010
2014
  if (open.length > 1) return { error: `${open.length} open tracking issues for ${version} (${open.map((r) => `#${r.number}`).join(', ')}) — one per version; close the duplicate by hand` };
2011
2015
  if (open.length === 1) return { ...open[0] };
2012
- if (isCandidate && mine.length) return { error: `the tracking issue for ${version} (#${mine[0].number}) is closed but ${version} is not final — reopen it; a closed record is never silently replaced` };
2016
+ if (isCandidate && mine.length) return { error: `the tracking issue for ${version} (#${mine[0].number}${mine[0].title ? ` ${JSON.stringify(mine[0].title)}` : ''}) is closed but ${version} is not final — reopen it; a closed record is never silently replaced` };
2013
2017
  return { number: null, createdAt: null, held: false, wouldCreate: !opts.dry };
2014
2018
  };
2015
2019
  const version0 = newest ? newest.version : (selection.version || null);
@@ -2021,7 +2025,7 @@ function cmdReleaseFinalize(argv) {
2021
2025
  const body = releaseFinalize.trackingBody({ version: version0, row: policy.derived.row, final: policy.effective.final, testPeriodDays: policy.effective.testPeriodDays });
2022
2026
  const c = tracker.forRepo(repoAbs).issueCreate({ title: releaseFinalize.trackingTitle(version0), body });
2023
2027
  if (!c.number) trackings.set(version0, { error: `could not open the tracking issue for ${version0} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'})` });
2024
- else { trackings.set(version0, { number: c.number, url: c.url, createdAt: now, held: false }); trackingCreated = true; }
2028
+ else { trackings.set(version0, { number: c.number, url: c.url, title: releaseFinalize.trackingTitle(version0), createdAt: now, held: false }); trackingCreated = true; }
2025
2029
  }
2026
2030
 
2027
2031
  // #441: an operator-granted automatic final — the decision it names is resolved once per run, from
@@ -2048,10 +2052,25 @@ function cmdReleaseFinalize(argv) {
2048
2052
  });
2049
2053
  // #566: only the run that CUT the candidate vouches for what it published — read from the rows
2050
2054
  // BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
2051
- const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
2055
+ const cutRunOpts = {
2052
2056
  tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
2053
2057
  jobCount: (id) => git.ghRunJobCount(repoAbs, id),
2054
- });
2058
+ };
2059
+ const cutRun = releaseFinalize.cutRunVerdict(rawRows, cutRunOpts);
2060
+ // #565: a run that failed only in its deploy jobs (staging) — the three run-reading conditions
2061
+ // re-read with it counted as passed. decide() uses that reading on a human final only, and names
2062
+ // the failure either way. Jobs are read lazily: only when a condition already failed.
2063
+ let deployReport = null;
2064
+ if (Array.isArray(rawRows) && !(conditions.ci.ok && conditions.suite.ok && cutRun.ok)) {
2065
+ const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
2066
+ if (d.failures.length) {
2067
+ const at = `${cand.tag}@${shortSha(cand.sha)}`;
2068
+ const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
2069
+ const run = git.summarizeRunsForCommit(lenRows, cand.sha);
2070
+ const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
2071
+ deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
2072
+ }
2073
+ }
2055
2074
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
2056
2075
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2057
2076
  // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
@@ -2075,7 +2094,7 @@ function cmdReleaseFinalize(argv) {
2075
2094
  }
2076
2095
  const verdict = releaseFinalize.decide({
2077
2096
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2078
- ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
2097
+ ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2079
2098
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2080
2099
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2081
2100
  });
@@ -2202,7 +2221,7 @@ function cmdReleaseFinalize(argv) {
2202
2221
 
2203
2222
  const supersededHeld = records.filter((r) => r.state === 'OPEN' && r.held && r.version !== (cand ? cand.version : version0) && !finals.has(r.version)).map((r) => r.number);
2204
2223
  const trackingOut = tracking && !tracking.error
2205
- ? { number: tracking.number || null, url: tracking.url || null, created: trackingCreated && (!cand || cand.version === version0), held: !!tracking.held, supersededHeld }
2224
+ ? { number: tracking.number || null, url: tracking.url || null, title: tracking.title || null, created: trackingCreated && (!cand || cand.version === version0), held: !!tracking.held, supersededHeld }
2206
2225
  : null;
2207
2226
  // #468: why this run made no final, and which candidate finals first — the line the release
2208
2227
  // workflow prints, so "no final" never has to be reconstructed from a checklist.
@@ -3792,7 +3811,8 @@ It is minted only when ALL of these hold, checked before any network call:
3792
3811
  - the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
3793
3812
  a grant carrying a failing review is a contradiction, so it is refused, not recorded;
3794
3813
  - the branch is pushed, and --head (if given) equals origin's tip — the grant binds that tip;
3795
- - this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human);
3814
+ - the policy resolves to \`reviewer\` (#596): this checkout's project.yml \`migration-grant:\` when
3815
+ declared (#398), else the owner-level value (\`colab owner-policy\`), else human;
3796
3816
  - checklist-items, when given, is <passed>/${migrationGrant.REVIEW_CHECKLIST_ITEMS} and, with checklist pass, every item
3797
3817
  passed (#457) — the record counts against the checklist the migration-review skill walks today.
3798
3818
  Then, read from CI after the tracker read and before anything is written (#457):
@@ -3800,8 +3820,8 @@ Then, read from CI after the tracker read and before anything is written (#457):
3800
3820
  passed there (the rule ship applies), and --ci-run, when given, is one of the runs at that
3801
3821
  head and carries the job. A repo whose CI has no such job cannot mint a reviewer grant at all.
3802
3822
  COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
3803
- \`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
3804
- \`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
3823
+ \`colab ship\` honours a reviewer grant only when ALL of (#401): P the policy at the target resolves to
3824
+ reviewer (its project.yml key, else the owner-level value, else human — #596) · M this record is live, trusted and passing · HEAD its head is the
3805
3825
  branch's exact remote head, or its \`migrations\` id equals the id at that head · R the live
3806
3826
  "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job passed on the SHIPPED head (re-read by ship, never
3807
3827
  taken from the record). Any condition failing → a human runs Phase B.
@@ -3906,11 +3926,21 @@ function migrationGrantReviewRecord(repoAbs, opts) {
3906
3926
 
3907
3927
  // Policy first: under the default (human) a reviewer grant would do nothing and mislead. Read from
3908
3928
  // THIS checkout (trunk at rest), never the branch — a branch must not raise its own grant policy.
3909
- const pol = migrationGrant.parseGrantPolicy(projectDoc(repoAbs));
3929
+ // #596: three levels — this checkout's key > the owner-level value > human. The owner record is
3930
+ // read only when the repo key is absent or `human` (the opt-out case needs it to say so).
3931
+ const mintDoc = projectDoc(repoAbs);
3932
+ const pol = migrationGrantPolicyFor(repoAbs, mintDoc, trustHumans.parseTrustHumans(mintDoc));
3910
3933
  if (!pol.valid) throw new UserError(`${pol.reason} — fix project.yml before minting a reviewer grant`);
3911
3934
  if (pol.policy !== 'reviewer') {
3935
+ if (pol.optedOut) {
3936
+ throw new UserError(`${pol.reason} — no reviewer grant is minted here. A human grant still works: \`COLAB_HUMAN=1 colab migration-grant <N> --branch <branch>\``);
3937
+ }
3938
+ if (pol.ownerNote) {
3939
+ throw new UserError(`this repo's migration-grant policy is "${pol.policy}" (absent = human), and ${pol.ownerNote} — re-run once \`colab owner-policy show\` reads it`);
3940
+ }
3912
3941
  throw new UserError(`this repo's migration-grant policy is "${pol.policy}"${pol.declared ? '' : ' (absent = human)'} — a reviewer grant is minted only where project.yml declares migration-grant: reviewer`);
3913
3942
  }
3943
+ opts.policyResolved = pol;
3914
3944
 
3915
3945
  // HEAD binding: the grant covers exactly the commit on origin. An unpushed branch has no tip any
3916
3946
  // other machine can check against, so it is refused rather than bound to a local-only sha.
@@ -4041,6 +4071,7 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
4041
4071
  print(' Bound to that HEAD: any new commit voids it. It expires the moment the issue closes.');
4042
4072
  }
4043
4073
  print(` colab ship honours it only while the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job has passed on that HEAD and the policy still says reviewer.`);
4074
+ if (opts.policyResolved && opts.policyResolved.source === 'owner') print(` Policy source: ${opts.policyResolved.reason}.`);
4044
4075
  print(` Revoke any time: colab migration-grant ${num} --revoke`);
4045
4076
  return 0;
4046
4077
  }
@@ -4113,9 +4144,16 @@ function cmdMigrationGrantList(opts) {
4113
4144
  grants.push(row);
4114
4145
  }
4115
4146
 
4147
+ // #596: the policy these grants are judged under, with its source (repo | owner | default).
4148
+ const listDoc = projectDoc(repoAbs);
4149
+ const pol = migrationGrantPolicyFor(repoAbs, listDoc, trustHumans.parseTrustHumans(listDoc));
4150
+ const policy = { value: pol.policy, source: pol.source, optedOut: pol.optedOut,
4151
+ ...(pol.source === 'owner' ? { owner: pol.owner, by: pol.ownerBy, at: pol.ownerAt } : {}) };
4116
4152
  if (opts.json) {
4117
- return print(JSON.stringify({ repo: shortRepo(repoAbs), label: labels.MIGRATION_GRANT_LABEL, grants, stale }, null, 2));
4153
+ return print(JSON.stringify({ repo: shortRepo(repoAbs), label: labels.MIGRATION_GRANT_LABEL, policy, grants, stale }, null, 2));
4118
4154
  }
4155
+ // Prose names the source only where the owner level is in play — otherwise byte-identical.
4156
+ if (pol.source === 'owner' || pol.optedOut || pol.ownerNote) print(`migration-grant policy: ${pol.policy} (source: ${ownerPolicy.sourceLabel(pol)}) — ${pol.reason}`);
4119
4157
 
4120
4158
  if (grants.length === 0 && stale.length === 0) {
4121
4159
  print(`no outstanding migration grants in ${shortRepo(repoAbs)}`);
@@ -4132,6 +4170,162 @@ function cmdMigrationGrantList(opts) {
4132
4170
  return 0;
4133
4171
  }
4134
4172
 
4173
+ // ---------------------------------------------------------------------------
4174
+ // owner-policy (#596) — an owner-level `migration-grant` value, set once by a human for every repo
4175
+ // the GitHub owner runs. Record + proof rules: tools/lib/owner-policy.js. This section is gh I/O.
4176
+ // Precedence everywhere: the repo's own key > the owner value > human.
4177
+
4178
+ const HELP_OWNER_POLICY = `colab owner-policy [show] [--json] [--repo <path>]
4179
+ COLAB_HUMAN=1 colab owner-policy set migration-grant <human|reviewer|unset> [--repo <path>]
4180
+
4181
+ The owner-level grant policy (#596): ONE value for every repo the GitHub owner runs, so a new repo
4182
+ does not silently start at \`human\` and the owner does not land one project.yml commit per repo.
4183
+
4184
+ Precedence (read by \`colab migration-grant\` when minting and \`colab ship\` when gating):
4185
+ 1. the repo's own \`migration-grant:\` in project.yml — \`human\` there opts the repo out
4186
+ 2. the owner-level value set here
4187
+ 3. the default, \`human\`
4188
+
4189
+ Where it lives: marker comments on the open \`${ownerPolicy.LABEL}\`-labelled issue in the owner's
4190
+ \`${ownerPolicy.RECORD_REPO}\` repo (<owner>/${ownerPolicy.RECORD_REPO}). The latest marker per key whose author
4191
+ is the owner or an org MEMBER — and, where the judged repo declares trust-humans, a listed login —
4192
+ wins. A marker from anyone else is ignored and shown here, never honoured.
4193
+
4194
+ show print the owner value, who set it and when, and what THIS repo resolves to
4195
+ set K V post a new marker. Human-only: refused without COLAB_HUMAN=1, exit 1. Never
4196
+ reachable through \`colab config set\` — migration-grant stays an authority key there.
4197
+ \`unset\` withdraws the owner value. The ${ownerPolicy.RECORD_REPO} repo must exist —
4198
+ colab never creates a repo; the issue and label are created on the first set.
4199
+
4200
+ Only \`migration-grant\` is an owner-level key today. Nothing else about a reviewer grant changes:
4201
+ review record, CI round-trip job, HEAD binding and revoke are exactly as before.
4202
+ `;
4203
+
4204
+ /** The `<owner>/.github` REST paths, with gh's {owner} placeholder — resolved from the repo's remote. */
4205
+ function ownerRecordPath(rest) { return `repos/{owner}/${ownerPolicy.RECORD_REPO}/${rest}`; }
4206
+
4207
+ function ghFirstLine(s) { return String(s || '').trim().split('\n')[0] || 'gh failed'; }
4208
+
4209
+ /**
4210
+ * Locate the owner record issue. Returns { read: 'ok', issue, owner } · { read: 'none', owner? }
4211
+ * (no .github repo, or no labelled open issue — "nothing set", never an error) · { read: 'unread', why }.
4212
+ */
4213
+ function ownerRecordIssue(repoAbs) {
4214
+ const r = git.ghApi(repoAbs, [ownerRecordPath(`issues?labels=${ownerPolicy.LABEL}&state=open&per_page=100`)]);
4215
+ if (!r.ok) {
4216
+ if (/HTTP 404|Not Found/i.test(r.stderr || '')) return { read: 'none', owner: null, why: `no ${ownerPolicy.RECORD_REPO} repo for this owner` };
4217
+ return { read: 'unread', why: ghFirstLine(r.stderr) };
4218
+ }
4219
+ let list;
4220
+ try { list = JSON.parse(r.stdout); } catch (_) { return { read: 'unread', why: 'unparseable issue list' }; }
4221
+ const issues = (Array.isArray(list) ? list : []).filter((i) => i && !i.pull_request).sort((a, b) => a.number - b.number);
4222
+ if (issues.length === 0) return { read: 'none', owner: null, why: `no open ${ownerPolicy.LABEL} issue` };
4223
+ const m = String(issues[0].repository_url || '').match(/\/repos\/([^/]+)\//);
4224
+ return { read: 'ok', issue: issues[0].number, owner: m ? m[1] : null };
4225
+ }
4226
+
4227
+ /**
4228
+ * #596: the owner-level value for `key`, judged with the reading repo's `trust`. Returns the shape
4229
+ * owner-policy.js resolveGrantPolicy takes: { read, owner, issue, set, value, by, at, ignored, why }.
4230
+ */
4231
+ function ownerPolicyRead(repoAbs, trust, key = 'migration-grant') {
4232
+ const loc = ownerRecordIssue(repoAbs);
4233
+ if (loc.read !== 'ok') return { ...loc, set: false, value: null, ignored: [] };
4234
+ const c = git.ghApi(repoAbs, ['--paginate', ownerRecordPath(`issues/${loc.issue}/comments?per_page=100`),
4235
+ '--jq', '.[] | {user: {login: .user.login}, author_association, created_at, body}']);
4236
+ if (!c.ok) return { read: 'unread', why: ghFirstLine(c.stderr), set: false, value: null, ignored: [] };
4237
+ const comments = [];
4238
+ for (const line of c.stdout.split('\n')) {
4239
+ if (!line.trim()) continue;
4240
+ try { comments.push(JSON.parse(line)); } catch (_) { return { read: 'unread', why: 'unparseable comment list', set: false, value: null, ignored: [] }; }
4241
+ }
4242
+ return { read: 'ok', owner: loc.owner, issue: loc.issue, ...ownerPolicy.ownerValue(comments, key, trust) };
4243
+ }
4244
+
4245
+ /**
4246
+ * #596: the migration-grant policy for a repo, three levels. `doc` is the project.yml that counts
4247
+ * (the trunk checkout for a mint, the merge target for ship). The owner record is read only when the
4248
+ * repo key is absent or a valid `human` — a declared reviewer needs no lookup.
4249
+ */
4250
+ function migrationGrantPolicyFor(repoAbs, doc, trust) {
4251
+ const repoPol = migrationGrant.parseGrantPolicy(doc);
4252
+ const needOwner = !repoPol.declared || (repoPol.valid && repoPol.policy === 'human');
4253
+ return ownerPolicy.resolveGrantPolicy(repoPol, needOwner ? ownerPolicyRead(repoAbs, trust) : null);
4254
+ }
4255
+
4256
+ function cmdOwnerPolicy(argv) {
4257
+ const opts = parseArgs(argv, {
4258
+ values: { '--repo': 'repo' },
4259
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
4260
+ });
4261
+ if (opts.help) return print(HELP_OWNER_POLICY);
4262
+ const sub = opts._[0] || 'show';
4263
+ if (sub === 'set') {
4264
+ // HUMAN-ONLY, first — before resolveRepo or any gh call. Same bar as minting a grant.
4265
+ if (process.env.COLAB_HUMAN !== '1') {
4266
+ process.stderr.write('✗ Refusing: setting the owner-level grant policy requires a human.\n');
4267
+ process.stderr.write(' Re-run with COLAB_HUMAN=1. (No field, flag or config value can lower this bar.)\n');
4268
+ return 1;
4269
+ }
4270
+ const [, key, value] = opts._;
4271
+ if (!ownerPolicy.KEYS.includes(key)) throw new UserError(`owner-policy set: key ${JSON.stringify(key)} — expected one of ${ownerPolicy.KEYS.join(' | ')}`);
4272
+ if (!ownerPolicy.isValidValue(key, value)) throw new UserError(`owner-policy set ${key}: value ${JSON.stringify(value)} — expected one of ${[...ownerPolicy.VALUES[key], ownerPolicy.UNSET].join(' | ')}`);
4273
+ const repoAbs = resolveRepoOrCwd(opts);
4274
+ if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4275
+ if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — the owner policy lives on the tracker`);
4276
+ return cmdOwnerPolicySet(repoAbs, key, value);
4277
+ }
4278
+ if (sub !== 'show') throw new UserError(`unknown owner-policy subcommand "${sub}" — expected one of show | set`);
4279
+ const repoAbs = resolveRepoOrCwd(opts);
4280
+ if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
4281
+ if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — the owner policy lives on the tracker`);
4282
+ const doc = projectDoc(repoAbs);
4283
+ const trust = trustHumans.parseTrustHumans(doc);
4284
+ const owner = ownerPolicyRead(repoAbs, trust);
4285
+ const res = ownerPolicy.resolveGrantPolicy(migrationGrant.parseGrantPolicy(doc), owner);
4286
+ const out = {
4287
+ repo: shortRepo(repoAbs),
4288
+ owner: { read: owner.read, owner: owner.owner || null, issue: owner.issue || null, why: owner.why || null,
4289
+ 'migration-grant': owner.set ? { value: owner.value, by: owner.by, at: owner.at } : null, ignored: owner.ignored || [] },
4290
+ resolved: { 'migration-grant': { policy: res.policy, source: res.source, valid: res.valid, optedOut: res.optedOut, reason: res.reason } },
4291
+ };
4292
+ if (opts.json) return print(JSON.stringify(out, null, 2));
4293
+ const where = owner.owner ? `${owner.owner}/${ownerPolicy.RECORD_REPO}#${owner.issue}` : `<owner>/${ownerPolicy.RECORD_REPO}`;
4294
+ if (owner.read === 'unread') warn(`could not read the owner record (${owner.why}) — read as unset`);
4295
+ print(`owner-level migration-grant: ${owner.set ? `${owner.value} — set by ${owner.by} at ${owner.at} (${where})` : `not set (${owner.why || where})`}`);
4296
+ for (const i of owner.ignored || []) warn(`ignored marker ${i.value} by ${i.login || '(unknown)'} at ${i.at}: ${i.reason}`);
4297
+ print(`${shortRepo(repoAbs)} resolves to: ${res.policy} (source: ${ownerPolicy.sourceLabel(res)}) — ${res.reason}`);
4298
+ return 0;
4299
+ }
4300
+
4301
+ function cmdOwnerPolicySet(repoAbs, key, value) {
4302
+ let loc = ownerRecordIssue(repoAbs);
4303
+ if (loc.read === 'unread') throw new UserError(`could not read the owner record (${loc.why}) — nothing was posted; re-run once \`colab owner-policy show\` reads it`);
4304
+ if (loc.read === 'none') {
4305
+ // Is the .github repo there at all? colab never creates a repo — that is the owner's call.
4306
+ const repoR = git.ghApi(repoAbs, [`repos/{owner}/${ownerPolicy.RECORD_REPO}`, '--jq', '.full_name']);
4307
+ if (!repoR.ok) {
4308
+ throw new UserError(`the owner has no ${ownerPolicy.RECORD_REPO} repo (${ghFirstLine(repoR.stderr)}) — nothing was posted. colab never creates a repo: the owner must create <owner>/${ownerPolicy.RECORD_REPO} (GitHub's owner-wide defaults repo), then re-run`);
4309
+ }
4310
+ git.ghApi(repoAbs, ['-X', 'POST', `repos/{owner}/${ownerPolicy.RECORD_REPO}/labels`, '-f', `name=${ownerPolicy.LABEL}`,
4311
+ '-f', 'color=5319E7', '-f', 'description=colab owner-level policy record (#596) — human-set markers only']);
4312
+ const body = 'The owner-level colab policy record. Each value is a marker comment posted by `COLAB_HUMAN=1 colab owner-policy set`; ' +
4313
+ 'the latest one from the owner or an org member wins. Do not close this issue — closing it withdraws every owner value.';
4314
+ const created = git.ghApi(repoAbs, ['-X', 'POST', `repos/{owner}/${ownerPolicy.RECORD_REPO}/issues`, '-f', `title=${ownerPolicy.ISSUE_TITLE}`,
4315
+ '-f', `body=${body}`, '-f', `labels[]=${ownerPolicy.LABEL}`, '--jq', '.number']);
4316
+ if (!created.ok) throw new UserError(`could not create the owner record issue (${ghFirstLine(created.stderr)}) — nothing was posted; check write access with \`gh auth status\`, then re-run`);
4317
+ loc = { read: 'ok', issue: Number(created.stdout.trim()), owner: null };
4318
+ }
4319
+ const iso = nowISO();
4320
+ const c = git.ghApi(repoAbs, ['-X', 'POST', ownerRecordPath(`issues/${loc.issue}/comments`),
4321
+ '-f', `body=${ownerPolicy.markerBody(key, value, commentHost(repoAbs), iso)}`]);
4322
+ if (!c.ok) throw new UserError(`could not post the owner policy marker (${ghFirstLine(c.stderr)}) — nothing changed; check write access with \`gh auth status\`, then re-run`);
4323
+ print(`Recorded owner-level ${key}: ${value} on ${loc.owner ? `${loc.owner}/` : '<owner>/'}${ownerPolicy.RECORD_REPO}#${loc.issue} at ${iso}.`);
4324
+ print(` Repos that declare their own ${key}: are unaffected; \`${key}: human\` in a repo opts it out.`);
4325
+ print(' Check what a repo resolves to: colab owner-policy show');
4326
+ return 0;
4327
+ }
4328
+
4135
4329
  // ---------------------------------------------------------------------------
4136
4330
  // decision (#121, #122) — record a human's answer to a blocking `needs-decision` question as a
4137
4331
  // POSITIVE, machine-readable act, never as the label's mere absence. See tools/lib/decision-
@@ -4169,8 +4363,14 @@ TRUSTED_ASSOCIATIONS, checked on read. Same principle, a different mechanism, be
4169
4363
  command TRANSCRIBES a decision made elsewhere rather than AUTHORIZING a write that did not exist
4170
4364
  before it ran — the flag would assert nothing here that \`--ruled-by\` does not already.
4171
4365
 
4172
- \`--answers <ref>\` names the \`<!-- decision:options -->\` comment (id or URL) this decision
4173
- resolves, when one exists — omit it when there was no options block.
4366
+ \`--answers <ref>\` names the question this decision resolves: an ASK ID (the \`id=\` of an open
4367
+ \`<!-- <tool>:ask id=<id> v=<n> -->\` record a dashboard that tracks asks wrote on the issue), or the
4368
+ \`<!-- decision:options -->\` comment (id or URL). Omit it only when there is neither. --record
4369
+ reads the issue's open asks first (#582) — an ask with no answer record, and no ⚖ record
4370
+ naming it, after its latest version: with ONE open ask and no --answers it prints the ask id
4371
+ and the exact re-run line, and says the ruling will be read as answering that ask; with TWO OR
4372
+ MORE it REFUSES before any write and lists every id, because a nameless ruling cannot say which
4373
+ one it settles.
4174
4374
 
4175
4375
  Reopening removes \`${labels.DECISION_RECORDED_LABEL}\`, re-applies \`${labels.NEEDS_DECISION_LABEL}\`,
4176
4376
  and posts a \`${decisionRecord.REOPEN_MARK}\` receipt — every decision on that issue up to this
@@ -4199,7 +4399,7 @@ Options:
4199
4399
  and an issue number is present, for the common one-shot case)
4200
4400
  --reopen reopen an existing decision instead of recording a new one
4201
4401
  --ruled-by <name> required for --record/--reopen — who made this call, never the typist
4202
- --answers <ref> (--record only) the decision:options comment this answers, if any
4402
+ --answers <ref> (--record only) the open ask id, or the decision:options comment, this answers
4203
4403
  --body-file <f> ruling prose (or reopen reason) to append below the marker line
4204
4404
  --list list every issue with a live decision right now, instead of recording
4205
4405
  --json (with --list) machine-readable output
@@ -4291,6 +4491,23 @@ function cmdDecisionRecord(repoAbs, num, opts, body) {
4291
4491
  ${pair.fix}`);
4292
4492
  }
4293
4493
 
4494
+ // #582: show the recorder the asks still waiting on this issue, so the ruling names the one it
4495
+ // settles. One open ask + no --answers: a consumer reads the ruling as answering it — say so.
4496
+ // Two or more + no --answers: ambiguous, refuse before any write (same posture as the pair
4497
+ // check above) and list the ids.
4498
+ const asks = decisionRecord.openAsks(info.comments);
4499
+ const shellQuote = (v) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(String(v)) ? String(v) : `'${String(v).replace(/'/g, `'\\''`)}'`);
4500
+ if (asks.length > 0 && !opts.answers) {
4501
+ const rerun = (id) => `colab decision ${num} --record --ruled-by ${shellQuote(opts.ruledBy)} --answers ${shellQuote(id)}${opts.bodyFile ? ` --body-file ${shellQuote(opts.bodyFile)}` : ''}`;
4502
+ const rows = asks.map((a) => ` ${a.id} (v${a.version}, asked ${a.at || 'unknown'})\n ${rerun(a.id)}`).join('\n');
4503
+ if (asks.length > 1) {
4504
+ throw new UserError(`#${num} has ${asks.length} open asks and this record names none — a reader cannot tell which one the ruling settles. Re-run with --answers <ask id>:
4505
+ ${rows}`);
4506
+ }
4507
+ warn(`#${num} has one open ask: ${asks[0].id} (v${asks[0].version}, asked ${asks[0].at || 'unknown'}). This ruling will be read as answering it. To name it explicitly, re-run as:
4508
+ ${rerun(asks[0].id)}`);
4509
+ }
4510
+
4294
4511
  const present = git.ghListLabels(repoAbs);
4295
4512
  if (present && !present.includes(labels.DECISION_RECORDED_LABEL)) {
4296
4513
  throw new UserError(labels.decisionRecordedMissingLabelHint(present)
@@ -4474,7 +4691,8 @@ CI grant merges into a repo whose own test suite is known-failing:
4474
4691
  for the BRANCH's own current head (the same "ask by sha" check \`ship\` itself uses) — a human's
4475
4692
  say-so alone is never enough. \`--evidence-run\` is a RECORDING-ONLY pointer for the audit trail;
4476
4693
  it can never substitute for the measured run. If the branch has no run yet, open a PR for it
4477
- (\`gh pr create\`) and let CI finish, then re-run this command.
4694
+ (\`gh pr create\`) and let CI finish, then re-run this command. You do not need to close that
4695
+ PR afterwards: \`colab ship\` closes it once the branch lands (#584).
4478
4696
  2. NEVER STACKS. Creating a grant refuses outright if trunk is not currently red (nothing to
4479
4697
  exempt), and refuses again if a PRIOR ci-grant already merged something and trunk has been red
4480
4698
  continuously since — a second exemption on a still-broken repo is exactly the failure this gate
@@ -4823,7 +5041,7 @@ function cmdCiGrantCreate(repoAbs, num, opts) {
4823
5041
  throw new UserError(
4824
5042
  `"${opts.branch}" has no completed, successful CI run for its current head (${shortSha(evRun.sha)}) — ` +
4825
5043
  `a CI grant requires MEASURED evidence, never a human's say-so alone. Open a PR for it ` +
4826
- `(\`gh pr create\`) and let CI finish, then re-run this command.`);
5044
+ `(\`gh pr create\`) and let CI finish, then re-run this command — \`colab ship\` closes that PR once the branch lands (#584).`);
4827
5045
  }
4828
5046
  const evidenceSha = evRun.sha;
4829
5047
 
@@ -6290,6 +6508,9 @@ in a cleanup cron.
6290
6508
  reported but never deleted (a label a triage session just created and has not
6291
6509
  applied yet is indistinguishable from one whose members were all transferred
6292
6510
  away — the labels API exposes no creation time, so a human decides).
6511
+ Also lists open PRs whose head commit already landed in trunk (#584) — CI-trigger
6512
+ PRs a squash ship left open. Report-only, --prune included: doctor never closes
6513
+ a PR. A PR whose head is not in the local clone is not judged.
6293
6514
  `;
6294
6515
 
6295
6516
  const EMPTY_SET = new Set();
@@ -6374,7 +6595,7 @@ function cmdDoctor(argv) {
6374
6595
  const report = { deadWorktrees: [], orphanClaims: [], staleClaims: [], stalePlaces: [], unprovablePlaces: [], releasedPlaces: [], orphanPorts: [], brokenRecords: [], prunedPorts: [],
6375
6596
  renamedHostRecords: [], unprovenHostRecords: [],
6376
6597
  mergedFlips: [], mergedSweep: [], mergedDirty: [], mergedHookFail: [], mergedRemoveFail: [], shippedBranches: [], ghostPorts: [],
6377
- spentGroupLabels: [], groupLabelsChecked: !!opts.sync, pruned: !!opts.prune };
6598
+ spentGroupLabels: [], groupLabelsChecked: !!opts.sync, landedPrs: [], landedPrsUnread: [], pruned: !!opts.prune };
6378
6599
 
6379
6600
  // One answer per (repo, branch) — pass 5b asks about the same branch from a worktree and from each
6380
6601
  // of its claims, and every miss costs two `git rev-parse` calls.
@@ -6765,6 +6986,28 @@ function cmdDoctor(argv) {
6765
6986
  }
6766
6987
  }
6767
6988
 
6989
+ // 9b. open PRs whose head already landed (#584) — the CI-trigger PRs a squash ship left open before
6990
+ // ship learned to close them, or that a ship on another machine could not close. Report-only,
6991
+ // --prune included: closing a PR is a write on a shared forge, and a human may still want it.
6992
+ // Behind --sync for the same reason as pass 9 (network). A PR whose head commit is not in this
6993
+ // clone is not judged — the answer would be a guess — so the list is honest, not exhaustive.
6994
+ if (opts.sync && git.ghAvailable()) {
6995
+ const repos = [...new Set([...(config.repos || []), ...knownRepos(config)].map((r) => path.resolve(r)))]
6996
+ .filter((r) => repoLive(r) && git.remoteUrl(r));
6997
+ for (const repo of repos) {
6998
+ const trunk = resolveTrunk(repo, projectDoc(repo));
6999
+ if (!trunk) continue;
7000
+ const listed = git.ghOpenPrs(repo);
7001
+ if (listed.error) { report.landedPrsUnread.push({ repo: shortRepo(repo), error: listed.error }); continue; }
7002
+ for (const pr of listed.prs) {
7003
+ if (!pr.headRefOid || pr.headRefName === trunk) continue;
7004
+ if (!git.git(['cat-file', '-e', `${pr.headRefOid}^{commit}`], repo).ok) continue;
7005
+ if (landed.landedState(repo, trunk, pr.headRefOid).state !== 'landed') continue;
7006
+ report.landedPrs.push({ repo: shortRepo(repo), number: pr.number, url: pr.url || '', branch: pr.headRefName || '', trunk });
7007
+ }
7008
+ }
7009
+ }
7010
+
6768
7011
  // 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
6769
7012
  // the verdict — it is configuration, not state drift. Silent on a machine with no
6770
7013
  // <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
@@ -6914,6 +7157,17 @@ function cmdDoctor(argv) {
6914
7157
  print(' NOT exhaustive: a branch whose work trunk later rewrote can conflict against trunk');
6915
7158
  print(' instead of matching it, and is omitted here rather than risk calling unmerged work spent.');
6916
7159
  }
7160
+ // #584 — after the verdict, not counted: an open PR on a landed branch breaks nothing, it reads as
7161
+ // unmerged work on a tracker. Printed only under --sync.
7162
+ if (report.landedPrs.length) {
7163
+ print('');
7164
+ print(`Open PRs whose branch already landed (${report.landedPrs.length}) — the squash left them open:`);
7165
+ for (const p of report.landedPrs) print(` #${p.number} ${p.branch} [${p.repo}] → in ${p.trunk}${p.url ? ` ${p.url}` : ''}`);
7166
+ print(' `colab ship` closes these itself since #584; these predate that, or a ship could not close them.');
7167
+ print(' doctor never closes a PR, --prune included. To close one:');
7168
+ print(` gh pr close ${report.landedPrs[0].number} --comment "Landed on ${report.landedPrs[0].trunk} by squash." # in ${report.landedPrs[0].repo}`);
7169
+ }
7170
+ for (const u of report.landedPrsUnread) warn(`could not list open PRs in ${u.repo} (${u.error}) — landed-PR check skipped there`);
6917
7171
  // Also after the verdict, and also not drift: a spent group label breaks nothing, it is picker
6918
7172
  // noise on a tracker. Printed only under --sync, so silence here NEVER means "checked, clean" —
6919
7173
  // which is why a --sync run that finds nothing says so explicitly below.
@@ -9302,6 +9556,10 @@ prepended at the top for a *.yml/*.yaml copy, since there is no shebang to prote
9302
9556
  opens with a \`#!\` shebang (a *.mjs template) gets the same stamp on its SECOND line instead —
9303
9557
  using \`//\` there, since a bare \`#\` on any other line is a JS syntax error — so the shebang
9304
9558
  still has to be line 1 for the file to run.
9559
+ A ci-* template is also written with this repo's protected refs (#526): the template names
9560
+ \`main\`/\`dev\` in concurrency and the dedupe guard; the copy names the \`trunk:\` declared in
9561
+ .github/project.yml (plus \`main\` where a promotion into main releases), and says what it wrote.
9562
+ It then lists the repo's other workflows that also run on push, for you to keep, merge or delete.
9305
9563
  These templates are NEVER called remotely — copy, edit, own. When the audit flags your
9306
9564
  copy as behind a changed template, review the diff and re-copy to re-stamp.
9307
9565
  `;
@@ -9391,7 +9649,30 @@ function cmdTemplate(argv) {
9391
9649
  warn('handbook has no tags yet — stamping @ v0. Tag the handbook, then re-copy to stamp a real version.');
9392
9650
  }
9393
9651
 
9394
- const body = fs.readFileSync(srcFile, 'utf8');
9652
+ let body = fs.readFileSync(srcFile, 'utf8');
9653
+ // #526: a CI template names its protected refs `main`/`dev` — defaults, not this repo's facts.
9654
+ // Write the repo's declared trunk (and release branch) instead, and say what changed.
9655
+ const trunkNotes = [];
9656
+ let repoForCopy = null;
9657
+ if (ext === 'yml') {
9658
+ try { repoForCopy = git.repoRoot(path.dirname(destFile)) || resolveWorkingRepo(opts); } catch (_) { repoForCopy = null; }
9659
+ }
9660
+ if (ext === 'yml' && /^ci-/.test(stem)) {
9661
+ const tt = require('./lib/template-trunk');
9662
+ let doc = null;
9663
+ if (repoForCopy) doc = repoDescriptorDoc(repoForCopy);
9664
+ const p = tt.protectedRefs(doc);
9665
+ if (!p) {
9666
+ trunkNotes.push(' trunk: no `trunk:` in .github/project.yml — the template\'s main/dev refs are left as is; walk its # EDIT: markers.');
9667
+ } else {
9668
+ const r = tt.substituteTrunk(body, p);
9669
+ body = r.text;
9670
+ trunkNotes.push(r.changes.length
9671
+ ? ` trunk: wrote ${p.refs.join(', ')} (from .github/project.yml) into: ${r.changes.join(', ')}.`
9672
+ : ` trunk: ${p.refs.join(', ')} — the template's refs already match .github/project.yml.`);
9673
+ if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
9674
+ }
9675
+ }
9395
9676
  // A *.yml copy has no shebang to protect, so this is still a plain prepend at line 1 — unchanged
9396
9677
  // from before. A *.mjs copy opens with `#!/usr/bin/env node`; insertStamp puts the stamp on line
9397
9678
  // 2 instead so the shebang stays first and the file keeps running as a script (#252).
@@ -9405,6 +9686,23 @@ function cmdTemplate(argv) {
9405
9686
  // extension) is exactly how a stem collision reads back as a false confirmation (#252).
9406
9687
  print(`✓ ${stem}.${ext} @ ${version} → ${destFile}`);
9407
9688
  print(' stamped. Walk its # EDIT: markers, declare your toolchain, then commit. You own this file now.');
9689
+ for (const l of trunkNotes) print(l);
9690
+ // #526: a repo adopting a CI template usually has CI already. Both then run on every push —
9691
+ // name them and leave the choice to the person, never decide it here.
9692
+ if (ext === 'yml' && /^ci-/.test(stem) && repoForCopy) {
9693
+ const wfDir = path.join(repoForCopy, '.github', 'workflows');
9694
+ let others = [];
9695
+ try {
9696
+ const wt = require('./lib/workflow-triggers');
9697
+ others = fs.readdirSync(wfDir)
9698
+ .filter((f) => /\.ya?ml$/.test(f) && path.join(wfDir, f) !== destFile)
9699
+ .filter((f) => { const on = wt.parseWorkflowOn(fs.readFileSync(path.join(wfDir, f), 'utf8')); return on.found && on.events.has('push'); });
9700
+ } catch (_) { others = []; }
9701
+ if (others.length) {
9702
+ print(' Other workflows here also run on push — keep each, merge it into this one, or delete it (your call):');
9703
+ for (const f of others) print(` .github/workflows/${f}`);
9704
+ }
9705
+ }
9408
9706
  return 0;
9409
9707
  }
9410
9708
 
@@ -9475,6 +9773,8 @@ function inspectRepo(entry, ctx) {
9475
9773
  try { wfs = fs.existsSync(wfDir) ? fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f)).sort() : []; }
9476
9774
  catch (_) { wfs = []; }
9477
9775
 
9776
+ // #526: a CI copy is written with this repo's refs, so pristine means "as colab template renders it here".
9777
+ const descDoc = repoDescriptorDoc(abs);
9478
9778
  for (const wf of wfs) {
9479
9779
  const rel = `.github/workflows/${wf}`;
9480
9780
  const text = read(rel);
@@ -9483,6 +9783,7 @@ function inspectRepo(entry, ctx) {
9483
9783
  const c = stamp.classifyStamped({
9484
9784
  root: ctx.handbookRoot, hb: ctx.hb, tmplNames: ctx.tmplNames,
9485
9785
  templateName: st.name, stampVersion: st.version, localText: text, comparable: true,
9786
+ render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc),
9486
9787
  });
9487
9788
  artifacts.push({ file: rel, template: st.name, applicable: c.state === 'behind', ...c });
9488
9789
  } else {
@@ -9566,10 +9867,17 @@ function entryLabel(entry) {
9566
9867
  }
9567
9868
 
9568
9869
  /** Rewrite a behind-but-pristine workflow copy as the current template, freshly stamped. */
9870
+ /** A repo's parsed .github/project.yml, or null when absent or unreadable. */
9871
+ function repoDescriptorDoc(repoAbs) {
9872
+ try { return require('./lib/yaml').parse(fs.readFileSync(path.join(repoAbs, '.github', 'project.yml'), 'utf8')) || {}; }
9873
+ catch (_) { return null; }
9874
+ }
9875
+
9569
9876
  function refreshArtifact(repo, art, ctx) {
9570
9877
  const src = path.join(ctx.templatesDir, `${art.template}.yml`);
9571
9878
  if (!fs.existsSync(src)) return { ok: false, err: `template ${art.template}.yml is not in the handbook` };
9572
- const body = fs.readFileSync(src, 'utf8');
9879
+ // Rendered exactly as `colab template <name> --force` would write it here (#526).
9880
+ const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path));
9573
9881
  const dest = path.join(repo.path, art.file);
9574
9882
  try {
9575
9883
  fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -10027,7 +10335,11 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
10027
10335
  /** P, HEAD and the R thunk for shipMigrationGate. The thunk memoises its one verdict on the ctx
10028
10336
  * (`roundtripResult`) so the payload can report what R saw without a second read. */
10029
10337
  function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
10030
- const policy = migrationGrant.parseGrantPolicy(projectDocAt(repoAbs, target)).policy;
10338
+ // #596: the target's key > the owner-level value > human. `trust` (the target's trust-humans)
10339
+ // also judges who wrote the owner record.
10340
+ const trust = trustAt(repoAbs, target);
10341
+ const pres = migrationGrantPolicyFor(repoAbs, projectDocAt(repoAbs, target), trust);
10342
+ const policy = pres.policy;
10031
10343
  const remote = git.remoteInfo(repoAbs).name || 'origin';
10032
10344
  const ls = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
10033
10345
  const remoteSha = ls.ok ? ((ls.stdout.split('\n')[0] || '').split('\t')[0].trim() || null) : null;
@@ -10037,10 +10349,12 @@ function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
10037
10349
  if (!remoteSha) headNote = `${branch} could not be read on ${remote} — CI cannot have run a HEAD nobody can see`;
10038
10350
  else if (localSha && localSha !== remoteSha) headNote = `local ${branch} is ${localSha.slice(0, 7)}, ${remote} is ${remoteSha.slice(0, 7)} — push or pull until they agree`;
10039
10351
  else headSha = remoteSha;
10040
- const trust = trustAt(repoAbs, target);
10041
10352
  // #508: what the branch's migration files ARE at the shipped head, for a content-bound grant.
10042
10353
  const contentId = headSha ? migrationContentAt(repoAbs, migrations, headSha) : null;
10043
10354
  const ctx = { policy, headSha, contentId, headNote, roundtripResult: null, trust,
10355
+ policySource: pres.source, policyRes: pres,
10356
+ // Only where the owner level is in play: the default/repo refusal text stays byte-identical.
10357
+ policyReason: pres.source === 'owner' || pres.optedOut || pres.ownerNote ? pres.reason : null,
10044
10358
  labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.MIGRATION_GRANT_LABEL) };
10045
10359
  ctx.roundtrip = () => {
10046
10360
  const d = git.git(['diff', '--name-only', `${target}...${branch}`], repoAbs);
@@ -10073,6 +10387,10 @@ function migDetail(migrations, grants, target, branch, ctx) {
10073
10387
  const payload = {
10074
10388
  branch, files: [...migrations],
10075
10389
  policy: ctx ? ctx.policy : null,
10390
+ // #596: where the policy came from — repo | owner | default — and, for owner, who set it when.
10391
+ policySource: ctx ? ctx.policySource || null : null,
10392
+ policyOwner: ctx && ctx.policyRes && ctx.policyRes.source === 'owner'
10393
+ ? { owner: ctx.policyRes.owner, by: ctx.policyRes.ownerBy, at: ctx.policyRes.ownerAt } : null,
10076
10394
  headSha: ctx ? ctx.headSha : null,
10077
10395
  contentId: ctx ? ctx.contentId || null : null,
10078
10396
  // #407: the human list as read from the TARGET — null when undeclared (association class).
@@ -10086,7 +10404,9 @@ function migDetail(migrations, grants, target, branch, ctx) {
10086
10404
  if (grants.ok) {
10087
10405
  const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}${g.via === 'content' ? `, migration content ${String(g.migrations).slice(0, 12)} unchanged since` : ''}, CI round-trip passed)` : '#' + g.issue)).join(' ');
10088
10406
  const roles = [...new Set(grants.granted.map((g) => g.role || 'human'))].join('+');
10089
- return { text: `${migrations.length} present, exempted by a ${roles} grant on ${by} for branch "${branch}" — ${files}`, payload };
10407
+ const src = ctx && ctx.policySource === 'owner' && grants.granted.some((g) => g.role === 'reviewer')
10408
+ ? ` (policy: ${ownerPolicy.sourceLabel(ctx.policyRes)})` : '';
10409
+ return { text: `${migrations.length} present, exempted by a ${roles} grant on ${by} for branch "${branch}"${src} — ${files}`, payload };
10090
10410
  }
10091
10411
  // Each missing entry already carries its own specific, actionable reason (evaluateShipSet) —
10092
10412
  // report those verbatim rather than just an issue tag, so an operator or a scheduled driver's
@@ -10221,8 +10541,8 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10221
10541
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
10222
10542
  }
10223
10543
 
10224
- const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
10225
- colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10544
+ 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]
10545
+ colab ship --batch <b1,b2[,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10226
10546
 
10227
10547
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10228
10548
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10317,6 +10637,26 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
10317
10637
  \`Colab-Adopted: origin/<br> @ <sha> on <host> (machine <id>)\` trailer. A LOCAL no-digit branch is
10318
10638
  still a legitimate zero. --adopt never bypasses a branch that names issues.
10319
10639
 
10640
+ A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
10641
+ \`colab ship --branch <br> --handoff <url>\`, where <url> is the executor's hand-off comment
10642
+ (…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
10643
+ name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
10644
+ one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
10645
+ branch that moved after its hand-off needs a new one — except by base-sync merges, #579, below); and every issue the branch carries has a
10646
+ live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
10647
+ claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
10648
+ the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
10649
+ 🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
10650
+ the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
10651
+ --batch or --direct, and not when this machine already holds a claim on the branch.
10652
+
10653
+ A remote-built branch that fell BEHIND its base (#579) is synced by the lander as usual (B0: merge
10654
+ the base in, push) — and the hand-off still verifies, because the commits between the handed-off
10655
+ sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
10656
+ and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
10657
+ conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
10658
+ trailer then reads \`Colab-Handoff: <url> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
10659
+
10320
10660
  UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
10321
10661
  --session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
10322
10662
  (--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
@@ -10421,7 +10761,7 @@ Every other precondition is unchanged. No flag, env var or project.yml field wid
10421
10761
 
10422
10762
  TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
10423
10763
  diff changes .github/project.yml ALONE, every changed line inside a tuning key (ship-batch,
10424
- ship-batch-wait, ci-wait-factor, thresholds) and every moved value valid; never with an authority
10764
+ ship-batch-wait, ship-batch-steps, ci-wait-factor, thresholds) and every moved value valid; never with an authority
10425
10765
  key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
10426
10766
  release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
10427
10767
  writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
@@ -10445,9 +10785,11 @@ keeps its claim so a re-run finds it. Cannot be combined with --worktree/--branc
10445
10785
  --delete-branch/--keep-branch/--keep-worktree/--adopt. \`writes: direct\` is not required. --dry and --dry --json
10446
10786
  work as usual (json: \`direct: true\`, \`branch: null\`, \`mode: "evidence-close"\`, \`coreReview\`).
10447
10787
 
10448
- BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–3;
10788
+ BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–${shipBatch.MAX_BATCH};
10449
10789
  absent or 1 declines every --batch call. It tests up to N green candidates as ONE combined head, then
10450
- fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle:
10790
+ fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle.
10791
+ A batch of ONE is valid (#562): a lone ready member lands the same way, so the combined run — the
10792
+ setups a repo runs only on ship-batch/** and trunk — gates it too, and it needs no sync + re-run:
10451
10793
  - each member must be green at its OWN head (or have no run that could ever arrive), pass every
10452
10794
  gate its own \`ship --dry --json\` reports, and be an ordinary squash into trunk through the
10453
10795
  auto-trunk grant — the docs-only door, a migration, a ci-grant/cure, a core-path review, an
@@ -10465,15 +10807,24 @@ It never waits: each call reads the remote, takes ONE step and exits —
10465
10807
  it, bounded (code-ship B1a), and run the SAME command again
10466
10808
  4 declined — nothing landed; the last line is "→ SERIAL: colab ship --branch <b1> · …". Causes:
10467
10809
  not enabled, no auto-trunk, no workflow fires on ship-batch/** (the run could never arrive),
10468
- trunk CI red (the cure/grant doors apply per member, never to a batch), fewer than two members
10469
- can join, or the combined run is red — classify it: red:infra → the printed \`gh run rerun\`,
10470
- once; red:finding, or red again after that one re-run → serial
10810
+ trunk CI red (the cure/grant doors apply per member, never to a batch), no member can join,
10811
+ or a batch of ONE whose combined run is red — classify it: red:infra → the printed
10812
+ \`gh run rerun\`, once; red:finding, or red again after that one re-run → serial.
10813
+ A red batch of TWO OR MORE never goes serial (#557): red:infra → re-run once; red:finding →
10814
+ the same command plus --split; red again after the re-run → it splits by itself. A split
10815
+ rebuilds the same ship-batch/<trunk-sha7> with the FIRST half of its members (exit 3); the rest
10816
+ wait for the next batch, and a red half splits again
10471
10817
  1 refused (a broken checkout, an unreadable remote) — or the land push was refused while trunk did
10472
10818
  NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
10473
10819
  re-running hits the same refusal until its cause is fixed (#509)
10474
10820
  One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
10475
10821
  is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
10476
10822
  for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
10823
+ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref at trunk's tip has its
10824
+ combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
10825
+ \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
10826
+ 'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
10827
+ A red batch, or one with no run / not landed past that grace, holds nothing.
10477
10828
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
10478
10829
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
10479
10830
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
@@ -10483,12 +10834,17 @@ at build, added since) is NOT landed with it — the command names both lists an
10483
10834
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10484
10835
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10485
10836
  Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
10837
+ ADAPTIVE SIZE (#557) — opt-in per repo: \`ship-batch-steps: 2,4,8\` in project.yml, ascending sizes
10838
+ within ship-batch. Absent or malformed: every batch is up to ship-batch, exactly as above. With it,
10839
+ each batch head carries "Ship-Batch-Size: <s>" ("<s> red" on a split half), and the next batch is
10840
+ built at the step above the last landed one's size after a green, the step below after a red, the
10841
+ smallest step when trunk carries none yet.
10486
10842
  PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
10487
10843
  unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10488
10844
  ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10489
10845
  since the member became ready (its head CI's last update, else its head commit's date) — then the same
10490
- call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10491
- --batch with all of them. A single named branch is accepted only when the field is set.
10846
+ call builds it as a batch of one (#562). The caller waits, gathers every ready candidate again and
10847
+ calls --batch with all of them. Without the field, a lone member is built at once.
10492
10848
 
10493
10849
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10494
10850
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -11079,6 +11435,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11079
11435
  const ids = treeGreen.treeSkipCheckRuns(checks);
11080
11436
  if (!ids || !ids.length) return verdict;
11081
11437
  const cites = [];
11438
+ const docs = [];
11082
11439
  let unreadable = 0;
11083
11440
  const treeOf = (sha) => {
11084
11441
  const r = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{tree}`], repoAbs);
@@ -11086,7 +11443,11 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11086
11443
  };
11087
11444
  const ours = treeOf(run.sha);
11088
11445
  for (const id of ids) {
11089
- const cite = treeGreen.parseCitation(git.ghCheckRunAnnotations(repoAbs, id));
11446
+ const annotations = git.ghCheckRunAnnotations(repoAbs, id);
11447
+ // #570: a docs-only skip — the guard found every changed path documentation from a green base.
11448
+ const docsSkip = treeGreen.parseDocsSkip(annotations);
11449
+ if (docsSkip) { docs.push(docsSkip); continue; }
11450
+ const cite = treeGreen.parseCitation(annotations);
11090
11451
  if (!cite) { unreadable++; continue; }
11091
11452
  const theirs = treeOf(cite.head);
11092
11453
  if (ours && theirs && ours !== theirs) {
@@ -11095,7 +11456,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11095
11456
  }
11096
11457
  cites.push({ ...cite, proof: ours && theirs ? 'verified' : 'unverified' });
11097
11458
  }
11098
- return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable), treeGreen: cites.map((c) => c.url) };
11459
+ return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable, docs), treeGreen: cites.map((c) => c.url) };
11099
11460
  }
11100
11461
 
11101
11462
  /**
@@ -11838,8 +12199,13 @@ function cmdShipDryJson(opts) {
11838
12199
  const trunk = resolveTrunk(repoAbs, doc);
11839
12200
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
11840
12201
  if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
12202
+ const handoff = applyShipHandoff(repoAbs, sess, opts, trunk); // #578 — same resolution as the prose path
11841
12203
 
11842
12204
  const checks = [];
12205
+ if (handoff) {
12206
+ checks.push({ name: 'hand-off verified (#578)', ok: handoff.ok, class: handoff.ok ? null : HUMAN_GATED,
12207
+ detail: handoff.ok ? handoffDetail(handoff) : `${handoff.reason}: ${handoff.detail}` });
12208
+ }
11843
12209
  let target = null;
11844
12210
  // #74/#263: the close-gate split (closeIssues/refsIssues/checklistFindings) is reported
11845
12211
  // ALONGSIDE `checks` AS WELL AS folded into it — `closeIssues`/`refsIssues`/`checklistFindings`
@@ -12114,6 +12480,17 @@ function cmdShipDryJson(opts) {
12114
12480
  if (coreReviewJson.verdict === 'pending') mode = 'pr-pending';
12115
12481
  }
12116
12482
 
12483
+ // #581: the same lane read as the prose path's table — a squash into trunk while a batch holds the
12484
+ // lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
12485
+ // Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
12486
+ if (!dryMode.evidenceClose && !opts._batchMember) {
12487
+ const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
12488
+ if (laneJson) {
12489
+ checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
12490
+ detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
12491
+ }
12492
+ }
12493
+
12117
12494
  // #149: the same inherited-closing-keyword scan the prose --dry path runs, mirrored here —
12118
12495
  // following #153's own precedent for this function (its comment above: "a caller reading only
12119
12496
  // checks[]/ok … used to see NO check at all here"). Without this, the ONE caller class this path
@@ -12909,6 +13286,72 @@ function autonomyGatePayload(gate) {
12909
13286
  }
12910
13287
 
12911
13288
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
13289
+ /**
13290
+ * #578 — `--handoff <comment-url>`: verify the executor's recorded hand-off and, when it holds, take
13291
+ * the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
13292
+ * without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
13293
+ *
13294
+ * Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
13295
+ * this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
13296
+ */
13297
+ function applyShipHandoff(repoAbs, sess, opts, trunk) {
13298
+ if (!opts.handoff) return null;
13299
+ if (opts.adopt) throw new UserError('--handoff and --adopt contradict each other: --adopt is for a branch with NO issue, --handoff for one whose claim lives on another machine — drop --adopt');
13300
+ if (sess.issues.length) {
13301
+ throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
13302
+ `for ${sess.branch} — ship it without --handoff`);
13303
+ }
13304
+ const u = shipHandoff.parseHandoffUrl(opts.handoff);
13305
+ let comment = null;
13306
+ if (u) {
13307
+ const r = git.ghApi(repoAbs, [`repos/{owner}/{repo}/issues/comments/${u.commentId}`]);
13308
+ if (r.ok) {
13309
+ try {
13310
+ const j = JSON.parse(r.stdout);
13311
+ comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
13312
+ } catch (_) { comment = null; }
13313
+ }
13314
+ }
13315
+ // The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
13316
+ const remote = git.remoteFor(repoAbs);
13317
+ if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
13318
+ const refs = git.branchRefs(repoAbs, sess.branch, remote);
13319
+ // #579: base-sync merges the lander (B0) stacked on the handed-off head do not void the hand-off.
13320
+ // Read against the base as it is NOW — the merges' second parents must already be on it.
13321
+ let syncChain = [];
13322
+ if (u && comment && refs && refs.remoteSha && trunk) {
13323
+ git.git(['fetch', '--quiet', remote, `+refs/heads/${trunk}:refs/remotes/${remote}/${trunk}`], repoAbs);
13324
+ syncChain = shipHandoff.syncMergeChain((a) => git.git(a, repoAbs), refs.remoteSha, `refs/remotes/${remote}/${trunk}`);
13325
+ }
13326
+ const claimsByIssue = {};
13327
+ if (u && comment) {
13328
+ for (const n of shipguard.branchIssueNumbers(sess.branch)) {
13329
+ const info = git.ghIssueView(repoAbs, n, ['comments']);
13330
+ claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
13331
+ }
13332
+ }
13333
+ const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain });
13334
+ if (!v.ok) return v;
13335
+ sess.issues = v.issues;
13336
+ sess.handoff = v;
13337
+ // #372: the implementer is the executor that handed off — name it, never leave it reading as the shipper.
13338
+ const ex = (claimsByIssue[v.issues[0]] || []).find((c) => c.branch === sess.branch && c.login === v.executor.login);
13339
+ if (ex && (ex.session || ex.sessionName)) sess.holder = { session: ex.session || '', sessionName: ex.sessionName || '' };
13340
+ return v;
13341
+ }
13342
+
13343
+ function handoffDetail(v) {
13344
+ const head = v.syncMerges
13345
+ ? `${shortSha(v.handedOff)}, under ${v.syncMerges} clean base-sync merge${v.syncMerges === 1 ? '' : 's'} to the remote head ${shortSha(v.sha)} (#579)`
13346
+ : `${shortSha(v.sha)} = the remote head`;
13347
+ return `${v.url} hands off ${head}; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
13348
+ }
13349
+
13350
+ /** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
13351
+ function handoffEvidence(v) {
13352
+ return v ? ` · landed from the executor's hand-off ${v.url} — its claim and worktree stay until it confirms the land` : '';
13353
+ }
13354
+
12912
13355
  function shipRefFor(repoAbs, branch) {
12913
13356
  const r = git.branchRefs(repoAbs, branch);
12914
13357
  return r.localSha || r.remoteSha || branch;
@@ -12916,14 +13359,14 @@ function shipRefFor(repoAbs, branch) {
12916
13359
 
12917
13360
  function cmdShip(argv) {
12918
13361
  const opts = parseArgs(argv, {
12919
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
13362
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
12920
13363
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
12921
13364
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
12922
13365
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
12923
13366
  // repeat (`once`), checked here before any git or GitHub call.
12924
13367
  lists: { '--refs': 'refs' },
12925
13368
  once: true,
12926
- flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '-h': 'help', '--help': 'help' },
13369
+ flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '--split': 'split', '-h': 'help', '--help': 'help' },
12927
13370
  });
12928
13371
  if (opts.help) return print(HELP_SHIP);
12929
13372
  // --json is scoped to --dry only (#77): a machine-readable READ of the preconditions. Reporting
@@ -12931,6 +13374,9 @@ function cmdShip(argv) {
12931
13374
  // — refuse the combination rather than silently ignore --json on a real ship.
12932
13375
  if (opts.json && !opts.dry) throw new UserError('--json currently only applies together with --dry — see `colab ship --help`');
12933
13376
  if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
13377
+ // #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
13378
+ if (opts.handoff && (opts.batch || opts.direct)) throw new UserError(`--handoff applies to one --branch ship — not to ${opts.batch ? '--batch' : '--direct'} (see \`colab ship --help\`)`);
13379
+ 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');
12934
13380
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
12935
13381
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
12936
13382
  // feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
@@ -12948,6 +13394,17 @@ function cmdShip(argv) {
12948
13394
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
12949
13395
  if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
12950
13396
 
13397
+ // #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
13398
+ // branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
13399
+ // remote-only branch resolve here at all.
13400
+ const handoff = applyShipHandoff(repoAbs, sess, opts, trunk);
13401
+ if (handoff && !handoff.ok) {
13402
+ process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
13403
+ `ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
13404
+ process.stderr.write(' Nothing was claimed or taken over here — the executor\'s claim still stands.\n');
13405
+ return 1;
13406
+ }
13407
+
12951
13408
  // ---- the recorded branch must RESOLVE, before anything else is computed ----
12952
13409
  // Everything downstream is keyed to this name: the claim lookup above, the migration diff, the
12953
13410
  // squash. A worktree record holding a role word or a deleted branch fails all three quietly —
@@ -13007,6 +13464,7 @@ function cmdShip(argv) {
13007
13464
  const gh = isGhUsable(repoAbs);
13008
13465
  // #345: the gate that passed is the table's first row, so a reader sees WHICH door opened it.
13009
13466
  const checks = [['✓', 'autonomy granted', autonomyGate.detail]];
13467
+ if (handoff) checks.push(['✓', 'hand-off verified (#578)', handoffDetail(handoff)]);
13010
13468
 
13011
13469
  // Which claimed issues are REFERENCED (Refs #N), not closed — three sources unioned by
13012
13470
  // resolveCloseRefsSplit (#48, #74): --refs, the tracking label, and #74's close gate (an
@@ -13118,6 +13576,11 @@ function cmdShip(argv) {
13118
13576
  const coreReview = shipCoreReview(repoAbs, gh, target, sess.branch);
13119
13577
  const coreOk = coreReview.verdict !== 'refuse';
13120
13578
  checks.push([coreOk ? (coreReview.verdict === 'pending' ? '⏸' : '✓') : '✗', 'core-path review (#350)', coreReview.detail]);
13579
+
13580
+ // #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
13581
+ // hold is not a failed precondition — it is a pause, taken below once every real one has passed.
13582
+ const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
13583
+ if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
13121
13584
  for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
13122
13585
 
13123
13586
  // #389: the record this ship will write after the push must be writable NOW.
@@ -13352,6 +13815,8 @@ function cmdShip(argv) {
13352
13815
  print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · ' +
13353
13816
  (opts.keepWorktree ? 'keep worktree' : 'worktree rm') + ' (releases claims)');
13354
13817
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
13818
+ } else if (lane && lane.held && coreReview.verdict !== 'pending') {
13819
+ print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
13355
13820
  } else if (coreReview.verdict === 'pending') {
13356
13821
  print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
13357
13822
  'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
@@ -13417,6 +13882,9 @@ function cmdShip(argv) {
13417
13882
  return shipOpenCorePr(repoAbs, coreReview, { target, branch: sess.branch, title, body });
13418
13883
  }
13419
13884
 
13885
+ // ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
13886
+ if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
13887
+
13420
13888
  // ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
13421
13889
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
13422
13890
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
@@ -13562,6 +14030,10 @@ function cmdShip(argv) {
13562
14030
  ciGrantForTrailer = ciResultB1.grantVerdict;
13563
14031
  }
13564
14032
  }
14033
+ // #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
14034
+ // built in that window is exactly as live as one the table saw.
14035
+ const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
14036
+ if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
13565
14037
  // WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
13566
14038
  // (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
13567
14039
  // out onto a long-lived line is the very state that made this axis necessary — everything reading
@@ -13679,7 +14151,7 @@ function cmdShip(argv) {
13679
14151
  (publicOmit ? (m) => print(` ${m}`) : warn)(`Machine trailer ${machineTrailerSummary(trailerDecision)}`);
13680
14152
  }
13681
14153
  const machineLine = trailerDecision.line;
13682
- const ciTrailerLines = [ciTrailer, adoptTrailer, machineLine].filter(Boolean);
14154
+ const ciTrailerLines = [ciTrailer, adoptTrailer, shipHandoff.handoffTrailer(sess.handoff), machineLine].filter(Boolean);
13683
14155
  if (opts.message) {
13684
14156
  // --message overrides the subject/body, but Closes is spliced in as its own paragraph — never
13685
14157
  // concatenated. Appending it welded ` — Closes #N` onto whatever the message ended with, which
@@ -13688,7 +14160,7 @@ function cmdShip(argv) {
13688
14160
  for (const tl of ciTrailerLines) {
13689
14161
  if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
13690
14162
  const lastLine = commitMsg.split('\n').pop().trim();
13691
- commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
14163
+ commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
13692
14164
  }
13693
14165
  } else {
13694
14166
  // Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
@@ -13850,11 +14322,13 @@ function cmdShip(argv) {
13850
14322
  // a long ship these lines would otherwise scroll off above the `✓ Shipped` line — which is
13851
14323
  // exactly how #304's failure went unnoticed in the first place.
13852
14324
  deferredCollector = [];
14325
+ let reviewPrHandled = null; // #584: the #350 review PR, already closed (or warned about) above
13853
14326
  // #350: the approved PR is spent — its work landed by squash, which the forge cannot see as a merge.
13854
14327
  if (coreReview.verdict === 'approved' && coreReview.pr && gh) {
13855
14328
  const closed = git.ghPrClose(repoAbs, coreReview.pr.number, `Landed on \`${target}\` as ${sha} by \`colab ship\` (#350), approved by ${coreReview.approval.by}.`);
13856
14329
  if (closed.ok) print(` closed PR #${coreReview.pr.number} (landed as ${sha})`);
13857
14330
  else warnDeferred(`could not close PR #${coreReview.pr.number} (${(closed.stderr || '').split('\n')[0]}) — it landed as ${sha}; close it by hand`);
14331
+ reviewPrHandled = coreReview.pr.number; // #584: either way the tail's landed-PR close must not touch it again
13858
14332
  }
13859
14333
  // Only when the target IS the shared checkout. `ephemeralTarget === false` means
13860
14334
  // `targetDir === repoAbs` (see #234's note above); a declared integration line merged in a
@@ -13898,7 +14372,7 @@ function cmdShip(argv) {
13898
14372
  pushEvent('ship', {
13899
14373
  repo: repoAbs, worktree: sess.name, session: sess.session,
13900
14374
  issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
13901
- payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}) },
14375
+ payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}), ...(sess.handoff ? { handoff: { url: sess.handoff.url, sha: sess.handoff.sha } } : {}) },
13902
14376
  });
13903
14377
 
13904
14378
  // Then, PER ISSUE, a merge-completion event (#46 §2, following #45 §2). The ship event above is
@@ -13920,11 +14394,13 @@ function cmdShip(argv) {
13920
14394
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
13921
14395
  // same block, and re-assigning the collector here would silently discard them.
13922
14396
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
13923
- evidenceExtra: opts.humanDoorEvidence || '' }); // #525
14397
+ skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14398
+ evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
13924
14399
 
13925
14400
  print('');
13926
14401
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
13927
14402
  if (adoptInfo) print(` adopted from ${adoptInfo.remote || 'origin'}/${adoptInfo.branch} @ ${shortSha(adoptInfo.remoteSha)} — recorded in the Colab-Adopted: trailer (#324)`);
14403
+ if (sess.handoff) print(` landed from the hand-off ${sess.handoff.url} — the executor's claim and worktree stay until it confirms the land (#578)`);
13928
14404
  if (target !== trunk) print(` "${target}" is a declared line: this work is NOT in ${trunk} until a human merges the line.`);
13929
14405
  // #114: everything deferred since the push (e2, #304) lands here, AFTER the success line — not scattered above it
13930
14406
  // where a long ship scrolls it out of view. The merge itself already landed either way; this is
@@ -13938,6 +14414,38 @@ function cmdShip(argv) {
13938
14414
  }
13939
14415
 
13940
14416
 
14417
+ /**
14418
+ * #584: close every open PR whose head is the branch this ship just landed — the PR a person or an
14419
+ * automation opened only to obtain branch CI. The forge never sees a squash as a merge of that PR, so
14420
+ * without this it stays open forever, reading as unmerged work. Only a PR whose head commit is the
14421
+ * landed tip (or an ancestor of it) is closed; one carrying commits that did not land is kept and
14422
+ * reported. Best-effort throughout: every failure defers a warning, none fails the ship.
14423
+ */
14424
+ function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
14425
+ const remoteName = git.remoteInfo(repoAbs).name || 'origin';
14426
+ const tipOf = (ref) => { const r = git.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoAbs); return r.ok ? r.stdout.trim() : null; };
14427
+ const tip = tipOf(`refs/heads/${sess.branch}`) || tipOf(`refs/remotes/${remoteName}/${sess.branch}`);
14428
+ const headLanded = (oid) => {
14429
+ if (!tip) return false;
14430
+ if (oid === tip) return true;
14431
+ return git.git(['merge-base', '--is-ancestor', oid, tip], repoAbs).ok;
14432
+ };
14433
+ const res = landedPrs.closeLandedPrs({
14434
+ prs: git.ghOpenPrsForBranch(repoAbs, sess.branch),
14435
+ headLanded,
14436
+ close: (n, comment) => git.ghPrClose(repoAbs, n, comment),
14437
+ comment: landedPrs.landedPrComment({ target, sha, issues }),
14438
+ skip,
14439
+ });
14440
+ if (res.listError) {
14441
+ warnDeferred(`could not list open PRs for ${sess.branch} (${res.listError}) — any PR opened for its CI is still open; close it by hand (it landed as ${sha})`);
14442
+ return;
14443
+ }
14444
+ for (const n of res.closed) print(` closed PR #${n} — its branch ${sess.branch} landed as ${sha} (#584)`);
14445
+ for (const f of res.failed) warnDeferred(`could not close PR #${f.number} (${f.error}) — ${sess.branch} landed as ${sha}; close it by hand`);
14446
+ for (const k of res.kept) warnDeferred(`kept PR #${k.number} open: ${k.reason} (${sess.branch} landed as ${sha}) — it carries work that did not ship`);
14447
+ }
14448
+
13941
14449
  /**
13942
14450
  * The post-merge tail every landed branch gets — cmdShip's B3 through i2, moved here unchanged (#373)
13943
14451
  * so a batch member gets exactly the same steps in the same order: worktree teardown (B3), the claims
@@ -13946,7 +14454,13 @@ function cmdShip(argv) {
13946
14454
  * addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
13947
14455
  * batch member.
13948
14456
  */
13949
- function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '' }) {
14457
+ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
14458
+ // #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
14459
+ // B3 below may delete it, and "did the PR's head land?" is answered against that tip.
14460
+ if (gh && sess.branch) {
14461
+ try { shipCloseLandedPrs(repoAbs, sess, { target, sha, issues: closeIssues, skip: skipPrs }); }
14462
+ catch (e) { warnDeferred(`landed-PR close for ${sess.branch} failed (${e.message}) — the ship landed as ${sha}; close any PR for it by hand`); }
14463
+ }
13950
14464
  const worktreeKept = !!(sess.name && opts.keepWorktree);
13951
14465
  if (sess.name && !opts.keepWorktree) {
13952
14466
  print(`B3: removing worktree ${sess.name} …`);
@@ -13966,7 +14480,8 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
13966
14480
  // B3 (cont.) — the shipped branch. Kept by default; --delete-branch opts in. MUST come after the
13967
14481
  // worktree removal above: git refuses to delete a branch checked out in a worktree.
13968
14482
  // #368: a Refs-only ship deletes unless --keep-branch — see tools/lib/shipped-branch.js.
13969
- const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch });
14483
+ // #578: a handed-off branch is the executor's until it confirms the land — never deleted for it.
14484
+ const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch || (!!sess.handoff && !opts.deleteBranch) });
13970
14485
  handleShippedBranch(repoAbs, target, sess.branch, { disposition, worktreeKept, integration });
13971
14486
 
13972
14487
  // ---- (g/h) B4 verify + post summary per issue ----
@@ -14082,6 +14597,46 @@ function shipDryJsonReport(opts) {
14082
14597
  return { ok: code === 0, body: holder.body || null, error: null };
14083
14598
  }
14084
14599
 
14600
+ /**
14601
+ * #581: is a batch in flight at trunk's current tip? Read by every serial door that moves trunk (the
14602
+ * prose ship's table and B1, `--dry --json`), so a lander told about it waits instead of moving trunk
14603
+ * under the batch — which would throw the batch's green combined run away. The rule is
14604
+ * lib/ship-batch.js laneHold; this only reads the remote.
14605
+ *
14606
+ * Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
14607
+ * trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
14608
+ */
14609
+ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
14610
+ if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
14611
+ const remote = git.remoteFor(repoAbs);
14612
+ const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
14613
+ if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
14614
+ const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
14615
+ const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
14616
+ const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
14617
+ .filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
14618
+ const batches = atTip.map((x) => {
14619
+ const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
14620
+ let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
14621
+ if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
14622
+ const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
14623
+ return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
14624
+ builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
14625
+ });
14626
+ const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
14627
+ const detail = r.held
14628
+ ? `${r.ref} holds the ${trunk} lane — ${r.why}; landing now would move ${trunk} under it and discard its run`
14629
+ : (r.released.length ? `no batch holds the lane (${r.released.map((x) => `${x.ref}: ${x.why}`).join('; ')})` : `no batch in flight at ${trunk}@${shortSha(trunkNow)}`);
14630
+ return { ...r, trunkNow, detail };
14631
+ }
14632
+
14633
+ /** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
14634
+ function printBatchLanePause(lane, trunk) {
14635
+ print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
14636
+ print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
14637
+ print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
14638
+ }
14639
+
14085
14640
  function cmdShipBatch(opts) {
14086
14641
  for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
14087
14642
  if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
@@ -14104,17 +14659,32 @@ function cmdShipBatch(opts) {
14104
14659
  if (String(doc.autonomy || '') !== 'auto-trunk') {
14105
14660
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
14106
14661
  }
14107
- // #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
14662
+ // #555: a declared ship-batch-wait makes a lone member wait for a partner below.
14663
+ // #562: one named member is a valid batch — it lands through the combined run, never serially.
14108
14664
  const waitCfg = shipBatch.parseShipBatchWait(doc);
14109
14665
  if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
14110
- if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
14111
- if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
14666
+ if (members.length < 1) return serial('--batch names no branch — name every ready candidate');
14112
14667
 
14113
14668
  const remote = git.remoteFor(repoAbs);
14114
14669
  const fetched = git.git(['fetch', '--prune', remote], repoAbs);
14115
14670
  if (!fetched.ok) throw new UserError(`could not fetch ${remote}: ${git.gitFailureLine(fetched.stderr)} — a batch is never built from stale refs`);
14116
14671
  const trunkRef = `${remote}/${trunk}`;
14117
14672
 
14673
+ // #557: the size this batch is built at — fixed at ship-batch without steps; with them, one step
14674
+ // above the last landed batch's size after a green, one below after a red, read from trunk alone.
14675
+ const stepsCfg = shipBatch.parseShipBatchSteps(doc);
14676
+ if (!stepsCfg.valid) warn(`${stepsCfg.reason} — ignored: every batch is up to ship-batch: ${cfg.n} (fails closed, #557)`);
14677
+ let lastSize = null;
14678
+ if (stepsCfg.steps) {
14679
+ const lg = git.git(['log', '-1', '--first-parent', `--grep=^${shipBatch.SIZE_TRAILER_KEY}: `, '--format=%B', trunkRef], repoAbs);
14680
+ lastSize = lg.ok ? shipBatch.parseSizeTrailer([lg.stdout]) : null;
14681
+ }
14682
+ const size = shipBatch.adaptiveSize({ n: cfg.n, steps: stepsCfg.steps, last: lastSize });
14683
+ const sizeLabel = stepsCfg.steps
14684
+ ? `ship-batch: ${cfg.n} · step ${size} of ${stepsCfg.steps.join(',')}${lastSize ? ` — the last landed batch was ${lastSize.red ? `a split of a red one at ${lastSize.size}` : `green at ${lastSize.size}`}` : ' — no sized batch on trunk yet'}`
14685
+ : `ship-batch: ${cfg.n}`;
14686
+ if (members.length > size) warn(`--batch names ${members.length} branches; ${sizeLabel} caps the batch — the rest wait for the next one`);
14687
+
14118
14688
  // ---- (a) wiring: could the combined run ever arrive? Decided BEFORE anything is pushed. ----
14119
14689
  const fires = workflowsFiringAt(repoAbs, trunkRef, shipBatch.PROBE_REF);
14120
14690
  if (!shipBatch.wiring(fires).wired) {
@@ -14173,8 +14743,9 @@ function cmdShipBatch(opts) {
14173
14743
  }
14174
14744
  if (!foreignStep) {
14175
14745
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
14176
- const matches = heads.length >= 2 && heads.every((m) => m.now && m.now.startsWith(m.sha));
14177
- existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
14746
+ const matches = heads.length >= 1 && heads.every((m) => m.now && m.now.startsWith(m.sha));
14747
+ existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches,
14748
+ size: shipBatch.parseSizeTrailer(log.ok ? log.stdout.split('\0') : []) };
14178
14749
  // #415: the command line and the staged batch can name different sets. A requested branch the
14179
14750
  // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
14180
14751
  // along — say so, naming both lists, instead of resuming as if the two were the same.
@@ -14186,7 +14757,10 @@ function cmdShipBatch(opts) {
14186
14757
  }
14187
14758
  }
14188
14759
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14189
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: 2, existing, trunkNow, verdict });
14760
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
14761
+ if (opts.split && !(verdict && verdict.state === 'red')) {
14762
+ 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)`);
14763
+ }
14190
14764
 
14191
14765
  if (step.step === 'rebuild') {
14192
14766
  print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
@@ -14208,6 +14782,24 @@ function cmdShipBatch(opts) {
14208
14782
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
14209
14783
  return 4;
14210
14784
  }
14785
+ if (step.step === 'red-rerun-or-split') {
14786
+ const ids = verdict.runIds.join(', ') || '(id unread)';
14787
+ const cmd = `colab ship --batch ${members.join(',')} --split${opts.repo ? ` --repo ${opts.repo}` : ''}`;
14788
+ print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}; run ${ids}). Nothing landed.`);
14789
+ print(` ${existing.members.length} members — it splits rather than going serial (#557). Classify it first (CONVENTIONS §4, Branch CI):`);
14790
+ for (const id of verdict.runIds) print(` red:infra → gh run rerun ${id} --failed then run this command again (one re-run only)`);
14791
+ print(` red:finding → ${cmd}`);
14792
+ print(' rebuilds this batch with its first half; the rest wait for the next batch');
14793
+ return 4;
14794
+ }
14795
+ let splitHalf = null;
14796
+ if (step.step === 'split') {
14797
+ const { first, held } = shipBatch.splitHalves(existing.members);
14798
+ splitHalf = { first, held, parentSize: existing.size ? existing.size.size : existing.members.length };
14799
+ print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}${verdict.attempt >= 2 ? ', after its one re-run' : ''}). Nothing landed.`);
14800
+ print(` splitting (#557): testing ${first.map((m) => m.branch).join(', ')} on the same base; held for the next batch: ${held.map((m) => m.branch).join(', ')}`);
14801
+ step = { step: 'build' };
14802
+ }
14211
14803
  if (step.step === 'red-serial') {
14212
14804
  print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
14213
14805
  deleteRef(existing.ref);
@@ -14240,13 +14832,21 @@ function cmdShipBatch(opts) {
14240
14832
  // #387: a generated path shared by two members is not an overlap — the build regenerates it (below).
14241
14833
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
14242
14834
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
14243
- const { selected, overflow } = shipBatch.selectMembers(eligible, cfg.n, { isGenerated: (f) => isGeneratedPath(f, generated) });
14244
- print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (ship-batch: ${cfg.n})${opts.dry ? ' [DRY RUN]' : ''}`);
14835
+ // #557: a split builds exactly its first half, in the red batch's order — the pre-sort is not re-run,
14836
+ // or a different subset would be tested and the bisection would not narrow.
14837
+ const { selected, overflow } = splitHalf
14838
+ ? (() => {
14839
+ const want = splitHalf.first.map((m) => m.branch);
14840
+ const sel = want.map((b) => eligible.find((e) => e.branch === b)).filter(Boolean);
14841
+ return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
14842
+ })()
14843
+ : shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
14844
+ 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]' : ''}`);
14245
14845
  print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
14246
- e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14846
+ 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']));
14247
14847
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14248
14848
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14249
- if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14849
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
14250
14850
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14251
14851
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14252
14852
  const lone = selected[0];
@@ -14256,13 +14856,13 @@ function cmdShipBatch(opts) {
14256
14856
  if (pw.wait) {
14257
14857
  print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
14258
14858
  print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14259
- print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
14859
+ print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone, as a batch of one.');
14260
14860
  return 3;
14261
14861
  }
14262
14862
  const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
14263
- return serial(`1 member can join and no partner arrived — ${why}`);
14863
+ print(` no partner arrived for ${lone.branch} — ${why}; building a batch of one (the combined run still gates it, #562)`);
14264
14864
  }
14265
- if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
14865
+ if (step.step === 'serial') return serial('no member can join — each one above says why');
14266
14866
 
14267
14867
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14268
14868
  const ref = shipBatch.batchRefName(trunkNow);
@@ -14337,22 +14937,26 @@ function cmdShipBatch(opts) {
14337
14937
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
14338
14938
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14339
14939
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14340
- // Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
14341
- if (dropped.length && built.length >= 2) {
14940
+ // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
14941
+ // #557: with steps declared (or on a split), the head also carries the size it was built at, so the
14942
+ // next build reads the lane's last outcome from trunk alone.
14943
+ const sizeLine = splitHalf ? shipBatch.sizeTrailer({ size: splitHalf.parentSize, red: true })
14944
+ : (stepsCfg.steps ? shipBatch.sizeTrailer({ size }) : null);
14945
+ if ((dropped.length || sizeLine) && built.length >= 1) {
14342
14946
  const last = built[built.length - 1];
14343
14947
  const cur = git.git(['log', '-1', '--format=%B'], dir);
14344
- const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
14948
+ const lines = [...dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls })), ...(sizeLine ? [sizeLine] : [])];
14345
14949
  const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
14346
14950
  if (am.ok) last.commit = git.git(['rev-parse', 'HEAD'], dir).stdout;
14347
- else warn(`could not record the dropped member(s) on the batch head: ${git.gitFailureLine(am.stderr)} — the drop is on this terminal only`);
14951
+ else warn(`could not record the dropped member(s)/size on the batch head: ${git.gitFailureLine(am.stderr)} — they are on this terminal only`);
14348
14952
  }
14349
14953
  for (const b of built.filter((x) => x.regenerated)) {
14350
14954
  print(` ↻ ${b.branch}: combined despite a generated-file overlap — ${b.regenerated.join(', ')} regenerated by .colab/hooks/pre-ship on the combined head (the combined run is the gate)`);
14351
14955
  }
14352
14956
  const head = git.git(['rev-parse', 'HEAD'], dir).stdout;
14353
- if (built.length < 2) {
14957
+ if (built.length < 1) {
14354
14958
  cleanup();
14355
- return serial(`${built.length} member(s) survived the build — a batch needs at least two`, members);
14959
+ return serial('no member survived the build', members);
14356
14960
  }
14357
14961
  if (opts.dry) {
14358
14962
  cleanup();
@@ -14366,7 +14970,7 @@ function cmdShipBatch(opts) {
14366
14970
  cleanup();
14367
14971
  if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
14368
14972
  print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
14369
- if (overflow.length) print(` eligible but over the cap (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
14973
+ if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
14370
14974
  print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
14371
14975
  return 3;
14372
14976
  }
@@ -14991,11 +15595,17 @@ its head, trunk runs say when a landing was pushed and when its trunk-CI cycle e
14991
15595
  Reports:
14992
15596
  batches landed, and their fill · combined-run builds: first-attempt green, green after the
14993
15597
  one re-run, red, pending
14994
- red red builds, and how many of their members then landed serially (the fallback)
15598
+ red red builds, and how many of their members then landed alone — serially, or as a
15599
+ batch of one (#580) — the fallback
14995
15600
  dropped members dropped at build, by class, and the eviction rate
14996
15601
  serial serial landings, and MISSED PARTNERS — another change, landed later, that was
14997
15602
  already green when this one landed alone (could have joined) or went green inside
14998
- this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys)
15603
+ this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys).
15604
+ "serial" means landed through the serial path, and only that
15605
+ alone the same partner scan over every change that landed ALONE — serially or as a batch
15606
+ of one (#580). On a ship-batch repo a lone ready candidate lands as a fill-1 batch,
15607
+ so there serial reads zero either way; alone is the line to tune ship-batch-wait by.
15608
+ Printed only when a batch of one landed (otherwise it equals serial)
14999
15609
  queue wait green-at-head → landing, per landed change
15000
15610
 
15001
15611
  No batch history in the window is an answer, not an error: it says so, and still reports the
@@ -15014,6 +15624,9 @@ function batchStatsSince(v, nowMs) {
15014
15624
  return Number.isFinite(t) ? t : null;
15015
15625
  }
15016
15626
 
15627
+ /** The trunk log read's buffer (#585); COLAB_BATCH_STATS_MAX_BUFFER overrides it, for a test. */
15628
+ const BATCH_STATS_LOG_MAX_BUFFER = Number(process.env.COLAB_BATCH_STATS_MAX_BUFFER) || 256 * 1024 * 1024;
15629
+
15017
15630
  function cmdBatchStats(argv) {
15018
15631
  const opts = parseArgs(argv, {
15019
15632
  values: { '--repo': 'repo', '--since': 'since' },
@@ -15034,7 +15647,11 @@ function cmdBatchStats(argv) {
15034
15647
  const remote = git.remoteFor(repoAbs);
15035
15648
  const f = git.git(['fetch', remote, trunk], repoAbs);
15036
15649
  if (!f.ok) notes.push(`could not fetch ${remote}/${trunk} (${git.gitFailureLine(f.stderr)}) — read from the local copy, which may be behind`);
15037
- const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs);
15650
+ // Full squash bodies over a long window pass spawnSync's 1 MiB default (measured 2026-10-10:
15651
+ // 60 days of one repo's trunk came to 1,061,950 bytes), and ENOBUFS then read as a failed
15652
+ // fetch (#585). The buffer is sized for the read; a spawn error is reported as itself.
15653
+ const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs, { maxBuffer: BATCH_STATS_LOG_MAX_BUFFER });
15654
+ if (!log.ok && log.error) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — pass a shorter --since, then run \`colab batch-stats\` again`);
15038
15655
  if (!log.ok) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — run \`git fetch ${remote} ${trunk}\`, then run this again`);
15039
15656
  const commits = log.stdout.split('\x1e').map((r) => r.replace(/^\n/, '')).filter((r) => r.trim()).map((r) => {
15040
15657
  const [sha, iso, body] = r.split('\x1f');
@@ -15100,12 +15717,17 @@ function cmdBatchStats(argv) {
15100
15717
  else {
15101
15718
  const fill = Object.keys(rep.batches.fill).sort().map((k) => `${rep.batches.fill[k]}×${k}`).join(' · ') || '—';
15102
15719
  print(` batches ${rep.batches.landed} landed (fill ${fill}) · ${rep.batches.builds} combined-run build(s): ${rep.batches.firstAttemptGreen} first-attempt green (${pct(rep.batches.firstAttemptGreenRate)}), ${rep.batches.greenAfterRerun} after a re-run, ${rep.batches.red} red, ${rep.batches.pending} pending`);
15103
- print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedSerially} then landed serially`);
15720
+ print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedAlone} then landed alone (${rep.red.relandedSerially} serially · ${rep.red.relandedAlone - rep.red.relandedSerially} as a batch of one)`);
15104
15721
  const cls = Object.entries(rep.dropped.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
15105
15722
  print(` dropped ${rep.dropped.count} of ${rep.dropped.attempted} attempted (${pct(rep.dropped.rate)})${cls ? ` — ${cls}` : ''}`);
15106
15723
  }
15107
15724
  print(` serial ${rep.serial.landings} landed alone · ${rep.serial.withMissedPartner} with a missed partner (already green) · ${rep.serial.withNearMiss} more with a near miss (green within its trunk-CI cycle)`);
15108
15725
  if (rep.serial.nearMissWait.samples) print(` near misses per pair, the wait from the lone change's own green that would have caught its partner: ${q(rep.serial.nearMissWait)}`);
15726
+ if (rep.alone.batchOfOne) {
15727
+ // #580: a batch of one landed alone too — the serial line above cannot see it.
15728
+ print(` alone ${rep.alone.landings} landed alone (${rep.alone.landings - rep.alone.batchOfOne} serial · ${rep.alone.batchOfOne} batch of one) · ${rep.alone.withMissedPartner} with a missed partner (already green) · ${rep.alone.withNearMiss} more with a near miss`);
15729
+ if (rep.alone.nearMissWait.samples) print(` near misses (alone) ${q(rep.alone.nearMissWait)}`);
15730
+ }
15109
15731
  print(` queue wait green-at-head → landing: ${q(rep.queueWait)}`);
15110
15732
  for (const n of rep.notes) print(` ! ${n}`);
15111
15733
  return 0;
@@ -15362,6 +15984,59 @@ Empty output is clean ground ONLY when the fetch succeeded. Exit: 0 answered, 2
15362
15984
  staleness (fetch skipped or failed, and the result would have been "clean").
15363
15985
  `;
15364
15986
 
15987
+ const HELP_INSTRUCTION_FILES = `colab instruction-files [--base <rev> | --staged] [--repo <path>] [--json]
15988
+
15989
+ Is every tracked CLAUDE.md the thin-shell shape — the \`@AGENTS.md\` import plus tool-managed blocks,
15990
+ with the repo's prose in AGENTS.md (CONVENTIONS.md §9 step 5, #588)? One judgement
15991
+ (tools/lib/instruction-file.js), shared with the audit, the pre-commit hook and the reusable CI
15992
+ workflow \`.github/workflows/instruction-files.yml\`.
15993
+
15994
+ --base <rev> RATCHET against merge-base(<rev>, HEAD). Fails only when a CLAUDE.md does not
15995
+ conform at HEAD AND either a CLAUDE.md/AGENTS.md changed since the merge base, or
15996
+ every CLAUDE.md conformed there. An unmigrated repo whose change leaves both files
15997
+ alone passes. This is what CI runs.
15998
+ --staged judge the INDEX against HEAD, same ratchet (staging a CLAUDE.md/AGENTS.md is
15999
+ touching it). This is what the pre-commit hook runs.
16000
+ (neither) judge every CLAUDE.md at HEAD, no ratchet: any non-conforming file fails.
16001
+ --repo <path> repo to run in (default: cwd)
16002
+ --json { ok, error?, mode, base, fail, reason, files: [{ path, conforming, message }], changed }
16003
+
16004
+ Exit: 0 pass · 1 fail · 2 cannot judge (not a repo, base not fetched — never read as a pass).
16005
+ The fix for a failure is always the same: move the prose to AGENTS.md (handbook-sync's graft step
16006
+ does the move), keeping CLAUDE.md to \`@AGENTS.md\`, blank lines and tool blocks.
16007
+ `;
16008
+
16009
+ function cmdInstructionFiles(argv) {
16010
+ const opts = parseArgs(argv, {
16011
+ values: { '--repo': 'repo', '--base': 'base' },
16012
+ flags: { '--json': 'json', '--staged': 'staged', '-h': 'help', '--help': 'help' },
16013
+ });
16014
+ if (opts.help) return print(HELP_INSTRUCTION_FILES);
16015
+ if (opts.staged && opts.base) throw new UserError('--staged and --base are two different questions — pass one: `colab instruction-files --staged` (a commit) or `colab instruction-files --base <rev>` (a branch)');
16016
+ // The tree you stand in, NOT resolveRepo's main checkout: from inside a linked worktree the hook
16017
+ // and CI must judge that worktree's index and HEAD, never trunk's.
16018
+ const at = opts.repo ? path.resolve(String(opts.repo)) : process.cwd();
16019
+ const cwd = git.repoRoot(at);
16020
+ if (!cwd) throw new UserError(`${at} is not inside a git repo — pass --repo <path>`);
16021
+ const r = instructionGate.gate({ cwd, staged: !!opts.staged, base: opts.base ? String(opts.base) : null });
16022
+ if (opts.json) {
16023
+ print(JSON.stringify(r, null, 2));
16024
+ return !r.ok ? 2 : r.fail ? 1 : 0;
16025
+ }
16026
+ const lines = instructionGate.describe(r);
16027
+ if (!r.ok) {
16028
+ process.stderr.write(`✗ instruction-files: ${lines[0]} — re-run once the base is fetched (\`git fetch origin\`), or run \`colab instruction-files\` with no --base to judge without the ratchet\n`);
16029
+ return 2;
16030
+ }
16031
+ if (r.fail) {
16032
+ process.stderr.write(`✗ instruction-files: CLAUDE.md carries repo prose — move it to AGENTS.md (\`colab instruction-files --help\`)\n`);
16033
+ for (const l of lines) process.stderr.write(` ${l}\n`);
16034
+ return 1;
16035
+ }
16036
+ for (const l of lines) print(r.bad.length ? `! ${l}` : `✓ ${l}`);
16037
+ return 0;
16038
+ }
16039
+
15365
16040
  function cmdHolders(argv) {
15366
16041
  const opts = parseArgs(argv, {
15367
16042
  values: { '--repo': 'repo', '--base': 'base' },
@@ -15992,6 +16667,8 @@ Commands:
15992
16667
  blocked <blocked> --by <blocker> [--clear --reason R [--force]] [--repo P]
15993
16668
  own the blocked_by dependency-edge write (#251)
15994
16669
  migration-grant <issue> --branch B | --revoke | --list [--json] human-only ship migration exemption (#98)
16670
+ owner-policy [show [--json]] | set migration-grant <human|reviewer|unset> owner-level grant policy,
16671
+ every repo the GitHub owner runs; set is human-only (#596)
15995
16672
  decision <issue> --record --ruled-by N | --reopen --ruled-by N | --list [--json]
15996
16673
  record/reopen a needs-decision answer (#121, #122)
15997
16674
  ci-grant <issue> --branch B | --revoke | --list [--json] ship trunk-CI-green exemption: human, or ci-reviewer under opt-in (#105, #504)
@@ -16028,6 +16705,10 @@ Commands:
16028
16705
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
16029
16706
  have not landed on the base (filters the raw git-log
16030
16707
  one-liner through \`landed\`'s content classification)
16708
+ instruction-files [--base B | --staged] [--json]
16709
+ CLAUDE.md is only @AGENTS.md + tool blocks? ratcheted:
16710
+ fails only where the change touches it or would regress
16711
+ a migrated repo (#588) — the hook and CI run this
16031
16712
  promote [--repo P] [--message M] [--dry] trunk → main (--no-ff); gated by deploy + promotion; never tags
16032
16713
  deliver [--repo P] [--dry] [--json] [--reopen] project.yml owner: only — open/refresh ONE PR
16033
16714
  trunk → the owner's branch; never merges it (#394)
@@ -16100,6 +16781,7 @@ function main(argv) {
16100
16781
  case 'readiness': return cmdReadiness(rest);
16101
16782
  case 'blocked': return cmdBlocked(rest);
16102
16783
  case 'migration-grant': return cmdMigrationGrant(rest);
16784
+ case 'owner-policy': return cmdOwnerPolicy(rest);
16103
16785
  case 'decision': return cmdDecision(rest);
16104
16786
  case 'ci-grant': return cmdCiGrant(rest);
16105
16787
  case 'claims': return cmdClaims(rest);
@@ -16115,6 +16797,7 @@ function main(argv) {
16115
16797
  case 'trunk-ci': return cmdTrunkCi(rest);
16116
16798
  case 'ci-wait': return cmdCiWait(rest);
16117
16799
  case 'holders': return cmdHolders(rest);
16800
+ case 'instruction-files': return cmdInstructionFiles(rest);
16118
16801
  case 'promote': return cmdPromote(rest);
16119
16802
  case 'deliver': return cmdDeliver(rest);
16120
16803
  case 'doctor': return cmdDoctor(rest);