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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -113,11 +113,6 @@ Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
113
113
  handbook), and `migration-review` (review a branch's migrations, for whoever a
114
114
  repo binds to that role).
115
115
 
116
- **Running the loop by hand at a terminal?** With no `--session`, `colab` names
117
- you `person:<git user.email>/<host token>`, so claims and ship evidence say who
118
- you are. If you work on several units at once from separate shells, give each
119
- shell its own `COLAB_SESSION=<any stable id>` so their holds stay apart.
120
-
121
116
  **Words you will meet:**
122
117
 
123
118
  - **Trunk** — the branch sessions merge into (`trunk:` in `project.yml`).
package/README.vi.md CHANGED
@@ -112,12 +112,6 @@ Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó,
112
112
  nhất), và `migration-review` (review migration của một nhánh, cho người/agent
113
113
  được repo gán vai đó).
114
114
 
115
- **Tự chạy vòng này bằng tay ở terminal?** Không có `--session` thì `colab` đặt
116
- tên bạn là `person:<git user.email>/<host token>`, nên claim và bằng chứng ship
117
- đều ghi rõ ai làm. Nếu làm nhiều đơn vị việc cùng lúc ở các shell khác nhau,
118
- đặt cho mỗi shell một `COLAB_SESSION=<id ổn định bất kỳ>` để các hold không lẫn
119
- vào nhau.
120
-
121
115
  **Mấy từ sẽ gặp:**
122
116
 
123
117
  - **Trunk** — nhánh các phiên merge vào (`trunk:` trong `project.yml`).
package/package.json CHANGED
@@ -17,7 +17,6 @@
17
17
  "tools/colab",
18
18
  "tools/lib/*.js",
19
19
  "!tools/lib/*.test.js",
20
- "!tools/lib/refusal-sites.js",
21
20
  "tools/lib/tracker-scenarios.json",
22
21
  "tools/lib/codec/*.js",
23
22
  "tools/lib/codec/*.d.ts",
@@ -33,5 +32,5 @@
33
32
  "engines": {
34
33
  "node": ">=18"
35
34
  },
36
- "version": "1.13.0-rc.10"
35
+ "version": "1.13.0-rc.2"
37
36
  }
package/tools/colab CHANGED
@@ -77,7 +77,6 @@ const shipRoles = require('./lib/ship-roles'); // #372
77
77
  const refsBrake = require('./lib/refs-brake'); // #385
78
78
  const localAdopt = require('./lib/local-adopt'); // #393
79
79
  const ownerBranch = require('./lib/owner-branch'); // #394
