@futurelastic/colab-handbook 1.12.0-rc.69 → 1.12.0-rc.70

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/README.md CHANGED
@@ -133,18 +133,24 @@ it end to end.
133
133
 
134
134
  ## The five questions
135
135
 
136
- Adopting means answering these about your repo, once, into
137
- `.github/project.yml`. `colab adopt` asks them as numbered menus:
138
-
139
- | # | Question | Writes |
140
- |---|---|---|
141
- | 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` |
142
- | 2 | Who else works here — just you, a team, or the public? | `room` |
143
- | 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` |
144
- | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` |
145
- | 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` |
146
-
147
- Nothing is asked that the repo already states — its default branch (`trunk`),
136
+ Adopting means answering these about your repo into `.github/project.yml`.
137
+ `colab adopt` asks only the two that change a gate (1 and 3), as numbered menus;
138
+ the other three are optional and can be answered any time later:
139
+
140
+ | # | Question | Writes | At adoption |
141
+ |---|---|---|---|
142
+ | 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` | asked |
143
+ | 2 | Who else works here — just you, a team, or the public? | `room` | optional — `colab adopt --axis room` |
144
+ | 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` | asked — a human's answer |
145
+ | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` | optional — `colab adopt --axis writes` |
146
+ | 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` | optional — `colab adopt --axis channels` |
147
+
148
+ **Answering question 3 is a human's act** when the answer is "nothing" or "only
149
+ people already in the room". An agent can drive everything else; when it gets
150
+ there, `colab adopt` prints, as its first line, the one command the human runs.
151
+
152
+ Nothing is asked that the repo already states — its default branch (`trunk`,
153
+ kept as it is: a `master` default is fine, nothing needs renaming),
148
154
  its toolchain, its ports are detected. Gate count, release ritual and whether a
149
155
  branch is mandatory are derived from the answers. What each answer resolves to,
150
156
  and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
