@futurelastic/colab-handbook 1.14.0-rc.1 → 1.14.0-rc.2

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
@@ -107,7 +107,7 @@ const ownerBranchLib = require("../tools/lib/owner-branch.js");
107
107
  const npmGuard = require("../tools/lib/npm-publish-guard.js");
108
108
  const installRoute = require("../tools/lib/install-route.js");
109
109
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
110
- const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
110
+ const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
111
111
  const shipBatch = require("../tools/lib/ship-batch.js");
112
112
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
113
113
  const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
@@ -1792,6 +1792,9 @@ function auditRepo(target, ctx) {
1792
1792
  // #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
1793
1793
  // #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
1794
1794
  checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
1795
+ // #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
1796
+ // dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
1797
+ checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
1795
1798
 
1796
1799
  // ---- markdown anchor links resolve (#158) --------------------------------
1797
1800
  // Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
@@ -2756,6 +2759,13 @@ function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
2756
2759
  // caller is `deploy: manual` (a human runs it) or `deploy: tag` deployed OUTSIDE CI (a GitOps
2757
2760
  // poller runs it). Both share the same invariant: the deploy runs off no in-repo workflow, so the
2758
2761
  // path to production must be WRITTEN DOWN or nobody but its author can ship it.
2762
+ // ---- the instruction-files caller's trigger (#599) ---------------------------
2763
+ // The logic lives in tools/lib/workflow-triggers.js beside the other trigger readers. WARN, never
2764
+ // fail: the caller is a copy the repo owns, and handbook-sync's trigger graft is the fix.
2765
+ function checkInstructionFilesCaller(src, workflows, trunk, warn) {
2766
+ for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
2767
+ }
2768
+
2759
2769
  // ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
2760
2770
  // The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
2761
2771
  // 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.14.0-rc.1"
36
+ "version": "1.14.0-rc.2"
37
37
  }
@@ -1,8 +1,13 @@
1
1
  # Copy to .github/workflows/instruction-files.yml — CLAUDE.md must be @AGENTS.md + tool blocks (#588).
2
2
  name: instruction-files
3
3
  on:
4
+ # Keep `push:` UNFILTERED (#599). The ratchet is meant to fail on the session branch that breaks
5
+ # it, before trunk; narrowed to `branches: [main]`, it first fails ON trunk, and the cure branch's
6
+ # push run cannot prove the job (#297). The audit reports a narrowed copy.
4
7
  push:
5
8
  pull_request:
9
+ # Lets `colab ship` prove a red job on a cure branch by dispatch (#510), with no human ci-grant.
10
+ workflow_dispatch:
6
11
  jobs:
7
12
  instruction-files:
8
13
  uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
@@ -265,6 +265,62 @@ function prereleaseTagTriggers({ readFile, workflows, deploy }) {
265
265
  return out;
266
266
  }
267
267
 
268
+ // ---- callers of the reusable instruction-files workflow (#599) ---------------
269
+ // The ratchet (#588) is meant to fail on the SESSION BRANCH, before trunk. A caller narrowed to
270
+ // `push: branches: [main]` (measured: 15 of 16 adopting copies) never runs there, so a branch that
271
+ // trips it merges green and the failure first appears on trunk — where the cure rule (#297) then
272
+ // cannot find the job on the cure branch's push run and, with no `workflow_dispatch` to fall back on
273
+ // (#510), ships only through a human grant. A caller is recognised by what it RUNS — a job `uses:`
274
+ // the reusable `.github/workflows/instruction-files.yml` — never by its file name. One branch per
275
+ // session-branch type is probed (plus a machine-prefixed one, §4), so `branches: ['feat/**']` reads
276
+ // as narrowed too; the trunk itself is probed as well, since a caller that skips trunk is narrowed
277
+ // the other way.
278
+ const INSTRUCTION_FILES_USES = /^\s*(?:-\s*)?uses:\s*["']?[^\s"'#]*\.github\/workflows\/instruction-files\.ya?ml(?:@[^\s"'#]*)?["']?\s*(?:#.*)?$/m;
279
+ const SESSION_BRANCH_PROBES = ["feat/probe-1", "fix/probe-1", "docs/probe-1", "chore/probe-1", "refactor/probe-1",
280
+ "test/probe-1", "perf/probe-1", "design/probe-1", "ada/box-a/feat/probe-1"];
281
+
282
+ /** Does this workflow call the reusable instruction-files workflow? (#599) */
283
+ function isInstructionFilesCaller(text) {
284
+ return !!text && INSTRUCTION_FILES_USES.test(text);
285
+ }
286
+
287
+ /**
288
+ * Each caller of the reusable instruction-files workflow whose trigger cannot run it on a session
289
+ * branch, or which cannot be dispatched (#599). `readFile(relPath)` returns the text or null;
290
+ * `trunk` is project.yml's value (`main` when absent). Returns
291
+ * [{ workflow, narrowed:[branch…], dispatchable:boolean, text }] — only callers with a problem.
292
+ */
293
+ function instructionFilesCallerFindings({ readFile, workflows, trunk }) {
294
+ const out = [];
295
+ for (const wf of workflows || []) {
296
+ const text = readFile(`.github/workflows/${wf}`);
297
+ if (!isInstructionFilesCaller(text)) continue;
298
+ const on = parseWorkflowOn(text);
299
+ const probes = [trunk || "main", ...SESSION_BRANCH_PROBES];
300
+ const narrowed = probes.filter((b) => !workflowFiresOnBranchPush(on, b));
301
+ const dispatchable = on.events.has("workflow_dispatch");
302
+ if (!narrowed.length && dispatchable) continue;
303
+ const why = [];
304
+ if (narrowed.length) {
305
+ why.push(!on.events.has("push")
306
+ ? "has no push trigger, so it never runs on a session branch"
307
+ : `its push trigger does not fire on ${narrowed.slice(0, 3).join(", ")}${narrowed.length > 3 ? ` (+${narrowed.length - 3} more)` : ""}` +
308
+ " — the ratchet then fails first on trunk instead of on the branch that broke it");
309
+ }
310
+ if (!dispatchable) {
311
+ why.push("it declares no workflow_dispatch, so a cure branch cannot prove the job by dispatch (#510) and a red trunk ships only through a human ci-grant");
312
+ }
313
+ out.push({
314
+ workflow: wf, narrowed, dispatchable,
315
+ text:
316
+ `.github/workflows/${wf} calls the reusable instruction-files workflow, but ${why.join("; and ")}. ` +
317
+ "Fix: use the template trigger — an unfiltered `push:`, `pull_request:` and `workflow_dispatch:` " +
318
+ "(templates/instruction-files.yml; handbook-sync grafts it) (#599)",
319
+ });
320
+ }
321
+ return out;
322
+ }
323
+
268
324
  // --------------------------------------------------- workflow_dispatch inputs (#474)
269
325
  //
270
326
  // The names declared under `on: workflow_dispatch: inputs:`, in order. `[]` for a bare
@@ -318,4 +374,5 @@ module.exports = {
318
374
  workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
319
375
  isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
320
376
  workflowDispatchInputs, workflowNameOf,
377
+ SESSION_BRANCH_PROBES, isInstructionFilesCaller, instructionFilesCallerFindings,
321
378
  };