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

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.46"
31
31
  }
package/tools/colab CHANGED
@@ -7473,7 +7473,7 @@ const HELP_ADOPT = `colab adopt [--repo <path>] [--json] [--no-verify] [--axis a
7473
7473
  [--writes <free|direct|isolated>] [--channels <c1,c2,...>]
7474
7474
  [--production <url>|none] [--deploy <push-main|tag|manual|none>]
7475
7475
  [--stack "<text>"] [--answered-by <name>] [--reason "<text>"]
7476
- [--fork | --no-fork]
7476
+ [--fork | --no-fork] [--autonomy <manual|auto-trunk>] [--land]
7477
7477
 
7478
7478
  Detects what a repo already states in .github/project.yml, ASKS a human only what could not be
7479
7479
  detected (flags, or a forced multiple-choice menu at a TTY — every row is a numbered choice,
@@ -7504,7 +7504,32 @@ accepted and reads as free — no adopter's descriptor breaks, and none is re-as
7504
7504
  named, and a new CLAUDE.md gets no AGENTS.md stub (CONVENTIONS.md §9,
7505
7505
  "A fork of an upstream")
7506
7506
 
7507
- Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack) makes the
7507
+ THE AUTONOMY GRANT AND --land (#481) — so a new repo's first branch is not hand-merged:
7508
+
7509
+ --autonomy auto-trunk records the maintainer's grant (project.yml autonomy:) with the same
7510
+ provenance comment as every answer. It EXPANDS permission (an agent may
7511
+ then complete Phase B through \`colab ship\`), so it carries the writes:
7512
+ direct bar: interactive TTY, OR COLAB_HUMAN=1 AND --answered-by <name>
7513
+ (exit 3 otherwise). Refused with ceremony: light (exit 5). manual (the
7514
+ default) is never gated. Append-only: a different value already declared
7515
+ is refused (exit 5) — change it by hand.
7516
+ --land commits what THIS run wrote — the descriptor, plus the thin-shell
7517
+ CLAUDE.md/AGENTS.md when written now — straight to trunk as its own
7518
+ commit, then pushes origin/<trunk>. It is the human's adoption act, not
7519
+ an agent's: COLAB_HUMAN=1 AND --answered-by are required, no TTY
7520
+ substitute (exit 3). It runs only on the checkout standing ON trunk, never
7521
+ with --local, and refuses before writing anything when origin's trunk is
7522
+ ahead (pull first). Run without new answers, it lands a descriptor an
7523
+ earlier adopt left uncommitted. No origin remote: commits only.
7524
+
7525
+ The shape it exists for: \`colab ship\` judges a branch's autonomy by the descriptor trunk
7526
+ carries. Land it first, and the follow-up branch (CI workflow, guards, docs) ships through the
7527
+ normal lane under the grant — no human merge of the adoption branch.
7528
+
7529
+ COLAB_HUMAN=1 colab adopt --exposure self --stack node --autonomy auto-trunk \\
7530
+ --answered-by "<name>" --land
7531
+
7532
+ Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack/--autonomy) makes the
7508
7533
  whole run NON-INTERACTIVE — it never half-prompts. With no answer flags and no TTY, and something
7509
7534
  is still missing, this refuses in under a second, naming exactly which flags would answer it —
7510
7535
  never hangs waiting on stdin nobody is at.
@@ -7610,7 +7635,7 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
7610
7635
  block, topic, register, autopilot) and why.
7611
7636
 
7612
7637
  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
7638
+ \`colab register\`, and it never commits unless --land asks it to (#481). One exception (#417): on a repo with no descriptor before
7614
7639
  the run and no CLAUDE.md, plain adopt also writes the thin-shell CLAUDE.md (\`@AGENTS.md\` + the
7615
7640
  filled Conventions block) and an AGENTS.md stub if none exists; an existing CLAUDE.md is never
7616
7641
  touched, and --local never writes either. It ends with the machine-readable
@@ -8099,9 +8124,9 @@ async function cmdAdopt(argv) {
8099
8124
  '--repo': 'repo', '--axis': 'axis', '--room': 'room', '--exposure': 'exposure',
8100
8125
  '--writes': 'writes', '--channels': 'channels', '--production': 'production',
8101
8126
  '--deploy': 'deploy', '--stack': 'stack', '--answered-by': 'answeredBy', '--reason': 'reason',
8102
- '--trunk': 'trunk',
8127
+ '--trunk': 'trunk', '--autonomy': 'autonomy',
8103
8128
  },
8104
- flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '-h': 'help', '--help': 'help' },
8129
+ flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '--land': 'land', '-h': 'help', '--help': 'help' },
8105
8130
  });
8106
8131
  if (opts.help) return print(HELP_ADOPT);
8107
8132
  if (opts.fork && opts.noFork) throw new UserError('--fork and --no-fork contradict each other — pass one');
@@ -8109,6 +8134,10 @@ async function cmdAdopt(argv) {
8109
8134
  throw new UserError('--trunk only means something with --local — on an ordinary adoption trunk is DETECTED, never asked (CONVENTIONS.md §9)');
8110
8135
  }
8111
8136
  if (opts.noLabels && !opts.local) throw new UserError('--no-labels only means something with --local — plain adopt never touches labels');
8137
+ if (opts.land && opts.local) throw new UserError('--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)');
8138
+ if (opts.autonomy !== undefined && !adopt.VALID_AUTONOMY.has(opts.autonomy)) {
8139
+ throw new UserError(`--autonomy must be one of: ${[...adopt.VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(opts.autonomy)})`);
8140
+ }
8112
8141
 
8113
8142
  // --local (#393): the descriptor is machine state, not a committable source file — it lives in
8114
8143
  // the MAIN checkout (where every worktree's `colab` call reads project.yml from, via
@@ -8139,9 +8168,33 @@ async function cmdAdopt(argv) {
8139
8168
  const localAnswerFlag = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'].some((k) => opts[k] !== undefined);
8140
8169
  if (local && !localAnswerFlag && !requestedAxes.length && axisAuthority.axisOfRecord(cfg).source === 'exposure') axesToAsk = [];
8141
8170
 
8171
+ const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
8172
+ const colabHuman = process.env.COLAB_HUMAN === '1';
8173
+
8174
+ // #481: --land preflight — every refusal here happens BEFORE anything is written, like the gates.
8175
+ let landTrunk = null;
8176
+ if (opts.land) {
8177
+ landTrunk = cfg.trunk ? String(cfg.trunk) : (extra.trunk || null);
8178
+ const cur = git.git(['symbolic-ref', '--short', 'HEAD'], repoAbs);
8179
+ const lv = adopt.landVerdict({ local: !!opts.local, colabHuman, answeredBy: opts.answeredBy || null,
8180
+ trunk: landTrunk, currentBranch: cur.ok && cur.stdout ? cur.stdout : null });
8181
+ if (!lv.ok) { warn(lv.message); return lv.exitCode; }
8182
+ const behind = adoptLandBehind(repoAbs, landTrunk);
8183
+ if (behind) { warn(behind); return 1; }
8184
+ }
8185
+
8186
+ // #481: --autonomy — the maintainer's grant, gated like writes: direct (it expands permission).
8187
+ let autonomyWrite = false;
8188
+ if (opts.autonomy !== undefined) {
8189
+ const av = adopt.autonomyGateVerdict({ autonomy: opts.autonomy, current: cfg.autonomy, ceremony: cfg.ceremony,
8190
+ isTTY, colabHuman, answeredBy: opts.answeredBy || null });
8191
+ if (!av.ok) { warn(av.message); return av.exitCode; }
8192
+ autonomyWrite = av.write;
8193
+ }
8194
+
8142
8195
  // Already complete (and nothing forced): report, write nothing, exit 0 — except the one key a
8143
8196
  // 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) {
8197
+ if (axesToAsk.length === 0 && opts.stack === undefined && !autonomyWrite) {
8145
8198
  const backfill = localOwnerEntry(local, cfg, today());
8146
8199
  if (backfill) {
8147
8200
  fs.writeFileSync(descriptorFile, adopt.renderDescriptor(rawTextBefore, [backfill]));
@@ -8149,9 +8202,12 @@ async function cmdAdopt(argv) {
8149
8202
  }
8150
8203
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8151
8204
  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; }
8205
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
8206
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8207
+ 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
8208
  printAdoptReport(report, repoAbs, verify, lf);
8154
- return lf && !lf.ok ? 1 : 0;
8209
+ printAdoptLand(land);
8210
+ return rc;
8155
8211
  }
8156
8212
 
8157
8213
  // `trunk` is DETECTED, never asked — no answer flag can supply it, and asking a human "what is
@@ -8166,9 +8222,9 @@ async function cmdAdopt(argv) {
8166
8222
  return 1;
8167
8223
  }
8168
8224
 
8169
- const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'];
8225
+ // --autonomy counts as an answer flag (#481): it makes the run non-interactive, never half-prompted.
8226
+ const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack', 'autonomy'];
8170
8227
  const anyAnswerFlagGiven = answerFlagKeys.some((k) => opts[k] !== undefined);
8171
- const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
8172
8228
 
8173
8229
  // `stack` is REQUIRED by the audit but free-form, so it cannot always be detected — a
8174
8230
  // manifest-less repo (a docs-only repo; this handbook's own shape) has zero candidates.
@@ -8183,7 +8239,8 @@ async function cmdAdopt(argv) {
8183
8239
  let stackAnsweredInteractively = false;
8184
8240
  if (axesToAsk.length === 0) {
8185
8241
  answers = {};
8186
- } else if (anyAnswerFlagGiven) {
8242
+ } else if (anyAnswerFlagGiven || (opts.land && !isTTY)) {
8243
+ // #481: a bare --land with no terminal lands what is already on disk — it never asks.
8187
8244
  // Fully non-interactive: whatever flags were given get applied; anything still missing
8188
8245
  // just stays missing (reported in "remaining"), never prompted for — half a prompt is worse
8189
8246
  // than none. `stack` is the one exception: it is a required key, not an optional row, so an
@@ -8325,6 +8382,10 @@ async function cmdAdopt(argv) {
8325
8382
  comment: `${adopt.provenanceComment('exposure', m)}${reasonSuffix}`,
8326
8383
  });
8327
8384
  }
8385
+ if (autonomyWrite) {
8386
+ entries.push({ key: 'autonomy', value: opts.autonomy, comment: adopt.provenanceComment('autonomy',
8387
+ { mode: 'flag', flags: ['--autonomy'], date: nowDate, colabHuman, answeredBy: opts.answeredBy || null }) });
8388
+ }
8328
8389
  // Fallback: exposure ends this run still unanswered (declined interactively, or simply not
8329
8390
  // among the axes that got an answer this run) and no `tier` already exists — derive one from
8330
8391
  // (production, deploy), using the EFFECTIVE values (this run's tier answer, if any, else what
@@ -8380,9 +8441,12 @@ async function cmdAdopt(argv) {
8380
8441
  warn('nothing to write — every requested row was already answered, or nothing was supplied to answer it.');
8381
8442
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8382
8443
  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; }
8444
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
8445
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8446
+ if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, written: [], local: lf, land }, null, 2)); return rc; }
8384
8447
  printAdoptReport(report, repoAbs, verify, lf);
8385
- return lf && !lf.ok ? 1 : 0;
8448
+ printAdoptLand(land);
8449
+ return rc;
8386
8450
  }
8387
8451
 
8388
8452
  const newText = adopt.renderDescriptor(rawTextBefore, entries);
@@ -8398,9 +8462,16 @@ async function cmdAdopt(argv) {
8398
8462
  const shell = local || rawTextBefore !== null ? null : adoptWriteShell(repoAbs, after);
8399
8463
  const verify = opts.noVerify ? null : adoptVerify(repoAbs);
8400
8464
  const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
8465
+ // #481: --land commits exactly what THIS run wrote — the descriptor, plus the thin shell when
8466
+ // it was written now — never anything else in the working tree.
8467
+ const landPaths = ['.github/project.yml'];
8468
+ if (shell && shell.claude === 'written') landPaths.push(CLAUDE_FILE);
8469
+ if (shell && shell.agents === 'written') landPaths.push('AGENTS.md');
8470
+ const land = opts.land ? adoptLand(repoAbs, landTrunk, landPaths, opts.answeredBy) : undefined;
8471
+ const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
8401
8472
  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;
8473
+ print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf, land }, null, 2));
8474
+ return rc;
8404
8475
  }
8405
8476
  for (const e of entries) print(`✓ wrote ${e.key}: ${fmtVal(e.value)}`);
8406
8477
  if (shell) {
@@ -8411,7 +8482,63 @@ async function cmdAdopt(argv) {
8411
8482
  }
8412
8483
  print('');
8413
8484
  printAdoptReport(after, repoAbs, verify, lf);
8414
- return lf && !lf.ok ? 1 : 0;
8485
+ printAdoptLand(land);
8486
+ return rc;
8487
+ }
8488
+
8489
+ /**
8490
+ * #481 — `--land` preflight: is origin's trunk ahead of this checkout? Landing on a stale trunk
8491
+ * would either fail the push or need a merge, and adopt does neither on a human's behalf. Returns a
8492
+ * refusal message, or null. No origin remote, or no trunk there yet (a first push), is not behind.
8493
+ */
8494
+ function adoptLandBehind(repoAbs, trunk) {
8495
+ if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) return null;
8496
+ const f = git.git(['fetch', 'origin', trunk], repoAbs);
8497
+ if (!f.ok) {
8498
+ const remoteHas = git.git(['ls-remote', '--exit-code', '--heads', 'origin', trunk], repoAbs);
8499
+ if (remoteHas.ok) return `--land could not fetch origin/${trunk} — refusing to land on a trunk it cannot see: ${f.stderr || f.stdout}`;
8500
+ return null; // origin has no trunk yet: the landing push creates it
8501
+ }
8502
+ const anc = git.git(['merge-base', '--is-ancestor', 'FETCH_HEAD', 'HEAD'], repoAbs);
8503
+ if (anc.ok) return null;
8504
+ return `--land refuses: origin/${trunk} has commits this checkout does not — pull ${trunk} first, then re-run`;
8505
+ }
8506
+
8507
+ /**
8508
+ * #481 — commit `paths` (only those) onto trunk and push it. Called only after landVerdict passed
8509
+ * (COLAB_HUMAN=1 + --answered-by, standing on trunk), so the pre-push guard's COLAB_HUMAN door is
8510
+ * the one this push walks through — the same env the human set. Nothing staged for these paths
8511
+ * (already committed) is not an error: it still pushes a trunk that is ahead of origin.
8512
+ */
8513
+ function adoptLand(repoAbs, trunk, paths, answeredBy) {
8514
+ const present = paths.filter((p) => fs.existsSync(path.join(repoAbs, p)));
8515
+ if (!present.length) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: 'no descriptor on disk to land' };
8516
+ const add = git.git(['add', '--', ...present], repoAbs);
8517
+ if (!add.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git add failed: ${add.stderr || add.stdout}` };
8518
+ const staged = git.git(['diff', '--cached', '--name-only', '--', ...present], repoAbs);
8519
+ const committed = staged.ok && staged.stdout ? staged.stdout.split('\n').filter(Boolean) : [];
8520
+ if (committed.length) {
8521
+ const c = git.git(['commit', '--only', '-m', adopt.landCommitMessage({ answeredBy, paths: committed }), '--', ...committed], repoAbs);
8522
+ if (!c.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git commit failed: ${c.stderr || c.stdout}` };
8523
+ }
8524
+ const head = git.git(['rev-parse', 'HEAD'], repoAbs);
8525
+ const sha = head.ok ? head.stdout : null;
8526
+ if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) {
8527
+ return { ok: true, trunk, committed, sha, pushed: false, note: 'no origin remote — committed locally; the first push of trunk carries it' };
8528
+ }
8529
+ const p = git.git(['push', 'origin', `HEAD:refs/heads/${trunk}`], repoAbs);
8530
+ 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}` };
8531
+ return { ok: true, trunk, committed, sha, pushed: true };
8532
+ }
8533
+
8534
+ function printAdoptLand(land) {
8535
+ if (!land) return;
8536
+ print('');
8537
+ if (!land.ok) { print(`✗ land: ${land.error}`); return; }
8538
+ const what = land.committed.length ? `committed ${land.committed.join(', ')} as ${shortSha(land.sha)}` : `nothing new to commit (trunk at ${shortSha(land.sha)})`;
8539
+ print(`✓ land: ${what} on ${land.trunk}${land.pushed ? ` — pushed to origin/${land.trunk}` : ''}`);
8540
+ if (land.note) print(` ${land.note}`);
8541
+ print(' The follow-up branch (CI, guards, docs) is judged by this descriptor — ship it through the normal lane.');
8415
8542
  }
8416
8543
 
8417
8544
  /**
@@ -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
  };