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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -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 +13790 -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 +259 -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.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +521 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
package/package.json CHANGED
@@ -1,10 +1,31 @@
1
1
  {
2
2
  "name": "@futurelastic/colab-handbook",
3
- "version": "0.0.0-bootstrap.0",
4
- "description": "Name reservation. Real releases are published from CI with provenance: see https://github.com/futurelastic/colab-handbook",
3
+ "description": "colab CLI — issue claims, worktrees, releases and handbook adoption for parallel agent/human sessions. Zero dependencies.",
5
4
  "license": "MIT",
6
- "repository": { "type": "git", "url": "git+https://github.com/futurelastic/colab-handbook.git" },
7
5
  "homepage": "https://github.com/futurelastic/colab-handbook#readme",
8
- "files": ["README.md","bin/cli.js"],
9
- "bin": { "colab": "bin/cli.js" }
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/futurelastic/colab-handbook.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/futurelastic/colab-handbook/issues"
12
+ },
13
+ "bin": {
14
+ "colab": "./tools/colab"
15
+ },
16
+ "files": [
17
+ "tools/colab",
18
+ "tools/lib/*.js",
19
+ "!tools/lib/*.test.js",
20
+ "templates/",
21
+ "audit/audit.mjs"
22
+ ],
23
+ "publishConfig": {
24
+ "access": "public",
25
+ "provenance": true
26
+ },
27
+ "engines": {
28
+ "node": ">=18"
29
+ },
30
+ "version": "1.12.0-rc.10"
10
31
  }
