actions-warden 0.3.0 → 0.4.0

package/AGENTS.md

@@ -58,10 +58,11 @@ actions-warden org-scan ORG --agent-mode
   checkpoint. It emits only a bounded JSON receipt to stdout. The packaged
   skill should pass the flag; an integration may instead set
   `ACTIONS_WARDEN_MODE=agent` once.
-- Automatic artifact names are derived from the complete checkpoint identity.
-  An exact-scope later run resumes its checkpoint; a changed filter, severity,
-  policy, baseline, tool version, or rule catalog receives a different path.
-  Compatibility validation still fails closed.
+- Automatic artifact names are derived from the checkpoint compatibility
+  identity. An exact-scope later run resumes its checkpoint across compatible
+  package versions; a changed filter, severity, policy, baseline, analysis
+  generation, or rule catalog receives a different path. Compatibility
+  validation still fails closed.
 - Preserve the scope the user requested. Reducing LLM context use is not
   permission to omit repositories, severities, findings, or errors.
 - Explicit CLI choices override agent defaults. If the user asks to watch live
@@ -112,8 +113,13 @@ deprecating a package. A release request does not authorize those actions.
 ## Non-negotiable invariants
 
 - `pin` and `upgrade` are dry-run by default.
+- CLI usage errors return `2`; numeric limits and change IDs are parsed
+  strictly, and contradictory flags fail before command work begins.
 - Writes remain within the real repository root, reject symlink escapes, are
   atomic, preserve permissions, and reparse modified YAML.
+- CLI report, baseline, and checkpoint destinations are preflighted before
+  network or workflow mutation and cannot replace workflow or policy-control
+  files.
 - GitHub ref resolution and commit ownership fail closed.
 - Credentials are redacted in every format, annotation, and top-level error.
 - Finding IDs are clone-independent; pin findings and plans share an ID.
@@ -123,6 +129,10 @@ deprecating a package. A release request does not authorize those actions.
 - Organization resume requires fresh discovery and matching default-branch tree
   SHAs; never reuse failed results. Checkpoints remain guarded, atomic, and free
   of tokens or raw YAML.
+- `ORGANIZATION_ANALYSIS_GENERATION` is the organization-result compatibility
+  boundary. Increment it whenever discovery, parser, finding identity, rule
+  evaluation, or persisted result semantics can change; do not increment it
+  for a version-only compatible release.
 - CLI progress stays on stderr and never corrupts structured report stdout.
 - Attacker-controlled text cannot forge output records or workflow commands.
 

package/README.md

@@ -57,7 +57,7 @@ actions-warden verify
 For a one-off run without a global install:
 
 ```sh
-npx --yes actions-warden@0.3.0 audit --explain
+npx --yes actions-warden@0.4.0 audit --explain
 ```
 
 `audit` returns exit code `1` when it finds issues. That is a completed scan,
@@ -109,6 +109,12 @@ reused; changed and previously failed repositories are scanned again. Progress
 defaults to interactive terminals; use `--progress=always` for redirected logs
 or `--progress=never` to disable it.
 
