@vaultcompass/conductor 0.5.0 → 0.7.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
@@ -16,7 +16,7 @@ runs, with exactly the configuration it had.
16
16
  The claim is checked in public. The
17
17
  [conductor-proof](https://github.com/vaultcompasshq/conductor-proof)
18
18
  repository runs an ordinary gitleaks and osv-scanner job beside conductor,
19
- with four pull requests left open on purpose, one planted problem each.
19
+ with six pull requests left open on purpose, one planted problem each.
20
20
  Read the checks on each pull request rather than this table.
21
21
 
22
22
  | Planted problem | Ordinary job | conductor |
@@ -25,10 +25,13 @@ Read the checks on each pull request rather than this table.
25
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
26
  | [A credential-shaped string in a test fixture](https://github.com/vaultcompasshq/conductor-proof/pull/8) | fail | fail |
27
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 |
28
30
 
29
- The third row is parity, not a catch: both jobs see a credential shape.
30
- The other three are what a scanner that only knows about vulnerabilities
31
- and secrets has no way to know.
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.
32
35
 
33
36
  <!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
34
37
  The Vault & Compass guardrails are three gates over an AI-assisted coding
@@ -43,7 +46,11 @@ contract, and change budgets). Each one installs, configures and runs on its
43
46
  own;
44
47
  [conductor](https://www.npmjs.com/package/@vaultcompass/conductor) is the
45
48
  optional umbrella that runs them from one policy file, one hook and one
46
- 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.
47
54
  <!-- /guardrails-family -->
48
55
 
49
56
  ## Adopting conductor
@@ -149,28 +156,42 @@ required.
149
156
  commit at all). A clean commit prints one line:
150
157
 
151
158
  ```
152
- 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.
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.
153
160
  ```
154
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
+
155
167
  A commit with a staged credential in it prints the full report and exits 1:
156
168
 
157
169
  ```
158
- conductor 0.5.0
170
+ conductor 0.7.0
171
+ verdict-token: blocked (1)
159
172
  conductor run: 2 gate(s), 1 finding(s)
160
173
 
161
- dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
174
+ dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
162
175
  threshold medium suppressed 0 ignored 0
176
+ mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
163
177
 
164
- secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
165
- BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
178
+ secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
179
+ BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
166
180
  Possible secret of type 'anthropic'
167
181
  threshold medium suppressed 0 ignored not reported
182
+ filesScanned 1 patternsActive 59
168
183
 
169
184
  deferred intent intent-guard did not run here; it runs from stage ci onwards
170
185
 
171
186
  verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
172
187
  ```
173
188
 
189
+ The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
190
+ `dependencies`, and the `filesScanned`/`patternsActive` line under
191
+ `secrets`, are each gate's own run facts, one line per gate, added to the
192
+ full report so a reader can see what a gate actually scanned and with
193
+ what, not only its verdict.
194
+
174
195
  Both gates there are the ones you installed a moment ago, running with
175
196
  their own thresholds and their own baselines. The umbrella found nothing
176
197
  of its own, because it looks for nothing of its own.
@@ -202,7 +223,9 @@ required.
202
223
  exit code, only a blocking finding's. Leaving the check out of branch
203
224
  protection is what keeps that expected exit 2 from blocking the merge;
204
225
  the step posts a comment saying so with the remedy on it, which is the
205
- honest report of an unfinished adoption, not a broken tool.
226
+ honest report of an unfinished adoption, not a broken tool. The same
227
+ refusal recurs once on every new base branch; see "Why the first pull
228
+ request still exits 2 under `advisory: true`" below.
206
229
 
207
230
  3. **Merge.** Every pull request after that is judged by the policy on the
208
231
  base branch, and a change to that policy shows up as a proposal line and
@@ -405,6 +428,10 @@ above); do not commit it.
405
428
  somebody else's file into one this tool may overwrite. Like `--adopt`,
406
429
  only meaningful together with `--hook` on an init (not on a `--revert`);
407
430
  without it, init errors.
431
+ - `--project <dir>` writes into that repository instead of the current
432
+ directory, resolved to its git top level the same way the current
433
+ directory already is, so a script can point init at a repository without a
434
+ `cd` compound.
408
435
 
409
436
  The rest of this section, on hook managers already wired into the
410
437
  repository, applies only when `--hook` is given: none of it is consulted,
