@vaultcompass/conductor 0.16.0 → 0.18.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
@@ -60,7 +60,7 @@ jobs:
60
60
  gates:
61
61
  runs-on: ubuntu-latest
62
62
  steps:
63
- - uses: actions/checkout@v7
63
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
64
64
  with:
65
65
  fetch-depth: 0
66
66
  - name: Install gitleaks and osv-scanner
@@ -76,8 +76,8 @@ jobs:
76
76
  echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
77
  chmod +x "$bin/osv-scanner"
78
78
  echo "$bin" >> "$GITHUB_PATH"
79
- - uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
80
- - uses: github/codeql-action/upload-sarif@v4
79
+ - uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
80
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
81
81
  if: always()
82
82
  with:
83
83
  sarif_file: conductor.sarif
@@ -151,7 +151,7 @@ required.
151
151
  product: osv-scanner
152
152
  ```
153
153
 
154
- **Globally, and that is the guidance for CI too.** A devDependency is
154
+ **Install globally; that is the guidance for CI too.** A devDependency is
155
155
  fine beside it for your own pre-commit hook, and nothing about a local
156
156
  run changed, but under the Action keep it at the Action's pin or a push
157
157
  run is could-not-run (see "The Action" below). It is not what gates
@@ -229,7 +229,7 @@ required.
229
229
 
230
230
  Your terminal also shows one status line per gate, written to stderr so a
231
231
  CI job log has a per-gate record even when the report goes to a file,
232
- such as `conductor: gate dependencies (dep-guard 0.18.0): ok, exit 0` or
232
+ such as `conductor: gate dependencies (dep-guard 0.18.2): ok, exit 0` or
233
233
  a `skipped (deferred to stage ci)` line for a deferred gate. They carry
234
234
  nothing the summary does not; to see only the summary, redirect stderr
235
235
  (`conductor run --staged --stage commit 2>/dev/null` in the hook).
@@ -237,15 +237,15 @@ required.
237
237
  A commit with a staged credential in it prints the full report and exits 1:
238
238
 
239
239
  ```
240
- conductor 0.16.0
240
+ conductor 0.18.0
241
241
  verdict-token: blocked (1)
242
242
  conductor run: 2 gate(s), 1 finding(s)
243
243
 
244
- dependencies dep-guard 0.18.0 exit 0 153ms via dep-guard on path
244
+ dependencies dep-guard 0.18.2 exit 0 153ms via dep-guard on path
245
245
  threshold medium suppressed 0 ignored 0
246
246
  mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
247
247
 
248
- secrets vault-guard 1.13.0 exit 1 105ms via vault-guard on path
248
+ secrets vault-guard 1.13.1 exit 1 105ms via vault-guard on path
249
249
  BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
250
250
  Possible secret of type 'anthropic'
251
251
  threshold medium suppressed 0 ignored not reported
@@ -287,8 +287,8 @@ required.
287
287
 
288
288
  2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
289
289
  and the workflow together, with `advisory: true` and `pr-comment: true`
