@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.
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 +13785 -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 +481 -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
@@ -0,0 +1,267 @@
1
+ #!/bin/sh
2
+ # pre-commit-identity — refuse to commit content that names something the operator has
3
+ # decided must never be published: a machine hostname, an account handle, an absolute home
4
+ # path, an internal domain, a customer or partner name.
5
+ #
6
+ # WHY THIS EXISTS. Every automated gate in a normal repo guards SECRETS. A secret scanner
7
+ # finds credentials, and it finds them well — but a hostname is not a credential, an
8
+ # account handle is not a credential, and a customer's name is not a credential. Those pass
9
+ # every gate, land in a public repo, and stay there: git history cannot be recalled once
10
+ # anything is cloned or forked. This scans the one class the secret scanner structurally
11
+ # cannot see.
12
+ #
13
+ # WHY PRE-COMMIT AND NOT CI. CI is too late. By the time a workflow runs, the commit exists
14
+ # and may already be pushed, and the only remedy is rewriting published history. Pre-commit
15
+ # is the last point at which nothing has left the machine.
16
+ #
17
+ # ⚠ THE SCANNER SHIPS; THE VOCABULARY DOES NOT. A list of the exact strings an organisation
18
+ # considers sensitive is itself sensitive — it is a precise index of what to look for. This
19
+ # script therefore takes the vocabulary BY PATH, from a file the operator keeps OUTSIDE the
20
+ # repo. Never commit a real one. `templates/identity-vocabulary.example` is an invented
21
+ # list, safe to copy and then edit in place outside the working tree.
22
+ #
23
+ # WHERE THE VOCABULARY COMES FROM (first hit wins):
24
+ # 1. $COLAB_IDENTITY_VOCAB — explicit, per invocation
25
+ # 2. git config colab.identityVocabulary — explicit, per clone (lives in .git/config,
26
+ # so it is machine-local and never synced —
27
+ # the same property core.hooksPath relies on)
28
+ # 3. ${COLAB_HOME:-~/.colab}/identity-vocabulary — the machine-wide default
29
+ #
30
+ # If 1 or 2 names a file that cannot be read, this REFUSES the commit: you declared a
31
+ # vocabulary and it is not there, so the check cannot run, and a check that cannot run must
32
+ # never pass silently. If only 3 applies and the file is absent, the machine simply has no
33
+ # vocabulary configured — it warns on every commit and exits 0, exactly as the gitleaks
34
+ # hook does when gitleaks is not installed.
35
+ #
36
+ # INSTALL — three shapes, pick one:
37
+ # a. Alongside an existing pre-commit hook (the usual case), via the dispatcher:
38
+ # cp templates/pre-commit-dispatch <hooks>/pre-commit # see its own header
39
+ # cp templates/pre-commit-identity <hooks>/pre-commit.d/20-identity
40
+ # chmod +x <hooks>/pre-commit <hooks>/pre-commit.d/*
41
+ # b. As the whole hook, in a repo that has no pre-commit hook at all:
42
+ # cp templates/pre-commit-identity .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
43
+ # c. Additionally as a commit-msg hook — a commit MESSAGE is published too, and unlike a
44
+ # file it cannot be corrected afterwards without rewriting history:
45
+ # cp templates/pre-commit-identity .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
46
+ # (git passes the message file as $1; this script scans a file when given one.)
47
+ # <hooks> is `git config core.hooksPath` if you set one, else `.git/hooks`.
48
+ #
49
+ # WHAT IT SCANS. With no argument: the STAGED diff's added lines, plus the staged path
50
+ # names themselves (a directory named after a customer names them just as loudly as a line
51
+ # of prose). Deleted lines and unstaged work are not scanned — this is about what the commit
52
+ # publishes. With a file argument: that file, whole.
53
+ #
54
+ # ON A MATCH. The commit is refused, and the matched text is REDACTED in the output: the
55
+ # whole point is that the string should not be republished, and a terminal, a shell history
56
+ # and a CI log are all places it would then live. You get file:line and the vocabulary entry
57
+ # number — you own that file, so the entry number is all you need. COLAB_IDENTITY_SHOW=1
58
+ # prints the matched term when you genuinely cannot tell what fired.
59
+ #
60
+ # OVERRIDE — per invocation, never persistent:
61
+ # COLAB_IDENTITY_OK=1 git commit ...
62
+ # It is deliberately an environment variable and NOT an in-file marker (`# privacy-ok` and
63
+ # friends). Three reasons: a marker is persistent, so it silently allows every future commit
64
+ # touching that line; a marker is itself committed, which publishes an arrow pointing at the
65
+ # thing it excuses; and a marker can be added by the same diff that carries the leak, which
66
+ # means the scanner can be disabled by the content it is scanning. An environment variable
67
+ # is none of those — it is one act, by the person at the keyboard, for one commit.
68
+ # `git commit --no-verify` also works, but it disables EVERY hook including the secret scan;
69
+ # this override is narrower on purpose. Setting it is the operator's call — an agent that
70
+ # hits this block surfaces it and stops, it does not set the variable for itself.
71
+ #
72
+ # EXIT: 0 clean (or overridden, or no vocabulary configured), 1 blocked.
73
+
74
+ set -eu
75
+
76
+ MIN_TERM_LEN=3 # a 1-2 character term matches nearly everything; refuse it as a mistake
77
+ MAX_REPORTED=20 # a flood of hits is not more informative than the first twenty
78
+
79
+ say() { printf '%s\n' "$*" >&2; }
80
+
81
+ # --------------------------------------------------------------- resolve the vocabulary
82
+ vocab=""
83
+ vocab_src=""
84
+ vocab_explicit=0
85
+
86
+ if [ -n "${COLAB_IDENTITY_VOCAB:-}" ]; then
87
+ vocab=$COLAB_IDENTITY_VOCAB
88
+ vocab_src="COLAB_IDENTITY_VOCAB"
89
+ vocab_explicit=1
90
+ else
91
+ cfg=$(git config --get colab.identityVocabulary 2>/dev/null || true)
92
+ if [ -n "$cfg" ]; then
93
+ vocab=$cfg
94
+ vocab_src="git config colab.identityVocabulary"
95
+ vocab_explicit=1
96
+ else
97
+ vocab="${COLAB_HOME:-$HOME/.colab}/identity-vocabulary"
98
+ vocab_src="default"
99
+ fi
100
+ fi
101
+
102
+ # `~` is not expanded inside a git config value or an exported variable.
103
+ case $vocab in
104
+ "~/"*) vocab="$HOME/${vocab#\~/}" ;;
105
+ esac
106
+
107
+ if [ ! -r "$vocab" ]; then
108
+ if [ "$vocab_explicit" -eq 1 ]; then
109
+ say "❌ identity scan: the vocabulary named by $vocab_src cannot be read — commit BLOCKED."
110
+ say " path: $vocab"
111
+ say " A configured check that cannot run is not a pass. Fix the path, or unset it."
112
+ exit 1
113
+ fi
114
+ say "⚠ identity scan: no vocabulary at $vocab — nothing was scanned for identity."
115
+ say " Create one (start from templates/identity-vocabulary.example, keep it OUT of any repo)"
116
+ say " or point at yours: git config colab.identityVocabulary <path>"
117
+ exit 0
118
+ fi
119
+
120
+ # ------------------------------------------------------------------------ what to scan
121
+ tmp=$(mktemp -d "${TMPDIR:-/tmp}/identity-scan.XXXXXX")
122
+ trap 'rm -rf "$tmp"' EXIT
123
+ trap 'rm -rf "$tmp"; exit 130' INT
124
+ trap 'rm -rf "$tmp"; exit 143' TERM
125
+
126
+ subject="$tmp/subject" # one record per line: <location><TAB><text>
127
+ : > "$subject"
128
+
129
+ if [ "$#" -gt 0 ] && [ -n "${1:-}" ]; then
130
+ if [ ! -r "$1" ]; then
131
+ say "❌ identity scan: cannot read $1 — commit BLOCKED (the check could not run)."
132
+ exit 1
133
+ fi
134
+ awk '{ printf "%s:%d\t%s\n", FILENAME, FNR, $0 }' "$1" > "$subject"
135
+ else
136
+ # Staged PATHS. A path is content too, and it is the one kind a diff of added lines
137
+ # never shows: renaming a directory after a customer adds no line anywhere.
138
+ #
139
+ # Reported by ORDINAL, never by name — the path IS the offending string here, so printing
140
+ # it as the location would republish exactly what the redaction exists to withhold. The
141
+ # ordinal is the line number in the listing below, which the message tells you how to run.
142
+ git diff --cached --name-only --diff-filter=ACMR \
143
+ | awk 'NF { printf "(staged path %d)\t%s\n", FNR, $0 }' >> "$subject"
144
+
145
+ # Staged ADDED LINES, with real file:line locations reconstructed from the hunk headers.
146
+ # --unified=0 so there is no context: a neighbouring line somebody else wrote is not
147
+ # this commit's to answer for.
148
+ git diff --cached --unified=0 --diff-filter=ACMR \
149
+ | awk '
150
+ /^\+\+\+ \/dev\/null/ { path = ""; next }
151
+ /^\+\+\+ / { path = substr($0, 7); next } # strips the "+++ b/" prefix
152
+ /^@@ / { n = $3; sub(/^\+/, "", n); sub(/,.*$/, "", n); ln = n + 0; next }
153
+ /^\+/ { printf "%s:%d\t%s\n", (path == "" ? "(unknown)" : path), ln, substr($0, 2); ln++; next }
154
+ ' >> "$subject"
155
+ fi
156
+
157
+ # ------------------------------------------------------------------- parse the vocabulary
158
+ # One term per line. Blank lines and lines whose first non-space character is `#` are
159
+ # comments. A leading `re:` marks an extended regular expression; everything else is a
160
+ # fixed string. Matching is case-insensitive and by SUBSTRING, deliberately: a hostname
161
+ # appears inside URLs, paths and identifiers with no word boundary anywhere near it.
162
+ # A term is kept verbatim apart from surrounding whitespace, so it may contain `#`.
163
+ terms="$tmp/terms"
164
+ awk '
165
+ {
166
+ line = $0
167
+ sub(/\r$/, "", line)
168
+ sub(/^[ \t]+/, "", line); sub(/[ \t]+$/, "", line)
169
+ if (line == "" || substr(line, 1, 1) == "#") next
170
+ kind = "fixed"
171
+ if (substr(line, 1, 3) == "re:") { kind = "regex"; line = substr(line, 4); sub(/^[ \t]+/, "", line) }
172
+ if (line == "") next
173
+ gsub(/\t/, " ", line) # tab separates the fields of the record below
174
+ printf "%d\t%s\t%s\n", FNR, kind, line
175
+ }' "$vocab" > "$terms"
176
+
177
+ # ------------------------------------------------------------------------------- scan
178
+ hits="$tmp/hits" # <entry><TAB><chars><TAB><location><TAB><term>
179
+ : > "$hits"
180
+ problems="$tmp/problems"
181
+ : > "$problems"
182
+
183
+ TAB=$(printf '\t')
184
+ while IFS="$TAB" read -r entry kind value; do
185
+ [ -n "${entry:-}" ] || continue
186
+ if [ "${#value}" -lt "$MIN_TERM_LEN" ]; then
187
+ printf 'entry %s is only %s character(s) — too short to be a term (minimum %s)\n' \
188
+ "$entry" "${#value}" "$MIN_TERM_LEN" >> "$problems"
189
+ continue
190
+ fi
191
+ if ! found=$(
192
+ TERM_VALUE="$value" TERM_KIND="$kind" awk '
193
+ BEGIN { t = tolower(ENVIRON["TERM_VALUE"]); k = ENVIRON["TERM_KIND"] }
194
+ {
195
+ i = index($0, "\t")
196
+ if (i == 0) next
197
+ loc = substr($0, 1, i - 1)
198
+ text = tolower(substr($0, i + 1))
199
+ if (k == "regex") { if (text ~ t) print loc }
200
+ else if (index(text, t) > 0) { print loc }
201
+ }' "$subject" 2>/dev/null
202
+ ); then
203
+ printf 'entry %s is not a valid regular expression\n' "$entry" >> "$problems"
204
+ continue
205
+ fi
206
+ [ -n "$found" ] || continue
207
+ printf '%s\n' "$found" | while IFS= read -r loc; do
208
+ [ -n "$loc" ] || continue
209
+ printf '%s\t%s\t%s\t%s\n' "$entry" "${#value}" "$loc" "$value" >> "$hits"
210
+ done
211
+ done < "$terms"
212
+
213
+ # ---------------------------------------------------------------------------- verdict
214
+ if [ -s "$problems" ]; then
215
+ say "❌ identity scan: the vocabulary itself is unusable — commit BLOCKED."
216
+ while IFS= read -r p; do say " $p"; done < "$problems"
217
+ say " Vocabulary: $vocab ($vocab_src)"
218
+ say " Fix those entries. This is not what COLAB_IDENTITY_OK is for — a broken"
219
+ say " vocabulary is not a false positive, it is a check that did not run."
220
+ exit 1
221
+ fi
222
+
223
+ if [ ! -s "$hits" ]; then
224
+ exit 0
225
+ fi
226
+
227
+ total=$(wc -l < "$hits" | tr -d ' ')
228
+ if [ "${COLAB_IDENTITY_OK:-}" = "1" ]; then
229
+ say "⚠ identity scan: $total match(es) allowed through by COLAB_IDENTITY_OK=1."
230
+ else
231
+ say "❌ identity scan: staged content names something the vocabulary forbids — commit BLOCKED."
232
+ fi
233
+
234
+ shown=0
235
+ while IFS="$TAB" read -r entry chars loc value; do
236
+ shown=$((shown + 1))
237
+ if [ "$shown" -gt "$MAX_REPORTED" ]; then continue; fi
238
+ if [ "${COLAB_IDENTITY_SHOW:-}" = "1" ]; then
239
+ say " $loc — vocabulary entry $entry: $value"
240
+ else
241
+ say " $loc — vocabulary entry $entry ($chars chars, redacted)"
242
+ fi
243
+ done < "$hits"
244
+ if [ "$total" -gt "$MAX_REPORTED" ]; then
245
+ say " … and $((total - MAX_REPORTED)) more."
246
+ fi
247
+
248
+ if [ "${COLAB_IDENTITY_OK:-}" = "1" ]; then
249
+ exit 0
250
+ fi
251
+
252
+ if grep -q '(staged path ' "$hits" 2>/dev/null; then
253
+ say " Resolve a (staged path N) with:"
254
+ say " git diff --cached --name-only --diff-filter=ACMR | sed -n Np"
255
+ fi
256
+
257
+ say ""
258
+ say " The matched text is redacted on purpose — printing it here would republish it into"
259
+ say " your terminal, your shell history and any log that captures them. Vocabulary:"
260
+ say " $vocab ($vocab_src). COLAB_IDENTITY_SHOW=1 unredacts it locally."
261
+ say ""
262
+ say " • Rewrite it with an invented value — a fixture asserts shape, never provenance, so"
263
+ say " an invented value tests exactly as well (CONVENTIONS.md §9)."
264
+ say " • Genuinely a false positive? COLAB_IDENTITY_OK=1 git commit ..."
265
+ say " That override is the operator's call. An agent surfaces this block; it does not"
266
+ say " set the variable for itself."
267
+ exit 1
@@ -0,0 +1,137 @@
1
+ #!/bin/sh
2
+ # pre-push-guard — refuse raw `git push` to protected branches unless a sanctioned path set the env.
3
+ # TRUNK (from .github/project.yml): allowed by COLAB_SHIP=1 (colab ship) or COLAB_HUMAN=1.
4
+ # INTEGRATION lines (project.yml `integration:`): same rule as trunk. Work merges into a declared
5
+ # line exactly the way it merges into trunk — via `colab ship` — so it gets the same door. The
6
+ # line is a DEVELOPMENT integration point: guarding it protects the branch, and nothing here
7
+ # gives it any path to production.
8
+ # MAIN, on tier A and C (trunk != main): allowed by COLAB_PROMOTE=1 (colab promote) or COLAB_HUMAN=1.
9
+ # COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
10
+ # The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
11
+ # automatically — main there is what promotion deploys, so it needs the gate most.
12
+ # RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
13
+ # `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
14
+ # they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
15
+ # uses a branch of either name for something else edits its copy of this hook (copy-and-own).
16
+ # On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
17
+ # Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
18
+ #
19
+ # The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
20
+ # the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
21
+ # process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
22
+ # The refusal messages below therefore name the remedy and not the variable (#322) — this header is
23
+ # the documentation lane, which a human consults deliberately and an error message is not.
24
+ #
25
+ # Install (copy-and-own, per repo):
26
+ # cp templates/pre-push-guard .git/hooks/pre-push && chmod +x .git/hooks/pre-push
27
+ # # or, if you use a shared hooks dir: cp templates/pre-push-guard "$(git config core.hooksPath)/pre-push"
28
+ set -eu
29
+
30
+ root=$(git rev-parse --show-toplevel 2>/dev/null || echo .)
31
+ pj="$root/.github/project.yml"
32
+ if [ ! -f "$pj" ]; then
33
+ echo "pre-push-guard: no .github/project.yml — allowing push (cannot determine trunk)." >&2
34
+ exit 0
35
+ fi
36
+
37
+ trunk=$(sed -n 's/^trunk:[[:space:]]*//p' "$pj" | head -1 | tr -d "\"'" | awk '{print $1}')
38
+ [ -z "$trunk" ] && exit 0
39
+
40
+ # Declared integration lines, in either YAML list form: `integration: [a, b]` or `integration:`
41
+ # followed by ` - a` lines. Same minimal subset the audit tool and the CLI read.
42
+ integration=$(awk '
43
+ /^integration:[[:space:]]*\[/ {
44
+ s = $0; sub(/^[^[]*\[/, "", s); sub(/\].*$/, "", s); gsub(/[,"'"'"']/, " ", s); print s; next
45
+ }
46
+ /^integration:[[:space:]]*$/ { inlist = 1; next }
47
+ inlist && /^[[:space:]]*-[[:space:]]*/ {
48
+ s = $0; sub(/^[[:space:]]*-[[:space:]]*/, "", s); sub(/[[:space:]]*#.*$/, "", s)
49
+ gsub(/["'"'"']/, "", s); print s; next
50
+ }
51
+ inlist && /^[^[:space:]#]/ { inlist = 0 }
52
+ ' "$pj")
53
+
54
+ # Which protected refs are being pushed? (stdin: <localref> <localsha> <remoteref> <remotesha>)
55
+ pushing_trunk=0
56
+ pushing_main=0
57
+ pushing_line=""
58
+ pushing_channel=""
59
+ while read -r _localref _localsha remoteref _remotesha; do
60
+ case "${remoteref:-}" in
61
+ refs/heads/"$trunk") pushing_trunk=1 ;;
62
+ refs/heads/main) pushing_main=1 ;;
63
+ refs/heads/next) pushing_channel=next ;;
64
+ refs/heads/stable) pushing_channel=stable ;;
65
+ esac
66
+ for line in $integration; do
67
+ if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
68
+ done
69
+ done
70
+
71
+ # A REFUSAL NAMES THE REMEDY, NEVER THE DOOR (#322). Each message below used to end with the
72
+ # environment variable that defeats it. That is a bypass printed at the exact moment its reader has
73
+ # run out of ideas, and it was taken: two independent sessions in one day set COLAB_SHIP=1 by hand
74
+ # after this hook refused them, one of them reporting it as ordinary housekeeping. Neither had read
75
+ # it in a skill — they read it HERE. So these messages say what to run; the attended-human override
76
+ # is documented in this file's header and in tools/README.md, where a person looks it up and an
77
+ # agent scanning an error message does not find it.
78
+ #
79
+ # COLAB_SHIP is a PROCESS-IDENTITY assertion — "`colab ship` ran its preconditions" — not a human
80
+ # gate. Typed by hand it asserts that falsely and skips the grade, the branch-CI check, the claim
81
+ # release and the evidence comment. There is no case where typing it is the right next step.
82
+
83
+ # The remote the remedy text below names (#376). git hands a pre-push hook the remote it is pushing
84
+ # to as $1 — the name when the push went through a configured remote, the bare URL when it did not.
85
+ # A name is used as-is: it is the remote this push actually targets, and the one whose tracking ref
86
+ # the reader has. A URL push has no tracking ref of its own, so it falls back to the per-clone
87
+ # override colab itself reads (`git config colab.remote`, tools/README.md "Which remote"), then to
88
+ # `origin`. Message-only: nothing below decides anything on this value.
89
+ remote=${1:-}
90
+ if [ -z "$remote" ] || ! git config --get "remote.$remote.url" >/dev/null 2>&1; then
91
+ remote=$(git config --get colab.remote 2>/dev/null || true)
92
+ [ -z "$remote" ] && remote=origin
93
+ fi
94
+
95
+ # TRUNK guard (also covers tier B, where trunk == main).
96
+ if [ "$pushing_trunk" -eq 1 ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
97
+ echo "pre-push-guard: refusing raw push to trunk '$trunk'." >&2
98
+ echo " Ship the branch instead: colab ship --branch <your-branch>" >&2
99
+ echo " Already committed onto '$trunk' by hand? That commit belongs on a branch, not here:" >&2
100
+ echo " git log --oneline $remote/$trunk..$trunk # what is actually there" >&2
101
+ echo " git branch <type>/<slug>-<issue> $trunk # keep it, on a branch" >&2
102
+ echo " git reset --hard $remote/$trunk # return the checkout to at-rest" >&2
103
+ echo " then claim its issue and ship that branch." >&2
104
+ exit 1
105
+ fi
106
+
107
+ # INTEGRATION-LINE guard — a declared long-lived line is an integration point, not a feature branch.
108
+ if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
109
+ echo "pre-push-guard: refusing raw push to integration line '$pushing_line'." >&2
110
+ echo " Ship the branch instead (it merges into the base the branch was cut from):" >&2
111
+ echo " colab ship --branch <your-branch>" >&2
112
+ exit 1
113
+ fi
114
+
115
+ # RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
116
+ if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
117
+ echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
118
+ echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
119
+ if [ "$pushing_channel" = next ]; then
120
+ echo " colab release cut # a new candidate fast-forwards 'next'" >&2
121
+ else
122
+ echo " colab release finalize # a new final fast-forwards 'stable'" >&2
123
+ fi
124
+ echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
125
+ exit 1
126
+ fi
127
+
128
+ # MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
129
+ if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
130
+ echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
131
+ echo " Promotion is trunk->main and it is a human act on every repo: colab promote" >&2
132
+ echo " There is no agent-side override for this one; if you are an agent, this is where you stop" >&2
133
+ echo " and report, not where you look for a flag." >&2
134
+ exit 1
135
+ fi
136
+
137
+ exit 0