+Compatible package upgrades reuse the same checkpoint. The producing package
+version is recorded as metadata, while an explicit analysis generation plus
+the rule catalog controls compatibility. A parser, discovery, or rule behavior
+change advances that generation and requires a fresh scan. Compatible older
+checkpoints are rewritten atomically on their first successful resume.
+
 When a coding agent initiates the scan, use the explicit bounded mode:
 
 ```sh
@@ -150,8 +156,14 @@ audit/report/pin/upgrade plan → review IDs and diffs → --fix=<id> --write
 - `pin` and `upgrade` are dry-runs unless `--write` is present.
 - `--write --dry-run` is rejected instead of guessing intent.
 - `--fix=<id>` limits a pin or upgrade to one exact source occurrence.
+- Numeric limits and change IDs are parsed strictly; partial, fractional, and
+  imprecise values fail before network or write work begins.
 - Rewrites preserve surrounding YAML and are reparsed before an atomic write.
-- Paths, output files, and symlinks are constrained to the selected repository.
+- `--output-path` implies file output; contradictory or incomplete output flags
+  are rejected before a scan or authorized mutation begins.
+- Paths, output files, and symlinks are constrained to the selected repository,
+  and report/baseline/checkpoint destinations cannot replace workflows or
+  policy controls.
 - Credential-like values are recursively redacted from every output format.
 - Repository policy is strictly validated; unknown keys and rule IDs fail.
 - Remote organization source is kept in memory and is not persisted in cache.

package/SECURITY.md

@@ -12,7 +12,7 @@ Please include:
 
 - A clear description of the issue.
 - A minimal reproduction (workflow YAML, command line, expected vs. actual).
-- The version of `actions-warden` (`npx --yes actions-warden@0.3.0 --version`).
+- The version of `actions-warden` (`npx --yes actions-warden@0.4.0 --version`).
 - Any disclosure constraints on your side.
 
 We aim to acknowledge within **3 business days** and to ship a fix or a
@@ -50,16 +50,21 @@ Out of scope:
   install dependencies in consumer workflows.
 - Repository policy and baseline files should be protected with CODEOWNERS or
   branch rules; changes to them can intentionally alter which findings fail CI.
+- CLI report, baseline, and checkpoint destinations are guarded and preflighted;
+  they cannot replace selected/default-discovery workflows or reserved policy
+  paths, and active control-file collisions are rejected before output writes.
 - Parser failures are operational errors and cannot be suppressed by a finding
   baseline.
 - Organization scans read count- and size-bounded Git blobs in memory and never
   clone, check out, or execute code from scanned repositories. Truncated trees,
   exceeded limits, and unreadable blobs are operational errors.
 - Organization checkpoints are opt-in, guarded atomic writes. They omit tokens
-  and raw workflow YAML, validate tool/rule/scope/policy identity, and reuse an
-  error-free result only after a fresh repository/default-branch tree-SHA
-  match. They still contain redacted repository and finding evidence and should
-  be protected like organization reports.
+  and raw workflow YAML, validate analysis-generation/rule/scope/policy
+  identity, and reuse an error-free result only after a fresh
+  repository/default-branch tree-SHA match. The producing package version is
+  metadata rather than a compatibility boundary. They still contain redacted
+  repository and finding evidence and should be protected like organization
+  reports.
 - Explicit CLI agent mode creates scope-keyed report and checkpoint files with
   the same guarded writer and `0600` creation mode. Its stdout receipt contains
   only paths and bounded counts; the artifact files remain sensitive.

package/docs/AI-AGENTS.md

@@ -88,6 +88,15 @@ found something. Parse and present the report.
 
 Exit code `2` is an invocation-level problem. Read stderr, do not assume stdout
 contains valid JSON, and do not retry by weakening policy or changing paths.
+Unknown options, conflicting flags, malformed numeric values, invalid change
+IDs, unsafe destinations, and a missing command all use this exit code. These
+checks happen before network requests or authorized workflow mutations whenever
+the required path information is available.
+
+When saving a report, `--output-path=<path>` is sufficient and implies file
+output. Do not combine it with explicit `--output=stdout`. Create the parent
+directory first, and never select a workflow, policy, baseline, or checkpoint
+path as the report destination.
 
 For an organization scan, report coverage before findings:
 
@@ -260,19 +269,26 @@ Agent mode is an explicit contract, not heuristic detection. By default it:
 - selects JSON and writes the full report to a guarded hidden file;
 - disables progress;
 - creates a guarded hidden checkpoint on the first run;
-- resumes that checkpoint on a later run with the exact same checkpoint
-  identity;
+- resumes that checkpoint on a later run with the same compatibility identity,
+  including across package-version-only upgrades;
 - emits only a bounded JSON receipt containing status, coverage summary,
   report path, report format, checkpoint path, and whether resume was used.
 
 The automatic artifact key covers the organization, repository filters,
 inclusion flags, repository limit, severity, explanation setting, normalized
-policy, baseline contents, tool version, and rule catalog. A changed scope or
-security control therefore receives a different path instead of replacing an
-incompatible checkpoint. The generated files begin
+policy, baseline contents, analysis generation, and rule catalog. A compatible
+package upgrade keeps the same path and atomically migrates older checkpoint
+metadata on the first successful resume. A changed scope, security control, or
+analysis behavior receives a different path instead of replacing an
+incompatible checkpoint.
+The generated files begin
 `.actions-warden-agent.`; protect them as sensitive report artifacts and add
 that pattern to the consuming repository's ignore rules when appropriate.
 
+Version-only upgrades do not accumulate new automatic artifacts. A deliberate
+analysis-generation change does retain the older keyed files as audit evidence;
+remove them only under the consuming repository's retention policy.
+
 Explicit CLI options take precedence over agent defaults. Use
 `--progress=always` when the user requests live progress. Use
 `--output=stdout` only when the caller intentionally wants the complete report

package/docs/CLI.md

@@ -21,7 +21,7 @@ actions-warden --version
 For reproducible one-off automation, invoke an exact package version:
 
 ```sh
