@futurelastic/colab-handbook 1.12.0-rc.52 → 1.12.0-rc.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.52"
30
+ "version": "1.12.0-rc.54"
31
31
  }
@@ -31,7 +31,7 @@ Starting points you **copy into your own repo**. That is the entire model.
31
31
  | `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
32
32
  | `gotchas-d-README.md` | `docs/gotchas.d/README.md` | Any repo starting a `docs/gotchas.d/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Naming rule (`<issue>-<slug>.md`) and the don't-copy-back rule against an existing `docs/gotchas.md`. Optional — writing the first gotcha entry does not require copying this in first. |
33
33
  | `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
34
- | `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.claude/plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
34
+ | `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
35
35
  | `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
36
36
  | `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
37
37
 
@@ -71,7 +71,7 @@
71
71
  // - a git-IGNORED markdown file is not part of the doc graph and is never
72
72
  // enumerated by any check. Scratch that never ships must not be able to
73
73
  // fail a structural check on the repo — and it was: `.claude/plans/
74
- // issue-<N>.md`, the git-excluded, `code-ship`-deleted plan file that
74
+ // issue-<N>.md` (since #488 `.plans/issue-<N>.md`), the git-excluded, `code-ship`-deleted plan file that
75
75
  // `code-start` writes, contributed 7 of one control run's 10 check-6
76
76
  // failures purely by quoting `§4` in prose, which made the repo lint clean
77
77
  // or dirty depending on who happened to have a session open
package/tools/colab CHANGED
@@ -47,6 +47,7 @@ const ciVerdict = require('./lib/ci-verdict');
47
47
  const baseCiVerdict = require('./lib/base-ci-verdict');
48
48
  const staleBase = require('./lib/stale-base');
49
49
  const dirtyOwner = require('./lib/dirty-owner');
50
+ const scratchDirs = require('./lib/scratch-dirs');
50
51
  const lockfileDrift = require('./lib/lockfile-drift');
51
52
  const adopt = require('./lib/adopt');
52
53
  const consumerEvidence = require('./lib/consumer-evidence');