@@ -163,7 +169,7 @@ edits.
163
169
  By hand, the same steps (full checklist:
164
170
  [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
165
171
 
166
- 1. `colab adopt` — answers the five questions and writes
172
+ 1. `colab adopt` — answers the two gating questions and writes
167
173
  `.github/project.yml`. It stops there and prints the remaining steps.
168
174
  2. `colab labels --ensure` — the convention labels do not exist by default. A
169
175
  check whose label was never created can never fire.
package/README.vi.md CHANGED
@@ -132,18 +132,24 @@ còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra n
132
132
 
133
133
  ## Năm câu hỏi
134
134
 
135
- Adopt nghĩa là trả lời mấy câu này về repo của bạn, một lần, vào
136
- `.github/project.yml`. `colab adopt` hỏi chúng dưới dạng menu đánh số:
137
-
138
- | # | Câu hỏi | Ghi vào |
139
- |---|---|---|
140
- | 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` |
141
- | 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` |
142
- | 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` |
143
- | 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` |
144
- | 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` |
145
-
146
- Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`), toolchain,
135
+ Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
136
+ `colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
137
+ số; ba câu còn lại là tuỳ chọn, trả lời lúc nào sau này cũng được:
138
+
139
+ | # | Câu hỏi | Ghi vào | Lúc adopt |
140
+ |---|---|---|---|
141
+ | 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` | có hỏi |
142
+ | 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` | tuỳ chọn — `colab adopt --axis room` |
143
+ | 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` | có hỏi — người thật trả lời |
144
+ | 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` | tuỳ chọn — `colab adopt --axis writes` |
145
+ | 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` | tuỳ chọn — `colab adopt --axis channels` |
146
+
147
+ **Trả lời câu 3 là việc của người thật** khi câu trả lời là "không gì cả" hoặc
148
+ "chỉ những người đang có mặt". Agent làm được mọi phần còn lại; tới bước đó,
149
+ `colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
150
+
151
+ Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`, giữ nguyên
152
+ như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
147
153
  port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
148
154
  nhánh hay không đều suy ra từ câu trả lời. Mỗi câu trả lời quy về đâu, và vì
149
155
  sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
@@ -161,7 +167,7 @@ nhất mà không làm mất phần bạn đã sửa.
161
167
  Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
162
168
  [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
163
169
 
164
- 1. `colab adopt` — trả lời năm câu hỏi và ghi `.github/project.yml`. Nó dừng ở
170
+ 1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
165
171
  đó và in ra các bước còn lại.
166
172
  2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
167
173
  của nó chưa từng được tạo thì không bao giờ chạy được.
package/audit/audit.mjs CHANGED
@@ -82,7 +82,7 @@ const {
82
82
  // encode the VALIDATOR half (report every violation) separately from `colab adopt`'s CONSTRUCTOR
83
83
  // half (does declaring this exposure value stay possible at all?). Same install.sh-freezes-
84
84
  // tools/lib/ reasoning as the other requires on this page.
85
- const { evaluateExposure } = require("../tools/lib/exposure-shape.js");
85
+ const { evaluateExposure, singleTrunkViolation } = require("../tools/lib/exposure-shape.js");
86
86
  // #208's `writes` split precedence ladder — same shared-module reasoning as axisAuthority
87
87
  // above, reused for a second axis rather than a bespoke second mechanism.
88
88
  const writesAuthority = require("../tools/lib/writes-authority.js");
@@ -1100,6 +1100,10 @@ function renderDuration(age) {
1100
1100
 
1101
1101
  function auditRepo(target, ctx) {
1102
1102
  const src = makeSource(target);
1103
+ // #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
1104
+ // trunk-exists check below — one read, so a remote target costs one API listing, not three.
1105
+ let branchesMemo;
1106
+ const branchList = () => (branchesMemo === undefined ? (branchesMemo = src.branches()) : branchesMemo);
1103
1107
  const findings = []; // { level: 'fail'|'warn', text }
1104
1108
  // `self` = this target IS the handbook, not one of its consumers. Surfaced in the
1105
1109
  // report (and in --json) so the row reads as source-of-truth rather than clean-by-luck:
@@ -1608,7 +1612,12 @@ function auditRepo(target, ctx) {
1608
1612
  ? `tier A with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(trunk)}`
1609
1613
  : `tier A requires trunk "dev", found ${JSON.stringify(trunk)} — only a tag-gated A (deploy: tag) may run a single trunk "main"`);
1610
1614
  }
1611
- if (tier === "B" && trunk !== "main") fail(`tier B requires trunk "main", found ${JSON.stringify(trunk)}`);
1615
+ // #522: B is the single-trunk shape — one long-lived branch, any spelling. `master` (or
1616
+ // whatever an existing repo's default is) conforms; a "main" beside a non-main trunk does not.
1617
+ if (tier === "B") {
1618
+ const single = singleTrunkViolation(trunk, branchList());
1619
+ if (single) fail(`tier B requires a single trunk — ${single}`);
1620
+ }
1612
1621
  // C uses A's two-branch split: main = what is live, trunk = where sessions land. #205:
1613
1622
  // this validates the SPLIT, not the spelling — trunk is a declared setting (default
1614
1623
  // "dev", proposed by colab adopt and the templates), never required to literally be
@@ -1817,7 +1826,7 @@ function auditRepo(target, ctx) {
1817
1826
  // construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
1818
1827
  // A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
1819
1828
  // "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
1820
- const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers] };
1829
+ const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers], branches: branchList() };
1821
1830
  for (const entry of evaluateExposure(exp, shapeCtx)) {
1822
1831
  if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
1823
1832
  else fail(entry.message);
@@ -1825,7 +1834,7 @@ function auditRepo(target, ctx) {
1825
1834
  }
1826
1835
 
1827
1836
  // ---- declared trunk actually exists -------------------------------------
1828
- const branches = src.branches();
1837
+ const branches = branchList();
1829
1838
  if (trunk && branches === null) {
1830
1839
  warn(`cannot list branches (not a git checkout, or gh unavailable) — trunk "${trunk}" unverified`);
1831
1840
  } else if (trunk && branches && !branches.includes(trunk)) {
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.69"
35
+ "version": "1.12.0-rc.70"
36
36
  }
package/tools/colab CHANGED
@@ -7718,6 +7718,18 @@ answered by its number OR its literal value), DERIVES the rest, and WRITES the d
7718
7718
  act — append-only, never touching a byte already there. A complete descriptor just reports
7719
7719
  (write nothing, exit 0); re-answer one row on purpose with --axis.
7720
7720
 
7721
+ ONLY THE GATING ROWS ARE ASKED (#533): deploy/production and exposure. room, writes and channels
7722
+ are optional and legal absent — never prompted for; the report names them in one line with the
7723
+ \`--axis\` command that answers each later, and their own flag still answers one in the same run.
7724
+ After deploy: none, production is not asked again (null follows; --deploy none alone implies it).
7725
+
7726
+ A SINGLE TRUNK, ANY SPELLING (#522): exposure none (and released with production null, and the
7727
+ legacy tier B) need ONE long-lived branch, not one named "main" — an existing master default
7728
+ adopts as-is. A "main" beside a non-main trunk is the two-branch shape and is refused (exit 5).
7729
+ At a terminal the exposure answer is checked against that shape when given, and re-asked with
7730
+ the reason. When a human must finish (the gate below), the FIRST line printed is the one
7731
+ command to run, every answer this run had already filled in.
7732
+
7721
7733
  --writes accepts free (coexistence, the default), direct (an attended human may commit straight
7722
7734
  to trunk; DECLARED today, its runtime is DEFERRED — see CONVENTIONS.md §2, "writes: direct —
7723
7735
  declared today, runtime deferred"), or isolated (vetoes trunk-direct outright, human or not).
@@ -7914,7 +7926,26 @@ function adoptGitExtras(repoAbs, opts = {}) {
7914
7926
  // #483: the fork's own owner, from origin's URL — what an inherited CODEOWNERS team is compared to.
7915
7927
  const originUrl = git.git(['remote', 'get-url', 'origin'], repoAbs);
7916
7928
  const ownOrg = originUrl.ok ? codeowners.remoteOwner(originUrl.stdout) : null;
7917
- return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg };
7929
+ return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg, branches: adoptBranchList(repoAbs) };
7930
+ }
7931
+
7932
+ /** #522: every branch name visible here — refs/heads ∪ refs/remotes/<any>/<name> — the same union
7933
+ * audit/audit.mjs's `branches()` reads, so the single-trunk rule (tools/lib/exposure-shape.js
7934
+ * `singleTrunkViolation`) answers identically on both sides: adopt never writes what the audit
7935
+ * then fails. null when git cannot list refs (the rule then fails closed to trunk "main"). */
7936
+ function adoptBranchList(repoAbs) {
7937
+ const r = git.git(['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes'], repoAbs);
7938
+ if (!r.ok) return null;
7939
+ const names = new Set();
7940
+ for (const ref of r.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
7941
+ if (ref.startsWith('refs/heads/')) names.add(ref.slice('refs/heads/'.length));
7942
+ else if (ref.startsWith('refs/remotes/')) {
7943
+ const rest = ref.slice('refs/remotes/'.length);
7944
+ const name = rest.slice(rest.indexOf('/') + 1);
7945
+ if (rest.includes('/') && name && name !== 'HEAD') names.add(name);
7946
+ }
7947
+ }
7948
+ return [...names];
7918
7949
  }
7919
7950
 
7920
7951
  /**
@@ -8187,6 +8218,8 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
8187
8218
  print(`detected trunk: ${t.detected || '(unknown)'}${trunkSourceNote}${t.declared !== null ? ` (declared: ${t.declared}${t.agree === false ? ' ⚠ disagrees with detected' : ''})` : ''}`);
8188
8219
  print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
8189
8220
  print(`declared ports: ${fmtVal(report.detected.ports)}`);
8221
+ const optLine = adopt.optionalRowsLine(report.optionalUnanswered); // #533
8222
+ if (optLine) print(optLine);
8190
8223
  if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
8191
8224
  if (report.inheritedCodeowners) {
8192
8225
  const ic = report.inheritedCodeowners;
@@ -8262,6 +8295,8 @@ function adoptAnswersFromFlags(opts, cfg, axesToAsk, forcedAxes) {
8262
8295
  if (!adopt.VALID_DEPLOY.has(opts.deploy)) throw new UserError(`--deploy must be one of: ${[...adopt.VALID_DEPLOY].join(', ')}`);
8263
8296
  values.deploy = opts.deploy;
8264
8297
  flags.push('--deploy');
8298
+ // #533: deploy: none already says nothing is live — production: null follows, never re-asked.
8299
+ if (opts.deploy === 'none' && opts.production === undefined && eligible('production', 'tier')) values.production = null;
8265
8300
  }
8266
8301
  if (flags.length) answers.tier = { values, mode: 'flag', flags };
8267
8302
  }
@@ -8325,7 +8360,7 @@ async function askMenu(rl, axis, promptFn) {
8325
8360
  * URL itself asked only on "yes" — this keeps every axis forced-choice-shaped without pretending
8326
8361
  * a URL belongs to an enum.
8327
8362
  */
8328
- async function adoptAskInteractive(rl, axesToAsk, cfg) {
8363
+ async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
8329
8364
  const answers = {};
8330
8365
  for (const axis of axesToAsk) {
8331
8366
  const q = adopt.QUESTIONS.find((x) => x.axis === axis);
@@ -8336,13 +8371,16 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8336
8371
  process.stdout.write(`${adopt.renderMenu('tier')}\n`);
8337
8372
  return rlAsk(rl, ' deploy: ');
8338
8373
  });
8339
- process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
8340
- const existsRaw = (await rlAsk(rl, ' production: ')).trim();
8341
8374
  let prod = null;
8342
- if (existsRaw === '2' || existsRaw === 'yes') {
8343
- prod = (await rlAsk(rl, ' URL: ')).trim() || null;
8344
- } else if (existsRaw !== '1' && existsRaw !== 'no') {
8345
- throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
8375
+ // #533: deploy: none already answered "nothing is live" — asking production again is noise.
8376
+ if (depChoice.value !== 'none') {
8377
+ process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
8378
+ const existsRaw = (await rlAsk(rl, ' production: ')).trim();
8379
+ if (existsRaw === '2' || existsRaw === 'yes') {
8380
+ prod = (await rlAsk(rl, ' URL: ')).trim() || null;
8381
+ } else if (existsRaw !== '1' && existsRaw !== 'no') {
8382
+ throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
8383
+ }
8346
8384
  }
8347
8385
  answers.tier = { values: { production: prod, deploy: depChoice.value }, mode: 'interactive' };
8348
8386
  } else if (axis === 'channels') {
@@ -8352,12 +8390,22 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8352
8390
  });
8353
8391
  answers.channels = { values: { channels: resolved.value }, mode: 'interactive' };
8354
8392
  } else if (axis === 'exposure') {
8355
- const resolved = await askMenu(rl, 'exposure', () => {
8356
- process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
8357
- return rlAsk(rl, ' choice: ');
8358
- });
8359
- if (resolved.skip) continue; // decline — the fallback tier derivation picks this up
8360
- answers.exposure = { values: { exposure: resolved.value }, mode: 'interactive' };
8393
+ // #522: the repo-shape check runs HERE, at answer time — a refusal re-asks with its reason,
8394
+ // instead of surfacing after every other question with nothing written.
8395
+ let chosen = null;
8396
+ for (let attempt = 0; attempt < 2 && !chosen; attempt++) {
8397
+ const resolved = await askMenu(rl, 'exposure', () => {
8398
+ process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
8399
+ return rlAsk(rl, ' choice: ');
8400
+ });
8401
+ if (resolved.skip) { chosen = resolved; break; }
8402
+ const problem = checkExposure ? checkExposure(resolved.value, answers) : null;
8403
+ if (!problem) { chosen = resolved; break; }
8404
+ process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
8405
+ }
8406
+ if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
8407
+ if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
8408
+ answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
8361
8409
  } else {
8362
8410
  // room, writes — plain single-choice menus, no skip.
8363
8411
  const resolved = await askMenu(rl, axis, () => {
@@ -8370,11 +8418,41 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8370
8418
  return answers;
8371
8419
  }
8372
8420
 
8421
+ /** #522: this run's answers as the ordered flag list `adopt.humanAdoptCommand` prints — what the
8422
+ * human pastes to finish the same adoption with the gate satisfied. */
8423
+ function adoptReplayFlags(opts, answers) {
8424
+ const flags = [];
8425
+ if (opts.repo !== undefined) flags.push(['--repo', opts.repo]);
8426
+ const t = answers.tier && answers.tier.values;
8427
+ if (t && 'production' in t) flags.push(['--production', t.production === null ? 'none' : t.production]);
8428
+ if (t && 'deploy' in t) flags.push(['--deploy', t.deploy]);
8429
+ if (answers.exposure) flags.push(['--exposure', answers.exposure.values.exposure]);
8430
+ if (answers.room) flags.push(['--room', answers.room.values.room]);
8431
+ if (answers.writes) flags.push(['--writes', answers.writes.values.writes]);
8432
+ if (answers.channels) flags.push(['--channels', answers.channels.values.channels.join(',')]);
8433
+ if (opts.stack !== undefined) flags.push(['--stack', opts.stack]);
8434
+ if (opts.autonomy !== undefined) flags.push(['--autonomy', opts.autonomy]);
8435
+ if (opts.reason !== undefined) flags.push(['--reason', opts.reason]);
8436
+ if (opts.answeredBy) flags.push(['--answered-by', opts.answeredBy]);
8437
+ if (opts.land) flags.push(['--land', true]);
8438
+ return flags;
8439
+ }
8440
+
8441
+ /** #522: the same command shape for a run that had no answers at all — placeholders per asked row. */
8442
+ function adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable) {
8443
+ const flags = [];
8444
+ if (axesToAsk.includes('tier')) flags.push(['--production', '<url>|none'], ['--deploy', '<none|tag|manual|push-main>']);
8445
+ if (axesToAsk.includes('exposure')) flags.push(['--exposure', '<none|self|live|released>']);
8446
+ for (const a of ['room', 'writes', 'channels']) if (axesToAsk.includes(a)) flags.push([`--${a}`, `<${a}>`]);
8447
+ if (stackUnresolvable) flags.push(['--stack', '<text>']);
8448
+ return flags;
8449
+ }
8450
+
8373
8451
  /** The `EXPOSURE_SHAPE`/falsifier context, built from EFFECTIVE production/deploy — accounting
8374
8452
  * for a `tier`-axis answer resolved in THIS SAME run, not only what was already on record, so
8375
8453
  * declaring production+deploy and exposure together in one invocation validates against each
8376
8454
  * other rather than the pre-write snapshot. */
8377
- function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
8455
+ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io, branches) {
8378
8456
  const effProduction = tierAnswer ? tierAnswer.values.production : (Object.prototype.hasOwnProperty.call(cfg, 'production') ? cfg.production : null);
8379
8457
  const effDeploy = tierAnswer ? tierAnswer.values.deploy : (Object.prototype.hasOwnProperty.call(cfg, 'deploy') ? cfg.deploy : null);
8380
8458
  const evidence = consumerEvidence.consumerEvidence(io, workflows);
@@ -8382,7 +8460,7 @@ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
8382
8460
  const hasProduction = effProduction !== null && effProduction !== undefined && effProduction !== '';
8383
8461
  const runbook = Object.prototype.hasOwnProperty.call(cfg, 'runbook') ? cfg.runbook : null;
8384
8462
  const hasRunbook = !!(runbook && io.readFile(String(runbook).trim().replace(/^\.\//, '')) !== null);
8385
- return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy };
8463
+ return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy, branches: branches === undefined ? null : branches };
8386
8464
  }
8387
8465
 
8388
8466
  async function cmdAdopt(argv) {
@@ -8428,7 +8506,12 @@ async function cmdAdopt(argv) {
8428
8506
  if (!adopt.ROW_NAMES.includes(a)) throw new UserError(`Unknown --axis "${a}" — expected one of: ${adopt.ROW_NAMES.join(', ')}`);
8429
8507
  }
8430
8508
  const forcedAxes = new Set(requestedAxes);
8431
- let axesToAsk = adopt.ROW_NAMES.filter((a) => forcedAxes.has(a) || adopt.axisMissing(cfg, a));
8509
+ // #533: a fresh adoption asks only the rows that change a gate (production/deploy, exposure);
8510
+ // room/writes/channels are asked only when forced (--axis) or answered by their flag.
8511
+ const flagAxes = new Set();
8512
+ if (opts.production !== undefined || opts.deploy !== undefined) flagAxes.add('tier');
8513
+ for (const a of ['room', 'exposure', 'writes', 'channels']) if (opts[a] !== undefined) flagAxes.add(a);
8514
+ let axesToAsk = adopt.axesToAsk(cfg, forcedAxes, flagAxes);
8432
8515
  // --local re-run (#393): once exposure is on record, a bare `adopt --local` (no answer flags, no
8433
8516
  // --axis) is the idempotent re-apply — exclude lines, stub, labels, checkout — never a prompt for
8434
8517
  // the optional rows (room/writes/channels), which --local leaves to the operator by design.
@@ -8522,7 +8605,11 @@ async function cmdAdopt(argv) {
8522
8605
  } else if (isTTY) {
8523
8606
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
8524
8607
  try {
8525
- answers = await adoptAskInteractive(rl, axesToAsk, cfg);
8608
+ const shapeWorkflows = io.listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f));
8609
+ answers = await adoptAskInteractive(rl, axesToAsk, cfg, (exposure, sofar) => {
8610
+ const v = adopt.exposureShapeVerdict(exposure, adoptShapeCtx(cfg, sofar.tier, extra.trunk, shapeWorkflows, io, extra.branches));
8611
+ return v.ok ? null : v.reason;
8612
+ });
8526
8613
  if (needsStack && opts.stack === undefined) {
8527
8614
  process.stdout.write('\nNo manifest recognised (package.json/composer.json/pyproject.toml/'
8528
8615
  + '.python-version) — the audit requires stack: as a literal key.\n');
@@ -8537,6 +8624,12 @@ async function cmdAdopt(argv) {
8537
8624
  } else {
8538
8625
  const hints = axesToAsk.map(adoptAxisFlagHint).join(' ');
8539
8626
  const stackHint = stackUnresolvable ? ' --stack "<text>"' : '';
8627
+ // #522: the human step goes FIRST — answering exposure none/self is a human's act, so the one
8628
+ // command that finishes the adoption leads, and the explanation follows it.
8629
+ if (axesToAsk.includes('exposure')) {
8630
+ warn('a human finishes this adoption — run at an interactive terminal: colab adopt (or, non-interactively:)');
8631
+ warn(` ${adopt.humanAdoptCommand(adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable))}`);
8632
+ }
8540
8633
  warn(`${axesToAsk.length} unanswered §9 row(s) (${axesToAsk.join(', ')}) — no TTY and no answer flags, so there is no way to ask. Re-run with: ${hints}${stackHint}`);
8541
8634
  return 1;
8542
8635
  }
@@ -8561,7 +8654,7 @@ async function cmdAdopt(argv) {
8561
8654
  // written, per "nothing partially written on refusal".
8562
8655
  if (answers.exposure) {
8563
8656
  const proposedExposure = answers.exposure.values.exposure;
8564
- const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io);
8657
+ const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io, extra.branches);
8565
8658
  const evidence = consumerEvidence.consumerEvidence(io, workflows);
8566
8659
  const currentExposure = axisAuthority.axisOfRecord(cfg).exposure;
8567
8660
  const verdict = adopt.gateVerdict({
@@ -8575,6 +8668,10 @@ async function cmdAdopt(argv) {
8575
8668
  reason: opts.reason || null,
8576
8669
  });
8577
8670
  if (!verdict.ok) {
8671
+ if (verdict.class === adopt.GATE_CLASS.HUMAN_GATED) {
8672
+ // #522: lead with the one command a human runs, every answer this run had filled in.
8673
+ warn(`a human finishes this adoption — run: ${adopt.humanAdoptCommand(adoptReplayFlags(opts, answers))}`);
8674
+ }
8578
8675
  warn(verdict.message);
8579
8676
  return verdict.exitCode;
8580
8677
  }
@@ -37,6 +37,13 @@ const { UserError } = require('./util.js');
37
37
 
38
38
  const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
39
39
 
40
+ /** #533: the rows that change a gate — the only ones a fresh adoption ASKS. `tier` here is the
41
+ * production/deploy pair; `exposure` sets the gate count. The other three are optional in the
42
+ * schema and legal absent (room → trail verbosity, writes → `free` is the default, channels →
43
+ * descriptive), so adoption leaves them unanswered and names the `--axis` command instead. */
44
+ const GATING_ROWS = Object.freeze(['tier', 'exposure']);
45
+ const OPTIONAL_ROWS = Object.freeze(['room', 'writes', 'channels']);
46
+
40
47
  // ---------------------------------------------------------------------- descriptor read
41
48
 
42
49
  /** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
@@ -387,7 +394,7 @@ function remainingSteps(ctx = {}) {
387
394
  if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
388
395
  steps.push(
389
396
  { n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
390
- { n: 4, text: 'Add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4' },
397
+ { n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
391
398
  );
392
399
  if (ctx.fork) {
393
400
  steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
@@ -538,6 +545,7 @@ function detect(io, extra = {}) {
538
545
  inheritedCodeowners,
539
546
  migrations,
540
547
  remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
548
+ optionalUnanswered: optionalUnanswered(cfg), // #533
541
549
  };
542
550
  }
543
551
 
@@ -780,6 +788,52 @@ function axisMissing(cfg, axis) {
780
788
  }
781
789
  }
782
790
 
791
+ /**
792
+ * #533: which rows this run asks. A gating row is asked when it is still missing; an optional row
793
+ * (room/writes/channels) only when the caller forced it (`--axis`) or supplied its answer flag —
794
+ * a fresh adoption never prompts for it. `flagAxes` — the rows an answer flag was given for.
795
+ */
796
+ function axesToAsk(cfg, forcedAxes, flagAxes) {
797
+ const forced = forcedAxes instanceof Set ? forcedAxes : new Set(forcedAxes || []);
798
+ const flagged = flagAxes instanceof Set ? flagAxes : new Set(flagAxes || []);
799
+ return ROW_NAMES.filter((a) => forced.has(a)
800
+ || (axisMissing(cfg, a) && (GATING_ROWS.includes(a) || flagged.has(a))));
801
+ }
802
+
803
+ /** #533: the optional rows still unanswered after a run — reported in one line, never asked. */
804
+ function optionalUnanswered(cfg) {
805
+ return OPTIONAL_ROWS.filter((a) => axisMissing(cfg, a));
806
+ }
807
+
808
+ /** The one line naming them and the command that answers each later (#533). null when none. */
809
+ function optionalRowsLine(rows) {
810
+ if (!rows || !rows.length) return null;
811
+ return `not asked (optional, legal absent): ${rows.join(', ')} — answer later with \`colab adopt --axis ${rows.join(',')}\``;
812
+ }
813
+
814
+ /** Shell-quote one argument only when it needs it — the printed command must paste and run. */
815
+ function shellArg(v) {
816
+ const t = String(v);
817
+ return /^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `"${t.replace(/(["\\$`])/g, '\\$1')}"`;
818
+ }
819
+
820
+ /**
821
+ * #522: the ONE command a human runs to finish an adoption an agent could not — printed as the
822
+ * first line of a human-gated refusal, answers already filled in. `flags` is an ordered list of
823
+ * `[flag, value]` pairs (value undefined/null for a bare flag); `--answered-by` is appended as a
824
+ * placeholder when absent, because the human bar needs it alongside COLAB_HUMAN=1.
825
+ */
826
+ function humanAdoptCommand(flags) {
827
+ const parts = ['COLAB_HUMAN=1', 'colab', 'adopt'];
828
+ let hasAnsweredBy = false;
829
+ for (const [flag, value] of flags || []) {
830
+ if (flag === '--answered-by') hasAnsweredBy = true;
831
+ parts.push(value === undefined || value === null || value === true ? flag : `${flag} ${shellArg(value)}`);
832
+ }
833
+ if (!hasAnsweredBy) parts.push('--answered-by "<your name>"');
834
+ return parts.join(' ');
835
+ }
836
+
783
837
  // ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
