@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13785 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
package/package.json
CHANGED
|
@@ -1,10 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@futurelastic/colab-handbook",
|
|
3
|
-
"
|
|
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
|
-
"
|
|
9
|
-
|
|
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.9"
|
|
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
|