80
- const humanDoor = require('./lib/ship-human-door'); // #525
81
80
  const {
82
81
  HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
83
82
  parseArgs, table, shortRepo,
@@ -284,38 +283,11 @@ function myMachineId() { return machine.localMachine().id || null; }
284
283
 
285
284
  /**
286
285
  * Resolve the Claude session URL for this invocation: --session flag > COLAB_SESSION env >
287
- * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — typically a session URL.
288
- *
289
- * The derived step exists for a person at a plain terminal, who has no session runtime and so no
290
- * id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
291
- * warned three lines every time, and ship evidence read `implemented by: unknown`. It applies only
292
- * when `COLAB_SESSION` is unset and the shell is not an agent's (`claimIdentity.
293
- * shouldDerivePersonSession` has why) — an explicit flag or env value always wins.
286
+ * '' (absent, never an error). Free-form — typically a session URL.
294
287
  */
295
288
  function resolveSession(opts) {
296
- const s = String(opts.session || process.env.COLAB_SESSION || '').trim();
297
- return s || derivedPersonSession();
298
- }
299
-
300
- /**
301
- * The derived person identity for this invocation, or ''. Memoized — one `git config` spawn, and
302
- * the "derived" note is printed once per invocation (stderr, so `--json` stdout stays clean).
303
- */
304
- let derivedSessionCache = null;
305
- function derivedPersonSession() {
306
- if (derivedSessionCache !== null) return derivedSessionCache;
307
- derivedSessionCache = '';
308
- if (!claimIdentity.shouldDerivePersonSession(process.env)) return derivedSessionCache;
309
- const r = spawnSync('git', ['config', '--get', 'user.email'], { encoding: 'utf8' });
310
- const email = r.status === 0 ? String(r.stdout || '').trim() : '';
311
- let user = process.env.USER || '';
312
- if (!user) { try { user = os.userInfo().username; } catch { user = ''; } }
313
- derivedSessionCache = claimIdentity.derivePersonSession({ email, user, hostToken: machine.hostToken(HOST) });
314
- if (derivedSessionCache) {
315
- process.stderr.write(`· session: ${derivedSessionCache} (derived — no --session or COLAB_SESSION given; ` +
316
- `either one overrides it)\n`);
317
- }
318
- return derivedSessionCache;
289
+ const s = opts.session || process.env.COLAB_SESSION || '';
290
+ return String(s).trim();
319
291
  }
320
292
 
321
293
  /**
@@ -5705,8 +5677,7 @@ function cmdWorktreeNew(argv) {
5705
5677
 
5706
5678
  // #488: the scratch dirs (plans, briefs) are hidden in the clone's shared info/exclude — one
5707
5679
  // write covers the main checkout and every worktree, with no per-repo .gitignore diff.
5708
- // #527: and the worktree subdir itself, or trunk's `git add -A` stages this worktree as a gitlink.
5709
- ensureScratchExcluded(repoAbs, config);
5680
+ ensureScratchExcluded(repoAbs);
5710
5681
 
5711
5682
  // 5. optional repo hook (machine-specific steps plug in here)
5712
5683
  const hook = runHook(repoAbs, 'post-create', { wtPath, name, branch, ports: alloc.chosenPorts, trunk, base, issues });
@@ -8052,17 +8023,13 @@ function gitExcludePath(repoAbs) {
8052
8023
  /**
8053
8024
  * #488: append the scratch-dir exclude lines (scratch-dirs.js `excludeLines`) to the clone's shared
8054
8025
  * info/exclude, idempotently. Best-effort: a failure warns and never blocks the caller.
8055
- * #527: `config` given → the worktree subdir's line too (`worktreeExcludeLine`), so whatever creates
8056
- * the default worktree dir also hides it — an adopted repo's `.gitignore` has never heard of it.
8057
8026
  */
8058
- function ensureScratchExcluded(repoAbs, config = null) {
8027
+ function ensureScratchExcluded(repoAbs) {
8059
8028
  const excludeFile = gitExcludePath(repoAbs);
8060
8029
  if (!excludeFile) return [];
8061
8030
  let before = null;
8062
8031
  try { before = fs.readFileSync(excludeFile, 'utf8'); } catch (_) { /* absent */ }
8063
8032
  const lines = scratchDirs.excludeLines();
8064
- const wtLine = config ? scratchDirs.worktreeExcludeLine(worktreeSubdir(config)) : null;
8065
- if (wtLine && !lines.includes(wtLine)) lines.push(wtLine);
8066
8033
  const missing = localAdopt.missingExcludeLines(before, lines);
8067
8034
  if (!missing.length) return [];
8068
8035
  try {
@@ -8381,9 +8348,7 @@ async function askMenu(rl, axis, promptFn) {
8381
8348
  if (resolved.ok) return resolved;
8382
8349
  process.stdout.write(` ${resolved.message}\n`);
8383
8350
  }
8384
- throw new UserError(`${axis}: no valid answer after one re-prompt — nothing was written. Run \`colab adopt --axis ${axis}\` ` +
8385
- `to be asked again, or pass the value directly: \`colab adopt ${axis === 'tier' ? '--deploy' : `--${axis}`} <value>\` ` +
8386
- `(\`colab adopt --help\` lists them).`);
8351
+ throw new UserError(`${axis}: no valid answer after one re-prompt`);
8387
8352
  }
8388
8353
 
8389
8354
  /**
@@ -8443,10 +8408,7 @@ async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
8443
8408
  if (!problem) { chosen = resolved; break; }
8444
8409
  process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
8445
8410
  }
8446
- // #532: this refusal comes after a long interaction, so it names the way through, not just the stop.
8447
- if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt — nothing was written. ' +
8448
- 'Each "✗" above says why its value was refused. Run `colab adopt --axis exposure` and pick a value it accepts, ' +
8449
- 'or `colab adopt --exposure <value>` non-interactively; choosing "skip" leaves exposure unanswered for now.');
8411
+ if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
8450
8412
  if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
8451
8413
  answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
8452
8414
  } else {
@@ -8536,12 +8498,6 @@ async function cmdAdopt(argv) {
8536
8498
  local = adoptLocalPrepare(repoAbs, opts);
8537
8499
  if (local.exit !== undefined) return local.exit;
8538
8500
  }
8539
- // #527: a repo adopted before `worktree new` hid its own dir gets the same exclude lines here —
8540
- // machine-local (info/exclude), idempotent, never a committed diff. --local already wrote them.
8541
- if (!opts.local) {
8542
- const hidden = ensureScratchExcluded(repoAbs, state.loadConfig());
8543
- if (hidden.length && !opts.json) print(`✓ hid ${hidden.join(' ')} in .git/info/exclude (machine-local)`);
8544
- }
8545
8501
  const io = adoptIo(repoAbs);
8546
8502
  const extra = adoptGitExtras(repoAbs, opts);
8547
8503
  if (local) { extra.trunk = local.trunk; extra.trunkSource = 'local-integration'; }
@@ -10030,18 +9986,14 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10030
9986
  return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
10031
9987
  }
10032
9988
 
10033
- const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
9989
+ const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--session <id>] [--session-name <s>] [--dry] [--json]
10034
9990
  colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10035
9991
 
10036
9992
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10037
9993
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
10038
9994
  (project.yml \`integration:\`). Autonomy is granted by the repo's .github/project.yml
10039
9995
  (\`autonomy: auto-trunk\`) — NOT by any flag. Without that grant, ship refuses and a human must run
10040
- Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). That human runs ship
10041
- too, through the HUMAN DOOR (#525): at an interactive terminal (outside an agent shell) ship asks
10042
- them to confirm; non-interactively, COLAB_HUMAN=1 plus --answered-by <name>. Every other
10043
- precondition still applies, and the 🚢 comment records that the human door opened the gate.
10044
- ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
9996
+ Phase B — unless the change is DOCS-ONLY, computed from git (#345, below). ship NEVER touches main (when trunk≠main), NEVER tags, NEVER promotes.
10045
9997
 
10046
9998
  Base and target are ONE decision. A branch cut from a long-lived line and shipped into trunk would
10047
9999
  drag the entire line in behind it, as a single squash commit that reads like a small change — so
@@ -10051,8 +10003,6 @@ promotes is an integration event of the same weight as a promotion, and stays hu
10051
10003
 
10052
10004
  Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
10053
10005
  a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
10054
- — or a person runs ship through the human door (#525): a confirmed interactive
10055
- terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
10056
10006
  b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
10057
10007
  human step needed — OR every issue the branch carries holds a valid
10058
10008
  \`colab ci-grant\` over trunk's CURRENT red sha, #105 — see below) · no new
@@ -11099,7 +11049,7 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
11099
11049
  return {
11100
11050
  name: raw.name, ok: true, class: null,
11101
11051
  detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via}${viaDry} (raw: ${raw.detail})`,
11102
- grantVerdict: null, cureVerdict, redSha,
11052
+ grantVerdict: null, cureVerdict,
11103
11053
  };
11104
11054
  }
11105
11055
 
@@ -11114,45 +11064,10 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
11114
11064
  return {
11115
11065
  name: raw.name, ok: true, class: null,
11116
11066
  detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
11117
- grantVerdict, cureVerdict, redSha,
11067
+ grantVerdict, cureVerdict,
11118
11068
  };
11119
11069
  }
11120
- // #534: both doors were consulted and both refused — say WHY on the row itself, so the prose table,
11121
- // `--dry`, and B1's abort line all tell "needs a grant" from "missing evidence" from "stacked". The
11122
- // JSON payload already carried `ciCure.reason`; the prose detail used to end at the raw trunk read.
11123
- return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict)}`, grantVerdict, cureVerdict, redSha };
11124
- }
11125
-
11126
- /**
11127
- * Which red-trunk door let a trunk-CI row pass — `'cure rule'`, `'ci-grant'`, or null for a row that
11128
- * passed on its own (green) or did not pass (#538: B1 re-measures only a door the table relied on).
11129
- */
11130
- function doorThatAdmitted(ciResult) {
11131
- if (!ciResult || !ciResult.ok) return null;
11132
- if (ciResult.cureVerdict && ciResult.cureVerdict.ok) return 'cure rule';
11133
- if (ciResult.grantVerdict && ciResult.grantVerdict.ok) return 'ci-grant';
11134
- return null;
11135
- }
11136
-
11137
- /** #538: the pause before B1's one re-measure — long enough for a transient `gh` failure to clear. */
11138
- const B1_REMEASURE_MS = Number.isFinite(Number(process.env.COLAB_B1_REMEASURE_MS))
11139
- && process.env.COLAB_B1_REMEASURE_MS !== '' ? Number(process.env.COLAB_B1_REMEASURE_MS) : 3000;
11140
-
11141
- /**
11142
- * The " — cure rule (#281): …; ci-grant (#105): …" suffix of a refused trunk-CI row (#534). Empty
11143
- * when neither door was consulted. One clause per door, each its own refusal reason verbatim — the
11144
- * cure's `reason`, the grant's per-issue `missing[].reason` — never a re-wording, so the prose and
11145
- * the `--dry --json` fields cannot read differently.
11146
- */
11147
- function doorRefusalNote(cureVerdict, grantVerdict) {
11148
- const parts = [];
11149
- if (cureVerdict && !cureVerdict.ok && cureVerdict.reason) parts.push(`cure rule (#281): ${cureVerdict.reason}`);
11150
- if (grantVerdict && !grantVerdict.ok) {
11151
- const why = (grantVerdict.missing || []).map((m) => (m.issue ? `#${m.issue}: ` : '') + m.reason)
11152
- .map((s) => s.replace(/^(#\d+): \1/, '$1')).join('; ');
11153
- if (why) parts.push(`ci-grant (#105): ${why}`);
11154
- }
11155
- return parts.length ? ` — ${parts.join(' · ')}` : '';
11070
+ return { ...raw, grantVerdict, cureVerdict };
11156
11071
  }
11157
11072
 
11158
11073
  /**
@@ -11694,8 +11609,7 @@ function cmdShipDryJson(opts) {
11694
11609
  }
11695
11610
 
11696
11611
  // ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
11697
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
11698
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
11612
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
11699
11613
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
11700
11614
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
11701
11615
 
@@ -12094,7 +12008,7 @@ function shipEvidenceClose({ repoAbs, st, sess, target, trunk, gh, closeIssues,
12094
12008
  `The deliverable is recorded on this issue (see the comment(s) above), which is what authorised ` +
12095
12009
  `the close — colab closes a zero-diff issue only when it already carries a comment colab did not ` +
12096
12010
  `write. The zero-diff fact was measured from git: ${mode.why}.${shipSess}`;
12097
- const c = git.ghIssueComment(repoAbs, num, body + (opts.humanDoorEvidence || '')); // #525
12011
+ const c = git.ghIssueComment(repoAbs, num, body);
12098
12012
  if (!c.ok) warn(`could not post the evidence-close comment on #${num} — closing anyway`);
12099
12013
  const r = tracker.forRepo(repoAbs).issueClose(num, { reason: 'completed' });
12100
12014
  if (!r.ok) { skipped.push({ num, why: `gh issue close failed: ${(r.stderr || '').split('\n')[0]}` }); continue; }
@@ -12256,8 +12170,7 @@ function cmdShipDirect(opts) {
12256
12170
  // #345: a trunk-direct unit has no branch diff. Its change set is every trunk commit since its
12257
12171
  // earliest claim — by anyone, so the verdict can only err toward refusing (lib/docs-only.js).
12258
12172
  const since = claims.map((c) => c.created).filter(Boolean).sort()[0];
12259
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since),
12260
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12173
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.directChanges(git, repoAbs, trunk, since));
12261
12174
  autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
12262
12175
  checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
12263
12176
 
@@ -12336,7 +12249,6 @@ function cmdShipDirect(opts) {
12336
12249
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12337
12250
  process.stderr.write(' A human must close this unit. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12338
12251
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12339
- process.stderr.write(shipHumanDoorRefusal(autonomyGate, '--direct'));
12340
12252
  return 1;
12341
12253
  }
12342
12254
  if (!coreOk && coreReview.corePaths.length) {
@@ -12348,7 +12260,6 @@ function cmdShipDirect(opts) {
12348
12260
  process.stderr.write(' unit\'s reviewed landing, a human closes this issue by hand.\n');
12349
12261
  }
12350
12262
  if (autonomyGate.via === 'docs-only') print(`→ AUTONOMY: ${autonomyGate.detail} (#345) — project.yml autonomy: ${autonomyGate.declared}`);
12351
- if (autonomyGate.via === 'human') print(`→ AUTONOMY: ${autonomyGate.detail}`);
12352
12263
  print(`→ MODE: evidence-close (trunk-direct — the work is already on ${trunk}; nothing to merge)`);
12353
12264
  if (opts.dry) {
12354
12265
  print(preOk ? '→ READY: preconditions pass. Re-run without --dry to close.' : '→ NOT READY: fix the ✗ rows above.');
@@ -12360,7 +12271,6 @@ function cmdShipDirect(opts) {
12360
12271
  return preOk ? 0 : 1;
12361
12272
  }
12362
12273
  if (!preOk) { process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was closed.\n'); return 1; }
12363
- if (!shipHumanDoorGo(autonomyGate, opts, `close ${issues.map((n) => '#' + n).join(' ')} on ${trunk} (trunk-direct)`)) return 1;
12364
12274
 
12365
12275
  const tip = shortSha(git.git(['rev-parse', trunk], repoAbs).stdout);
12366
12276
  const mode = { evidenceClose: true, direct: true, why: `trunk-direct unit — ${trunk}@${tip} is checked out clean and published to ${git.remoteInfo(repoAbs).name || 'origin'}/${trunk}` };
@@ -12578,81 +12488,20 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
12578
12488
  *
12579
12489
  * Returns `{ ok, via: 'auto-trunk'|'docs-only'|null, declared, docsOnly: verdict|null, detail }`.
12580
12490
  */
12581
- function shipAutonomyGate(doc, readDocsOnly, door = null) {
12491
+ function shipAutonomyGate(doc, readDocsOnly) {
12582
12492
  const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
12583
- if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
12493
+ if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, detail: 'auto-trunk' };
12584
12494
  const verdict = readDocsOnly();
12585
12495
  if (verdict.docsOnly) {
12586
- return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
12587
- }
12588
- // #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
12589
- // after docs-only, so a docs-only change keeps its own (agent-usable) door and record.
12590
- if (door && door.open) {
12591
- return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
12592
- detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
12496
+ return { ok: true, via: 'docs-only', declared, docsOnly: verdict, detail: `${verdict.reason} — autonomy exception` };
12593
12497
  }
12594
- return { ok: false, via: null, declared, docsOnly: verdict, human: door,
12595
- detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; human door closed: ${door ? door.why : 'not offered'})` };
12596
- }
12597
-
12598
- /** #525: the human-door refusal lines — what a person runs, never just "a human must". */
12599
- function shipHumanDoorRefusal(gate, selector) {
12600
- const lines = [];
12601
- if (gate.human && gate.human.why) lines.push(` The human door (#525) did not open: ${gate.human.why}.`);
12602
- lines.push(' A person gives the go by running ship themselves — every other precondition still applies:');
12603
- for (const l of humanDoor.humanDoorCommands(selector)) lines.push(` ${l}`);
12604
- lines.push(' An agent does not pass this door on its own (CONVENTIONS.md §2, *The human door*).');
12605
- return lines.join('\n') + '\n';
12606
- }
12607
-
12608
- /** #525: the ship selector to paste into the refusal's command line. */
12609
- function shipSelector(opts, sess) {
12610
- if (opts.direct) return '--direct';
12611
- if (opts.worktree) return `--worktree ${opts.worktree}`;
12612
- if (sess && sess.name) return `--worktree ${sess.name}`;
12613
- if (opts.branch) return `--branch ${opts.branch}`;
12614
- return sess && sess.branch ? `--branch ${sess.branch}` : '';
12615
- }
12616
-
12617
- /**
12618
- * #525: confirm the TTY door by a typed answer. Synchronous on purpose — ship is a sync pipeline,
12619
- * and the prompt sits before any write. Anything but `y`/`yes` is a no; EOF is a no.
12620
- */
12621
- function shipConfirmAtTerminal(question) {
12622
- process.stdout.write(`${question} [y/N] `);
12623
- const buf = Buffer.alloc(256);
12624
- let line = '';
12625
- for (;;) {
12626
- let n = 0;
12627
- try { n = fs.readSync(0, buf, 0, buf.length, null); } catch (e) { if (e.code === 'EAGAIN') continue; return false; }
12628
- if (n <= 0) break;
12629
- line += buf.toString('utf8', 0, n);
12630
- if (line.includes('\n')) break;
12631
- }
12632
- return /^\s*y(es)?\s*$/i.test(line.split('\n')[0]);
12633
- }
12634
-
12635
- /**
12636
- * #525: the last step before any write when the human door opened the gate. A TTY door asks the
12637
- * person to confirm; a COLAB_HUMAN door already carries its go (`--answered-by`). Either way the
12638
- * evidence clause is stashed on `opts` for the comment writers. Returns false on a declined prompt.
12639
- */
12640
- function shipHumanDoorGo(gate, opts, what) {
12641
- if (gate.via !== 'human') return true;
12642
- if (gate.human.how === 'tty' && !shipConfirmAtTerminal(`Human door (#525): ${what}. This is your go — proceed?`)) {
12643
- process.stderr.write('✗ Not confirmed at the terminal. Nothing was changed.\n');
12644
- return false;
12645
- }
12646
- opts.humanDoorEvidence = humanDoor.humanDoorEvidence(gate.human);
12647
- return true;
12498
+ return { ok: false, via: null, declared, docsOnly: verdict,
12499
+ detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason})` };
12648
12500
  }
12649
12501
 
12650
12502
  /** #345: the additive `autonomyGate` field of the `--dry --json` output. */
12651
12503
  function autonomyGatePayload(gate) {
12652
- // #525: `human` is additive and present only when the human door was consulted, so an
12653
- // auto-trunk / docs-only payload stays byte-identical to before.
12654
- return gate.human ? { via: gate.via, docsOnly: gate.docsOnly, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } }
12655
- : { via: gate.via, docsOnly: gate.docsOnly };
12504
+ return { via: gate.via, docsOnly: gate.docsOnly };
12656
12505
  }
12657
12506
 
12658
12507
  /** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
@@ -12663,7 +12512,7 @@ function shipRefFor(repoAbs, branch) {
12663
12512
 
12664
12513
  function cmdShip(argv) {
12665
12514
  const opts = parseArgs(argv, {
12666
- values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
12515
+ values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch' },
12667
12516
  // #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
12668
12517
  // `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
12669
12518
  // accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
@@ -12738,13 +12587,11 @@ function cmdShip(argv) {
12738
12587
 
12739
12588
  // ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
12740
12589
  // #345: …or the branch's diff is documentation only, computed here from git — never asserted.
12741
- const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
12742
- humanDoor.humanDoorFromProcess(process, opts.answeredBy)); // #525
12590
+ const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)));
12743
12591
  if (!autonomyGate.ok) {
12744
12592
  process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
12745
12593
  process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
12746
12594
  process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
12747
- process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
12748
12595
  return 1;
12749
12596
  }
12750
12597
 
@@ -13137,9 +12984,6 @@ function cmdShip(argv) {
13137
12984
  }
13138
12985
  process.stderr.write('✗ Aborting: one or more preconditions failed (see ✗ above). Nothing was pushed.\n'); return 1;
13139
12986
  }
13140
- if (!shipHumanDoorGo(autonomyGate, opts, mode.evidenceClose
13141
- ? `evidence-close ${sess.issues.map((n) => '#' + n).join(' ')} (${sess.branch} has nothing to merge)`
13142
- : `squash-merge ${sess.branch} into ${target}`)) return 1;
13143
12987
 
13144
12988
  // ---- (b3) evidence-close: the whole B0–B2 sequence is skipped, because there is nothing to merge ----
13145
12989
  if (mode.evidenceClose) return shipEvidenceClose({
@@ -13264,29 +13108,12 @@ function cmdShip(argv) {
13264
13108
  let ciGrantForTrailer = null; // #105: set below when B1 shipped UNDER a grant — read at commit-message time
13265
13109
  let ciCureForTrailer = null; // #281: set below when B1 shipped UNDER the cure rule — read at commit-message time
13266
13110
  if (gh) {
13267
- const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
13111
+ const ciResultB1 = shipCiCheck(repoAbs, gh, target, trunk,
13268
13112
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
13269
13113
  (redSha) => shipCiCure(repoAbs, gh, target, trunk, redSha, sess.branch), sess.branch);
13270
- let ciResultB1 = measureB1();
13271
- // #538: the table admitted this branch through a door (cure or grant) at red sha X, and B1 —
13272
- // seconds later, at the SAME red sha — refused. Nothing the door judges moved (trunk's head is
13273
- // X in both reads), so the likeliest cause is one of the ~10 `gh` reads a door makes failing
13274
- // once, which every door reads as a refusal (fail closed). Measured: `--dry` said READY and the
13275
- // real ship aborted here with only the raw "conclusion=failure". Re-measure ONCE, in full —
13276
- // never reuse the table's verdict (B1 exists to catch a change) — and if it refuses again, abort
13277
- // saying it was the door, with the door's own reason.
13278
- const tableDoor = doorThatAdmitted(ciResult);
13279
- if (!ciResultB1.ok && tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha) {
13280
- warn(` B1: the ${tableDoor} admitted this branch in the table at ${target}@${shortSha(ciResult.redSha)} but refused on the re-check at the same sha — re-measuring once (a failed read refuses).`);
13281
- ciWait.sleepSync(B1_REMEASURE_MS);
13282
- ciResultB1 = measureB1();
13283
- }
13284
13114
  if (!ciResultB1.ok) {
13285
13115
  cleanupEphemeral();
13286
- const sameRed = tableDoor && ciResultB1.redSha && ciResultB1.redSha === ciResult.redSha;
13287
- process.stderr.write(sameRed
13288
- ? `✗ B1: the ${tableDoor} admitted this branch in the precondition table, then refused twice on the re-check at the same ${target}@${shortSha(ciResult.redSha)} — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`
13289
- : `✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
13116
+ process.stderr.write(`✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
13290
13117
  return 1;
13291
13118
  }
13292
13119
  if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
@@ -13656,8 +13483,7 @@ function cmdShip(argv) {
13656
13483
  // last — see warnDeferred's own comment for why this is scoped to exactly this window. The
13657
13484
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
13658
13485
  // same block, and re-assigning the collector here would silently discard them.
13659
- shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
13660
- evidenceExtra: opts.humanDoorEvidence || '' }); // #525
13486
+ shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts });
13661
13487
 
13662
13488
  print('');
13663
13489
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -95,43 +95,6 @@ function isIntentSession(s) {
95
95
  return /^intent:\S/.test(String(s == null ? '' : s).trim());
96
96
  }
97
97
 
98
- /**
99
- * Should a blank session be DERIVED for a person at a plain terminal (#528)? Only when nothing was
100
- * said at all: `COLAB_SESSION` is UNSET (an explicit `COLAB_SESSION=''` is a deliberate "present no
101
- * identity" and is honoured as one), and the shell is not an agent's (`CLAUDECODE=1` / `AI_AGENT`,
102
- * the same signal `place.resolveAnchor` reads). An agent keeps #242's refusal: two concurrent agent
103
- * sessions on one machine would derive the SAME person id, and `place.conflict`'s same-holder
104
- * exemption would then read one session's hold as the other's — the collision #242 exists to stop.
105
- * A person running several units at once from separate shells has the same problem, which is why
106
- * the README tells them to give each shell its own `COLAB_SESSION`.
107
- */
108
- function shouldDerivePersonSession(env) {
109
- const e = env || {};
110
- if (Object.prototype.hasOwnProperty.call(e, 'COLAB_SESSION')) return false;
111
- if (e.CLAUDECODE === '1' || e.AI_AGENT) return false;
112
- return true;
113
- }
114
-
115
- /**
116
- * The derived identity for a person (#528): `person:<who>/<hostToken>`, where `<who>` is git's
117
- * `user.email`, else the OS user. The host is the opaque `h:` token (`machine.hostToken`), never
118
- * the raw name: this value is written verbatim into claim comments, and a public tracker must not
119
- * learn a machine's name from it (#369). Stable across invocations — the same person on the same
120
- * machine always derives the same value, which is what a re-acquire needs. '' when no `<who>` or
121
- * no host is available: then nothing is derived and the blank-session paths apply unchanged.
122
- */
123
- function derivePersonSession({ email, user, hostToken } = {}) {
124
- const who = String(email || '').trim() || String(user || '').trim();
125
- const host = String(hostToken || '').trim();
126
- if (!who || !host || /\s/.test(who)) return '';
127
- return `person:${who}/${host}`;
128
- }
129
-
130
- /** Is `s` a derived person identity (#528)? */
131
- function isPersonSession(s) {
132
- return /^person:\S+$/.test(String(s == null ? '' : s).trim());
133
- }
134
-
135
98
  /**
136
99
  * Are `a` and `b` on the SAME machine (#327)? Both carry a `machine` → compare those (a raw id or
137
100
  * the `m:` digest a claim comment carries — `machineToken` makes the two comparable); raw ids of
@@ -226,5 +189,4 @@ module.exports = {
226
189
  DEFAULT_COMPONENTS, FINE_COMPONENTS,
227
190
  claimIdentityProblem, components, identityString, sameClaimant, mergeClaimRecord,
228
191
  looksLikeSessionId, isIntentSession, sameHost,
229
- shouldDerivePersonSession, derivePersonSession, isPersonSession,
230
192
  };
@@ -41,9 +41,7 @@ const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
41
41
  function looksLikeSessionId(v) {
42
42
  const s = String(v == null ? '' : v).trim();
43
43
  if (!s) return false;
44
- // #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
45
- // too — a stable join key, not a display name — so it reads back as one from a claim comment.
46
- return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s);
44
+ return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
47
45
  }
48
46
 
49
47
  /**
@@ -169,11 +169,6 @@
169
169
  * this entry, plus the matching `code-triage` verdict, is what makes those readings
170
170
  * reconcilable instead of silently contradictory.
171
171
  *
172
- * `priority:now` / `priority:high` joined the set in #537: the upward rank beside `low-priority`
173
- * (CONVENTIONS.md §5, *Priority*). Fixed values, not a prefix kind — they decode as plain
174
- * `convention` labels. Same malignant-absence reason: a rank only the owner may set must be
175
- * appliable the moment the owner says so, which a label the repo never created is not.
176
- *
177
172
  * `deferred:date` / `deferred:measurement` / `deferred:external-party` joined the set in
178
173
  * #279: `deps-checked` was being asked to carry two orthogonal facts at once — "has a
179
174
  * reasoning session evaluated this?" (process state, monotonic — the label's own
@@ -227,8 +222,6 @@ const CONVENTION_LABELS = [
227
222
  { name: 'needs-migration-grant', color: 'D4C5F9', description: 'Agent-flagged: deliverable is a schema migration; surfaces the grant request for a human to Accept' },
228
223
  { name: 'ci-granted', color: 'D73A4A', description: "A human granted this branch a one-shot exemption from ship's trunk-CI-green gate" },
229
224
  { name: 'low-priority', color: 'C2E0C6', description: 'Throttle, not a veto — startable, but code-triage ranks it behind every other ready group' },
230
- { name: 'priority:now', color: 'B60205', description: "Rank first among ready work — the owner's order; never skips a gate or overrides a file hold" },
231
- { name: 'priority:high', color: 'D93F0B', description: 'Rank ahead of default among ready work — owner or coordinator; never skips a gate' },
232
225
  { name: 'delivery:code', color: '1D76DB', description: 'Delivery is a code commit — the ordinary code pipeline applies' },
233
226
  { name: 'delivery:content', color: 'FEF2C0', description: 'Delivery is a content push, not a code commit — route, do not start in the code pipeline' },
234
227
  { name: 'delivery:ops', color: 'D4C5F9', description: 'Delivery is an ops/production check, not a code commit — route, do not start in the code pipeline' },
@@ -81,22 +81,6 @@
81
81
  "known": true
82
82
  }
83
83
  },
84
- {
85
- "wire": "priority:now",
86
- "decoded": {
87
- "kind": "convention",
88
- "value": "priority:now",
89
- "known": true
90
- }
91
- },
92
- {
93
- "wire": "priority:high",
94
- "decoded": {
95
- "kind": "convention",
96
- "value": "priority:high",
97
- "known": true
98
- }
99
- },
100
84
  {
101
85
  "wire": "release-hold",
102
86
  "decoded": {
@@ -81,18 +81,6 @@ function excludeLines(env = process.env) {
81
81
  return out;
82
82
  }
83
83
 
84
- /**
85
- * #527: the root-anchored exclude line for the worktree subdir (`colab worktree new` creates
86
- * worktrees INSIDE the clone, `.worktrees/` by default), or null when the configured subdir is
87
- * absolute or climbs out of the repo. Deliberately NOT part of `excludeLines`: those are scratch
88
- * (disposable, filtered out of the uncommitted-work gate by `isScratchPath`); a worktree is live
89
- * work and must never be filtered — it only has to stay out of the main checkout's `git status`,
90
- * where one habitual `git add -A` would otherwise commit it as an embedded-repo gitlink.
91
- */
92
- function worktreeExcludeLine(worktreeSubdir) {
93
- return anchoredLine(normalise(worktreeSubdir, '.worktrees'));
94
- }
95
-
96
84
  /**
97
85
  * Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
98
86
  * keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
@@ -114,5 +102,5 @@ function withoutScratch(porcelainText, env = process.env) {
114
102
  module.exports = {
115
103
  DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
116
104
  plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
117
- excludeLines, worktreeExcludeLine, isScratchPath, withoutScratch,
105
+ excludeLines, isScratchPath, withoutScratch,
118
106
  };
@@ -1,76 +0,0 @@
1
- 'use strict';
2
- /**
3
- * #525 — the human door on `colab ship`'s autonomy gate.
4
- *
5
- * Without `autonomy: auto-trunk` the gate used to have two answers: docs-only (#345) or refuse.
6
- * The refusal said "a human must trigger Phase B", but refused that human too, so on the default
7
- * (`manual`) repo the person meant to give the go had no tool to give it with. Ruling on #525
8
- * (option 1): a person running `colab ship` IS the go, measured on the bar the CLI already applies
9
- * to human-only acts (`colab adopt --autonomy`, `colab release finalize`):
10
- *
11
- * - an interactive terminal (stdin AND stdout a TTY) outside an agent shell, confirmed by typing
12
- * at the prompt — `how: 'tty'`; or
13
- * - `COLAB_HUMAN=1` AND `--answered-by <name>` — `how: 'colab-human'`.
14
- *
15
- * An agent never passes on its own: an agent shell (`CLAUDECODE=1` / `AI_AGENT`, the signals
16
- * `lib/place.js` already reads) does not count as a terminal, and setting `COLAB_HUMAN=1` is
17
- * governed by the handbook's existing rule — never on the agent's own say-so.
18
- *
19
- * Pure: every input is passed in, so the TTY branch is unit-testable without a pty.
20
- */
21
-
22
- /** Is this process running inside an agent's shell? Same signals as lib/place.js rule 3. */
23
- function isAgentShell(env) {
24
- return env.CLAUDECODE === '1' || !!env.AI_AGENT;
25
- }
26
-
27
- /**
28
- * @returns {{ open: boolean, how: 'tty'|'colab-human'|null, why: string }}
29
- */
30
- function humanDoorVerdict({ isTTY, colabHuman, answeredBy, agentShell }) {
31
- if (colabHuman && answeredBy) {
32
- return { open: true, how: 'colab-human', why: `COLAB_HUMAN=1, answered by ${answeredBy}` };
33
- }
34
- if (colabHuman && !answeredBy) {
35
- return { open: false, how: null, why: 'COLAB_HUMAN=1 also needs --answered-by "<name>"' };
36
- }
37
- if (isTTY && !agentShell) {
38
- return { open: true, how: 'tty', why: 'a person at an interactive terminal' };
39
- }
40
- if (isTTY && agentShell) {
41
- return { open: false, how: null, why: 'an agent shell is not a person at a terminal' };
42
- }
43
- return { open: false, how: null, why: 'unattended (no interactive terminal, no COLAB_HUMAN=1)' };
44
- }
45
-
46
- /** Read the door's inputs from a real process. */
47
- function humanDoorFromProcess(proc, answeredBy) {
48
- return humanDoorVerdict({
49
- isTTY: !!(proc.stdin.isTTY && proc.stdout.isTTY),
50
- colabHuman: proc.env.COLAB_HUMAN === '1',
51
- answeredBy: answeredBy || null,
52
- agentShell: isAgentShell(proc.env),
53
- });
54
- }
55
-
56
- /**
57
- * The exact commands a human runs, for the refusal. `target` is the ship selector the caller
58
- * used (`--worktree x`, `--branch y`, `--direct`), so the line can be pasted as it stands.
59
- */
60
- function humanDoorCommands(selector) {
61
- const sel = selector ? ` ${selector}` : '';
62
- return [
63
- `at your own terminal: colab ship${sel} (asks you to confirm)`,
64
- `or, non-interactive: COLAB_HUMAN=1 colab ship${sel} --answered-by "<your name>"`,
65
- ];
66
- }
67
-
68
- /** The clause the 🚢 / ✅ evidence comment carries when the human door opened the gate. */
69
- function humanDoorEvidence(door) {
70
- if (!door || !door.open) return '';
71
- return door.how === 'tty'
72
- ? ' · merged through the human door (#525): a person confirmed at an interactive terminal'
73
- : ` · merged through the human door (#525): ${door.why}`;
74
- }
75
-
76
- module.exports = { isAgentShell, humanDoorVerdict, humanDoorFromProcess, humanDoorCommands, humanDoorEvidence };