@vaultcompass/conductor 0.14.0 → 0.16.0

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/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # conductor
2
2
 
3
3
  conductor is the one required check for a repository an AI agent edits. It
4
- runs the scanners a maintainer already trusts, and adds the checks those
5
- scanners cannot do on their own: a hallucinated package name, a credential
6
- caught before the edit lands, a pull request that edits its own gate, a
7
- change that reaches outside what was approved for it.
4
+ runs the scanners a maintainer already trusts beside the three family
5
+ gates, which check what those scanners do not: a hallucinated package name,
6
+ a credential caught before the edit lands, a pull request that edits its
7
+ own gate, a change that reaches outside what was approved for it.
8
8
 
9
9
  It does that by running five gates over one policy file, one init, one
10
10
  hook and one report: three from this family, and two the adopter already
@@ -33,9 +33,70 @@ and osv-scanner, so both see a credential shape, a credential in history,
33
33
  and a known advisory. The other three are what a scanner that only knows
34
34
  about vulnerabilities and secrets has no way to know.
35
35
 
36
+ ## Quick start
37
+
38
+ Install the umbrella and the three gates, look at what init would write, then
39
+ write it with one pre-commit hook:
40
+
41
+ ```sh
42
+ npm install -g @vaultcompass/conductor @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
43
+ conductor init --dry-run # prints every file it would write, writes nothing
44
+ conductor init --hook # writes .guardrails.yaml and one pre-commit hook
45
+ ```
46
+
47
+ The hook runs every enabled gate on each commit and, when the commit is
48
+ clean, prints one summary line, plus one status line per gate on stderr.
49
+ Each gate can also be installed and run on its own.
50
+
51
+ Then the same gates on every pull request, as one pinned workflow:
52
+
53
+ ```yaml
54
+ name: guardrails
55
+ on: [pull_request, push]
56
+ permissions:
57
+ contents: read
58
+ security-events: write
59
+ jobs:
60
+ gates:
61
+ runs-on: ubuntu-latest
62
+ steps:
63
+ - uses: actions/checkout@v7
64
+ with:
65
+ fetch-depth: 0
66
+ - name: Install gitleaks and osv-scanner
67
+ run: |
68
+ set -euo pipefail
69
+ bin="$RUNNER_TEMP/external-gates"
70
+ mkdir -p "$bin"
71
+ cd "$RUNNER_TEMP"
72
+ curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
73
+ echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
74
+ tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
75
+ curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
76
+ echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
+ chmod +x "$bin/osv-scanner"
78
+ echo "$bin" >> "$GITHUB_PATH"
79
+ - uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
80
+ - uses: github/codeql-action/upload-sarif@v4
81
+ if: always()
82
+ with:
83
+ sarif_file: conductor.sarif
84
+ ```
85
+
86
+ One pin, not five: the action tag decides which version of each of the four
87
+ npm packages is installed. The install step for gitleaks and osv-scanner is
88
+ needed when the policy enables the secrets-history and vulnerabilities gates,
89
+ and it pins both by version and checksum. On a pull request every gate reads
90
+ its rules from the base branch, so a change cannot turn off the check that
91
+ exists to catch it. The first pull request under a new policy cannot be judged
92
+ by that policy, so read the careful path below before you make the check
93
+ required.
94
+
95
+ ## Part of the Vault & Compass guardrails
96
+
36
97
  <!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
37
98
  The Vault & Compass guardrails are three gates over an AI-assisted coding
