@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11

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 (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. package/bin/cli.js +0 -3
@@ -0,0 +1,740 @@
1
+ 'use strict';
2
+ /**
3
+ * Stamp + drift logic, shared by `audit/audit.mjs` (report) and `colab update` (report + refresh).
4
+ *
5
+ * Copy-and-own means nothing is pushed to an adopter: a copied artifact carries a STAMP naming
6
+ * the template and the handbook version it came from, and drift is discovered by comparing that
7
+ * stamp against the handbook's own git history. Both tools must read stamps identically — a
8
+ * second implementation that disagreed about what "behind" means is exactly the two-places-drift
9
+ * disease this handbook exists to kill, so the reading lives here once.
10
+ *
11
+ * CommonJS on purpose: `tools/colab` is CJS, `audit/audit.mjs` is ESM. CJS is the format both can
12
+ * consume (the audit pulls it in through `createRequire`); the reverse is not true from a
13
+ * synchronous CLI.
14
+ *
15
+ * Every function takes the handbook root explicitly rather than resolving it — the two callers
16
+ * locate the handbook differently (the audit honours COLAB_HANDBOOK; the CLI walks up from its
17
+ * own file), and a module that guessed would be wrong for one of them.
18
+ */
19
+
20
+ const { execFileSync } = require('child_process');
21
+ const releaseTag = require('./release-tag.js');
22
+
23
+ // The artifact kinds that carry a stamp. Workflow copies are WHOLE-FILE copies, so a pristine one
24
+ // can be regenerated byte-for-byte. The CLAUDE block is a fragment pasted into a larger file whose
25
+ // placeholders the adopter fills in — see CLAUDE_BLOCK below.
26
+ const CLAUDE_BLOCK_TEMPLATE = 'templates/repo-CLAUDE-block.md';
27
+
28
+ // The FROZEN CLI copy: `install.sh --tools` copies `tools/colab` + `tools/lib/` into
29
+ // `<COLAB_HOME>/bin/` and writes the stamp beside it, so a long-lived process never resolves the
30
+ // CLI through a working tree. The symlink install (`~/.local/bin/colab`) is deliberately the
31
+ // opposite — a human session should follow whatever branch the handbook clone has checked out —
32
+ // but an always-on service must not change behaviour because somebody checked out an unrelated
33
+ // branch. Refreshing the frozen copy is therefore an act (re-run install.sh), never a side effect.
34
+ //
35
+ // The stamp is a SIDECAR file rather than a line prepended into the script: `colab` is executable
36
+ // with a shebang on line 1, and the sidecar keeps the copied bytes identical to the source.
37
+ // It uses the ordinary workflow stamp convention (`# colab-handbook: <name> @ <version>`) and is
38
+ // read with parseWorkflowStamp, so there is one stamp format on the machine, not two.
39
+ const FROZEN_STAMP_NAME = 'colab-bin';
40
+ const FROZEN_STAMP_FILE = 'STAMP';
41
+
42
+ /**
43
+ * The handbook version at/after which #144's authority-flip advisory activates: a `warn`,
44
+ * on a repo whose axis of record is a LEGACY `tier` read (no `exposure` declared), noting
45
+ * that `tier` is now read as legacy rather than authoritative. Dormant below this version,
46
+ * mirroring the `hb.untagged` precedent `compareStamp` already uses (deactivated while there
47
+ * is no real version line to compare against) — the re-keying itself is NOT gated by it (it
48
+ * is designed to be output-identical on every descriptor without `exposure` regardless of
49
+ * handbook version; only this one new warn is).
50
+ *
51
+ * No tag exists past the axis commits yet (#200, a human act, still pending) — the handbook
52
+ * is expected to cut a MINOR tag containing #144 next (keeping `v1.x`, so the fleet gets a
53
+ * clean baseline first), and only a LATER, separate major bump would ever reach this
54
+ * constant. Comparison uses `cmpSemver`, so a same-or-later `v2.x.y` also arms it.
55
+ */
56
+ const AUTHORITY_FLIP_VERSION = 'v2.0.0';
57
+ // What the frozen copy is made of, as repo-relative paths — the same role `templateFiles()` plays
58
+ // for a template, and fed to the same `git log <stamp>..HEAD -- <paths>` question.
59
+ // Every path install.sh's freeze_cli COPIES belongs here: a source it copies but this list omits can
60
+ // change without ever marking a frozen copy behind. tools/package.json was exactly that gap (#341) —
61
+ // an `engines` bump shipped to no machine. tools/lib/install-sh.test.js holds the two lists together.
62
+ const FROZEN_SOURCES = ['tools/colab', 'tools/lib', 'tools/package.json'];
63
+
64
+ // ---------------------------------------------------------------------------
65
+ // git access to the handbook checkout
66
+ // ---------------------------------------------------------------------------
67
+
68
+ function gitIn(root, args) {
69
+ try {
70
+ return {
71
+ ok: true,
72
+ out: execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
73
+ };
74
+ } catch (_) {
75
+ return { ok: false, out: '' };
76
+ }
77
+ }
78
+
79
+ /** `version` of `<root>/package.json` when this root is a published package (not a git checkout), else null. */
80
+ function packageVersion(root) {
81
+ try {
82
+ const j = JSON.parse(require('fs').readFileSync(require('path').join(root, 'package.json'), 'utf8'));
83
+ return typeof j.version === 'string' && /^\d+\.\d+\.\d+$/.test(j.version) ? j.version : null;
84
+ } catch (_) {
85
+ return null;
86
+ }
87
+ }
88
+
89
+ /** The npm name this CLI publishes under — must equal the root package.json's `name` (a test pins it). */
90
+ const PACKAGE_NAME = '@futurelastic/colab-handbook';
91
+
92
+ /** True when `root` is its own git checkout — the toplevel git finds IS `root`, not an enclosing repo. */
93
+ function ownsGit(root) {
94
+ const top = gitIn(root, ['rev-parse', '--show-toplevel']);
95
+ return top.ok && realPath(top.out) === realPath(require('path').resolve(root));
96
+ }
97
+
98
+ /**
99
+ * `{ root, version }` when `root` is THIS CLI installed from the npm registry, else null (#444).
100
+ *
101
+ * Three conditions, all required:
102
+ * - no git of its own (an enclosing repo does not count — see handbookInfo);
103
+ * - `<root>/package.json` names this package, so an unrelated package.json never qualifies;
104
+ * - `root` sits under a `node_modules/` directory. Without this, a handbook working tree that is
105
+ * file-synced to another machine with its `.git` deliberately left behind would pass the first
106
+ * two and be reported as a registry install. npx, `npm i` and `npm i -g` all install there.
107
+ *
108
+ * `version` is package.json's verbatim — a candidate's `1.12.0-rc.8` included. That is the point:
109
+ * this answers "which build is running", where handbookInfo answers "what may I stamp with", and a
110
+ * candidate is never the latter (#334) — so its stricter packageVersion is right for it, wrong here.
111
+ */
112
+ function npmPackageInfo(root) {
113
+ const p = require('path');
114
+ if (!p.resolve(root).split(p.sep).includes('node_modules')) return null;
115
+ let j;
116
+ try {
117
+ j = JSON.parse(require('fs').readFileSync(p.join(root, 'package.json'), 'utf8'));
118
+ } catch (_) {
119
+ return null;
120
+ }
121
+ if (!j || j.name !== PACKAGE_NAME || typeof j.version !== 'string' || !j.version) return null;
122
+ if (ownsGit(root)) return null;
123
+ return { root, version: j.version };
124
+ }
125
+
126
+ /**
127
+ * The handbook's own identity: { root, hasGit, untagged, version }.
128
+ * Before the first tag exists the version is 'v0' and `untagged` is true, which DEACTIVATES stamp
129
+ * comparison in both callers — there is no real version line to compare against, and inventing one
130
+ * would mark every adopter stale against a version that never shipped.
131
+ *
132
+ * `git -C <root> rev-parse --show-toplevel` does not fail when `root` itself has no `.git` — it
133
+ * walks UP and answers about the nearest ENCLOSING repository. So a root that is not itself a repo
134
+ * still returns `ok`, and treating success alone as "hasGit: true" reports the wrong repo's tags
135
+ * with no error and no advisory (root is a subdirectory that legitimately has no `.git` of its own
136
+ * — e.g. working trees file-synced between machines while git metadata deliberately is not, nested
137
+ * inside a parent that IS a repo). The fix is the comparison this function was missing: the
138
+ * toplevel git actually found must equal `root` itself, not merely exist. realPath both sides —
139
+ * `--show-toplevel` resolves symlinks, so a symlinked root would otherwise never match its own
140
+ * unresolved spelling (same reasoning as `realPath` above, applied here for the same failure mode).
141
+ */
142
+ function handbookInfo(root) {
143
+ const top = gitIn(root, ['rev-parse', '--show-toplevel']);
144
+ if (!top.ok || realPath(top.out) !== realPath(require('path').resolve(root))) {
145
+ // An npm install (#431) has no git of its own: the registry copy's version is its package.json,
146
+ // which the publish job stamps from the release tag. Without this a copy installed from the
147
+ // registry would stamp every adopter's files `v0`.
148
+ const pkgVersion = packageVersion(root);
149
+ if (pkgVersion) return { root, hasGit: false, untagged: false, version: `v${pkgVersion}` };
150
+ return { root, hasGit: false, untagged: true, version: 'v0' };
151
+ }
152
+ // Pre-release tags are not a version (#334): a candidate must never become what adopters are
153
+ // compared against or stamped with. Only candidates, no final yet, reads as untagged.
154
+ const tag = releaseTag.latestReleaseTag(root);
155
+ if (!tag) return { root, hasGit: true, untagged: true, version: 'v0' };
156
+ return { root, hasGit: true, untagged: false, version: tag };
157
+ }
158
+
159
+ /**
160
+ * What to stamp a frozen copy WITH: { version, tag, exact, untagged }.
161
+ *
162
+ * A frozen copy is bytes taken from a working tree, and when that tree is ahead of the last tag no
163
+ * version honestly describes it. Stamping the bare tag overstates what the copy contains — it
164
+ * silently claims to be a release it is newer than. So `version` is `git describe --tags` (pre-release
165
+ * tags excluded — release-tag.js, #334), which
166
+ * is the bare tag when HEAD sits exactly on one (`v1.6.1`, the common case, unchanged) and the long
167
+ * form when it does not (`v1.6.1-14-gc8436c6`).
168
+ *
169
+ * The long form is not a cosmetic label — it is chosen because it stays correct everywhere the
170
+ * stamp is already consumed, with no second format on the machine:
171
+ * - parseWorkflowStamp's version pattern accepts it;
172
+ * - cmpSemver reads it as its tag (trailing junk parses to 0), so it never trips the "stamp is
173
+ * NEWER than the handbook" branch against its own tag;
174
+ * - `git rev-parse` resolves it, so classifyFrozen can use it as a lower bound directly — which
175
+ * makes the comparison EXACT rather than merely honest: a copy frozen mid-cycle is measured
176
+ * from the commit it was actually taken from, so the next release marks it behind only for the
177
+ * commits it genuinely lacks.
178
+ *
179
+ * Dirty trees are deliberately NOT described (`--dirty` would produce a ref nothing can resolve,
180
+ * turning every such copy into `n-a` with misleading "fetch tags" advice). Uncommitted work in a
181
+ * frozen copy stays outside this model.
182
+ */
183
+ function freezeVersion(root) {
184
+ const hb = handbookInfo(root);
185
+ if (hb.untagged || !hb.hasGit) return { version: 'v0', tag: 'v0', exact: false, untagged: true };
186
+ // Long form measured from the last FINAL tag (#334) — a tree sitting on `v1.3.0-rc.1` stamps
187
+ // `v1.2.0-N-g<sha>`, never the candidate.
188
+ const d = gitIn(root, releaseTag.describeArgs({ abbrev: null }));
189
+ const version = d.ok && d.out ? d.out : hb.version;
190
+ return { version, tag: hb.version, exact: version === hb.version, untagged: false };
191
+ }
192
+
193
+ /**
194
+ * The handbook's shared git directory — the one identity that survives worktrees. Every worktree
195
+ * of a repo reports the SAME `--git-common-dir`, while their working-tree paths all differ.
196
+ */
197
+ function gitCommonDir(root) {
198
+ const r = gitIn(root, ['rev-parse', '--git-common-dir']);
199
+ if (!r.ok || !r.out) return null;
200
+ return realPath(require('path').resolve(root, r.out));
201
+ }
202
+
203
+ /**
204
+ * Resolve symlinks before comparing paths, falling back to the input when the path does not exist.
205
+ *
206
+ * Not optional pedantry: git answers `--git-common-dir` RELATIVELY from a main checkout (`.git`)
207
+ * but ABSOLUTELY, and already symlink-resolved, from a worktree. So the two sides of the comparison
208
+ * arrive in different forms, and any handbook checkout reached through a symlinked path (`/tmp` on
209
+ * macOS, a symlinked home, a network mount) produced two different strings for one directory —
210
+ * making the repo fail to recognise itself.
211
+ */
212
+ function realPath(p) {
213
+ try { return require('fs').realpathSync(p); } catch (_) { return p; }
214
+ }
215
+
216
+ /**
217
+ * Is `repoPath` the handbook itself? Both tools must answer this identically, so it is answered
218
+ * ONCE, here — the same reason stamp reading lives here.
219
+ *
220
+ * NOT a path-string comparison, and that is the whole point. `colab update` used to test
221
+ * `abs === handbookRoot`, which silently answers "no" whenever the CLI runs from a git WORKTREE of
222
+ * the handbook: the CLI locates its root by walking up from its own file (giving the worktree),
223
+ * while the fleet registry names the main checkout. Same repo, two spellings, and the handbook was
224
+ * audited as its own consumer — reported `unstamped`, with advice to stamp its own CLAUDE.md as a
225
+ * copy of a version of itself. Comparing git common dirs is immune to that: worktree, symlink or
226
+ * a differently-spelled path all resolve to one identity.
227
+ *
228
+ * Remote (owner/name) targets are out of scope: recognising "self" through the API would need the
229
+ * name match this deliberately avoids.
230
+ */
231
+ function isHandbookItself(repoPath, handbookRoot) {
232
+ const { resolve } = require('path');
233
+ if (!repoPath || !handbookRoot) return false;
234
+ const root = realPath(resolve(repoPath));
235
+ if (root === realPath(resolve(handbookRoot))) return true;
236
+ const a = gitCommonDir(root);
237
+ const b = gitCommonDir(handbookRoot);
238
+ return a !== null && b !== null && a === b;
239
+ }
240
+
241
+ /** Template stems present in the handbook (e.g. "ci-node", "ci-laravel", "release-tag"). */
242
+ function templateNames(root) {
243
+ const { readdirSync } = require('fs');
244
+ const { join } = require('path');
245
+ try {
246
+ return new Set(
247
+ readdirSync(join(root, 'templates'))
248
+ .filter((f) => /\.ya?ml$/.test(f))
249
+ .map((f) => f.replace(/\.ya?ml$/, '')),
250
+ );
251
+ } catch (_) {
252
+ return new Set();
253
+ }
254
+ }
255
+
256
+ /** Both spellings a template file may use, as repo-relative paths for `git log`/`git show`. */
257
+ function templateFiles(name) {
258
+ return [`templates/${name}.yml`, `templates/${name}.yaml`];
259
+ }
260
+
261
+ // The trailer key a handbook editor writes on a commit to declare — at edit time, never
262
+ // inferred afterward — that a template change carries no rule content (#272). One key,
263
+ // one truthy spelling; keep this narrow so a reader never has to guess what counts.
264
+ const RULE_NEUTRAL_TRAILER = 'Rule-Neutral';
265
+ const RULE_NEUTRAL_TRUE = /^(yes|true)$/i;
266
+
267
+ /**
268
+ * Is every commit that touched `files` in `sinceRef..untilRef` marked with the
269
+ * Rule-Neutral trailer? Empty range (nothing changed) reads as false — callers only ask
270
+ * this after confirming `changed`, and "no commits" is not the same claim as "all
271
+ * commits declared neutral".
272
+ *
273
+ * Uses `\x1f`/`\x1e` as field/record separators, not the trailer text itself, because
274
+ * `%(trailers:valueonly)` renders empty for a commit with no trailer — a plain newline
275
+ * join cannot tell "no trailer" apart from "trailer, empty value" from the commit count.
276
+ */
277
+ function allCommitsRuleNeutral(root, files, sinceRef, untilRef) {
278
+ const fmt = `%H\x1f%(trailers:key=${RULE_NEUTRAL_TRAILER},valueonly,separator=%x2C)\x1e`;
279
+ const r = gitIn(root, ['log', `--format=${fmt}`, `${sinceRef}..${untilRef}`, '--', ...files]);
280
+ if (!r.ok || !r.out) return false;
281
+ const records = r.out.split('\x1e').map((s) => s.trim()).filter(Boolean);
282
+ if (records.length === 0) return false;
283
+ return records.every((rec) => {
284
+ const value = rec.split('\x1f')[1] || '';
285
+ return RULE_NEUTRAL_TRUE.test(value.trim());
286
+ });
287
+ }
288
+
289
+ /**
290
+ * Did any of the given files change between the stamped version and `untilRef` (default HEAD)?
291
+ * Returns { verifiable, changed, ruleNeutral }. verifiable=false when either ref does not
292
+ * resolve in this checkout (a tag we do not have) — reported, never guessed. `ruleNeutral` is
293
+ * only ever true alongside `changed: true` — see `allCommitsRuleNeutral` above (#272): a
294
+ * template stays a hard fail unless EVERY commit since the stamp was deliberately declared
295
+ * rule-neutral by whoever wrote it, never by comparing before/after content here.
296
+ *
297
+ * This is the check that keeps releases quiet: comparing version STRINGS would mark every adopter
298
+ * stale on every handbook release, including releases that touched nothing they copied.
299
+ *
300
+ * `untilRef` exists because the two callers are asking about different UNITS. A template copy is
301
+ * compared against HEAD: the adopter refreshes from the working tree, so the working tree is the
302
+ * thing they can actually get. The frozen CLI copy is compared against the latest TAG — see
303
+ * classifyFrozen for why measuring it to HEAD made every maintainer's machine permanently stale.
304
+ */
305
+ function templateChangedSince(root, files, sinceRef, untilRef = 'HEAD') {
306
+ const resolves = (ref) => gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
307
+ if (!resolves(sinceRef) || !resolves(untilRef)) return { verifiable: false, changed: false, ruleNeutral: false };
308
+ const log = gitIn(root, ['log', '--oneline', `${sinceRef}..${untilRef}`, '--', ...files]);
309
+ const changed = log.ok && log.out.length > 0;
310
+ const ruleNeutral = changed && allCommitsRuleNeutral(root, files, sinceRef, untilRef);
311
+ return { verifiable: true, changed, ruleNeutral };
312
+ }
313
+
314
+ /**
315
+ * A template's content AS OF a given ref (`git show <ref>:templates/<name>.yml`), or null.
316
+ * Divergence detection stands entirely on this: to know whether a copy was hand-edited you must
317
+ * compare it against what it was copied FROM, not against what the template has since become.
318
+ * Comparing against the current template would call every out-of-date copy "hand-edited".
319
+ */
320
+ function templateAt(root, ref, name) {
321
+ for (const f of templateFiles(name)) {
322
+ const r = gitIn(root, ['show', `${ref}:${f}`]);
323
+ if (r.ok) return r.out;
324
+ }
325
+ return null;
326
+ }
327
+
328
+ // The descriptor axes that entered the model after the original tier/trunk/deploy/production/
329
+ // stack fields — each one is a heading in project.schema.md, added the commit it landed.
330
+ const AXES = ['room', 'exposure', 'writes', 'channels'];
331
+
332
+ /**
333
+ * Which of AXES did NOT yet exist in project.schema.md as of `ref` — i.e. which axes this
334
+ * repo's marker predates, if its CLAUDE stamp names `ref` as the handbook version it was last
335
+ * synced against. Reuses the same stamp-comparison shape as templateChangedSince/templateAt:
336
+ * read the schema doc's content AT THAT REF, never at HEAD, because "predates" is a question
337
+ * about what existed at adoption time, not about what the handbook has since become.
338
+ *
339
+ * `verifiable: false` — same posture as an unresolvable stamp elsewhere in this module — means
340
+ * the ref cannot be read at all (an unfetched tag, a version string that isn't a real ref). The
341
+ * caller must stay SILENT in that case, not guess; a repo whose stamp names a ref this checkout
342
+ * cannot resolve is exactly the "look, don't assume" case the rest of the fleet already treats
343
+ * as unknown rather than as broken.
344
+ *
345
+ * A ref that resolves but predates project.schema.md entirely (the file did not exist yet) is
346
+ * read as "every axis is missing" — `git show` fails per-heading-check below, which already
347
+ * degrades to "not found" correctly with no extra branch.
348
+ */
349
+ function axesPredating(root, ref) {
350
+ const resolves = gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
351
+ if (!resolves) return { verifiable: false, axes: [] };
352
+ const schema = gitIn(root, ['show', `${ref}:project.schema.md`]);
353
+ const text = schema.ok ? schema.out : '';
354
+ const missing = AXES.filter((axis) => !new RegExp('^###\\s+`' + axis + '`', 'm').test(text));
355
+ return { verifiable: true, axes: missing };
356
+ }
357
+
358
+ // The ruling's own landed vocabulary (project.schema.md, "writes — optional", and
359
+ // CONVENTIONS.md, "Writes"), used as the boundary marker below rather than a hand-picked
360
+ // version number. Distinct from a structural heading (what AXES/axesPredating match) because
361
+ // the `writes` heading itself did not change — only what is written under it did.
362
+ const WRITES_VETO_MARKER = 'two-state VETO';
363
+
364
+ /**
365
+ * #239: did a repo's marker already tell it what ⚖ #233 changed about `writes:`? Same
366
+ * stamp-comparison shape as axesPredating one function above — read project.schema.md AS OF
367
+ * the repo's OWN stamped ref, never at HEAD, because this asks what a sync at THAT time could
368
+ * have told the repo, not what the handbook has since become.
369
+ *
370
+ * Deliberately gated on the ruling's own arrival (`WRITES_VETO_MARKER`'s presence at `ref`),
371
+ * not a version threshold: unlike `AUTHORITY_FLIP_VERSION` near the top of this file — which
372
+ * exists BECAUSE that advisory wanted to wait for a later, separate major bump — #239's own
373
+ * text says this must not be deferred past the very next tag that carries #237. Reading for
374
+ * the change's own landed text sidesteps having to invent a version number for a tag nobody
375
+ * has cut yet (who tags follows CONVENTIONS §6's release rung).
376
+ *
377
+ * `verifiable: false` on the same terms as axesPredating: an unresolvable ref means stay
378
+ * silent, never guess.
379
+ */
380
+ function writesRulingKnownAt(root, ref) {
381
+ const resolves = gitIn(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']).ok;
382
+ if (!resolves) return { verifiable: false, known: false };
383
+ const schema = gitIn(root, ['show', `${ref}:project.schema.md`]);
384
+ const text = schema.ok ? schema.out : '';
385
+ return { verifiable: true, known: text.includes(WRITES_VETO_MARKER) };
386
+ }
387
+
388
+ // ---------------------------------------------------------------------------
389
+ // stamps
390
+ // ---------------------------------------------------------------------------
391
+
392
+ /**
393
+ * Which comment syntax a stamp line should use, chosen by the copied file's language — not a
394
+ * single fixed spelling. `#` works for YAML and shell (the original, and still the default for
395
+ * backward compatibility). A `.mjs`/`.js` copy cannot use it: a bare `#` on any line but a `#!`
396
+ * shebang is a JS syntax error (outside a class body, where it means something else entirely), so
397
+ * a stamped JS file needs `//` or it would break the very file it is stamping (#252).
398
+ */
399
+ function stampCommentPrefix(ext) {
400
+ return ext === 'mjs' || ext === 'js' ? '//' : '#';
401
+ }
402
+
403
+ /** The canonical workflow stamp line. `colab template` writes it; `colab update` rewrites it.
404
+ * `commentPrefix` defaults to `#` (unchanged behaviour for every existing *.yml caller) — pass
405
+ * the value from `stampCommentPrefix(ext)` for a non-YAML template. */
406
+ function stampLine(name, version, commentPrefix = '#') {
407
+ return `${commentPrefix} colab-handbook: ${name} @ ${version}\n`;
408
+ }
409
+
410
+ /**
411
+ * Insert a stamp line into a copied template's body.
412
+ *
413
+ * A `*.yml` copy has always taken the stamp prepended at the very top (line 1) — unchanged here.
414
+ * A copy that opens with a `#!` shebang cannot take that: prepending anything above line 1 breaks
415
+ * the shebang, which is exactly the gap `templates/README.md`'s Hooks section documents (#252).
416
+ * So a shebang file gets the stamp on its SECOND line instead — after the first `\n`, shebang
417
+ * intact on line 1 — and everything else is prepended as before.
418
+ */
419
+ function insertStamp(body, line) {
420
+ if (body.startsWith('#!')) {
421
+ const nl = body.indexOf('\n');
422
+ if (nl === -1) return body + '\n' + line; // shebang with no trailing newline — still safe
423
+ return body.slice(0, nl + 1) + line + body.slice(nl + 1);
424
+ }
425
+ return line + body;
426
+ }
427
+
428
+ /** Workflow stamp: `# colab-handbook: <name> @ <version>` or, for a shebang/JS copy, the same
429
+ * shape with `//` (see stampCommentPrefix) — either prefix is accepted wherever it appears in the
430
+ * file, not just on line 1, so a second-line stamp reads back identically to a first-line one. */
431
+ function parseWorkflowStamp(text) {
432
+ if (!text) return null;
433
+ const m = text.match(/(?:#|\/\/)\s*colab-handbook:\s*([A-Za-z0-9._-]+)\s*@\s*(v?[0-9][0-9A-Za-z.\-+]*)/);
434
+ return m ? { name: m[1], version: m[2] } : null;
435
+ }
436
+
437
+ /** CLAUDE-block stamp: `<!-- colab-handbook @ <version> -->`. */
438
+ function parseClaudeStamp(text) {
439
+ if (!text) return null;
440
+ const m = text.match(/<!--\s*colab-handbook\s*@\s*(v?[0-9][0-9A-Za-z.\-+]*)\s*-->/);
441
+ return m ? { version: m[1] } : null;
442
+ }
443
+
444
+ /**
445
+ * Content fingerprints that mark a workflow as a handbook derivative even when someone renamed the
446
+ * file or dropped the stamp.
447
+ *
448
+ * THE ADMISSION TEST, and it is the whole design: *could this string appear in a file nobody copied
449
+ * from us?* If yes, it is not a fingerprint — it is the STACK'S VOCABULARY, and matching on it
450
+ * accuses every repo that happens to use that stack. We shipped two such strings and both misfired
451
+ * on real repos:
452
+ *
453
+ * - `wayfinder:generate` — a framework command, not our text. ANY workflow doing build-time
454
+ * codegen on that framework contains it, whatever its origin. It flagged three hand-written
455
+ * deploy workflows that had never been near a template.
456
+ * - `gitleaks/gitleaks/releases/download` — the upstream release URL. It identifies gitleaks,
457
+ * not us. Two hand-written CI files on this fleet contain it (including this handbook's own),
458
+ * copied from each other rather than from `templates/`.
459
+ *
460
+ * What survives is text WE COINED: the step names in our templates. No upstream tool, framework or
461
+ * generator emits "Resolve toolchain versions"; a file containing it was typed by us or copied from
462
+ * something that was. Each entry is therefore matched as a STEP NAME (`- name: <marker>`), not as a
463
+ * loose substring — so prose that merely mentions the phrase (a comment, a README, this file) does
464
+ * not trip it.
465
+ *
466
+ * `template` attributes the evidence, which is what lets the advice name a real template instead of
467
+ * a `<name>` placeholder the reader has to guess. `null` means the marker is shared by several
468
+ * templates: it still proves derivation, but not FROM WHICH — and the advice must then say so
469
+ * rather than pick one.
470
+ *
471
+ * Precise on purpose: better to miss an unstamped copy than to nag a file we cannot attribute.
472
+ */
473
+ const WORKFLOW_FINGERPRINTS = [
474
+ // Header lines — verbatim template prose, and self-attributing.
475
+ { marker: 'CI (Node) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-node' },
476
+ { marker: 'CI (Laravel) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-laravel' },
477
+ { marker: 'CI (Python) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-python' },
478
+ { marker: 'Release (tag) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-tag' },
479
+ { marker: 'Release (auto) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-auto' },
480
+ { marker: 'Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-xserver' },
481
+ { marker: 'Branch name — TEMPLATE. Copy me into your repo', kind: 'text', template: 'branch-name' },
482
+ // The header convention itself, unattributed: this catches a copy of any template ADDED LATER
483
+ // without anyone remembering to extend this list — provided the new template keeps the house
484
+ // header. A template that omits it is invisible here, which is worth knowing when writing one.
485
+ { marker: '— TEMPLATE. Copy me into your repo', kind: 'text', template: null },
486
+ // Step names we coined, one per template.
487
+ { marker: 'Resolve Node version', kind: 'step', template: 'ci-node' },
488
+ { marker: 'Detect optional scripts', kind: 'step', template: 'ci-node' },
489
+ { marker: 'Resolve toolchain versions', kind: 'step', template: 'ci-laravel' },
490
+ { marker: 'Prepare throwaway env for build-time codegen (wayfinder)', kind: 'step', template: 'ci-laravel' },
491
+ { marker: 'Resolve Python version', kind: 'step', template: 'ci-python' },
492
+ { marker: 'Detect optional tooling', kind: 'step', template: 'ci-python' },
493
+ { marker: 'Build grouped release summary', kind: 'step', template: 'release-tag' },
494
+ { marker: 'Resolve tag and previous tag', kind: 'step', template: 'release-tag' },
495
+ // release-auto (#425): its two decision steps. The publish step's name is deliberately not a
496
+ // marker — "Publish GitHub Release" is release-tag's too, and would attribute a copy to both.
497
+ { marker: 'Cut a candidate (colab release cut --auto)', kind: 'step', template: 'release-auto' },
498
+ { marker: 'Finalize the newest clean candidate (colab release finalize --auto)', kind: 'step', template: 'release-auto' },
499
+ // deploy-xserver. These two were CHOSEN to differ from the step names in the hand-written deploy
500
+ // workflows this template was derived from ("Setup Node", "Smoke test (…)"), which is the same
501
+ // admission test as above read from the other end: those files must keep classifying as
502
+ // `unrelated`, and a marker they happen to contain would reclassify them as copies and invite an
503
+ // overwrite. Verified against all three before being added here.
504
+ { marker: 'Resolve deploy toolchain', kind: 'step', template: 'deploy-xserver' },
505
+ { marker: 'Verify the deployed site answers', kind: 'step', template: 'deploy-xserver' },
506
+ // branch-name (#348): its one step.
507
+ { marker: 'Check branch name (CONVENTIONS §4)', kind: 'step', template: 'branch-name' },
508
+ // Shared by all three ci-* templates: proves derivation, cannot say from which. Note the exact
509
+ // parenthetical — hand-written installers on this fleet say "(pinned binary)", which is why the
510
+ // step NAME discriminates where the URL inside the step does not.
511
+ { marker: 'Install gitleaks (pinned release binary)', kind: 'step', template: null },
512
+ ];
513
+
514
+ function reEscape(s) {
515
+ return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
516
+ }
517
+
518
+ /** Does one fingerprint match? Step markers must appear as an actual `- name:` step, not as prose. */
519
+ function fingerprintHits(text, fp) {
520
+ if (fp.kind === 'text') return text.includes(fp.marker);
521
+ return new RegExp(`^\\s*-\\s*name:\\s*["']?${reEscape(fp.marker)}["']?\\s*$`, 'm').test(text);
522
+ }
523
+
524
+ /**
525
+ * Where did an UNSTAMPED workflow come from? Returns { origin, template, evidence }:
526
+ *
527
+ * derived content evidence says it is a handbook copy. `template` names it when the evidence
528
+ * attributes one, else null (derivation proven, source not).
529
+ * name-only the FILENAME matches a template but the content carries none of it. This is the
530
+ * dangerous case, and it is why a name match is no longer sufficient on its own: the
531
+ * moment `templates/<x>.yml` is added for some `x` that repos already have as their
532
+ * own hand-written workflow, a name-only match would advise `--force` and OVERWRITE
533
+ * a file that never came from us. A shared name is a coincidence, not a lineage.
534
+ * none neither. Somebody's own workflow — say nothing about it, ever.
535
+ */
536
+ function workflowProvenance(text, stem, tmplNames) {
537
+ const hits = text ? WORKFLOW_FINGERPRINTS.filter((fp) => fingerprintHits(text, fp)) : [];
538
+ if (hits.length) {
539
+ const named = [...new Set(hits.map((h) => h.template).filter(Boolean))];
540
+ // One attributed template wins; several (or none) fall back to the filename, and only if that
541
+ // is a real template name. Never guess.
542
+ const template = named.length === 1 ? named[0] : (tmplNames.has(stem) ? stem : null);
543
+ // Cite only the most specific form of each match: the generic header rule always fires
544
+ // alongside the attributed one, and quoting both back at the reader reads like two findings.
545
+ const markers = hits.map((h) => h.marker);
546
+ const evidence = markers.filter((m) => !markers.some((o) => o !== m && o.includes(m)));
547
+ return { origin: 'derived', template, evidence };
548
+ }
549
+ if (tmplNames.has(stem)) return { origin: 'name-only', template: stem, evidence: [] };
550
+ return { origin: 'none', template: null, evidence: [] };
551
+ }
552
+
553
+ /**
554
+ * The single source of the advice both tools print, so the two can never drift apart on the one
555
+ * thing that matters here: whether to suggest asserting provenance.
556
+ * Returns null when there is nothing honest to say.
557
+ */
558
+ function unstampedFinding(prov) {
559
+ if (prov.origin === 'derived') {
560
+ const why = `matched handbook template text (${prov.evidence.map((e) => `"${e}"`).join(', ')})`;
561
+ const how = prov.template
562
+ ? `re-copy deliberately with \`colab template ${prov.template} --force\``
563
+ : 'identify which template it came from before re-copying — the evidence proves it is a copy but not of which template';
564
+ return {
565
+ state: 'unstamped',
566
+ reason: `${why} but carries no stamp — lineage unknown, so replacing it could destroy unknown edits; ${how}`,
567
+ };
568
+ }
569
+ if (prov.origin === 'name-only') {
570
+ return {
571
+ state: 'unrelated',
572
+ reason: `shares a name with templates/${prov.template} but contains none of that template's text — treated as this repo's own file. A matching NAME is not lineage: do NOT \`colab template ${prov.template} --force\`, it would overwrite work that never came from here.`,
573
+ };
574
+ }
575
+ return null;
576
+ }
577
+
578
+ /** Boolean view, kept for callers that only ask "is this ours?". A shared NAME alone is not. */
579
+ function looksLikeHandbookWorkflow(text, stem, tmplNames) {
580
+ return workflowProvenance(text, stem, tmplNames).origin === 'derived';
581
+ }
582
+
583
+ /** A CLAUDE.md that pasted the conventions block (this line is unique to the block template). */
584
+ function looksLikeHandbookClaude(text) {
585
+ return !!text && /follows the \[?colab-handbook/i.test(text);
586
+ }
587
+
588
+ // ---------------------------------------------------------------------------
589
+ // version comparison
590
+ // ---------------------------------------------------------------------------
591
+
592
+ /** Element-wise numeric compare; missing components count as 0. */
593
+ function cmpParts(a, b) {
594
+ const n = Math.max(a.length, b.length);
595
+ for (let i = 0; i < n; i++) {
596
+ const x = a[i] ?? 0;
597
+ const y = b[i] ?? 0;
598
+ if (x !== y) return x < y ? -1 : 1;
599
+ }
600
+ return 0;
601
+ }
602
+
603
+ /** vX.Y.Z comparison. Non-numeric junk sorts as 0 so a malformed stamp never throws. */
604
+ function cmpSemver(a, b) {
605
+ const norm = (s) => String(s).replace(/^v/i, '').split('.').map((n) => parseInt(n, 10) || 0);
606
+ return cmpParts(norm(a), norm(b));
607
+ }
608
+
609
+ // ---------------------------------------------------------------------------
610
+ // classification — the heart of `colab update`
611
+ // ---------------------------------------------------------------------------
612
+
613
+ // Compare tolerantly at the edges only: line endings and trailing blank lines are noise no adopter
614
+ // chose. Anything else counts as a real edit — under-reporting divergence here would let the tool
615
+ // overwrite someone's work, which is the one outcome it must never produce.
616
+ function sameContent(a, b) {
617
+ const norm = (s) => String(s).replace(/\r\n/g, '\n').replace(/\s+$/, '');
618
+ return norm(a) === norm(b);
619
+ }
620
+
621
+ /**
622
+ * Classify one stamped artifact. Returns { state, reason, from, to }.
623
+ *
624
+ * current the stamp is the handbook's version, OR the template genuinely has not changed
625
+ * since that stamp. Nothing to do.
626
+ * behind the stamp is older AND the template changed in between AND the local copy is
627
+ * still pristine as of its own stamp — so it can be regenerated safely.
628
+ * diverged the local copy does not match the template AS OF ITS OWN STAMP: someone edited it.
629
+ * Copy-and-own makes that legitimate (§7), so it is reported and never written.
630
+ * unstamped lineage unknown — handled by the caller, which can see it has no stamp at all.
631
+ * n-a cannot be assessed, with a stated reason (unknown template, a stamp from a version
632
+ * not in this checkout, a stamp newer than the handbook). Never silent.
633
+ *
634
+ * `comparable: false` (the CLAUDE block) means the artifact's pristine form cannot be reconstructed,
635
+ * so divergence is undecidable and the classification stops at current/behind.
636
+ */
637
+ function classifyStamped(opts) {
638
+ const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames } = opts;
639
+
640
+ if (hb.untagged || !hb.hasGit) {
641
+ return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion, to: hb.version };
642
+ }
643
+ if (templateName !== null && !tmplNames.has(templateName)) {
644
+ return { state: 'n-a', reason: `names unknown template "${templateName}" — not in the handbook's templates/`, from: stampVersion, to: hb.version };
645
+ }
646
+ if (cmpSemver(stampVersion, hb.version) > 0) {
647
+ return { state: 'n-a', reason: `stamp is NEWER than handbook ${hb.version} — clock skew or a hand-edited stamp`, from: stampVersion, to: hb.version };
648
+ }
649
+
650
+ const files = templateName === null ? [CLAUDE_BLOCK_TEMPLATE] : templateFiles(templateName);
651
+ const { verifiable, changed } = templateChangedSince(root, files, stampVersion);
652
+ if (!verifiable) {
653
+ return { state: 'n-a', reason: `stamped @ ${stampVersion}, a version not in this handbook checkout — fetch tags, or re-copy`, from: stampVersion, to: hb.version };
654
+ }
655
+ if (!changed) {
656
+ const why = cmpSemver(stampVersion, hb.version) === 0
657
+ ? 'stamped at the current handbook version'
658
+ : `template unchanged since ${stampVersion}`;
659
+ return { state: 'current', reason: why, from: stampVersion, to: hb.version };
660
+ }
661
+
662
+ // The template moved. Whether we may refresh depends on whether the copy is still pristine.
663
+ if (!comparable) {
664
+ return { state: 'behind', reason: 'template changed since this stamp', from: stampVersion, to: hb.version };
665
+ }
666
+ const pristine = templateAt(root, stampVersion, templateName);
667
+ if (pristine === null) {
668
+ return { state: 'n-a', reason: `cannot read templates/${templateName} at ${stampVersion} — cannot tell pristine from edited`, from: stampVersion, to: hb.version };
669
+ }
670
+ const expected = stampLine(templateName, stampVersion) + pristine;
671
+ if (sameContent(localText, expected)) {
672
+ return { state: 'behind', reason: 'pristine copy, template changed since this stamp', from: stampVersion, to: hb.version };
673
+ }
674
+ return { state: 'diverged', reason: `hand-edited since it was copied @ ${stampVersion} — copy-and-own, review by hand`, from: stampVersion, to: hb.version };
675
+ }
676
+
677
+ /**
678
+ * Classify the frozen CLI copy: { state, reason, from, to }, with state one of
679
+ * current / behind / n-a.
680
+ *
681
+ * Answered by `git log`, not by comparing version strings — so a handbook release that touched no
682
+ * CLI code does not tell every machine its frozen copy is stale.
683
+ *
684
+ * The upper bound is the latest TAG, not HEAD, and that is the whole difference from a template
685
+ * copy. A stamp records a version, so measuring it to HEAD compares two different units: any
686
+ * unreleased commit under FROZEN_SOURCES marked every machine `behind` until the next tag. That
687
+ * re-coupled precisely what freezing decouples — `behind` was computed against the working tree,
688
+ * and its advertised remedy (`install.sh --tools`) copies FROM the working tree, so on a machine
689
+ * where the handbook is being developed the tool continuously advised services to adopt untagged
690
+ * code. It also misreported worst for maintainers (HEAD ahead of the tag is their resting state)
691
+ * and best for pure consumers, and `colab update`'s exit code rides on it, so anything scripting
692
+ * it flapped red for the whole window between a CLI commit and the next tag.
693
+ *
694
+ * `behind` therefore means: a RELEASED CLI change exists that this machine lacks. True regardless
695
+ * of what the local checkout happens to be doing.
696
+ *
697
+ * No `diverged` state, and that is the one real difference from a template copy. A template is
698
+ * copy-and-own: the adopter is entitled to edit it, so an edit must be detected and protected. The
699
+ * frozen CLI is a CACHE of this repo's own tool — nobody owns it, install.sh overwrites it wholesale
700
+ * on every run, and a hand-edited one is a machine to fix, not an edit to preserve.
701
+ */
702
+ function classifyFrozen(opts) {
703
+ const { root, hb, stampVersion } = opts;
704
+
705
+ if (hb.untagged || !hb.hasGit) {
706
+ return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion || null, to: hb.version };
707
+ }
708
+ if (!stampVersion) {
709
+ return { state: 'n-a', reason: `no ${FROZEN_STAMP_FILE} beside the frozen copy — lineage unknown, re-run install.sh --tools`, from: null, to: hb.version };
710
+ }
711
+ if (cmpSemver(stampVersion, hb.version) > 0) {
712
+ return { state: 'n-a', reason: `stamp is NEWER than handbook ${hb.version} — this machine froze from a checkout ahead of here`, from: stampVersion, to: hb.version };
713
+ }
714
+
715
+ const { verifiable, changed } = templateChangedSince(root, FROZEN_SOURCES, stampVersion, hb.version);
716
+ if (!verifiable) {
717
+ return { state: 'n-a', reason: `stamped @ ${stampVersion}, a version not in this handbook checkout — fetch tags, or re-freeze`, from: stampVersion, to: hb.version };
718
+ }
719
+ if (!changed) {
720
+ const why = cmpSemver(stampVersion, hb.version) === 0
721
+ ? 'frozen at the current handbook version'
722
+ : `no released CLI change since ${stampVersion}`;
723
+ return { state: 'current', reason: why, from: stampVersion, to: hb.version };
724
+ }
725
+ return { state: 'behind', reason: `${hb.version} changed the CLI since ${stampVersion} — re-run install.sh --tools to re-freeze`, from: stampVersion, to: hb.version };
726
+ }
727
+
728
+ module.exports = {
729
+ CLAUDE_BLOCK_TEMPLATE, WORKFLOW_FINGERPRINTS,
730
+ FROZEN_STAMP_NAME, FROZEN_STAMP_FILE, FROZEN_SOURCES, classifyFrozen,
731
+ AUTHORITY_FLIP_VERSION,
732
+ gitIn, gitCommonDir, isHandbookItself,
733
+ handbookInfo, PACKAGE_NAME, npmPackageInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
734
+ AXES, axesPredating,
735
+ WRITES_VETO_MARKER, writesRulingKnownAt,
736
+ stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,
737
+ fingerprintHits, workflowProvenance, unstampedFinding,
738
+ looksLikeHandbookWorkflow, looksLikeHandbookClaude,
739
+ cmpParts, cmpSemver, sameContent, classifyStamped,
740
+ };