290
- on the conductor step -- the recipe under "Running the gates as an
291
- advisory check" below is a complete copy-paste job -- and leave the check
290
+ on the conductor step (the recipe under "Running the gates as an
291
+ advisory check" below is a complete copy-paste job), and leave the check
292
292
  out of branch protection for this one pull request. The step still exits
293
293
  2 on this pull request even with `advisory: true`: the base branch has no
294
294
  policy yet, so the run has no rules, and `advisory` never touches that
@@ -305,7 +305,7 @@ required.
305
305
 
306
306
  4. **Go required.** Once a few ordinary pull requests have shown the report
307
307
  reads the way you expect, remove `advisory: true` from the conductor step
308
- and require the job's own check context in branch protection -- `gates`
308
+ and require the job's own check context in branch protection: `gates`
309
309
  in the recipes below, the job name, never the context the SARIF-upload
310
310
  step reports under. That is the whole of turning this from an advisory
311
311
  job into the one required check.
@@ -382,8 +382,11 @@ it is what makes a team switch a hook off.
382
382
  It is not a sixth gate. It finds no bugs of its own and scans nothing.
383
383
  Every finding about your code came from one of the five gates and is
384
384
  labelled with which one. The only findings it adds are about the gates
385
- themselves, and they are labelled `conductor`: a gate that is switched on
386
- and could not run, and a gate whose output it could not read. Those exist
385
+ themselves, and they are labelled `conductor`. Three can fail a run; the rest
386
+ are non-blocking notes, all listed under "What is in and what is out" below.
387
+ The main ones are a gate that is switched on and could not run, and a gate
388
+ whose output it could not read.
389
+ Those exist
387
390
  because a report that reads clean when nothing looked is the failure this
388
391
  whole family exists to prevent.
389
392
 
@@ -505,7 +508,14 @@ its configuration from the base branch and the pull request cannot change the
505
508
  rules it is judged by; a change to the rules shows as a proposal line and
506
509
  takes effect after merge. See
507
510
  [The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
508
- other event it passes nothing and behaviour is unchanged. The `trust-base`
511
+ other event it passes nothing and behaviour is unchanged. One shape passes a
512
+ different commit: when the base branch has moved to a commit with the exact
513
+ tree of the run's merge ref, as when a pull request lands while its job is
514
+ queued, that commit cannot judge the run, so the step moves the private ref to
515
+ the commit the merge ref was built from and prints a notice naming both. That
516
+ needs a full clone (`fetch-depth: 0`) and every control file listed in
517
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md) the same
518
+ at both commits; otherwise the run stays could-not-run, exit 2. The `trust-base`
509
519
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
510
520
  set. **On a `pull_request` or `pull_request_target` event this input is
511
521
  refused outright, in the validate step** (issue #58). On `pull_request` the
@@ -532,8 +542,8 @@ request being judged, and the version-pin protection described above
532
542
  "protects nothing" against a tree that controls its own judge (the
533
543
  validate step's own comment in `action.yml` says so in those words). A tag
534
544
  moves when someone pushes it. Name this action by owner and the full commit
535
- SHA instead. The recipes in this README name v0.15.0 that way, as
536
- `vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0`.
545
+ SHA instead. The recipes in this README name v0.17.0 that way, as
546
+ `vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0`.
537
547
 
538
548
  ```yaml
539
549
  name: guardrails
@@ -546,7 +556,7 @@ jobs:
546
556
  contents: read
547
557
  security-events: write
548
558
  steps:
549
- - uses: actions/checkout@v7
559
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
550
560
  with:
551
561
  # From 0.8.0 a shallow checkout on a pull-request run is
552
562
  # could-not-run for the history gate.
@@ -555,10 +565,10 @@ jobs:
555
565
  with:
556
566
  node-version: '22.23.4'
557
567
  - id: conductor
558
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
568
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
559
569
  with:
560
570
  output: conductor.sarif
561
- - uses: github/codeql-action/upload-sarif@v3
571
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
562
572
  if: always()
563
573
  continue-on-error: true
564
574
  with:
@@ -599,8 +609,8 @@ refuses a pin below them, and that bump's own pull request goes red with
599
609
  nothing wrong in it. The fix is in the same pull request: raise each pinned
600
610
  line to the new tag's default (the CHANGELOG entry for the tag lists them,
601
611
  and so does the table in [Upgrading](docs/upgrading.md)), or delete it. The
602
- spelled-out example below names them when a workflow wants that
603
- transparency, and carries that cost.
612
+ example below leaves them out for that reason; add an exact forward pin when
613
+ a workflow needs one, and accept that it then has to be raised by hand.
604
614
 
605
615
  **The gates the Action installs are as new as the tag** (issue 146). A
606
616
  tag's defaults can reach npm the same day the tag does, so they can be
@@ -625,7 +635,7 @@ jobs:
625
635
  contents: read
626
636
  security-events: write
627
637
  steps:
628
- - uses: actions/checkout@v7
638
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
629
639
  with:
630
640
  # Required. From 0.8.0 a shallow checkout on a pull-request run is
631
641
  # could-not-run for the history gate. Without a full history there
@@ -654,21 +664,18 @@ jobs:
654
664
  # installs those itself, globally. Leave conductor-version unset so the
655
665
  # umbrella is the default in the pinned action.yml.
656
666
  - id: conductor
657
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
667
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
658
668
  with:
659
669
  output: conductor.sarif
660
- # Exact versions, never a range and never "latest". These three
661
- # lines decide which gate programs judge a pull request, so a pull
662
- # request's own lockfile no longer does. They are only as protected
663
- # as this file is: require review on .github/workflows in your
664
- # branch protection. Bump them like any other pin, in a pull
665
- # request of their own. On a pull request the action refuses a pin
666
- # below what the pinned action.yml ships, and the three lines can
667
- # be left out entirely to take that action's own versions.
668
- dep-guard-version: 0.18.0
669
- vault-guard-version: 1.13.0
670
- intent-guard-version: 1.10.3
671
- - uses: github/codeql-action/upload-sarif@v3
670
+ # The gate versions are left out on purpose: the defaults travel
671
+ # with the tag above, so a bump of that line moves the gates with it.
672
+ # To pin a gate forward, add an exact version such as
673
+ # `dep-guard-version: x.y.z`, never a range and never "latest". A
674
+ # pin decides which gate program judges a pull request, so it is
675
+ # only as protected as this file is: require review on
676
+ # .github/workflows in your branch protection. On a pull request the
677
+ # action refuses a pin below what the pinned action.yml ships.
678
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
672
679
  # Always: the log is most worth having on the run that failed.
673
680
  if: always()
674
681
  # The sarif path is published BEFORE the gates run, so on the exit 2
@@ -687,7 +694,7 @@ jobs:
687
694
  build:
688
695
  runs-on: ubuntu-latest
689
696
  steps:
690
- - uses: actions/checkout@v7
697
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
691
698
  - uses: pnpm/action-setup@v4
692
699
  - uses: actions/setup-node@v7
693
700
  with:
@@ -710,8 +717,12 @@ keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
710
717
  (`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
711
718
  `.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
712
719
  credential helpers, `core.sshCommand`), git hooks such as
713
- `reference-transaction`, and replace refs or grafts. Say it plainly:
714
- package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
720
+ `reference-transaction`, and replace refs or grafts. (The action's fetch, gates
721
+ and fallback render steps set `GIT_NO_REPLACE_OBJECTS=1` for themselves and
722
+ for the gates they run, which narrows replace refs. The fetch step alone also
723
+ reads through a graft file, for its decision to move the trust base; the gates
724
+ and the CLI still see one.)
725
+ Say it plainly: package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
715
726
  `prepare`) run by an install bypass "require review on `.github/workflows`",
716
727
  because the pull request supplies them, not the workflow file. Branch
717
728
  protection on the workflow directory does not stop them, so the gates must
@@ -862,7 +873,7 @@ jobs:
862
873
  contents: read
863
874
  pull-requests: write
864
875
  steps:
865
- - uses: actions/checkout@v7
876
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
866
877
  with:
867
878
  # From 0.8.0 a shallow checkout on a pull-request run is
868
879
  # could-not-run for the history gate.
@@ -876,7 +887,7 @@ jobs:
876
887
  # seconds) plus 300 seconds for the preview, rounded up. A step
877
888
  # timeout below that can kill a full gitleaks scan and leave no verdict.
878
889
  timeout-minutes: 30
879
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
890
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
880
891
  with:
881
892
  pr-comment: true
882
893
  advisory: true
@@ -1012,7 +1023,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1012
1023
  # the pull request runs before the action in this job: no install, build
1013
1024
  # or test step here; those belong in a separate job. ...
1014
1025
  - id: conductor
1015
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1026
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
1016
1027
  with:
1017
1028
  output: conductor.sarif
1018
1029
  pr-comment: true
@@ -1091,12 +1102,12 @@ per pull request.
1091
1102
 
1092
1103
  ```yaml
1093
1104
  - id: conductor-package-a
1094
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1105
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
1095
1106
  with:
1096
1107
  pr-comment: true
1097
1108
  pr-comment-marker: 'package-a'
1098
1109
  - id: conductor-package-b
1099
- uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
1110
+ uses: vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
1100
1111
  with:
1101
1112
  pr-comment: true
1102
1113
  pr-comment-marker: 'package-b'
@@ -1214,12 +1225,14 @@ binary (the adopter installs gitleaks and osv-scanner), and any finding of
1214
1225
  the umbrella's own about
1215
1226
  anybody's CODE. The findings it does raise are all about the gates
1216
1227
  themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
1217
- and `conductor/gate-failed`, plus the two diagnostics
1218
- `conductor/blocking-count-mismatch` and
1219
- `conductor/blocking-threshold-unknown`.
1228
+ and `conductor/gate-failed`, which count toward the exit code, and diagnostics
1229
+ that never do: `conductor/blocking-count-mismatch` and
1230
+ `conductor/blocking-threshold-unknown`, plus the `conductor/` notes on what the
1231
+ vulnerabilities gate was handed and how it was run, such as
1232
+ `conductor/lockfiles-empty`.
1220
1233
 
1221
1234
  Also out: intent at the cohesion level, which is what a merge or a
1222
- promotion would want and which the audits do by hand today; and anything that
1235
+ promotion would want; and anything that
1223
1236
  runs inside an agent session or on save, which intent-guard's own optional
1224
1237
  session hooks already cover.
1225
1238
 
package/dist/cli.js CHANGED
@@ -18,7 +18,7 @@ import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, renderT
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
19
  import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
20
20
  import { refusedTrustBase, runAll } from './run.js';
21
- import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
21
+ import { headTreeEqualsBase, withMovedBaseTip, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
22
22
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
23
23
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
24
24
  /**
@@ -631,10 +631,10 @@ export function buildProgram() {
631
631
  .option('--preview', 'pull-request mode only: when the pull request changes a gate\'s enabled or stage, run those gates once more under the proposed values, as a preview that never changes the exit code or the verdict. Every other policy key still comes from the base ref, and so do the gitleaks and osv-scanner configs; dep-guard and vault-guard read their own config files from the head. Not on --staged.')
632
632
  .option('--format <format>', 'output format: text or sarif')
633
633
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
634
- .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
635
- .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
634
+ .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base the action resolved (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
635
+ .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event, or the commit the merge ref was built from when the fetched tip has the merge ref\'s exact tree.')
636
636
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
637
- .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, or had no contract), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
637
+ .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, had no contract, or was handed an empty change set), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
638
638
  .option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention. On a pull-request run (--trust-base) the spec is read from the base ref, and a frozen contract on the base takes precedence over it')
639
639
  .option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
640
640
  .option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
@@ -697,7 +697,7 @@ export function buildProgram() {
697
697
  ...(stage === undefined ? {} : { stage }),
698
698
  ...(options.base === undefined ? {} : { base: options.base }),
699
699
  ...(options.spec === undefined ? {} : { spec: options.spec }),
700
- ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
700
+ ...(source.trustBase === undefined ? {} : { trustBase: withMovedBaseTip(root, source.trustBase, process.env.CONDUCTOR_BASE_TIP) }),
701
701
  // Only on request, never on --staged, and only with a trust
702
702
  // base and a preview policy: a head that parsed and changed
703
703
  // at least one role's enabled or stage.
@@ -351,6 +351,7 @@ export interface GateOutcome {
351
351
  contractSource: ContractSource;
352
352
  baseRef: string | null;
353
353
  note?: string;
354
+ changedPaths?: number;
354
355
  };
355
356
  /**
356
357
  * Present only on a pull-request run. Whether this gate was put into
@@ -31,7 +31,7 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
31
31
  import { osvLockfileKind, profileFor } from './products.js';
32
32
  import { unreadManifestsNote } from './unread-manifests.js';
33
33
  import { escapeNonAscii } from './policy-diff.js';
34
- import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
34
+ import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
35
35
  import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
36
36
  /** The longest excerpt of a gate's own reason that is carried. */
37
37
  export const GATE_SAID_MAX_CHARS = 160;
@@ -675,8 +675,9 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
675
675
  return refusal;
676
676
  }
677
677
  }
678
+ const fromOptions = new Set(binary.optionArgumentPaths ?? []);
678
679
  for (const argument of binary.argumentPaths) {
679
- const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
680
+ const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument, fromOptions.has(argument) ? "the gate's options:" : "the gate's args:");
680
681
  if (refusal !== null) {
681
682
  return refusal;
682
683
  }
@@ -770,7 +771,7 @@ changeBase,
770
771
  * after its enables, so the appended flag wins.
771
772
  */
772
773
  preview = false) {
773
- const passthrough = renderOptionFlags(gate.options);
774
+ const passthrough = renderOptionFlags(gate.options, gate.product);
774
775
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
775
776
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
776
777
  switch (gate.product) {
@@ -946,7 +947,7 @@ preview = false) {
946
947
  ...lockfiles,
947
948
  ...(noResolve ? ['--no-resolve'] : []),
948
949
  ...callAnalysis,
949
- ...renderOptionFlags(options),
950
+ ...renderOptionFlags(options, gate.product),
950
951
  ...(preview ? ['--no-call-analysis=all'] : []),
951
952
  ];
952
953
  }
@@ -1216,7 +1217,7 @@ export function runGate(gate, options) {
1216
1217
  intent: {
1217
1218
  contractSource: options.intent.contractSource,
1218
1219
  baseRef: options.intent.baseRef,
1219
- ...(options.intent.note === undefined ? {} : { note: options.intent.note }),
1220
+ ...(options.intent.note === undefined ? {} : { note: options.intent.note }), ...(options.intent.paths === null ? {} : { changedPaths: options.intent.paths.length }),
1220
1221
  },
1221
1222
  }
1222
1223
  : options.intentContract === undefined
@@ -1304,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
1304
1305
  detail: "the preview does not run call analysis, because it would build the head's code",
1305
1306
  };
