actions-warden 0.4.0 → 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.
Files changed (76) hide show
  1. package/AGENTS.md +46 -8
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +171 -61
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +15 -5
  6. package/docs/AI-AGENTS.md +109 -29
  7. package/docs/CLI.md +284 -60
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +97 -24
  10. package/docs/GITHUB-ACTION.md +157 -27
  11. package/docs/JAVASCRIPT-API.md +172 -8
  12. package/docs/OUTPUTS.md +399 -36
  13. package/docs/README.md +1 -1
  14. package/examples/README.md +21 -0
  15. package/examples/baseline-adoption/README.md +79 -0
  16. package/examples/baseline-adoption/github-actions.yml +56 -0
  17. package/examples/baseline-adoption/policy.yml +7 -0
  18. package/examples/ci-violation-reporting/README.md +82 -0
  19. package/examples/ci-violation-reporting/github-actions.yml +55 -0
  20. package/examples/ci-violation-reporting/policy.yml +7 -0
  21. package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
  22. package/examples/csv-reporting/README.md +50 -0
  23. package/examples/csv-reporting/github-actions.yml +59 -0
  24. package/examples/html-organization-report/README.md +35 -0
  25. package/examples/html-organization-report/github-actions.yml +61 -0
  26. package/examples/notifications/README.md +67 -0
  27. package/examples/notifications/github-actions.yml +163 -0
  28. package/examples/org-scan.yml +24 -5
  29. package/examples/sarif-code-scanning/README.md +42 -0
  30. package/examples/sarif-code-scanning/github-actions.yml +66 -0
  31. package/examples/upgrade-pr.yml +1 -1
  32. package/llms.txt +14 -5
  33. package/package.json +8 -4
  34. package/skills/actions-warden/SKILL.md +78 -35
  35. package/src/action.js +351 -174
  36. package/src/cli.js +191 -177
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +451 -280
  39. package/src/commands/pin.js +9 -5
  40. package/src/commands/report.js +7 -2
  41. package/src/commands/upgrade.js +9 -5
  42. package/src/commands/verify.js +24 -4
  43. package/src/index.js +5 -1
  44. package/src/lib/action-summary.js +656 -0
  45. package/src/lib/annotations.js +4 -6
  46. package/src/lib/baseline.js +11 -1
  47. package/src/lib/config.js +10 -5
  48. package/src/lib/destination.js +98 -0
  49. package/src/lib/execution.js +5 -1
  50. package/src/lib/formats/csv.js +125 -0
  51. package/src/lib/formats/html.js +394 -0
  52. package/src/lib/formats/json.js +17 -0
  53. package/src/lib/formats/sarif.js +229 -0
  54. package/src/lib/formats/text.js +30 -0
  55. package/src/lib/formats/toon.js +50 -0
  56. package/src/lib/formatter.js +25 -192
  57. package/src/lib/github-org.js +208 -102
  58. package/src/lib/org-artifacts.js +211 -0
  59. package/src/lib/org-checkpoint.js +137 -96
  60. package/src/lib/org-progress.js +182 -4
  61. package/src/lib/org-report-comparison.js +505 -0
  62. package/src/lib/org-report-directory.js +251 -0
  63. package/src/lib/org-report.js +223 -0
  64. package/src/lib/org-run.js +305 -0
  65. package/src/lib/org-schema.js +89 -0
  66. package/src/lib/org-source-links.js +39 -0
  67. package/src/lib/parser.js +5 -0
  68. package/src/lib/paths.js +18 -1
  69. package/src/lib/redact.js +58 -7
  70. package/src/lib/resolver.js +66 -9
  71. package/src/lib/types.js +137 -0
  72. package/src/rules/pull-request-target-checkout.js +5 -0
  73. package/src/rules/unpinned-action.js +2 -3
  74. package/src/rules/workflow-structure.js +2 -4
  75. package/src/version.js +1 -1
  76. package/src/lib/agent-mode.js +0 -174
package/docs/CLI.md CHANGED
@@ -21,7 +21,7 @@ actions-warden --version
21
21
  For reproducible one-off automation, invoke an exact package version:
22
22
 
23
23
  ```sh
24
- npx --yes actions-warden@0.4.0 audit
24
+ npx --yes actions-warden@0.6.0 audit
25
25
  ```