@@ -0,0 +1,257 @@
1
+ # Templates
2
+
3
+ Starting points you **copy into your own repo**. That is the entire model.
4
+
5
+ > **These are NOT called remotely.** There is no `uses: futurelastic/colab-handbook/...`
6
+ > anywhere, and nothing here is a reusable workflow another repo calls. (`dist-refs.yml` is a
7
+ > `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
8
+ > `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
9
+ > handbook told repos to call shared workflows; that was reversed. Every workflow now
10
+ > lives, in full, inside the repo that runs it. You copy the file, you edit it, **you
11
+ > own it.** Divergence between your copy and this template is expected — a shared
12
+ > workflow that silently changes under a hundred repos is the failure mode we are
13
+ > avoiding.
14
+
15
+ ## What each template is for
16
+
17
+ | File | Copy to | For | Notes |
18
+ |---|---|---|---|
19
+ | `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. |
20
+ | `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
21
+ | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
22
+ | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
23
+ | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily, from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
24
+ | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
25
+ | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path for a service's `init`. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
26
+ | `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
27
+ | `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
28
+ | `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. |
29
+ | `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. |
30
+ | `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. |
31
+ | `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. |
32
+ | `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. |
33
+
34
+ ### Migration round-trip — what the Laravel job proves, and what it cannot
35
+
36
+ `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
37
+ zero, then — after rolling back the migrations the change adds and seeding rows at the
38
+ schema *before* the change — once more, the way a deploy lands new migrations on data
39
+ that predates them. The schema after both passes must match. Two things to know before
40
+ trusting a green run:
41
+
42
+ - **Both legs matter.** The engines disagree: a `NOT NULL` column added without a default
43
+ fails on sqlite when rows exist, while MariaDB accepts it and silently writes `''` into
44
+ every existing row. A deploy-engine leg at a version production does not run proves
45
+ nothing about production — set the image to the exact version.
46
+ - **Without `ROUNDTRIP_SEEDER`, the data traps pass.** A foreign key over orphan rows,
47
+ `->change()` dropping an unrestated `nullable`, lossy numeric conversion and the
48
+ `NOT NULL` case all need rows to fire; on empty tables every one is green on both
49
+ engines. The seeder runs against the pre-change schema, so it writes the way old data
50
+ looks — raw `DB::table()` inserts into long-lived columns, not factories.
51
+
52
+ **Prisma.** No Prisma stack template exists here, so there is no Prisma job to add. The
53
+ round-trip does not translate directly anyway: Prisma Migrate has no down migrations. A
54
+ Prisma repo's nearest equivalent is applying its migrations to an empty deploy-engine
55
+ database (`prisma migrate deploy`) and then asserting no drift
56
+ (`prisma migrate diff --from-migrations … --to-schema-datamodel … --exit-code`) — worth a
57
+ template of its own once a Prisma stack is adopted.
58
+
59
+ ### Hooks — the same model, copied by hand
60
+
61
+ These are `sh`, with no file extension at all, and their destination filename does not
62
+ match their source stem (`pre-push-guard` → `<hooks>/pre-push`) — so `colab template`
63
+ does not carry them, and they take **no version stamp**. The original reason a stamp
64
+ was impossible here — prepending a comment line above a `#!` shebang breaks it — is
65
+ fixed for `docs-lint.mjs` above (a second-line stamp, colab-handbook #252), but that fix
66
+ still needs a destination formula before it can apply to these too, and these three
67
+ files don't have one. Copy them with `cp`, `chmod +x`, and own them exactly as you own
68
+ a workflow.
69
+
70
+ | File | Copy to | For | Notes |
71
+ |---|---|---|---|
72
+ | `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
73
+ | `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
74
+ | `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
75
+ | `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
76
+
77
+ `<hooks>` is `git config core.hooksPath` if you set one, else `.git/hooks`. The
78
+ executable bit is per-clone for anything git does not track, so ship a one-line install
79
+ script that chmods — put it **inside `<hooks>` itself** (this repo's
80
+ `.githooks/install.sh` is the pattern), not in a top-level `scripts/` dir. It is
81
+ never invoked as a hook (git only ever runs the exact hook filenames it knows —
82
+ `pre-commit`, `pre-push`, etc. — never every file in the directory), and
83
+ colocating it with what it installs means a repo whose only "script" is this
84
+ one installer does not end up with a whole `scripts/` folder for a single
85
+ 506-byte file. An earlier version of this handbook shipped the pattern at
86
+ `scripts/install-hooks.sh`; that scaffolded a bare one-file `scripts/`
87
+ directory into ~45 repos and was wrong — fixed 2026-08-20.
88
+
89
+ ## How to adopt
90
+
91
+ 1. **Copy — use `colab template`.** It copies the template *and* stamps it with the
92
+ current handbook version in one act, so the audit can later tell you when the
93
+ source moved on:
94
+
95
+ ```sh
96
+ colab template # list templates + handbook version
97
+ colab template ci-node --dest .github/workflows/ci.yml
98
+ colab template release-tag --dest .github/workflows/release.yml
99
+ colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
100
+ colab template docs-lint.mjs --dest tools/docs-lint.mjs # --dest is required for this one
101
+ ```
102
+
103
+ The stamp is one comment line — `# colab-handbook: <name> @ <version>` — prepended
104
+ at the top for a YAML copy. `docs-lint.mjs` opens with a `#!/usr/bin/env node`
105
+ shebang, so its stamp lands on the **second** line instead, spelled `//` (a bare `#`
106
+ anywhere but a shebang is a JS syntax error) — the shebang still has to stay first
107
+ for the file to run. Do a plain `cp` only if you have no `colab` on PATH, and then
108
+ add that stamp line by hand (an unstamped copy is untrackable — the audit will nag
109
+ you to re-copy).
110
+ 2. **Walk the `# EDIT:` markers.** Each one is a decision only your repo can make:
111
+ which branches exist, self-hosted runner or not, the build command, working
112
+ directory.
113
+ 3. **Declare your toolchain.** The CI templates refuse to guess a version. Put it in
114
+ `.github/project.yml` (`node: "22"`, `php: "8.4"`, `python: "3.13"`), or rely on
115
+ `.nvmrc` / `package.json engines.node` / `composer.json require.php` /
116
+ `.python-version` / `pyproject.toml requires-python`. If none of these exists,
117
+ CI fails on purpose with a message telling you to declare it. Note that
118
+ `requirements.txt` is **not** one of these — it pins dependencies, not the interpreter.
119
+ 4. **Add `.github/project.yml`** if you have not — copy the reference at the handbook's
120
+ own `.github/project.yml`. The audit tool and the CI resolution step both read it.
121
+ 5. **Paste the CLAUDE block** (`repo-CLAUDE-block.md`) so the next agent in the repo can
122
+ find its way back here. Set its `<!-- colab-handbook @ <version> -->` stamp to the
123
+ handbook version you adopted at.
124
+ 6. **Own it.** From this point the file is yours. Edit freely; nothing overwrites it.
125
+
126
+ ### Adopting a guard in an existing repo — why this is a template at all
127
+
128
+ **A guard delivered by scaffolding reaches only repos created after it shipped.** We have
129
+ measured that: one existed for months and covered a small minority of repositories, while
130
+ every older one — public ones included — had `core.hooksPath` set, a hooks directory
131
+ present, and no such check in it. Nothing was broken and nothing reported anything. The
132
+ repo *looked* configured, which is worse than an obviously empty one, because the state
133
+ that makes you go and look never arises.
134
+
135
+ Templates are copied into repositories that **already exist**. That is the mechanism that
136
+ actually propagates here, and it is why a guard belongs in this directory rather than in a
137
+ scaffold. A scaffold answers "what does a new repo start with"; a template answers "what
138
+ can any repo adopt today". A control that only the newest repos have is not a control.
139
+
140
+ So, into a repo that already has a `pre-commit` hook — the normal case, since a secret
141
+ scan is the one guard almost everything already carries:
142
+
143
+ ```sh
144
+ mkdir -p <hooks>/pre-commit.d
145
+ git mv <hooks>/pre-commit <hooks>/pre-commit.d/10-secrets # your existing check, unchanged
146
+ cp templates/pre-commit-dispatch <hooks>/pre-commit
147
+ cp templates/pre-commit-identity <hooks>/pre-commit.d/20-identity
148
+ chmod +x <hooks>/pre-commit <hooks>/pre-commit.d/*
149
+ cp templates/identity-vocabulary.example ~/.colab/identity-vocabulary # then EDIT it, outside any repo
150
+ ```
151
+
152
+ Four things to know before you do it:
153
+
154
+ 1. **Your existing check is moved, never replaced.** The dispatcher sequences checks; it
155
+ has no opinion about them. Step 2 above is load-bearing — skip it and you have swapped
156
+ a working secret scan for a dispatcher with nothing to dispatch (which refuses to
157
+ commit, so you will find out immediately, but you will have to go and get it back).
158
+ 2. **Do not simply append the identity scan to your existing hook.** The usual secret-scan
159
+ hook exits early when its scanner is not installed, and everything below that line is
160
+ skipped with it — on exactly the machine that is already least protected. The
161
+ dispatcher's header carries the full argument.
162
+ 3. **The vocabulary is not ours to ship and not yours to commit.** Without one the scan
163
+ warns on every commit and passes; that is a deliberate no-op, not a silent one.
164
+ 4. **Verify by committing something you expect it to catch**, once. A guard nobody has ever
165
+ seen fire is indistinguishable from one that is not installed — which is the failure
166
+ this whole section is about.
167
+
168
+ Repository *metadata* — description, topics, homepage, the name — never passes through git,
169
+ so no hook can see any of it, and it is the first thing a visitor reads. That half is a
170
+ periodic sweep instead: `node audit.mjs --identity`, documented in
171
+ [`audit/README.md`](../audit/README.md). Same vocabulary, same path, same refusal to run
172
+ without one.
173
+
174
+ ### Adopting the deploy template — the extra steps
175
+
176
+ A deploy workflow is the only template that can break something that is already
177
+ live, so it carries obligations the CI ones do not:
178
+
179
+ 1. **Do the one-time server preparation first.** It is a checklist in the
180
+ template header — subdomain, certificate, database, the server-side `.env`, the
181
+ deploy key in `authorized_keys`. None of it is automated and the first deploy
182
+ fails without it. Copy that checklist into the repo's runbook rather than
183
+ leaving it in a workflow comment.
184
+ 2. **Fill the `env:` block, and nothing below it.** Every per-repo value — host,
185
+ user, paths, the server's PHP binary, the smoke URL — lives in that one block
186
+ precisely so your diff against this template stays readable. Editing step
187
+ bodies instead is how the three ancestors of this file drifted ~120 lines apart.
188
+ 3. **Add the secret, one per repo.** `DEPLOY_SSH_KEY`, never shared between repos
189
+ even when they deploy into the same hosting account: a shared key cannot be
190
+ rotated for one of them, and a leak from any reaches all.
191
+ 4. **Make `project.yml` true.** A tag deploys only where `deploy: tag` is
192
+ declared. **This does not change your tier** — tier says whether production
193
+ exists and how many gates guard it, and it moves only by the [§9](../CONVENTIONS.md#9-adopting-this) checklist. If
194
+ the repo was `deploy: manual`, switching it now is a deliberate edit (and drop
195
+ the `runbook:` that is no longer the mechanism). Adopting this into a Tier B
196
+ repo is not an adoption at all: it is giving the repo a production, which is a
197
+ different decision.
198
+ 5. **Keep the smoke test.** It is the only step that distinguishes "the workflow
199
+ went green" from "the site answers", and a deploy can do the first while
200
+ failing the second.
201
+ 6. **Retro-fitting an existing hand-written deploy workflow is a per-repo job, by
202
+ hand.** Those files have local edits — extra artisan commands, app-specific
203
+ backfills — that a blind overwrite destroys. `colab update` will classify such
204
+ a file as `unrelated` (its name matches this template, its content never came
205
+ from here) and refuse to touch it. That is correct: diff the two yourself and
206
+ move across only what you mean to.
207
+
208
+ ## Reconciliation — how you find out when a template changes
209
+
210
+ Because you own your copy, nothing pushes updates to you. Instead the copy is
211
+ **stamped** with the handbook version it came from, and `audit/audit.mjs` compares that
212
+ stamp against the handbook's git history. When a template you copied has changed since
213
+ your stamp, the audit flags it: review the diff, take what you want, and re-run
214
+ `colab template … --force` to re-stamp. That is the whole loop — no remote calls, no
215
+ silent updates, just an honest report that you are behind.
216
+
217
+ If you're the one editing a template *in this repo* and the change touches no rule at
218
+ all — a typo, a broken hyperlink, a comment — write `Rule-Neutral: yes` as a trailer on
219
+ that commit. Every adopter's drift finding for it then downgrades to a warn instead of a
220
+ hard fail, but only if **every** commit since their stamp declared it; a `ci-*` template
221
+ is never eligible, trailer or not. Full contract: [CONVENTIONS.md §8](../CONVENTIONS.md#8-conformance-and-reconciliation).
222
+
223
+ ## Keeping honest
224
+
225
+ `audit/audit.mjs` in this handbook sweeps many repos and reports when a `project.yml`
226
+ is missing or incoherent, when a declared toolchain disagrees with what CI actually
227
+ pins, when branch names drift, and when a stamped copy has fallen behind its template.
228
+ It is advisory — run it locally or on a schedule. It is **not** wired into any repo's CI.
229
+
230
+ ## Runner policy
231
+
232
+ Decided 2026-07-19, after a GitHub Actions billing lock stopped every
233
+ `ubuntu-latest` job org-wide while self-hosted runners kept working:
234
+
235
+ | Repo class | `runs-on` | Why |
236
+ |---|---|---|
237
+ | **Public** repo | `ubuntu-latest` | Free minutes, unaffected by billing — and **never** self-hosted: a fork PR would execute arbitrary code on your runner. |
238
+ | **Private** CI | the org's `[self-hosted, ...]` runner **where one exists**; `ubuntu-latest` otherwise | Immune to billing, persistent tool caches, local network. Runners are registered per-org — one org's runner serves nothing in another org. Register a runner for an org when its billing or scale makes it worth it, not preemptively. |
239
+ | **Private** deploy | its own runner label | Deploys must never queue behind CI jobs. |
240
+
241
+ Self-hosted job hygiene: no `sudo`, install tools into `$RUNNER_TEMP`, never
242
+ write outside the workspace, prefer the runner's native toolchains. A shared
243
+ runner is infrastructure, not a throwaway VM.
244
+
245
+ ### Self-hosted patterns that earn their place
246
+
247
+ - **Split a test matrix by purpose.** The leg matching production is the release
248
+ gate → self-hosted (immune to billing/outage). Forward-compat legs (next PHP,
249
+ next Node) are reconnaissance → keep them on hosted runners with
250
+ `continue-on-error: true`. Losing an advisory signal during an outage is fine;
251
+ losing the gate is not.
252
+ - **Service containers on a shared runner: never fix the host port.** The runner
253
+ machine likely runs its own database on the default port. Publish the container
254
+ port unmapped (`- 3306`) and read the randomly assigned host port from the job's
255
+ service context (`job.services.mysql.ports['3306']`), threading it through your
256
+ env. A fixed `3306:3306` works exactly until the first job lands on a runner
257
+ that already listens there.
@@ -0,0 +1,57 @@
1
+ # `docs/adr/` — one file per architecture decision
2
+
3
+ This directory holds Architecture Decision Records — one file per decision,
4
+ never a single growing document and never sequential numbering. Same design
5
+ as `docs/gotchas.d/`, and for the same reason: a shared counter (`0001-`,
6
+ `0002-`, …) has no stable identity, so two parallel branches each adding
7
+ "the next one" pick the same number, and one silently loses its identity at
8
+ merge — with every existing citation to that number now pointing at
9
+ different content, and no error anywhere.
10
+
11
+ ## Naming
12
+
13
+ `<issue-number>-<slug>.md` — the issue the decision was made under, then a
14
+ short slug. Example: `142-worktree-stash-collision.md`.
15
+
16
+ The issue number is the stable id. Citations elsewhere in the repo reference
17
+ the decision by this filename (or by issue number), never by a sequence
18
+ position — a filename never needs renumbering when a neighbour is added or
19
+ removed.
20
+
21
+ ## Writing an entry
22
+
23
+ One file, one decision. The shape that has proven itself elsewhere (context /
24
+ decision / consequences — MADR-style, adapt freely):
25
+
26
+ ```md
27
+ # <short title of the decision>
28
+
29
+ ## Context
30
+
31
+ What forced this decision — the problem, the constraint, the trigger.
32
+
33
+ ## Decision
34
+
35
+ What was chosen, stated as a decision, not a description.
36
+
37
+ ## Alternatives rejected
38
+
39
+ What else was considered, and why it lost.
40
+
41
+ ## Consequences
42
+
43
+ What this makes easier, harder, or is now true as a result.
44
+ ```
45
+
46
+ **Append-only.** A new decision is a new file — never edit another entry's
47
+ file to extend or reverse it. A decision that gets superseded gets a *new*
48
+ file that says so and points back; the old one stays as the historical
49
+ record of what was actually decided at the time, which is the whole point of
50
+ keeping one.
51
+
52
+ ## An existing sequentially-numbered `docs/adr/`, if this repo has one
53
+
54
+ Left exactly as-is — this is not a forced renumber. Only *new* decisions from
55
+ here on use the issue-keyed name. The old entries keep their `000N-` names
56
+ and their existing citations; nothing needs to change for them to stay
57
+ correct.
@@ -0,0 +1,51 @@
1
+ # Branch name — TEMPLATE. Copy me into your repo at
2
+ # .github/workflows/branch-name.yml. Copy-and-own, exactly like every other
3
+ # workflow template in this directory — nothing calls this workflow remotely,
4
+ # and nothing here updates itself. See templates/README.md.
5
+ #
6
+ # OPT-IN. Checks that a pull request's head branch matches CONVENTIONS.md §4:
7
+ #
8
+ # <type>/<slug>-<N> the default shape
9
+ # <login>/<machine>/<type>/<slug>-<N> the machine-carried shape, which
10
+ # `colab worktree new` cuts once the repo
11
+ # declares `branchPrefix: machine`
12
+ #
13
+ # Both pass as shipped. Branches that predate the convention are grandfathered by
14
+ # §4 — this only ever sees a branch when someone opens a PR from it, so an old
15
+ # branch nobody proposes is never checked.
16
+ #
17
+ # EDIT POINTS are marked `# EDIT:`.
18
+
19
+ name: branch-name
20
+
21
+ on:
22
+ pull_request:
23
+ # EDIT: your trunk (and any declared integration line) — the branches PRs target.
24
+ branches: [main, dev]
25
+
26
+ jobs:
27
+ branch-name:
28
+ name: branch name (CONVENTIONS §4)
29
+ # Public repos stay on ubuntu-latest always (a fork PR must never execute on
30
+ # your own runner) — see templates/README.md "Runner policy".
31
+ runs-on: ubuntu-latest
32
+ steps:
33
+ - name: Check branch name (CONVENTIONS §4)
34
+ env:
35
+ # Passed through env, never interpolated into the script: on a public repo
36
+ # the head branch name is chosen by whoever opened the PR.
37
+ BRANCH: ${{ github.head_ref }}
38
+ run: |
39
+ # EDIT: once this repo declares `branchPrefix: machine`, delete the `?`
40
+ # after the first group to REQUIRE the prefix. Kept byte-identical to the
41
+ # regex in CONVENTIONS.md §4 otherwise — do not hand-edit its body.
42
+ RE='^([a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*/)?(feat|fix|docs|chore|refactor|test|perf|design)/[a-z0-9._-]+$'
43
+ case "$BRANCH" in
44
+ dependabot/*|renovate/*) echo "bot branch, exempt: $BRANCH"; exit 0 ;;
45
+ esac
46
+ if [[ "$BRANCH" =~ $RE ]]; then
47
+ echo "ok: $BRANCH"
48
+ else
49
+ echo "::error::branch \"$BRANCH\" does not match CONVENTIONS.md §4 — want <type>/<slug>-<N> or <login>/<machine>/<type>/<slug>-<N>"
50
+ exit 1
51
+ fi