@@ -5216,7 +5217,10 @@ function removeWorktreeDir(repoAbs, wtPath) {
5216
5217
  function uncommittedWork(wtPath) {
5217
5218
  if (!wtPath || !fs.existsSync(wtPath)) return { any: false, lines: '', what: '' };
5218
5219
  const tracked = git.dirtyTracked(wtPath);
5219
- const untracked = git.dirtyUntracked(wtPath);
5220
+ // #488: scratch (a plan or brief left in the worktree) is disposable by definition — it must never
5221
+ // be what makes a teardown refuse. Normally info/exclude already hides it; this covers a clone
5222
+ // whose exclude predates the scratch dirs, or a dir configured after the worktree was cut.
5223
+ const untracked = scratchDirs.withoutScratch(git.dirtyUntracked(wtPath));
5220
5224
  return {
5221
5225
  any: !!(tracked || untracked),
5222
5226
  lines: [tracked, untracked].filter(Boolean).join('\n'),
@@ -5491,6 +5495,10 @@ function cmdWorktreeNew(argv) {
5491
5495
  }
5492
5496
  settleTrackerPending(repoAbs, claimedHere.filter((n) => !lostIssues.includes(n)), trackerMissed, { wtName: name, branch });
5493
5497
 
5498
+ // #488: the scratch dirs (plans, briefs) are hidden in the clone's shared info/exclude — one
5499
+ // write covers the main checkout and every worktree, with no per-repo .gitignore diff.
5500
+ ensureScratchExcluded(repoAbs);
5501
+
5494
5502
  // 5. optional repo hook (machine-specific steps plug in here)
5495
5503
  const hook = runHook(repoAbs, 'post-create', { wtPath, name, branch, ports: alloc.chosenPorts, trunk, base, issues });
5496
5504
  if (hook.ran && !hook.ok) warn(`post-create hook exited ${hook.code} — worktree was still created; finish setup manually`);
@@ -7672,7 +7680,8 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
7672
7680
 
7673
7681
  1. refuses if .github/project.yml is TRACKED (then the repo is adopted — use plain adopt), if
7674
7682
  --trunk is missing, or if --trunk names the owner's own default branch;
7675
- 2. appends /.github/project.yml, /CLAUDE.local.md, /.claude/plans/ and the worktree subdir
7683
+ 2. appends /.github/project.yml, /CLAUDE.local.md, the scratch dirs (/.plans/, /.briefs/,
7684
+ legacy /.claude/plans/ — #488) and the worktree subdir
7676
7685
  (/.worktrees/ by default — the owner's .gitignore does not hide it) to .git/info/exclude (the
7677
7686
  shared common dir — never .gitignore, which is itself a tracked file) BEFORE writing, and
7678
7687
  keeps them even if a later check refuses (idempotent, local, hides nothing that exists);
@@ -7799,6 +7808,26 @@ function gitExcludePath(repoAbs) {
7799
7808
  return path.join(r.stdout, 'info', 'exclude');
7800
7809
  }
7801
7810
 
7811
+ /**
7812
+ * #488: append the scratch-dir exclude lines (scratch-dirs.js `excludeLines`) to the clone's shared
7813
+ * info/exclude, idempotently. Best-effort: a failure warns and never blocks the caller.
7814
+ */
7815
+ function ensureScratchExcluded(repoAbs) {
7816
+ const excludeFile = gitExcludePath(repoAbs);
7817
+ if (!excludeFile) return [];
7818
+ let before = null;
7819
+ try { before = fs.readFileSync(excludeFile, 'utf8'); } catch (_) { /* absent */ }
7820
+ const lines = scratchDirs.excludeLines();
7821
+ const missing = localAdopt.missingExcludeLines(before, lines);
7822
+ if (!missing.length) return [];
7823
+ try {
7824
+ fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
7825
+ const sep = before && !before.endsWith('\n') ? '\n' : '';
7826
+ fs.appendFileSync(excludeFile, sep + missing.join('\n') + '\n');
7827
+ } catch (e) { warn(`could not hide the scratch dirs in ${excludeFile}: ${e.message}`); return []; }
7828
+ return missing;
7829
+ }
7830
+
7802
7831
  function gitTracks(repoAbs, rel) {
7803
7832
  return git.git(['ls-files', '--error-unmatch', '--', rel], repoAbs).ok;
7804
7833
  }
@@ -11450,7 +11479,14 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
11450
11479
  }
11451
11480
 
11452
11481
  function shipJournalPlanFiles(repoAbs, issues) {
11453
- const plansDir = path.join(repoAbs, '.claude', 'plans');
11482
+ // #488: the configured plans dir first, then the legacy `.claude/plans/` — a plan written before
11483
+ // the switch is still journalled and deleted. One journal line per issue across both dirs: a
11484
+ // stray duplicate in the second dir is deleted without journalling the issue twice.
11485
+ const journalled = new Set();
11486
+ for (const plansDir of scratchDirs.planReadDirs(repoAbs)) shipJournalPlanDir(repoAbs, plansDir, issues, journalled);
11487
+ }
11488
+
11489
+ function shipJournalPlanDir(repoAbs, plansDir, issues, journalled) {
11454
11490
  let entries;
11455
11491
  try { entries = fs.readdirSync(plansDir); } catch (_) { return; } // no plans dir at all — nothing to do
11456
11492
  const issueSet = new Set(issues.map((n) => String(n)));
@@ -11467,13 +11503,17 @@ function shipJournalPlanFiles(repoAbs, issues) {
11467
11503
  const rm = txt.match(/^rung:\s*(.+)$/m); if (rm) rung = rm[1].trim();
11468
11504
  const cm = txt.match(/^cause:\s*(.+)$/m); if (cm) cause = cm[1].trim();
11469
11505
  } catch (_) { /* front matter is optional — the defaults above cover a plain rung-1 stub */ }
11470
- const lines = nums.map((num) => JSON.stringify({
11506
+ const fresh = nums.filter((num) => !journalled.has(num));
11507
+ const lines = fresh.map((num) => JSON.stringify({
11471
11508
  ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
11472
11509
  issue: Number(num), rung, cause, verdict: 'pass',
11473
- })).join('\n') + '\n';
11510
+ })).join('\n');
11474
11511
  try {
11475
- fs.mkdirSync(path.dirname(journalPath), { recursive: true });
11476
- fs.appendFileSync(journalPath, lines);
11512
+ if (lines) {
11513
+ fs.mkdirSync(path.dirname(journalPath), { recursive: true });
11514
+ fs.appendFileSync(journalPath, lines + '\n');
11515
+ }
11516
+ for (const num of fresh) journalled.add(num);
11477
11517
  fs.rmSync(planPath, { force: true }); // only after the journal write above landed
11478
11518
  } catch (e) {
11479
11519
  warnDeferred(`could not journal/delete the plan file "${name}" (${e.message}) — left in place`);
@@ -20,12 +20,16 @@
20
20
  * Everything here is pure (text in, text/verdict out); tools/colab does the IO.
21
21
  */
22
22
 
23
+ const scratchDirs = require('./scratch-dirs');
24
+
23
25
  /**
24
26
  * Paths hidden by `.git/info/exclude`, root-anchored (a leading `/`) so they match only at the
25
27
  * repo root — `CLAUDE.local.md` in a subdirectory the owner commits must stay visible.
26
- * `.claude/plans/` is the plan-file scratch dir code-start already excludes the same way.
28
+ * The session scratch dirs (plans, briefs — #488) are appended by `localExcludePaths` from
29
+ * scratch-dirs.js, so a configured COLAB_PLANS_DIR / COLAB_BRIEFS_DIR is hidden too; the legacy
30
+ * `.claude/plans/` stays among them.
27
31
  */
28
- const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.claude/plans/'];
32
+ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'];
29
33
 
30
34
  /**
31
35
  * LOCAL_EXCLUDE_PATHS plus the worktree subdir (`colab worktree new` creates worktrees INSIDE the
@@ -33,9 +37,9 @@ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.clau
33
37
  * `.gitignore`; the owner's repo does not, so without this line every worktree shows up in the
34
38
  * main checkout's `git status` — measured on the #393 fixture the moment the first one was cut.
35
39
  */
36
- function localExcludePaths(worktreeSubdir) {
40
+ function localExcludePaths(worktreeSubdir, env = process.env) {
37
41
  const sub = String(worktreeSubdir || '.worktrees').replace(/^\/+|\/+$/g, '');
38
- return [...LOCAL_EXCLUDE_PATHS, `/${sub}/`];
42
+ return [...LOCAL_EXCLUDE_PATHS, ...scratchDirs.excludeLines(env), `/${sub}/`];
39
43
  }
40
44
 
41
45
  const EXCLUDE_HEADER = '# colab-handbook: local-only adoption (#393) — handbook files this clone keeps out of the owner\'s history';
@@ -0,0 +1,106 @@
1
+ 'use strict';
2
+ /**
3
+ * #488: where a session's scratch lives — the plan file (`code-start` / `code-plan` write it,
4
+ * `code-wrap` / `code-ship` read and delete it) and dispatch briefs.
5
+ *
6
+ * Both used to be literals under `.claude/` (`.claude/plans/`, `.claude/briefs/`). The agent CLI
7
+ * guards `.claude/` as configuration, so every scratch write there could cost the operator a
8
+ * permission prompt — for a file that is disposable by definition. Defaults now sit outside it:
9
+ *
10
+ * plans `<main checkout>/.plans/` overridable by COLAB_PLANS_DIR
11
+ * briefs `<main checkout>/.briefs/` overridable by COLAB_BRIEFS_DIR
12
+ *
13
+ * A configured value is relative to the repo root, or absolute. Writers use ONLY the configured
14
+ * dir. Readers use the configured dir first, then the legacy `.claude/plans/` — one transition,
15
+ * so a plan written before the switch is still graded, journalled and deleted. Old files are never
16
+ * moved.
17
+ *
18
+ * Everything here is pure (env + strings in, strings out); tools/colab does the IO.
19
+ */
20
+
21
+ const path = require('path');
22
+
23
+ const DEFAULT_PLANS_DIR = '.plans';
24
+ const DEFAULT_BRIEFS_DIR = '.briefs';
25
+ /** Read-only fallbacks for the transition (#488). Never written to by anything that follows #488. */
26
+ const LEGACY_PLANS_DIR = '.claude/plans';
27
+ const LEGACY_BRIEFS_DIR = '.claude/briefs';
28
+
29
+ /** A configured dir, normalised: trimmed, forward slashes, no trailing slash; blank → the default. */
30
+ function normalise(value, dflt) {
31
+ const v = String(value === undefined || value === null ? '' : value).trim().replace(/\\/g, '/');
32
+ if (!v) return dflt;
33
+ if (v === '/') return dflt; // the filesystem root is never a scratch dir — treat as unset
34
+ return v.replace(/\/+$/, '') || dflt;
35
+ }
36
+
37
+ /** The plans dir as configured — relative to the repo root unless absolute. */
38
+ function plansDirSetting(env = process.env) { return normalise(env.COLAB_PLANS_DIR, DEFAULT_PLANS_DIR); }
39
+ /** The briefs dir as configured — relative to the repo root unless absolute. */
40
+ function briefsDirSetting(env = process.env) { return normalise(env.COLAB_BRIEFS_DIR, DEFAULT_BRIEFS_DIR); }
41
+
42
+ function resolveIn(repoRoot, rel) { return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel); }
43
+
44
+ /** Absolute dir a writer puts a plan file in. Never the legacy dir (unless configured to it). */
45
+ function planWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, plansDirSetting(env)); }
46
+
47
+ /** Absolute dir a writer puts a brief in. */
48
+ function briefsWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, briefsDirSetting(env)); }
49
+
50
+ /** Absolute dirs a reader looks in, in order: configured first, then legacy. Deduplicated. */
51
+ function planReadDirs(repoRoot, env = process.env) {
52
+ const out = [];
53
+ for (const d of [planWriteDir(repoRoot, env), resolveIn(repoRoot, LEGACY_PLANS_DIR)]) {
54
+ if (!out.includes(d)) out.push(d);
55
+ }
56
+ return out;
57
+ }
58
+
59
+ /**
60
+ * A configured dir that is relative and stays inside the repo, as a root-anchored exclude line
61
+ * (`/.plans/`) — or null for an absolute dir or one that climbs out (`../x`), which no repo-local
62
+ * ignore file can or needs to hide.
63
+ */
64
+ function anchoredLine(rel) {
65
+ if (path.isAbsolute(rel)) return null;
66
+ const n = path.posix.normalize(rel);
67
+ if (n === '.' || n.startsWith('../') || n === '..') return null;
68
+ return `/${n.replace(/^\.\//, '')}/`;
69
+ }
70
+
71
+ /**
72
+ * Root-anchored `.git/info/exclude` lines for every scratch dir — configured plans, configured
73
+ * briefs, and the legacy `.claude/plans/` (kept: a clone may still hold pre-#488 files).
74
+ */
75
+ function excludeLines(env = process.env) {
76
+ const out = [];
77
+ for (const rel of [plansDirSetting(env), briefsDirSetting(env), LEGACY_PLANS_DIR]) {
78
+ const line = anchoredLine(rel);
79
+ if (line && !out.includes(line)) out.push(line);
80
+ }
81
+ return out;
82
+ }
83
+
84
+ /**
85
+ * Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
86
+ * keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
87
+ * by definition, and must never be what makes a teardown refuse (#488).
88
+ */
89
+ function isScratchPath(relPath, env = process.env) {
90
+ const p = String(relPath || '').replace(/^"|"$/g, '').replace(/\\/g, '/').replace(/^\.\//, '');
91
+ return excludeLines(env).some((line) => p.startsWith(line.slice(1)));
92
+ }
93
+
94
+ /** Drop porcelain lines (`?? path`, ` M path`) whose path is scratch. Text in, text out. */
95
+ function withoutScratch(porcelainText, env = process.env) {
96
+ if (!porcelainText) return porcelainText;
97
+ return String(porcelainText).split('\n')
98
+ .filter((l) => l && !isScratchPath(l.slice(3), env))
99
+ .join('\n');
100
+ }
101
+
102
+ module.exports = {
103
+ DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
104
+ plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
105
+ excludeLines, isScratchPath, withoutScratch,
106
+ };