26
26
 
27
27
  Network-backed commands resolve credentials in this order:
@@ -35,6 +35,36 @@ Prefer an environment variable over `--token` because command-line arguments
35
35
  may be visible to other local processes. Give the token only the repository
36
36
  metadata and contents read access needed for the requested scope.
37
37
 
38
+ ## Quick cheat sheet
39
+
40
+ Here is a quick summary of the most common commands you will use daily:
41
+
42
+ ```sh
43
+ # 1. Audit your workflows for security vulnerabilities with clear explanations
44
+ actions-warden audit --explain
45
+
46
+ # 2. Preview the pin plan (safe dry-run; no files are modified)
47
+ actions-warden pin
48
+
49
+ # 3. Apply the reviewed pin plan to your workflow files
50
+ actions-warden pin --write
51
+
52
+ # 4. Verify that pinned commit SHAs match their GitHub repositories
53
+ actions-warden verify
54
+
55
+ # 5. Check if newer versions of your pinned actions are available
56
+ actions-warden upgrade
57
+
58
+ # 6. Apply available upgrades to your files
59
+ actions-warden upgrade --write
60
+
61
+ # 7. Scan an entire GitHub organization
62
+ actions-warden org-scan my-org --severity=high
63
+
64
+ # 8. Export an interactive HTML report to view in your browser
65
+ actions-warden audit --format=html --output-path=audit-report.html
66
+ ```
67
+
38
68
  ## Target and output options
39
69
 
40
70
  The repository commands (`audit`, `pin`, `verify`, `upgrade`, and `report`)
@@ -44,7 +74,7 @@ share these target and output options:
44
74
  |---|---|---|
45
75
  | `-w, --workflow <pattern...>` | discovery | One or more files, directories, or globs |
46
76
  | `--cwd <dir>` | current directory | Repository and path-safety root |
47
- | `--format <format>` | `toon` | `toon`, `json`, `text`, or `sarif` |
77
+ | `--format <format>` | `toon` | `toon`, `json`, `text`, `csv`, `sarif`, or `html` |
48
78
  | `--output <destination>` | `stdout` | `stdout` or `file` |
49
79
  | `--output-path <path>` | none | Report path inside `--cwd`; implies `--output=file` |
50
80
 
@@ -94,10 +124,35 @@ actions-warden audit \
94
124
  `--output=file --output-path=...` remains valid when an explicit destination
95
125
  is clearer in automation.
96
126
 
127
+ HTML is intended as a saved human-review artifact:
128
+
129
+ ```sh
130
+ actions-warden audit \
131
+ --format=html \
132
+ --output-path=reports/actions-warden.html
133
+ ```
134
+
135
+ It is self-contained and does not load external assets. The report is
136
+ credential-redacted, HTML-escaped, protected by a restrictive content security
137
+ policy, deterministic for unchanged inputs, and capped at 32 MiB.
138
+
139
+ CSV can stream to stdout or be written as a guarded file:
140
+
141
+ ```sh
142
+ actions-warden audit \
143
+ --format=csv \
144
+ --output-path=reports/actions-warden.csv
145
+ ```
146
+
147
+ CSV provides a flat spreadsheet/export view. Use JSON for the versioned,
148
+ lossless machine contract and for future organization comparisons.
149
+
97
150
  ## `audit`
98
151
 
99
- Scan local workflows and composite actions without making network calls or
100
- changing workflows. It writes only an explicitly requested report or baseline.
152
+ The `audit` command is completely local and offline. It inspects your workflow
153
+ files and composite actions for vulnerabilities, excessive permissions, script
154
+ injections, and unpinned dependencies without executing any workflows or making
155
+ network requests. It writes only an explicitly requested report or baseline.
101
156
 
102
157
  ```sh
103
158
  actions-warden audit \
@@ -109,9 +164,9 @@ actions-warden audit \
109
164
 
110
165
  The default includes every severity. `--severity` keeps findings at or above
111
166
  the selected threshold; parse errors always remain visible. `--explain` adds a
112
- plain-language remediation field.
167
+ plain-language remediation explanation to each finding.
113
168
 
114
- Create a reviewed baseline from all current findings:
169
+ Create a reviewed baseline from all current findings (useful when adopting on existing projects):
115
170
 
116
171
  ```sh