-npx --yes actions-warden@0.3.0 audit
+npx --yes actions-warden@0.4.0 audit
 ```
 
 Network-backed commands resolve credentials in this order:
@@ -38,16 +38,20 @@ metadata and contents read access needed for the requested scope.
 ## Target and output options
 
 The repository commands (`audit`, `pin`, `verify`, `upgrade`, and `report`)
-share these options:
+share these target and output options:
 
 | option | default | behavior |
 |---|---|---|
 | `-w, --workflow <pattern...>` | discovery | One or more files, directories, or globs |
 | `--cwd <dir>` | current directory | Repository and path-safety root |
-| `--token <token>` | environment | GitHub API credential for network-backed work |
 | `--format <format>` | `toon` | `toon`, `json`, `text`, or `sarif` |
 | `--output <destination>` | `stdout` | `stdout` or `file` |
-| `--output-path <path>` | none | Required with `--output=file`; resolved inside `--cwd` |
+| `--output-path <path>` | none | Report path inside `--cwd`; implies `--output=file` |
+
+`pin`, `verify`, `upgrade`, and online `report` also accept `--token`. `audit`
+is entirely local and does not accept a token. `report --offline` rejects an
+explicit token, mode, or cooldown because those options would otherwise be
+silently unused.
 
 Without `--workflow`, actions-warden discovers:
 
@@ -72,19 +76,28 @@ actions-warden audit --cwd ../service
 ```
 
 Output files are created atomically and must remain within the real working
-directory after symlinks are resolved:
+directory after symlinks are resolved. Their parent directory must already
+exist. `--output=file` without a path and an explicit
+`--output=stdout --output-path=...` are invocation errors. Report, baseline,
+and checkpoint destinations are preflighted before network or mutation work;
+they cannot be directories, symlinks, selected workflows, default workflow
+discovery paths, or the reserved `.actions-warden.yml` and
+`.actions-warden.yaml` policy paths. Active configuration and baseline paths
+are checked again before any report or baseline destination is written.
 
 ```sh
 actions-warden audit \
   --format=sarif \
-  --output=file \
   --output-path=reports/actions-warden.sarif
 ```
 
+`--output=file --output-path=...` remains valid when an explicit destination
+is clearer in automation.
+
 ## `audit`
 
 Scan local workflows and composite actions without making network calls or
-changing files.
+changing workflows. It writes only an explicitly requested report or baseline.
 
 ```sh
 actions-warden audit \
@@ -105,8 +118,10 @@ actions-warden audit \
   --create-baseline=.actions-warden-baseline.json
 ```
 
-`--create-baseline` cannot be combined with `--baseline`. Parser failures are
-never written into the baseline. See [configuration and baselines](./CONFIGURATION.md).
+`--create-baseline` cannot be combined with `--baseline`, cannot share the
+report output path, and is validated before the audit begins. Parser failures
+are never written into the baseline. See
+[configuration and baselines](./CONFIGURATION.md).
 
 Exit code `0` means no unsuppressed findings; `1` means findings were reported;
 `2` means the scan could not be invoked safely or correctly.