38
- session: [dep-guard](https://www.npmjs.com/package/@vaultcompass/dep-guard)
99
+ session, plus an optional umbrella: [dep-guard](https://www.npmjs.com/package/@vaultcompass/dep-guard)
39
100
  checks what comes in (hallucinated package names, typosquats, tampered
40
101
  lockfile entries),
41
102
  [vault-guard](https://www.npmjs.com/package/@vaultcompass/vault-guard) checks
@@ -53,7 +114,7 @@ vulnerabilities. conductor scans nothing itself and installs nothing that
53
114
  is not its own.
54
115
  <!-- /guardrails-family -->
55
116
 
56
- ## Adopting conductor
117
+ ## Adopting conductor: the careful path
57
118
 
58
119
  The first pull request under a policy conductor just added cannot be judged
59
120
  by that policy, so plan for a short, ordered sequence rather than one
@@ -98,8 +159,9 @@ required.
98
159
  run the umbrella never looks in `node_modules/.bin` at all, because what
99
160
  is installed there is chosen by the head's own manifest and lockfile. The
100
161
  Action installs all four packages itself, globally, at versions pinned in
101
- your workflow file. See "The pull-request trust boundary" and "The
102
- Action" below.
162
+ your workflow file. See
163
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md) and
164
+ [The Action](#the-action) below.
103
165
 
104
166
  From the repository root, look before you write:
105
167
 
@@ -154,7 +216,7 @@ required.
154
216
  Commit something, now that `--hook` above has installed the pre-commit
155
217
  hook (this walkthrough's output below only appears when the hook is
156
218
  installed; a bare `conductor init` with no `--hook` runs no gate on
157
- commit at all). A clean commit prints one line:
219
+ commit at all). A clean commit prints one summary line on stdout:
158
220
 
159
221
  ```
160
222
  conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 0 gate(s) left out by --gate. 0 gate(s) not enforced. 1 note(s). 0 suppressed across all gates. Re-run with --verbose for the full report.
@@ -165,18 +227,25 @@ required.
165
227
  out by `--gate`, not enforced, and suppressed findings. Which gates appear
166
228
  in each depends on your policy file.
167
229
 
230
+ Your terminal also shows one status line per gate, written to stderr so a
231
+ CI job log has a per-gate record even when the report goes to a file,
232
+ such as `conductor: gate dependencies (dep-guard 0.18.0): ok, exit 0` or
233
+ a `skipped (deferred to stage ci)` line for a deferred gate. They carry
234
+ nothing the summary does not; to see only the summary, redirect stderr
235
+ (`conductor run --staged --stage commit 2>/dev/null` in the hook).
236
+
168
237
  A commit with a staged credential in it prints the full report and exits 1:
169
238
 
170
239
  ```
171
- conductor 0.14.0
240
+ conductor 0.16.0
172
241
  verdict-token: blocked (1)
173
242
  conductor run: 2 gate(s), 1 finding(s)
174
243
 
175
- dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
244
+ dependencies dep-guard 0.18.0 exit 0 153ms via dep-guard on path
176
245
  threshold medium suppressed 0 ignored 0
177
- mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
246
+ mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
178
247
 
179
- secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
248
+ secrets vault-guard 1.13.0 exit 1 105ms via vault-guard on path
180
249
  BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
181
250
  Possible secret of type 'anthropic'
182
251
  threshold medium suppressed 0 ignored not reported
@@ -187,7 +256,8 @@ required.
187
256
  verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
188
257
  ```
189
258
 
190
- The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
259
+ The `mode`, `corpusBuiltAt`, `lockfileFormat`, `online`, `lookups` and
260
+ `skipped-by-deadline` line under
191
261
  `dependencies`, and the `filesScanned`/`patternsActive` line under
192
262
  `secrets`, are each gate's own run facts, one line per gate, added to the
193
263
  full report so a reader can see what a gate actually scanned and with
@@ -212,7 +282,8 @@ required.
212
282
  gate `skipped ... no contract` and never reaches the exit code. So a
213
283
  first pull request with no contract yet is not blocked by the intent gate
214
284
  on the pull request, whatever the local preview showed a moment before.
215
- See "Intent at a pull request" below for the full mechanism.
285
+ See [Intent at a pull request](docs/intent-at-a-pull-request.md) for the
286
+ full mechanism.
216
287
 
217
288
  2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
218
289
  and the workflow together, with `advisory: true` and `pr-comment: true`
@@ -250,7 +321,7 @@ A repository with history will not start clean, and a gate that is red on its
250
321
  first pull request gets switched off. The order that works:
251
322
 
252
323
  1. **Advisory first.** The first pull request runs with `advisory: true` and
253
- `pr-comment: true`, as in "Adopting conductor" above. Findings print and
324
+ `pr-comment: true`, as in "Adopting conductor: the careful path" above. Findings print and
254
325
  are commented, and none of them fails the run.
255
326
 
256
327
  2. **Record what is already there, in each gate's own file.** conductor does
@@ -328,1023 +399,14 @@ It does not overrule a gate. A gate that says a commit is blocked blocks
328
399
  the commit. The umbrella can add to that decision and never subtracts from
329
400
  it.
330
401
 
331
- ## The policy file
332
-
333
- `.guardrails.yaml`, at the repository root. `conductor init` writes one with
334
- every gate listed and only the ones it found switched on.
335
-
336
- ```yaml
337
- version: 1
338
-
339
- gates:
340
- dependencies:
341
- product: dep-guard
342
- enabled: true
343
- stage: commit
344
- enforce: true
345
- options:
346
- fail-on: high
347
- secrets:
348
- product: vault-guard
349
- enabled: true
350
- stage: commit
351
- enforce: true
352
- intent:
353
- product: intent-guard
354
- enabled: true
355
- stage: ci
356
- # It runs and reports in CI without failing the run. Flip it to
357
- # true once a few pull requests show the signal is worth blocking on.
358
- enforce: false
359
- options:
360
- require-frozen: false
361
- secrets-history:
362
- product: gitleaks
363
- enabled: true
364
- # Enabled because gitleaks was found on the machine that ran init. CI must
365
- # install gitleaks itself (conductor does not); without it this gate
366
- # reports conductor/gate-missing and the run exits 2.
367
- stage: ci
368
- enforce: true
369
- vulnerabilities:
370
- product: osv-scanner
371
- enabled: true
372
- # Enabled because osv-scanner was found on the machine that ran init. CI must
373
- # install osv-scanner itself (conductor does not); without it this gate
374
- # reports conductor/gate-missing and the run exits 2.
375
- stage: ci
376
- enforce: true
377
- present-on-base: report
378
-
379
- report:
380
- format: text
381
- ```
402
+ ## Reference
382
403
 
383
- **Gates are keyed by role**, not by product. `dependencies` (dep-guard),
384
- `secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
385
- (gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
386
- the resolved dependency tree). The `product` field says which binary fills
387
- that role today. The last two are external tools you install yourself.
388
-
389
- **`enabled`** defaults to true. A gate that is enabled and whose binary
390
- cannot be found is a blocking finding of the umbrella's own
391
- (`conductor/gate-missing`), never a silent skip.
392
-
393
- **`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
394
- **cumulative** in that order, so a gate runs at its own stage and at every
395
- later one, and a run at `ci` runs everything that is enabled. The defaults
396
- are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
397
- `secrets-history` and `vulnerabilities`: a history scan and a registry
398
- lookup are pull-request work, not commit-time work.
399
-
400
- A gate held back by the stage filter is never silent. It is one line in the
401
- text report naming the stage it is waiting for, and a `conductor/gate-deferred`
402
- notification in the SARIF log's `conductor` run. Its binary is not even looked
403
- for, so a gate installed only on the CI image does not fail a developer's
404
- commit.
405
-
406
- **`enforce`** defaults to true. A gate with `enforce: false` runs, reports,
407
- and its findings appear in the text report and the SARIF log exactly as an
408
- enforced gate's do. The only thing it cannot do is change the exit code: its
409
- blocking findings do not raise it, and its failing to run at all does not
410
- make the run exit 2. That is the adoption ramp, so a gate can be switched on
411
- and read for a few weeks before it is allowed to refuse anybody's commit.
412
- `init` writes it out for every gate. For the intent gate it writes `true`
413
- (and see `present-on-base` below for the vulnerabilities gate)
414
- when a frozen contract already exists at init time
415
- (`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
416
- `.conductor/intent-contract.yaml`), since the ramp is already climbed by
417
- then, and leaving it unenforced would silently let a frozen contract's
418
- protected paths produce findings that never fail the check. It writes
419
- `false`, with a comment explaining why, when there is no contract yet to
420
- enforce against, and in that case it also writes `require-frozen: false`
421
- under `options`, since intent-guard otherwise blocks on a missing contract.
422
- The `options` comment is written per gate: gitleaks and osv-scanner have no
423
- severity floor, so their comments point at `.gitleaks.toml` and
424
- `osv-scanner.toml` rather than at `fail-on`.
425
-
426
- **`options`** is handed to that gate unchanged. Each key is one of that
427
- gate's own long flags with the leading dashes stripped: `fail-on: high`
428
- becomes `--fail-on high`, `online: true` becomes `--online`,
429
- `require-frozen: false` becomes `--no-require-frozen`, and a list becomes
430
- one flag per entry. The handful of flags the umbrella supplies itself (the
431
- JSON format flag, `--staged`, and the intent gate's `--project`) are
432
- rejected if you also set them, rather than being silently overridden. For
433
- the external gates the umbrella writes `--report-format`, `--report-path`,
434
- `--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
435
- `--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
436
- gitleaks, and
437
- `--format`, `--config` and `--lockfile` to osv-scanner, so those are
438
- reserved too. Narrow what either
439
- tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
440
- instead. Two osv-scanner flags are written without being reserved: a run
441
- that scans a requirements file always gets `--no-resolve`, and a
442
- `no-resolve` key here is dropped from that run with a note; and a
443
- pull-request run gets `--no-call-analysis=all` unless this block names
444
- `call-analysis` or `no-call-analysis`, in which case that value is used.
445
- `timeout-seconds` is refused under `options` on every gate, and `timeout`
446
- on every gate but gitleaks, where it is gitleaks' own `--timeout` flag and
447
- is passed through (see `timeout-seconds` below and "What a history scan
448
- costs").
449
-
450
- **`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
451
- never under `options`) is `block` or `report`. On a pull-request run whose
452
- osv-scanner scan blocked, the umbrella also scans the base branch copies of
453
- the lockfiles that carry findings and labels each finding `introduced` or
454
- `present-on-base`. `block` blocks on every finding; `report` reports the
455
- present-on-base ones without blocking and blocks only on what the pull
456
- request introduced. A policy without the key blocks on every finding, so no
457
- existing policy is loosened; `init` writes `report` for a new repository.
458
- On a pull request the key is read from the base branch's policy like every
459
- other key, so a pull request cannot set it for itself. A run with no base (a
460
- local run, a push) has no labels, and every finding blocks. The key on any
461
- other gate is an error, and an older conductor rejects it, so move the
462
- Action first.
463
-
464
- **`timeout-seconds`** (any gate, beside `enforce`, never under `options`)
465
- is how long conductor lets that gate run before stopping it: a whole number
466
- of seconds from 10 to 21600. The floor is there because the same limit
467
- bounds the gate's version probe, and a limit of a second or two can stop the
468
- probe of a gate that starts slowly before it ever scans. The ceiling is the
469
- six hours after which a GitHub-hosted job is cancelled; a larger limit could
470
- never fire there. Without the key each gate keeps the default for its
471
- product: 120 seconds for dep-guard, vault-guard and intent-guard, 600 for
472
- gitleaks, 300 for osv-scanner. There is no policy-wide default, for the same
473
- reason there is no shared severity threshold: the five gates differ in cost
474
- by orders of magnitude. Every spawn of the gate gets the full limit (the
475
- version probe, the scan, the intent gate's preparation steps, osv-scanner's
476
- base run on a pull request). A gate stopped at its limit could not run, with
477
- the reason `timed-out` and what to do about it, and an enforced one makes
478
- the run exit 2. On a pull request the key is read from the base branch's
479
- policy like every other key, so a pull request cannot raise, lower or
480
- remove its own limit; an invalid value on the base fails every pull request
481
- with exit 2 until the base is fixed, and an invalid value only on the head
482
- is a policy proposal there and fails the push run after merge. An older
483
- conductor rejects the key, so move the Action first.
484
-
485
- **There is no shared severity threshold, on purpose.** One top-level
486
- `failOn` would read as one decision and mean five different things, so
487
- setting one is an error rather than a knob that half works. Each gate keeps
488
- its own threshold in its own `options` block, spelled the way that gate
489
- spells it.
490
-
491
- **`command`** takes an absolute path and overrides binary resolution for
492
- that gate, for pointing at a build that is not installed anywhere. `args`
493
- beside it sets the argument prefix. conductor's history gate assumes
494
- gitleaks' `git` mode; an `args` that switches it to `dir` mode changes what
495
- gitleaks' own `--timeout` does (in `dir` mode it exits 0 after a partial
496
- scan, with no warning).
497
-
498
- **`report.format`** is `text` or `sarif`, and `--format` overrides it.
499
-
500
- ## Commands
501
-
502
- `conductor init` writes the policy file and `.guardrails/manifest.json`, the
503
- record `--revert` reads back later. The manifest currently records absolute
504
- machine paths rather than repo-relative ones (see "Adopting conductor"
505
- above); do not commit it. When git does not already ignore it, init appends
506
- `.guardrails/` to `.gitignore` (or creates one) and says so; a `.gitignore`
507
- that is a symbolic link or not a regular file is left alone and the line is
508
- printed for you to add. On a policy file that already exists, init lists the
509
- gate roles it has no entry for, with the two lines that add each. An external
510
- gate (gitleaks, osv-scanner) is written enabled only when its binary is found
511
- on the machine running init, with a comment under it that CI must install it;
512
- a CI job without it gets `conductor/gate-missing` and exit 2.
513
-
514
- - `--hook` also writes one pre-commit hook running every enabled gate whose
515
- stage is `commit`. Without it, init writes only the policy file and the
516
- manifest: no hook, and none of the hook-manager detection below runs
517
- either. `.git/hooks` is never part of a clone, so a hook one checkout has
518
- does not follow a teammate's clone, or a fresh clone of your own; each
519
- needs its own `conductor init --hook`. `--revert` still removes a hook a
520
- previous `--hook` run left behind, whether or not this invocation passes
521
- `--hook` itself.
522
- - `--dry-run` prints every file it would write or change and writes nothing.
523
- - `--revert` removes exactly what a previous init wrote, and nothing else.
524
- A file changed since init is reported and left alone. The one exception is
525
- the `.guardrails/` line init appends to `.gitignore`: `--revert` does not
526
- remove it.
527
- - `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
528
- Without it, init reports the collision and stops rather than stacking a
529
- second invocation of a gate that is already hooked. A hook the umbrella
530
- does not recognise is never replaced, with or without `--adopt`. Only
531
- meaningful together with `--hook`; without it, init errors rather than
532
- silently ignoring the flag, because there is no hook for it to act on.
533
- - `--force` acts on a file **conductor itself wrote** and that has changed
534
- since: on its own it replaces a managed hook somebody has edited, and with
535
- `--revert` it removes one, restoring an adopted hook if there was one. It
536
- never overrides a foreign-hook or gate-hook refusal, with or without
537
- `--adopt`: those hooks were never conductor's, and no flag here turns
538
- somebody else's file into one this tool may overwrite. Like `--adopt`,
539
- only meaningful together with `--hook` on an init (not on a `--revert`);
540
- without it, init errors.
541
- - `--project <dir>` writes into that repository instead of the current
542
- directory, resolved to its git top level the same way the current
543
- directory already is, so a script can point init at a repository without a
544
- `cd` compound.
545
-
546
- The rest of this section, on hook managers already wired into the
547
- repository, applies only when `--hook` is given: none of it is consulted,
548
- and none of it can block the policy file from being written, on a plain
549
- `conductor init`.
550
-
551
- Init recognises the hook manager already wired into the repository. husky is
552
- redirected to the tracked hook it maintains rather than the generated
553
- dispatcher git runs. On a fresh clone, where husky's install has not set
554
- `core.hooksPath` yet, husky is recognised from `package.json` (a `husky`
555
- dependency or devDependency, or a `prepare` script that runs husky) or a
556
- tracked `.husky/` directory, and init writes `.husky/pre-commit` and says the
557
- install still has to run, rather than writing `.git/hooks/pre-commit`, which
558
- husky's install would bypass. This applies only when `core.hooksPath` is not
559
- set at all: one set by hand, even to `.git/hooks`, is left alone. A prepare
560
- script counts only when it runs husky as a command. lefthook and the pre-commit framework are refused, with
561
- the stanza to add to their own config file. simple-git-hooks and yorkie are
562
- refused too, and recognised from the declaration as well as from the hook
563
- file, because the declaration is there on a fresh clone where the generated
564
- hook is not yet: the `simple-git-hooks` or `gitHooks` key in package.json, or
565
- any of the standalone config files simple-git-hooks reads. Their hook text
566
- lives in package.json, which conductor does not write, so the guidance names
567
- the entry to add and `--force` does not override the refusal.
568
-
569
- That refusal applies only where git actually runs `.git/hooks`. Both managers
570
- write that directory and neither reads `core.hooksPath`, so a repository that
571
- has pointed git somewhere else has taken their file out of play, and init
572
- proceeds normally without mentioning them.
573
-
574
- `conductor run` runs every enabled gate and prints one report.
575
-
576
- - `--staged` gates the git index against HEAD, which is what the hook does.
577
- - `--format text|sarif`.
578
- - `--stage commit|push|ci` runs the gates at that stopping point and every
579
- earlier one. With no `--stage` at all, every enabled gate runs, whatever
580
- its stage. An unknown value is a usage error and exits 2 rather than
581
- quietly running everything or nothing: a typo in a CI file that runs every
582
- gate and one that runs none both look like a passing build.
583
- - `--base <ref>` measures the intent gate against what this branch changed
584
- since `<ref>`, rather than against the index. See "Intent at a pull
585
- request" below.
586
- - `--trust-base <ref>` reads the **rules** from `<ref>` instead of from the
587
- tree being judged: this repository's own `.guardrails.yaml`, and every
588
- control input of the gates that support it. See "The pull-request trust
589
- boundary" below. `--base` and `--trust-base` are independent and a
590
- pull-request run passes both: `--base` decides which paths are judged,
591
- `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
592
- set, an explicit `--trust-base` is accepted only when it resolves to the
593
- same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
594
- private `refs/conductor/trust-base` (issue #58); anyone invoking the
595
- CLI directly on a pull request, rather than through the Action, gets this
596
- as its own refusal, named below.
597
- - `--spec <path>` names the spec the intent gate imports its contract from.
598
- - `--output <path>` writes the report to a file instead of to stdout, for a
599
- CI step that uploads it. One line still goes to stdout, because a job whose
600
- only product is an uploaded artifact otherwise reads as a job that did
601
- nothing. A path that cannot be written is exit 2, not a green run beside a
602
- report nobody can read. A relative value resolves against the current
603
- directory the command was invoked from, not against `--project` or the
604
- repository root: with `--project` pointing elsewhere, a relative
605
- `--output` still lands next to where you are, not next to the repository
606
- being judged.
607
- - `--text-report <path>`, with `--format sarif`, also writes the text report
608
- to that file **from the same run**: exactly what `--format text` would have
609
- rendered for this result (`--verbose`, `--compact-on-refusal` and
610
- `--advisory` respected), and no gate is run a second time. This is how the
611
- Action gets a SARIF log, a comment body and a verdict token that are one
612
- run's answer. With `--format text` it is refused as a usage error (exit 2),
613
- before any gate runs: the text report is the output already, so a second
614
- copy in a file would only duplicate it. A path that cannot be written is
615
- exit 2, like `--output`. See "The verdict token" below.
616
- - `--verbose` prints the full per-gate report even when the run is clean.
617
- Text output only; the SARIF log never changes shape with it. Without it a
618
- gate prints its first 20 findings, blocking first, and one line saying how
619
- many more there are; every count, the verdict and SARIF include all of
620
- them. `--verbose` also lists the lockfiles behind an osv-scanner line
621
- that groups one advisory across several ("lodash@4.17.20 2 lockfiles
622
- fix 4.17.21"). A gitleaks finding shows its short commit and the
623
- fingerprint `.gitleaksignore` takes.
624
- - `--compact-on-refusal` shrinks the report to the version, the verdict and
625
- the refusal reason when the trust base was refused and no gate ran,
626
- instead of the full per-gate report. Built for the pull-request-comment
627
- step. It has no effect on a run that was not refused, whatever `--verbose`
628
- says. Text output only; it has no effect on the SARIF log and never
629
- changes the exit code.
630
- - `--gate <role>`, repeatable. A gate the policy file enables and this flag
631
- leaves out is named as excluded, on one line in the text report and as a
632
- `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
633
- It never reaches the exit code.
634
- - `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
635
- finding no longer fails. A gate that could not run is unaffected and still
636
- exits 2, so a crashed install or a missing policy still shows red rather
637
- than a silent green: this flag changes what a **finding** does, never what
638
- a **broken gate** does. The report is unchanged, a blocking finding still
639
- prints with its `BLOCKING` marker, and only the process exit and the
640
- verdict line's own wording (it says findings were advisory and did not
641
- block) change. Text output only; the SARIF log has no verdict line to
642
- change and its `properties.blocking` on each result is unaffected.
643
- - `--project <dir>` runs against that repository instead of the current
644
- directory, resolved to its git top level the same way the current
645
- directory already is, so a subdirectory resolves to that repository's top
646
- level. A relative value resolves against the current directory. A path
647
- that does not exist, is not a directory, or is not inside a git repository
648
- is a usage error naming the path and exits 2 rather than falling back to
649
- the current directory.
650
-
651
- ### Exit codes
652
-
653
- - **0** every enabled gate ran and none blocked.
654
- - **1** every enabled gate ran and at least one blocked.
655
- - **2** an enabled gate could not run: its binary is missing, it exited with
656
- its own could-not-run code, it exited 1 with nothing parseable on
657
- stdout, which is what a rejected config file looks like from two of the
658
- three family gates, or conductor stopped it at its time limit
659
- (`timed-out`, see `timeout-seconds` in the policy file).
660
-
661
- The external gates' exits are read per tool. gitleaks exits 1 for an error
662
- as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
663
- (blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
664
- when git itself fails (a base ref the checkout never fetched), so a clean
665
- exit that logged an `ERR` line is could-not-run too, never a pass. A
666
- gitleaks exit with no report file behind it is could-not-run. osv-scanner is
667
- handed every tracked lockfile by name, at any depth, never under
668
- `node_modules`: `package-lock.json`, `npm-shrinkwrap.json`,
669
- `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `go.mod`, `poetry.lock`,
670
- `Pipfile.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `Gemfile.lock`,
671
- `composer.lock`, `gradle.lockfile`, `packages.lock.json`, `mix.lock`,
672
- `pubspec.lock`, `Package.resolved`, `conan.lock`, `renv.lock`,
673
- `packages.config`, `buildscript-gradle.lockfile`, `gems.locked`,
674
- `pylock.toml`, `cabal.project.freeze`, `stack.yaml.lock` and
675
- `verification-metadata.xml` inside a `gradle` directory, and pip
676
- requirements files (`requirements.txt`, `requirements-dev.txt`,
677
- `requirements_test.txt`, `requirements.prod.txt`, `dev-requirements.txt`)
678
- whose every requirement, includes followed, is pinned with `==`. `go.sum`
679
- is never handed over: osv-scanner reads `go.mod` for Go. A requirements
680
- file with an unpinned line, or an include that is missing, untracked or
681
- outside the repository, is not scanned and is named in a
682
- `conductor/requirements-not-scanned` note with the line that stopped it,
683
- because any version osv-scanner reported for it would be a guess.
684
- Requirements files are scanned with `--no-resolve`: direct requirements
685
- only, as written, and the report says so per file. On a pull request a
686
- requirements file that is pinned on the base stays scanned even when the
687
- pull request adds an unpinned line to it. When the repository tracks none
688
- of these, osv-scanner is not spawned at all and the gate is reported clean
689
- with a `conductor/nothing-to-scan` note, so a docs-only repository is not
690
- red on every pull request. The note says that nothing was scanned and names
691
- the tracked manifests that were not handed to osv-scanner (a
692
- `pyproject.toml`, a `go.sum`, a `Dockerfile`, a workflow, or a requirements
693
- file the pin check left out), so a green gate is not read as a scan of
694
- them. A `go.mod` or a pinned requirements file is handed over and so is
695
- never on that list. It says nothing about what other gates read. When
696
- other lockfiles WERE handed over, the same list (a `Podfile.lock` beside a
697
- scanned `mix.lock`, say) is printed as a `conductor/manifests-not-handed`
698
- note under the gate instead. Its 1 is
699
- blocked. Its own 128 ("no package sources found") on lockfiles it WAS
700
- handed means they parsed to no packages; that is clean too, with a distinct
701
- `conductor/lockfiles-empty` note naming the files. When some handed
702
- lockfiles had packages and one had none (a lockfile rewritten to `{}` beside
703
- others), the same note names the empty one and the `lockfiles` line marks it
704
- `[no packages read]`; the verdict over the other files is unchanged. That
705
- naming reads osv-scanner's own per-file count, which it prints at its
706
- default verbosity. Lockfiles inside git
707
- submodules are never listed. In a sparse
708
- checkout a tracked lockfile that is not on disk is still handed over and
709
- osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
710
- (127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
711
- osv-scanner older than 2.0 is could-not-run, naming the floor.
712
-
713
- `run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
714
- could not run is a different failure from a blocking finding, and advisory
715
- mode exists to leave that one alone. See "Running the gates as an advisory
716
- check" below.
717
-
718
- ### The verdict token
719
-
720
- The text report carries one more line: `verdict-token: <token>`, the **second
721
- line**, directly under the version line (the closing `verdict:` sentence is
722
- unchanged). It is a label for the umbrella's own exit decision, in a closed
723
- set, so a person or a script can read the state without parsing a sentence.
724
- It decides nothing and never overrules a gate: it is derived from the exit
725
- code and the `enforce` flags the run already had.
726
-
727
- - `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
728
- could not run. Under `present-on-base: report` a `pass` can carry known
729
- vulnerabilities already on the base branch, reported and not blocking;
730
- the report's third line then says `present-on-base: N reported, not
731
- blocking`, the verdict sentence says the same, and the Action copies that
732
- line to the job summary under the token. When the intent gate's spec was
733
- chosen weakly, differently than before 0.11.0, or not at all because of a
734
- tie or a branch 0.10.0 bound, the line after the token (after the
735
- present-on-base line, when there is one) is one of four fixed
736
- `intent-spec:` lines naming no branch or file, and the Action copies that
737
- one too.
738
- - `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
739
- all (none is enabled, or every enabled one was deferred to a later stage,
740
- had nothing to judge, or was skipped), or every gate that ran examined
741
- nothing: the vulnerabilities gate with no lockfile it reads, or the intent
742
- gate with no contract to check against. The second case was `pass` in
743
- 0.8.x. The exit status is unchanged, since nothing failed, but this is not
744
- a pass: nothing was verified. In the Action the `verdict` output carries
745
- this token, so a workflow can tell it apart from `pass`.
746
- - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
747
- it exit 0. N is the blocking findings on enforced gates.
748
- - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
749
- blocking findings or could not run. N counts those findings plus those
750
- gates. Exit 0 here is not a pass, and the token says so.
751
- - `blocked (N)`: exit 1. N as for `advisory-blocked`.
752
- - `could-not-run`: exit 2, a refused trust base included.
753
-
754
- When several apply the order is `could-not-run`, then `blocked` or
755
- `advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
756
- ran, or none that ran checked anything) or `pass`. A run with
757
- `--advisory` whose only blocking findings sit on an unenforced gate is
758
- `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
759
- there. A gate skipped for want of a contract does not by itself move the token
760
- off `pass` when another gate ran and checked something; when no gate ran, or
761
- every gate that ran checked nothing, the token is `nothing-checked` and the
762
- verdict sentence says "nothing was checked". A
763
- gate that exited non-zero with no finding marked blocking counts as one in N,
764
- so a state that is not a pass never prints a count of zero. The one-line
765
- summary of a clean, non-verbose run has no token line, since it is one line by
766
- design. `conductor run` also prints the token on its job-log line,
767
- `conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
768
-
769
- ## The pull-request trust boundary
770
-
771
- Every gate reads its own rules out of the repository it is judging. On a pull
772
- request the author controls that repository, so without this a pull request
773
- could turn a gate off in the same commit that carries the thing the gate
774
- exists to catch, and the report would say the run was clean. For the umbrella
775
- the sharpest version is `command:`, which names a program to run: a pull
776
- request could point a gate at a script it added in the same commit.
777
-
778
- **On a pull-request run the rules come from the base branch.** With
779
- `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
780
- git and judges the head tree against it. A trusted file at the base that git
781
- cannot read as a regular file (a symlink, a directory, a submodule, or a file
782
- below a symlinked or submodule directory) is could-not-run, never replaced by
783
- a default. Clear it by making the file a regular file on the base branch; the
784
- pull request that does so is judged against that same base, so it has to be
785
- merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
786
- pull request never takes effect for that run, `command:` and `args:`
787
- included, so **a pull request cannot change the rules it is judged by, and
788
- cannot choose the program that judges it, as long as that program is
789
- self-contained** (see the directory rule below). The same ref is passed
790
- down to every gate that supports it, so their contracts, configs and
791
- baselines come from the base branch too.
792
-
793
- **The program is checked as well as the rules.** Reading the rules from the
794
- base ref is worth nothing if the pull request supplies the binary that
795
- applies them, and without this it could, two ways that both look ordinary in
796
- a diff: a base `command:` pointing at a path inside the repository, where the
797
- head replaces the file behind the approved path; and no `command:` at all,
798
- where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
799
- because resolution prefers the repository's own copy over PATH so that a
800
- project pin beats a global install.
801
-
802
- **On a pull-request run `node_modules/.bin` is not consulted at all.** That
803
- second shape is closed one step earlier than the first, and this is why: what
804
- is installed there is chosen by the head's own manifest and lockfile, so it is
805
- never approved by any ref, and a repository whose gates are devDependencies
806
- would otherwise meet the program refusal on every ordinary pull request. So
807
- that location is simply not searched when a trust base is set. PATH and an
808
- absolute `command:` remain, and both still go through the program check below.
809
- The skip is never silent: one line in the full report and one
810
- `conductor/node-modules-skipped` note in the SARIF log name each gate and the
811
- copy that was not taken, and a gate with nothing on PATH either is
812
- could-not-run with `npm install -g` and the Action's version input named as
813
- the remedy. **Outside pull-request mode nothing changes**: your own checkout
814
- and your pre-commit hook still run the pin, which is what `pnpm exec` does in
815
- the same repository.
816
-
817
- **The versions that judge a pull request are pinned in the workflow file**,
818
- and that is the point: the pull request can change its own lockfile,
819
- manifest and `node_modules`, and none of those decide which conductor and
820
- which gates run over it any more. Be clear about what that does not cover.
821
- On a `pull_request` event GitHub runs the workflow as it is in the pull
822
- request's merge commit, so a pull request that edits the workflow file can
823
- change the pins or remove the gates step, exactly as it could rewrite any
824
- other step in your CI. The boundary here is against the tree choosing its
825
- own judge; the control for a workflow edit is branch protection on your
826
- base branch with review required for `.github/workflows`, and no action can
827
- provide that for you. Only `pull_request_target` runs the base branch's copy
828
- of a workflow, and that event exposes the base's secrets to the pull
829
- request's code, which is the wrong trade for a gate over untrusted changes.
830
-
831
- One part of that is closed, and only one. Because the pins are written in a
832
- file the pull request controls, a pull request could otherwise pin a gate
833
- **backward** to a published version that predates the rule which would have
834
- caught it: an exact version, so the validate step's shape check accepts it,
835
- and a change that reads as ordinary version management. **On a pull request
836
- the action now refuses any of the four `*-version` inputs naming a version
837
- below the one the action tag ships.** Pinning forward is still accepted.
838
- See "The Action" below.
839
-
840
- So on a pull-request run a gate's program must be **outside the working tree**
841
- (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
842
- **both** of these:
843
-
844
- - it is a **tracked regular file whose contents are identical** at the base
845
- ref and at the head commit; and
846
- - **the tree object id of its containing directory is identical** at those
847
- two refs, which is to say the pull request changed nothing anywhere in that
848
- directory's subtree.
849
-
850
- Both are compared with `git ls-tree` on both refs and never read from the
851
- working tree. The second is not belt and braces. A vendored gate is rarely
852
- one file: `vendor/vault-guard` execs `vendor/impl.sh`, and a pull request
853
- that leaves the wrapper byte for byte alone and rewrites the helper beside it
854
- passes a per-file check while running its own code. Comparing the directory
855
- covers every file under it at once, without this tool having to know what a
856
- wrapper calls.
857
-
858
- **What is and is not vetted**, exactly: the program file and everything in
859
- its directory subtree. Anything the program reaches **outside** that
860
- directory is not vetted at all, so an in-repo gate must be **self-contained
861
- within its own directory**. A program at the repository ROOT is refused, and
862
- the message says to give it a directory: at the root the containing directory
863
- is the whole repository, so the rule would mean "no pull request may change
864
- anything".
865
-
866
- A symlink inside the repository is refused on **its own entry**, before its
867
- target is considered: it is either untracked, or its tree entry is a link
868
- rather than a regular file, and either refuses. (A symlink whose own path is
869
- outside the tree but which points into it has its target vetted; that is the
870
- case following the link exists for.)
871
-
872
- Anything else is could-not-run for that gate, naming the path, and it reaches
873
- the exit code even where the policy sets `enforce: false`, because the gate
874
- produced no findings to un-enforce: the umbrella declined to run a program
875
- the pull request chose.
876
-
877
- Nothing under `node_modules` is ever base-approved, which is why the rule
878
- above does not look there at all. Were it to look, the answer would always be
879
- the same refusal: what is there is chosen by the head's own manifest and
880
- lockfile and installed by a step that runs before the gates, so git has no
881
- record of those bytes at either ref. A pull request that edits its lockfile to
882
- pull a different build of a gate has chosen its own judge just as surely as
883
- one that commits a stub. **Vendoring a gate still works**, on those
884
- terms: put it in its own directory, keep everything it needs inside that
885
- directory, and leave the whole directory alone in a pull request the gate is
886
- meant to judge. Changing it is not forbidden, it just has to land on the base
887
- branch first, like any other rule change.
888
-
889
- **A change to the rules is not refused, it is proposed.** Rules legitimately
890
- change, and a gate that blocked every such pull request would train people to
891
- bypass it. So a policy file that differs from the base ref's is reported as
892
- one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
893
- as one proposal each; a head `.guardrails.yaml` that is absent or does not
894
- parse gives one line saying its changes are not known, and when no effective
895
- key differs (a default spelled out, or the YAML reordered) the old single line,
896
- `policy changed in this pull request`, is kept. The run continues under the
897
- base ref's rules, and the change takes effect **after merge**, on the first
898
- run whose base branch carries it. The gates' own proposals are summed with it
899
- into one sentence, `N control change(s) proposed in this pull request`, on the
900
- one-line summary and on the verdict, with a line each under `--verbose` and a
901
- `conductor/control-change-proposed` notification each in the SARIF log. A
902
- reflow, a re-quote or an edited comment is not a proposal: the two files are
903
- compared as parsed documents.
904
-
905
- **An explicit `--trust-base` redirect gets a refusal on a pull request, at two
906
- places (issue #58), and neither closes the whole hole by itself.**
907
- `refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
908
- commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
909
- `origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
910
- longer matches either test, so a same-repo pull request could set
911
- `trust-base` to its own branch, in its own workflow file, and have conductor
912
- read `.guardrails.yaml` from the pull request after all, at which point the
913
- pull request controls the whole policy. dep-guard's own base input took the
914
- stronger line for its base input in 0.8.0: on a `pull_request` event an
915
- explicit value is refused outright.
916
-
917
- **The Action refuses an explicit redirect on `pull_request` and
918
- `pull_request_target` events.** Its validate step refuses a `trust-base`
919
- input outright on those events, naming the value given and the fix, which is
920
- to remove the input; see "The Action" below.
921
-
922
- **The CLI check catches a misconfigured or innocent-looking redirect when
923
- `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
924
- that variable is set, an explicit `--trust-base` is accepted only when it is
925
- `refs/conductor/trust-base`, the private ref the Action fetches the base
926
- branch into and always passes (that ref is the authority and is not compared
927
- with anything), or resolves to the same commit as
928
- `refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
929
- unaffected. A ref naming the pull request's own branch, or anything else that
930
- disagrees, is refused with both refs and both commits named, through the same
931
- could-not-run path as every other trust-base refusal: exit 2, the report
932
- leads with the reason, and nothing is checked. A short name that matches both
933
- a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
934
- refused as ambiguous: spell the ref in full. When neither resolves, this fails
935
- closed too, naming it, for the same reason the fetch-depth remedy below
936
- exists.
937
-
938
- **Neither layer closes anything against a pull request that edits its own
939
- workflow file.** A CLI invocation on a pull request can simply omit
940
- `--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
941
- and nothing here refuses either; the Action has the matching gap, since a
942
- pull request can pin `uses:` to a tag published before this fix, in its own
943
- workflow file. This is exactly the boundary "On a pull request those four
944
- inputs may not pin backward" (below, under "The Action") already draws for
945
- the four `*-version` inputs: the control for a workflow edit is branch
946
- protection on the base branch with review required for `.github/workflows`,
947
- and nothing in this section, or in that one, substitutes for it.
948
-
949
- **It fails closed.** A `--trust-base` that does not resolve is not a reason to
950
- fall back to the pull request's own file, because that fallback is the hole:
951
- the run exits 2 and the report **leads with the refusal**, naming the ref and
952
- the remedy, whether or not it can name any gate. That last part matters: with
953
- no base ref there is no base policy, so the only list of gates available is
954
- the head's, and a head that switches every gate off leaves it empty. So is a
955
- base ref that resolves to the head commit, or to a different commit carrying
956
- the head's tree, both of which would put the rules back inside the tree being
957
- judged while still reporting pull-request mode as on. Pass the base
958
- **branch**, never a SHA: on a `pull_request` event `github.sha` is the merge
959
- commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
960
- the run has no rules and exits 2 rather than using the pull request's; the
961
- file the pull request adds decides what runs once it is on the base branch.
962
-
963
- **One narrow exception to the equal-tree refusal (issue #69).** When a pull
964
- request's net diff is empty -- a value committed and then backed out inside
965
- the same pull request -- the merge ref GitHub builds has a tree
966
- byte-identical to the base's, and the refusal above would stop
967
- secrets-history from running on exactly the shape it exists to catch: the
968
- value is gone from the tree but still in the history between the base and
969
- HEAD. So the refusal makes one exception, and only one: when HEAD is a real
970
- merge commit (two or more parents) and `--trust-base` resolves to HEAD's
971
- **first** parent, the run is not refused. First-parent identity is the
972
- discriminator, not ancestry, because GitHub always builds the merge ref with
973
- the base branch as the first parent and the pull request's own head as the
974
- second: a trust base resolving to HEAD's **second** parent is also an
975
- ancestor and also carries the same tree, and it is exactly the ref this rule
976
- must keep refusing. In the accepted shape the umbrella still does not judge
977
- the unchanged tree as if it were the change: it runs every enabled gate
978
- whose input is git history rather than the tree -- gitleaks today -- with its
979
- ordinary arguments (already scoped to `<base>..HEAD`), and every other
980
- enabled gate is reported as tree-unchanged rather than spawned: one line in
981
- the full report, a clause on the one-line summary, and a
982
- `conductor/tree-unchanged` notification in the SARIF log, never reaching the
983
- exit code. Every other equal-tree shape -- a non-merge HEAD, the second
984
- parent, any other ancestor -- keeps refusing exactly as before.
985
-
986
- The exception needs HEAD's own parents, so it needs the same non-shallow
987
- checkout the rest of pull-request mode already requires: `fetch-depth: 0`
988
- (see below). On a depth-1 checkout git reports the merge commit with no
989
- parents at all, so the first-parent check cannot match and the run keeps
990
- refusing with the ordinary equal-tree message -- it fails closed rather than
991
- guessing. That loss costs nothing real: at depth 1 gitleaks could not have
992
- seen the backed-out commit either, since its own history scan has nothing
993
- before HEAD to scope `<base>..HEAD` against.
994
-
995
- That is why adopting conductor takes one merge before the gates can judge
996
- anything, and it is not an oversight: the policy file can name a program to
997
- run, so a run that read it from the pull request would let the pull request
998
- choose its own judge on exactly the repositories that have no rules yet. See
999
- "Adopting conductor" below for the sequence and for how to see what your
1000
- policy will do before you merge it.
1001
-
1002
- **Which gates are covered.** All five: dep-guard from **0.10.1**,
1003
- intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
1004
- external gates at their command-line floors, gitleaks **8.19.0** and
1005
- osv-scanner **2.0.0**. On a pull-request run an older family gate is
1006
- could-not-run rather than run outside pull-request mode.
1007
-
1008
- **The external gates get their pull-request mode from the umbrella.**
1009
- Neither tool has a `--trust-base`, and both auto-load a config from the tree
1010
- they scan, which on a pull request is the head: a pull request could add an
1011
- allowlist entry for exactly the secret or advisory it introduces. So on a
1012
- pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
1013
- from the base ref with `git show` and passes each tool that copy with
1014
- `--config`. When the base has none, the tool gets a neutral one (gitleaks'
1015
- built-in rules, an empty osv-scanner config) rather than nothing, because
1016
- nothing would let it find the head's file on its own. gitleaks'
1017
- `.gitleaksignore` is handled the same way, and because gitleaks also loads
1018
- the ignore file at the root of whatever it scans, the umbrella scans the
1019
- repository's git directory instead of the working tree on a pull request:
1020
- the same history, without the head's ignore file. A head-side change to any
1021
- of these files is reported as a proposal line and takes effect after merge,
1022
- exactly like a change to `.guardrails.yaml`. History is scoped to
1023
- `<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
1024
- another branch never reddens this one. Merge commits are scanned by their
1025
- first-parent diff, so a secret added inside a merge (while resolving a
1026
- conflict, say) is found; the same leak seen in a pull request's commit and
1027
- again in its merge is reported once, with the other commit listed.
1028
-
1029
- A base `.gitleaks.toml` can name another file with `[extend] path`, which
1030
- gitleaks resolves against its working directory. On a pull request
1031
- conductor copies every file in that chain from the base ref into a
1032
- directory of its own and runs gitleaks from there, so the head's copy of an
1033
- extended file is never read; a head-side edit to one is a proposal, and an
1034
- extended file the base does not have makes the gate could-not-run, naming
1035
- it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
1036
- because conductor reads gitleaks' error lines to tell a failed scan from a
1037
- clean one. Write the extend as a plain relative path in an `[extend]` table:
1038
- a base `.gitleaks.toml` whose extend target is a symbolic link, or which
1039
- writes the extend as an inline table or a quoted key, fails closed on every
1040
- pull request until it is rewritten that way.
1041
-
1042
- **Local runs and `.gitattributes`.** On a pull request gitleaks scans the
1043
- repository's git directory, where the head's `.gitattributes` is not read.
1044
- A local run scans the working tree, so a file your own `.gitattributes`
1045
- marks `binary` is skipped by gitleaks there. Pull requests are not affected.
1046
-
1047
- On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
1048
- inline `gitleaks:allow` comment does not hide a secret: an inline allow
1049
- lives in the tree being judged, so the pull request controls it. A
1050
- legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
1051
- `.gitleaksignore`, both of which conductor already reads from the base.
1052
- Local runs keep inline allows.
1053
-
1054
- osv-scanner is never pointed at a directory to walk, because its own walk
1055
- skips anything `.gitignore` matches, tracked or not, so one ignore line in a
1056
- pull request could hide a committed lockfile. conductor lists the tracked
1057
- lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
1058
- a pull request that list comes from the head's index, not the base ref: the
1059
- lockfiles are the tree being judged, and adding or removing one is visible
1060
- in the diff. Only the root `osv-scanner.toml` is read from the base and
1061
- passed with `--config`, which overrides any nested one for the run; a
1062
- nested one the pull request adds or edits is reported as a proposal.
1063
-
1064
- The umbrella asks each gate its version before it runs it. On a run with a
1065
- trust base, a gate older than its pull-request-mode minimum (intent-guard
1066
- 1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
1067
- never run without the flag: without it the gate would take its rules from
1068
- the tree being judged. The fix is to install that minimum or newer, or to
1069
- remove an explicit older version pin. A version that cannot be read at all
1070
- is could-not-run too: the umbrella cannot establish that the gate would
1071
- take its rules from the base ref. The one gate that runs without the flag
1072
- is an intent gate judging a contract imported from the base for the run,
1073
- whose project is a temporary directory with no repository to resolve a ref
1074
- in; that is never silent: it gets a line in the report, a clause on the
1075
- clean one-line summary, and a `conductor/trust-base-not-passed`
1076
- notification in the SARIF log.
1077
-
1078
- Outside pull-request mode nothing changes. A pre-commit hook and a direct run
1079
- on your own checkout are already inside the trust boundary, and neither passes
1080
- the flag.
1081
-
1082
- **In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
1083
- `GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
1084
- rules have to come from the base branch, and no base was named. Pass `--trust-base
1085
- refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
1086
- which always passes one. A pre-commit hook run inside a pull-request job hits
1087
- this too: skip the hook in CI, or pass the trust base to it.
1088
-
1089
- **On a pull-request run PATH holds only absolute entries, and conductor's own
1090
- git comes from outside the repository.** Empty and relative entries are
1091
- removed for conductor and every gate it starts, with one notice naming them,
1092
- and conductor runs the first git on PATH that lives outside the repository's
1093
- work tree; with none, the run is could-not-run and says to put git's own
1094
- directory on PATH. A gate found only through a removed entry is reported
1095
- missing; put it on an absolute PATH entry or name it with an absolute
1096
- `command:`. Every gate conductor starts, and everything a gate starts, gets
1097
- a PATH whose first entry is a private directory outside the repository
1098
- holding only that same git, so a gate that runs git by name runs it too; on
1099
- Windows no such directory is made and the gates look git up through the
1100
- cleaned PATH, and a system temp directory inside the repository is
1101
- could-not-run until TMPDIR names one outside it.
1102
-
1103
- **git 2.31 or later** is needed on a pull-request run with the secrets-history
1104
- gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1105
- which arrived in git 2.31. Only that gate checks: an older git makes it
1106
- could-not-run, naming the version, and the other gates run.
1107
-
1108
- ### Trying pull-request mode locally
1109
-
1110
- To see roughly what CI would say about a branch, check it out and name the
1111
- base as the trust base:
1112
-
1113
- ```
1114
- conductor run --trust-base refs/remotes/origin/main --verbose
1115
- ```
1116
-
1117
- `--trust-base` takes any ref git resolves in your clone, so use a clone with
1118
- the base branch present (the CI recipes use `fetch-depth: 0` for the same
1119
- reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
1120
- intent gate is measured from the trust base, so `--base` is optional; add
1121
- `--base <ref>` to measure from a different ref. Add `--stage ci` to run at
1122
- the stage the Action runs at.
1123
-
1124
- The gotcha is the same locally as in CI: the policy and the other control
1125
- files are read from the base ref, not from your working tree. A local edit to
1126
- `.guardrails.yaml` has no effect on a `--trust-base` run until the change is
1127
- on the base; it shows up as a proposal line in the report instead. To preview
1128
- a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1129
- conductor" above.
1130
-
1131
- Where the proposals appear under the Action: the job log gets a
1132
- `conductor: N control change(s) proposed in this pull request.` line followed
1133
- by one `conductor: proposed <product> <line>` line per proposal, and the step
1134
- summary gets the same count and up to 50 proposed lines under `control
1135
- changes:` in a text block, with a `(n more in the report)` line when there are
1136
- more. This does not depend on `pr-comment`. A proposed line that holds a
1137
- backtick or a character outside printable ASCII is replaced by a placeholder.
1138
-
1139
- ### The preview under the proposed rules
1140
-
1141
- A pull request that switches a gate on or off, or moves its `stage`, is judged
1142
- under the base's rules, so the author would not otherwise see what the
1143
- proposed rules say until after merge. With the preview, each role whose
1144
- `enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
1145
- policy with only `enabled`, `stage` and `enforce` taken from the head. Every
1146
- other head value, `command:`, `args:`, `options` and `timeout-seconds`
1147
- included, never reaches it: the base's command and the base's limit are what
1148
- run, and a base `command:` that resolves inside the working tree is refused
1149
- there. A gate's own config is another matter: in the preview, dep-guard and
1150
- vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
1151
- head, because previewing the proposed rules means their rules too, while
1152
- gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
1153
- refused in the preview, because it would build the head's code. The intent
1154
- gate is deferred and not previewed.
1155
-
1156
- **The preview decides nothing.** The exit code, the verdict token and the SARIF
1157
- results are those of the run under the base rules, whatever the preview finds
1158
- or however it fails. In the full report (`--verbose`, the form the Action
1159
- reads) the first four lines are untouched; in the one-line clean form the
1160
- primary report is a byte-for-byte prefix and the preview follows it. It prints after
1161
- the verdict under `Preview under the proposed rules (does not affect the
1162
- verdict)`, as `conductor: preview ...` lines in the job log, as note-level
1163
- `conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
1164
- run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
1165
- the step summary. The whole preview has a hard deadline of 300 seconds; a
1166
- gate reached with no budget left is listed as over budget, and one that starts and is killed at the deadline is could-not-run (timed-out). A gate section in the preview
1167
- uses the same words as a primary section, so a finding may read `BLOCKING`
1168
- there: it means the finding would block under the proposed rules, and it does
1169
- not affect this run. A pull-request comment is cut at 60000 characters, the
1170
- preview block first.
1171
-
1172
- Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
1173
- input, which defaults to `true`; any other value turns it off. There is no
1174
- preview when the head `.guardrails.yaml` does not parse.
1175
-
1176
- ## Intent at a pull request
1177
-
1178
- The intent gate is the only one of the five with any ceremony: its native
1179
- flow wants a contract approved before the work starts, which is a per-task
1180
- human step. That step is exactly what a pull request cannot carry, so at the
1181
- `ci` stage the umbrella stands in for it.
1182
-
1183
- **What it measures.** With `--base <ref>`, the changed-path set is what this
1184
- branch changed since it forked, from
1185
- `git diff --name-only --no-renames <base>...HEAD` in the repository root.
1186
-
1187
- With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
1188
- `refs/conductor/trust-base` (the Action's private fetch of the base) if that
1189
- exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
1190
- shadow it. The text report says which. An explicit `--base` that matches both
1191
- a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
1192
- (merge_group, workflow_dispatch, a CLI run), the change set is measured from
1193
- the trust base. With none of the three, the intent gate runs the way
1194
- it does at a commit: against the staged index, or the paths you name.
1195
-
1196
- **This is why a local preview and a pull-request run can disagree about a
1197
- missing contract.** The contract-discovery rules below (`--spec`, a frozen
1198
- native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
1199
- only engage once `--base` resolves to something, or `--spec` is given.
1200
- Neither is true of a plain `conductor run` on your own checkout, so a
1201
- repository with no contract gets intent-guard's own native answer instead:
1202
- `BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
1203
- approved contract and none exists. On a pull request `--base` is set, this
1204
- whole section's machinery engages, and a branch with nothing to import
1205
- lands in the no-contract state below instead: reported, and never reaching
1206
- the exit code. Read a local `BLOCKING` line on the intent gate as "there is
1207
- no contract for the umbrella to import here yet," not as "this pull request
1208
- will fail."
1209
-
1210
- A git failure here is **fail-closed**: could-not-run, so exit 2 for an
1211
- enforced gate and a note for an unenforced one. There is deliberately no
1212
- fallback to an empty path set, because an empty path set is what a passing
1213
- gate looks like. In Actions this is almost always a shallow checkout, so
1214
- **`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
1215
-
1216
- **On a pull-request run the base decides.** With `--trust-base`, whether a
1217
- frozen contract governs the pull request is read from the base ref alone. A
1218
- frozen contract on the base is used, ahead of everything in the list below,
1219
- `--spec` included (the report says so when `--spec` was given), and the gate
1220
- judges any edit to it against the base copy. That holds for every
1221
- intent-guard that can run on a pull-request run, since one older than its
1222
- pull-request-mode minimum is could-not-run rather than run without the base
1223
- ref. With no frozen contract on the
1224
- base, nothing in the pull request becomes the contract: a spec on the base,
1225
- found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
1226
- run `--spec` must be a plain path inside the repository that the base
1227
- carries), and otherwise
1228
- the gate is skipped with "No contract on the base". A contract or spec the
1229
- pull request adds is reported as a proposal, so adopting the intent gate
1230
- merges, and the next pull request is judged against it. Retiring or replacing
1231
- a frozen contract through a judged pull request is refused by the intent gate
1232
- itself and needs an administrator to merge it.
1233
-
1234
- **Where the contract comes from**, in order:
1235
-
1236
- 1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
1237
- outranks everything else in this list, and a path here that is not on
1238
- disk is reported rather than replaced: running a different contract than
1239
- the one somebody named is the wrong kindness. On a pull-request run it is
1240
- read from the base, and a frozen contract on the base takes precedence.
1241
- 2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
1242
- `<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
1243
- wherever a team has done it. Frozen is the test rather than present: an
1244
- unfrozen contract is a draft somebody left behind, and running the gate
1245
- against it fails every pull request on "not frozen by user" without
1246
- checking anything.
1247
-
1248
- The second path is the directory intent-guard used before 1.3.0, which
1249
- renamed it because `.conductor` had become the name of a different product
1250
- in this family. Both are read, so a repository on either version is
1251
- checked rather than blocked, and a run that used the old one says so: one
1252
- line on the gate's contract line in the text report, and an
1253
- `intent-guard/legacy-state-dir` notification in the SARIF log. If the
1254
- repository holds **both** directories, the gate does not run and says so,
1255
- naming both: that is the state intent-guard itself refuses every command
1256
- in, so the umbrella refuses on exactly the gate's rule rather than a
1257
- softer one. A `.conductor` holding nothing intent-guard wrote belongs to
1258
- something else and is ignored.
1259
- 3. The **first** `Spec: <path>` line in the pull request body, read from the
1260
- event payload at `GITHUB_EVENT_PATH`. A path here that is not on disk, or
1261
- one that leaves the repository, falls through to the next rule.
1262
- `Spec: none` is a **waiver**: it says this pull request deliberately has
1263
- no spec, so rule 4 is not tried and the gate reports itself skipped with
1264
- `intent-guard/contract-waived` instead of `intent-guard/no-contract`. The
1265
- token is exact and lowercase, a frozen contract at rule 2 still wins over
1266
- it, and `--spec` at rule 1 still overrides it.
1267
- 4. A markdown file **directly under** `docs/superpowers/specs` whose name
1268
- matches the branch on **whole words**. The branch slug is the branch name
1269
- with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
1270
- stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
1271
- ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
1272
- spaces. A spec is a candidate when one name's words appear, in order and
1273
- together, inside the other's, and at least one shared word is three or
1274
- more characters, contains a letter, and is not a common branch word
1275
- (`fix`, `feat`, `wip`, `docs`, and the rest of the list in
1276
- `src/intent-spec.ts`). Candidates are ranked by an equal name first, then
1277
- the most shared words, then the longest shared word, then the lexically
1278
- greatest filename among files with the same name (the newest date when
1279
- every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
1280
- Two different specs that tie are **not** guessed between: the gate is
1281
- skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
1282
- one shared word, or on word length alone, is used and the report says the
1283
- match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
1284
- the choice matters, say it: a `Spec:` line in the pull request body, or a
1285
- branch named after the spec.
1286
-
1287
- **A branch with neither** is a third state beside deferred and could-not-run:
1288
- the gate is switched on, it ran, and it had nothing to check. It gets one
1289
- line in the text report and one `intent-guard/no-contract` notification
1290
- in the `conductor` run, and it **never** reaches the exit code, enforced or
1291
- not. A branch with no spec is a branch this gate has no opinion about, and
1292
- turning that into a failed build is how a gate gets switched off across a
1293
- repository. A waived pull request lands in the same state and is reported
1294
- under its own `intent-guard/contract-waived` id, with its own wording on the
1295
- skipped line, in the verdict and on the one-line summary of a clean run, so a
1296
- reader can tell "nobody has written one" from "somebody decided against one"
1297
- wherever they meet it. An ambiguous branch, one two specs match equally,
1298
- lands in the same advisory state under its own `intent-guard/spec-ambiguous`
1299
- id, and never reaches the exit code either.
1300
-
1301
- **A repository with no contract yet is not a repository this gate can act
1302
- on**, and the no-contract skip line names `docs/superpowers/specs`, which is
1303
- a convention from this family's own tooling and not one an outside adopter
1304
- has reason to recognise. The next step, if you want this gate to have an
1305
- opinion here, is the one intent-guard's own documentation describes: draft a
1306
- contract naming the paths worth protecting, then freeze it, and keep the
1307
- frozen file committed so rule 2 above finds it on every pull request from
1308
- then on. Until you do that, a project rule that lives only in `AGENTS.md`
1309
- never blocks anything through this gate. intent-guard does read prose rules
1310
- files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
1311
- sources, but by its own design a constraint from that source is advisory
1312
- and leaves the exit code alone; only a user-stated constraint, or one
1313
- promoted with `intent-guard correct --promote`, can block. Conductor itself
1314
- never opens that file. What is enforced is the frozen contract or the
1315
- imported spec, never project convention documented in prose.
1316
-
1317
- **A waiver is a decision, recorded by whoever wrote the pull request body,
1318
- and that includes a contributor from a fork.** On the ordinary path, where a
1319
- repository has no frozen contract of its own, `Spec: none` means the intent
1320
- gate does not run at all on that pull request, and budget breaches are the
1321
- thing this gate blocks on. The one thing a waiver cannot override is a frozen
1322
- native contract, under either of the two paths above, which is checked first:
1323
- a repository that wants the gate to be non-waivable freezes a native contract
1324
- and keeps it committed. The branch-name convention is not a control either:
1325
- whoever names the branch chooses among the base's specs.
1326
-
1327
- **What blocks is unchanged.** Blocking stays where intent-guard puts it:
1328
- budget breaches block, subject to `enforce`. Drift on its own is reported and
1329
- not blocked, which is already intent-guard's own behaviour. The umbrella adds
1330
- no severity threshold of its own here either, and intent-guard 1.7.0's own
1331
- advance-notice warnings about an unmatchable `protected_paths` or
1332
- `allowed_paths` entry never reach the exit code either, right up until the
1333
- 2.0.0 release where intent-guard turns that same shape into a blocking
1334
- reason. Where they print depends on how much of the report is showing: as a
1335
- note under the intent gate in the full report (`--verbose`, a non-clean run,
1336
- or the pull-request comment, which the Action always renders with
1337
- `--verbose`), and, on an otherwise-clean run with neither, counted without
1338
- their text in the one-line summary's own note count instead.
1339
-
1340
- **A prose-sourced constraint finding is never marked blocking, even when the
1341
- run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
1342
- whose source is one of those same prose rules files at advisory: a strong
1343
- match is still reported, but it never raises the gate's own exit code. A run
1344
- that blocks on scope creep alone still carries that capped finding in its
1345
- report, and it is rendered as a non-blocking, lower-severity line in the text
1346
- report and with `properties.blocking: false` in SARIF, rather than inheriting
1347
- the run's own blocking flag the way every other drift finding does.
404
+ - The policy file: see [docs/policy-file.md](docs/policy-file.md).
405
+ - Commands, exit codes and the verdict token: see [docs/commands.md](docs/commands.md).
406
+ - The pull-request trust boundary: see [docs/pull-request-trust-boundary.md](docs/pull-request-trust-boundary.md).
407
+ - Intent at a pull request: see [docs/intent-at-a-pull-request.md](docs/intent-at-a-pull-request.md).
408
+ - Upgrading and the defaults per action tag: see [docs/upgrading.md](docs/upgrading.md).
409
+ - The Action recipes and inputs are the section [The Action](#the-action) below.
1348
410
 
1349
411
  ## The Action
1350
412
 
@@ -1441,7 +503,8 @@ rather than running without a trust base; the token exists only in that fetch
1441
503
  step and never in the gates), so the run takes
1442
504
  its configuration from the base branch and the pull request cannot change the
1443
505
  rules it is judged by; a change to the rules shows as a proposal line and
1444
- takes effect after merge. See "The pull-request trust boundary" above. On any
506
+ takes effect after merge. See
507
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
1445
508
  other event it passes nothing and behaviour is unchanged. The `trust-base`
1446
509
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
1447
510
  set. **On a `pull_request` or `pull_request_target` event this input is
@@ -1469,7 +532,8 @@ request being judged, and the version-pin protection described above
1469
532
  "protects nothing" against a tree that controls its own judge (the
1470
533
  validate step's own comment in `action.yml` says so in those words). A tag
1471
534
  moves when someone pushes it. Name this action by owner and the full commit
1472
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.14.0.
535
+ SHA instead. The recipes in this README name v0.15.0 that way, as
536
+ `vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0`.
1473
537
 
1474
538
  ```yaml
1475
539
  name: guardrails
@@ -1489,9 +553,9 @@ jobs:
1489
553
  fetch-depth: 0
1490
554
  - uses: actions/setup-node@v7
1491
555
  with:
1492
- node-version: '22.11.0'
556
+ node-version: '22.23.4'
1493
557
  - id: conductor
1494
- uses: vaultcompasshq/conductor@v0.14.0
558
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1495
559
  with:
1496
560
  output: conductor.sarif
1497
561
  - uses: github/codeql-action/upload-sarif@v3
@@ -1523,10 +587,32 @@ pinned `action.yml`, which is the version that commit ships, so the installed
1523
587
  umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
1524
588
  input is set and is older than the constants in that pinned action.yml, a
1525
589
  pull request run is refused and the validate step says to remove the input. A
1526
- newer value is accepted and is what gets installed. The three gate version
1527
- inputs can be left out too: each one then takes the default in the pinned
1528
- action.yml. The spelled-out example below names them when a workflow wants
1529
- that transparency.
590
+ newer value is accepted and is what gets installed.
591
+
592
+ **Omit the three gate version inputs too, unless you need to pin a gate
593
+ forward** (issue 145). Each one then takes the default in the pinned
594
+ action.yml, so the defaults travel with the tag and a Dependabot or Renovate
595
+ bump of the `uses:` line moves the gates with it. Pinned by hand, they do
596
+ not move: after the bump `dep-guard-version`, `vault-guard-version` or
597
+ `intent-guard-version` sits below the new tag's defaults, a pull request
598
+ refuses a pin below them, and that bump's own pull request goes red with
599
+ nothing wrong in it. The fix is in the same pull request: raise each pinned
600
+ line to the new tag's default (the CHANGELOG entry for the tag lists them,
601
+ and so does the table in [Upgrading](docs/upgrading.md)), or delete it. The
602
+ spelled-out example below names them when a workflow wants that
603
+ transparency, and carries that cost.
604
+
605
+ **The gates the Action installs are as new as the tag** (issue 146). A
606
+ tag's defaults can reach npm the same day the tag does, so they can be
607
+ younger than the minimum release age dep-guard holds your own dependencies
608
+ to (7 days by default, a check that runs when dep-guard runs with
609
+ `--online`). The Action installs them itself, outside your
610
+ lockfile, so dep-guard does not see them. To run older gates, pin the action
611
+ ref to an older tag, whose defaults are older; pinning the version inputs
612
+ below the tag's own defaults is refused on a pull request, because a pull
613
+ request must not choose an older, weaker judge. A Dependabot `cooldown`
614
+ setting on the `github-actions` ecosystem delays the bump itself by the
615
+ same number of days.
1530
616
 
1531
617
  ```yaml
1532
618
  name: guardrails
@@ -1554,8 +640,10 @@ jobs:
1554
640
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
1555
641
  # refuses because that client reports a clean install as tampered
1556
642
  # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
1557
- # can verify.
1558
- node-version: '22.11.0'
643
+ # can verify. 22.23.4 is the patched release this repository's own
644
+ # release job pins after the 2026-10-21 Node security release; the
645
+ # gates run over pull-request content under whatever Node you pick.
646
+ node-version: '22.23.4'
1559
647
  # NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
1560
648
  # No `pnpm install`, `npm ci`, build or test step: an install runs the
1561
649
  # repository's own lifecycle scripts (a root postinstall), and that code
@@ -1566,7 +654,7 @@ jobs:
1566
654
  # installs those itself, globally. Leave conductor-version unset so the
1567
655
  # umbrella is the default in the pinned action.yml.
1568
656
  - id: conductor
1569
- uses: vaultcompasshq/conductor@v0.14.0
657
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1570
658
  with:
1571
659
  output: conductor.sarif
1572
660
  # Exact versions, never a range and never "latest". These three
@@ -1577,9 +665,9 @@ jobs:
1577
665
  # request of their own. On a pull request the action refuses a pin
1578
666
  # below what the pinned action.yml ships, and the three lines can
1579
667
  # be left out entirely to take that action's own versions.
1580
- dep-guard-version: 0.16.1
1581
- vault-guard-version: 1.12.1
1582
- intent-guard-version: 1.10.1
668
+ dep-guard-version: 0.18.0
669
+ vault-guard-version: 1.13.0
670
+ intent-guard-version: 1.10.3
1583
671
  - uses: github/codeql-action/upload-sarif@v3
1584
672
  # Always: the log is most worth having on the run that failed.
1585
673
  if: always()
@@ -1603,7 +691,7 @@ jobs:
1603
691
  - uses: pnpm/action-setup@v4
1604
692
  - uses: actions/setup-node@v7
1605
693
  with:
1606
- node-version: '22.11.0'
694
+ node-version: '22.23.4'
1607
695
  cache: pnpm
1608
696
  - run: pnpm install --frozen-lockfile
1609
697
  - run: pnpm test
@@ -1745,12 +833,19 @@ days (issue #36) because the step's exit code was swallowed regardless of
1745
833
  which of the two reasons produced it. `advisory` fixes the failure that
1746
834
  caused that; `continue-on-error` is the thing that let it happen, so the two
1747
835
  do not belong in the same recipe. Set a step `timeout-minutes` as well: the
1748
- Action already caps each gate's own subprocess at 120 seconds and reports one
1749
- that exceeds it as could-not-run, so the timeout is an outer bound around the
1750
- whole run rather than the primary control. Make it at least what the primary
1751
- run needs plus 300 seconds (5 minutes), because the preview under the
1752
- proposed rules can use up to that much on a pull request that changes a
1753
- gate's `enabled` or `stage`; a step killed mid-preview has no verdict. Check
836
+ Action already caps each gate's own subprocess (by default 120 seconds for
837
+ the three family gates, 600 for gitleaks and 300 for osv-scanner, see the
838
+ time limits above) and reports one that exceeds it as could-not-run, so the
839
+ timeout is an outer bound around the whole run rather than the primary
840
+ control. It must not undercut those limits, because a step killed by its
841
+ own timeout has no verdict at all, where a gate stopped at its limit is
842
+ reported. Make it at least the sum of the enabled gates' limits plus 300
843
+ seconds for the preview under the proposed rules, which can use up to that
844
+ much on a pull request that changes a gate's `enabled` or `stage`, plus the
845
+ time the step spends installing the gates before any of them runs. With all
846
+ five gates at their defaults that is 1260 plus 300 seconds, 26 minutes,
847
+ before the install, so the recipe below says 30; raise it with any
848
+ `timeout-seconds` you raise. Check
1754
849
  out with `persist-credentials: false` so the gates never run with a token
1755
850
  left in the checkout's git config.
1756
851
 
@@ -1775,11 +870,13 @@ jobs:
1775
870
  persist-credentials: false
1776
871
  - uses: actions/setup-node@v7
1777
872
  with:
1778
- node-version: '22.11.0'
873
+ node-version: '22.23.4'
1779
874
  - id: conductor
1780
- # The primary run's need (here 5 minutes) plus 300 seconds.
1781
- timeout-minutes: 10
1782
- uses: vaultcompasshq/conductor@v0.14.0
875
+ # The enabled gates' own limits (all five at their defaults: 1260
876
+ # seconds) plus 300 seconds for the preview, rounded up. A step
877
+ # timeout below that can kill a full gitleaks scan and leave no verdict.
878
+ timeout-minutes: 30
879
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1783
880
  with:
1784
881
  pr-comment: true
1785
882
  advisory: true
@@ -1865,7 +962,7 @@ change and forget the other half.
1865
962
 
1866
963
  ### Adopting conductor
1867
964
 
1868
- See "Adopting conductor" near the top of this README for the ordered
965
+ See "Adopting conductor: the careful path" near the top of this README for the ordered
1869
966
  walkthrough: init, a first pull request in advisory mode, merge, then go
1870
967
  required. This subsection is the mechanism behind two of those steps.
1871
968
 
@@ -1915,7 +1012,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1915
1012
  # the pull request runs before the action in this job: no install, build
1916
1013
  # or test step here; those belong in a separate job. ...
1917
1014
  - id: conductor
1918
- uses: vaultcompasshq/conductor@v0.14.0
1015
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1919
1016
  with:
1920
1017
  output: conductor.sarif
1921
1018
  pr-comment: true
@@ -1937,7 +1034,7 @@ comment every time, the way the manual recipe below does. It runs on a
1937
1034
  gates step passed or failed, since a blocking run is the one an advisory
1938
1035
  check most needs a developer to actually see. The first line of every
1939
1036
  comment carries the version of conductor that produced it, the second line
1940
- carries the verdict token (see "The verdict token" above), and when the
1037
+ carries the verdict token (see [The verdict token](docs/commands.md#the-verdict-token)), and when the
1941
1038
  trust base was refused and no gate ran at all, the comment shrinks to the
1942
1039
  version, the verdict, and the refusal reason (with its remedy, when one
1943
1040
  applies) rather than the full per-gate report, so an adopter with no policy
@@ -1994,12 +1091,12 @@ per pull request.
1994
1091
 
1995
1092
  ```yaml
1996
1093
  - id: conductor-package-a
1997
- uses: vaultcompasshq/conductor@v0.14.0
1094
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1998
1095
  with:
1999
1096
  pr-comment: true
2000
1097
  pr-comment-marker: 'package-a'
2001
1098
  - id: conductor-package-b
2002
- uses: vaultcompasshq/conductor@v0.14.0
1099
+ uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
2003
1100
  with:
2004
1101
  pr-comment: true
2005
1102
  pr-comment-marker: 'package-b'
@@ -2099,67 +1196,6 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
2099
1196
  history between runs, and a new comment every time rather than an alert that
2100
1197
  closes when the finding goes away.
2101
1198
 
2102
- ## Upgrading
2103
-
2104
- An adopter pins two numbers, and they control different things.
2105
-
2106
- - **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
2107
- which `action.yml` runs. That file carries the defaults for the four
2108
- version inputs and the constants the pull-request backward-pin rule
2109
- measures a pin against.
2110
- - **The `conductor-version` input** picks which `@vaultcompass/conductor`
2111
- the install step installs. The same step installs the three gates at
2112
- `dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
2113
- Each input defaults to the version the tag shipped.
2114
-
2115
- **The recommended shape is to leave all four version inputs unset** and move
2116
- only the action ref. On a pull request, the validate step refuses an input
2117
- naming a version below the one the tag ships, so an explicit old pin breaks
2118
- the day you upgrade the ref (see "The Action" above). Outside a pull request
2119
- an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2120
- until the first pull request after the upgrade.
2121
-
2122
- **Pin the action ref to a full commit SHA** with the tag as a comment, for
2123
- example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.14.0`. To
2124
- find the SHA for a tag, run
2125
- `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2126
- the Releases page.
2127
-
2128
- **Dependabot or Renovate bumping that SHA changes the action ref only.** It
2129
- does not touch a `dep-guard-version`, `vault-guard-version`,
2130
- `intent-guard-version` or `conductor-version` you set by hand, so such a pin
2131
- must be raised or removed by hand in the same pull request, or that pull
2132
- request is refused by the rule above.
2133
-
2134
- **An action-only tag moves the tag while the npm package stays.** The
2135
- CHANGELOG marks these as "An action-only release" and says which
2136
- `conductor-version` default stays. `@vaultcompass/conductor` does not change
2137
- on those, so `conductor-version` need not change either; the gate defaults
2138
- may.
2139
-
2140
- Defaults per tag, taken only from CHANGELOG.md entries that state them. A
2141
- tag with no row here has an entry that does not state its defaults; read
2142
- `action.yml` at that tag.
2143
-
2144
- | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2145
- | --- | --- | --- | --- |
2146
- | v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
2147
- | v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
2148
- | v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
2149
- | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
2150
- | v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
2151
- | v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
2152
- | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
2153
- | v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
2154
- | v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
2155
- | v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
2156
- | v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
2157
- | v0.7.0 | package | 0.7.0 | none |
2158
- | v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
2159
- | v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
2160
- | v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
2161
- | v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
2162
-
2163
1199
  ## What is in and what is out
2164
1200
 
2165
1201
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,