@@ -444,13 +471,30 @@ proceeds normally without mentioning them.
444
471
  control input of the gates that support it. See "The pull-request trust
445
472
  boundary" below. `--base` and `--trust-base` are independent and a
446
473
  pull-request run passes both: `--base` decides which paths are judged,
447
- `--trust-base` decides what they are judged by.
474
+ `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
475
+ set, an explicit `--trust-base` is accepted only when it resolves to the
476
+ same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
477
+ CLI directly on a pull request, rather than through the Action, gets this
478
+ as its own refusal, named below.
448
479
  - `--spec <path>` names the spec the intent gate imports its contract from.
449
480
  - `--output <path>` writes the report to a file instead of to stdout, for a
450
481
  CI step that uploads it. One line still goes to stdout, because a job whose
451
482
  only product is an uploaded artifact otherwise reads as a job that did
452
483
  nothing. A path that cannot be written is exit 2, not a green run beside a
453
- report nobody can read.
484
+ report nobody can read. A relative value resolves against the current
485
+ directory the command was invoked from, not against `--project` or the
486
+ repository root: with `--project` pointing elsewhere, a relative
487
+ `--output` still lands next to where you are, not next to the repository
488
+ being judged.
489
+ - `--text-report <path>`, with `--format sarif`, also writes the text report
490
+ to that file **from the same run**: exactly what `--format text` would have
491
+ rendered for this result (`--verbose`, `--compact-on-refusal` and
492
+ `--advisory` respected), and no gate is run a second time. This is how the
493
+ Action gets a SARIF log, a comment body and a verdict token that are one
494
+ run's answer. With `--format text` it is refused as a usage error (exit 2),
495
+ before any gate runs: the text report is the output already, so a second
496
+ copy in a file would only duplicate it. A path that cannot be written is
497
+ exit 2, like `--output`. See "The verdict token" below.
454
498
  - `--verbose` prints the full per-gate report even when the run is clean.
455
499
  Text output only; the SARIF log never changes shape with it.
456
500
  - `--compact-on-refusal` shrinks the report to the version, the verdict and
@@ -472,6 +516,13 @@ proceeds normally without mentioning them.
472
516
  verdict line's own wording (it says findings were advisory and did not
473
517
  block) change. Text output only; the SARIF log has no verdict line to
474
518
  change and its `properties.blocking` on each result is unaffected.
519
+ - `--project <dir>` runs against that repository instead of the current
520
+ directory, resolved to its git top level the same way the current
521
+ directory already is, so a subdirectory resolves to that repository's top
522
+ level. A relative value resolves against the current directory. A path
523
+ that does not exist, is not a directory, or is not inside a git repository
524
+ is a usage error naming the path and exits 2 rather than falling back to
525
+ the current directory.
475
526
 
476
527
  ### Exit codes
477
528
 
@@ -509,6 +560,37 @@ could not run is a different failure from a blocking finding, and advisory
509
560
  mode exists to leave that one alone. See "Running the gates as an advisory
510
561
  check" below.
511
562
 
563
+ ### The verdict token
564
+
565
+ The text report carries one more line: `verdict-token: <token>`, the **second
566
+ line**, directly under the version line (the closing `verdict:` sentence is
567
+ unchanged). It is a label for the umbrella's own exit decision, in a closed
568
+ set, so a person or a script can read the state without parsing a sentence.
569
+ It decides nothing and never overrules a gate: it is derived from the exit
570
+ code and the `enforce` flags the run already had.
571
+
572
+ - `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
573
+ could not run.
574
+ - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
575
+ it exit 0. N is the blocking findings on enforced gates.
576
+ - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
577
+ blocking findings or could not run. N counts those findings plus those
578
+ gates. Exit 0 here is not a pass, and the token says so.
579
+ - `blocked (N)`: exit 1. N as for `advisory-blocked`.
580
+ - `could-not-run`: exit 2, a refused trust base included.
581
+
582
+ When several apply the order is `could-not-run`, then `blocked` or
583
+ `advisory-blocked`, then `unenforced-findings`, then `pass`. A run with
584
+ `--advisory` whose only blocking findings sit on an unenforced gate is
585
+ `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
586
+ there. A gate skipped for want of a contract does not by itself move the token
587
+ off `pass`; the verdict sentence is where "nothing was checked" is said. A
588
+ gate that exited non-zero with no finding marked blocking counts as one in N,
589
+ so a state that is not a pass never prints a count of zero. The one-line
590
+ summary of a clean, non-verbose run has no token line, since it is one line by
591
+ design. `conductor run` also prints the token on its job-log line,
592
+ `conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
593
+
512
594
  ## The pull-request trust boundary