@@ -141,7 +156,9 @@ or one exact stable ID:
 actions-warden pin --fix=18b82e86d7c14fe2 --write
 ```
 
-`--write` and `--dry-run` together are rejected.
+`--write` and `--dry-run` together are rejected. `--fix` must be one exact
+16-character hexadecimal ID from a current plan; uppercase input is normalized
+for convenience.
 
 ## `verify`
 
@@ -176,7 +193,9 @@ Defaults are `--mode=minor --min-age=7` and dry-run. Tag discovery is paginated;
 prereleases and downgrades are excluded. A candidate tag must be older than the
 cooldown. The age comes from GitHub release publication data when available,
 then from locally recorded first-seen evidence for the exact tag-to-SHA mapping.
-Missing evidence fails closed.
+Missing evidence fails closed. `--min-age` accepts only a non-negative integer;
+values such as `7days`, `1.5`, and values outside JavaScript's safe integer
+range are rejected rather than truncated.
 
 SHA-pinned references need `actions-warden-ref` metadata to establish the
 current semantic version. Legacy plain-semver comments remain readable.
@@ -207,7 +226,8 @@ actions-warden report \
 The audit determines the target set; pin and upgrade use exactly that same
 scope. A location with an upgrade is not duplicated as a pin proposal.
 `--offline` skips both network-backed planning phases and returns only the
-local audit.
+local audit. Because they cannot affect an offline report, explicitly combining
+`--offline` with `--token`, `--mode`, or `--min-age` is rejected.
 
 Use report for review, issue generation, or an AI planning step. It never
 accepts `--write`.
@@ -244,7 +264,9 @@ Defaults:
 
 Repository patterns match either `name` or `owner/name`, case-insensitively.
 An explicit pattern set that matches no eligible repository is an error.
-Selection is stable before `--max-repos` is applied.
+Selection is stable before `--max-repos` is applied. `--max-repos` must be a
+positive safe integer, and `--concurrency` must be an integer from 1 through
+16; malformed, fractional, or imprecise values fail before any API request.
 
 ```sh
 actions-warden org-scan my-org \
@@ -287,8 +309,9 @@ When the corresponding options were not explicitly supplied, agent mode sets:
 
 The artifact key includes the organization, repository filters, inclusion
 flags, repository limit, severity, explanation setting, normalized policy,
-baseline contents, package version, and rule catalog. A scope or security
-control change therefore selects a different checkpoint rather than
+baseline contents, analysis generation, and rule catalog. A compatible package
+upgrade therefore keeps the same paths, while a scope, security-control, or
+analysis-behavior change selects a different checkpoint rather than
 overwriting incompatible state. Generated paths have these shapes:
 
 ```text
@@ -321,7 +344,8 @@ an invocation error. Explicit `--format`, `--output`, `--output-path`,
 `--progress`, `--checkpoint`, and `--resume` choices override agent defaults.
 With explicit `--output=stdout`, stdout is the complete selected report and no
 receipt is added. Use `--no-agent-mode` to override an inherited environment
-marker. `ACTIONS_WARDEN_MODE` must be exactly `agent` when set.
+marker. Passing both agent-mode flags is rejected. `ACTIONS_WARDEN_MODE` must
+be exactly `agent` when set.
 
 ### Progress and resume
 
@@ -345,8 +369,8 @@ actions-warden org-scan my-org \
 ```
 
 Resume with the same organization, filters, inclusion flags, repository limit,
-severity, explanation setting, configuration, baseline, tool version, and rule
-catalog:
+severity, explanation setting, configuration, baseline, analysis generation,
+and rule catalog:
 
 ```sh
 actions-warden org-scan my-org \
@@ -358,11 +382,18 @@ actions-warden org-scan my-org \
 ```
 
 The token, concurrency, output format, progress mode, and report destination do