117
172
  actions-warden audit \
@@ -123,18 +178,25 @@ report output path, and is validated before the audit begins. Parser failures
123
178
  are never written into the baseline. See
124
179
  [configuration and baselines](./CONFIGURATION.md).
125
180
 
126
- Exit code `0` means no unsuppressed findings; `1` means findings were reported;
127
- `2` means the scan could not be invoked safely or correctly.
181
+ > [!TIP]
182
+ > **Understanding exit codes:**
183
+ > - `0`: Clean! No unsuppressed security findings were found.
184
+ > - `1`: Findings reported. This is the normal exit code when issues are detected, allowing CI pipelines to catch vulnerabilities.
185
+ > - `2`: Invocation error. Occurs when command-line flags are invalid, contradictory, or missing required values.
128
186
 
129
187
  ## `pin`
130
188
 
131
- Resolve mutable external action and reusable-workflow refs to full commit SHAs.
189
+ The `pin` command protects your workflows against supply-chain attacks. It
190
+ resolves mutable version tags (such as `@v4` or `@main`) into immutable
191
+ 40-character commit SHAs from GitHub, while preserving the human-readable version
192
+ as an inline comment.
132
193
 
133
194
  ```sh
134
195
  actions-warden pin [--dry-run] [--write] [--fix=<id>]
135
196
  ```
136
197
 
137
- Dry-run is the default. A planned rewrite looks like:
198
+ **Dry-run is the default.** Running `actions-warden pin` will only show you a
199
+ safe preview on your terminal without touching any files. A planned rewrite looks like:
138
200
 
139
201
  ```yaml
140
202
  - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5
@@ -144,13 +206,13 @@ The metadata preserves the readable version for `verify` and `upgrade`.
144
206
  Existing comments and scalar quoting are preserved. The target commit is
145
207
  verified as belonging to the referenced repository before a plan is accepted.
146
208
 
147
- Review the dry-run output, then either apply the whole plan:
209
+ Review the dry-run output, then apply the whole plan to your files:
148
210
 
149
211
  ```sh
150
212
  actions-warden pin --write
151
213
  ```
152
214
 
153
- or one exact stable ID:
215
+ Or apply one exact reviewed action occurrence by its stable ID:
154
216
 
155
217
  ```sh
156
218
  actions-warden pin --fix=18b82e86d7c14fe2 --write
@@ -162,7 +224,8 @@ for convenience.
162
224
 
163
225
  ## `verify`
164
226
 
165
- Verify action and reusable-workflow pins against GitHub.
227
+ The `verify` command checks that all pinned actions in your repository are
228
+ authentic and unmodified.
166
229
 
167
230
  ```sh
168
231
  actions-warden verify
@@ -171,8 +234,8 @@ actions-warden verify
171
234
  For every external reference, verification checks that:
172
235
 
173
236
  1. the ref is a full 40-character commit SHA;
174
- 2. the commit belongs to the referenced repository; and
175
- 3. `actions-warden-ref` metadata, when present, resolves to that SHA.
237
+ 2. the commit truly belongs to the referenced repository on GitHub; and
238
+ 3. `actions-warden-ref` metadata, when present, resolves to that exact SHA.
176
239
 
177
240
  A valid SHA without version metadata produces a warning. An unpinned,
178
241
  unverifiable, or metadata-mismatched reference is an error and returns status
@@ -180,7 +243,10 @@ unverifiable, or metadata-mismatched reference is an error and returns status
180
243
 
181
244
  ## `upgrade`
182
245
 
183
- Plan or apply newer action versions while preserving immutable SHA pins.
246
+ The `upgrade` command checks for newer releases of your pinned actions while
247
+ keeping them securely pinned to commit SHAs. It includes a built-in **cooldown period**
248
+ (default: 7 days) to protect your team against newly published releases that may have
249
+ day-zero issues or compromised tags.
184
250
 
185
251
  ```sh
186
252
  actions-warden upgrade \
@@ -201,7 +267,7 @@ SHA-pinned references need `actions-warden-ref` metadata to establish the
201
267
  current semantic version. Legacy plain-semver comments remain readable.
