@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

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 (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -18,7 +18,8 @@
18
18
  * listDir(relPath) -> string[] non-recursive listing, [] if unreadable/absent
19
19
  * tags() -> string[] | null every git tag, or null if undeterminable
20
20
  *
21
- * Git facts that are NOT plain file reads (trunk, `core.hooksPath`) are passed in separately via
21
+ * Git facts that are NOT plain file reads (trunk, `core.hooksPath`, the fork remote and `git ls-files`
22
+ * for #449) are passed in separately via
22
23
  * `extra`, rather than folded into `io` — `detectTrunk()` already lives in `tools/lib/git.js` and
23
24
  * belongs to the CLI layer, not duplicated here.
24
25
  *
@@ -36,6 +37,13 @@ const { UserError } = require('./util.js');
36
37
 
37
38
  const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
38
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
+
39
47
  // ---------------------------------------------------------------------- descriptor read
40
48
 
41
49
  /** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
@@ -210,22 +218,201 @@ function deriveConsequences({ exposure, writes, room }) {
210
218
 
211
219
  // ---------------------------------------------------------------------- §9 remainder checklist
212
220
 
221
+ const migrationPaths = require('./migration-paths.js');
222
+ const codeowners = require('./codeowners.js');
223
+
213
224
  /**
214
- * §9's steps 3-9, unconditionally — this commit never performs any of them (Boundary, #199's
215
- * plan: "adopt writes the descriptor and nothing else"), so the remainder is the same regardless
216
- * of what the descriptor already states. Handed back as data, not prose, so a caller (a report
217
- * printer, or a future `handbook-sync` call site) does not grow its own paraphrase of these steps.
225
+ * #483 — on a fork, the CODEOWNERS teams that belong to another org: inherited from the upstream,
226
+ * unable to review here, and therefore ignored by `colab ship`'s core-path reader (CONVENTIONS.md
227
+ * §2, *Core paths*). Adopt names them so the fork owner learns at adoption time, not at the first
228
+ * ship, that the inherited file is inert until the fork writes its own. Null when there is nothing
229
+ * to say: not a fork, the fork's owner unknown, no CODEOWNERS, or no foreign team in it.
218
230
  */
219
- function remainingSteps() {
220
- return [
221
- { n: 3, text: 'Create the full label set (13 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
222
- { n: 4, text: 'Add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4' },
223
- { n: 5, text: 'Make CLAUDE.md the thin shell — `@AGENTS.md` plus templates/repo-CLAUDE-block.md, repo prose in AGENTS.md (adopt writes both on a new repo, #417), step 5' },
231
+ function detectInheritedCodeowners(io, fork, ownOrg) {
232
+ if (!fork || !ownOrg) return null;
233
+ for (const p of codeowners.CODEOWNERS_PATHS) {
234
+ const text = io.readFile(p);
235
+ if (text === null || text === undefined) continue;
236
+ const teams = codeowners.foreignTeams(codeowners.parse(text).rules, { fork: true, ownOrg });
237
+ return teams.length ? { path: p, ownOrg, teams } : null;
238
+ }
239
+ return null;
240
+ }
241
+
242
+ /**
243
+ * #449 — the agent workflow an upstream ships inside the fork: entries under `.claude/skills/`
244
+ * and `.claude/commands/`, plus a committed `AGENTS.md`. Upstream-owned files compete with the
245
+ * `code-*` skills, and deleting or editing them is a fork patch that conflicts on every upstream
246
+ * merge — so adopt only NAMES them, for the precedence line the appended block carries.
247
+ */
248
+ function detectUpstreamAgentFiles(io) {
249
+ const out = [];
250
+ for (const dir of ['.claude/skills', '.claude/commands']) {
251
+ for (const e of io.listDir(dir).slice().sort()) {
252
+ if (e.startsWith('.')) continue;
253
+ out.push(`${dir}/${e}`);
254
+ }
255
+ }
256
+ return out;
257
+ }
258
+
259
+ /**
260
+ * #449 — where this repo's migrations might live, beyond what `migrations:` and the two defaults
261
+ * already cover. Two heuristics over `git ls-files`, both CANDIDATES for a human, never written:
262
+ * a `migrations/` directory nothing covers (the audit's own rule, `undeclaredMigrationDirs`), and
263
+ * a directory holding tracked `*.sql` files nothing covers (a fork whose upstream keeps them in
264
+ * `modules/<name>/sql/` — measured: the no-new-migrations gate was blind there). The `.sql` rule
265
+ * over-reports seeds and fixtures on purpose: a false candidate costs a glance, a missed layout
266
+ * leaves a human-only gate seeing nothing.
267
+ */
268
+ function detectMigrationCandidates(cfg, trackedFiles) {
269
+ const parsed = migrationPaths.parseMigrationPaths(cfg);
270
+ const declared = parsed.paths;
271
+ const files = trackedFiles || [];
272
+ const dirs = new Set(migrationPaths.undeclaredMigrationDirs(files, declared));
273
+ for (const file of files) {
274
+ if (!/\.sql$/i.test(file)) continue;
275
+ const segs = String(file).split('/');
276
+ if (segs.length < 2) continue; // a root-level .sql is not a layout
277
+ if (segs.some((s) => s === 'node_modules' || s === 'vendor')) continue;
278
+ if (migrationPaths.isMigrationPath(file, declared)) continue;
279
+ const dir = `${segs.slice(0, -1).join('/')}/`;
280
+ if ([...dirs].some((d) => dir.startsWith(d))) continue;
281
+ dirs.add(dir);
282
+ }
283
+ return { declared: parsed.declared ? declared : null, candidates: [...dirs].sort() };
284
+ }
285
+
286
+ const MIGRATION_CANDIDATES_SHOWN = 6;
287
+
288
+ /** The step-2 remainder line about `migrations:` — adopt never asks it, so it always reports it. */
289
+ function migrationsStepText(m) {
290
+ const tail = 'project.schema.md `migrations`; `colab adopt` does not ask it, step 2';
291
+ if (m && m.declared && m.declared.length) {
292
+ const extra = m.candidates.length ? ` — still uncovered, check: ${listShort(m.candidates)}` : '';
293
+ return `\`migrations:\` declared (${m.declared.join(', ')})${extra} — ${tail}`;
294
+ }
295
+ if (m && m.candidates.length) {
296
+ return `Declare \`migrations:\` in .github/project.yml — candidate layouts outside database/migrations/ and prisma/migrations/: ${listShort(m.candidates)}. Until declared, the no-new-migrations gate cannot see them — ${tail}`;
297
+ }
298
+ return `Declare \`migrations:\` in .github/project.yml if this repo keeps migrations anywhere but database/migrations/ or prisma/migrations/ (none detected) — ${tail}`;
299
+ }
300
+
301
+ function listShort(items) {
302
+ const shown = items.slice(0, MIGRATION_CANDIDATES_SHOWN).join(', ');
303
+ return items.length > MIGRATION_CANDIDATES_SHOWN ? `${shown} (+${items.length - MIGRATION_CANDIDATES_SHOWN} more)` : shown;
304
+ }
305
+
306
+ /**
307
+ * §9's remainder, as data, not prose, so a caller (a report printer, or a future `handbook-sync`
308
+ * call site) does not grow its own paraphrase of these steps. Adopt writes the descriptor and
309
+ * nothing else (Boundary, #199's plan), so steps 3-9 are always listed.
310
+ *
311
+ * `ctx` (all optional, #449):
312
+ * migrations — `detectMigrationCandidates()`'s result; adds the step-2 `migrations:` line
313
+ * (absent ctx = the pre-#449 list, steps 3-9 only)
314
+ * fork — `{ remote, url, source }` when this repo tracks an upstream it does not own:
315
+ * step 5 becomes the append-only block instead of the thin-shell conversion
316
+ * (CONVENTIONS.md §9, *A fork of an upstream*)
317
+ * upstreamAgentFiles — on a fork, the upstream's own agent workflow, named for the precedence line
318
+ * releaseRung — `releaseRungSteps()`'s result (#492): extra step-6 lines on exposure: released
319
+ */
320
+ const releasePolicy = require('./release-policy.js');
321
+
322
+ const FINAL_TAG = /^v\d+\.\d+\.\d+$/;
323
+
324
+ /**
325
+ * #492 — on `exposure: released`, step 6 is not only CI: the release rung (CONVENTIONS.md §6) has
326
+ * to be wired at adoption too, or the repo never cuts a candidate until someone notices. Measured:
327
+ * six adopters in one fleet sweep with no `release:` block and no release workflow, several more
328
+ * with the workflow but no first final (`release cut` refuses with no final to bump from).
329
+ *
330
+ * Pure: reads the descriptor and what `io` already exposes. Returns step-6 entries (possibly
331
+ * none). Never decides a route on a human's behalf beyond §6's own derivation — the no-production
332
+ * row's choice is PROPOSED (public room -> public-tool, else rapid-app), and the text says so.
333
+ *
334
+ * `ctx`: { cfg, workflowTexts: { [file]: text }, tags: string[]|null, stackFiles: string[] }
335
+ */
336
+ function releaseRungSteps(ctx = {}) {
337
+ const cfg = ctx.cfg || {};
338
+ const def = releasePolicy.deriveDefault(cfg);
339
+ const exposure = axisAuthority.axisOfRecord(cfg).exposure;
340
+ if (exposure !== 'released') return [];
341
+ const steps = [];
342
+ const block = cfg.release && typeof cfg.release === 'object' ? cfg.release : null;
343
+
344
+ // 6a — the release: block.
345
+ if (block && block.route) {
346
+ steps.push({ n: 6, text: `Release rung: \`release.route: ${block.route}\` declared — keep it; confirm \`version-source\` (default \`tag\` where the machine cuts the tag, #484), CONVENTIONS.md §6 *Release routes*` });
347
+ } else if (def.row === 'released-tag' || def.row === 'released-manual') {
348
+ steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: deploy-tag\` and \`version-source: tag\` (block style — the descriptor reader parses no \`{ }\` flow map) — the tag deploys production (deploy: ${cfg.deploy}), so candidates are automatic and every final is a human click (CONVENTIONS.md §6 *Release routes*, #492)` });
349
+ } else if (def.row === 'released-no-production') {
350
+ const proposed = cfg.room === 'public' ? 'public-tool' : 'rapid-app';
351
+ steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: ${proposed}\` and \`version-source: tag\` (block style) — PROPOSED from room: ${cfg.room || 'undeclared'} (public CLI/handbook adopters install → public-tool; an app or tool with few installers → rapid-app; a library its consumers pin → library-fast) — confirm with the human, CONVENTIONS.md §6 *Release routes* (#492)` });
352
+ } else {
353
+ steps.push({ n: 6, text: 'Release rung: exposure: released but production/deploy match no §6 row — no route derives, a human tags; fix `deploy:`/`production:` before wiring a release workflow (CONVENTIONS.md §6, #492)' });
354
+ return steps;
355
+ }
356
+
357
+ // 6b — the release workflow.
358
+ const texts = ctx.workflowTexts || {};
359
+ const releaseWf = Object.keys(texts).find((f) => /colab release cut/.test(texts[f] || ''));
360
+ if (releaseWf) {
361
+ steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the self-hosted label on a private repo` });
362
+ } else {
363
+ steps.push({ n: 6, text: 'Copy the release workflow — `colab template release-auto`, then walk its `# EDIT:` points: `HANDBOOK_REF` (a channel or tag the handbook carries, #480), the test-suite workflow `name:`, and on a PRIVATE repo the self-hosted runner label from ci.yml on every job except `npm` (#492)' });
364
+ }
365
+
366
+ // 6c — a deploy template by stack, only where the tag deploys.
367
+ if (def.row === 'released-tag' || def.row === 'released-manual') {
368
+ const files = new Set(ctx.stackFiles || []);
369
+ const deployWf = Object.keys(texts).find((f) => /^deploy/.test(f));
370
+ const php = files.has('composer.json');
371
+ const container = ['Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml'].some((f) => files.has(f));
372
+ const tpl = php ? 'deploy-xserver' : container ? 'deploy-container' : null;
373
+ if (deployWf) {
374
+ steps.push({ n: 6, text: `Deploy workflow present (.github/workflows/${deployWf}) — nothing to copy` });
375
+ } else if (tpl) {
376
+ steps.push({ n: 6, text: `Copy the deploy template for this stack — \`colab template ${tpl}\` (${php ? 'PHP: composer.json' : 'container: a Dockerfile/compose file'}) — and keep it DISARMED: leave only its \`workflow_dispatch\` trigger until the operator has set its secrets and arms the \`push: tags\` trigger (#492)` });
377
+ } else {
378
+ steps.push({ n: 6, text: 'No deploy template matches this stack (none for it under templates/) — the deploy stays the runbook\'s, by hand (#492)' });
379
+ }
380
+ }
381
+
382
+ // 6d — the first final.
383
+ const tags = ctx.tags;
384
+ if (tags === null || tags === undefined) {
385
+ steps.push({ n: 6, text: 'First final: tags could not be read — check for a `vX.Y.Z` final; `colab release cut` refuses until one exists (#492)' });
386
+ } else if (!tags.some((t) => FINAL_TAG.test(t))) {
387
+ steps.push({ n: 6, text: 'First final: none yet, and `colab release cut` refuses with no final to bump from — the first final is the operator\'s to set (e.g. `git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0`); an agent tags it only when told to (#492)' });
388
+ }
389
+ return steps;
390
+ }
391
+
392
+ function remainingSteps(ctx = {}) {
393
+ const steps = [];
394
+ if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
395
+ steps.push(
396
+ { n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
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)' },
398
+ );
399
+ if (ctx.fork) {
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` });
401
+ const agentFiles = ctx.upstreamAgentFiles || [];
402
+ if (agentFiles.length) {
403
+ steps.push({ n: 5, text: `Upstream ships its own agent workflow (${listShort(agentFiles)}): leave it in place, and say in the appended block that fork work runs code-start → code-wrap → code-ship, not that workflow — §9 "A fork of an upstream", step 5` });
404
+ }
405
+ } else {
406
+ steps.push({ n: 5, text: 'Make CLAUDE.md the thin shell — `@AGENTS.md` plus templates/repo-CLAUDE-block.md, repo prose in AGENTS.md (adopt writes both on a new repo, #417), step 5' });
407
+ }
408
+ steps.push(
224
409
  { n: 6, text: "Make sure CI meets §7's outcome — `colab template <name>`, step 6" },
410
+ ...(ctx.releaseRung || []),
225
411
  { n: 7, text: 'Register the repo — `colab register`, step 7' },
226
412
  { n: 8, text: 'Leave existing branches alone — nothing to do, step 8' },
227
413
  { n: 9, text: 'Do not create `dev` unless genuinely Tier A or Tier C — nothing to do, step 9' },
228
- ];
414
+ );
415
+ return steps;
229
416
  }
230
417
 
231
418
  // ---------------------------------------------------------------------- row state
@@ -321,6 +508,24 @@ function detect(io, extra = {}) {
321
508
  // from a remote's HEAD — tools/colab's adoptGitExtras() is the only place that computes it.
322
509
  const trunkSource = (extra && extra.trunkSource) || null;
323
510
 
511
+ // #449: a repo you own that tracks an upstream you don't. The CLI detects it (a remote named
512
+ // `upstream` whose URL differs from origin's) or takes `--fork`/`--no-fork`; null = not a fork.
513
+ const fork = (extra && extra.fork) || null;
514
+ const upstreamAgentFiles = fork ? detectUpstreamAgentFiles(io) : [];
515
+ const inheritedCodeowners = detectInheritedCodeowners(io, fork, (extra && extra.ownOrg) || null);
516
+ // Only when the CLI handed over `git ls-files` — a pure-io caller without it gets no step-2 line
517
+ // rather than a false "none detected".
518
+ const migrations = extra && Array.isArray(extra.trackedFiles)
519
+ ? detectMigrationCandidates(cfg, extra.trackedFiles)
520
+ : null;
521
+
522
+ // #492: on exposure: released, step 6 also wires the release rung.
523
+ const workflowTexts = {};
524
+ for (const f of workflows) workflowTexts[f] = io.readFile(`.github/workflows/${f}`) || '';
525
+ const stackFiles = ['composer.json', 'Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml']
526
+ .filter((f) => io.readFile(f) !== null);
527
+ const releaseRung = releaseRungSteps({ cfg, workflowTexts, tags: io.tags ? io.tags() : null, stackFiles });
528
+
324
529
  return {
325
530
  descriptorExists: io.readFile('.github/project.yml') !== null,
326
531
  cfg,
@@ -335,7 +540,12 @@ function detect(io, extra = {}) {
335
540
  },
336
541
  legacyTierLetter,
337
542
  consequences,
338
- remaining: remainingSteps(),
543
+ fork,
544
+ upstreamAgentFiles,
545
+ inheritedCodeowners,
546
+ migrations,
547
+ remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
548
+ optionalUnanswered: optionalUnanswered(cfg), // #533
339
549
  };
340
550
  }
341
551
 
@@ -578,6 +788,52 @@ function axisMissing(cfg, axis) {
578
788
  }
579
789
  }
580
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
+
581
837
  // ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
582
838
 
583
839
  /**
@@ -747,6 +1003,92 @@ function writesGateVerdict({ writes, effExposure, isTTY, colabHuman, answeredBy
747
1003
  return { ok: true };
748
1004
  }
749
1005
 
1006
+ const VALID_AUTONOMY = new Set(['manual', 'auto-trunk']);
1007
+
1008
+ /**
1009
+ * #481 — `--autonomy` on `colab adopt`: the maintainer's grant recorded at adoption, so the
1010
+ * descriptor trunk carries from its first commit already says whether an agent may complete
1011
+ * Phase B. `auto-trunk` is the one value that EXPANDS permission (an unattended trunk merge
1012
+ * through `colab ship`), so it carries the same human bar as `writes: direct`; `manual` is the
1013
+ * default and never gated. Append-only like every other answer: a value already on record is
1014
+ * either the same (no-op) or a hand edit, never overwritten here.
1015
+ *
1016
+ * Returns `{ ok, write }` — `write` false when the same value is already declared — or a refusal
1017
+ * `{ ok:false, class, exitCode, message }`. Pure: cmdAdopt passes every fact in.
1018
+ */
1019
+ function autonomyGateVerdict({ autonomy, current, ceremony, isTTY, colabHuman, answeredBy }) {
1020
+ if (!VALID_AUTONOMY.has(autonomy)) {
1021
+ throw new UserError(`--autonomy must be one of: ${[...VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(autonomy)})`);
1022
+ }
1023
+ if (current !== undefined && current !== null) {
1024
+ if (String(current) === autonomy) return { ok: true, write: false };
1025
+ return {
1026
+ ok: false,
1027
+ class: GATE_CLASS.REPO_SHAPE,
1028
+ exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
1029
+ message: `project.yml already declares autonomy: ${current} — adopt is append-only and never `
1030
+ + 'rewrites a declared key; change it by hand, as its own reviewed commit',
1031
+ };
1032
+ }
1033
+ if (autonomy !== 'auto-trunk') return { ok: true, write: true };
1034
+ if (ceremony === 'light') {
1035
+ return {
1036
+ ok: false,
1037
+ class: GATE_CLASS.REPO_SHAPE,
1038
+ exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
1039
+ message: 'autonomy: auto-trunk is refused alongside ceremony: light — an unattended merge with '
1040
+ + 'the ceremony skipped is the one combination the handbook forbids (CONVENTIONS.md §2)',
1041
+ };
1042
+ }
1043
+ if (!(isTTY || (colabHuman && answeredBy))) {
1044
+ return {
1045
+ ok: false,
1046
+ class: GATE_CLASS.HUMAN_GATED,
1047
+ exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
1048
+ message: 'declaring autonomy: auto-trunk requires a human: answer at an interactive terminal, or '
1049
+ + 're-run with COLAB_HUMAN=1 and --answered-by "<name>" — it grants agents the trunk merge',
1050
+ };
1051
+ }
1052
+ return { ok: true, write: true };
1053
+ }
1054
+
1055
+ /**
1056
+ * #481 — may `colab adopt --land` commit the descriptor straight to trunk? Landing writes trunk,
1057
+ * so it is the human's act and never an agent's: COLAB_HUMAN=1 AND --answered-by, no TTY
1058
+ * substitute (a TTY proves a terminal, not that this particular write was asked for). It runs only
1059
+ * on a checkout standing ON trunk, never --local (a local descriptor is machine state, never
1060
+ * committed). Pure.
1061
+ */
1062
+ function landVerdict({ local, colabHuman, answeredBy, trunk, currentBranch }) {
1063
+ if (local) {
1064
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
1065
+ message: '--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)' };
1066
+ }
1067
+ if (!(colabHuman && answeredBy)) {
1068
+ return { ok: false, class: GATE_CLASS.HUMAN_GATED, exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
1069
+ message: '--land commits to trunk, which is a human act: re-run with COLAB_HUMAN=1 and --answered-by "<name>"' };
1070
+ }
1071
+ if (!trunk) {
1072
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
1073
+ message: '--land needs a trunk, and none could be determined' };
1074
+ }
1075
+ if (currentBranch !== trunk) {
1076
+ return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
1077
+ message: `--land runs on the trunk checkout: this checkout is on ${currentBranch ? JSON.stringify(currentBranch) : 'no branch'}, trunk is ${JSON.stringify(trunk)} — `
1078
+ + `run it from the checkout standing on ${trunk}` };
1079
+ }
1080
+ return { ok: true };
1081
+ }
1082
+
1083
+ /** The commit message `--land` writes. Conventional, so it is visible in release notes. */
1084
+ function landCommitMessage({ answeredBy, paths }) {
1085
+ return 'chore: adopt the colab-handbook conventions — land the descriptor on trunk\n\n'
1086
+ + `Committed by \`colab adopt --land\` (COLAB_HUMAN=1, --answered-by ${JSON.stringify(answeredBy)}): `
1087
+ + 'the maintainer\'s adoption answers, on trunk from its first commit, so the branch that adds '
1088
+ + 'CI is judged by them.\n\n'
1089
+ + `Paths: ${paths.join(', ')}\n`;
1090
+ }
1091
+
750
1092
  // ---------------------------------------------------------------------- provenance + the append-only write
751
1093
 
752
1094
  /** The comment placed beside a written key — never trusted as identity (see gateVerdict's
@@ -822,7 +1164,7 @@ function renderDescriptor(rawText, entries) {
822
1164
  * `tier` may be null (a shape with no legacy letter): the placeholder is then left for a human,
823
1165
  * never guessed — the same rule deriveTier itself follows.
824
1166
  */
825
- function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
1167
+ function renderClaudeShell(blockTemplate, { version, trunk, tier, importAgents = true }) {
826
1168
  let block = String(blockTemplate).replace(/^\s*<!--[\s\S]*?-->\s*/, ''); // the paste note
827
1169
  block = block.replace('<!-- colab-handbook @ <version> -->', `<!-- colab-handbook @ ${version} -->`);
828
1170
  if (trunk) {
@@ -834,7 +1176,10 @@ function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
834
1176
  // `<A = … · C = … · B = …>` → the one gloss that applies.
835
1177
  block = block.replace(/<A = ([^·>]+?) · C = ([^·>]+?) · B = ([^>]+?)>/, (m, a, c, b) => ({ A: a, B: b, C: c })[tier] || m);
836
1178
  }
837
- return `@AGENTS.md\n\n${block.replace(/\s*$/, '\n')}`;
1179
+ // #449: a fork with no upstream AGENTS.md gets the block alone — no import of a file adopt
1180
+ // must not create there.
1181
+ const body = block.replace(/\s*$/, '\n');
1182
+ return importAgents ? `@AGENTS.md\n\n${body}` : body;
838
1183
  }
839
1184
 
840
1185
  /** The AGENTS.md stub written beside a new shell, only when no AGENTS.md exists. */
@@ -850,6 +1195,7 @@ function renderAgentsStub() {
850
1195
  }
851
1196
 
852
1197
  module.exports = {
1198
+ detectInheritedCodeowners,
853
1199
  renderClaudeShell,
854
1200
  renderAgentsStub,
855
1201
  ROW_NAMES,
@@ -859,6 +1205,9 @@ module.exports = {
859
1205
  deriveTier,
860
1206
  deriveConsequences,
861
1207
  remainingSteps,
1208
+ releaseRungSteps,
1209
+ detectUpstreamAgentFiles,
1210
+ detectMigrationCandidates,
862
1211
  detect,
863
1212
  // commit 2
864
1213
  VALID_ROOM,
@@ -871,12 +1220,22 @@ module.exports = {
871
1220
  renderMenu,
872
1221
  resolveChoice,
873
1222
  axisMissing,
1223
+ GATING_ROWS,
1224
+ OPTIONAL_ROWS,
1225
+ axesToAsk,
1226
+ optionalUnanswered,
1227
+ optionalRowsLine,
1228
+ humanAdoptCommand,
874
1229
  EXPOSURE_RANK,
875
1230
  GATE_CLASS,
876
1231
  EXIT_CODE,
877
1232
  exposureShapeVerdict,
878
1233
  gateVerdict,
879
1234
  writesGateVerdict,
1235
+ VALID_AUTONOMY,
1236
+ autonomyGateVerdict,
1237
+ landVerdict,
1238
+ landCommitMessage,
880
1239
  provenanceComment,
881
1240
  renderDescriptor,
882
1241
  };
@@ -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
  };