-not affect checkpoint compatibility. A resumed scan always lists repositories
-again and fetches a fresh default-branch tree for each selected repository.
-An error-free result is reused only when repository identity, default branch,
-and tree SHA still match. Changed repositories and any checkpointed result with
-an operational error are scanned again.
+not affect checkpoint compatibility. Neither does a package-version-only
+upgrade: the producing version is retained as checkpoint metadata, and a
+compatible older checkpoint is rewritten atomically on its first successful
+resume. The
+explicit analysis generation is advanced when discovery, parsing, finding
+identity, rule evaluation, or persisted result behavior changes. An
+incompatible generation fails closed; automatic agent mode selects a new keyed
+path. A resumed scan always lists repositories again and fetches a fresh
+default-branch tree for each selected repository. An error-free result is
+reused only when repository identity, default branch, and tree SHA still match.
+Changed repositories and any checkpointed result with an operational error are
+scanned again.
 
 `--checkpoint` starts a new checkpoint and replaces an existing file at that
 path. `--resume` requires a valid existing checkpoint and updates it. The
@@ -373,6 +404,11 @@ not the token or raw YAML, but can still reveal private repository names,
 paths, findings, and security posture; protect and retain them accordingly.
 Checkpoint reads and writes are capped at 256 MiB.
 
+Version-only upgrades no longer create extra agent artifacts. When an analysis
+generation intentionally changes, the older keyed report and checkpoint are
+retained rather than deleted automatically because they may be needed as audit
+evidence; remove them according to the consuming repository's retention policy.
+
 The scanner reads the default-branch Git tree and YAML blobs in memory. It
 never clones, checks out, or executes remote content. It fails closed on
 truncated trees and enforces these bounds per repository:
@@ -398,6 +434,23 @@ actions-warden rules --format=json
 
 This command has no repository or network dependency.
 
+## Exit status and invocation errors
+
+Every command uses the same process contract:
+
+- `0`: completed with status `OK`, or displayed help/version information;
+- `1`: completed with a structured `FAIL` result, such as findings or
+  operational errors;
+- `2`: could not start or complete safely because the command line, paths,
+  configuration, inputs, or environment were invalid.
+
+Commander-level failures such as unknown flags, missing values, invalid
+choices, conflicts, excess arguments, and a missing command also return `2`.
+Argument parsing and destination preflight run before network requests and
+before authorized workflow writes; active-control collisions are checked again
+before output. On exit `2`, treat stderr as the error channel and do not assume
+stdout contains a complete structured result.
+
 ## Cache and network behavior
 
 Local `pin`, `verify`, `upgrade`, and online `report` work caches successful

package/docs/DEVELOPMENT.md

@@ -81,6 +81,7 @@ src/
   lib/
     parser.js               YAML-to-normalized-workflow model
     targets.js, paths.js    repository target discovery
+    path-equality.js        real-path destination/control comparisons
     config.js, baseline.js  policy and accepted-finding controls
     resolver.js, cache.js   GitHub API, caching, ref and ownership checks
     github-org.js           read-only organization/tree/blob access
@@ -139,11 +140,17 @@ Changes must preserve these boundaries:
 
 - `pin` and `upgrade` default to dry-run at the command and API layers.
 - CLI and Action mutation require an explicit write option.
+- CLI integers and 16-hex change IDs use strict whole-value parsing. Commander
+  usage failures and application-level invocation failures both exit `2`.
 - A resolver failure must not fall back to a guessed tag or SHA.
 - Commits must be verified as belonging to the referenced repository.
 - Workflow rewrites operate on parsed scalar ranges and reparse before write.
 - Writes and configured paths remain inside the real repository root.
 - Symlink escapes and explicit targets that match nothing fail.
+- CLI report, baseline, and checkpoint destinations are preflighted before
+  network or workflow mutation, cannot replace selected/default-discovery
+  workflows or reserved policy paths, and are checked against active controls
+  again before output is written.
 - Credentials are redacted in JSON, TOON, text, SARIF, annotations, and
   top-level errors.
 - Finding and change IDs exclude absolute checkout paths.