202
268
 
203
269
  ```sh
204
- # Review every eligible minor update
270
+ # Review every eligible minor update (dry-run preview)
205
271
  actions-warden upgrade --mode=minor --min-age=14 --format=json
206
272
 
207
273
  # Apply one reviewed change
@@ -244,10 +310,13 @@ actions-warden org-scan <organization> \
244
310
  [--max-repos=<count>] [--concurrency=<1-16>] \
245
311
  [--severity=low|medium|high|critical] [--explain] \
246
312
  [--config=<path> | --ignore-config] [--baseline=<path>] \
247
- [--checkpoint=<path> | --resume=<path>] \
248
- [--progress=auto|always|never] \
313
+ [--checkpoint=<path> | --resume=<path>] [--fresh] \
314
+ [--no-auto-checkpoint] \
315
+ [--previous-report=<path>] \
316
+ [--progress=auto|plain|json|none] \
317
+ [--report-dir=<dedicated-directory>] \
249
318
  [--agent-mode | --no-agent-mode] \
250
- [--format=toon|json|text|sarif] \
319
+ [--format=toon|json|text|csv|sarif|html] \
251
320
  [--output=stdout|file] [--output-path=<path>]
252
321
  ```
253
322
 
@@ -258,7 +327,10 @@ Defaults:
258
327
  - repository concurrency: `4`;
259
328
  - repository count: every eligible repository;
260
329
  - audit severity: every level;
261
- - progress: `auto` (stderr only when attached to an interactive terminal);
330
+ - format: `json`;
331
+ - output: a guarded scope-keyed file plus a compact JSON receipt on stdout;
332
+ - checkpoint: a guarded scope-keyed file, automatically resumed when present;
333
+ - progress: `auto` (plain stderr only when attached to an interactive terminal);
262
334
  - agent mode: disabled unless explicitly selected or enabled by the
263
335
  environment.
264
336
 
@@ -268,6 +340,27 @@ Selection is stable before `--max-repos` is applied. `--max-repos` must be a
268
340
  positive safe integer, and `--concurrency` must be an integer from 1 through
269
341
  16; malformed, fractional, or imprecise values fail before any API request.
270
342
 
