@marinjursic/prc-darwin-arm64 0.1.0

package/bin/docs/architecture/adapters.md

@@ -0,0 +1,380 @@
+# Sandboxed adapter protocol
+
+External tools are untrusted evidence producers. They do not evaluate controls,
+change policy, or mark assertions as passing. The scanner accepts only
+schema-valid observations and leaves the final assertion assessment to the
+deterministic engine.
+
+## Protocol
+
+`prc-adapter-jsonl-v1` is a line-delimited JSON protocol over standard input and
+standard output. The scanner sends exactly three messages:
+
+```json
+{"type":"hello","protocol":"prc-adapter-jsonl-v1","run_id":"<64 lowercase hex characters>"}
+{"type":"input","subject":{"target_name":"example","inventory_digest":"<64 lowercase hex characters>"},"facts":{},"config":{}}
+{"type":"execute"}
+```
+
+An adapter may emit bounded `log`, `observation`, and `artifact` messages and
+must end with exactly one `summary`. Standard output is protocol-only. Standard
+error is bounded diagnostic text. A summary is an implementation execution
+status, not a control result.
+
+Raw standard error is not echoed in CLI JSON. The runner reports only its byte
+count and SHA-256 digest. Protocol messages may still describe sensitive target
+facts, so operators must treat the transcript as assessment evidence and apply
+appropriate access, redaction, and retention controls.
+
+The decoder rejects:
+
+- unknown or duplicate JSON fields;
+- blank, oversized, excessive, or trailing messages;
+- absolute, non-normalized, or escaping artifact and source paths;
+- malformed digests, statuses, locations, and counters;
+- missing summaries or messages after a summary; and
+- fields through which an adapter tries to declare `pass`, suppress a finding,
+  or otherwise take evaluator authority.
+
+The machine contract is
+[`adapter-message.schema.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/schemas/adapter-message.schema.json). The
+checked-in release suite includes completed, unsupported, timeout, malformed,
+resource-limit, undeclared-output, and explicit evaluator-authority attack
+transcripts.
+
+Manifest v0.4 also defines two closed native-output protocols. The first,
+`prc-adapter-gitleaks-json-v1`, accepts only Gitleaks 8.30.0's reviewed
+official image digest, exact scanner-owned current-tree command, and JSON
+report contract. The scanner supplies the SHA-256-pinned upstream default
+ruleset on standard input, forces full redaction, ignores target-owned Gitleaks
+configuration, ignore files, and `gitleaks:allow` comments, and disables archive
+and recursive-decoding expansion. The normalizer rejects unknown or duplicate
+fields, unredacted findings, history or symlink metadata, paths outside the
+snapshot, inconsistent fingerprints, invalid coordinates, and excessive
+findings. It retains only rule identity and normalized location metadata.
+
+The exact redacted native report is represented by a media type, byte count,
+and SHA-256 artifact descriptor in the transcript; raw report content is not
+copied into the durable run record. This preserves content provenance without
+persisting matched source context. An empty report becomes an explicit
+`not_found` observation. One or more findings become `found` observations, but
+neither the tool nor normalizer can declare an assertion pass or failure.
+
+The second closed protocol, `prc-adapter-syft-cyclonedx-json-v1`, accepts only
+Syft 1.51.0's reviewed non-root image digest and the scanner-owned directory
+command. The scanner injects an empty configuration at a reserved `.prc` path,
+so target `.syft.yaml` or environment defaults cannot disable catalogers or
+redirect output. The normalizer requires Syft's exact tool identity and
+CycloneDX 1.7 document envelope, rejects duplicate keys, malformed component,
+package-URL, dependency, or metadata structures, and caps the component and
+output counts.
+
+Syft generates a fresh timestamp and serial number for identical input. The
+normalizer removes those optional values and the source component's
+non-semantic `bom-ref`, then canonically orders components, properties, and
+dependencies. The resulting `application/vnd.cyclonedx+json;version=1.7`
+artifact is content-addressed and byte-for-byte deterministic for the same
+sealed inventory. When `--state-dir` is supplied, the bytes are written before
+the run that references them. A successful `value` observation proves only
+that this repository-inventory SBOM was generated; it does not claim that a
+built artifact is complete, vulnerability-free, acceptably licensed, or
+production ready.
+
+The third closed protocol, `prc-adapter-grype-json-v1`, accepts only Grype
+0.116.1's reviewed image digest, exact scanner-owned command, and enriched JSON
+report. It injects scanner-owned configuration that disables application and
+database updates, external sources, target ignores, and VEX policy. The
+container runs without network access against one explicitly supplied,
+read-only `grype-db` directory. The runner hashes and seals that directory while
+the normalizer independently requires a valid schema-v6 database, an official
+archive URL with a SHA-256 checksum, a build age no greater than 120 hours, and
+valid EPSS, KEV, and NVD provider provenance.
+
+Grype output is decoded with duplicate and unknown-field rejection and bounded
+nested records. Ignored matches, package alerts, escaping paths, unsupported
+tool or database identities, incomplete matching evidence, or unsafe numeric
+values fail the execution. The deterministic normalized artifact retains only
+the findings and provenance needed for assessment; report timestamps and bulk
+raw metadata do not affect its digest. A `not_found` observation is time-bound
+evidence for the catalog gate, while any `found` observation remains a factual
+tool result for the engine to assess.
+
+An assertion binding owns the meaning of an observation outcome. Bindings that
+omit an outcome policy retain the conservative analysis default:
+`not_found` passes and `found` fails. A binding may instead declare a nonempty
+`pass_outcomes` list and a disjoint, possibly empty `fail_outcomes` list from
+the closed `found`, `not_found`, `value`, and `unsupported` vocabulary. Any
+unconfigured outcome remains Unknown; a configured pass mixed with another
+unconfigured outcome is Conflicting. The SBOM assertion therefore treats only
+`value` as passing and has no failing tool outcome: malformed, missing,
+unsupported, partial, or contradictory output never becomes Pass.
+
+## Capability manifest
+
+Every external adapter has a strict
+[`adapter-manifest.schema.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/schemas/adapter-manifest.schema.json).
+Manifest v0.4 binds the exact protocol and output schema, compatible
+engine APIs, publisher and owner identities, immutable tool version and
+supported format versions, declared observation kinds, maintenance state, and
+known limitations. Output validation rejects an observation kind that is not
+declared by that exact manifest. The archived v0.1 through v0.3 schemas remain
+available for record interpretation but are not accepted for new execution.
+
+Trust is deliberately not self-declared by the adapter. A registry or explicit
+local operator grant must bind trust to the exact manifest digest and publisher;
+the manifest alone cannot promote itself to first-party or verified status.
+The current experimental runner deliberately supports only a narrow subset:
+
+- OCI execution through Docker or Podman;
+- an image reference pinned by a `sha256` digest and explicit registry host;
+- a private, read-only snapshot containing the regular files in the sealed
+  inventory plus any exact protocol-owned policy input described below;
+- explicitly declared, content-hashed, read-only external data directories for
+  reviewed native adapters whose immutable datasets are too large to copy into
+  each project snapshot;
+- no image pull during a scan;
+- no network;
+- no secret handles;
+- no child processes for generic JSONL adapters, with narrowly reviewed,
+  PID-bounded OS-task allowances for the pinned Gitleaks, Syft, and Grype
+  binaries;
+- an optional bounded scratch `tmpfs`; and
+- explicit wall-time, memory, CPU, process, line, message, stdin, stdout, and
+  stderr limits.
+
+Before execution, the scanner reopens and hashes every inventoried regular file
+while copying it to a private temporary snapshot. Scanner-excluded paths and
+symlinks are not copied. Protocol-owned path remapping may prevent a target file
+from changing analyzer policy without dropping its content: the Gitleaks
+protocol relocates the root `.gitleaksignore`, scans its original bytes, and
+maps any resulting location back to `.gitleaksignore`. The Syft and Grype
+protocols add only their digest-bound scanner configurations under the
+inventory-excluded `.prc` namespace. A changed type, size, or
+digest stops execution. The snapshot has a 4 GiB safety ceiling, is mounted
+read-only, and is removed after the run. Its own deterministic digest is sealed
+into the OCI plan and checked again immediately before and after the container
+runs, so observations cannot silently refer to different bytes than the
+inventory.
+
+External data is a separate trust boundary. A manifest can declare only a
+bounded named directory mounted at its reserved `/prc-inputs/NAME` path. The
+operator supplies the host directory explicitly. The scanner rejects empty,
+oversized, over-populated, symlink-containing, non-regular, missing, extra, or
+duplicate mounts; hashes every file before planning; seals the digest, file
+count, byte count, and destination into the OCI plan; and rehashes the directory
+immediately before and after execution. The durable execution records this
+content identity but never the host path. A data directory changing during a
+run is an execution error, not evidence. This mechanism does not download or
+refresh data and does not let an adapter expand its declared mounts.
+
+The generated OCI command also drops all Linux capabilities, enables
+`no-new-privileges`, uses the invoking non-root UID/GID so private snapshot
+permissions need not be broadened, disables swap beyond the memory ceiling,
+caps open files, makes the image root filesystem read-only, and removes the
+named container. The runner refuses root and Windows hosts. Timeout cleanup
+targets only the scanner-generated container name. The plan records the OCI
+client binary digest and execution stops if the plan, manifest, runtime binary,
+or bound snapshot changes after capability evaluation.
+
+An OCI runtime is a security control, not proof of perfect isolation. Operators
+must keep the runtime and host patched, review adapter images, and treat runtime
+or resource-control failure as an execution error. Podman documents that some
+rootless resource limits depend on the host cgroup configuration.
+
+## Registry lockfile and revocation
+
+[`adapter-registry.schema.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/schemas/adapter-registry.schema.json)
+defines the local registry trust root. Each entry pins the adapter ID, manifest
+SHA-256, publisher ID, registry-assigned trust, lifecycle status, and normalized
+relative manifest path. The loader hashes and validates the manifest, rejects
+publisher or lifecycle drift, rejects symlinked or escaping paths, and verifies
+current engine compatibility.
+
+`revoked` entries remain effective even when the compromised manifest has been
+removed. Default resolution permits only `first-party-sandboxed` and
+`verified-community` entries; it denies deprecated, unverified-community, and
+local entries. A manifest cannot alter these registry decisions. Detached,
+scoped Ed25519 verification is available through an explicitly selected
+[publisher trust store](publisher-trust.md). The current repository does not
+yet publish an official release trust store or signed registry, so a public
+adapter distribution channel is not yet complete.
+
+Validate and inspect a lockfile without executing anything:
+
+```bash
+prc adapter registry-validate \
+  --file /path/to/adapter-registry.yaml \
+  --format json
+```
+
+## Inspect and validate
+
+Validate the full release fixture suite without executing an adapter:
+
+```bash
+prc adapter fixture-validate \
+  --suite fixtures/adapters/fixture-suite.yaml \
+  --format json
+```
+
+The strict
+[`adapter-fixture-suite.schema.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/schemas/adapter-fixture-suite.schema.json)
+binds every transcript to the canonical digest of one exact manifest. A case
+may reduce the manifest's line, message, or stdout ceiling to exercise a
+resource failure, but it cannot increase adapter authority or resource limits.
+The runner rejects symlinks and paths outside the suite, hashes the suite and
+transcript corpus, and evaluates every case twice. It compares exact
+disposition, summary status, error class, and observation ID, kind, and
+outcome. CI fails when any expectation drifts or either evaluation differs.
+
+The resulting
+[`adapter-fixture-report.schema.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/schemas/adapter-fixture-report.schema.json)
+is release evidence for protocol compatibility only. It does not prove the
+upstream analyzer's detection accuracy, image provenance, runtime isolation,
+or suitability for the production profile. A real adapter still needs its own
+tool-specific corpus, reviewed pinned image, registry entry, publisher trust,
+and exact catalog binding.
+
+Validate a transcript without executing an adapter:
+
+```bash
+prc adapter validate-output \
+  --manifest fixtures/adapters/fixture-adapter.yaml \
+  --file fixtures/adapters/valid-output.jsonl
+```
+
+Render the exact OCI command without starting a container:
+
+```bash
+prc adapter plan-oci \
+  --manifest /path/to/pinned-adapter.yaml \
+  --target /path/to/project \
+  --runtime docker
+```
+
+Run an already-present pinned image in the bounded OCI environment and emit a
+content-addressed execution record bound to the exact manifest and inventory:
+
+```bash
+prc adapter run-oci \
+  --manifest /path/to/pinned-adapter.yaml \
+  --target /path/to/project \
+  --runtime docker
+```
+
+`--pull=never` means the command fails if the exact image is not already
+available. For a manifest that declares external data, repeat
+`--data NAME=/path/to/directory` for both `plan-oci` and `run-oci`. Current v0.3
+execution records include required `resolution` and `data_inputs` identities.
+An explicit manifest records the publisher and `local-explicit`
+operator grant; a registry resolution additionally binds the registry ID,
+revision, content digest, and registry-assigned trust. Changing any provenance
+field changes the execution ID. Version-specific v0.1 and v0.2 records remain
+valid for archived runs, but v0.1 records cannot be supplied as evidence to a
+new scan. Current run results embed these records. A scan may execute up to 16
+adapters when applicable assertions bind every exact adapter ID, manifest
+SHA-256 digest, and observation kind. Repeat `--adapter-manifest` for an
+explicit local set:
+
+```bash
+prc scan \
+  --target /path/to/project \
+  --catalog-root /path/to/trusted/catalog \
+  --mode verify-local \
+  --adapter-manifest /path/to/first-pinned-adapter.yaml \
+  --adapter-manifest /path/to/second-pinned-adapter.yaml \
+  --adapter-runtime docker
+```
+
+Scan-level data bindings use an adapter-qualified name so multi-adapter runs
+cannot consume one another's inputs:
+
+```bash
+prc scan \
+  --target /path/to/project \
+  --catalog-root /path/to/trusted/catalog \
+  --profile prc/supply-chain \
+  --mode verify-local \
+  --adapter-manifest /path/to/pinned-adapter.yaml \
+  --adapter-data 'prc.adapter.example@1.0/example-db=/path/to/database-cache'
+```
+
+For registry-assigned trust and revocation, resolve the same catalog-pinned
+adapter through a lockfile instead:
+
+```bash
+prc scan \
+  --target /path/to/project \
+  --catalog-root /path/to/trusted/catalog \
+  --mode verify-local \
+  --adapter-registry /path/to/adapter-registry.yaml \
+  --adapter-id prc.adapter.first@1.0 \
+  --adapter-id prc.adapter.second@1.0 \
+  --adapter-runtime docker
+```
+
+`--adapter-manifest` is the explicit local-operator path and is mutually
+exclusive with `--adapter-registry`. Adapter paths and IDs cannot repeat. Both
+paths still require an exact manifest digest binding in an applicable catalog
+assertion; registry approval cannot authorize a catalog-unbound adapter. The
+scanner resolves, validates, and authorizes the complete set before invoking the
+runtime, then executes the set in deterministic adapter-ID and manifest-digest
+order. When project configuration supplies a maximum duration, one shared
+deadline bounds the complete set rather than restarting the budget per adapter.
+
+The explicit mode grants only the reviewed no-network OCI capability envelope;
+authorization is checked before the OCI runtime is invoked. The adapter cannot
+declare an assertion assessment: the engine maps `found`, `not_found`,
+`unsupported`, incomplete, and conflicting observations through the catalog's
+immutable binding. The execution and each resulting evidence envelope are bound
+to the exact inventory digest. Offline execution-record import is deliberately
+unsupported because a content digest alone does not prove that a tool ran.
+
+The default `PRC-A-CORE-013` binding pins
+`prc.adapter.gitleaks@8.30` and the canonical manifest digest for
+`adapters/gitleaks-v8.30.0.yaml`. It remains Blocked in an ordinary inspect-mode
+core scan because inspect mode never launches containers. To produce executed
+evidence, an operator must first pull the exact image digest and then explicitly
+select `--mode verify-local` with the checked-in manifest. The checked-in
+protocol fixture still exercises generic JSONL plumbing in tests but is not
+authorized by the production profile.
+
+```bash
+docker pull \
+  ghcr.io/gitleaks/gitleaks@sha256:691af3c7c5a48b16f187ce3446d5f194838f91238f27270ed36eef6359a574d9
+
+prc scan \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist \
+  --mode verify-local \
+  --adapter-manifest /path/to/production-readiness-checklist/adapters/gitleaks-v8.30.0.yaml
+```
+
+The command scans only the sealed current-tree snapshot. It does not scan Git
+history, files above 10 MiB, symlink targets, archives, or recursively decoded
+content. Gitleaks rules are heuristic; both false positives and false negatives
+remain possible, so this binding is one selected analysis class rather than a
+claim of complete secret or static-analysis coverage.
+
+Normal validation and scanner-release workflows pull that exact digest and run
+the clean and suppression-resistant finding cases through the production OCI
+runner. A nonempty test-image override that differs from the reviewed digest is
+an error, not a skipped test.
+
+## Design references
+
+- [OCI content descriptors](https://specs.opencontainers.org/image-spec/descriptor/?v=v1.1.0)
+  define digest-addressed references and require retrieved content to be checked
+  against its digest.
+- [Docker container run](https://docs.docker.com/reference/cli/docker/container/run/)
+  documents read-only roots, capability removal, resource limits, and
+  `no-new-privileges`.
+- [Podman run](https://docs.podman.io/en/stable/markdown/podman-run.1.html)
+  documents the corresponding rootless container and resource controls.
+- [Gitleaks v8.30.0](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.0)
+  is the pinned upstream release; its official CLI documents directory scans,
+  JSON reports, full redaction, timeouts, and bounded target-file size.
+- [Gitleaks default configuration](https://github.com/gitleaks/gitleaks/blob/v8.30.0/config/gitleaks.toml)
+  is vendored as a deterministic gzip archive, attributed in
+  `THIRD_PARTY_NOTICES.md`, and verified in both compressed and exact
+  decompressed forms before every execution.

package/bin/docs/architecture/agent-providers.md

@@ -0,0 +1,188 @@
+# Read-only agent providers
+
+The experimental provider layer connects the scanner to installed Codex and
+Claude Code CLIs without giving either provider authority over scanner truth.
+The local CLI binary and remote provider are still trusted process and data
+processing dependencies. The current mode is deliberately `suggest`: an agent receives only content-addressed
+copies of declared relevant text files and returns a schema-constrained patch
+proposal. It cannot inspect the source workspace, edit files, run shell commands,
+use web or MCP tools, change capabilities, or mark an assertion as passed.
+
+The implementation follows the current official documentation for [Codex
+non-interactive mode](https://developers.openai.com/codex/noninteractive/),
+[Codex sandboxing](https://developers.openai.com/codex/sandboxing/), [Claude Code
+headless mode](https://code.claude.com/docs/en/headless), and [Claude Code
+permissions](https://code.claude.com/docs/en/permissions). Provider flags are
+also covered by golden launch-plan tests so an accidental dangerous flag fails
+review.
+
+## Capability boundary
+
+Both launch plans require:
+
+- a content-addressed `prc.agent-task/v0.2` task bound to one canonical finding
+  ID and stable fingerprint;
+- explicit acknowledgement that relevant source may be processed by a remote
+  provider;
+- an exact workspace inventory plus bounded, content-addressed task inputs;
+- a fail-closed preflight that prevents obvious private keys, distinctive
+  provider-token shapes, and credential-bearing URLs from entering a remote
+  task without logging the matched value;
+- a private execution/output directory disjoint from the source workspace;
+- denied agent-tool network access and no task secrets;
+- schema-constrained, non-interactive output;
+- scanner-enforced time and output limits;
+- executable and output-schema digests rechecked immediately before execution;
+  and
+- filtered process environments that exclude unrelated credentials such as
+  cloud, repository, and deployment tokens.
+
+The scanner can reuse only a login created by `prc login codex` or `prc login claude`.
+Those commands call the provider's official authentication flow with a private
+scanner credential directory. They do not reuse the provider's normal user
+configuration, sessions, instructions, plugins, hooks, or MCP servers. Supported
+API-key environment variables remain an alternative. Each scan still gets a
+new private home; only the selected credential, basic runtime variables, and
+scanner-owned overrides reach the process.
+
+Codex runs from the private output directory with ignored user configuration,
+strict configuration, ephemeral sessions, the read-only sandbox, approval policy
+`never`, no inherited shell environment, and the default shell tool disabled.
+Hosted web search, MCP, multi-agent, goal, remote-plugin, app, browser,
+computer-use, and image-generation features are also disabled. Claude Code runs
+from the same isolated directory with an empty tool allowlist; Bash, reading,
+editing, writing, notebook editing, web tools, slash commands, ambient MCP
+servers, project setting sources, and session persistence are disabled. The
+source text needed for either provider is inside the sealed task prompt. Claude's
+optional provider-side cost limit is passed through; the current Codex CLI
+adapter rejects a nonzero cost limit because it cannot enforce one.
+
+These command flags cannot contain a malicious local executable. A replaced or
+compromised `codex` or `claude` program runs as the current operating-system
+user and could ignore every argument before the scanner detects the changed
+digest. Install the CLI from its official source, keep it updated, inspect the
+resolved path and digest with `prc doctor`, and use a separate OS account or
+strong external sandbox when the host contains secrets the CLI must never see.
+The scanner also stops when it can see local Claude managed settings that may
+force hooks, plugins, or MCP configuration, but it cannot inspect every policy
+delivered by a provider server.
+
+Repository text is always untrusted data, including comments that resemble
+instructions or the scanner's task delimiter. The scanner JSON-encodes the
+entire content-addressed task, so delimiter characters inside a source file are
+escaped and cannot terminate the authoritative envelope. Checked-in adversarial
+tests reconstruct that envelope and require the hostile fixture to round-trip
+only as an input value. This is defense in depth: output schema validation,
+capability denial, patch-path validation, and independent candidate checks remain
+mandatory even when the prompt boundary is intact. These controls implement the
+OWASP guidance to [identify external content, constrain privileges, validate
+outputs, and test adversarially](https://genai.owasp.org/llmrisk/llm01-prompt-injection/).
+
+These controls are not an R2 write sandbox. Neither provider may mutate a
+candidate workspace. An agent proposal remains untrusted data. The
+scanner-owned [`remediate-proposal`](../scanner/remediation.md#apply-one-validated-r2-proposal)
+path can explicitly parse one validated proposal into a fresh isolated
+candidate and run deterministic acceptance checks; the provider does not apply
+or approve that result. The bounded `prc fix --provider` path composes those
+same two stages only for a scanner-planned missing-test task.
+
+## Create and seal a task
+
+Start from the checked-in
+[`fixtures/providers/suggest-task.json`](https://github.com/MarinJursic/production-readiness-checklist/blob/main/fixtures/providers/suggest-task.json)
+example.
+For a draft, leave `task_id` empty, keep arrays sorted, tailor the goal and path
+allowlists, and make the remote-processing decision explicit. Seal it without
+modifying the draft:
+
+```bash
+./prc provider seal-task \
+  --file /path/to/draft-task.json \
+  --workspace /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  > /safe/path/task.json
+```
+
+Sealing reads only the sorted `relevant_paths`, rejects non-regular, binary, or
+larger-than-256-KiB inputs, and embeds their text and SHA-256 digests. Total input
+text is limited to 768 KiB. Before remote processing, sealing also rejects
+high-confidence secret-like input without including the matched material in the
+error. This conservative guard is not a comprehensive repository secret scan;
+it covers selected high-precision generic and provider credential families
+recognized by [GitHub's supported secret-scanning pattern
+catalog](https://docs.github.com/en/code-security/reference/secret-security/supported-secret-scanning-patterns),
+and projects should still run a dedicated secret scanner. Sealing also binds the
+current workspace inventory digest into the task. The task's `finding_id` names the exact scan finding that caused
+the task to be created; both it and `finding_fingerprint` are revalidated
+against a fresh baseline before a proposal can be applied. For a manual draft,
+copy both values from the same canonical finding in a current JSON scan; the
+bounded loop does this automatically. When configured, that inventory includes
+the declared-scope digest, and the scanner merges its default guards, configured
+protected paths, and the in-target configuration path into the sealed task.
+Changing a task field, finding binding, configuration declaration, or any
+inventoried workspace file invalidates the execution plan.
+
+## Inspect a launch plan
+
+Create a new output directory outside the workspace, then inspect the exact
+executable identity, arguments, environment names, schema identity, and
+capabilities before any provider call:
+
+```bash
+install -d -m 700 /safe/path/provider-output
+export OPENAI_API_KEY='your-provider-key'
+
+./prc provider plan \
+  --provider codex \
+  --task /safe/path/task.json \
+  --workspace /path/to/project \
+  --output-dir /safe/path/provider-output
+```
+
+Use `--provider claude` for Claude Code. `provider capabilities` reports the
+static envelope for either adapter.
+
+## Run explicitly
+
+`provider run` invokes the installed provider and can consume provider quota or
+incur provider charges. It should be called only after the operator reviews the
+task's remote-source acknowledgement and launch plan.
+
+```bash
+./prc provider run \
+  --provider codex \
+  --task /safe/path/task.json \
+  --workspace /path/to/project \
+  --output-dir /safe/path/provider-output
+```
+
+The scanner writes raw standard output and diagnostics as mode-`0600` transcript
+files in the output directory, records their byte counts and SHA-256 digests,
+and emits a `prc.agent-execution/v0.1` record after valid output. A failed
+invocation instead returns a content-addressed `prc.agent-failure/v0.1` record
+with scanner-authored stage and reason codes plus complete or partial transcript
+metadata. Treat transcripts as sensitive source-derived evidence.
+
+## Validate without running
+
+Golden and adversarial provider outputs can be checked independently:
+
+```bash
+./prc provider validate-output \
+  --provider codex \
+  --task fixtures/providers/suggest-task.json \
+  --file fixtures/providers/valid-output.json
+```
+
+Validation rejects prose-only responses, duplicate JSON keys, task mismatches,
+unsorted or duplicate files, changes outside the allowlist, protected paths,
+reported command execution, requested capability expansion, trailing JSON, and
+oversized output. Claude's outer JSON envelope must contain a non-error
+`structured_output` value that passes the same validation.
+
+After validation, follow the [isolated R2 proposal](../scanner/remediation.md#apply-one-validated-r2-proposal)
+workflow when the task's assertion is R2. `provider run` itself never applies a
+proposal. The optional [bounded R2 loop](../scanner/remediation.md#opt-in-to-one-scanner-planned-r2-task)
+constructs and seals its own narrow task, invokes the same read-only provider
+protocol, and hands valid output to the isolated scanner-owned application
+path. A proposal is never applied to the source workspace.

package/bin/docs/architecture/applicability.md

@@ -0,0 +1,80 @@
+# Bounded applicability evaluation
+
+Applicability decides whether an assertion belongs in a specific assessment. It
+does not decide whether the assertion passes. The scanner evaluates catalog
+applicability with Common Expression Language (CEL) and records the outcome,
+evaluator identity, and reason in the immutable scan plan.
+
+## Fail-closed contract
+
+Every expression must compile, evaluate within the configured resource budget,
+and return a Boolean. The result mapping is deliberately small:
+
+| CEL outcome | Planned applicability |
+| --- | --- |
+| `true` | `applicable` |
+| `false` | `not_applicable` |
+| Compile error, missing field, non-Boolean result, or evaluation error | `undetermined` |
+| Parser, recursion, expression-size, or runtime-cost limit reached | `undetermined` |
+
+`undetermined` never becomes Not Applicable or Pass. A required assertion with
+undetermined applicability keeps the assessment incomplete.
+
+Plan v0.3 records `applicability_reason` for every planned assertion and
+identifies the evaluator as `cel-go/v0.30.0+prc-inventory/v0.3`. Version-specific
+v0.1 through v0.6 plan schemas remain available for validating archived plans.
+
+## Available inventory view
+
+Expressions receive only a deterministic projection named `inventory`. Target
+file bytes, the target root path, environment variables, credentials, and
+process or network capabilities are not exposed.
+
+The projection contains:
+
+- `file_count` and `source_files`;
+- `package_ecosystems`, `manifests`, `lock_files`, `container_files`, and
+  `symlinks`;
+- `ci.github_actions` and `ci.workflow_files`;
+- `infrastructure.terraform_files` and
+  `infrastructure.kubernetes_files`;
+- `components`, limited to component ID, kind, path, and ecosystem; and
+- `fact_values`, mapping sourced inventory fact keys to their string values; and
+- `declared`, containing the bound project ID, risk profile, profile, release
+  scope, features, and data-context tags, or `configured: false` when absent.
+
+Examples:
+
+```text
+inventory.package_ecosystems.size() > 0
+inventory.ci.github_actions == true
+inventory.components.exists(c, c.kind == "container-build")
+inventory.components.exists(c, c.kind == "api-description" && c.ecosystem == "openapi")
+```
+
+Inventory detection remains evidence with stated limitations. An expression can
+select assertions using detected facts; it cannot turn those facts into proof of
+runtime behavior or deployment state.
+
+## Resource and capability boundary
+
+CEL is used as a non-Turing-complete, side-effect-free expression evaluator. The
+scanner additionally limits an expression to 4,096 source characters, parser
+recursion depth 64, and 10,000 runtime cost units, with periodic interruption
+checks. Compiled programs are cached by exact expression for deterministic,
+concurrent reuse.
+
+No custom functions perform file, process, network, clock, random, or environment
+access. Catalog authors cannot use applicability to execute a target project or
+an adapter. Applicability expressions should be short predicates over the
+documented projection; assertion implementations remain responsible for
+collecting and evaluating evidence.
+
+## Design references
+
+- The [CEL project](https://github.com/cel-expr/cel-go) describes CEL as a
+  non-Turing-complete, type-checkable, side-effect-free expression language and
+  documents program reuse.
+- The [cel-go API](https://pkg.go.dev/github.com/google/cel-go/cel) documents
+  parser recursion and expression-size limits, runtime cost limits, and
+  interruption checks used by this implementation.