@@ -154,14 +161,19 @@ Changes must preserve these boundaries:
 - Organization resume never trusts a stale result without fresh discovery and
   a matching repository identity, default branch, and tree SHA. Failed results
   are never reused.
+- Organization result compatibility is controlled by
+  `ORGANIZATION_ANALYSIS_GENERATION`, not by the package version. Producer
+  versions remain checkpoint metadata and compatible checkpoints migrate
+  through the guarded atomic writer.
 - Checkpoints use guarded atomic writes, remain inside the working directory,
   omit tokens and raw YAML, and cannot replace active policy or baseline files.
 - Progress stays outside deterministic report serialization; CLI progress is
   stderr-only and Action progress cannot form workflow commands.
 - Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
   vendor-environment heuristic. Explicit CLI output and progress options win.
-  Its automatic artifact key uses the validated checkpoint identity, and its
-  stdout receipt never includes findings or repository result arrays.
+  Its automatic artifact key uses the validated checkpoint compatibility
+  identity, and its stdout receipt never includes findings or repository result
+  arrays.
 - Attacker-controlled values cannot forge TOON lines or GitHub annotations.
 
 Tests should demonstrate the fail-closed behavior for any change touching these
@@ -276,6 +288,17 @@ previous repository errors, output equivalence, and concurrent completions.
 Persist each completed result before emitting its completion event so an
 observer failure or process interruption loses at most in-flight work.
 
+`ORGANIZATION_ANALYSIS_GENERATION` in `src/lib/org-checkpoint.js` is the manual
+semantic compatibility switch. Increment it whenever organization workflow
+selection, parsing, finding identity, rule evaluation, suppression, summaries,
+or other persisted repository-result semantics can change. Keep it unchanged
+for documentation, release metadata, progress rendering, authentication,
+concurrency, or internal refactors that preserve those results. The rule
+catalog hash independently invalidates catalog changes. A generation change
+must add tests proving the old checkpoint fails closed and agent mode selects a
+new artifact key; a compatible format migration must prove the old checkpoint
+is validated, rewritten atomically, and still subject to fresh tree checks.
+
 ## Output compatibility
 
 JSON is the public machine interface. Raw command results and serialized JSON

package/docs/GITHUB-ACTION.md

