@futurelastic/colab-handbook 1.20.4-rc.9 → 1.21.0-rc.1

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/audit/audit.mjs CHANGED
@@ -123,6 +123,8 @@ const npmGuard = require("../tools/lib/npm-publish-guard.js");
123
123
  const installRoute = require("../tools/lib/install-route.js");
124
124
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
125
125
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
126
+ // #721: a copied CI gate, or one that never skips, is drift — the pure reading lives with its tests.
127
+ const gateDrift = require("../tools/lib/gate-drift.js");
126
128
  const shipBatch = require("../tools/lib/ship-batch.js");
127
129
  const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
128
130
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
@@ -584,6 +586,13 @@ function listRemoteDir(slug, path) {
584
586
  }
585
587
  }
586
588
 
589
+ // #721: one GitHub REST read, parsed — null when it could not be read (offline, no auth, an API error).
590
+ function readRemoteJson(slug, path) {
591
+ const r = remoteCache.get(slug, `repos/${slug}/${path}`);
592
+ if (r.status !== "ok") return null;
593
+ try { return JSON.parse(r.text); } catch { return null; }
594
+ }
595
+
587
596
  function listRemoteBranches(slug) {
588
597
  const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
589
598
  return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
@@ -872,6 +881,12 @@ function makeSource(target) {
872
881
  const slug = url ? githubSlugFromRemote(url) : null;
873
882
  return slug ? readRemoteIssue(slug, num) : null;
874
883
  },
884
+ // #721: a REST read under repos/<slug>/ on the same resolved remote; null = unreadable.
885
+ ghApi: (p) => {
886
+ const url = gitRemote.remoteUrl(root);
887
+ const slug = url ? githubSlugFromRemote(url) : null;
888
+ return slug ? readRemoteJson(slug, p) : null;
889
+ },
875
890
  // Same remote-slug resolution as labels() above, one API call, and only when the
876
891
  // identity scan was explicitly asked for — see readRemoteMetadata for the contract.
877
892
  // An unresolvable remote is its own status, not "no-remote": the scan was asked for
@@ -930,6 +945,7 @@ function makeSource(target) {
930
945
  isLinkedWorktree: () => false,
931
946
  labels: () => listRemoteLabels(target.slug),
932
947
  issue: (num) => readRemoteIssue(target.slug, num),
948
+ ghApi: (p) => readRemoteJson(target.slug, p),
933
949
  // Anchor-link check is local-only by design (#158) — enumerating markdown remotely
934
950
  // would be N `gh api` calls per repo across a fleet sweep. Empty list = the check
935
951
  // scans nothing and emits nothing for a remote source, matching checkRunbook's
@@ -2187,6 +2203,8 @@ function auditRepoInner(target, ctx) {
2187
2203
  info.predatesAxes = [];
2188
2204
  info.suggestions = [];
2189
2205
  const suggest = (t) => info.suggestions.push(t);
2206
+ // #721: the CI dedupe gate maintained once — a copy of it, or a gate that never skips, is drift.
2207
+ checkGateDrift(src, workflows, cfg?.trunk ?? null, warn, { self: isSelf, suggest });
2190
2208
  if (integrationSuggestion) suggest(integrationSuggestion); // #610
2191
2209
  if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
2192
2210
 
@@ -2853,6 +2871,58 @@ function checkInstructionFilesCaller(src, workflows, trunk, warn) {
2853
2871
  for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
2854
2872
  }
2855
2873
 
2874
+ // ---- CI gate drift (#721) ----------------------------------------------------
2875
+ // The dedupe gate lives once, in the handbook's reusable workflow (.github/workflows/ci-light.yml).
2876
+ // Two readings, both warn (drift, not customisation — the repo still owns its files):
2877
+ // 1. a workflow carrying its own copy of the gate instead of calling ci-light.yml — static, always;
2878
+ // 2. a guarded workflow whose last N trunk push runs never skipped although one landed a tree another
2879
+ // ref had already passed green — read from run history, so only where GitHub can be read.
2880
+ // The handbook itself is the source: its ci.yml and ci-light.yml carry the gate by design, so the
2881
+ // static reading is off here (self-audit); the history reading still runs.
2882
+ // Reading 1 is a warn only once the handbook's latest release tag carries ci-light.yml: before that
2883
+ // there is nothing to switch TO (a caller pins a tag), so it is a suggestion — the #607 posture for a
2884
+ // CI copy — and it turns into drift by itself the day a release ships the workflow.
2885
+ let reusableReleasedMemo;
2886
+ function reusableReleased() {
2887
+ if (reusableReleasedMemo !== undefined) return reusableReleasedMemo;
2888
+ const hb = handbookInfo(HANDBOOK_ROOT);
2889
+ reusableReleasedMemo = false;
2890
+ if (hb.hasGit && !hb.untagged) {
2891
+ try {
2892
+ execFileSync("git", ["-C", HANDBOOK_ROOT, "cat-file", "-e", `${hb.version}:${gateDrift.REUSABLE_PATH}`], { stdio: "ignore" });
2893
+ reusableReleasedMemo = hb.version;
2894
+ } catch { reusableReleasedMemo = false; }
2895
+ }
2896
+ return reusableReleasedMemo;
2897
+ }
2898
+ function checkGateDrift(src, workflows, trunk, warn, { self = false, suggest = () => {} } = {}) {
2899
+ const { callers, copies } = gateDrift.copiedGates({ readFile: (p) => src.readFile(p), workflows });
2900
+ if (!self && copies.length) {
2901
+ const released = reusableReleased();
2902
+ for (const wf of copies) {
2903
+ if (released) warn(gateDrift.copiedGateText(wf));
2904
+ else suggest(`${wf}: ${gateDrift.copiedGateText(wf)} — a suggestion until a handbook release tag carries ${gateDrift.REUSABLE_PATH}`);
2905
+ }
2906
+ }
2907
+ if (!trunk || typeof src.ghApi !== "function") return;
2908
+ for (const wf of [...callers, ...copies]) {
2909
+ if (self && wf === "ci-light.yml") continue; // the callee: its runs are its callers'
2910
+ const q = (p) => src.ghApi(`actions/workflows/${encodeURIComponent(wf)}/${p}`);
2911
+ const trunkList = q(`runs?branch=${encodeURIComponent(trunk)}&event=push&status=completed&per_page=${gateDrift.RECENT_TRUNK_RUNS}`);
2912
+ if (!trunkList || !Array.isArray(trunkList.workflow_runs)) continue; // unreadable or offline — say nothing
2913
+ const greenList = q("runs?event=push&status=success&per_page=50"); // the guard's own window (#493)
2914
+ if (!greenList || !Array.isArray(greenList.workflow_runs)) continue;
2915
+ const tree = (r) => (r.head_commit && r.head_commit.tree_id) || null;
2916
+ const trunkRuns = trunkList.workflow_runs.slice(0, gateDrift.RECENT_TRUNK_RUNS).map((r) => {
2917
+ const j = src.ghApi(`actions/runs/${r.id}/jobs?per_page=100`);
2918
+ return { id: r.id, tree: tree(r), created: r.created_at, jobs: j && Array.isArray(j.jobs) ? j.jobs : null };
2919
+ });
2920
+ const greenRuns = greenList.workflow_runs.map((r) => ({ id: r.id, branch: r.head_branch, tree: tree(r), created: r.created_at }));
2921
+ const r = gateDrift.gateNeverSkips({ trunkRuns, greenRuns, trunk });
2922
+ if (r.verdict === "drift") warn(gateDrift.inertGateText(wf, r));
2923
+ }
2924
+ }
2925
+
2856
2926
  // ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
2857
2927
  // The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
2858
2928
  // same finding; this maps its severity onto the audit's fail/warn.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.4-rc.9"
36
+ "version": "1.21.0-rc.1"
37
37
  }
@@ -2,10 +2,11 @@
2
2
 
3
3
  Starting points you **copy into your own repo**. That is the entire model.
4
4
 
5
- > **These are NOT called remotely — with one exception.** `instruction-files.yml` is a caller:
5
+ > **These are NOT called remotely — with two exceptions.** `instruction-files.yml` is a caller:
6
6
  > its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
7
- > kept for compatibility — see *Where each file lives* below). Every other file here is copied,
8
- > not called. (`dist-refs.yml` is a
7
+ > kept for compatibility — see *Where each file lives* below). `ci-call.yml` is the other: it calls
8
+ > the reusable light lane `.github/workflows/ci-light.yml`, pinned to a release tag (#721 — see
9
+ > *The reusable light lane* below). Every other file here is copied, not called. (`dist-refs.yml` is a
9
10
  > `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
10
11
  > `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
11
12
  > handbook told repos to call shared workflows; that was reversed. Every other workflow now
@@ -102,6 +103,7 @@ check that reads one of these files is that tool's behaviour, documented with th
102
103
 
103
104
  | File | Copy to | For | Notes |
104
105
  |---|---|---|---|
106
+ | `ci-call.yml` | `.github/workflows/ci.yml` | Any Node, Python or Laravel repo that wants the light lane **called, not copied** (#721) | **A caller, not a copy:** triggers, concurrency and one `uses:` of the handbook's reusable `.github/workflows/ci-light.yml` — the dedupe gate, the secret scan, a `quick` and a `full` job, job-class `runs-on`. `colab template ci-call` writes this repo's trunk refs and pins the call to the release it stamps. Your commands go in `with:` (`toolchain`, `install`, `quick`, `full`); your own jobs sit beside the call. A copied gate is reported as drift. |
105
107
  | `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. Opt-in `Migration round-trip` job — `--roundtrip` writes it live, see *Migration round-trip* below. |
106
108
  | `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. |
107
109
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step; the `secrets` job's gitleaks install and `GITLEAKS_VERSION` likewise follow the light lane's `gitleaks` job. `TRUNK` is an edit point. |
@@ -176,6 +178,26 @@ The rule all of this keeps: [one verdict per tree](../CONVENTIONS.md#one-verdict
176
178
  Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
177
179
  run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
178
180
 
181
+ ### The reusable light lane — calling instead of copying (#721)
182
+
183
+ The guard above drifted copy by copy: measured across adopters (2026-11-09 → 11-11), missing in six
184
+ repositories and present but never skipping in three, and #717's fix reached a copy only through a manual
185
+ sync. `.github/workflows/ci-light.yml` carries the same guard, the same secret scan and the descriptor check
186
+ once, for every caller; `ci-call.yml` is the caller. What changes for you:
187
+
188
+ - **Only the caller is yours**: the triggers and `concurrency` (a called workflow cannot own either), the
189
+ `with:` block, and your own jobs beside the call. A job behind the gate reads `needs: ci` +
190
+ `if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}`; a trunk-only job outside it is named
191
+ in `trunk-only-jobs` (#717).
192
+ - **Pinned to a release tag, never `main`.** `colab template ci-call` writes the version it stamps the copy
193
+ with; `colab update` moves a pristine copy's stamp and pin together.
194
+ - **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
195
+ and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
196
+ and both take the `trunk` class on a trunk ref under `runs-on: classes`.
197
+ - The copied `ci-<stack>.yml` templates still work and are still copied; moving them onto the caller is
198
+ tracked in #724. A repo carrying one is reported as drift — a suggestion until a handbook release tag carries
199
+ `ci-light.yml`, a warning from then on.
200
+
179
201
  ### Migration round-trip — have it from the first copy
180
202
 
181
203
  `migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
@@ -0,0 +1,73 @@
1
+ # CI (light lane) — CALLER of the handbook's reusable workflow (#721). Copy to .github/workflows/ci.yml
2
+ # with `colab template ci-call --dest .github/workflows/ci.yml`: it writes this repo's trunk refs and pins the call to the handbook
3
+ # release it stamps the copy with. Unlike templates/ci-<stack>.yml, nothing below the `uses:` line is
4
+ # yours to maintain — the dedupe gate, the secret scan, the quick/full split and the job-class
5
+ # `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
6
+ #
7
+ # EDIT POINTS are marked `# EDIT:` — the `with:` block is the only real one.
8
+ #
9
+ # Kept HERE because a called workflow cannot declare them (CONVENTIONS.md §7, "One verdict per tree"):
10
+ # - the triggers: every branch (#384 — a candidate gets a run of its own before the merge; '**'
11
+ # also covers `ship-batch/**`), no `pull_request` beside push (#512), and workflow_dispatch (the
12
+ # release workflow dispatches CI on a promotion its token cannot trigger, #440);
13
+ # - concurrency: one live run per branch, a trunk run never cancelled and in a group of its own (#512).
14
+ # Its trunk refs and the `trunk-branches` input name the same branches — `colab template` writes both.
15
+ name: CI
16
+
17
+ on:
18
+ push:
19
+ branches: ['**']
20
+ workflow_dispatch:
21
+
22
+ concurrency:
23
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
24
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
25
+
26
+ # The called jobs can only narrow these: the gate lists this workflow's runs and reads git objects.
27
+ permissions:
28
+ actions: read
29
+ contents: read
30
+
31
+ jobs:
32
+ ci:
33
+ # Pinned to a handbook release, never a branch: a caller tracking `main` would take every gate
34
+ # change the moment it merges there, untested against this repo. Move the tag deliberately
35
+ # (`colab update` refreshes a pristine copy to the current release).
36
+ uses: futurelastic/colab-handbook/.github/workflows/ci-light.yml@HANDBOOK_TAG
37
+ with:
38
+ trunk-branches: '["main","dev"]'
39
+ # EDIT: one stack — keep the lines for yours, delete the rest. Versions are resolved from
40
+ # .github/project.yml, then the manifest (.nvmrc / engines.node, .python-version /
41
+ # requires-python, composer.json require.php); none declared fails the job, never a default.
42
+ #
43
+ # Node:
44
+ toolchain: node
45
+ install: auto # npm ci / pnpm install --frozen-lockfile, from the lockfile
46
+ quick: npm run --if-present typecheck && npm run --if-present lint
47
+ full: npm test --if-present && npm run --if-present build
48
+ #
49
+ # Python:
50
+ # toolchain: python
51
+ # install: auto # pip install -e . (or -r requirements.txt), then requirements-dev.txt
52
+ # quick: python -m ruff check . && python -m mypy src
53
+ # full: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
54
+ #
55
+ # Laravel (PHP + Vite):
56
+ # toolchain: php,node
57
+ # install: auto # composer install, then npm ci
58
+ # quick: vendor/bin/pint --test
59
+ # full: cp .env.example .env && php artisan key:generate && npm run build && php artisan migrate --force && vendor/bin/pest --ci --exclude-group=heavy
60
+ #
61
+ # EDIT: self-hosted runners — `classes` runs each job on ["self-hosted", <class>]: `trunk` on a
62
+ # trunk ref, else `quick` or `full` (CONVENTIONS.md §7, "Runner classes"). A public repo keeps
63
+ # the default, ubuntu-latest. A bare label or a JSON label list also works.
64
+ # runs-on: classes
65
+ # runner-lane: my-repo-lane # only for a capped lane (rule 3)
66
+ #
67
+ # EDIT: name your trunk-only jobs below (deploy, publish) when they sit outside the gate (#717).
68
+ # trunk-only-jobs: Deploy
69
+
70
+ # Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
71
+ # needs: ci
72
+ # if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}
73
+ # Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
package/tools/colab CHANGED
@@ -10113,6 +10113,17 @@ function cmdTemplate(argv) {
10113
10113
  if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
10114
10114
  }
10115
10115
  }
10116
+ // #721: the reusable-workflow caller calls the handbook version this copy is stamped with.
10117
+ if (ext === 'yml') {
10118
+ const pin = require('./lib/template-trunk').pinHandbookTag(body, version);
10119
+ body = pin.text;
10120
+ if (pin.pinned) trunkNotes.push(` pin: calls the reusable workflow at ${pin.pinned} — the version this copy is stamped with.`);
10121
+ if (pin.pinned && stamp.handbookInfo(root).hasGit) {
10122
+ const cr = spawnSync('git', ['-C', root, 'cat-file', '-e', `${pin.pinned}:.github/workflows/ci-light.yml`], { stdio: 'ignore' });
10123
+ if (!cr.error && cr.status !== 0) trunkNotes.push(` ⚠ pin: ${pin.pinned} does not carry .github/workflows/ci-light.yml — this copy cannot run until it calls a release that does; set the tag by hand.`);
10124
+ }
10125
+ if (pin.unpinned) trunkNotes.push(' ⚠ pin: the handbook has no tag, so `@HANDBOOK_TAG` is left in place — set it to a release tag that carries .github/workflows/ci-light.yml.');
10126
+ }
10116
10127
  // #625: the round-trip job written live, at copy — the commit that creates the workflows.
10117
10128
  const roundtripNotes = [];
10118
10129
  if (opts.roundtrip && roundtrip.ALWAYS_ON.has(stem)) {
@@ -10261,7 +10272,7 @@ function inspectRepo(entry, ctx) {
10261
10272
  const c = stamp.classifyStamped({
10262
10273
  root: ctx.handbookRoot, hb: ctx.hb, tmplNames: ctx.tmplNames,
10263
10274
  templateName: st.name, stampVersion: st.version, localText: text, comparable: true,
10264
- render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc),
10275
+ render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc, st.version),
10265
10276
  });
10266
10277
  artifacts.push({ file: rel, template: st.name, applicable: c.state === 'behind', ...c });
10267
10278
  } else {
@@ -10355,7 +10366,7 @@ function refreshArtifact(repo, art, ctx) {
10355
10366
  const src = path.join(ctx.templatesDir, `${art.template}.yml`);
10356
10367
  if (!fs.existsSync(src)) return { ok: false, err: `template ${art.template}.yml is not in the handbook` };
10357
10368
  // Rendered exactly as `colab template <name> --force` would write it here (#526).
10358
- const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path));
10369
+ const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path), ctx.hb.version);
10359
10370
  const dest = path.join(repo.path, art.file);
10360
10371
  try {
10361
10372
  fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -12054,6 +12065,37 @@ function pushVerifiedWorkflowsAt(repoAbs, sha) {
12054
12065
  return names;
12055
12066
  }
12056
12067
 
12068
+ /**
12069
+ * #723: the workflows that SHOULD have a push run at `sha`, the head of `branch` — read from the
12070
+ * workflow files at that sha, the head commit's message (a skip directive), the repo's policy and the
12071
+ * workflows API's state (verify-runs.js `expectedWorkflows`). Null when the tree cannot be read (the
12072
+ * commit is not local and one fetch does not bring it): no expected set, so the runs that exist
12073
+ * decide, as before. GitHub only — a forge's commit statuses carry no workflow identity to match.
12074
+ */
12075
+ function expectedWorkflowsAt(repoAbs, sha, branch) {
12076
+ if (!sha || !branch) return null;
12077
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
12078
+ git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
12079
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
12080
+ }
12081
+ const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
12082
+ const defs = [];
12083
+ if (ls.ok) {
12084
+ for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
12085
+ const rel = `.github/workflows/${f}`;
12086
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
12087
+ if (show.ok) defs.push({ path: rel, text: show.stdout });
12088
+ }
12089
+ }
12090
+ if (!defs.length) return { expected: [], skipDirective: false };
12091
+ const msg = git.git(['log', '-1', '--format=%B', sha], repoAbs);
12092
+ const headMessage = msg.ok ? msg.stdout : null;
12093
+ if (verifyRuns.skipsWorkflows(headMessage)) return { expected: [], skipDirective: true }; // no API call spent
12094
+ return verifyRuns.expectedWorkflows({
12095
+ defs, branch, policy: verifyRuns.parsePolicy(projectDoc(repoAbs)), states: git.ghWorkflowStates(repoAbs), headMessage,
12096
+ });
12097
+ }
12098
+
12057
12099
  /** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
12058
12100
  function trunkWorkflowFiles(repoAbs, sha) {
12059
12101
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
@@ -12479,7 +12521,9 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12479
12521
  // head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
12480
12522
  const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
12481
12523
  run = git.summarizeRunsForCommit(rows, headSha);
12482
- verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true });
12524
+ // #723: the workflows that should have fired at the head — one with no run there holds the head row.
12525
+ const exp = rows ? expectedWorkflowsAt(repoAbs, headSha, branch) : null;
12526
+ verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true, expected: exp ? exp.expected : [] });
12483
12527
  }
12484
12528
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12485
12529
  // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
@@ -16863,6 +16907,15 @@ Exit codes — branch on these, never on the text:
16863
16907
  4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
16864
16908
  5 UNKNOWN a read failed or returned a state it cannot classify
16865
16909
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
16910
+ 7 NO_RUN --sha with --branch: the deadline passed and a workflow whose definition at the
16911
+ head fires on a push to that branch still had NO run there (#723). The runs that
16912
+ do exist never stand in for it, so such a head is pending, never GREEN. The
16913
+ output names it (\`no-run:<workflow>\`) and how to get it a run — a hint only
16914
+
16915
+ Expected at a branch head (#723): a workflow file at the head sha triggered by \`push\`, whose
16916
+ branch filters match the branch, with no \`paths\`/\`paths-ignore\` filter, in ship-gate-workflows
16917
+ when declared, not in ship-ignore-workflows, and not disabled. None when the head commit carries a
16918
+ skip directive ([skip ci] …). Any doubt (an unreadable filter, an unread tree) means not expected.
16866
16919
 
16867
16920
  On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
16868
16921
  combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
@@ -16870,7 +16923,7 @@ is a usage error there. RED and --json name the contexts that are not green (\`n
16870
16923
 
16871
16924
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
16872
16925
  --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
16873
- detail, status, conclusion, url, notGreen? }`;
16926
+ detail, status, conclusion, url, notGreen?, missing?, hint? }`;
16874
16927
 
16875
16928
  function cmdCiWait(argv) {
16876
16929
  const opts = parseArgs(argv, {
@@ -16938,6 +16991,10 @@ function cmdCiWait(argv) {
16938
16991
  }
16939
16992
 
16940
16993
  const verifyPolicy = verifyingPolicy(repoAbs);
16994
+ // #723: on a branch head, the workflows that should have a run there — read once, before the loop. A
16995
+ // missing one holds green as pending and ends the wait NO_RUN (exit 7) at the deadline.
16996
+ const expectedSet = !fc && !runId && opts.branch ? expectedWorkflowsAt(repoAbs, opts.sha, opts.branch) : null;
16997
+ const expected = expectedSet ? expectedSet.expected : [];
16941
16998
  // #681: inside a Forgejo Actions run (the release workflow waiting on CI at its own sha) the calling
16942
16999
  // workflow's own contexts are dropped — a run never waits on itself (#425's rule; a no-op elsewhere).
16943
17000
  const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null, rowsFilter: (rows) => releaseCut.withoutOwnWorkflow(rows) }), fc.kind) : (etag) => {
@@ -16960,7 +17017,7 @@ function cmdCiWait(argv) {
16960
17017
  }
16961
17018
  // #503: the same verifying-runs policy ship reads — a wait on trunk's head ends when the CI
16962
17019
  // that verifies the code ends, not when the post-CI release run does.
16963
- summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy });
17020
+ summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy, expected });
16964
17021
  const pick = rows.find((x) => x.databaseId === summary.databaseId);
16965
17022
  summary = { ...summary, url: pick ? pick.url : null };
16966
17023
  }
@@ -16985,13 +17042,14 @@ function cmdCiWait(argv) {
16985
17042
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
16986
17043
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
16987
17044
  ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
17045
+ ...(Array.isArray(s.missing) && s.missing.length ? { missing: s.missing, hint: verifyRuns.missingHint(s.missing, opts.branch) } : {}), // #723
16988
17046
  ...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
16989
17047
  ...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
16990
17048
  };
16991
17049
  if (opts.json) print(JSON.stringify(out, null, 2));
16992
17050
  else {
16993
17051
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
16994
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
17052
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${verifyRuns.missingNote(s.missing, opts.branch)}${readViaNote(s)}${notGreenNote(s)}`);
16995
17053
  }
16996
17054
  return code;
16997
17055
  }
@@ -35,6 +35,9 @@ const EXIT = Object.freeze({
35
35
  RATE_LIMITED: 4,
36
36
  UNKNOWN: 5,
37
37
  ALREADY_WAITING: 6,
38
+ // #723: the deadline passed with an expected workflow still having NO run at the sha (only other
39
+ // workflows ran there). Not TIMEOUT: nothing is in flight to wait longer for — someone must get it a run.
40
+ NO_RUN: 7,
38
41
  });
39
42
 
40
43
  const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
@@ -112,10 +115,15 @@ function restRow(x) {
112
115
  * The state of what is being waited on, from a summarized run (`{status, conclusion}`):
113
116
  * `green` · `red` · `pending` · `unknown`. `none` (no run at the sha yet) is pending: runs appear
114
117
  * seconds after a push, and the deadline bounds the wait if they never do.
118
+ *
119
+ * #723: a summary carrying `missing` (an expected workflow with no run at the sha) is never green —
120
+ * it is pending, like `none`: the run may still appear, and the deadline ends the wait as NO_RUN.
121
+ * A red stays red: a failure that already happened does not wait on a run that has not.
115
122
  */
