Skip to content

Latest commit

 

History

History
435 lines (342 loc) · 31 KB

CI-RECIPES.md

File metadata and controls

435 lines (342 loc) · 31 KB

CI Recipes

Recipe 1 — Guard (mandatory CI gate)

Run docguard init --with ci to create .github/workflows/docguard.yml. Existing workflows are preserved; explicit --force backs up and replaces the file. The standalone docguard ci command continues to execute checks. Start from templates/ci/github-actions.yml or the Spec Kit guard workflow in extensions/spec-kit-docguard/templates/github-workflows/. These checked-in templates are the maintained source for action pins, runtime selection, and report handling. Copying a template does not configure repository branch protection; require its check independently.

Use a fixed tool version, full Git history for freshness, and explicit warning policy. Run the check against the actual revision proposed for merging. A missing executable, malformed report, or unexpected nonzero exit is a tool failure, not a successful scan. Configure merge-queue triggers if the repository uses a merge queue.

node_modules/.bin/docguard ci --format json --no-history > docguard-report.json

The CLI exits 0 for pass, 1 for failure, and 2 for warning-only results. A plain shell step treats both 1 and 2 as failures. To permit warnings, capture the exit status explicitly and allow only 0 or 2. To block warnings, use ci --fail-on-warning. Severity overrides retain their configured meaning.

Exit 4 under the strict default. guard exits 4 when a validator that applies to the project examined nothing for a reason the project can resolve (or could not observe at all), and ci blocks with CI_STRICT_UNEXAMINED. A pipeline that fails on any non-zero exit fails on 4, which is the point: the job log carries the Adopt block, with each validator's cause and fix, and the "DocGuard could not read" block, which never changes the exit code. The Action turns 4 into a failed step with a message that says so; the GitLab component and templates/ci/github-actions.yml pass the exit code through.

For a staged rollout, either pin the release line the project already passes with "enforcement": { "mode": "strict", "asOf": "0.47" } in .docguard.json (checks added to strict later are reported as pending and do not change the exit code), or stay on the earlier behavior with "enforcement": "standard". A "validators": { "<key>": false } entry in .docguard.json does not switch a check off under strict (guard names the entries it did not honor); a reasoned waiver or "enforcement": "standard" does. Do not make the pipeline swallow exit 4 with || true: the run then reads green for a check that examined nothing. docguard upgrade prints what the default changes for a project, read-only, and docs/upgrading-to-strict.md walks through the ways forward.

To adopt the gate on a repository that already has findings, run guard --update-baseline once and commit .docguard.baseline.json. Guard and ci then suppress up to the frozen number of each finding, report how many they suppressed, and gate everything new; --no-baseline shows everything for one run. A finding is matched by its code, file path without line number, and message with numbers masked. TRC004's trailing IR soft-match hint is left out, so adding an unrelated test file does not bring a frozen finding back. A baseline written by an earlier release still matches, and --update-baseline rewrites it in the current form (specs/052-baseline-stable-fingerprint).

When .docguard-evidence.json exists, guard also evaluates its declarations. Contradictions are high-confidence errors. Stale input digests, missing or ambiguous targets, malformed evidence, and unsupported report shapes remain visible warnings. Inspect the complete contract with:

npx docguard-cli verify --evidence --format json

This direct command exits 0 when every configured declaration is verified, 2 when evidence is stale, inconclusive, or unsupported, and 1 when a declaration is contradicted or the manifest is invalid. CI that permits unresolved evidence must explicitly allow only status 2; a contradiction is always a failed gate.

Generate oasdiff or Buf reports in an earlier pinned CI step, save their machine output, and declare SHA-256 identities for every repository input. DocGuard consumes those artifacts; it does not install or invoke either producer. Keep the broad freshness and semantic review paths enabled because exact evidence does not cover undeclared prose.

Recipe 2 — Auto-Fix (PR-time mechanical fixes)

Run fix --write on a controlled checkout when documentation mutation is intended. Review the resulting diff and rerun guard. Preserve human-authored intent; a disagreement may require fixing implementation rather than rewriting the specification.

Mechanical replacements require their existing provenance and generated-section safeguards. A scheduled or PR repair workflow should create a reviewable branch/PR and deduplicate existing repair work. Grant write privileges only to that explicitly enabled workflow. Fork contributions should receive read-only verification unless a separate trusted process handles repair.