513
595
 
514
596
  Every gate reads its own rules out of the repository it is judging. On a pull
@@ -636,6 +718,46 @@ one-line summary and on the verdict, with a line each under `--verbose` and a
636
718
  reflow, a re-quote or an edited comment is not a proposal: the two files are
637
719
  compared as parsed documents.
638
720
 
721
+ **An explicit `--trust-base` redirect gets a refusal on a pull request, at two
722
+ places (issue #58), and neither closes the whole hole by itself.**
723
+ `refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
724
+ commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
725
+ `origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
726
+ longer matches either test, so a same-repo pull request could set
727
+ `trust-base` to its own branch, in its own workflow file, and have conductor
728
+ read `.guardrails.yaml` from the pull request after all, at which point the
729
+ pull request controls the whole policy. dep-guard's own base input took the
730
+ stronger line for its base input in 0.8.0: on a `pull_request` event an
731
+ explicit value is refused outright.
732
+
733
+ **The Action refuses an explicit redirect on `pull_request` and
734
+ `pull_request_target` events.** Its validate step refuses a `trust-base`
735
+ input outright on those events, naming the value given and the fix, which is
736
+ to remove the input; see "The Action" below.
737
+
738
+ **The CLI check catches a misconfigured or innocent-looking redirect when
739
+ `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
740
+ that variable is set, an explicit `--trust-base` is accepted only when it
741
+ resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
742
+ what the Action itself always passes, so an ordinary pull-request run is
743
+ unaffected. A ref naming the pull request's own branch, or anything else that
744
+ disagrees, is refused with both refs and both commits named, through the same
745
+ could-not-run path as every other trust-base refusal: exit 2, the report
746
+ leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
747
+ itself does not resolve, this fails closed too, naming it, for the same
748
+ reason the fetch-depth remedy below exists.
749
+
750
+ **Neither layer closes anything against a pull request that edits its own
751
+ workflow file.** A CLI invocation on a pull request can simply omit
752
+ `--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
753
+ and nothing here refuses either; the Action has the matching gap, since a
754
+ pull request can pin `uses:` to a tag published before this fix, in its own
755
+ workflow file. This is exactly the boundary "On a pull request those four
756
+ inputs may not pin backward" (below, under "The Action") already draws for
757
+ the four `*-version` inputs: the control for a workflow edit is branch
758
+ protection on the base branch with review required for `.github/workflows`,
759
+ and nothing in this section, or in that one, substitutes for it.
760
+
639
761
  **It fails closed.** A `--trust-base` that does not resolve is not a reason to
640
762
  fall back to the pull request's own file, because that fallback is the hole:
641
763
  the run exits 2 and the report **leads with the refusal**, naming the ref and
@@ -649,6 +771,39 @@ judged while still reporting pull-request mode as on. Pass the base
649
771
  commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
650
772
  the run has no rules and exits 2 rather than using the pull request's; the
651
773
  file the pull request adds decides what runs once it is on the base branch.
774
+
775
+ **One narrow exception to the equal-tree refusal (issue #69).** When a pull
776
+ request's net diff is empty -- a value committed and then backed out inside
777
+ the same pull request -- the merge ref GitHub builds has a tree
778
+ byte-identical to the base's, and the refusal above would stop
779
+ secrets-history from running on exactly the shape it exists to catch: the
780
+ value is gone from the tree but still in the history between the base and
781
+ HEAD. So the refusal makes one exception, and only one: when HEAD is a real
782
+ merge commit (two or more parents) and `--trust-base` resolves to HEAD's
783
+ **first** parent, the run is not refused. First-parent identity is the
784
+ discriminator, not ancestry, because GitHub always builds the merge ref with
785
+ the base branch as the first parent and the pull request's own head as the
786
+ second: a trust base resolving to HEAD's **second** parent is also an
787
+ ancestor and also carries the same tree, and it is exactly the ref this rule
788
+ must keep refusing. In the accepted shape the umbrella still does not judge
789
+ the unchanged tree as if it were the change: it runs every enabled gate
790
+ whose input is git history rather than the tree -- gitleaks today -- with its
791
+ ordinary arguments (already scoped to `<base>..HEAD`), and every other
792
+ enabled gate is reported as tree-unchanged rather than spawned: one line in
793
+ the full report, a clause on the one-line summary, and a
794
+ `conductor/tree-unchanged` notification in the SARIF log, never reaching the
795
+ exit code. Every other equal-tree shape -- a non-merge HEAD, the second
796
+ parent, any other ancestor -- keeps refusing exactly as before.
797
+
798
+ The exception needs HEAD's own parents, so it needs the same non-shallow
799
+ checkout the rest of pull-request mode already requires: `fetch-depth: 0`
800
+ (see below). On a depth-1 checkout git reports the merge commit with no
801
+ parents at all, so the first-parent check cannot match and the run keeps
802
+ refusing with the ordinary equal-tree message -- it fails closed rather than
803
+ guessing. That loss costs nothing real: at depth 1 gitleaks could not have
804
+ seen the backed-out commit either, since its own history scan has nothing
805
+ before HEAD to scope `<base>..HEAD` against.
806
+
652
807
  That is why adopting conductor takes one merge before the gates can judge
653
808
  anything, and it is not an oversight: the policy file can name a program to
654
809
  run, so a run that read it from the pull request would let the pull request
@@ -848,7 +1003,24 @@ and keeps it committed.
848
1003
  **What blocks is unchanged.** Blocking stays where intent-guard puts it:
849
1004
  budget breaches block, subject to `enforce`. Drift on its own is reported and
850
1005
  not blocked, which is already intent-guard's own behaviour. The umbrella adds
851
- no severity threshold of its own here either.
1006
+ no severity threshold of its own here either, and intent-guard 1.7.0's own
1007
+ advance-notice warnings about an unmatchable `protected_paths` or
1008
+ `allowed_paths` entry never reach the exit code either, right up until the
1009
+ 2.0.0 release where intent-guard turns that same shape into a blocking
1010
+ reason. Where they print depends on how much of the report is showing: as a
1011
+ note under the intent gate in the full report (`--verbose`, a non-clean run,
1012
+ or the pull-request comment, which the Action always renders with
1013
+ `--verbose`), and, on an otherwise-clean run with neither, counted without
1014
+ their text in the one-line summary's own note count instead.
1015
+
1016
+ **A prose-sourced constraint finding is never marked blocking, even when the
1017
+ run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
1018
+ whose source is one of those same prose rules files at advisory: a strong
1019
+ match is still reported, but it never raises the gate's own exit code. A run
1020
+ that blocks on scope creep alone still carries that capped finding in its
1021
+ report, and it is rendered as a non-blocking, lower-severity line in the text
1022
+ report and with `properties.blocking: false` in SARIF, rather than inheriting
1023
+ the run's own blocking flag the way every other drift finding does.
852
1024
 
853
1025
  ## The Action
854
1026
 
@@ -917,9 +1089,10 @@ provenance even though all four packages publish it.
917
1089
  > points npm at a mirror or proxy that does not (via `actions/setup-node`'s
918
1090
  > `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
919
1091
  > install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
920
- > sigstore outage has the same effect. It fails closed on purpose, so that is a
921
- > red gate rather than a skipped check; pin to `@v0.4.0`, which does not
922
- > verify, if it blocks you.
1092
+ > sigstore outage has the same effect. The audit is retried once after a short
1093
+ > pause before the step fails, to absorb a one-off registry hiccup. It fails
1094
+ > closed on purpose, so that is a red gate rather than a skipped check; pin to
1095
+ > `@v0.4.0`, which does not verify, if it blocks you.
923
1096
 
924
1097
  `--base` is passed only when the `base-ref` input names one; left empty, the
925
1098
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
@@ -932,7 +1105,15 @@ rules it is judged by; a change to the rules shows as a proposal line and
932
1105
  takes effect after merge. See "The pull-request trust boundary" above. On any
933
1106
  other event it passes nothing and behaviour is unchanged. The `trust-base`
934
1107
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
935
- set.
1108
+ set. **On a `pull_request` or `pull_request_target` event this input is
1109
+ refused outright, in the validate step** (issue #58). On `pull_request` the
1110
+ workflow file is the pull request's own, so a value here that redirects the
1111
+ trust base is settable by the thing it judges; on `pull_request_target` the
1112
+ workflow file is the *base* branch's own instead, but the input is refused
1113
+ there too, because pull-request mode already derives the trust base on both
1114
+ events and an explicit redirect has no legitimate use on either. The refusal
1115
+ names the value that was given and the fix, which is to remove the input: the
1116
+ action already derives `origin/$GITHUB_BASE_REF` itself on that event.
936
1117
 
937
1118
  There is deliberately **no input that turns pull-request mode off**.
938
1119
  Base-ref judging is the floor rather than a knob, and on a `pull_request`
@@ -967,7 +1148,7 @@ jobs:
967
1148
  with:
968
1149
  node-version: '22.11.0'
969
1150
  - id: conductor
970
- uses: vaultcompasshq/conductor@v0.5.0
1151
+ uses: vaultcompasshq/conductor@v0.7.0
971
1152
  with:
972
1153
  output: conductor.sarif
973
1154
  - uses: github/codeql-action/upload-sarif@v3
@@ -977,6 +1158,14 @@ jobs:
977
1158
  sarif_file: ${{ steps.conductor.outputs.sarif }}
978
1159
  ```
979
1160
 
1161
+ The examples leave the trigger unnarrowed on purpose, so the job runs for a
1162
+ pull request into any branch. If you narrow it with a `branches:` filter,
1163
+ include every branch whose merges reach users, release branches and the
1164
+ production branch included, for instance `branches: [main, 'release/**',
1165
+ production]`. The pull request that promotes a release is where a bad
1166
+ dependency or a leaked secret actually ships, and a job that is not triggered
1167
+ leaves no red check and no report to notice.
1168
+
980
1169
  No version inputs there at all: left out, the four gates run at the versions
981
1170
  this tag ships, which is the intended default. The fully spelled-out example
982
1171
  below adds explicit version pins and comments explaining each one, for a
@@ -1016,7 +1205,7 @@ jobs:
1016
1205
  # pinned below.
1017
1206
  - run: pnpm install --frozen-lockfile
1018
1207
  - id: conductor
1019
- uses: vaultcompasshq/conductor@v0.5.0
1208
+ uses: vaultcompasshq/conductor@v0.7.0
1020
1209
  with:
1021
1210
  output: conductor.sarif
1022
1211
  # Exact versions, never a range and never "latest". These four
@@ -1027,10 +1216,10 @@ jobs:
1027
1216
  # request of their own. Forward only on a pull request: the action
1028
1217
  # refuses a pin below what its tag ships, and the four lines can be
1029
1218
  # left out entirely to take that tag's own versions.
1030
- conductor-version: 0.5.0
1031
- dep-guard-version: 0.7.0
1219
+ conductor-version: 0.7.0
1220
+ dep-guard-version: 0.9.0
1032
1221
  vault-guard-version: 1.8.0
1033
- intent-guard-version: 1.5.2
1222
+ intent-guard-version: 1.7.0
1034
1223
  - uses: github/codeql-action/upload-sarif@v3
1035
1224
  # Always: the log is most worth having on the run that failed.
1036
1225
  if: always()
@@ -1122,7 +1311,7 @@ jobs:
1122
1311
  node-version: '22.11.0'
1123
1312
  - id: conductor
1124
1313
  timeout-minutes: 5
1125
- uses: vaultcompasshq/conductor@v0.5.0
1314
+ uses: vaultcompasshq/conductor@v0.7.0
1126
1315
  with:
1127
1316
  pr-comment: true
1128
1317
  advisory: true
@@ -1153,6 +1342,58 @@ author nothing they could not already do by editing the workflow to add
1153
1342
  edit, is branch protection requiring review on `.github/workflows`, not
1154
1343
  anything in `action.yml`.
1155
1344
 
1345
+ **A `paths:` filter on this job is a real trade, not a free speedup, and the
1346
+ honest default is to skip it.** The biggest reason is not about coverage, it
1347
+ is about merging at all: `paths:` applies to the workflow's own trigger, and
1348
+ a required check whose workflow a `paths:` filter kept from running is
1349
+ reported as never having run at all, not as passed. That check then sits
1350
+ **pending**, and a pull request cannot merge while a required check is
1351
+ pending, regardless of how trivial the change is. GitHub's own documentation
1352
+ describes exactly this failure mode for a required, `paths:`-filtered
1353
+ workflow, and its usual workaround: a job that always runs, regardless of
1354
+ what changed, and reports success or failure on its own rather than relying
1355
+ on the whole workflow being skipped or not.
1356
+
1357
+ The coverage cost is real too, separately from the merge-blocking one. Every
1358
+ gate in the default policy reads the whole changed set, not a slice of it:
1359
+ gitleaks scans git history, so a secret can land in any file regardless of
1360
+ what kind of pull request carries it; vault-guard's own staged scan is the
1361
+ same, over whatever paths changed; dep-guard and osv-scanner only care about
1362
+ manifests and lockfiles, but they still need to see a pull request touch one
1363
+ to react to it; and intent-guard's drift and budget checks are evaluated
1364
+ against every changed path, not only source. A `paths:` filter keyed on
1365
+ `package.json`, the lockfile, and your source globs is exactly right for
1366
+ dep-guard and osv-scanner and exactly wrong for the two secrets gates: it
1367
+ makes a docs-only pull request skip the whole job, gitleaks and vault-guard
1368
+ included, which means a secret pasted into a docs-only change, a comment, or
1369
+ a config file the filter did not list is never scanned at all. That is the
1370
+ cost, plainly: fewer runs bought by turning off secrets scanning on the pull
1371
+ requests the filter excludes.
1372
+
1373
+ If your workflow already has its own required security job and you only
1374
+ want this one to skip clean docs-only changes, add GitHub's own `paths:`
1375
+ (or `paths-ignore:`) to the `on: pull_request` block, the same syntax GitHub
1376
+ documents for any workflow trigger, and account for both traps above before
1377
+ you make the job required: the pull requests it would leave permanently
1378
+ pending, and the coverage this recipe would then lose on exactly the pull
1379
+ requests it skips. The alternative this README recommends is to leave
1380
+ the job triggering on every pull request: a run with nothing to report is
1381
+ not a run worth avoiding, and this recipe has no documented time budget to
1382
+ promise you here, because that number depends on your repository's size and
1383
+ the gates you enable, not on anything conductor fixes. Measure it once on
1384
+ your own repository if you need a number to plan around.
1385
+
1386
+ **Renaming the job changes what branch protection is watching for.** GitHub
1387
+ matches a required check by its context, which is the JOB's name (`gates`
1388
+ here), never the workflow's name (`guardrails-advisory`). If you split this
1389
+ into a paths-filtered job with a different name, or rename the job for any
1390
+ other reason, a pull request that no longer produces the old context name
1391
+ will sit waiting on a check that will never report, until you also update
1392
+ the required-checks list in
1393
+ the branch protection ruleset to match. That edit lives on the repository's
1394
+ settings, not in the workflow file, so it is easy to make the workflow
1395
+ change and forget the other half.
1396
+
1156
1397
  ### Adopting conductor
1157
1398
 
1158
1399
  See "Adopting conductor" near the top of this README for the ordered
@@ -1168,6 +1409,15 @@ for `advisory` to act on. Leaving the check out of branch protection for
1168
1409
  that one pull request is what keeps the expected exit 2 from blocking the
1169
1410
  merge; the step posts a comment naming the ref and the remedy.
1170
1411
 
1412
+ The same refusal happens once on every new base branch, not only on the
1413
+ default branch, because rules are read from whatever branch the pull request
1414
+ targets. A release or release-candidate branch cut before the policy existed,
1415
+ or any long-lived branch that has never received `.guardrails.yaml`, refuses
1416
+ its first pull request the same way. There are two remedies. Carry the policy
1417
+ onto the branch before opening a pull request against it; a sync from the
1418
+ default branch does this. Or expect exactly one could-not-run run there, and
1419
+ leave the check out of that branch's protection for that one pull request.
1420
+
1171
1421
  **Why "go required" means the job's own context, never the SARIF-upload
1172
1422
  row.** The recipes above upload conductor's SARIF log with
1173
1423
  `github/codeql-action/upload-sarif`, which can add its own code-scanning
@@ -1194,7 +1444,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1194
1444
  steps:
1195
1445
  # ... checkout, pnpm, setup-node, install, as in the example above ...
1196
1446
  - id: conductor
1197
- uses: vaultcompasshq/conductor@v0.5.0
1447
+ uses: vaultcompasshq/conductor@v0.7.0
1198
1448
  with:
1199
1449
  output: conductor.sarif
1200
1450
  pr-comment: true
@@ -1202,13 +1452,21 @@ step and add `pull-requests: write` to the job's `permissions`:
1202
1452
 
1203
1453
  That posts conductor's own text report, the one the README quotes above
1204
1454
  ("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
1205
- the pull request. It is **sticky**: a hidden marker in the comment body lets
1455
+ the pull request. It is **the report of the run that decided the job**: the
1456
+ gates step asks that one run for the SARIF log and the text report together
1457
+ (`--text-report`), and the comment step posts the file it wrote without
1458
+ running the gates again. Before this the comment came from a second run, which
1459
+ could disagree with the first whenever a gate's answer was time or network
1460
+ dependent, and doubled the gate time on every pull request. An installed
1461
+ `conductor-version` too old to have `--text-report` is detected by asking the
1462
+ binary, and gets the second-run behaviour it always had, without a token. It is **sticky**: a hidden marker in the comment body lets
1206
1463
  a re-run find and update that same comment, so a push does not pile up a new
1207
1464
  comment every time, the way the manual recipe below does. It runs on a
1208
1465
  `pull_request` or `pull_request_target` event only, and it runs whether the
1209
1466
  gates step passed or failed, since a blocking run is the one an advisory
1210
1467
  check most needs a developer to actually see. The first line of every
1211
- comment carries the version of conductor that produced it, and when the
1468
+ comment carries the version of conductor that produced it, the second line
1469
+ carries the verdict token (see "The verdict token" above), and when the
1212
1470
  trust base was refused and no gate ran at all, the comment shrinks to the
1213
1471
  version, the verdict, and the refusal reason (with its remedy, when one
1214
1472
  applies) rather than the full per-gate report, so an adopter with no policy
@@ -1227,6 +1485,18 @@ add; nothing here does that for you.
1227
1485
 
1228
1486
  Off by default, so an existing consumer of this action is unaffected.
1229
1487
 
1488
+ **The verdict, whether or not the comment is on.** The gates step reads the
1489
+ token out of the text report its own run wrote and publishes it twice: as a
1490
+ line on the job summary, `conductor verdict: advisory-blocked (1)`, and as the
1491
+ Action's `verdict` output, spelled exactly as the report's second line spells
1492
+ it (`steps.conductor.outputs.verdict`). It is flattened to one line before it
1493
+ goes to either. It is a label for conductor's own exit decision, and the
1494
+ step's exit status is conductor's own in every state. When the gate packages
1495
+ could not be verified and no gate ran, the summary says
1496
+ `conductor verdict: could-not-run (<reason>)` and the output is
1497
+ `could-not-run`. The output is empty when the installed `conductor-version`
1498
+ predates the token.
1499
+
1230
1500
  **The sticky match only ever adopts conductor's own comment.** On
1231
1501
  `pull_request_target` this step runs with a write token even though the
1232
1502
  pull request itself is untrusted, so anyone who can comment on the pull
@@ -1246,12 +1516,12 @@ per pull request.
1246
1516
 
1247
1517
  ```yaml
1248
1518
  - id: conductor-package-a
1249
- uses: vaultcompasshq/conductor@v0.5.0
1519
+ uses: vaultcompasshq/conductor@v0.7.0
1250
1520
  with:
1251
1521
  pr-comment: true
1252
1522
  pr-comment-marker: 'package-a'
1253
1523
  - id: conductor-package-b
1254
- uses: vaultcompasshq/conductor@v0.5.0
1524
+ uses: vaultcompasshq/conductor@v0.7.0
1255
1525
  with:
1256
1526
  pr-comment: true
1257
1527
  pr-comment-marker: 'package-b'
@@ -1282,9 +1552,12 @@ case, `pr-comment: true` is the built-in answer.
1282
1552
  The SARIF upload produces no alerts on a private repository without GitHub
1283
1553
  Code Security, which is why that step carries `continue-on-error`. A comment
1284
1554
  is free there. Add `pull-requests: write` to the job's `permissions` and this
1285
- step after the gates. It **runs the gates a second time**, because the Action
1286
- writes SARIF and nothing else, so the job costs roughly twice the gate time;
1287
- `--verbose` because a clean run otherwise collapses to one line.
1555
+ step after the gates. It **runs the gates a second time**, because a run has
1556
+ one format and the recipe below asks for text, so the job costs roughly twice
1557
+ the gate time and the comment can in principle disagree with the first run;
1558
+ the built-in `pr-comment: true` does not, since it posts the file the first
1559
+ run wrote (`--text-report`). `--verbose` because a clean run otherwise
1560
+ collapses to one line.
1288
1561
 
1289
1562
  ```yaml
1290
1563
  - name: Comment the report on the pull request