343
+ The generated paths use these shapes:
344
+
345
+ ```text
346
+ .actions-warden-org-scan.<scope-key>.report.json
347
+ .actions-warden-org-scan.<scope-key>.checkpoint.json
348
+ ```
349
+
350
+ An explicit format changes the report extension while keeping the same
351
+ compatibility key. New files use mode `0600`; both report and checkpoint can
352
+ contain private repository names and security evidence.
353
+
354
+ The key covers scan scope, policy, baseline, rules, and analysis generation.
355
+ Running the same command again selects the same paths and resumes only
356
+ compatible, unchanged, error-free repository results. The report is complete;
357
+ stdout is a bounded `actions-warden-org-scan-receipt` containing status,
358
+ summary, report metadata, exact checkpoint reuse, coverage metadata, and
359
+ optional comparison counts.
360
+ Use `--output=stdout` when the complete selected report is intentionally wanted
361
+ on stdout. Use `--no-auto-checkpoint` for a stateless scan; file output still
362
+ uses a generated report path unless `--output-path` is supplied.
363
+
271
364
  ```sh
272
365
  actions-warden org-scan my-org \
273
366
  --repository 'service-*' 'my-org/platform-*' \
@@ -281,47 +374,140 @@ actions-warden org-scan my-org \
281
374
  The result includes discovered, eligible, selected, scanned, skipped, failed,
282
375
  and workflow-bearing repository counts. Per-repository operational errors make
283
376
  the overall status `FAIL`; they do not abort reporting for repositories that
284
- can still be scanned.
377
+ can still be scanned. The `coverage` object separately states whether every
378
+ eligible repository was covered. A deliberate `--max-repos` cap makes
379
+ `coverage.complete` false without turning an otherwise clean selected scan
380
+ into `FAIL`.
381
+
382
+ ### HTML, CSV, and report comparison
383
+
384
+ Create a self-contained organization dashboard for human review:
385
+
386
+ ```sh
387
+ actions-warden org-scan my-org \
388
+ --severity=high \
389
+ --format=html \
390
+ --output-path=reports/org.html
391
+ ```
392
+
393
+ It includes the requested scope, incomplete-coverage warning, severity and
394
+ rule summary, repository table, searchable/filterable evidence, HTTPS source
395
+ links, comparison sections when present, and operational errors. Treat the
396
+ file as sensitive because it may identify private repositories and findings.
397
+
398
+ Compare a current scan with a previous actions-warden organization JSON report:
399
+
400
+ ```sh
401
+ actions-warden org-scan my-org \
402
+ --severity=high \
403
+ --previous-report=reports/org.previous.json \
404
+ --format=json \
405
+ --output-path=reports/org.current.json
406
+ ```
407
+
408
+ The previous report must be inside `--cwd`, use schema `1.0`, contain a public
409
+ analysis identity, and match the current organization, scope, normalized
410
+ policy, baseline contents, rule catalog, and analysis generation. Reports made
411
+ by an earlier analysis generation, including every report made before commits,
412
+ file inventories, and permalinks were added, must be regenerated once. Token,
413
+ concurrency, progress, and output destination do not affect compatibility.
414
+
415
+ Comparison uses semantic fingerprints and returns complete `new`, `resolved`,
416
+ `unchanged`, and `unknown` finding arrays plus repository and count summaries.
417
+ A previous finding is resolved only when its repository is present and has no
418
+ current API, blob, or workflow-parse coverage error. Missing, failed, or
419
+ unparseable repositories make unmatched prior findings unknown, and
420
+ `summary.complete` becomes `false`. The scan's normal
421
+ status remains based on current findings and errors.
422
+
423
+ `--previous-report` cannot be combined with SARIF because SARIF has no resolved
424
+ or unknown-result contract. Its path must differ from the output and checkpoint
425
+ paths so evidence is never overwritten. Retain JSON when it will be used as a
426
+ future comparison source; HTML is the human view rather than a comparison
427
+ input. CSV is likewise an export view rather than a comparison input.
428
+
429
+ ### Directory JSON reports
430
+
431
+ For a broad report that will be uploaded or inspected repository by
432
+ repository, select a dedicated directory instead of one large JSON file:
433
+
434
+ ```sh
435
+ actions-warden org-scan my-org \
436
+ --severity=high \
437
+ --report-dir=reports/actions-warden-org
438
+ ```
439
+
440
+ `--report-dir` implies JSON file output. It cannot be combined with
441
+ `--output-path`, `--output=stdout`, or a non-JSON format. The directory must be
442
+ inside `--cwd`, cannot be the working directory itself or a workflow discovery
443
+ path, and cannot overlap the active checkpoint, config, baseline, previous
444
+ report, or reserved config paths. Symbolic-link layout components and non-file artifact entries are
445
+ rejected.
446
+
447
+ The layout is:
448
+
449
+ ```text
450
+ reports/actions-warden-org/
451
+ organization-report.json compact aggregate and artifact pointers
452
+ organization-comparison.json complete comparison, when requested
453
+ repositories/
454
+ <repository>.<16-hex-id>.json complete repository evidence
455
+ manifest.json paths, byte counts, and SHA-256 digests
456
+ ```
457
+
458
+ Directories created by the command use mode `0700`; generated files use mode
459
+ `0600`. `manifest.json` is written last and is the authoritative file set for
460
+ the run. Unrelated and stale regular files are not deleted automatically.
461
+ Consumers should verify every listed byte count and digest and reject a
462
+ mismatch, which also detects an interrupted multi-file update.
463
+ Directory output bounds downstream reads and artifact handling, but the
464
+ scanner still constructs the complete result in memory before writing it. A
465
+ directory aggregate is not accepted as `--previous-report`; retain a normal
466
+ complete JSON report when future comparison input is required.
285
467
 
286
468
  ### Agent mode
287
469
 
288
- There is no reliable cross-agent process or environment signal. Agent callers
289
- opt in explicitly:
470
+ There is no reliable universal way to infer that a process is running inside
471
+ an AI agent. Agent callers opt in explicitly:
290
472
 
291
473
  ```sh
292
474
  actions-warden org-scan my-org --agent-mode
293
475
  ```
294
476
 
295
- An integration can instead set the mode once:
477
+ An integration can instead set the preferred execution context once:
296
478
 
297
479
  ```sh