The shipped auto-fix template and composite action expose optional commit/comment behavior. Review those flags and their permissions before enabling them. A generated workflow is executable code and deserves the same review as another repository change.

Recipe 3 — Sync (memory refresh on a schedule or pre-merge)

sync --write regenerates sections declared as code-derived. Human sections retain judgment and rationale. Cache identity reflects relevant inputs, so ordinary source edits invalidate a prior plan. --since <ref> refreshes only the sections whose sources changed (specs/029-sync-section-scope). A section drawn from incomplete evidence, such as a module-graph on a runner without python3 for a Python project, is skipped unless --allow-partial; run the refresh where the evidence is complete.

On a schedule, produce a diff, check for an existing repair PR, and create a new proposal only when meaningful work remains. Keep clean runs quiet. Set an owner and response expectation for unresolved findings. Scheduled source scans cannot detect every external deployment or vendor change; operational checks need their own evidence.

Recipe 3a — Protected scheduled releases

The repository's scheduled release workflow opens a reviewable release/vX.Y.Z pull request because main requires pull requests and six checks: four runtime checks (test (18/20/22/24)) and the supply-chain checks osv-scan-pr / osv-scan and websec. GitHub places pull-request workflows created with the repository GITHUB_TOKEN into an approval-required state. Explicit workflow_dispatch events run, but their jobs do not satisfy branch protection's required pull-request checks, and their completion does not produce a downstream workflow_run when the repository token authored the dispatch. GitHub documents a personal token or GitHub App as the fully automated alternative. DocGuard instead keeps the repository token and one explicit maintainer action: select Approve workflows to run on the generated PR. No credential is stored for the release PR or its merge; the only release secret is the Homebrew tap deploy key described below.

After approval, ordinary pull-request CI supplies the six required contexts. Before the branch is pushed, the trusted scheduler validates the base repository, bot author, branch/title/version agreement, next-version increment, synchronized package surfaces, and changed-file allowlist. It then arms GitHub's native squash auto-merge. Native auto-merge remains blocked by the six required checks, binds eligibility to the current PR head, and resets when that head changes. The scheduler waits up to ten minutes for the merge and then dispatches the idempotent release workflow. Approvals rarely arrive inside that wait, so a tag-driven release sweep every 10 minutes is the usual publication route (#447); tagged versions exit after the small detect job. If publication is interrupted, either the sweep or the next release schedule sees the current package version without a tag and retries publication before considering another bump. An orphaned release branch fails closed; an existing open release PR is reused and has auto-merge re-armed.

The scheduler is four jobs, so no test runs beside a write token (specs/068-release-least-privilege). cut (read-only) decides whether a release is due, bumps the version, cuts the changelog, synchronizes the package surfaces, runs the candidate validation above, and uploads the result as a patch before any test runs. verify (read-only) applies that patch and runs the suite and guard. open-pr holds the write scopes and runs no repository code: it checks every path in the patch against the release path list, applies it, pushes the branch, opens the pull request, arms auto-merge and waits. recover holds only actions: write and dispatches the release workflow when the current version has no tag. In the release workflow, the test job is read-only, the Spec Kit ZIP, the Claude Desktop bundle and the PyPI distribution are built without credentials, and attach-assets and publish-pypi receive only the built files.

The bump is auto unless a maintainer dispatches patch or minor (specs/026-release-readiness). .github/scripts/release-changelog.mjs infer reads the curated ## [Unreleased] section. Any populated ### Added, ### Removed or ### Deprecated heading makes a minor release; otherwise the release is a patch. The same script's cut moves the curated notes under the new ## [x.y.z] heading and lists the merged commit subjects under ### Commits, so the published notes are the reviewed ones. The release PR also moves action.yml's DOCGUARD_RELEASED_VERSION and the copyable raccioly/[email protected] examples in README.md and docs/ai-integration.md. .github/scripts/sync-release-version.mjs updates every versioned surface in one fail-closed pass, including the checked-in .agent/skills/ and .agent/commands/ copies, which mirror their sources byte for byte; the release commit stages them and the changed-file allowlist (RELEASE_PATH_ALLOWLIST) admits them (specs/051-release-cut-green).

