@futurelastic/colab-handbook 1.12.0-rc.45 → 1.12.0-rc.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.45"
30
+ "version": "1.12.0-rc.47"
31
31
  }
package/tools/colab CHANGED
@@ -470,9 +470,14 @@ function remoteClaimConflicts(st, repoAbs, nums) {
470
470
  const want = new Set(nums);
471
471
  const records = [...Object.values(st.worktrees || {}), ...Object.values(st.claims || {})];
472
472
  const ours = (b) => records.some((r) => r && r.repo === repoAbs && r.branch === b && machine.isLocal(r));
473
+ // #485: a dependabot ref, trunk and every declared integration: line are never a session's claim —
474
+ // their trailing digits are a version or an accident of naming. Same filter as code-sweep §1.3.
475
+ const doc = projectDoc(repoAbs);
476
+ const trunk = resolveTrunk(repoAbs, doc) || '';
477
+ const scope = { trunk, integration: trunk ? resolveIntegration(repoAbs, doc, trunk) : [] };
473
478
  const conflicts = [];
474
479
  for (const h of heads.heads) {
475
- const carried = shipguard.branchIssueNumbers(h.branch).filter((n) => want.has(n));
480
+ const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
476
481
  if (!carried.length || ours(h.branch)) continue;
477
482
  for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
478
483
  }
@@ -7473,7 +7478,7 @@ const HELP_ADOPT = `colab adopt [--repo <path>] [--json] [--no-verify] [--axis a
7473
7478
  [--writes <free|direct|isolated>] [--channels <c1,c2,...>]
7474
7479
  [--production <url>|none] [--deploy <push-main|tag|manual|none>]
7475
7480
  [--stack "<text>"] [--answered-by <name>] [--reason "<text>"]
7476
- [--fork | --no-fork]
7481
+ [--fork | --no-fork] [--autonomy <manual|auto-trunk>] [--land]
7477
7482
 
7478
7483
  Detects what a repo already states in .github/project.yml, ASKS a human only what could not be
7479
7484
  detected (flags, or a forced multiple-choice menu at a TTY — every row is a numbered choice,
@@ -7504,7 +7509,32 @@ accepted and reads as free — no adopter's descriptor breaks, and none is re-as
7504
7509
  named, and a new CLAUDE.md gets no AGENTS.md stub (CONVENTIONS.md §9,
7505
7510
  "A fork of an upstream")
7506
7511
 
7507
- Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack) makes the
7512
+ THE AUTONOMY GRANT AND --land (#481) — so a new repo's first branch is not hand-merged:
7513
+
7514
+ --autonomy auto-trunk records the maintainer's grant (project.yml autonomy:) with the same
7515
+ provenance comment as every answer. It EXPANDS permission (an agent may
7516
+ then complete Phase B through \`colab ship\`), so it carries the writes:
7517
+ direct bar: interactive TTY, OR COLAB_HUMAN=1 AND --answered-by <name>
7518
+ (exit 3 otherwise). Refused with ceremony: light (exit 5). manual (the
7519
+ default) is never gated. Append-only: a different value already declared
7520
+ is refused (exit 5) — change it by hand.
7521
+ --land commits what THIS run wrote — the descriptor, plus the thin-shell
7522
+ CLAUDE.md/AGENTS.md when written now — straight to trunk as its own
7523
+ commit, then pushes origin/<trunk>. It is the human's adoption act, not
7524
+ an agent's: COLAB_HUMAN=1 AND --answered-by are required, no TTY
7525
+ substitute (exit 3). It runs only on the checkout standing ON trunk, never
7526
+ with --local, and refuses before writing anything when origin's trunk is
7527
+ ahead (pull first). Run without new answers, it lands a descriptor an
7528
+ earlier adopt left uncommitted. No origin remote: commits only.
7529
+
7530
+ The shape it exists for: \`colab ship\` judges a branch's autonomy by the descriptor trunk
7531
+ carries. Land it first, and the follow-up branch (CI workflow, guards, docs) ships through the
7532
+ normal lane under the grant — no human merge of the adoption branch.
7533
+
7534
+ COLAB_HUMAN=1 colab adopt --exposure self --stack node --autonomy auto-trunk \\
7535
+ --answered-by "<name>" --land
7536
+
7537
+ Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack/--autonomy) makes the
7508
7538
  whole run NON-INTERACTIVE — it never half-prompts. With no answer flags and no TTY, and something
7509
7539
  is still missing, this refuses in under a second, naming exactly which flags would answer it —
7510
7540
  never hangs waiting on stdin nobody is at.
@@ -7610,7 +7640,7 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
7610
7640
  block, topic, register, autopilot) and why.
7611
7641
 
7612
7642
  Boundary: adopt writes the descriptor and nothing else — no labels, no topic, no CI template, no
7613
- \`colab register\`, and it never commits. One exception (#417): on a repo with no descriptor before
7643
+ \`colab register\`, and it never commits unless --land asks it to (#481). One exception (#417): on a repo with no descriptor before
7614
7644
  the run and no CLAUDE.md, plain adopt also writes the thin-shell CLAUDE.md (\`@AGENTS.md\` + the
7615
7645
  filled Conventions block) and an AGENTS.md stub if none exists; an existing CLAUDE.md is never
7616
7646
  touched, and --local never writes either. It ends with the machine-readable
@@ -8099,9 +8129,9 @@ async function cmdAdopt(argv) {
8099
8129
  '--repo': 'repo', '--axis': 'axis', '--room': 'room', '--exposure': 'exposure',
8100
8130
  '--writes': 'writes', '--channels': 'channels', '--production': 'production',
8101
8131
  '--deploy': 'deploy', '--stack': 'stack', '--answered-by': 'answeredBy', '--reason': 'reason',
8102
- '--trunk': 'trunk',
8132
+ '--trunk': 'trunk', '--autonomy': 'autonomy',
8103
8133
  },
8104
- flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '-h': 'help', '--help': 'help' },
8134
+ flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '--land': 'land', '-h': 'help', '--help': 'help' },
8105
8135
  });
8106
8136
  if (opts.help) return print(HELP_ADOPT);
8107
8137
  if (opts.fork && opts.noFork) throw new UserError('--fork and --no-fork contradict each other — pass one');
@@ -8109,6 +8139,10 @@ async function cmdAdopt(argv) {
8109
8139
  throw new UserError('--trunk only means something with --local — on an ordinary adoption trunk is DETECTED, never asked (CONVENTIONS.md §9)');
8110
8140
  }
8111
8141
  if (opts.noLabels && !opts.local) throw new UserError('--no-labels only means something with --local — plain adopt never touches labels');
8142
+ if (opts.land && opts.local) throw new UserError('--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)');
8143
+ if (opts.autonomy !== undefined && !adopt.VALID_AUTONOMY.has(opts.autonomy)) {
8144
+ throw new UserError(`--autonomy must be one of: ${[...adopt.VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(opts.autonomy)})`);
8145
+ }
8112
8146
 
8113
8147
  // --local (#393): the descriptor is machine state, not a committable source file — it lives in
8114
8148
  // the MAIN checkout (where every worktree's `colab` call reads project.yml from, via
@@ -8139,9 +8173,33 @@ async function cmdAdopt(argv) {
8139
8173
  const localAnswerFlag = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'].some((k) => opts[k] !== undefined);
8140
8174
  if (local && !localAnswerFlag && !requestedAxes.length && axisAuthority.axisOfRecord(cfg).source === 'exposure') axesToAsk = [];
8141
8175
 
8176
+ const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
8177
+ const colabHuman = process.env.COLAB_HUMAN === '1';
8178
+
8179
+ // #481: --land preflight — every refusal here happens BEFORE anything is written, like the gates.
8180
+ let landTrunk = null;
8181
+ if (opts.land) {
8182
+ landTrunk = cfg.trunk ? String(cfg.trunk) : (extra.trunk || null);
8183
+ const cur = git.git(['symbolic-ref', '--short', 'HEAD'], repoAbs);
8184
+ const lv = adopt.landVerdict({ local: !!opts.local, colabHuman, answeredBy: opts.answeredBy || null,
8185
+ trunk: landTrunk, currentBranch: cur.ok && cur.stdout ? cur.stdout : null });
8186
+ if (!lv.ok) { warn(lv.message); return lv.exitCode; }
8187
+ const behind = adoptLandBehind(repoAbs, landTrunk);
8188
+ if (behind) { warn(behind); return 1; }
8189
+ }
8190
+
8191
+ // #481: --autonomy — the maintainer's grant, gated like writes: direct (it expands permission).
8192
+ let autonomyWrite = false;
8193
+ if (opts.autonomy !== undefined) {
8194
+ const av = adopt.autonomyGateVerdict({ autonomy: opts.autonomy, current: cfg.autonomy, ceremony: cfg.ceremony,
8195
+ isTTY, colabHuman, answeredBy: opts.answeredBy || null });
8196
+ if (!av.ok) { warn(av.message); return av.exitCode; }
8197
+ autonomyWrite = av.write;
8198
+ }
8199
+
8142
8200
  // Already complete (and nothing forced): report, write nothing, exit 0 — except the one key a
8143
8201
  // bare --local re-run still owes (#405): the `owner:` block, for a clone adopted before it existed.
8144
- if (axesToAsk.length === 0 && opts.stack === undefined) {
8202
+ if (axesToAsk.length === 0 && opts.stack === undefined && !autonomyWrite) {
8145
8203
  const backfill = localOwnerEntry(local, cfg, today());
8146
8204
  if (backfill) {
8147
8205
  fs.writeFileSync(descriptorFile, adopt.renderDescriptor(rawTextBefore, [backfill]));
@@ -8149,9 +8207,12 @@ async function cmdAdopt(argv) {
8149
8207
  }
8150
8208
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8151
8209
  const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
8152
- if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, ...(backfill ? { written: [{ key: backfill.key, value: backfill.value }] } : {}), local: lf }, null, 2)); return lf && !lf.ok ? 1 : 0; }
8210
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
8211
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8212
+ if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, ...(backfill ? { written: [{ key: backfill.key, value: backfill.value }] } : {}), local: lf, land }, null, 2)); return rc; }
8153
8213
  printAdoptReport(report, repoAbs, verify, lf);
8154
- return lf && !lf.ok ? 1 : 0;
8214
+ printAdoptLand(land);
8215
+ return rc;
8155
8216
  }
8156
8217
 
8157
8218
  // `trunk` is DETECTED, never asked — no answer flag can supply it, and asking a human "what is
@@ -8166,9 +8227,9 @@ async function cmdAdopt(argv) {
8166
8227
  return 1;
8167
8228
  }
8168
8229
 
8169
- const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'];
8230
+ // --autonomy counts as an answer flag (#481): it makes the run non-interactive, never half-prompted.
8231
+ const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack', 'autonomy'];
8170
8232
  const anyAnswerFlagGiven = answerFlagKeys.some((k) => opts[k] !== undefined);
8171
- const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
8172
8233
 
8173
8234
  // `stack` is REQUIRED by the audit but free-form, so it cannot always be detected — a
8174
8235
  // manifest-less repo (a docs-only repo; this handbook's own shape) has zero candidates.
@@ -8183,7 +8244,8 @@ async function cmdAdopt(argv) {
8183
8244
  let stackAnsweredInteractively = false;
8184
8245
  if (axesToAsk.length === 0) {
8185
8246
  answers = {};
8186
- } else if (anyAnswerFlagGiven) {
8247
+ } else if (anyAnswerFlagGiven || (opts.land && !isTTY)) {
8248
+ // #481: a bare --land with no terminal lands what is already on disk — it never asks.
8187
8249
  // Fully non-interactive: whatever flags were given get applied; anything still missing
8188
8250
  // just stays missing (reported in "remaining"), never prompted for — half a prompt is worse
8189
8251
  // than none. `stack` is the one exception: it is a required key, not an optional row, so an
@@ -8325,6 +8387,10 @@ async function cmdAdopt(argv) {
8325
8387
  comment: `${adopt.provenanceComment('exposure', m)}${reasonSuffix}`,
8326
8388
  });
8327
8389
  }
8390
+ if (autonomyWrite) {
8391
+ entries.push({ key: 'autonomy', value: opts.autonomy, comment: adopt.provenanceComment('autonomy',
8392
+ { mode: 'flag', flags: ['--autonomy'], date: nowDate, colabHuman, answeredBy: opts.answeredBy || null }) });
8393
+ }
8328
8394
  // Fallback: exposure ends this run still unanswered (declined interactively, or simply not
8329
8395
  // among the axes that got an answer this run) and no `tier` already exists — derive one from
8330
8396
  // (production, deploy), using the EFFECTIVE values (this run's tier answer, if any, else what
@@ -8380,9 +8446,12 @@ async function cmdAdopt(argv) {
8380
8446
  warn('nothing to write — every requested row was already answered, or nothing was supplied to answer it.');
8381
8447
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8382
8448
  const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
8383
- if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, written: [], local: lf }, null, 2)); return lf && !lf.ok ? 1 : 0; }
8449
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
8450
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8451
+ if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, written: [], local: lf, land }, null, 2)); return rc; }
8384
8452
  printAdoptReport(report, repoAbs, verify, lf);
8385
- return lf && !lf.ok ? 1 : 0;
8453
+ printAdoptLand(land);
8454
+ return rc;
8386
8455
  }
8387
8456
 
8388
8457
  const newText = adopt.renderDescriptor(rawTextBefore, entries);
@@ -8398,9 +8467,16 @@ async function cmdAdopt(argv) {
8398
8467
  const shell = local || rawTextBefore !== null ? null : adoptWriteShell(repoAbs, after);
8399
8468
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8400
8469
  const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
8470
+ // #481: --land commits exactly what THIS run wrote — the descriptor, plus the thin shell when
8471
+ // it was written now — never anything else in the working tree.
8472
+ const landPaths = ['.github/project.yml'];
8473
+ if (shell && shell.claude === 'written') landPaths.push(CLAUDE_FILE);
8474
+ if (shell && shell.agents === 'written') landPaths.push('AGENTS.md');
8475
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, landPaths, opts.answeredBy) : undefined;
8476
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8401
8477
  if (opts.json) {
8402
- print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf }, null, 2));
8403
- return lf && !lf.ok ? 1 : 0;
8478
+ print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf, land }, null, 2));
8479
+ return rc;
8404
8480
  }
8405
8481
  for (const e of entries) print(`✓ wrote ${e.key}: ${fmtVal(e.value)}`);
8406
8482
  if (shell) {
@@ -8411,7 +8487,63 @@ async function cmdAdopt(argv) {
8411
8487
  }
8412
8488
  print('');
8413
8489
  printAdoptReport(after, repoAbs, verify, lf);
8414
- return lf && !lf.ok ? 1 : 0;
8490
+ printAdoptLand(land);
8491
+ return rc;
8492
+ }
8493
+
8494
+ /**
8495
+ * #481 — `--land` preflight: is origin's trunk ahead of this checkout? Landing on a stale trunk
8496
+ * would either fail the push or need a merge, and adopt does neither on a human's behalf. Returns a
8497
+ * refusal message, or null. No origin remote, or no trunk there yet (a first push), is not behind.
8498
+ */
8499
+ function adoptLandBehind(repoAbs, trunk) {
8500
+ if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) return null;
8501
+ const f = git.git(['fetch', 'origin', trunk], repoAbs);
8502
+ if (!f.ok) {
8503
+ const remoteHas = git.git(['ls-remote', '--exit-code', '--heads', 'origin', trunk], repoAbs);
8504
+ if (remoteHas.ok) return `--land could not fetch origin/${trunk} — refusing to land on a trunk it cannot see: ${f.stderr || f.stdout}`;
8505
+ return null; // origin has no trunk yet: the landing push creates it
8506
+ }
8507
+ const anc = git.git(['merge-base', '--is-ancestor', 'FETCH_HEAD', 'HEAD'], repoAbs);
8508
+ if (anc.ok) return null;
8509
+ return `--land refuses: origin/${trunk} has commits this checkout does not — pull ${trunk} first, then re-run`;
8510
+ }
8511
+
8512
+ /**
8513
+ * #481 — commit `paths` (only those) onto trunk and push it. Called only after landVerdict passed
8514
+ * (COLAB_HUMAN=1 + --answered-by, standing on trunk), so the pre-push guard's COLAB_HUMAN door is
8515
+ * the one this push walks through — the same env the human set. Nothing staged for these paths
8516
+ * (already committed) is not an error: it still pushes a trunk that is ahead of origin.
8517
+ */
8518
+ function adoptLand(repoAbs, trunk, paths, answeredBy) {
8519
+ const present = paths.filter((p) => fs.existsSync(path.join(repoAbs, p)));
8520
+ if (!present.length) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: 'no descriptor on disk to land' };
8521
+ const add = git.git(['add', '--', ...present], repoAbs);
8522
+ if (!add.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git add failed: ${add.stderr || add.stdout}` };
8523
+ const staged = git.git(['diff', '--cached', '--name-only', '--', ...present], repoAbs);
8524
+ const committed = staged.ok && staged.stdout ? staged.stdout.split('\n').filter(Boolean) : [];
8525
+ if (committed.length) {
8526
+ const c = git.git(['commit', '--only', '-m', adopt.landCommitMessage({ answeredBy, paths: committed }), '--', ...committed], repoAbs);
8527
+ if (!c.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git commit failed: ${c.stderr || c.stdout}` };
8528
+ }
8529
+ const head = git.git(['rev-parse', 'HEAD'], repoAbs);
8530
+ const sha = head.ok ? head.stdout : null;
8531
+ if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) {
8532
+ return { ok: true, trunk, committed, sha, pushed: false, note: 'no origin remote — committed locally; the first push of trunk carries it' };
8533
+ }
8534
+ const p = git.git(['push', 'origin', `HEAD:refs/heads/${trunk}`], repoAbs);
8535
+ if (!p.ok) return { ok: false, trunk, committed, sha, pushed: false, error: `committed ${shortSha(sha)} on ${trunk}, but the push failed: ${p.stderr || p.stdout}` };
8536
+ return { ok: true, trunk, committed, sha, pushed: true };
8537
+ }
8538
+
8539
+ function printAdoptLand(land) {
8540
+ if (!land) return;
8541
+ print('');
8542
+ if (!land.ok) { print(`✗ land: ${land.error}`); return; }
8543
+ const what = land.committed.length ? `committed ${land.committed.join(', ')} as ${shortSha(land.sha)}` : `nothing new to commit (trunk at ${shortSha(land.sha)})`;
8544
+ print(`✓ land: ${what} on ${land.trunk}${land.pushed ? ` — pushed to origin/${land.trunk}` : ''}`);
8545
+ if (land.note) print(` ${land.note}`);
8546
+ print(' The follow-up branch (CI, guards, docs) is judged by this descriptor — ship it through the normal lane.');
8415
8547
  }
8416
8548
 
8417
8549
  /**
@@ -847,6 +847,92 @@ function writesGateVerdict({ writes, effExposure, isTTY, colabHuman, answeredBy
847
847
  return { ok: true };
848
848
  }
849
849
 
850
+ const VALID_AUTONOMY = new Set(['manual', 'auto-trunk']);
851
+
852
+ /**
853
+ * #481 — `--autonomy` on `colab adopt`: the maintainer's grant recorded at adoption, so the
854
+ * descriptor trunk carries from its first commit already says whether an agent may complete
855
+ * Phase B. `auto-trunk` is the one value that EXPANDS permission (an unattended trunk merge
856
+ * through `colab ship`), so it carries the same human bar as `writes: direct`; `manual` is the
857
+ * default and never gated. Append-only like every other answer: a value already on record is
858
+ * either the same (no-op) or a hand edit, never overwritten here.
859
+ *
860
+ * Returns `{ ok, write }` — `write` false when the same value is already declared — or a refusal
861
+ * `{ ok:false, class, exitCode, message }`. Pure: cmdAdopt passes every fact in.
862
+ */
863
+ function autonomyGateVerdict({ autonomy, current, ceremony, isTTY, colabHuman, answeredBy }) {
864
+ if (!VALID_AUTONOMY.has(autonomy)) {
865
+ throw new UserError(`--autonomy must be one of: ${[...VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(autonomy)})`);
866
+ }
867
+ if (current !== undefined && current !== null) {
868
+ if (String(current) === autonomy) return { ok: true, write: false };
869
+ return {
870
+ ok: false,
871
+ class: GATE_CLASS.REPO_SHAPE,
872
+ exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
873
+ message: `project.yml already declares autonomy: ${current} — adopt is append-only and never `
874
+ + 'rewrites a declared key; change it by hand, as its own reviewed commit',
875
+ };
876
+ }
877
+ if (autonomy !== 'auto-trunk') return { ok: true, write: true };
878
+ if (ceremony === 'light') {
879
+ return {
880
+ ok: false,
881
+ class: GATE_CLASS.REPO_SHAPE,
882
+ exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
883
+ message: 'autonomy: auto-trunk is refused alongside ceremony: light — an unattended merge with '
884
+ + 'the ceremony skipped is the one combination the handbook forbids (CONVENTIONS.md §2)',
885
+ };
886
+ }
887
+ if (!(isTTY || (colabHuman && answeredBy))) {
888
+ return {
889
+ ok: false,
890
+ class: GATE_CLASS.HUMAN_GATED,
891
+ exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
892
+ message: 'declaring autonomy: auto-trunk requires a human: answer at an interactive terminal, or '
893
+ + 're-run with COLAB_HUMAN=1 and --answered-by "<name>" — it grants agents the trunk merge',
894
+ };
895
+ }
896
+ return { ok: true, write: true };
897
+ }
898
+
899
+ /**
900
+ * #481 — may `colab adopt --land` commit the descriptor straight to trunk? Landing writes trunk,
901
+ * so it is the human's act and never an agent's: COLAB_HUMAN=1 AND --answered-by, no TTY
902
+ * substitute (a TTY proves a terminal, not that this particular write was asked for). It runs only
903
+ * on a checkout standing ON trunk, never --local (a local descriptor is machine state, never
904
+ * committed). Pure.
905
+ */
906
+ function landVerdict({ local, colabHuman, answeredBy, trunk, currentBranch }) {
907
+ if (local) {
908
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
909
+ message: '--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)' };
910
+ }
911
+ if (!(colabHuman && answeredBy)) {
912
+ return { ok: false, class: GATE_CLASS.HUMAN_GATED, exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
913
+ message: '--land commits to trunk, which is a human act: re-run with COLAB_HUMAN=1 and --answered-by "<name>"' };
914
+ }
915
+ if (!trunk) {
916
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
917
+ message: '--land needs a trunk, and none could be determined' };
918
+ }
919
+ if (currentBranch !== trunk) {
920
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
921
+ message: `--land runs on the trunk checkout: this checkout is on ${currentBranch ? JSON.stringify(currentBranch) : 'no branch'}, trunk is ${JSON.stringify(trunk)} — `
922
+ + `run it from the checkout standing on ${trunk}` };
923
+ }
924
+ return { ok: true };
925
+ }
926
+
927
+ /** The commit message `--land` writes. Conventional, so it is visible in release notes. */
928
+ function landCommitMessage({ answeredBy, paths }) {
929
+ return 'chore: adopt the colab-handbook conventions — land the descriptor on trunk\n\n'
930
+ + `Committed by \`colab adopt --land\` (COLAB_HUMAN=1, --answered-by ${JSON.stringify(answeredBy)}): `
931
+ + 'the maintainer\'s adoption answers, on trunk from its first commit, so the branch that adds '
932
+ + 'CI is judged by them.\n\n'
933
+ + `Paths: ${paths.join(', ')}\n`;
934
+ }
935
+
850
936
  // ---------------------------------------------------------------------- provenance + the append-only write
851
937
 
852
938
  /** The comment placed beside a written key — never trusted as identity (see gateVerdict's
@@ -982,6 +1068,10 @@ module.exports = {
982
1068
  exposureShapeVerdict,
983
1069
  gateVerdict,
984
1070
  writesGateVerdict,
1071
+ VALID_AUTONOMY,
1072
+ autonomyGateVerdict,
1073
+ landVerdict,
1074
+ landCommitMessage,
985
1075
  provenanceComment,
986
1076
  renderDescriptor,
987
1077
  };
@@ -54,6 +54,34 @@ function branchIssueNumbers(branchName) {
54
54
  return m[1].split('-').map(Number).filter((n) => Number.isInteger(n) && n > 0);
55
55
  }
56
56
 
57
+ /**
58
+ * Ref-name prefixes owned by a dependency bot, never by a session (#485). Dependabot names its
59
+ * branches after the version it bumps to — `dependabot/github_actions/actions/github-script-9` —
60
+ * so the trailing run is a MAJOR VERSION, not an issue number, and reading it as one makes an
61
+ * unrelated issue look held. `code-sweep` §1.3 drops the same prefix with `grep -v '^dependabot/'`;
62
+ * keep the two in step.
63
+ */
64
+ const BOT_BRANCH_PREFIXES = ['dependabot/'];
65
+
66
+ /**
67
+ * Issue numbers a branch carries AS A CLAIM — `branchIssueNumbers`, minus every ref that can only
68
+ * be a false positive (#485): a dependency bot's branch (`BOT_BRANCH_PREFIXES`), `HEAD`, the
69
+ * declared trunk, and any declared `integration:` line. Those are long-lived lines or tool-owned
70
+ * refs whose trailing digits mean something else; a match against one would refuse a claim that
71
+ * nobody holds and teach the session to reach for `--force` — the one flag that also bypasses a
72
+ * real holder. Returns [] for an excluded ref, exactly like a name with no trailing run.
73
+ *
74
+ * `branchIssueNumbers` itself stays unfiltered on purpose: ship's harvest reads the session's OWN
75
+ * branch, which can never be one of these.
76
+ */
77
+ function claimIssueNumbers(branchName, { trunk = '', integration = [] } = {}) {
78
+ const b = String(branchName || '');
79
+ if (!b || b === 'HEAD' || (trunk && b === trunk)) return [];
80
+ if (BOT_BRANCH_PREFIXES.some((p) => b.startsWith(p))) return [];
81
+ if ((integration || []).includes(b)) return [];
82
+ return branchIssueNumbers(b);
83
+ }
84
+
57
85
  /**
58
86
  * A §4-conforming name → `{ login, machine, type, rest, slug, issues, prefixed }`, or `null` when the
59
87
  * name conforms to neither shape. `rest` is `<slug>-<N…>` (everything after the type); `slug` is
@@ -133,5 +161,5 @@ function worktreeName(branch) {
133
161
 
134
162
  module.exports = {
135
163
  TYPES, BRANCH_RE_SOURCE, BRANCH_RE,
136
- branchIssueNumbers, parse, format, machineLabel, sessionBranch, worktreeName,
164
+ branchIssueNumbers, claimIssueNumbers, BOT_BRANCH_PREFIXES, parse, format, machineLabel, sessionBranch, worktreeName,
137
165
  };