@vaultcompass/conductor 0.4.7 → 0.6.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,8 +1,37 @@
1
1
  # conductor
2
2
 
3
- conductor is the optional layer over three guardrail gates that each work on
4
- their own. All it adds is one policy file, one init, one hook and one report.
5
- Delete it and every gate still runs, with exactly the configuration it had.
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.
8
+
9
+ It does that by running five gates over one policy file, one init, one
10
+ hook and one report: three from this family, and two the adopter already
11
+ installs, gitleaks for secrets anywhere in git history and osv-scanner for
12
+ known vulnerabilities. conductor scans nothing itself and installs nothing
13
+ that is not its own. Delete conductor and every one of those five still
14
+ runs, with exactly the configuration it had.
15
+
16
+ The claim is checked in public. The
17
+ [conductor-proof](https://github.com/vaultcompasshq/conductor-proof)
18
+ repository runs an ordinary gitleaks and osv-scanner job beside conductor,
19
+ with six pull requests left open on purpose, one planted problem each.
20
+ Read the checks on each pull request rather than this table.
21
+
22
+ | Planted problem | Ordinary job | conductor |
23
+ | --- | --- | --- |
24
+ | [A dependency whose name does not exist on npm](https://github.com/vaultcompasshq/conductor-proof/pull/6) | pass | fail |
25
+ | [A pull request that turns off its own checks, then adds that dependency](https://github.com/vaultcompasshq/conductor-proof/pull/7) | skipped | fail |
26
+ | [A credential-shaped string in a test fixture](https://github.com/vaultcompasshq/conductor-proof/pull/8) | fail | fail |
27
+ | [An edit to a path the intent contract protects](https://github.com/vaultcompasshq/conductor-proof/pull/11) | pass | fail |
28
+ | [A credential-shaped string committed, then replaced, so only history carries it](https://github.com/vaultcompasshq/conductor-proof/pull/15) | fail | fail |
29
+ | [A dependency at a version with a known advisory](https://github.com/vaultcompasshq/conductor-proof/pull/16) | fail | fail |
30
+
31
+ The rows where both fail are parity, not a catch: both jobs run gitleaks
32
+ and osv-scanner, so both see a credential shape, a credential in history,
33
+ and a known advisory. The other three are what a scanner that only knows
34
+ about vulnerabilities and secrets has no way to know.
6
35
 
7
36
  <!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
8
37
  The Vault & Compass guardrails are three gates over an AI-assisted coding
@@ -17,20 +46,212 @@ contract, and change budgets). Each one installs, configures and runs on its
17
46
  own;
18
47
  [conductor](https://www.npmjs.com/package/@vaultcompass/conductor) is the
19
48
  optional umbrella that runs them from one policy file, one hook and one
20
- report.
49
+ report, beside two scanners you install yourself:
50
+ [gitleaks](https://github.com/gitleaks/gitleaks) for secrets anywhere in git
51
+ history and [osv-scanner](https://github.com/google/osv-scanner) for known
52
+ vulnerabilities. conductor scans nothing itself and installs nothing that
53
+ is not its own.
21
54
  <!-- /guardrails-family -->
22
55
 
56
+ ## Adopting conductor
57
+
58
+ The first pull request under a policy conductor just added cannot be judged
59
+ by that policy, so plan for a short, ordered sequence rather than one
60
+ command: init, a first pull request in advisory mode, merge, then go
61
+ required.
62
+
63
+ 1. **Init.** Install the gates. Each of them is a working tool on its own,
64
+ and none of them needs this one:
65
+
66
+ ```
67
+ npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
68
+ ```
69
+
70
+ The umbrella is optional. Install it when running the three separately
71
+ has become the annoying part:
72
+
73
+ ```
74
+ npm install -g @vaultcompass/conductor
75
+ ```
76
+
77
+ The two external gates are installed by you, on your machine and in your
78
+ workflow, from their own releases: [gitleaks](https://github.com/gitleaks/gitleaks)
79
+ 8.19 or later and [osv-scanner](https://github.com/google/osv-scanner)
80
+ 2.x. conductor never downloads either one. It finds them on `PATH`, and
81
+ when one is enabled in the policy and missing, the run reports
82
+ could-not-run (exit 2) with the install step in the report. Two policy
83
+ lines switch them on:
84
+
85
+ ```yaml
86
+ gates:
87
+ secrets-history:
88
+ product: gitleaks
89
+ vulnerabilities:
90
+ product: osv-scanner
91
+ ```
92
+
93
+ **Globally, and that is the guidance for CI too.** A devDependency is
94
+ fine beside it for your own pre-commit hook, and nothing about a local
95
+ run changed. It is not what gates your pull requests: on a pull-request
96
+ run the umbrella never looks in `node_modules/.bin` at all, because what
97
+ is installed there is chosen by the head's own manifest and lockfile. The
98
+ Action installs all four packages itself, globally, at versions pinned in
99
+ your workflow file. See "The pull-request trust boundary" and "The
100
+ Action" below.
101
+
102
+ From the repository root, look before you write:
103
+
104
+ ```
105
+ conductor init --dry-run
106
+ ```
107
+
108
+ That prints every file it would write or change and writes nothing. Then:
109
+
110
+ ```
111
+ conductor init
112
+ ```
113
+
114
+ which writes `.guardrails.yaml` with every gate listed and only the ones
115
+ it found switched on, and `.guardrails/manifest.json`, the record init
116
+ reads back on a later `--revert`. The intent gate is written unenforced
117
+ unless a frozen contract already exists at `.intent-guard/intent-contract.yaml`,
118
+ in which case init enforces it from the start rather than leaving a
119
+ frozen contract's protected paths reporting without blocking. **It writes
120
+ no pre-commit hook unless you ask for one:**
121
+
122
+ ```
123
+ conductor init --hook
124
+ ```
125
+
126
+ adds one pre-commit hook on top of that, running every enabled gate whose
127
+ stage is `commit`. A CI-only adopter that never runs conductor locally can
128
+ stop at the first `conductor init`, with no hook at all.
129
+
130
+ **`.git/hooks` is never part of a clone**, so a hook one checkout has does
131
+ not follow a teammate's clone, or a fresh clone of your own: hooks are per
132
+ clone and per machine. Each clone that wants the hook runs
133
+ `conductor init --hook` once; a repository that already has
134
+ `.guardrails.yaml` gets only the hook from that run, since init never
135
+ rewrites a policy file that already exists.
136
+
137
+ Do not wire this into a `package.json` `prepare` script. A failing init
138
+ (no `.git` in a Docker build, a foreign hook already installed, husky's
139
+ own `prepare` key, or conductor not yet installed at install time) would
140
+ fail `npm install` itself for everyone who runs it, not only for the
141
+ person who wanted the hook.
142
+
143
+ **`.guardrails/manifest.json` records the absolute path on the machine
144
+ that ran `init`**, for the hook, when there is one, and for the policy
145
+ file alike, and
146
+ conductor does not add a `.gitignore` entry for it. That path is specific
147
+ to your checkout, so do not commit the file: add
148
+ `.guardrails/manifest.json` to your own `.gitignore` today. The file
149
+ lives inside your working tree so `--revert` can find it later, and
150
+ recording repo-relative paths there instead of absolute ones is a known
151
+ gap, not a design; it has not been fixed yet.
152
+
153
+ Commit something, now that `--hook` above has installed the pre-commit
154
+ hook (this walkthrough's output below only appears when the hook is
155
+ installed; a bare `conductor init` with no `--hook` runs no gate on
156
+ commit at all). A clean commit prints one line:
157
+
158
+ ```
159
+ 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.
160
+ ```
161
+
162
+ The line names every disposition a gate can have on that run, with its
163
+ count, even when the count is zero: ran, deferred to a later stage, left
164
+ out by `--gate`, not enforced, and suppressed findings. Which gates appear
165
+ in each depends on your policy file.
166
+
167
+ A commit with a staged credential in it prints the full report and exits 1:
168
+
169
+ ```
170
+ conductor 0.6.0
171
+ conductor run: 2 gate(s), 1 finding(s)
172
+
173
+ dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
174
+ threshold medium suppressed 0 ignored 0
175
+ mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
176
+
177
+ secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
178
+ BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
179
+ Possible secret of type 'anthropic'
180
+ threshold medium suppressed 0 ignored not reported
181
+ filesScanned 1 patternsActive 59
182
+
183
+ deferred intent intent-guard did not run here; it runs from stage ci onwards
184
+
185
+ verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
186
+ ```
187
+
188
+ The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
189
+ `dependencies`, and the `filesScanned`/`patternsActive` line under
190
+ `secrets`, are each gate's own run facts, one line per gate, added to the
191
+ full report so a reader can see what a gate actually scanned and with
192
+ what, not only its verdict.
193
+
194
+ Both gates there are the ones you installed a moment ago, running with
195
+ their own thresholds and their own baselines. The umbrella found nothing
196
+ of its own, because it looks for nothing of its own.
197
+
198
+ Before opening anything, run `conductor run --verbose` on this same
199
+ checkout. That is the full report your policy will produce for the
200
+ dependency and secrets gates, with no `--trust-base` involved: a direct
201
+ run on your own checkout is already inside the trust boundary, so it
202
+ reads the policy you just wrote. **It is not the full preview for the
203
+ intent gate.** Locally, with no `--base`, the intent gate runs the way it
204
+ runs at a commit: intent-guard's own native flow, which wants an approved
205
+ contract and reports `BLOCKING critical intent-guard/gate-blocked` when
206
+ there is none. On a pull request a base ref resolves (conductor reads
207
+ `GITHUB_BASE_REF`, which GitHub sets for the whole job on a
208
+ `pull_request` event), and the umbrella instead prepares a contract for the
209
+ intent gate itself; with no contract to import, that path reports the
210
+ gate `skipped ... no contract` and never reaches the exit code. So a
211
+ first pull request with no contract yet is not blocked by the intent gate
212
+ on the pull request, whatever the local preview showed a moment before.
213
+ See "Intent at a pull request" below for the full mechanism.
214
+
215
+ 2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
216
+ and the workflow together, with `advisory: true` and `pr-comment: true`
217
+ on the conductor step -- the recipe under "Running the gates as an
218
+ advisory check" below is a complete copy-paste job -- and leave the check
219
+ out of branch protection for this one pull request. The step still exits
220
+ 2 on this pull request even with `advisory: true`: the base branch has no
221
+ policy yet, so the run has no rules, and `advisory` never touches that
222
+ exit code, only a blocking finding's. Leaving the check out of branch
223
+ protection is what keeps that expected exit 2 from blocking the merge;
224
+ the step posts a comment saying so with the remedy on it, which is the
225
+ honest report of an unfinished adoption, not a broken tool.
226
+
227
+ 3. **Merge.** Every pull request after that is judged by the policy on the
228
+ base branch, and a change to that policy shows up as a proposal line and
229
+ takes effect after its own merge.
230
+
231
+ 4. **Go required.** Once a few ordinary pull requests have shown the report
232
+ reads the way you expect, remove `advisory: true` from the conductor step
233
+ and require the job's own check context in branch protection -- `gates`
234
+ in the recipes below, the job name, never the context the SARIF-upload
235
+ step reports under. That is the whole of turning this from an advisory
236
+ job into the one required check.
237
+
238
+ There is deliberately no mode in which the pull request's own policy file
239
+ decides the run, not even as a preview: step 1's preview gives you the same
240
+ report without putting a file the pull request controls behind a verdict on
241
+ the pull request page.
242
+
23
243
  ## Why
24
244
 
25
- Run all three and you have three inits, three config files, three output
26
- shapes, and three pre-commit hooks fighting over one file. That is the
245
+ Run all three family gates and you have three inits, three config files,
246
+ three output shapes, and three pre-commit hooks fighting over one file, and
247
+ a separate job for the two external scanners. That is the
27
248
  friction this repository removes, and that is all it removes:
28
249
 
29
250
  - **one policy file**, `.guardrails.yaml`, keyed by the role each gate
30
251
  fills rather than by the product filling it;
31
- - **one init**, which writes that file and a single pre-commit hook running
32
- every enabled gate whose stage is `commit`, which by default is every gate
33
- but the intent one;
252
+ - **one init**, which writes that file, and with `--hook` a single
253
+ pre-commit hook running every enabled gate whose stage is `commit`, which
254
+ by default is every gate but the intent one;
34
255
  - **one report**, as text for a terminal or as a single SARIF 2.1.0 log
35
256
  with one run per gate.
36
257
 
@@ -40,79 +261,10 @@ with ceremony rather than runtime named as the cost. A screenful of per-gate
40
261
  detail on a commit that found nothing is that cost, paid on every commit, and
41
262
  it is what makes a team switch a hook off.
42
263
 
43
- ## Quickstart
44
-
45
- Install the gates. Each of them is a working tool on its own, and none of
46
- them needs this one:
47
-
48
- ```
49
- npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
50
- ```
51
-
52
- The umbrella is optional. Install it when running the three separately has
53
- become the annoying part:
54
-
55
- ```
56
- npm install -g @vaultcompass/conductor
57
- ```
58
-
59
- **Globally, and that is the guidance for CI too.** A devDependency is fine
60
- beside it for your own pre-commit hook, and nothing about a local run changed.
61
- It is not what gates your pull requests: on a pull-request run the umbrella
62
- never looks in `node_modules/.bin` at all, because what is installed there is
63
- chosen by the head's own manifest and lockfile. The Action installs all four
64
- packages itself, globally, at versions pinned in your workflow file. See "The
65
- pull-request trust boundary" and "The Action" below.
66
-
67
- From the repository root, look before you write:
68
-
69
- ```
70
- conductor init --dry-run
71
- ```
72
-
73
- That prints every file it would write or change and writes nothing. Then:
74
-
75
- ```
76
- conductor init
77
- ```
78
-
79
- which writes `.guardrails.yaml` with every gate listed and only the ones it
80
- found switched on, plus one pre-commit hook running every enabled gate whose
81
- stage is `commit`.
82
-
83
- Commit something. A clean commit prints one line:
84
-
85
- ```
86
- 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. 1 note(s). Re-run with --verbose for the full report.
87
- ```
88
-
89
- A commit with a staged credential in it prints the full report and exits 1:
90
-
91
- ```
92
- conductor 0.4.7
93
- conductor run: 2 gate(s), 1 finding(s)
94
-
95
- dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
96
- threshold medium suppressed 0 ignored 0
97
-
98
- secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
99
- BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
100
- Possible secret of type 'anthropic'
101
- threshold medium suppressed 0 ignored not reported
102
-
103
- deferred intent intent-guard did not run here; it runs from stage ci onwards
104
-
105
- verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
106
- ```
107
-
108
- Both gates there are the ones you installed a moment ago, running with their
109
- own thresholds and their own baselines. The umbrella found nothing of its
110
- own, because it looks for nothing of its own.
111
-
112
264
  ## What it deliberately is not
113
265
 
114
- It is not a fourth gate. It finds no bugs of its own and scans nothing.
115
- Every finding about your code came from one of the three gates and is
266
+ It is not a sixth gate. It finds no bugs of its own and scans nothing.
267
+ Every finding about your code came from one of the five gates and is
116
268
  labelled with which one. The only findings it adds are about the gates
117
269
  themselves, and they are labelled `conductor`: a gate that is switched on
118
270
  and could not run, and a gate whose output it could not read. Those exist
@@ -122,8 +274,8 @@ whole family exists to prevent.
122
274
  It is not something you adopt before the gates are useful. Each gate keeps
123
275
  its own config file, its own baseline, its own thresholds, and its own exit
124
276
  codes. The umbrella never writes into any of them: it passes a policy to
125
- each gate as command-line flags, which every one of the three already
126
- treats as higher precedence than its own config. Delete this tool and every
277
+ each gate as command-line flags, which every one of them already treats as
278
+ higher precedence than its own config. Delete this tool and every
127
279
  gate still runs, with exactly the configuration it had, because nothing
128
280
  here ever touched it.
129
281
 
@@ -161,13 +313,26 @@ gates:
161
313
  enforce: false
162
314
  options:
163
315
  require-frozen: false
316
+ secrets-history:
317
+ product: gitleaks
318
+ enabled: true
319
+ stage: ci
320
+ enforce: true
321
+ vulnerabilities:
322
+ product: osv-scanner
323
+ enabled: true
324
+ stage: ci
325
+ enforce: true
164
326
 
165
327
  report:
166
328
  format: text
167
329
  ```
168
330
 
169
- **Gates are keyed by role**, not by product. `dependencies`, `secrets`,
170
- `intent`. The `product` field says which binary fills that role today.
331
+ **Gates are keyed by role**, not by product. `dependencies` (dep-guard),
332
+ `secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
333
+ (gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
334
+ the resolved dependency tree). The `product` field says which binary fills
335
+ that role today. The last two are external tools you install yourself.
171
336
 
172
337
  **`enabled`** defaults to true. A gate that is enabled and whose binary
173
338
  cannot be found is a blocking finding of the umbrella's own
@@ -176,7 +341,9 @@ cannot be found is a blocking finding of the umbrella's own
176
341
  **`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
177
342
  **cumulative** in that order, so a gate runs at its own stage and at every
178
343
  later one, and a run at `ci` runs everything that is enabled. The defaults
179
- are `commit` for `dependencies` and `secrets` and `ci` for `intent`.
344
+ are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
345
+ `secrets-history` and `vulnerabilities`: a history scan and a registry
346
+ lookup are pull-request work, not commit-time work.
180
347
 
181
348
  A gate held back by the stage filter is never silent. It is one line in the
182
349
  text report naming the stage it is waiting for, and a `conductor/gate-deferred`
@@ -190,7 +357,14 @@ enforced gate's do. The only thing it cannot do is change the exit code: its
190
357
  blocking findings do not raise it, and its failing to run at all does not
191
358
  make the run exit 2. That is the adoption ramp, so a gate can be switched on
192
359
  and read for a few weeks before it is allowed to refuse anybody's commit.
193
- `init` writes it out for every gate, and starts the intent gate at `false`.
360
+ `init` writes it out for every gate. For the intent gate it writes `true`
361
+ when a frozen contract already exists at init time
362
+ (`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
363
+ `.conductor/intent-contract.yaml`), since the ramp is already climbed by
364
+ then, and leaving it unenforced would silently let a frozen contract's
365
+ protected paths produce findings that never fail the check. It writes
366
+ `false`, with a comment explaining why, when there is no contract yet to
367
+ enforce against.
194
368
 
195
369
  **`options`** is handed to that gate unchanged. Each key is one of that
196
370
  gate's own long flags with the leading dashes stripped: `fail-on: high`
@@ -198,10 +372,18 @@ becomes `--fail-on high`, `online: true` becomes `--online`,
198
372
  `require-frozen: false` becomes `--no-require-frozen`, and a list becomes
199
373
  one flag per entry. The handful of flags the umbrella supplies itself (the
200
374
  JSON format flag, `--staged`, and the intent gate's `--project`) are
201
- rejected if you also set them, rather than being silently overridden.
375
+ rejected if you also set them, rather than being silently overridden. For
376
+ the external gates the umbrella writes `--report-format`, `--report-path`,
377
+ `--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
378
+ `--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
379
+ gitleaks, and
380
+ `--format`, `--config` and `--lockfile` to osv-scanner, so those are
381
+ reserved too. Narrow what either
382
+ tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
383
+ instead.
202
384
 
203
385
  **There is no shared severity threshold, on purpose.** One top-level
204
- `failOn` would read as one decision and mean three different things, so
386
+ `failOn` would read as one decision and mean five different things, so
205
387
  setting one is an error rather than a knob that half works. Each gate keeps
206
388
  its own threshold in its own `options` block, spelled the way that gate
207
389
  spells it.
@@ -213,21 +395,45 @@ that gate, for pointing at a build that is not installed anywhere.
213
395
 
214
396
  ## Commands
215
397
 
216
- `conductor init` writes the policy file and one pre-commit hook.
217
-
398
+ `conductor init` writes the policy file and `.guardrails/manifest.json`, the
399
+ record `--revert` reads back later. The manifest currently records absolute
400
+ machine paths rather than repo-relative ones (see "Adopting conductor"
401
+ above); do not commit it.
402
+
403
+ - `--hook` also writes one pre-commit hook running every enabled gate whose
404
+ stage is `commit`. Without it, init writes only the policy file and the
405
+ manifest: no hook, and none of the hook-manager detection below runs
406
+ either. `.git/hooks` is never part of a clone, so a hook one checkout has
407
+ does not follow a teammate's clone, or a fresh clone of your own; each
408
+ needs its own `conductor init --hook`. `--revert` still removes a hook a
409
+ previous `--hook` run left behind, whether or not this invocation passes
410
+ `--hook` itself.
218
411
  - `--dry-run` prints every file it would write or change and writes nothing.
219
412
  - `--revert` removes exactly what a previous init wrote, and nothing else.
220
413
  A file changed since init is reported and left alone.
221
414
  - `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
222
415
  Without it, init reports the collision and stops rather than stacking a
223
416
  second invocation of a gate that is already hooked. A hook the umbrella
224
- does not recognise is never replaced, with or without `--adopt`.
417
+ does not recognise is never replaced, with or without `--adopt`. Only
418
+ meaningful together with `--hook`; without it, init errors rather than
419
+ silently ignoring the flag, because there is no hook for it to act on.
225
420
  - `--force` acts on a file **conductor itself wrote** and that has changed
226
421
  since: on its own it replaces a managed hook somebody has edited, and with
227
422
  `--revert` it removes one, restoring an adopted hook if there was one. It
228
423
  never overrides a foreign-hook or gate-hook refusal, with or without
229
424
  `--adopt`: those hooks were never conductor's, and no flag here turns
230
- somebody else's file into one this tool may overwrite.
425
+ somebody else's file into one this tool may overwrite. Like `--adopt`,
426
+ only meaningful together with `--hook` on an init (not on a `--revert`);
427
+ without it, init errors.
428
+ - `--project <dir>` writes into that repository instead of the current
429
+ directory, resolved to its git top level the same way the current
430
+ directory already is, so a script can point init at a repository without a
431
+ `cd` compound.
432
+
433
+ The rest of this section, on hook managers already wired into the
434
+ repository, applies only when `--hook` is given: none of it is consulted,
435
+ and none of it can block the policy file from being written, on a plain
436
+ `conductor init`.
231
437
 
232
438
  Init recognises the hook manager already wired into the repository. husky is
233
439
  redirected to the tracked hook it maintains rather than the generated
@@ -262,13 +468,21 @@ proceeds normally without mentioning them.
262
468
  control input of the gates that support it. See "The pull-request trust
263
469
  boundary" below. `--base` and `--trust-base` are independent and a
264
470
  pull-request run passes both: `--base` decides which paths are judged,
265
- `--trust-base` decides what they are judged by.
471
+ `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
472
+ set, an explicit `--trust-base` is accepted only when it resolves to the
473
+ same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
474
+ CLI directly on a pull request, rather than through the Action, gets this
475
+ as its own refusal, named below.
266
476
  - `--spec <path>` names the spec the intent gate imports its contract from.
267
477
  - `--output <path>` writes the report to a file instead of to stdout, for a
268
478
  CI step that uploads it. One line still goes to stdout, because a job whose
269
479
  only product is an uploaded artifact otherwise reads as a job that did
270
480
  nothing. A path that cannot be written is exit 2, not a green run beside a
271
- report nobody can read.
481
+ report nobody can read. A relative value resolves against the current
482
+ directory the command was invoked from, not against `--project` or the
483
+ repository root: with `--project` pointing elsewhere, a relative
484
+ `--output` still lands next to where you are, not next to the repository
485
+ being judged.
272
486
  - `--verbose` prints the full per-gate report even when the run is clean.
273
487
  Text output only; the SARIF log never changes shape with it.
274
488
  - `--compact-on-refusal` shrinks the report to the version, the verdict and
@@ -290,6 +504,13 @@ proceeds normally without mentioning them.
290
504
  verdict line's own wording (it says findings were advisory and did not
291
505
  block) change. Text output only; the SARIF log has no verdict line to
292
506
  change and its `properties.blocking` on each result is unaffected.
507
+ - `--project <dir>` runs against that repository instead of the current
508
+ directory, resolved to its git top level the same way the current
509
+ directory already is, so a subdirectory resolves to that repository's top
510
+ level. A relative value resolves against the current directory. A path
511
+ that does not exist, is not a directory, or is not inside a git repository
512
+ is a usage error naming the path and exits 2 rather than falling back to
513
+ the current directory.
293
514
 
294
515
  ### Exit codes
295
516
 
@@ -298,7 +519,29 @@ proceeds normally without mentioning them.
298
519
  - **2** an enabled gate could not run: its binary is missing, it exited with
299
520
  its own could-not-run code, or it exited 1 with nothing parseable on
300
521
  stdout, which is what a rejected config file looks like from two of the
301
- three.
522
+ three family gates.
523
+
524
+ The external gates' exits are read per tool. gitleaks exits 1 for an error
525
+ as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
526
+ (blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
527
+ when git itself fails (a base ref the checkout never fetched), so a clean
528
+ exit that logged an `ERR` line is could-not-run too, never a pass. A
529
+ gitleaks exit with no report file behind it is could-not-run. osv-scanner is
530
+ handed every tracked lockfile by name (`package-lock.json`,
531
+ `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, at any
532
+ depth, never under `node_modules`); when the repository tracks none, it is
533
+ not spawned at all and the gate is reported clean with a
534
+ `conductor/nothing-to-scan` note, so a docs-only repository is not red on
535
+ every pull request. Its 1 is blocked. Its own 128 ("no package sources
536
+ found") on lockfiles it WAS handed means they parsed to no packages; that is
537
+ clean too, with a distinct `conductor/lockfiles-empty` note naming the
538
+ files. Only those npm-family names are handed over today: a repository
539
+ whose only lockfile belongs to another ecosystem gets nothing-to-scan from
540
+ this gate. Lockfiles inside git submodules are never listed. In a sparse
541
+ checkout a tracked lockfile that is not on disk is still handed over and
542
+ osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
543
+ (127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
544
+ osv-scanner older than 2.0 is could-not-run, naming the floor.
302
545
 
303
546
  `run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
304
547
  could not run is a different failure from a blocking finding, and advisory
@@ -432,6 +675,46 @@ one-line summary and on the verdict, with a line each under `--verbose` and a
432
675
  reflow, a re-quote or an edited comment is not a proposal: the two files are
433
676
  compared as parsed documents.
434
677
 
678
+ **An explicit `--trust-base` redirect gets a refusal on a pull request, at two
679
+ places (issue #58), and neither closes the whole hole by itself.**
680
+ `refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
681
+ commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
682
+ `origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
683
+ longer matches either test, so a same-repo pull request could set
684
+ `trust-base` to its own branch, in its own workflow file, and have conductor
685
+ read `.guardrails.yaml` from the pull request after all, at which point the
686
+ pull request controls the whole policy. dep-guard's own base input took the
687
+ stronger line for its base input in 0.8.0: on a `pull_request` event an
688
+ explicit value is refused outright.
689
+
690
+ **The Action refuses an explicit redirect on `pull_request` and
691
+ `pull_request_target` events.** Its validate step refuses a `trust-base`
692
+ input outright on those events, naming the value given and the fix, which is
693
+ to remove the input; see "The Action" below.
694
+
695
+ **The CLI check catches a misconfigured or innocent-looking redirect when
696
+ `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
697
+ that variable is set, an explicit `--trust-base` is accepted only when it
698
+ resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
699
+ what the Action itself always passes, so an ordinary pull-request run is
700
+ unaffected. A ref naming the pull request's own branch, or anything else that
701
+ disagrees, is refused with both refs and both commits named, through the same
702
+ could-not-run path as every other trust-base refusal: exit 2, the report
703
+ leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
704
+ itself does not resolve, this fails closed too, naming it, for the same
705
+ reason the fetch-depth remedy below exists.
706
+
707
+ **Neither layer closes anything against a pull request that edits its own
708
+ workflow file.** A CLI invocation on a pull request can simply omit
709
+ `--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
710
+ and nothing here refuses either; the Action has the matching gap, since a
711
+ pull request can pin `uses:` to a tag published before this fix, in its own
712
+ workflow file. This is exactly the boundary "On a pull request those four
713
+ inputs may not pin backward" (below, under "The Action") already draws for
714
+ the four `*-version` inputs: the control for a workflow edit is branch
715
+ protection on the base branch with review required for `.github/workflows`,
716
+ and nothing in this section, or in that one, substitutes for it.
717
+
435
718
  **It fails closed.** A `--trust-base` that does not resolve is not a reason to
436
719
  fall back to the pull request's own file, because that fallback is the hole:
437
720
  the run exits 2 and the report **leads with the refusal**, naming the ref and
@@ -445,6 +728,39 @@ judged while still reporting pull-request mode as on. Pass the base
445
728
  commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
446
729
  the run has no rules and exits 2 rather than using the pull request's; the
447
730
  file the pull request adds decides what runs once it is on the base branch.
731
+
732
+ **One narrow exception to the equal-tree refusal (issue #69).** When a pull
733
+ request's net diff is empty -- a value committed and then backed out inside
734
+ the same pull request -- the merge ref GitHub builds has a tree
735
+ byte-identical to the base's, and the refusal above would stop
736
+ secrets-history from running on exactly the shape it exists to catch: the
737
+ value is gone from the tree but still in the history between the base and
738
+ HEAD. So the refusal makes one exception, and only one: when HEAD is a real
739
+ merge commit (two or more parents) and `--trust-base` resolves to HEAD's
740
+ **first** parent, the run is not refused. First-parent identity is the
741
+ discriminator, not ancestry, because GitHub always builds the merge ref with
742
+ the base branch as the first parent and the pull request's own head as the
743
+ second: a trust base resolving to HEAD's **second** parent is also an
744
+ ancestor and also carries the same tree, and it is exactly the ref this rule
745
+ must keep refusing. In the accepted shape the umbrella still does not judge
746
+ the unchanged tree as if it were the change: it runs every enabled gate
747
+ whose input is git history rather than the tree -- gitleaks today -- with its
748
+ ordinary arguments (already scoped to `<base>..HEAD`), and every other
749
+ enabled gate is reported as tree-unchanged rather than spawned: one line in
750
+ the full report, a clause on the one-line summary, and a
751
+ `conductor/tree-unchanged` notification in the SARIF log, never reaching the
752
+ exit code. Every other equal-tree shape -- a non-merge HEAD, the second
753
+ parent, any other ancestor -- keeps refusing exactly as before.
754
+
755
+ The exception needs HEAD's own parents, so it needs the same non-shallow
756
+ checkout the rest of pull-request mode already requires: `fetch-depth: 0`
757
+ (see below). On a depth-1 checkout git reports the merge commit with no
758
+ parents at all, so the first-parent check cannot match and the run keeps
759
+ refusing with the ordinary equal-tree message -- it fails closed rather than
760
+ guessing. That loss costs nothing real: at depth 1 gitleaks could not have
761
+ seen the backed-out commit either, since its own history scan has nothing
762
+ before HEAD to scope `<base>..HEAD` against.
763
+
448
764
  That is why adopting conductor takes one merge before the gates can judge
449
765
  anything, and it is not an oversight: the policy file can name a program to
450
766
  run, so a run that read it from the pull request would let the pull request
@@ -452,8 +768,66 @@ choose its own judge on exactly the repositories that have no rules yet. See
452
768
  "Adopting conductor" below for the sequence and for how to see what your
453
769
  policy will do before you merge it.
454
770
 
455
- **Which gates are covered.** All three: dep-guard from **0.6.0**,
456
- intent-guard from **1.4.0**, vault-guard from **1.7.0**.
771
+ **Which gates are covered.** All five: dep-guard from **0.6.0**,
772
+ intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
773
+ external gates at their command-line floors, gitleaks **8.19.0** and
774
+ osv-scanner **2.0.0**.
775
+
776
+ **The external gates get their pull-request mode from the umbrella.**
777
+ Neither tool has a `--trust-base`, and both auto-load a config from the tree
778
+ they scan, which on a pull request is the head: a pull request could add an
779
+ allowlist entry for exactly the secret or advisory it introduces. So on a
780
+ pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
781
+ from the base ref with `git show` and passes each tool that copy with
782
+ `--config`. When the base has none, the tool gets a neutral one (gitleaks'
783
+ built-in rules, an empty osv-scanner config) rather than nothing, because
784
+ nothing would let it find the head's file on its own. gitleaks'
785
+ `.gitleaksignore` is handled the same way, and because gitleaks also loads
786
+ the ignore file at the root of whatever it scans, the umbrella scans the
787
+ repository's git directory instead of the working tree on a pull request:
788
+ the same history, without the head's ignore file. A head-side change to any
789
+ of these files is reported as a proposal line and takes effect after merge,
790
+ exactly like a change to `.guardrails.yaml`. History is scoped to
791
+ `<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
792
+ another branch never reddens this one. Merge commits are scanned by their
793
+ first-parent diff, so a secret added inside a merge (while resolving a
794
+ conflict, say) is found; the same leak seen in a pull request's commit and
795
+ again in its merge is reported once, with the other commit listed.
796
+
797
+ A base `.gitleaks.toml` can name another file with `[extend] path`, which
798
+ gitleaks resolves against its working directory. On a pull request
799
+ conductor copies every file in that chain from the base ref into a
800
+ directory of its own and runs gitleaks from there, so the head's copy of an
801
+ extended file is never read; a head-side edit to one is a proposal, and an
802
+ extended file the base does not have makes the gate could-not-run, naming
803
+ it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
804
+ because conductor reads gitleaks' error lines to tell a failed scan from a
805
+ clean one. Write the extend as a plain relative path in an `[extend]` table:
806
+ a base `.gitleaks.toml` whose extend target is a symbolic link, or which
807
+ writes the extend as an inline table or a quoted key, fails closed on every
808
+ pull request until it is rewritten that way.
809
+
810
+ **Local runs and `.gitattributes`.** On a pull request gitleaks scans the
811
+ repository's git directory, where the head's `.gitattributes` is not read.
812
+ A local run scans the working tree, so a file your own `.gitattributes`
813
+ marks `binary` is skipped by gitleaks there. Pull requests are not affected.
814
+
815
+ On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
816
+ inline `gitleaks:allow` comment does not hide a secret: an inline allow
817
+ lives in the tree being judged, so the pull request controls it. A
818
+ legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
819
+ `.gitleaksignore`, both of which conductor already reads from the base.
820
+ Local runs keep inline allows.
821
+
822
+ osv-scanner is never pointed at a directory to walk, because its own walk
823
+ skips anything `.gitignore` matches, tracked or not, so one ignore line in a
824
+ pull request could hide a committed lockfile. conductor lists the tracked
825
+ lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
826
+ a pull request that list comes from the head's index, not the base ref: the
827
+ lockfiles are the tree being judged, and adding or removing one is visible
828
+ in the diff. Only the root `osv-scanner.toml` is read from the base and
829
+ passed with `--config`, which overrides any nested one for the run; a
830
+ nested one the pull request adds or edits is reported as a proposal.
457
831
 
458
832
  The umbrella asks each gate its version and passes the flag only to a build
459
833
  that understands it, so an older gate is not handed a flag it would reject. A
@@ -473,7 +847,7 @@ the flag.
473
847
 
474
848
  ## Intent at a pull request
475
849
 
476
- The intent gate is the only one of the three with any ceremony: its native
850
+ The intent gate is the only one of the five with any ceremony: its native
477
851
  flow wants a contract approved before the work starts, which is a per-task
478
852
  human step. That step is exactly what a pull request cannot carry, so at the
479
853
  `ci` stage the umbrella stands in for it.
@@ -486,6 +860,20 @@ With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
486
860
  set, and the text report says so. With neither, the intent gate runs the way
487
861
  it does at a commit: against the staged index, or the paths you name.
488
862
 
863
+ **This is why a local preview and a pull-request run can disagree about a
864
+ missing contract.** The contract-discovery rules below (`--spec`, a frozen
865
+ native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
866
+ only engage once `--base` resolves to something, or `--spec` is given.
867
+ Neither is true of a plain `conductor run` on your own checkout, so a
868
+ repository with no contract gets intent-guard's own native answer instead:
869
+ `BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
870
+ approved contract and none exists. On a pull request `--base` is set, this
871
+ whole section's machinery engages, and a branch with nothing to import
872
+ lands in the no-contract state below instead: reported, and never reaching
873
+ the exit code. Read a local `BLOCKING` line on the intent gate as "there is
874
+ no contract for the umbrella to import here yet," not as "this pull request
875
+ will fail."
876
+
489
877
  A git failure here is **fail-closed**: could-not-run, so exit 2 for an
490
878
  enforced gate and a note for an unenforced one. There is deliberately no
491
879
  fallback to an empty path set, because an empty path set is what a passing
@@ -544,6 +932,22 @@ skipped line, in the verdict and on the one-line summary of a clean run, so a
544
932
  reader can tell "nobody has written one" from "somebody decided against one"
545
933
  wherever they meet it.
546
934
 
935
+ **A repository with no contract yet is not a repository this gate can act
936
+ on**, and the no-contract skip line names `docs/superpowers/specs`, which is
937
+ a convention from this family's own tooling and not one an outside adopter
938
+ has reason to recognise. The next step, if you want this gate to have an
939
+ opinion here, is the one intent-guard's own documentation describes: draft a
940
+ contract naming the paths worth protecting, then freeze it, and keep the
941
+ frozen file committed so rule 2 above finds it on every pull request from
942
+ then on. Until you do that, a project rule that lives only in `AGENTS.md`
943
+ never blocks anything through this gate. intent-guard does read prose rules
944
+ files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
945
+ sources, but by its own design a constraint from that source is advisory
946
+ and leaves the exit code alone; only a user-stated constraint, or one
947
+ promoted with `intent-guard correct --promote`, can block. Conductor itself
948
+ never opens that file. What is enforced is the frozen contract or the
949
+ imported spec, never project convention documented in prose.
950
+
547
951
  **A waiver is a decision, recorded by whoever wrote the pull request body,
548
952
  and that includes a contributor from a fork.** On the ordinary path, where a
549
953
  repository has no frozen contract of its own, `Spec: none` means the intent
@@ -556,7 +960,24 @@ and keeps it committed.
556
960
  **What blocks is unchanged.** Blocking stays where intent-guard puts it:
557
961
  budget breaches block, subject to `enforce`. Drift on its own is reported and
558
962
  not blocked, which is already intent-guard's own behaviour. The umbrella adds
559
- no severity threshold of its own here either.
963
+ no severity threshold of its own here either, and intent-guard 1.7.0's own
964
+ advance-notice warnings about an unmatchable `protected_paths` or
965
+ `allowed_paths` entry never reach the exit code either, right up until the
966
+ 2.0.0 release where intent-guard turns that same shape into a blocking
967
+ reason. Where they print depends on how much of the report is showing: as a
968
+ note under the intent gate in the full report (`--verbose`, a non-clean run,
969
+ or the pull-request comment, which the Action always renders with
970
+ `--verbose`), and, on an otherwise-clean run with neither, counted without
971
+ their text in the one-line summary's own note count instead.
972
+
973
+ **A prose-sourced constraint finding is never marked blocking, even when the
974
+ run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
975
+ whose source is one of those same prose rules files at advisory: a strong
976
+ match is still reported, but it never raises the gate's own exit code. A run
977
+ that blocks on scope creep alone still carries that capped finding in its
978
+ report, and it is rendered as a non-blocking, lower-severity line in the text
979
+ report and with `properties.blocking: false` in SARIF, rather than inheriting
980
+ the run's own blocking flag the way every other drift finding does.
560
981
 
561
982
  ## The Action
562
983
 
@@ -640,7 +1061,15 @@ rules it is judged by; a change to the rules shows as a proposal line and
640
1061
  takes effect after merge. See "The pull-request trust boundary" above. On any
641
1062
  other event it passes nothing and behaviour is unchanged. The `trust-base`
642
1063
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
643
- set.
1064
+ set. **On a `pull_request` or `pull_request_target` event this input is
1065
+ refused outright, in the validate step** (issue #58). On `pull_request` the
1066
+ workflow file is the pull request's own, so a value here that redirects the
1067
+ trust base is settable by the thing it judges; on `pull_request_target` the
1068
+ workflow file is the *base* branch's own instead, but the input is refused
1069
+ there too, because pull-request mode already derives the trust base on both
1070
+ events and an explicit redirect has no legitimate use on either. The refusal
1071
+ names the value that was given and the fix, which is to remove the input: the
1072
+ action already derives `origin/$GITHUB_BASE_REF` itself on that event.
644
1073
 
645
1074
  There is deliberately **no input that turns pull-request mode off**.
646
1075
  Base-ref judging is the floor rather than a knob, and on a `pull_request`
@@ -668,14 +1097,14 @@ jobs:
668
1097
  contents: read
669
1098
  security-events: write
670
1099
  steps:
671
- - uses: actions/checkout@v4
1100
+ - uses: actions/checkout@v7
672
1101
  with:
673
1102
  fetch-depth: 0
674
- - uses: actions/setup-node@v4
1103
+ - uses: actions/setup-node@v7
675
1104
  with:
676
1105
  node-version: '22.11.0'
677
1106
  - id: conductor
678
- uses: vaultcompasshq/conductor@v0.4.7
1107
+ uses: vaultcompasshq/conductor@v0.6.0
679
1108
  with:
680
1109
  output: conductor.sarif
681
1110
  - uses: github/codeql-action/upload-sarif@v3
@@ -702,7 +1131,7 @@ jobs:
702
1131
  contents: read
703
1132
  security-events: write
704
1133
  steps:
705
- - uses: actions/checkout@v4
1134
+ - uses: actions/checkout@v7
706
1135
  with:
707
1136
  # Required, for two reasons now. Without it there is no merge base
708
1137
  # to diff against, and the intent gate fails closed rather than
@@ -711,7 +1140,7 @@ jobs:
711
1140
  # base ref that will not resolve is exit 2 for every enabled gate.
712
1141
  fetch-depth: 0
713
1142
  - uses: pnpm/action-setup@v4
714
- - uses: actions/setup-node@v4
1143
+ - uses: actions/setup-node@v7
715
1144
  with:
716
1145
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
717
1146
  # refuses because that client reports a clean install as tampered
@@ -724,7 +1153,7 @@ jobs:
724
1153
  # pinned below.
725
1154
  - run: pnpm install --frozen-lockfile
726
1155
  - id: conductor
727
- uses: vaultcompasshq/conductor@v0.4.7
1156
+ uses: vaultcompasshq/conductor@v0.6.0
728
1157
  with:
729
1158
  output: conductor.sarif
730
1159
  # Exact versions, never a range and never "latest". These four
@@ -735,10 +1164,10 @@ jobs:
735
1164
  # request of their own. Forward only on a pull request: the action
736
1165
  # refuses a pin below what its tag ships, and the four lines can be
737
1166
  # left out entirely to take that tag's own versions.
738
- conductor-version: 0.4.7
739
- dep-guard-version: 0.7.0
1167
+ conductor-version: 0.6.0
1168
+ dep-guard-version: 0.9.0
740
1169
  vault-guard-version: 1.8.0
741
- intent-guard-version: 1.5.2
1170
+ intent-guard-version: 1.7.0
742
1171
  - uses: github/codeql-action/upload-sarif@v3
743
1172
  # Always: the log is most worth having on the run that failed.
744
1173
  if: always()
@@ -754,6 +1183,37 @@ jobs:
754
1183
  sarif_file: ${{ steps.conductor.outputs.sarif }}
755
1184
  ```
756
1185
 
1186
+ **The two external gates are installed by your workflow, not by the
1187
+ Action.** The Action still installs exactly its four npm packages and has no
1188
+ input for gitleaks or osv-scanner; conductor downloads, pins and checksums
1189
+ no third-party binary. If the policy enables `secrets-history` or
1190
+ `vulnerabilities`, add a step before the conductor step that puts both tools
1191
+ on `PATH`, pinned by version and checked against the release's own
1192
+ checksum, the same way you would for a standalone security job:
1193
+
1194
+ ```yaml
1195
+ - name: Install gitleaks and osv-scanner
1196
+ run: |
1197
+ set -euo pipefail
1198
+ bin="$RUNNER_TEMP/external-gates"
1199
+ mkdir -p "$bin"
1200
+ cd "$RUNNER_TEMP"
1201
+ curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
1202
+ echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
1203
+ tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
1204
+ curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
1205
+ echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
1206
+ chmod +x "$bin/osv-scanner"
1207
+ echo "$bin" >> "$GITHUB_PATH"
1208
+ ```
1209
+
1210
+ `fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
1211
+ pull request conductor scans `<base>..HEAD`, and a base that was never
1212
+ fetched is a git error gitleaks itself would report as a clean scan of
1213
+ nothing. conductor reads that error off gitleaks' log and reports the gate
1214
+ as could-not-run instead. A missing tool is could-not-run as well, with the
1215
+ install step named in the report.
1216
+
757
1217
  The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
758
1218
  runs whatever its author pushes to it next. Pin every third-party action by
759
1219
  commit digest in a workflow you actually run, the way this repository's own
@@ -791,15 +1251,15 @@ jobs:
791
1251
  contents: read
792
1252
  pull-requests: write
793
1253
  steps:
794
- - uses: actions/checkout@v4
1254
+ - uses: actions/checkout@v7
795
1255
  with:
796
1256
  fetch-depth: 0
797
- - uses: actions/setup-node@v4
1257
+ - uses: actions/setup-node@v7
798
1258
  with:
799
1259
  node-version: '22.11.0'
800
1260
  - id: conductor
801
1261
  timeout-minutes: 5
802
- uses: vaultcompasshq/conductor@v0.4.7
1262
+ uses: vaultcompasshq/conductor@v0.6.0
803
1263
  with:
804
1264
  pr-comment: true
805
1265
  advisory: true
@@ -830,34 +1290,82 @@ author nothing they could not already do by editing the workflow to add
830
1290
  edit, is branch protection requiring review on `.github/workflows`, not
831
1291
  anything in `action.yml`.
832
1292
 
833
- ### Adopting conductor
1293
+ **A `paths:` filter on this job is a real trade, not a free speedup, and the
1294
+ honest default is to skip it.** The biggest reason is not about coverage, it
1295
+ is about merging at all: `paths:` applies to the workflow's own trigger, and
1296
+ a required check whose workflow a `paths:` filter kept from running is
1297
+ reported as never having run at all, not as passed. That check then sits
1298
+ **pending**, and a pull request cannot merge while a required check is
1299
+ pending, regardless of how trivial the change is. GitHub's own documentation
1300
+ describes exactly this failure mode for a required, `paths:`-filtered
1301
+ workflow, and its usual workaround: a job that always runs, regardless of
1302
+ what changed, and reports success or failure on its own rather than relying
1303
+ on the whole workflow being skipped or not.
1304
+
1305
+ The coverage cost is real too, separately from the merge-blocking one. Every
1306
+ gate in the default policy reads the whole changed set, not a slice of it:
1307
+ gitleaks scans git history, so a secret can land in any file regardless of
1308
+ what kind of pull request carries it; vault-guard's own staged scan is the
1309
+ same, over whatever paths changed; dep-guard and osv-scanner only care about
1310
+ manifests and lockfiles, but they still need to see a pull request touch one
1311
+ to react to it; and intent-guard's drift and budget checks are evaluated
1312
+ against every changed path, not only source. A `paths:` filter keyed on
1313
+ `package.json`, the lockfile, and your source globs is exactly right for
1314
+ dep-guard and osv-scanner and exactly wrong for the two secrets gates: it
1315
+ makes a docs-only pull request skip the whole job, gitleaks and vault-guard
1316
+ included, which means a secret pasted into a docs-only change, a comment, or
1317
+ a config file the filter did not list is never scanned at all. That is the
1318
+ cost, plainly: fewer runs bought by turning off secrets scanning on the pull
1319
+ requests the filter excludes.
1320
+
1321
+ If your workflow already has its own required security job and you only
1322
+ want this one to skip clean docs-only changes, add GitHub's own `paths:`
1323
+ (or `paths-ignore:`) to the `on: pull_request` block, the same syntax GitHub
1324
+ documents for any workflow trigger, and account for both traps above before
1325
+ you make the job required: the pull requests it would leave permanently
1326
+ pending, and the coverage this recipe would then lose on exactly the pull
1327
+ requests it skips. The alternative this README recommends is to leave
1328
+ the job triggering on every pull request: a run with nothing to report is
1329
+ not a run worth avoiding, and this recipe has no documented time budget to
1330
+ promise you here, because that number depends on your repository's size and
1331
+ the gates you enable, not on anything conductor fixes. Measure it once on
1332
+ your own repository if you need a number to plan around.
1333
+
1334
+ **Renaming the job changes what branch protection is watching for.** GitHub
1335
+ matches a required check by its context, which is the JOB's name (`gates`
1336
+ here), never the workflow's name (`guardrails-advisory`). If you split this
1337
+ into a paths-filtered job with a different name, or rename the job for any
1338
+ other reason, a pull request that no longer produces the old context name
1339
+ will sit waiting on a check that will never report, until you also update
1340
+ the required-checks list in
1341
+ the branch protection ruleset to match. That edit lives on the repository's
1342
+ settings, not in the workflow file, so it is easy to make the workflow
1343
+ change and forget the other half.
834
1344
 
835
- The first pull request cannot be judged by the policy it adds. Plan for two
836
- steps rather than being surprised by one:
837
-
838
- 1. On a branch, run `conductor init`, then run `conductor run --verbose` on
839
- your own checkout. That is the full report your policy will produce, with
840
- no `--trust-base` involved: a direct run on your own checkout is already
841
- inside the trust boundary, so it reads the policy you just wrote. This is
842
- where you tune thresholds, not on a pull request.
843
- 2. Open the pull request with `.guardrails.yaml` and the workflow together,
844
- and set `advisory: true` on the conductor step, the same as the advisory
845
- recipe above, and leave the check not required in branch protection for
846
- this one pull request. The step still exits 2 on this pull request even
847
- with `advisory: true`: the base branch has no policy yet, so the run has
848
- no rules, and `advisory` never touches that exit code, only a blocking
849
- finding's. Leaving the check unrequired is what keeps that expected exit 2
850
- from blocking the merge; the step posts a comment saying so with the
851
- remedy on it, which is the honest report of an unfinished adoption, not a
852
- broken tool.
853
- 3. Merge. Every pull request after that is judged by the policy on the base
854
- branch, and a change to that policy shows up as a proposal line and takes
855
- effect after its own merge.
1345
+ ### Adopting conductor
856
1346
 
857
- There is deliberately no mode in which the pull request's own policy file
858
- decides the run, not even as a preview: the preview in step 1 gives you the
859
- same report without putting a file the pull request controls behind a
860
- verdict on the pull request page.
1347
+ See "Adopting conductor" near the top of this README for the ordered
1348
+ walkthrough: init, a first pull request in advisory mode, merge, then go
1349
+ required. This subsection is the mechanism behind two of those steps.
1350
+
1351
+ **Why the first pull request still exits 2 under `advisory: true`.**
1352
+ `advisory: true` maps a blocking **finding** to exit 0; it has no opinion
1353
+ about a run that never had a policy to be judged by. The pull request that
1354
+ first adds `.guardrails.yaml` is judged against the base branch, which has
1355
+ none yet, so the run is refused outright before any gate produces a finding
1356
+ for `advisory` to act on. Leaving the check out of branch protection for
1357
+ that one pull request is what keeps the expected exit 2 from blocking the
1358
+ merge; the step posts a comment naming the ref and the remedy.
1359
+
1360
+ **Why "go required" means the job's own context, never the SARIF-upload
1361
+ row.** The recipes above upload conductor's SARIF log with
1362
+ `github/codeql-action/upload-sarif`, which can add its own code-scanning
1363
+ check to a pull request's checks list alongside the workflow job's own
1364
+ check. Branch protection's required-checks picker can then show both. Only
1365
+ the job's own context (`gates` in the recipes above, the job key, not any
1366
+ step name) carries conductor's actual exit code; a code-scanning check can
1367
+ read green from an old scan, or from `continue-on-error` on the upload step
1368
+ itself, independent of whether the gates step passed. Require the job.
861
1369
 
862
1370
  ### The report as a pull request comment
863
1371
 
@@ -875,7 +1383,7 @@ step and add `pull-requests: write` to the job's `permissions`:
875
1383
  steps:
876
1384
  # ... checkout, pnpm, setup-node, install, as in the example above ...
877
1385
  - id: conductor
878
- uses: vaultcompasshq/conductor@v0.4.7
1386
+ uses: vaultcompasshq/conductor@v0.6.0
879
1387
  with:
880
1388
  output: conductor.sarif
881
1389
  pr-comment: true
@@ -927,12 +1435,12 @@ per pull request.
927
1435
 
928
1436
  ```yaml
929
1437
  - id: conductor-package-a
930
- uses: vaultcompasshq/conductor@v0.4.7
1438
+ uses: vaultcompasshq/conductor@v0.6.0
931
1439
  with:
932
1440
  pr-comment: true
933
1441
  pr-comment-marker: 'package-a'
934
1442
  - id: conductor-package-b
935
- uses: vaultcompasshq/conductor@v0.4.7
1443
+ uses: vaultcompasshq/conductor@v0.6.0
936
1444
  with:
937
1445
  pr-comment: true
938
1446
  pr-comment-marker: 'package-b'
@@ -1035,12 +1543,16 @@ In: the policy file and its schema, `init` with dry-run, revert, and adopt,
1035
1543
  `run` producing the combined text report and a combined SARIF log, the
1036
1544
  composed exit code, per-gate `stage` and `enforce`, `run --stage`, the intent
1037
1545
  gate at a pull request (`--base`, `--spec`, the imported contract, the
1038
- no-contract advisory), and the composite Action.
1546
+ no-contract advisory), the two external gates (gitleaks over git history and
1547
+ osv-scanner over the dependency tree, run from `PATH`, their config read
1548
+ from the base ref on a pull request), and the composite Action.
1039
1549
 
1040
1550
  Out, deliberately: a unified baseline or ledger (each gate keeps its own, and
1041
1551
  their fingerprints are not equally durable, so one shared file would expire
1042
1552
  entries silently for one product and not another), an MCP registration,
1043
- running the gates concurrently, and any finding of the umbrella's own about
1553
+ running the gates concurrently, downloading or pinning any third-party
1554
+ binary (the adopter installs gitleaks and osv-scanner), and any finding of
1555
+ the umbrella's own about
1044
1556
  anybody's CODE. The findings it does raise are all about the gates
1045
1557
  themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
1046
1558
  and `conductor/gate-failed`, plus the two diagnostics
@@ -1053,7 +1565,8 @@ runs inside an agent session or on save, which intent-guard's own optional
1053
1565
  session hooks already cover.
1054
1566
 
1055
1567
  This is a young tool rather than a finished one. The gates are still the
1056
- product; this is the convenience layer over them.
1568
+ product, two of them are not this family's, and this is the layer that
1569
+ makes them one required check.
1057
1570
 
1058
1571
  ## Design notes
1059
1572
 
@@ -1070,4 +1583,4 @@ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repo
1070
1583
 
1071
1584
  ## License
1072
1585
 
1073
- MIT, [Vault & Compass](https://vaultcompass.io)
1586
+ MIT. Built by [Vault & Compass](https://vaultcompass.io).