298
- export ACTIONS_WARDEN_MODE=agent
480
+ export ACTIONS_WARDEN_CONTEXT=agent
299
481
  actions-warden org-scan my-org
300
482
  ```
301
483
 
302
- When the corresponding options were not explicitly supplied, agent mode sets:
484
+ `ACTIONS_WARDEN_CONTEXT` accepts `agent`, `auto`, `ci`, or `interactive`.
485
+ With implicit `--progress=auto`, agent context is quiet, CI and interactive
486
+ contexts use plain progress, and auto context follows stderr TTY state.
303
487
 
304
- - `--format=json`;
305
- - `--output=file` with a guarded scope-keyed report path;
306
- - `--progress=never`;
307
- - a guarded scope-keyed checkpoint path, creating it when absent and resuming
308
- it when present.
488
+ The general organization-scan defaults already select JSON file output, a
489
+ scope-keyed checkpoint, compatible automatic resume, and a bounded receipt.
490
+ When progress was not explicitly supplied, agent context selects no progress.
491
+ It also selects `actions-warden-agent-receipt` so integrations can recognize
492
+ the bounded contract. It does not change scan scope, analysis, or artifact
493
+ identity.
309
494
 
310
495
  The artifact key includes the organization, repository filters, inclusion
311
496
  flags, repository limit, severity, explanation setting, normalized policy,
312
497
  baseline contents, analysis generation, and rule catalog. A compatible package
313
498
  upgrade therefore keeps the same paths, while a scope, security-control, or
314
499
  analysis-behavior change selects a different checkpoint rather than
315
- overwriting incompatible state. Generated paths have these shapes:
500
+ overwriting incompatible state. Normal, CI, interactive, and agent contexts
501
+ all use these paths:
316
502
 
317
503
  ```text
318
- .actions-warden-agent.<scope-key>.report.json
319
- .actions-warden-agent.<scope-key>.checkpoint.json
504
+ .actions-warden-org-scan.<scope-key>.report.json
505
+ .actions-warden-org-scan.<scope-key>.checkpoint.json
320
506
  ```
321
507
 
322
508
  An explicitly selected report format changes the report extension. Generated
323
509
  files are mode `0600` when first created and may reveal private security
324
- posture; protect them and ignore `.actions-warden-agent.*` in consuming
510
+ posture; protect them and ignore `.actions-warden-org-scan.*` in consuming
325
511
  repositories when appropriate.
326
512
 
327
513
  After writing the full report, stdout contains only a bounded JSON receipt:
@@ -334,30 +520,63 @@ After writing the full report, stdout contains only a bounded JSON receipt:
334
520
  organization: string,
335
521
  status: 'OK' | 'FAIL',
336
522
  summary: object,
337
- report: { path: string, format: 'toon' | 'json' | 'text' | 'sarif' },
338
- checkpoint: { path: string, resumed: boolean }
523
+ report: {
524
+ path: string,
525
+ format: 'toon' | 'json' | 'text' | 'csv' | 'sarif' | 'html',
526
+ layout: 'single' | 'directory',
527
+ directory?: string,
528
+ manifest?: string
529
+ },
530
+ checkpoint: {
531
+ path: string | null,
532
+ resumed: boolean,
533
+ repositoriesReused: number
534
+ },
535
+ coverage: {
536
+ complete: boolean,
537
+ enumerationComplete: boolean,
538
+ selectedRepositoriesComplete: boolean,
539
+ eligibleRepositoriesComplete: boolean,
540
+ limitedByMaxRepositories: boolean,
541
+ repositoriesOmittedByLimit: number,
542
+ incompleteRepositories: number
543
+ },
544
+ comparison?: object
339
545
  }
340
546
  ```
341
547
 
342
548
  The process still exits `0` for `OK`, `1` for a completed `FAIL`, and `2` for
343
549
  an invocation error. Explicit `--format`, `--output`, `--output-path`,
344
- `--progress`, `--checkpoint`, and `--resume` choices override agent defaults.
550
+ `--report-dir`, `--progress`, `--checkpoint`, `--resume`, `--fresh`, and
551
+ `--no-auto-checkpoint` choices override agent defaults.
345
552
  With explicit `--output=stdout`, stdout is the complete selected report and no