@@ -182,7 +182,9 @@ emission.
     if-no-files-found: error
 ```
 
-The output path must remain inside `working-directory`.
+The output path must remain inside `working-directory`, its parent directory
+must already exist, and an existing destination must be a regular file rather
+than a directory or symlink.
 
 ## Organization report
 
@@ -249,12 +251,14 @@ those inputs directly when an agent generates a workflow.
 the working directory before the actions-warden step, remove
 `checkpoint-path`, and set `resume-from` to the restored path. The Action does
 not itself retain files between ephemeral runners; use a protected artifact or
-other caller-managed storage. Scope, policy, baseline, package, and rule
-identity must match. Fresh repository discovery and tree checks still occur,
-and changed or previously failed repositories are rescanned. Checkpoints hold
-redacted report evidence about repositories and findings, so protect them like
-the organization report. `checkpoint-path` and `resume-from` are mutually
-exclusive and cannot equal `output-path`.
+other caller-managed storage. Scope, policy, baseline, analysis generation, and
+rule identity must match; a compatible package-version change is allowed and
+atomically refreshes checkpoint metadata on the first successful resume. Fresh
+repository discovery and tree checks still occur, and changed or previously
+failed repositories are rescanned. Checkpoints hold redacted report evidence
+about repositories and findings, so protect them like the organization report.
+`checkpoint-path` and `resume-from` are mutually exclusive and cannot equal
+`output-path`.
 
 ## Mutation workflows
 

package/docs/JAVASCRIPT-API.md

@@ -205,11 +205,13 @@ possible; failures that prevent organization discovery throw.
 `checkpointPath` explicitly enables atomic checkpoint writes inside `cwd`.
 Set `resume: true` to require, validate, and update an existing checkpoint at
 that path. The organization, selection and audit options, normalized policy,
-baseline contents, package version, and rule catalog must match. Concurrency
-and token changes are allowed. Resume performs fresh discovery and tree reads;
-it reuses only error-free results whose repository, default branch, and tree
-SHA remain unchanged. Checkpoints contain redacted report data and revision
-metadata, never tokens or raw YAML.
+baseline contents, analysis generation, and rule catalog must match.
+Concurrency, token, and compatible package-version changes are allowed. The
+producing package version remains metadata, and compatible older checkpoints
+are atomically migrated on the first successful resume. Resume performs fresh
+discovery and tree reads; it reuses only error-free results whose repository,
+default branch, and tree SHA remain unchanged. Checkpoints contain redacted
+report data and revision metadata, never tokens or raw YAML.
 
 `onProgress` may be synchronous or asynchronous and is awaited in event order
 at each emission point. A callback error rejects the scan; repository results

package/docs/OUTPUTS.md

@@ -47,8 +47,10 @@ The CLI maps results to process codes:
 | `1` | Semantic status `FAIL`; inspect the emitted report |
 | `2` | Invalid arguments, invalid policy, unsafe paths, or another invocation-level failure |
 
-An invocation-level failure is written to stderr as `error: <message>`. It may
-occur before a structured payload can be rendered, so do not assume stdout
+An invocation-level failure is written to stderr as `error: <message>`. Unknown
+options, missing values, invalid choices, conflicting flags, malformed numeric
+values, unsafe destinations, and a missing command all return `2`. The failure
+may occur before a structured payload can be rendered, so do not assume stdout
 contains JSON when the process exits `2`.
 
 Organization-scan live progress is also a stderr-only channel. It never becomes
@@ -119,16 +121,19 @@ node -e '
 '
 ```
 
-Writing reports through `--output=file` is safer than shell redirection when
-repository path containment matters:
+Writing reports through a guarded output path is safer than shell redirection
+when repository path containment matters. `--output-path` implies file output:
 
 ```sh
 actions-warden audit \
   --format=json \
-  --output=file \
   --output-path=reports/actions-warden.json
 ```
 
+The parent directory must exist. Destination safety is checked before command
+work, then active policy and baseline collisions are checked again before the
+report is written. Explicit `--output=stdout --output-path=...` is rejected.
+
 ## TOON
 
 TOON is Token-Oriented Object Notation. Each line is:

package/examples/upgrade-pr.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Apply eligible upgrades
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: npx --yes actions-warden@0.3.0 upgrade --mode=minor --min-age=7 --write
+        run: npx --yes actions-warden@0.4.0 upgrade --mode=minor --min-age=7 --write
 
       - name: Open or update pull request
         env:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actions-warden",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Audit GitHub Actions across repositories and organizations; pin, verify, and upgrade dependencies.",
   "author": "Naveen Yagati",
   "homepage": "https://github.com/chiz0me/actions-warden#readme",

package/skills/actions-warden/SKILL.md