116
123
  function runState(s) {
117
124
  if (!s) return 'unknown';
118
125
  if (s.status === 'none') return 'pending';
126
+ if (Array.isArray(s.missing) && s.missing.length && s.status === 'completed' && s.conclusion === 'success') return 'pending';
119
127
  if (s.status === 'completed') return s.conclusion === 'success' ? 'green' : 'red';
120
128
  if (['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(s.status)) return 'pending';
121
129
  return 'unknown';
@@ -162,7 +170,7 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
162
170
  const d = delayFor(i, schedule) * 1000;
163
171
  if (d) {
164
172
  const left = start + deadlineSec * 1000 - now();
165
- if (left <= 0) return done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
173
+ if (left <= 0) return deadline(`still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
166
174
  sleep(Math.min(d, left));
167
175
  }
168
176
  // The poll that lands on the deadline is the last one: it must read the truth, not a 304.
@@ -186,7 +194,13 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
186
194
  if (last.state === 'green') return done('GREEN', null);
187
195
  if (last.state === 'red') return done('RED', null);
188
196
  if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
189
- if (now() - start >= deadlineSec * 1000) return done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
197
+ if (now() - start >= deadlineSec * 1000) return deadline(`still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
198
+ }
199
+ // #723: a deadline that passes with an expected workflow still runless is NO_RUN, naming it.
200
+ function deadline(detail) {
201
+ const miss = last && last.summary && Array.isArray(last.summary.missing) ? last.summary.missing : [];
202
+ if (!miss.length) return done('TIMEOUT', detail);
203
+ return done('NO_RUN', `no-run:${miss.map((x) => x.name).join(',')} — no run of ${miss.length === 1 ? 'that workflow' : 'those workflows'} appeared by the ${fmtDuration(deadlineSec * 1000)} deadline`);
190
204
  }
191
205
  function done(outcome, detail, r) {
192
206
  return { outcome, polls, notModified, forced, waitedMs: now() - start, last: last || r || null, detail };
@@ -0,0 +1,110 @@
1
+ 'use strict';
2
+ /**
3
+ * CI gate drift (#721) — the pure half of two audit findings. No gh, no git, no I/O.
4
+ *
5
+ * The dedupe gate (CONVENTIONS.md §7, "One verdict per tree") used to live only in copies: each
6
+ * adopter copied a light CI template and owned the copy, so the gate drifted copy by copy — measured
7
+ * across adopters 2026-11-09 → 11-11, missing in six repositories and present but never skipping in
8
+ * three — and a template fix (#717) reached a copy only through a manual sync. The gate now lives once,
9
+ * in the handbook's reusable workflow (.github/workflows/ci-light.yml), and these two readings report
10
+ * what is left as DRIFT, not customisation:
11
+ *
12
+ * 1. copiedGates — a workflow that carries its own copy of the gate (its coined step name, or the
13
+ * guard's GUARD_NAME env) instead of calling ci-light.yml. Content decides, never the filename.
14
+ * 2. gateNeverSkips — of a guarded workflow's last N trunk push runs, at least one landed a tree a
15
+ * green push run on another ref had already passed, yet none of the N skipped: the gate is
16
+ * present and inert (a renamed guard, a trunk ref missing from its `if:`, a skip-chained run…).
17
+ * Read from run history, so it catches a gate that LOOKS right.
18
+ */
19
+
20
+ /** The workflow a caller names; `./.github/…` (a local call) and `owner/repo/.github/…@ref` both count. */
21
+ const REUSABLE_PATH = '.github/workflows/ci-light.yml';
22
+ const CALLER_RE = /^\s*uses:\s*["']?(?:\.\/|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/)\.github\/workflows\/ci-light\.ya?ml(?:@[^\s"'#]+)?["']?\s*(?:#.*)?$/m;
23
+ /** The guard's coined step name (every light template since #418/#493), or its GUARD_NAME env (#511). */
24
+ const GATE_STEP_RE = /^\s*-\s*name:\s*["']?Look for a green run of this workflow at this sha(?: or tree)?["']?\s*$/m;
25
+ const GATE_ENV_RE = /^\s*GUARD_NAME:\s*\S/m;
26
+ /** How many trunk runs the inert-gate reading looks back over. */
27
+ const RECENT_TRUNK_RUNS = 10;
28
+ const GUARD_NAME = 'Already tested at this sha or tree?';
29
+
30
+ function isCiLightCaller(text) { return !!text && CALLER_RE.test(text); }
31
+ function hasCopiedGate(text) { return !!text && !isCiLightCaller(text) && (GATE_STEP_RE.test(text) || GATE_ENV_RE.test(text)); }
32
+
33
+ /**
34
+ * { callers: [file], copies: [file] } over `.github/workflows/<file>`. A workflow both calling
35
+ * ci-light.yml and carrying a gate step is a caller (the call is the gate; the step would be dead).
36
+ */
37
+ function copiedGates({ readFile, workflows }) {
38
+ const callers = [];
39
+ const copies = [];
40
+ for (const wf of workflows || []) {
41
+ const text = readFile(`.github/workflows/${wf}`);
42
+ if (isCiLightCaller(text)) callers.push(wf);
43
+ else if (hasCopiedGate(text)) copies.push(wf);
44
+ }
45
+ return { callers, copies };
46
+ }
47
+
48
+ /**
49
+ * Did one trunk run skip its suite through the gate? From its jobs (`[{name, conclusion}]`): the
50
+ * guard (by name, or as a called "<caller> / <guard>") succeeded and some other job was skipped.
51
+ * On trunk the guard always runs, and a job other than it skips there only when the gate said
52
+ * tested — or for a reason of its own (an opt-in job switched off), which reads as a skip and so can
53
+ * only HIDE drift, never invent it. null in → null out (an unreadable listing is not "no").
54
+ */
55
+ function runSkipped(jobs) {
56
+ if (!Array.isArray(jobs)) return null;
57
+ const isGuard = (n) => n === GUARD_NAME || String(n).endsWith(` / ${GUARD_NAME}`);
58
+ const guardOk = jobs.some((j) => j && isGuard(j.name) && j.conclusion === 'success');
59
+ return guardOk && jobs.some((j) => j && !isGuard(j.name) && j.conclusion === 'skipped');
60
+ }
61
+
62
+ /**
63
+ * The inert-gate reading. trunkRuns: newest first, [{id, tree, created, jobs}] — `jobs` as runSkipped
64
+ * reads it; greenRuns: [{id, branch, tree, created}] green push runs of the same workflow on any ref.
65
+ * Returns { verdict: 'drift' | 'ok' | 'unknown', considered, matched: [{trunk, cited}], reason }:
66
+ * - unknown: no trunk run to read, or a listing could not be read (`null` jobs) — say nothing;
67
+ * - ok: some run skipped, or no run in the window had a green tree to reuse (nothing to skip);
68
+ * - drift: at least one had one, and none of the window skipped.
69
+ */
70
+ function gateNeverSkips({ trunkRuns, greenRuns, trunk, n = RECENT_TRUNK_RUNS }) {
71
+ if (!Array.isArray(trunkRuns) || !Array.isArray(greenRuns)) return { verdict: 'unknown', considered: 0, matched: [], reason: 'run history unreadable' };
72
+ const window = trunkRuns.slice(0, n);
73
+ if (!window.length) return { verdict: 'unknown', considered: 0, matched: [], reason: 'no trunk push run yet' };
74
+ const t = (x) => Date.parse(x) || 0;
75
+ const matched = [];
76
+ let skipped = 0;
77
+ for (const r of window) {
78
+ const s = runSkipped(r.jobs);
79
+ if (s === null) return { verdict: 'unknown', considered: window.length, matched: [], reason: `the jobs of run ${r.id} could not be read` };
80
+ if (s) { skipped++; continue; }
81
+ if (!r.tree) continue;
82
+ const cited = greenRuns.find((g) => g && g.tree === r.tree && g.id !== r.id && g.branch !== trunk && t(g.created) <= t(r.created));
83
+ if (cited) matched.push({ trunk: r.id, cited: cited.id, branch: cited.branch });
84
+ }
85
+ if (skipped) return { verdict: 'ok', considered: window.length, matched, reason: `${skipped} of the last ${window.length} trunk runs skipped through the gate` };
86
+ if (!matched.length) return { verdict: 'ok', considered: window.length, matched, reason: `no trunk run of the last ${window.length} landed a tree a branch had already passed` };
87
+ return {
88
+ verdict: 'drift', considered: window.length, matched,
89
+ reason: `none of the last ${window.length} trunk runs skipped, yet ${matched.length} landed a tree another ref had already passed green`,
90
+ };
91
+ }
92
+
93
+ /** The audit's two finding texts — one place, so the wording the docs quote cannot drift from the code. */
94
+ function copiedGateText(wf) {
95
+ return `drift: .github/workflows/${wf} carries its own copy of the CI dedupe gate instead of calling the handbook's ` +
96
+ `reusable workflow (${REUSABLE_PATH}) — a copy changes only by a manual sync, so a gate fix never reaches it ` +
97
+ '(#717 did not). Switch to templates/ci-call.yml (`colab template ci-call --dest .github/workflows/<this file>`) (#721)';
98
+ }
99
+ function inertGateText(wf, r) {
100
+ const ex = r.matched[0];
101
+ return `drift: the dedupe gate in .github/workflows/${wf} never skipped — ${r.reason} ` +
102
+ `(e.g. trunk run ${ex.trunk} could have cited run ${ex.cited} on ${ex.branch}). A gate that is present but inert ` +
103
+ 'runs every landing twice; check the guard\'s `if:` names this trunk and GUARD_NAME is its job\'s name, or call ' +
104
+ `${REUSABLE_PATH} (templates/ci-call.yml) (#721)`;
105
+ }
106
+
107
+ module.exports = {
108
+ REUSABLE_PATH, RECENT_TRUNK_RUNS, GUARD_NAME,
109
+ isCiLightCaller, hasCopiedGate, copiedGates, runSkipped, gateNeverSkips, copiedGateText, inertGateText,
110
+ };
package/tools/lib/git.js CHANGED
@@ -1156,6 +1156,23 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
1156
1156
  return runs.filter((x) => x && x.headSha === sha);
1157
1157
  }
1158
1158
 
1159
+ /**
1160
+ * #723: the repo's workflows as a Map of file path → `{ state, id, name }` — one REST call. `state`
1161
+ * (`active`, `disabled_manually`, …): a disabled workflow never gets a run, so it is never expected at
1162
+ * a head. `id` / `name` are how its runs identify it (a run's `workflow_id`, its `name`). Null on any
1163
+ * failure: the caller then takes every workflow as active and matches runs by the definition's name.
1164
+ */
1165
+ function ghWorkflowStates(repo) {
1166
+ const r = gh(['api', 'repos/{owner}/{repo}/actions/workflows?per_page=100'], { cwd: repo });
1167
+ if (!r.ok) return null;
1168
+ let j;
1169
+ try { j = JSON.parse(r.stdout); } catch (_) { return null; }
1170
+ if (!j || !Array.isArray(j.workflows)) return null;
1171
+ const m = new Map();
1172
+ for (const w of j.workflows) if (w && w.path) m.set(w.path, { state: w.state || null, id: w.id ?? null, name: w.name || null });
1173
+ return m;
1174
+ }
1175
+
1159
1176
  function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
1160
1177
  return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
1161
1178
  }
@@ -1267,6 +1284,14 @@ function excludedRunSummary(rows) {
1267
1284
  * #688: a workflow whose every run at the sha was skipped is then set aside beside a run that can
1268
1285
  * verify the code (setAsideWhollySkipped, below); the rows ride along as `skippedOnly`, and `allSkipped`
1269
1286
  * says nothing but such workflows ran here. `runCount` no longer counts them (#461's rule).
1287
+ *
1288
+ * #723: `opts.expected` (verify-runs.js `expectedWorkflows(...).expected`, `[{name, path, dispatch}]`)
1289
+ * names the workflows that SHOULD have a run at the sha. One with no counted row there rides along as
1290
+ * `missing` (same entries), present only when non-empty. The summary's status and conclusion are left
1291
+ * exactly as the runs that exist make them — a caller that asked for `expected` reads `missing` and
1292
+ * holds a would-be green (ci-wait.runState, stale-base.githubBranchHeadRedVerdict). Measured: only a
1293
+ * small `instruction-files` workflow ran at a branch head, the repo's CI never got a run there, and the
1294
+ * head read green from that one unrelated run.
1270
1295
  */
1271
1296
  function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1272
1297
  if (allForSha === null) return null;
@@ -1280,6 +1305,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1280
1305
  setAside = split.setAside;
1281
1306
  dispatchCounted = split.dispatchCounted || [];
1282
1307
  }
1308
+ const missing = missingExpected(owned, opts && opts.expected);
1283
1309
  const { heads, superseded } = newestRunPerWorkflow(owned);
1284
1310
  const { judged, skippedOnly, allSkipped } = setAsideWhollySkipped(heads, superseded, opts && opts.verifying);
1285
1311
  const extra = {
@@ -1289,6 +1315,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1289
1315
  ...(allSkipped ? { allSkipped: true } : {}),
1290
1316
  ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1291
1317
  ...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
1318
+ ...(missing.length ? { missing: missing.map((e) => ({ name: e.name, path: e.path || null, dispatch: !!e.dispatch, ...(e.id != null ? { id: e.id } : {}) })) } : {}),
1292
1319
  // #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
1293
1320
  // JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
1294
1321
  // those two executed anything). The summary's single `conclusion` names only the first not-green
@@ -1302,6 +1329,22 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1302
1329
  return { ...r, ...extra };
1303
1330
  }
1304
1331
 
1332
+ /**
1333
+ * #723: the expected workflows with no counted row at the sha. A row stands for an expected workflow
1334
+ * when its workflow FILE id matches (`workflowId`, the workflows API's id), or its name matches the
1335
+ * definition's or the API's. A row carrying neither a name nor an id cannot be told apart from any
1336
+ * workflow, so its presence means nothing is called missing — absence of a field never adds a hold,
1337
+ * the same rule as everywhere above.
1338
+ */
1339
+ function missingExpected(rows, expected) {
1340
+ const exp = Array.isArray(expected) ? expected.filter((e) => e && e.name) : [];
1341
+ if (!exp.length) return [];
1342
+ if (rows.some((x) => x && !x.workflowName && (x.workflowId === undefined || x.workflowId === null))) return [];
1343
+ const stands = (x, e) => !!x && ((e.id != null && x.workflowId != null && Number(x.workflowId) === Number(e.id))
1344
+ || x.workflowName === e.name || (!!e.apiName && x.workflowName === e.apiName));
1345
+ return exp.filter((e) => !rows.some((x) => stands(x, e)));
1346
+ }
1347
+
1305
1348
  /** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
1306
1349
  function isFinishedRed(x) {
1307
1350
  return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
@@ -1624,7 +1667,7 @@ module.exports = {
1624
1667
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1625
1668
  dirtyTracked, dirtyUntracked, dirtyAny,
1626
1669
  ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghRunsAtShaUnfiltered, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1627
- ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1670
+ ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghWorkflowStates, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1628
1671
  ghRunJobCount, ghRunJobs, ghActiveRunsOfWorkflow, ghWorkflowDispatch,
1629
1672
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1630
1673
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
@@ -141,19 +141,32 @@ function branchHeadCiVerdict(a) {
141
141
  * refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
142
142
  * summary's own status/conclusion decides.
143
143
  *
144
+ * #723: a head where an EXPECTED workflow has no run (`run.missing`, git.summarizeRunsForCommit's
145
+ * `opts.expected`) is pending, self-clearing, never a pass: ship --dry used to read READY on a head
146
+ * where only an unrelated workflow had run and the repo's CI never got a run at all. A red still wins
147
+ * (it is checked first). The detail names the missing workflow and how to get it a run — a hint only.
148
+ *
144
149
  * @param {object} a
145
150
  * @param {string|null} a.headSha - the branch head on the remote
146
151
  * @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
147
152
  * @param {string} a.branch
148
- * @returns {null|{ok:false, verdict:'red', selfClearing:false, detail:string}}
153
+ * @returns {null|{ok:false, verdict:'red'|'pending', selfClearing:boolean, detail:string}}
149
154
  */
150
155
  function githubBranchHeadRedVerdict(a) {
151
156
  const run = a && a.run;
152
157
  if (!a || !a.headSha || !run || run.status === 'none') return null;
153
158
  const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
154
159
  const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
155
- if (!listed.length && !summaryRed) return null;
156
160
  const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
161
+ const missing = Array.isArray(run.missing) ? run.missing : [];
162
+ if (!listed.length && !summaryRed) {
163
+ if (!missing.length) return null;
164
+ const { missingHint } = require('./verify-runs');
165
+ return { ok: false, verdict: 'pending', selfClearing: true,
166
+ detail: `${at} has no run of ${missing.map((x) => x.name).join(', ')}, though ${missing.length === 1 ? 'its' : 'their'} definition fires on a push to this branch — ` +
167
+ `the runs that exist there do not stand in for it (#723). Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`; ` +
168
+ `if it ends NO_RUN (exit 7), ${missingHint(missing, a.branch)}` };
169
+ }
157
170
  const failing = listed.length
158
171
  ? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
159
172
  : `conclusion=${run.conclusion || 'none'}`;
@@ -54,7 +54,11 @@ function substituteTrunk(text, p) {
54
54
  swap('concurrency group', `(${tplEq.join(' || ')}) && format(`, `(${p.refs.map(eq).join(' || ')}) && format(`);
55
55
  swap('cancel-in-progress', `cancel-in-progress: \${{ ${TEMPLATE_REFS.map(ne).join(' && ')} }}`,
56
56
  `cancel-in-progress: \${{ ${p.refs.map(ne).join(' && ')} }}`);
57
- swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
57
+ // #721: the reusable-workflow caller (templates/ci-call.yml) names its trunk refs in the `trunk-branches`
58
+ // input instead of a guard `if:` of its own — the guard lives in the called workflow.
59
+ const tplList = `trunk-branches: '${JSON.stringify(TEMPLATE_REFS)}'`;
60
+ if (out.includes(tplList)) swap('trunk-branches input', tplList, `trunk-branches: '${JSON.stringify(p.refs)}'`);
61
+ else swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
58
62
  // ci-laravel's test tier (only present there): the release-gating branch is the trunk on a one-branch repo.
59
63
  if (!p.twoBranch && p.trunk !== 'main' && out.includes('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')) {
60
64
  out = out.split('[ "$BASE_REF" = "main" ]').join(`[ "$BASE_REF" = "${p.trunk}" ]`);
@@ -71,10 +75,25 @@ function substituteTrunk(text, p) {
71
75
  * `colab update` uses the same rendering both to recognise a pristine copy and to refresh one, so
72
76
  * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
73
77
  */
74
- function renderForRepo(name, body, doc) {
78
+ function renderForRepo(name, body, doc, version) {
75
79
  if (!/^ci-/.test(String(name || ''))) return body;
80
+ const pinned = version ? pinHandbookTag(body, version).text : body;
76
81
  const p = protectedRefs(doc);
77
- return p ? substituteTrunk(body, p).text : body;
82
+ return p ? substituteTrunk(pinned, p).text : pinned;
78
83
  }
79
84
 
80
- module.exports = { TEMPLATE_REFS, protectedRefs, substituteTrunk, renderForRepo };
85
+ /**
86
+ * #721: the reusable-workflow caller pins the handbook by tag — `uses: …/ci-light.yml@HANDBOOK_TAG`
87
+ * in the template. A copy is written with the version its stamp records, so "copied from handbook X"
88
+ * and "calls handbook X" are one fact, and a refresh moves both together. `v0` (an untagged handbook)
89
+ * pins nothing: there is no tag to call, and the token is left for the copier to see.
90
+ */
91
+ const HANDBOOK_TAG = 'HANDBOOK_TAG';
92
+ function pinHandbookTag(text, version) {
93
+ const token = `@${HANDBOOK_TAG}`;
94
+ if (!String(text).includes(token)) return { text, pinned: null };
95
+ if (!version || version === 'v0') return { text, pinned: null, unpinned: true };
96
+ return { text: text.split(token).join(`@${version}`), pinned: version };
97
+ }
98
+
99
+ module.exports = { TEMPLATE_REFS, HANDBOOK_TAG, protectedRefs, substituteTrunk, renderForRepo, pinHandbookTag };
@@ -150,6 +150,28 @@ const BRANCH_TRIGGERS = Object.freeze(['push', 'pull_request', 'pull_request_tar
150
150
  * of the three `on:` shapes (scalar, flow list, block map / block list) — not a YAML parser.
151
151
  */
152
152
  function workflowTriggers(text) {
153
+ const parsed = onEvents(text);
154
+ if (!parsed) return null;
155
+ const { name, events } = parsed;
156
+ let verifies = false;
157
+ for (const [ev, e] of events) {
158
+ if (!BRANCH_TRIGGERS.includes(ev)) continue;
159
+ if (ev !== 'push') { verifies = true; break; }
160
+ const keys = e.body.map((b) => (/^([A-Za-z_-]+)\s*:/.exec(b.text) || [])[1]).filter(Boolean);
161
+ const tagsOnly = (keys.includes('tags') || keys.includes('tags-ignore')) && !keys.includes('branches') && !keys.includes('branches-ignore');
162
+ if (!tagsOnly) { verifies = true; break; }
163
+ }
164
+ return { name, verifiesBranches: verifies };
165
+ }
166
+
167
+ /**
168
+ * The top-level `name:` and the `on:` events of one workflow file: `{ name, events }`, or null when
169
+ * the text has no top-level `on:`. `events` maps an event name to `{ inline, body }` — `inline` is
170
+ * what follows `<event>:` on its own line ('' for the block form), `body` the child lines with their
171
+ * indent (`{ indent, text }`, text trimmed). The scalar and flow-list forms of `on:` give events with
172
+ * no inline value and no body. Shared by workflowTriggers (#567) and pushTrigger (#723).
173
+ */
174
+ function onEvents(text) {
153
175
  const lines = String(text || '').split(/\r?\n/);
154
176
  let name = null;
155
177
  let onIdx = -1;
@@ -162,10 +184,10 @@ function workflowTriggers(text) {
162
184
  if (m && onIdx < 0) { onIdx = i; onInline = yamlScalar(m[1]); }
163
185
  }
164
186
  if (onIdx < 0) return null;
165
- const events = new Map(); // event -> its child lines (block map form only)
187
+ const events = new Map();
166
188
  if (onInline) {
167
189
  const list = onInline.startsWith('[') ? onInline.replace(/^\[|\]$/g, '').split(',') : [onInline];
168
- for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, []); }
190
+ for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, { inline: '', body: [] }); }
169
191
  } else {
170
192
  let evIndent = null;
171
193
  let cur = null;
@@ -178,21 +200,188 @@ function workflowTriggers(text) {
178
200
  if (indent < evIndent) break;
179
201
  if (indent === evIndent) {
180
202
  const t = l.trim();
181
- const m = /^-\s*(.+)$/.exec(t) || /^([A-Za-z_]+)\s*:/.exec(t);
182
- cur = m ? yamlScalar(m[1].replace(/:.*$/, '')) : null;
183
- if (cur) events.set(cur, []);
184
- } else if (cur) events.get(cur).push(l.trim());
203
+ const li = /^-\s*(.+)$/.exec(t);
204
+ const mk = li ? null : /^([A-Za-z_]+)\s*:\s*(.*)$/.exec(t);
205
+ cur = li ? yamlScalar(li[1].replace(/:.*$/, '')) : (mk ? yamlScalar(mk[1]) : null);
206
+ if (cur) events.set(cur, { inline: mk ? yamlScalar(mk[2]) : '', body: [] });
207
+ } else if (cur) events.get(cur).body.push({ indent, text: l.trim() });
185
208
  }
186
209
  }
187
- let verifies = false;
188
- for (const [ev, body] of events) {
189
- if (!BRANCH_TRIGGERS.includes(ev)) continue;
190
- if (ev !== 'push') { verifies = true; break; }
191
- const keys = body.map((t) => (/^([A-Za-z_-]+)\s*:/.exec(t) || [])[1]).filter(Boolean);
192
- const tagsOnly = (keys.includes('tags') || keys.includes('tags-ignore')) && !keys.includes('branches') && !keys.includes('branches-ignore');
193
- if (!tagsOnly) { verifies = true; break; }
210
+ return { name, events };
211
+ }
212
+
213
+ /** A YAML flow list `[a, 'b', "c"]` or a single scalar → the strings; '' → []. */
214
+ function flowList(v) {
215
+ const t = String(v || '').trim();
216
+ if (!t) return [];
217
+ const inner = t.startsWith('[') && t.endsWith(']') ? t.slice(1, -1) : t;
218
+ return inner.split(',').map(yamlScalar).filter(Boolean);
219
+ }
220
+
221
+ const PUSH_FILTER_KEYS = Object.freeze(['branches', 'branches-ignore', 'tags', 'tags-ignore', 'paths', 'paths-ignore']);
222
+
223
+ /**
224
+ * #723: what one workflow file says about a BRANCH PUSH — the question "should this workflow have a
225
+ * run at the head of branch B?" asks. Returns null when the text has no top-level `on:`, else
226
+ * `{ name, push, readable, branches, branchesIgnore, tagsOnly, paths, dispatch }`:
227
+ * push the triggers include `push`
228
+ * readable the push filters were read; false for a shape this small reader does not follow
229
+ * (a flow map `push: {…}`, an unknown key) — the caller then never expects a run
230
+ * branches / branchesIgnore the glob lists, null when absent
231
+ * tagsOnly `tags`/`tags-ignore` with no branch filter: a branch push never fires it
232
+ * paths a `paths` / `paths-ignore` filter is present: whether a push fires it depends on
233
+ * the files the push changed, which this reader does not judge
234
+ * dispatch the triggers include `workflow_dispatch` — `gh workflow run` can give it a run
235
+ * Not a YAML parser; the same deliberately small reader as workflowTriggers.
236
+ */
237
+ function pushTrigger(text) {
238
+ const parsed = onEvents(text);
239
+ if (!parsed) return null;
240
+ const { name, events } = parsed;
241
+ const out = { name, push: events.has('push'), readable: true, branches: null, branchesIgnore: null,
242
+ tagsOnly: false, paths: false, dispatch: events.has('workflow_dispatch') };
243
+ if (!out.push) return out;
244
+ const e = events.get('push');
245
+ if (e.inline && !['null', '~', '{}'].includes(e.inline)) { out.readable = false; return out; }
246
+ const lists = {};
247
+ let key = null;
248
+ let keyIndent = null;
249
+ for (const b of e.body) {
250
+ if (keyIndent === null) keyIndent = b.indent;
251
+ if (b.indent === keyIndent) {
252
+ const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(b.text);
253
+ if (!m || !PUSH_FILTER_KEYS.includes(m[1])) { out.readable = false; return out; }
254
+ key = m[1];
255
+ lists[key] = flowList(m[2]);
256
+ } else if (key && b.indent > keyIndent) {
257
+ const li = /^-\s*(.+)$/.exec(b.text);
258
+ if (!li) { out.readable = false; return out; }
259
+ lists[key].push(yamlScalar(li[1]));
260
+ } else { out.readable = false; return out; }
194
261
  }
195
- return { name, verifiesBranches: verifies };
262
+ out.branches = lists.branches || null;
263
+ out.branchesIgnore = lists['branches-ignore'] || null;
264
+ out.tagsOnly = !!(lists.tags || lists['tags-ignore']) && !out.branches && !out.branchesIgnore;
265
+ out.paths = !!(lists.paths || lists['paths-ignore']);
266
+ return out;
267
+ }
268
+
269
+ /**
270
+ * One GitHub filter pattern (`*` not across `/`, `**` across, `?` / `+` / `[…]` on the preceding
271
+ * character as in a regex) → a RegExp over the whole branch name, or null when it cannot be read.
272
+ */
273
+ function filterPatternRe(p) {
274
+ let re = '';
275
+ const s = String(p);
276
+ for (let i = 0; i < s.length; i++) {
277
+ const c = s[i];
278
+ if (c === '*') { if (s[i + 1] === '*') { re += '.*'; i++; } else re += '[^/]*'; }
279
+ else if (c === '?' || c === '+') re += c;
280
+ else if (c === '[') { const j = s.indexOf(']', i); if (j < 0) return null; re += s.slice(i, j + 1); i = j; }
281
+ else if (c === '\\') { if (i + 1 >= s.length) return null; re += s[i + 1].replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); i++; }
282
+ else re += c.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
283
+ }
284
+ try { return new RegExp(`^${re}$`); } catch (_) { return null; }
285
+ }
286
+
287
+ /**
288
+ * #723: does a push to `branch` pass a workflow's branch filters? true / false, or null when a
289
+ * pattern cannot be read. `branches` is ordered with `!` negations (the last match decides);
290
+ * `branches-ignore` excludes on any match. Neither list → true.
291
+ */
292
+ function branchFilterMatches(branch, { branches = null, branchesIgnore = null } = {}) {
293
+ if (branches) {
294
+ let hit = false;
295
+ for (const raw of branches) {
296
+ const neg = raw.startsWith('!');
297
+ const re = filterPatternRe(neg ? raw.slice(1) : raw);
298
+ if (!re) return null;
299
+ if (re.test(branch)) hit = !neg;
300
+ }
301
+ return hit;
302
+ }
303
+ if (branchesIgnore) {
304
+ for (const raw of branchesIgnore) {
305
+ const re = filterPatternRe(raw);
306
+ if (!re) return null;
307
+ if (re.test(branch)) return false;
308
+ }
309
+ }
310
+ return true;
311
+ }
312
+
313
+ /** GitHub's skip directives (docs: "Skipping workflow runs") — a push run is not created for them. */
314
+ const SKIP_DIRECTIVES = Object.freeze(['[skip ci]', '[ci skip]', '[no ci]', '[skip actions]', '[actions skip]']);
315
+
316
+ function skipsWorkflows(message) {
317
+ const m = String(message || '');
318
+ const low = m.toLowerCase();
319
+ return SKIP_DIRECTIVES.some((d) => low.includes(d)) || /^skip-checks:\s*true\s*$/mi.test(m);
320
+ }
321
+
322
+ /**
323
+ * #723: the workflows that SHOULD have a push run at the head of `branch` — the expected set a
324
+ * branch verdict reads before it may call the head green. A workflow is expected when its definition
325
+ * AT THE HEAD (GitHub reads the workflow file from the pushed commit):
326
+ * - is triggered by `push`, read cleanly, not tags-only, with no `paths` / `paths-ignore` filter,
327
+ * - passes its branch filters for `branch` (an unreadable pattern → not expected),
328
+ * - is not in `ship-ignore-workflows`, and is in `ship-gate-workflows` when that list is declared,
329
+ * - is not reported anything but `active` by the workflows API (`states`: path → `{state, id, name}`
330
+ * or a bare state string; null = unread, every workflow taken as active). The API's `id` and
331
+ * `name` ride on the entry, so a run is matched by its workflow id too (git.js missingExpected).
332
+ * Nothing is expected when the head commit's message carries a skip directive (`headMessage`).
333
+ *
334
+ * Every doubt resolves to NOT expected: that is today's reading (the runs that exist decide), so the
335
+ * set can only add a hold where a workflow demonstrably should have run, never invent one.
336
+ *
337
+ * @param {object} a
338
+ * @param {Array<{path:string, text:string}>} a.defs - the workflow files at the head
339
+ * @param {string} a.branch
340
+ * @param {object} [a.policy] - parsePolicy's `{gate, ignore}`
341
+ * @param {Map<string,(string|{state:string, id:number, name:string})>|null} [a.states]
342
+ * @param {string|null} [a.headMessage]
343
+ * @returns {{ expected: Array<{name:string, path:string, dispatch:boolean, id?:number, apiName?:string}>, skipDirective: boolean }}
344
+ */
345
+ function expectedWorkflows({ defs, branch, policy = null, states = null, headMessage = null }) {
346
+ if (skipsWorkflows(headMessage)) return { expected: [], skipDirective: true };
347
+ const p = policy || { gate: null, ignore: [] };
348
+ const expected = [];
349
+ for (const d of defs || []) {
350
+ const t = pushTrigger(d.text);
351
+ if (!t || !t.push || !t.readable || t.tagsOnly || t.paths) continue;
352
+ if (branchFilterMatches(branch, t) !== true) continue;
353
+ const name = t.name || d.path;
354
+ if (p.ignore && p.ignore.includes(name)) continue;
355
+ if (p.gate && !p.gate.includes(name)) continue;
356
+ const st = states && states.has(d.path) ? states.get(d.path) : null;
357
+ const info = st && typeof st === 'object' ? st : { state: st };
358
+ if (info.state && info.state !== 'active') continue;
359
+ expected.push({ name, path: d.path, dispatch: t.dispatch,
360
+ ...(info.id != null ? { id: info.id } : {}), ...(info.name && info.name !== name ? { apiName: info.name } : {}) });
361
+ }
362
+ return { expected, skipDirective: false };
363
+ }
364
+
365
+ /**
366
+ * #723: how to get a run for each missing workflow — a hint, never an action. `gh workflow run` where
367
+ * the workflow takes `workflow_dispatch` (#567 counts that run as the push run it stands in for);
368
+ * otherwise a draft PR, or an empty re-push, which is the implementer's call.
369
+ */
370
+ function missingHint(missing, branch) {
371
+ const list = Array.isArray(missing) ? missing : [];
372
+ if (!list.length) return '';
373
+ const b = branch || '<branch>';
374
+ const parts = list.map((x) => (x.dispatch
375
+ ? `\`gh workflow run ${String(x.path || x.name).split('/').pop()} --ref ${b}\``
376
+ : `${x.name}: no workflow_dispatch — open a draft PR (\`gh pr create --draft --head ${b}\`) or push an empty commit (the implementer's call)`));
377
+ return `to get the run: ${parts.join('; ')}`;
378
+ }
379
+
380
+ /** #723: the verdict-detail suffix naming the expected workflows with no run at the sha — '' when none. */
381
+ function missingNote(missing, branch) {
382
+ const list = Array.isArray(missing) ? missing : [];
383
+ if (!list.length) return '';
384
+ return ` — no run of ${list.map((x) => x.name).join(', ')} at this sha, though ${list.length === 1 ? 'its' : 'their'} definition fires on a push to this branch (#723); ${missingHint(list, branch)}`;
196
385
  }
197
386
 
198
387
  /** The compact verdict-detail note for rows the lost-push rescue counted — '' when none. */
@@ -225,4 +414,7 @@ function skippedOnlyNote(rows) {
225
414
  return ` — not judged, every run skipped so it ran nothing here (#688; name a workflow in ship-gate-workflows if it must run): ${names.join(', ')}`;
226
415
  }
227
416
 
228
- module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote, skippedOnlyNote, workflowTriggers, dispatchCountedNote };
417
+ module.exports = {
418
+ VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, SKIP_DIRECTIVES, parsePolicy, setAsideReason, splitVerifying, setAsideNote, skippedOnlyNote,
419
+ workflowTriggers, pushTrigger, branchFilterMatches, skipsWorkflows, expectedWorkflows, missingHint, missingNote, dispatchCountedNote,
420
+ };