346
553
  receipt is added. Use `--no-agent-mode` to override an inherited environment
347
- marker. Passing both agent-mode flags is rejected. `ACTIONS_WARDEN_MODE` must
348
- be exactly `agent` when set.
554
+ marker. Passing both agent-mode flags is rejected. An explicit agent-mode flag
555
+ has precedence over `ACTIONS_WARDEN_CONTEXT`.
349
556
 
350
557
  ### Progress and resume
351
558
 
352
559
  Progress is independent of the report format and is written only to stderr.
353
- This keeps stdout valid JSON, SARIF, TOON, or text. Select `always` for CI or a
354
- redirected terminal log, and `never` when a caller wants no progress channel:
560
+ This keeps stdout valid JSON, CSV, SARIF, TOON, text, or HTML. Select `plain`
561
+ for human CI or redirected logs, `json` for one parseable event per line, and
562
+ `none` when a caller wants no progress channel:
355
563
 
356
564
  ```sh
357
- actions-warden org-scan my-org --format=json --progress=always > report.json
565
+ actions-warden org-scan my-org \
566
+ --format=json \
567
+ --output=stdout \
568
+ --no-auto-checkpoint \
569
+ --progress=plain > report.json
358
570
  ```
359
571
 
360
- Create an atomic checkpoint after each completed repository:
572
+ JSON Lines events use `schemaVersion: "1.0"`, kind
573
+ `actions-warden-org-scan-progress`, an event name, ISO timestamp, elapsed
574
+ milliseconds, and event-specific bounded fields. A fatal scan error ends that
575
+ channel with `scan-failed`; a post-scan comparison or persistence failure ends
576
+ it with `command-failed`. Neither appends a plain-text error line.
577
+
578
+ Choose stable, caller-managed report and checkpoint names when required by an
579
+ external storage convention:
361
580
 
362
581
  ```sh
363
582
  actions-warden org-scan my-org \
@@ -368,9 +587,9 @@ actions-warden org-scan my-org \
368
587
  --output-path=reports/org.json
369
588
  ```
370
589
 
371
- Resume with the same organization, filters, inclusion flags, repository limit,
372
- severity, explanation setting, configuration, baseline, analysis generation,
373
- and rule catalog:
590
+ The first run creates the checkpoint; repeating that exact command
591
+ automatically resumes it. Use the strict `--resume` form when external
592
+ automation restored a checkpoint that must exist:
374
593
 