@@ -33,27 +33,31 @@ Invoke `actions-warden` when the user:
 The package is on npm as `actions-warden`. Invoke the reviewed version exactly:
 
 ```sh
-npx --yes actions-warden@0.3.0 audit
-npx --yes actions-warden@0.3.0 audit --severity=high --explain
-npx --yes actions-warden@0.3.0 audit --create-baseline=.actions-warden-baseline.json
-npx --yes actions-warden@0.3.0 audit --baseline=.actions-warden-baseline.json
-npx --yes actions-warden@0.3.0 audit --format=sarif
-npx --yes actions-warden@0.3.0 pin
-npx --yes actions-warden@0.3.0 pin --write
-npx --yes actions-warden@0.3.0 upgrade --mode=minor
-npx --yes actions-warden@0.3.0 upgrade --min-age=14 --write
-npx --yes actions-warden@0.3.0 verify
-npx --yes actions-warden@0.3.0 report --offline
-npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --format=json
-npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --agent-mode
-npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --checkpoint=.actions-warden-org-checkpoint.json
-npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --resume=.actions-warden-org-checkpoint.json
-npx --yes actions-warden@0.3.0 rules
+npx --yes actions-warden@0.4.0 audit
+npx --yes actions-warden@0.4.0 audit --severity=high --explain
+npx --yes actions-warden@0.4.0 audit --create-baseline=.actions-warden-baseline.json
+npx --yes actions-warden@0.4.0 audit --baseline=.actions-warden-baseline.json
+npx --yes actions-warden@0.4.0 audit --format=sarif
+npx --yes actions-warden@0.4.0 pin
+npx --yes actions-warden@0.4.0 pin --write
+npx --yes actions-warden@0.4.0 upgrade --mode=minor
+npx --yes actions-warden@0.4.0 upgrade --min-age=14 --write
+npx --yes actions-warden@0.4.0 verify
+npx --yes actions-warden@0.4.0 report --offline
+npx --yes actions-warden@0.4.0 org-scan my-org --severity=high --format=json
+npx --yes actions-warden@0.4.0 org-scan my-org --severity=high --agent-mode
+npx --yes actions-warden@0.4.0 org-scan my-org --severity=high --checkpoint=.actions-warden-org-checkpoint.json
+npx --yes actions-warden@0.4.0 org-scan my-org --severity=high --resume=.actions-warden-org-checkpoint.json
+npx --yes actions-warden@0.4.0 rules
 ```
 
-Useful global flags: `--workflow <path-or-glob>` (repeatable), `--cwd <dir>`,
-`--format toon|json|text|sarif`, `--output stdout|file`, `--output-path <path>`,
-`--token <gh-token>` (also reads `GITHUB_TOKEN` / `GH_TOKEN`).
+Useful shared command flags: `--workflow <path-or-glob>` (repeatable),
+`--cwd <dir>`, `--format toon|json|text|sarif`, `--output stdout|file`, and
+`--output-path <path>`. An output path implies file output; never combine it
+with explicit `--output=stdout`, and create its parent directory first.
+Network-backed commands accept `--token <gh-token>` and also read
+`GITHUB_TOKEN` / `GH_TOKEN`; prefer the environment. Local `audit` does not
+accept or need a token.
 Audit, report, and org-scan also accept `--config <path>` and `--baseline <path>`.
 `.actions-warden.yml` is loaded automatically when present.
 Organization scans accept `--repository <glob...>`, `--visibility`,
@@ -69,7 +73,10 @@ precedence.
 Exit codes: `0` for a normal `OK` result, `1` for a normal structured `FAIL`
 result (findings or operational errors), and `2` for an invocation-level error.
 For code `1`, inspect the report. For code `2`, read stderr and do not assume
-stdout contains a complete structured payload.
+stdout contains a complete structured payload. Do not retry code `2` by
+guessing alternative flags: fix the named conflict, integer, ID, working
+directory, or destination. The CLI rejects those errors before network or
+authorized workflow mutation whenever the needed path information is known.
 
 ## What to do when invoked
 
@@ -124,7 +131,7 @@ stdout contains a complete structured payload.
    agent-initiated broad scan must use the explicit agent mode:
 
    ```sh
-   npx --yes actions-warden@0.3.0 org-scan my-org \
+   npx --yes actions-warden@0.4.0 org-scan my-org \
      --agent-mode
    ```
 
@@ -144,7 +151,9 @@ stdout contains a complete structured payload.
    inference tokens to plan, monitor, and summarize; output admitted to its
    context adds to that usage. Resume primarily saves GitHub API/blob work and
    elapsed time. A changed scope or security control receives a different
-   artifact key rather than overwriting an incompatible checkpoint.
+   artifact key rather than overwriting an incompatible checkpoint. Compatible
+   package upgrades retain the same key and resume state; an analysis-behavior
+   change receives a new key.
 
 ## Audit rules