After npm serves the new tarball, the publish-homebrew job renders packaging/homebrew/docguard.rb from it and pushes the result to raccioly/homebrew-tap. The tarball is checked against npm's dist.integrity first. The push uses a write deploy key that can reach only the tap, stored as the Actions secret HOMEBREW_TAP_DEPLOY_KEY. Without the secret the job warns and skips. With it, the 10-minute sweep retries until the tap serves the released version.

The publish-mcp-registry job lists each release in the official MCP registry (registry.modelcontextprotocol.io, server io.github.raccioly/docguard) once npm serves the package server.json names (specs/026-release-readiness FR-007). It holds contents: read and id-token: write only, with no stored secret: mcp-publisher login github-oidc proves the io.github.raccioly/* namespace with the repository's OIDC token. It checks out the released tag, asserts that server.json and package.json carry the version being published, verifies a pinned mcp-publisher with cosign, skips when the registry already lists the version, and counts a duplicate-version refusal as success. detect-version also reports registry_missing when the tag exists and the registry's latest is older, so the 10-minute sweep backfills a listing that fell behind. An unreadable registry answer publishes nothing and warns.

Do not use a post-approval workflow_run listener as the release continuation. The approval-required completion is the event that listener observes; approving the held run executes its jobs without producing a second completion event for the listener. Release PR #380 demonstrated this boundary while publishing v0.40.1. Release PR #383 then proved repository-token native auto-merge, while also proving that its resulting push is recursion-suppressed and cannot be the sole publication trigger. The bounded wait catches the rare fast approval; the 10-minute tag sweep publishes everything else without continuous polling or another credential.

The v0.40.3 release is the retained end-to-end proof. Scheduled run 34922506777 opened repository-token PR #386 and armed native auto-merge. After one maintainer workflow approval, CI run 34922605581 and supply-chain run 34922605917 passed, GitHub merged e27d6bf0203708ee8206a1434eb292520f4c4494, and the bounded wait dispatched publication run 34922784629. That run published npm, PyPI, GHCR, the GitHub Release, extension ZIP, and MCPB and refreshed the catalog reminder.

Catalog submission remains an explicit human action. The release and manual catalog workflows maintain one open reminder in this repository: each run refreshes the newest matching issue to the current version and closes older matching reminders as superseded.

Recipe 3b — Spec completion and post-hoc reconciliation

Run docguard reconcile --since <merge-base> --format json when implementation may have changed approved behavior outside the original Spec Kit flow. Review unsupported files and intent-change classifications; write mode can refresh only DocGuard-owned mechanical sections. After declared tasks, source and test evidence, and affected canonical docs are reviewed, run docguard specs complete --id <spec-id> --since <merge-base> --check as the merge gate. Apply the same command with --write --reason "<reviewed outcome>" on a clean controlled checkout to record verification. A taskless living verification contract is eligible only when every requirement has qualified evidence. Keep living specs current; archive only when the registry reports that the selected persistence model is ready.

--since sets the starting revision only for a spec's first completion. A spec with a recorded revision reconciles from it, so its maintenance gate is specs complete --id <spec-id> --check with no --since. There --since may name the recorded revision or an ancestor of it. A commit between the recorded revision and HEAD is accepted only when the recorded range exceeds the diff budgets even when read in batches; the outcome then records the skipped commits as narrowedFrom. Any other --since blocks with SPC006 and writes nothing (specs/028-completion-revision-anchoring).

Close a spec in one commit, with no hand edit of .docguard-specs.json (specs/101-completion-one-commit): tick the last task, run docguard specs --write, then docguard specs complete --id <spec-id> --since <ref> --canonical-doc <path> --persistence living --reason "<reviewed outcome>" --write (--canonical-doc is repeatable; both flags also exist on specs approve), and commit once. Ticking boxes in the completing spec's own tasks.md is part of closing it; any other change to that file, or a tick in another spec's, still blocks. The tick, the registry record and the outcome land in one commit, so a gate that runs guard on every commit never sees DLC002 or a half-written record. Several completions can share that commit: the registry, active context and outcome blocks they write do not count as changes.

The record survives a squash merge and a rebase. Each outcome also records the git blob of every evidence file (the Blobs: segment of its line in the spec's outcome block), and a recorded revision that is no longer an ancestor of HEAD is still anchored when the commit that landed the record has those blobs. Guard reports SPR008 only when the evidence changed between review and landing (the message names the files), or for a record written before blobs were recorded; docguard specs reanchor --id <spec-id> --write moves such a record to the first commit on HEAD's first-parent history whose evidence files are byte-identical, and adds the blobs (specs/028-completion-revision-anchoring, specs/101-completion-one-commit). When no commit carries those bytes, or the old revision no longer resolves, --to <merge commit> --reason "<why>" records an attested anchor and the evidence files that differ. When one spec has dangling revisions from different merges, add --from <revision> so each is attested to its own merge. The next specs complete takes the landing commit as its diff base, so --since is needed only when no commit carries the evidence.

A pull request that edits a closed spec's evidence files needs the spec closed again in the same pull request, and the gate says so: on the merge ref the commit that landed the record is the main branch's squash commit, whose files match the record, so SPR008 cannot see the edit, and SPR011 (a warning, which strict fails on) compares the record's blobs with HEAD's files instead (specs/103-completion-upkeep). It reads only HEAD's tree, so a shallow clone is enough, and it skips the spec's canonical documents and hub files (four or more specs list them). A gate that runs guard on every commit and fails on warnings stays clean when the edit is not committed first: run specs complete with the evidence edit uncommitted and commit both together. docguard specs complete --stale --reason "<text>" --write closes every flagged spec in one transaction; commit its result with the change.

Under squash merges, run completions on a branch whose HEAD is the default branch's tip when a record carries no evidence blobs (one written before they were recorded): every outcome then records a revision that stays on the default branch, and specs complete warns when it does not.

Recipe 3c — Spec-first gate

Require every pull request that changes governed code to name its spec. Declare the governed paths in .docguard.json ("specFirst": { "paths": ["src/**"] }; unset, every changed path except Markdown, specs/** and tests is governed), then run:

- uses: actions/checkout@<sha>
  with: { fetch-depth: 0 }
- uses: raccioly/docguard@<sha>
  with: { command: spec-first }

The command is docguard specs require --since origin/<base> --message-file <body>. It passes when the PR description or a commit message names an existing specs/<dir> path or Spec ID, when the change edits a spec's own files, or on one line Spec-Exempt: <kind> — <reason> (kinds release, deps, typo, test-only unless specFirst.exemptKinds says otherwise; reason of 10+ characters). An invented reference never passes. Exit 1 means uncovered and exit 2 means inconclusive (unknown base, shallow history, oversized inventory); both should fail the job. When calling the CLI from your own workflow, pass the PR body through env into a file. Never splice ${{ github.event.pull_request.body }} into a run: script.

Recipe 3d — Agent instruction budget

guard measures every AGENTS.md chain the way Codex loads it: root to working directory, with AGENTS.override.md replacing AGENTS.md. It reports STR004 above agentInstructions.maxBytes (default 32768, Codex's project_doc_max_bytes). The recipe needs no extra step: it runs inside Recipe 1.

For a monorepo that is already over budget, freeze the debt instead of raising the budget for everyone. The key is the chain's deepest file:

{ "agentInstructions": { "allowances": { "packages/api/AGENTS.md": 61440 } } }

A chain may shrink under its allowance, and one byte of growth past it fails again. STR005 asks you to lower an allowance once the chain has shrunk by 1 KiB or more, so every increase stays a reviewed diff.

Recipe 3e — Non-regression budgets

The budget job in ci.yml checks the PR's base commit out beside the head and runs node tools/budget.mjs ab. Guard runs interleaved over the same targets for both CLIs, so the time comparison measures the code, not the runner. Each tree also reports its own agent-facing output sizes (context pack, task packets, MCP responses, llms bundles), its packed package weight, its runtime dependencies and its self-guard findings. budgets.json holds the ratios and floors. A breach fails the job unless the PR body declares Budget-Exempt: <metric> — <reason>; the full table goes to the job summary. An unmeasurable base is inconclusive, never a pass. To reproduce the table locally, run git worktree add ../base origin/main and then npm run budget -- --base ../base (specs/031-non-regression-budgets).

Recipe 3f — Release trend gate

A pull request is compared with its base. A scheduled release batches many pull requests, so the release-gate job in release.yml also compares the candidate with the previous release tag before anything is tagged or published (specs/087-release-trend-gate):

  1. Finding changes. node tools/release-ab.mjs runs the previous release's CLI and the candidate over the corpus in release-gate.json: the repository itself, benchmarks/fixtures/* and benchmarks/agent-context/fixtures/*. Each directory gets one fresh one-commit copy per CLI, and the runs are serial. Findings are compared as multisets of stable fingerprints, along with exit codes and validator statuses.
  2. Explanations. The gate fails unless the CHANGELOG section being released names every code whose findings changed. An exit-code change needs an Exit codes: line. A code whose message carries a date or timing goes in volatileCodes, with a reason, and is compared by count. A code a corpus directory cannot judge goes in that entry's ignoreCodes, with a reason. Both are listed in the summary, never hidden.
  3. Budgets and precision. tools/budget.mjs ab and the precision benchmark are re-run with the previous release as the base. The release's CHANGELOG section is the message file, so a plain Budget-Exempt: <metric> — <reason> line there waives one metric, as it does in a PR body, and a Benchmark-Rebaselined: <case id> — <reason> line acknowledges a fixture corrected on purpose (the case's other regressions still fail; a line with nothing to acknowledge fails as stale).

With no previous tag the job prints a notice and skips. To run it locally: git archive v0.45.2 | tar -x -C ../prev && ln -s "$PWD/node_modules" ../prev/ && node tools/release-ab.mjs --base ../prev --head ..

Guard time is each tree's median of samples rounds (5 in budgets.json), and the tree that runs first alternates between rounds. A median of N samples ignores up to (N − 1) / 2 slowed samples of either tree: with five rounds, two guard runs delayed by a load burst, however long, cannot pull a median above the slowest of the other three. A load that rises steadily through the run moves the two medians only one sample apart. A difference under the floor (150 ms) never fails. Below three samples there is no outlier margin: with --samples 1, one delayed process decides the verdict (specs/062-budget-deterministic).

Recipe 3f — Requirement anchors under human review

docguard anchors accept records a reviewed link in .docguard-anchor-lock.jsonl, together with a reason, the fingerprints it replaced, and a bulk flag when it covers more than one link.

DocGuard authenticates nobody. An agent can run accept as easily as a person, so require human review of the lock in the forge. Add this to CODEOWNERS, and require review from code owners in branch protection:

.docguard-anchor-lock.jsonl @your-org/requirement-owners

Merging. Declare the lock merge=union in .gitattributes, so two branches that review links of the same spec merge without a conflict:

.docguard-anchor-lock.jsonl merge=union

docguard anchors accept … --gitattributes adds that line; DocGuard never edits .gitattributes without the flag. If a union merge keeps two different lines for one link, DocGuard reads the one whose recorded fingerprints match the code and the requirement as they are now, so the merge never fails a gate by itself; the link needs review (ANC001 or ANC002) only when neither line matches. The next accept writes one line per link, and docguard anchors merge --write does the same without accepting anything. Without the union line, a merge that conflicts in the lock leaves git conflict markers (ANC005); docguard anchors merge --write keeps both sides and resolves them.

Adoption. Run docguard anchors accept --baseline --bulk --reason "<why>" once, and commit the lock. Baselined links are never counted as reviewed; docguard anchors --format json reports the baselined share.

Warnings. Guard warns on:

  • a link whose code changed (ANC001);
  • a link whose requirement changed (ANC002);
  • a reviewed link whose tag is gone (ANC003).

Read the change, then docguard anchors accept --link '<key>' --reason "<what you checked>".

Failures. Under the default anchors.failOn: reviewed-exact, ANC001 and ANC003 fail guard only for a link that was accepted as reviewed, is anchored to a symbol, statement or route, and was read by Babel or python3's ast. Everything else stays a warning. Set "anchors": { "failOn": "none" } to keep anchors advisory.

docguard specs complete never counts the completing spec's own failing anchors toward SPC007. It lists them with their accept commands instead, because completing a spec is how its links get reviewed.

Recipe 4 — Score (track CDD maturity over time)

score --format json reports structural maturity. Its numeric threshold is stable, while assurance explicitly states that factual accuracy remains unverified. Comparing scores is meaningful only with the same tool/configuration and a comparable coverage scope.

Use guard findings and declared verification evidence for enforcement. A high score alone does not establish current documentation, correct prose, or regulatory compliance.

Recipe 1b — GitLab CI / Jenkins (JUnit output)

guard --format sarif emits SARIF 2.1.0 for GitHub Code Scanning and enterprise dashboards. Every result carries the finding's channels in properties: disposition (act when DocGuard names the correction, escalate when the judgement is the reader's), confidence, evidence (measured or not-measured), parserTier, reportable, suggestionKind, and the intrinsic and effective severities. Gate automation on disposition rather than severity alone — a blocking result can still be an escalation, and applying an automated fix to one silences a signal without resolving it. parserTier of regex-fallback or fallback-language means no syntax tree was available for that file, so absence of a result there is weak evidence.

guard --format junit emits a test report suitable for GitLab/Jenkins ingestion. Install a fixed DocGuard version in the job, capture the exit status, and upload the report even on failures. Permitting exit 2 is an explicit warning policy; other nonzero statuses remain failures.

Recipe 4b — Score history across ephemeral CI runs

ci records history by default. --no-history opts out. Ephemeral runners need an explicitly configured artifact or cache policy if trends are to span runs. Treat restored history as informational data, not proof that the current checkout was verified. Avoid sharing writable caches between untrusted pull requests and privileged release workflows.

Recipe 4c — Multi-repo scorecard (no extra tooling)

Run ci --format json per repository and retain project, revision, tool version, configuration, status, and assurance scope. Aggregate findings by code while preserving their repository ownership. Report unsupported and unclassified coverage alongside successful checks.

Recipe 4d — Detector precision regression

Run the network-free synthetic corpus on ordinary pull requests:

node benchmarks/run.mjs --baseline benchmarks/baseline.json

Run the full pinned public corpus in a separate trusted, network-enabled job when detector or scanner behavior changes:

node benchmarks/run.mjs --external --baseline benchmarks/baseline.json

Treat a core comparison failure as a quality regression. In the network-free run the pinned public baseline cases were not selected; they appear under comparison.core.outOfSelection and are not regressions. The loader validates the baseline envelope before the run starts and refuses one whose metrics or caveat no longer match its cases. Persisted runtime snapshots stay advisory even when environment labels match. Apply the 20-percent gate only to at least five controlled samples from the same paired comparison session. Updating the baseline is a reviewed change: inspect every added or removed case, label, unsupported result, and confidence limit before using --replace-baseline.

Pre-commit hook (no GitHub Actions required)

docguard hooks --type pre-commit installs a local gate that prefers the repository's installed DocGuard binary. The hook blocks an unavailable runtime. When husky, lefthook or simple-git-hooks owns the hook, DocGuard writes nothing and prints the line to add to that manager's configuration. --auto-fix additionally applies mechanical fixes and stages their output; enable it only when that mutation is intended.

A Git hook lives in the shared .git/hooks and is active on every branch and linked worktree, while .docguard.json is a branch-local tracked file. The installed hook therefore skips any working tree with no .docguard.json and lets the commit through, and treats guard exit 3 (errors in an uninitialised project) as allowed rather than blocking. A project that never adopted DocGuard is not blocked by a hook installed from another branch; adopted projects are gated exactly as before.

Regenerate installed hooks after upgrading to pick up changes in hook behavior. The pre-push score hook parses real JSON and enforces its configured minimum; it complements the full CI gate. Local hooks can be bypassed, so protected merges remain necessary for shared enforcement.

Recipe 5 — Pre-commit lite (changed files only)

guard --changed-only --since <ref> runs its curated validator subset with changed-file scoping, plus explicitly escalated validators. Use a full guard at the merge boundary. The entry point and guard.mjs define the current subset; a copied list in this recipe would drift.

Permissions cheatsheet

Operation Default authority Additional authority
Guard, score, report Repository read Artifact storage if configured
Mechanical repair Read/write controlled checkout Branch/PR publication only when enabled
Feedback preview Local analysis User submits reviewed public metadata voluntarily
External precision corpus Public read-only Git fetch Network access to exact pinned commits; no project script execution
Scheduled review Repository read Notification or publication only when explicitly configured

Action inputs reference

action.yml is the authoritative composite-action input contract. Review command selection, CLI version (docguard-version; empty installs the version the action release was published with), warning policy, score threshold, working directory, and optional commit/comment flags. Pin the action to a reviewed commit and retain the corresponding release label for maintenance.

Action outputs reference

Read the outputs declared in action.yml and the command's JSON schema before wiring downstream steps. Preserve unknown/unverified values. An integrity digest detects changes to covered report data; it is neither a trusted signature nor proof of a correct scanner.