375
594
  ```sh
376
595
  actions-warden org-scan my-org \
@@ -383,20 +602,23 @@ actions-warden org-scan my-org \
383
602
 
384
603
  The token, concurrency, output format, progress mode, and report destination do
385
604
  not affect checkpoint compatibility. Neither does a package-version-only
386
- upgrade: the producing version is retained as checkpoint metadata, and a
387
- compatible older checkpoint is rewritten atomically on its first successful
388
- resume. The
605
+ upgrade: the producing version is retained as checkpoint metadata that the next
606
+ checkpoint write refreshes. The
389
607
  explicit analysis generation is advanced when discovery, parsing, finding
390
608
  identity, rule evaluation, or persisted result behavior changes. An
391
- incompatible generation fails closed; automatic agent mode selects a new keyed
392
- path. A resumed scan always lists repositories again and fetches a fresh
393
- default-branch tree for each selected repository. An error-free result is
394
- reused only when repository identity, default branch, and tree SHA still match.
609
+ incompatible generation fails closed; automatic organization scans select a
610
+ new keyed path. A checkpoint from an older schema or generation is rejected.
611
+ A resumed scan always lists repositories again and resolves the current
612
+ default-branch commit and its tree for each selected repository. An error-free
613
+ result is reused only when repository identity, default branch, and tree SHA still match.
395
614
  Changed repositories and any checkpointed result with an operational error are
396
615
  scanned again.
397
616
 
398
- `--checkpoint` starts a new checkpoint and replaces an existing file at that
399
- path. `--resume` requires a valid existing checkpoint and updates it. The
617
+ `--checkpoint` creates a checkpoint when absent and automatically resumes it
618
+ when present. Add `--fresh` to ignore reusable results and atomically replace
619
+ the selected checkpoint. `--resume` requires a valid existing checkpoint and
620
+ cannot be combined with `--fresh`. `--no-auto-checkpoint` disables only the
621
+ generated checkpoint; an explicit `--checkpoint` or `--resume` still applies. The
400
622
  checkpoint and report paths must differ, remain inside `--cwd`, and have an
401
623
  existing parent directory. A checkpoint cannot replace the active config or
402
624
  baseline. Checkpoints contain redacted report evidence and revision metadata,
@@ -404,12 +626,14 @@ not the token or raw YAML, but can still reveal private repository names,
404
626
  paths, findings, and security posture; protect and retain them accordingly.
405
627
  Checkpoint reads and writes are capped at 256 MiB.
406
628
 
407
- Version-only upgrades no longer create extra agent artifacts. When an analysis
408
- generation intentionally changes, the older keyed report and checkpoint are
629
+ Version-only upgrades and context switches do not create extra automatic
630
+ artifacts. When an analysis generation intentionally changes, the older keyed report and checkpoint are
409
631
  retained rather than deleted automatically because they may be needed as audit
410
632
  evidence; remove them according to the consuming repository's retention policy.
411
633
 
412
- The scanner reads the default-branch Git tree and YAML blobs in memory. It
634
+ The scanner resolves the default-branch commit, reads that commit's Git tree,
635
+ and reads YAML blobs in memory, so each repository costs one extra request for
636
+ the commit that permalinks point at. It
413
637
  never clones, checks out, or executes remote content. It fails closed on
414
638
  truncated trees and enforces these bounds per repository:
415
639
 
@@ -259,17 +259,34 @@ Unmatched `ignore-start` directives extend to the end of the file. An
259
259
 
260
260
  ## Baselines
261
261
 
262
- A baseline accepts existing, reviewed findings while allowing new findings to
263
- fail the scan.
264
-
265
- Create one from the current unfiltered finding set:
266
-
267
- ```sh
268
- actions-warden audit \
269
- --create-baseline=.actions-warden-baseline.json
270
- ```
271
-
272
- The command writes a deterministic document:
262
+ A baseline records existing, reviewed findings so that your CI stays green on
263
+ day one, while ensuring that any **new** vulnerabilities fail future pull requests.
264
+
265
+ ### How to adopt on an existing codebase (without breaking CI)
266
+
267
+ When introducing `actions-warden` to an established project, you may encounter
268
+ existing warnings. Rather than blocking your team until every single issue is
269
+ resolved, follow this recommended baseline adoption workflow:
270
+
271
+ 1. **Record current findings in a baseline file:**
272
+ ```sh
273
+ actions-warden audit \
274
+ --create-baseline=.actions-warden-baseline.json
275
+ ```
276
+ 2. **Reference the baseline in `.actions-warden.yml`:**
277
+ ```yaml
278
+ version: 1
279
+ baseline: .actions-warden-baseline.json
280
+ ```
281
+ 3. **Commit both files to your repository.**
282
+ 4. **Enable `actions-warden` in your CI pipeline.**
283
+ All existing issues are now suppressed so builds remain green. However, if any
284
+ pull request introduces a **new** security finding or unpinned action, CI will
285
+ fail immediately—preventing security debt from growing.
286
+ 5. **Gradually fix issues over time:**
287
+ As you pin actions or fix permissions, simply re-generate or update your baseline.
288
+
289
+ The baseline file is saved as a deterministic, human-readable JSON document:
273
290
 
274
291
  ```json
275
292
  {
@@ -314,6 +331,12 @@ reports `totalFindings` and `suppressed`. Parser failures cannot be baselined.
314
331
 
315
332
  Review baseline diffs carefully. Deleting a finding from the baseline makes it
316
333
  active again; adding one accepts that risk without changing the workflow.
334
+ Organization report comparison includes normalized policy and baseline
335
+ contents in its analysis identity. Changing either intentionally requires a
336
+ new comparison starting point instead of presenting policy-driven differences
337
+ as resolved workflow findings.
338
+ The [baseline-adoption example](../examples/baseline-adoption/README.md) shows
339
+ the complete review, artifact, and CI-gating flow.
317
340
 
318
341
  ## Policy ownership
319
342