1306
1307
  }
1307
- if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
1308
+ // Inside by its real path OR as written: a directory on the written path
1309
+ // that is a link out of the tree is the head's choice too (audit
1310
+ // 2026-11-01, MB2), and the primary rule judges every path as written.
1311
+ if (gate.command !== undefined &&
1312
+ (realPathInside(repoRoot, gate.command) || writtenInsideWorkingTree(repoRoot, gate.command))) {
1308
1313
  return {
1309
1314
  reason: 'gate-program-refused',
1310
1315
  detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
@@ -1327,7 +1332,9 @@ function previewRefusal(gate, repoRoot) {
1327
1332
  // on every preview spawn, an option-value directory included (review B1).
1328
1333
  for (const arg of codeArguments(gate)) {
1329
1334
  const candidates = argumentCandidates(arg, repoRoot);
1330
- if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
1335
+ if (candidates.some((named) => realPathInside(repoRoot, named) ||
1336
+ realPathInside(repoRoot, path.dirname(named)) ||
1337
+ writtenInsideWorkingTree(repoRoot, named))) {
1331
1338
  return {
1332
1339
  reason: 'gate-program-refused',
1333
1340
  detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
@@ -1078,10 +1078,7 @@ function prepareAgainstTrustBase(options, trustBase) {
1078
1078
  proposals.push(`${headSpec} is a spec in this pull request but not on "${trustBase}": it is a proposal, ` +
1079
1079
  'and pull requests are judged against it once it is on the base branch.');
1080
1080
  }
1081
- return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" carries no frozen ` +
1082
- `${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
1083
- `${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
1084
- 'intent contract comes from the base ref only, so nothing in this pull request can ' +
1085
- 'become it; once a contract or spec is on the base branch, the next pull request is ' +
1086
- 'judged against it.', proposals, trustBase);
1081
+ return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" has no frozen contract or spec for ` +
1082
+ `${branch === null ? 'this branch' : `branch "${branch}"`}. See ` +
1083
+ 'https://github.com/vaultcompasshq/conductor/blob/main/docs/intent-at-a-pull-request.md', proposals, trustBase);
1087
1084
  }
package/dist/normalize.js CHANGED
@@ -533,8 +533,15 @@ function readTrustBase(raw, product) {
533
533
  export function normalizeIntentGuard(raw, version) {
534
534
  const product = 'intent-guard';
535
535
  const root = needRecord(raw, product, 'the output');
536
- if (root.status !== 'blocked' && root.status !== 'ok') {
537
- fail(product, 'status', 'either "ok" or "blocked"');
536
+ // "skipped" is accepted ahead of the gate using it (issue 103): intent-guard
537
+ // 1.10.4 says "nothing was checked" as status ok plus skipReason, because
538
+ // anything else would have been unparseable to every conductor up to this
539
+ // one, and a later release can move to a status of its own once its pin
540
+ // floor is above this version. It is the one value added; every other
541
+ // status is still refused, and readSkipReason refuses a skipped status
542
+ // that names no reason or that carries a finding.
543
+ if (root.status !== 'blocked' && root.status !== 'ok' && root.status !== 'skipped') {
544
+ fail(product, 'status', 'one of "ok", "blocked" or "skipped"');
538
545
  }
539
546
  const trustBase = readTrustBase(root.trustBase, product);
540
547
  const warnings = readIntentWarnings(root.warnings);
@@ -678,6 +685,7 @@ export function normalizeIntentGuard(raw, version) {
678
685
  : 'The intent gate blocked without stating a reason.', 'unattributed'));
679
686
  }
680
687
  }
688
+ const skipReason = readSkipReason(root, findings, product);
681
689
  return {
682
690
  findings,
683
691
  ...(trustBase === undefined ? {} : { trustBase }),
@@ -700,11 +708,43 @@ export function normalizeIntentGuard(raw, version) {
700
708
  driftCategories: drift?.categories ?? null,
701
709
  budgetAction: budget?.action ?? null,
702
710
  reasons,
711
+ // Present only when the gate said it checked nothing. The report
712
+ // surfaces read it through intentCheckedNothing in output-text.ts.
713
+ ...(skipReason === null ? {} : { skipReason }),
703
714
  },
704
715
  },
705
716
  diagnostics: [],
706
717
  };
707
718
  }
719
+ /**
720
+ * The gate's own statement that it checked nothing, or null (issue 103).
721
+ *
722
+ * intent-guard 1.10.4 puts a top-level `skipReason` string on a result whose
723
+ * status is still "ok" when require-frozen is off and there is no contract;
724
+ * a future status "skipped" means the same. Read only on those two
725
+ * statuses: a blocked result stays blocked whatever else it says, which is
726
+ * the fail-closed reading of a contradiction. An empty string is no reason.
727
+ *
728
+ * Refused as unparseable, never guessed at: a skipReason that is not a
729
+ * string, a status "skipped" that names no reason, and a skip that carries
730
+ * any finding. "Nothing was checked" beside a finding is a contradiction,
731
+ * and reading it as a skip would hide the finding, so the gate is reported
732
+ * as one whose output could not be read.
733
+ */
734
+ function readSkipReason(root, findings, product) {
735
+ if (root.status === 'blocked') {
736
+ return null;
737
+ }
738
+ const said = optionalString(root.skipReason ?? undefined, product, 'skipReason');
739
+ const reason = said === undefined || said === '' ? null : said;
740
+ if (root.status === 'skipped' && reason === null) {
741
+ fail(product, 'skipReason', 'a non-empty string when status is "skipped"');
742
+ }
743
+ if (reason !== null && findings.length > 0) {
744
+ fail(product, 'findings', 'empty when the gate says it checked nothing (skipReason)');
745
+ }
746
+ return reason;
747
+ }
708
748
  // -- gitleaks (external, git history mode) -------------------------------
709
749
  //
710
750
  // The report is a JSON array written to a file, one entry per leak, with
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
121
121
  import { cleanPreviewLine } from './gate-runner.js';
122
122
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
123
123
  import { INTENT_WARNING } from './normalize.js';
124
- import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
124
+ import { baseMovedSentences, gateOutcomeWords, intentEmptyChangeSet, intentNothingWording, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
125
125
  import { POLICY_FILE_NAME } from './policy.js';
126
126
  import { policyChangeLine } from './policy-diff.js';
127
127
  import { guardPreview } from './run.js';
@@ -426,7 +426,7 @@ fallbackUri, properties, invocation) {
426
426
  * summary or an exit code.
427
427
  */
428
428
  function diagnosticFindings(result) {
429
- return result.gates.flatMap((gate) => gate.diagnostics.map((diagnostic) => ({
429
+ return result.gates.flatMap((gate) => gate.diagnostics.filter((diagnostic) => diagnostic.code !== NOTHING_TO_SCAN).map((diagnostic) => ({
430
430
  schemaVersion: 1,
431
431
  product: UMBRELLA_DRIVER_NAME,
432
432
  productVersion: null,
@@ -587,6 +587,27 @@ function treeUnchangedNotifications(result) {
587
587
  * keep answering it the same way.
588
588
  */
589
589
  function skippedNotifications(result) {
590
+ return [...preparedSkipNotifications(result), ...ranAndCheckedNothingNotifications(result)];
591
+ }
592
+ /**
593
+ * An intent gate that RAN and checked nothing (issue 103): intent-guard
594
+ * 1.10.4's skipReason on a directly spawned run, or, before it, no contract
595
+ * found with require-frozen off. Filed under the same id as the
596
+ * pull-request path's no-contract skip, with the same message shape and the
597
+ * gate's own sentence as the detail, because it is the same state and a
598
+ * consumer filtering on intent-guard/no-contract should see both. The same
599
+ * predicate the text report reads (intentCheckedNothing), so the two agree.
600
+ * The gate's own run is still in the log, since it did run.
601
+ */
602
+ function ranAndCheckedNothingNotifications(result) {
603
+ return result.gates.filter(intentCheckedNothing).map((gate) => ({
604
+ id: `${gate.product}/no-contract`,
605
+ message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ` +
606
+ (intentSkipReason(gate) ?? 'It found no contract to check against.'),
607
+ details: { role: gate.role, product: gate.product, reason: 'no-contract' },
608
+ }));
609
+ }
610
+ function preparedSkipNotifications(result) {
590
611
  return result.skipped.map((gate) => ({
591
612
  // The reason IS the second half of the id, which keeps
592
613
  // intent-guard/no-contract exactly where consumers already have it and
@@ -1068,7 +1089,7 @@ export function renderSarif(result, umbrellaVersion) {
1068
1089
  ...deferredNotifications(result),
1069
1090
  ...excludedNotifications(result),
1070
1091
  ...treeUnchangedNotifications(result),
1071
- ...skippedNotifications(result),
1092
+ ...skippedNotifications(result), ...emptyChangeSetNotifications(result), ...nothingToScanNotifications(result), ...baseMovedNotifications(result),
1072
1093
  ...unenforcedNotifications(result),
1073
1094
  ...legacyStateDirNotifications(result),
1074
1095
  ...weakMatchNotifications(result),
@@ -1125,3 +1146,48 @@ export function renderSarif(result, umbrellaVersion) {
1125
1146
  }
1126
1147
  return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
1127
1148
  }
1149
+ /**
1150
+ * The base branch moved past the merge ref, as a notification: what this run
1151
+ * was judged against is a statement about the run. The same sentence as the
1152
+ * text report.
1153
+ */
1154
+ function baseMovedNotifications(result) {
1155
+ return baseMovedSentences(result).map((message) => ({
1156
+ id: 'conductor/base-moved',
1157
+ message,
1158
+ details: { ref: result.trustBase?.ref ?? null, baseTip: result.trustBase?.baseTip ?? null },
1159
+ }));
1160
+ }
1161
+ /**
1162
+ * An intent gate that ran with a contract on no changed paths, as a notification:
1163
+ * how much a run covered, by the rule at skippedNotifications. In the gate's own
1164
+ * namespace, like its no-contract skip, with the words of the verdict sentence. A
1165
+ * gate with no contract is left to that skip, which already says it checked nothing.
1166
+ */
1167
+ function emptyChangeSetNotifications(result) {
1168
+ return result.gates
1169
+ .filter((gate) => intentEmptyChangeSet(gate) && !intentCheckedNothing(gate))
1170
+ .map((gate) => ({
1171
+ id: `${gate.product}/empty-change-set`,
1172
+ message: `${intentNothingWording(gate)}.`,
1173
+ details: { role: gate.role, product: gate.product, reason: 'empty-change-set' },
1174
+ }));
1175
+ }
1176
+ /** The gate diagnostic the log carries as a notification, never a result. */
1177
+ const NOTHING_TO_SCAN = 'conductor/nothing-to-scan';
1178
+ /**
1179
+ * A gate with nothing to scan, as a notification.
1180
+ *
1181
+ * True on every run until somebody adds a lockfile, so by the rule at
1182
+ * skippedNotifications it says how much a run covered and is not a result. The
1183
+ * sentence is the gate's diagnostic, unchanged, which the text report prints too.
1184
+ */
1185
+ function nothingToScanNotifications(result) {
1186
+ return result.gates.flatMap((gate) => gate.diagnostics
1187
+ .filter((diagnostic) => diagnostic.code === NOTHING_TO_SCAN)
1188
+ .map((diagnostic) => ({
1189
+ id: diagnostic.code,
1190
+ message: diagnostic.message,
1191
+ details: { role: gate.role, product: gate.product },
1192
+ })));
1193
+ }
@@ -148,8 +148,8 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
148
148
  * nothing-checked exit 0, but nothing was checked: no gate ran at
149
149
  * all (none enabled, or every one deferred,
150
150
  * tree-unchanged or skipped), or every gate that
151
- * ran checked nothing (nothing to scan, or no
152
- * contract; audit finding F4)
151
+ * ran checked nothing (nothing to scan, no contract,
152
+ * or an empty change set; audit finding F4)
153
153
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
154
154
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
155
155
  * could not run
@@ -177,6 +177,21 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
177
177
  * not a pass.
178
178
  */
179
179
  export declare function verdictToken(result: RunResult, advisory: boolean): string;
180
+ /**
181
+ * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
182
+ * in the run details by normalizeIntentGuard only when non-empty.
183
+ */
184
+ export declare function intentSkipReason(gate: GateOutcome): string | null;
185
+ /**
186
+ * An intent gate that RAN and checked nothing: it said so with skipReason,
187
+ * or (before 1.10.4) it reported no contract found. The one predicate the
188
+ * text report, its one-line summary and the SARIF notification all read, so
189
+ * a directly spawned run reports this state on the same surfaces as the
190
+ * pull-request path's no-contract skip (issue 103). Never for a gate that
191
+ * could not run or that blocked: a missing contract under require-frozen is
192
+ * a block, not a skip.
193
+ */
194
+ export declare function intentCheckedNothing(gate: GateOutcome): boolean;
180
195
  export interface TextOptions {
181
196
  /**
182
197
  * Print the full report even when the run is fully clean.
@@ -252,4 +267,22 @@ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two
252
267
  */
253
268
  export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
254
269
  export declare function renderText(result: RunResult, options?: TextOptions): string;
270
+ /**
271
+ * An intent gate that ran with a contract on a change set of no paths: a branch
272
+ * the base it was measured against already carries, or a net-empty one. The
273
+ * gate says it is clean and it is, about nothing. Never for a gate that could
274
+ * not run or that blocked: every could-not-run outcome carries a blocking finding,
275
+ * so the one clause covers both. It does its work in the SARIF notification, which
276
+ * reads this directly; the text report sorts those gates out before it gets here.
277
+ */
278
+ export declare function intentEmptyChangeSet(gate: GateOutcome): boolean;
279
+ /** How the verdict sentence names an intent gate that ran and checked nothing. */
280
+ export declare function intentNothingWording(gate: GateOutcome): string;
281
+ /**
282
+ * Why the rules commit is not the base branch's tip, on a run the Action moved
283
+ * past it, as a list of one, or of none. Says what happened and never that
284
+ * anything merged: the same shape occurs on an open pull request. The text
285
+ * report and the SARIF log read this one sentence, so they cannot disagree.
286
+ */
287
+ export declare function baseMovedSentences(result: RunResult): string[];
255
288
  export {};