784
838
 
785
839
  /**
@@ -1166,6 +1220,12 @@ module.exports = {
1166
1220
  renderMenu,
1167
1221
  resolveChoice,
1168
1222
  axisMissing,
1223
+ GATING_ROWS,
1224
+ OPTIONAL_ROWS,
1225
+ axesToAsk,
1226
+ optionalUnanswered,
1227
+ optionalRowsLine,
1228
+ humanAdoptCommand,
1169
1229
  EXPOSURE_RANK,
1170
1230
  GATE_CLASS,
1171
1231
  EXIT_CODE,
@@ -53,7 +53,8 @@
53
53
  * Context shape both sides build (identically named, audit.mjs and adopt.js each computing the
54
54
  * booleans from their own sources — a real git checkout for one, a `git status`-aware `io` for
55
55
  * the other):
56
- * { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames? }
56
+ * { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames?, branches? }
57
+ * `branches` (#522) is what `singleTrunkViolation` reads — omitting it fails closed to trunk "main".
57
58
  * `deployWorkflowNames` is OPTIONAL and cosmetic only (the `none` violation names which
58
59
  * workflow(s) contradict it) — omitting it (as adopt.js's ctx does) only drops the parenthetical
59
60
  * from the message, never changes which entries fire.
@@ -74,13 +75,45 @@ function evaluateExposure(exposure, ctx) {
74
75
  }
75
76
  }
76
77
 
78
+ /**
79
+ * #522: the single-trunk invariant shared by every shape with no release branch — `exposure: none`,
80
+ * `exposure: released` with `production: null`, and the legacy `tier: B` (audit/audit.mjs). It is
81
+ * about HOW MANY long-lived branches exist, never how the one branch is spelled: an existing repo
82
+ * whose default branch is `master` (or anything else) adopts as-is, with nothing renamed.
83
+ *
84
+ * What it refuses is the two-branch shape wearing a single-trunk label: a `main` branch sitting
85
+ * beside a trunk that is not `main` is the live/released split (main = what ships, trunk = where
86
+ * sessions land), and declaring "nothing consumes this" over it would hide the release branch.
87
+ *
88
+ * `branches` — every branch name the caller can see (local ∪ remote-tracking), or null/undefined
89
+ * when it cannot list them. Unknown FAILS CLOSED to the old spelling rule (trunk "main"): a
90
+ * non-main trunk is accepted only when a readable branch list proves no `main` sits beside it.
91
+ *
92
+ * Returns null when the invariant holds, else the reason text (no prefix — each caller names its
93
+ * own shape in front of it).
94
+ */
95
+ function singleTrunkViolation(trunk, branches) {
96
+ if (!trunk) return `no trunk declared, found ${JSON.stringify(trunk)}`;
97
+ if (trunk === 'main') return null;
98
+ if (!Array.isArray(branches)) {
99
+ return `trunk ${JSON.stringify(trunk)} can stand in for "main" only when the branch list is readable `
100
+ + 'and shows no "main" beside it, and the branch list could not be read';
101
+ }
102
+ if (branches.includes('main')) {
103
+ return `trunk is ${JSON.stringify(trunk)} and a "main" branch exists beside it — that is the `
104
+ + 'two-branch (live/released) shape, not a single trunk';
105
+ }
106
+ return null;
107
+ }
108
+
77
109
  function evaluateNone(ctx) {
78
110
  const out = [];
79
- if (ctx.trunk !== 'main') {
111
+ const single = singleTrunkViolation(ctx.trunk, ctx.branches);
112
+ if (single) {
80
113
  out.push({
81
114
  kind: 'fail',
82
- message: `exposure: none requires trunk "main", found ${JSON.stringify(ctx.trunk)} — nothing `
83
- + 'consumes this repo, so there is no release branch to speak of',
115
+ message: `exposure: none requires a single trunk — ${single} — nothing consumes this repo, `
116
+ + 'so there is no release branch to speak of',
84
117
  });
85
118
  }
86
119
  if (ctx.hasDeployWorkflow) {
@@ -131,11 +164,12 @@ function evaluateLive(ctx) {
131
164
 
132
165
  function evaluateReleasedNoProduction(ctx) {
133
166
  const out = [];
134
- if (ctx.trunk !== 'main') {
167
+ const single = singleTrunkViolation(ctx.trunk, ctx.branches);
168
+ if (single) {
135
169
  out.push({
136
170
  kind: 'fail',
137
- message: `exposure: released with production: null requires trunk "main", found `
138
- + `${JSON.stringify(ctx.trunk)} — nothing is live, so there is no release branch to speak of`,
171
+ message: `exposure: released with production: null requires a single trunk — ${single} — `
172
+ + 'nothing is live, so there is no release branch to speak of',
139
173
  });
140
174
  }
141
175
  if (ctx.deploy !== null && ctx.deploy !== undefined && ctx.deploy !== 'none') {
@@ -204,4 +238,4 @@ function evaluateReleasedWithProduction(ctx) {
204
238
  return out;
205
239
  }
206
240
 
207
- module.exports = { evaluateExposure };
241
+ module.exports = { evaluateExposure, singleTrunkViolation };