@marinjursic/prc-darwin-arm64 0.1.0

package/bin/docs/scanner/core-repository.md

@@ -0,0 +1,62 @@
+<!-- Generated by scripts/catalog.py. Do not edit directly. -->
+
+# Core repository readiness
+
+Profile: `prc/core-repository@1.0`
+
+Deterministic repository governance, documentation, workflow, dependency, security, API-contract, and test foundations.
+
+This pilot demonstrates the structured control-to-assertion model. A listed
+assertion is not a claim that the scanner implementation exists unless its
+implementation is present and verified by the scanner test suite.
+
+## Assertions
+
+| Assertion | Objective | Severity | Gate | Evidence | Remediation |
+| --- | --- | --- | --- | --- | --- |
+| `PRC-A-CORE-001` — README is present | [USEQ-FDCA6C71](../engineering/05-code-quality-and-implementation.md) | medium | required | repository-file | R2 |
+| `PRC-A-CORE-002` — License is present | [USEQ-6497B434](../engineering/16-specialized-domains-and-release-assurance.md) | medium | required | repository-file | R0 |
+| `PRC-A-CORE-003` — Contribution guidance is present | [USEQ-89F5E97A](../engineering/16-specialized-domains-and-release-assurance.md) | low | advisory | repository-file | R0 |
+| `PRC-A-CORE-004` — Security policy is present | [USEQ-AC6AC548](../engineering/16-specialized-domains-and-release-assurance.md) | medium | required | repository-file | R0 |
+| `PRC-A-CORE-005` — Code of conduct is present | [USEQ-D73106BF](../engineering/16-specialized-domains-and-release-assurance.md) | low | advisory | repository-file | R0 |
+| `PRC-A-CORE-006` — Code ownership is declared | [USEQ-CA602113](../engineering/05-code-quality-and-implementation.md) | medium | required | repository-file | R0 |
+| `PRC-A-CORE-007` — Dependency resolution is reproducible | [USEQ-D1076D92](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | repository-file | R2 |
+| `PRC-A-CORE-008` — GitHub Actions use immutable references | [USEQ-F4D6E3B3](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | workflow-parse | R2 |
+| `PRC-A-CORE-009` — Continuous integration is configured | [USEQ-12655775](../engineering/05-code-quality-and-implementation.md) | medium | required | repository-file | R2 |
+| `PRC-A-CORE-010` — Automated tests are discoverable | [USEQ-12655775](../engineering/05-code-quality-and-implementation.md) | high | required | repository-structure | R2 |
+| `PRC-A-CORE-011` — Workflow permissions are explicit | [USEQ-73488048](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | workflow-parse | R2 |
+| `PRC-A-CORE-012` — Generated code follows normal review controls | [USEQ-F0F5ACE7](../engineering/05-code-quality-and-implementation.md) | high | required | reviewer-attestation | R0 |
+| `PRC-A-CORE-013` — Configured secret detection has executed | [USEQ-70E9D5AA](../engineering/10-verification-and-testing.md) | high | required | analysis-result | R2 |
+| `PRC-A-CORE-014` — Source files end with a newline | [USEQ-DAF77C8F](../engineering/05-code-quality-and-implementation.md) | low | advisory | source-format | R1 |
+| `PRC-A-CORE-015` — Source revision is identifiable | [USEQ-72088469](../engineering/01-governance-and-foundations.md) | medium | required | repository-identity | R0 |
+| `PRC-A-CORE-016` — Dependency updates are configured | [PRC-36-011](../checklists/08-maintenance-vendors-compliance.md) | medium | advisory | repository-file | R2 |
+| `PRC-A-CORE-017` — Workflow definitions parse | [USEQ-F4D6E3B3](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | workflow-parse | R2 |
+| `PRC-A-CORE-018` — Workflows define executable jobs | [USEQ-12655775](../engineering/05-code-quality-and-implementation.md) | high | required | workflow-parse | R2 |
+| `PRC-A-CORE-019` — Workflow jobs have bounded runtimes | [USEQ-B66A3064](../engineering/11-developer-experience-platform-and-delivery.md) | medium | required | workflow-parse | R2 |
+| `PRC-A-CORE-020` — pull_request_target workflows receive security review | [USEQ-73488048](../engineering/11-developer-experience-platform-and-delivery.md) | critical | required | workflow-parse | R0 |
+| `PRC-A-CORE-021` — Unresolved merge conflicts are absent | [USEQ-12655775](../engineering/05-code-quality-and-implementation.md) | high | no-go | source-integrity | R2 |
+| `PRC-A-CORE-022` — Repository files are not broadly writable | [USEQ-D60E6950](../engineering/11-developer-experience-platform-and-delivery.md) | medium | advisory | repository-metadata | R1 |
+| `PRC-A-CORE-023` — Dependency manifests are nonempty | [USEQ-D1076D92](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | repository-file | R2 |
+| `PRC-A-CORE-024` — Dependency locks are nonempty | [USEQ-D1076D92](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | repository-file | R2 |
+| `PRC-A-CORE-025` — Runtime versions are declared | [USEQ-0B7FDB5F](../engineering/05-code-quality-and-implementation.md) | medium | required | runtime-declaration | R2 |
+| `PRC-A-CORE-026` — Container base images are immutable | [USEQ-7D4DA192](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | containerfile-parse | R2 |
+| `PRC-A-CORE-027` — Final container stages declare a non-root user | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | containerfile-parse | R2 |
+| `PRC-A-CORE-028` — Terraform provider selections are locked | [USEQ-D1076D92](../engineering/11-developer-experience-platform-and-delivery.md) | medium | advisory | repository-file | R2 |
+| `PRC-A-CORE-029` — Kubernetes workloads require non-root containers | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | kubernetes-parse | R2 |
+| `PRC-A-CORE-030` — Kubernetes containers declare resource policy | [USEQ-13CBD6C6](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | kubernetes-parse | R2 |
+| `PRC-A-K8S-001` — Kubernetes workloads avoid privileged host access | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | kubernetes-parse | R2 |
+| `PRC-A-K8S-002` — Kubernetes Linux containers disable privilege escalation | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | kubernetes-parse | R2 |
+| `PRC-A-K8S-003` — Kubernetes Linux containers restrict capabilities | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | high | required | kubernetes-parse | R2 |
+| `PRC-A-K8S-004` — Kubernetes Linux containers use bounded seccomp profiles | [USEQ-A3559C64](../engineering/16-specialized-domains-and-release-assurance.md) | medium | required | kubernetes-parse | R2 |
+| `PRC-A-CORE-031` — Private-key armor is absent from repository files | [USEQ-E85957E3](../engineering/08-security-and-cryptography.md) | critical | no-go | sensitive-material-scan | R2 |
+| `PRC-A-GO-001` — Go net/http package helpers do not use the default client | [USEQ-F6ACEF15](../engineering/06-application-services-and-apis.md) | high | required | go-ast-analysis | R2 |
+| `PRC-A-GO-002` — Go HTTP servers use configurable Server instances | [USEQ-B66A3064](../engineering/11-developer-experience-platform-and-delivery.md) | high | required | go-ast-analysis | R2 |
+| `PRC-A-API-001` — OpenAPI documents expose required root metadata | [USEQ-13208C54](../engineering/06-application-services-and-apis.md) | medium | required | openapi-parse | R2 |
+| `PRC-A-API-002` — OpenAPI operations define valid responses | [USEQ-13208C54](../engineering/06-application-services-and-apis.md) | high | required | openapi-parse | R2 |
+| `PRC-A-API-003` — Declared OpenAPI operation IDs are unique | [USEQ-13208C54](../engineering/06-application-services-and-apis.md) | medium | required | openapi-parse | R2 |
+
+## Result interpretation
+
+The profile is satisfied only when every applicable required assertion has
+current passing evidence and no configured gate blocks the result. Manual or
+external evidence remains visible and cannot be inferred from repository files.

package/bin/docs/scanner/diff-and-invalidation.md

@@ -0,0 +1,79 @@
+# Diff-aware evidence invalidation
+
+`prc diff` compares a canonical prior run with a freshly inventoried target and
+answers a narrower question than `scan`: which prior conclusions had relevant
+inputs changed?
+
+```bash
+./prc diff \
+  --state-dir /safe/local/path/prc-state \
+  --base-run <run-id> \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist
+```
+
+Use `--format json` for `prc.invalidation/v0.1`. The report includes changed
+files and inventory dimensions, one decision for each prior or current
+assertion, stable reason codes, and aggregate counts.
+
+## What the decisions mean
+
+| Conclusion | Meaning | Can the old result be returned as current? |
+| --- | --- | --- |
+| `invalidated` | A rule, applicability outcome, relevant repository input, declared scope, or evidence-freshness condition changed. | No. |
+| `unchanged_inputs` | The implementation-specific inputs did not change. | Only when `reuse_allowed` is also true. |
+| `new` | The current profile newly includes the assertion. | No. |
+| `removed` | The current profile no longer includes the assertion. | No current evaluation is requested. |
+
+The scanner deliberately distinguishes input equivalence from evidence reuse.
+Repository evidence is bound to the complete inventory digest. If an unrelated
+file changes, an assertion may be `unchanged_inputs` while `reuse_allowed` is
+false and `fresh_evaluation_required` is true: its old evidence still names the
+old target. `prc diff` does not manufacture a new evidence envelope or relabel a
+prior Pass.
+
+Reuse is permitted only when the current inventory and plan identities exactly
+match the base run and no rule requires fresh non-repository evidence. Manual,
+executed, artifact, and environment evidence is not carried forward without a
+separate validity-window policy.
+
+## Bound rule identity
+
+Plans produced as `prc.plan/v0.6` bind:
+
+- the scanner engine contract;
+- the exact governing catalog, including every parsed objective, assertion, and profile;
+- the exact profile definition;
+- every assertion revision and complete definition, including parameters;
+- the implementation identifier and applicability evaluator;
+- project configuration, artifacts, and target environments;
+- the selected execution mode, capability policy, implementation registry, and
+  dependency DAG; and
+- the complete inventory identity.
+
+Each definition is represented by a SHA-256 digest over its canonical JSON
+representation. A changed objective statement or assertion parameter therefore
+invalidates the old conclusion even if its implementation name is unchanged.
+
+Runs recorded with an older plan schema remain readable, but they lack one or
+more rule bindings. Their assertions receive
+`base_plan_lacks_rule_binding` and require a fresh evaluation. This is a
+conservative migration rule, not a claim that the earlier result was wrong.
+
+## Native dependency map
+
+The versioned invalidation rules map each native implementation to the inputs it
+actually reads. Examples include candidate document paths for `file-present`,
+all workflow definitions for workflow parsers, source files for final-newline,
+manifest and lock sets for dependency checks, container definitions for
+container checks, and Terraform/Kubernetes resources for infrastructure checks.
+
+Unknown implementations default to all repository files. That may perform more
+fresh work than necessary, but it cannot preserve a stale Pass due to an
+unrecognized dependency. Adapter and manual-evidence assertions also require
+freshness proof instead of being inferred from a filename diff.
+
+`prc diff` is an analysis and planning command. `prc scan` still evaluates the
+current target afresh; automatic cache reuse is intentionally deferred until a
+future evidence-rebinding protocol can preserve subject identity and validity
+without weakening the trust model.

package/bin/docs/scanner/doctor.md

@@ -0,0 +1,71 @@
+# Diagnose scanner capabilities
+
+`prc doctor` checks whether the local host can perform the scanner operations
+you intend to use. It does not execute project code, containers, Codex, or Claude
+Code. Requested executable capabilities are resolved, identity-checked, and
+hashed without being launched.
+
+## Check read-only scanning
+
+```bash
+./prc doctor \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist
+```
+
+Target inventory and catalog validation are required. State storage, candidate
+workspaces, an OCI runtime, and agent providers are reported as optional warnings
+unless their corresponding flags are supplied.
+
+## Probe state and remediation filesystems
+
+Create the state directory with private permissions before probing it:
+
+```bash
+mkdir -m 0700 /safe/path/prc-state
+
+./prc doctor \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist \
+  --state-dir /safe/path/prc-state \
+  --candidate-parent /safe/path/candidates
+```
+
+The state probe verifies private-directory enforcement and the hard-link
+publication primitive used for immutable evidence records. The candidate probe
+creates a private temporary sibling directory, verifies that it is disjoint from
+the target, and tests file creation and mode enforcement. Probe directories are
+removed before the command returns.
+
+Do not place `--candidate-parent` inside the target. An ancestor such as a shared
+temporary root is allowed only when the actual private probe directory is a
+disjoint sibling of the target.
+
+## Inspect optional executables
+
+```bash
+./prc doctor \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist \
+  --oci-runtime docker \
+  --provider codex \
+  --provider claude
+```
+
+The OCI executable must resolve to `docker` or `podman`. Provider executables
+must resolve to `codex` or `claude`. A matching filename is not treated as trust:
+the report records the resolved path and SHA-256 digest so execution planning can
+bind the exact binary later. Doctor does not test authentication, make network
+requests, pull images, or prove that a daemon is running.
+
+## Automation output
+
+```bash
+./prc doctor --target . --catalog-root . --format json > doctor.json
+python scripts/validate_instance.py doctor.schema.json doctor.json
+```
+
+JSON conforms to `prc.doctor/v0.1`. Each check is `pass`, `warn`, or `fail` and
+states whether it is required. The command exits `0` when all requested required
+capabilities pass and `2` when at least one required capability fails. Warnings
+never silently claim that an untested optional capability is available.

package/bin/docs/scanner/getting-started.md

@@ -0,0 +1,355 @@
+# Scanner quick start
+
+The scanner CLI inventories a repository, creates an immutable plan, evaluates
+native assertions, records evidence, and reports explicit unresolved states.
+It also binds all 10,042 registered controls into every complete scan report.
+The narrow assertions do not overclaim that they proved a whole broad control.
+
+Choose one clear level:
+
+```bash
+./prc quick /path/to/project       # 18 high-signal local checks
+./prc scan /path/to/project        # 40 core local checks
+./prc full codex /path/to/project  # core scan plus advisory AI review of all controls
+```
+
+Use any command without a path to scan the current directory. `prc full claude`
+selects Claude Code instead. The commands do not fix files or execute project
+code. They print a summary and create a private, standalone HTML report outside
+the target. Open the exact path printed as `Detailed report:` to review verified
+findings and every incomplete or manual result. `quick` still includes every
+control in that report; it only runs fewer local assertions.
+
+The profile evaluator can consume a live, sandboxed adapter execution only when
+the selected profile binds its exact ID, manifest digest, and observation kind.
+The generated-code review remains manual. The default analysis-evidence
+assertion pins the reviewed Gitleaks 8.30.0 current-tree adapter, but remains
+blocked in ordinary inspect mode; an operator must explicitly select
+`--mode verify-local`, supply the checked-in manifest, and pre-pull its immutable
+image. The [adapter contract](../architecture/adapters.md) documents the exact
+command and important coverage limitations.
+One deterministic R1 remediation is available for recognized source files that
+lack a final line-feed byte, and another restricts broadly writable file modes.
+The bounded `fix` loop can compose those repairs in isolated sibling candidates
+without editing the target.
+
+## One-time setup
+
+### npm release package
+
+After a scanner release is published to npm, the normal short path is:
+
+```bash
+npm install -D @marinjursic/prc
+npx prc quick
+```
+
+Use `npx prc scan` for the core local scan.
+
+The npm launcher has no install hooks or third-party JavaScript dependencies.
+It uses one exact native platform package and never downloads a fallback. The
+public package names were not yet published when this guide was updated, so
+check the scanner release notes before using the registry command.
+
+For a pinned install with dependency hooks disabled, use
+`npm install -D -E --ignore-scripts --no-audit --no-fund @marinjursic/prc@X.Y.Z`,
+then `npm exec --offline --no -- prc scan`. To give a Node project one short
+repeatable command, add `"scan": "prc scan"` to `package.json`, then run
+`npm run scan`. Use `npm run --ignore-scripts scan` to skip local `prescan` and
+`postscan` hooks. npm does not let a project add a custom top-level `npm scan`
+command.
+
+### Build from source
+
+Go 1.27 or a compatible later supported toolchain is required.
+
+```bash
+go mod verify
+go build -trimpath -o prc ./cmd/prc
+./prc version
+```
+
+Run these commands from the Production Readiness Checklist repository. The
+binary automatically discovers the compatible `catalog/` in the current
+directory or beside the executable. Keep release-archive files together when
+moving the binary. If `go` is not found, install the supported Go toolchain and
+open a new shell so its binary directory is on `PATH`.
+
+Add the entire extracted or cloned scanner directory to `PATH` when you want to
+run `prc` without `./`; moving only the executable separates it from its
+compatible catalog. For a current macOS or Linux shell:
+
+```bash
+export PATH="/absolute/path/to/production-readiness-checklist:$PATH"
+```
+
+`prc version --format json` reports the scanner version, exact source revision,
+reproducible source timestamp, and Go toolchain embedded in a release build.
+Downloadable scanner releases use a separate `scanner-vX.Y.Z` tag namespace and
+bundle the compatible catalog, adapter manifests, packs, schemas, and scanner
+guides with every binary. See
+[releases and verification](releases.md) before trusting a downloaded artifact.
+
+The native CLI stays language-neutral and remains available without Node.
+
+## Inventory without executing target code
+
+```bash
+./prc inventory --target /path/to/project
+```
+
+The inventory walks regular files without following symlinks or executing project
+commands. Inventory v0.3 records content digests plus a deterministic component
+graph and sourced, confidence-bearing facts for package manifests, CI workflows,
+container build definitions, Terraform, Kubernetes, OpenAPI descriptions, and
+symlinks. Detection is
+not proof that a component is built or deployed; each fact states that limitation.
+When a validated project configuration is supplied, its digest, declared scope,
+and explicitly limited facts are bound into the inventory identity. Versioned
+v0.1, v0.2, and v0.3 schema files remain available for consumers of pinned
+output contracts; only the unversioned alias advances with a later contract.
+
+Before enabling persistent evidence, OCI adapters, or isolated remediation, run
+[`prc doctor`](doctor.md) with the corresponding paths and executables. It probes
+only explicitly requested host capabilities and never launches target code,
+containers, or agent providers.
+
+## Create a deterministic plan
+
+Optionally validate or export the exact catalog first:
+
+```bash
+./prc catalog validate --catalog-root /path/to/production-readiness-checklist
+./prc catalog bundle --catalog-root /path/to/production-readiness-checklist > catalog-bundle.json
+```
+
+The manifest and bundle are deterministic and contain no local path or timestamp.
+They identify validated definitions; release signing is a separate trust step.
+
+The scanner normally discovers its bundled catalog. Pass `--catalog-root` only
+when intentionally testing a different local catalog:
+
+```bash
+./prc plan \
+  --catalog-root /path/to/production-readiness-checklist \
+  --target /path/to/project \
+  --config /path/to/project/production-readiness.yaml \
+  --profile prc/core-repository
+```
+
+The same target inventory, profile, catalog, and execution mode produce the same
+plan digest. Plan v0.6 binds the full governing catalog, exact profile and
+assertion definitions, bounded CEL evaluator, an applicability reason for every
+assertion, configuration digest, declared project ID, artifact digests, target
+environments, implementation registry, capability envelope, and dependency
+DAG. `inspect` is the default and denies external processes, writable scratch,
+network, and secrets. Use `--mode verify-local` only when reviewing a plan that
+contains an authorized no-network OCI adapter. Invalid, unavailable,
+non-Boolean, or resource-exhausting expressions become `undetermined`; they
+never silently become Not Applicable. See
+[bounded applicability evaluation](../architecture/applicability.md) for the
+available inventory fields and limits.
+
+## Scan and read the report
+
+```bash
+./prc scan /path/to/project
+```
+
+Options may appear before or after the project path. The default report is
+created with mode `0600` under the operating system's user cache directory and
+is never written inside the target. Its name includes the target and run ID.
+It contains:
+
+- all 10,042 registered controls and an honest disposition for each one;
+- a plain-language split between verified problems, narrow passes, unresolved
+  local checks, manual decisions, controls needing evidence, and AI advice;
+- every verified finding with severity, gate, controls, locations, evidence,
+  remediation class, finding ID, and stable fingerprint; and
+- every assertion result with applicability, execution state, required
+  evidence, observed evidence, and locations.
+
+The scanner creates report files with exclusive creation and will not overwrite
+an existing path. Use `--report /safe/path/readiness.html` to choose a new path,
+or `--no-report` to explicitly suppress the default HTML report.
+
+`prc scan` has no code path to the remediation commands. A missing final newline
+or broad file mode may appear as a finding, but the target bytes and modes remain
+unchanged. `prc fix` is a separate, explicitly invoked candidate workflow.
+
+## Optional Codex or Claude review
+
+A normal scan does not contact an AI provider. Use the provider's official CLI
+sign-in flow once, then start the review with one short option:
+
+```bash
+prc login codex
+prc full codex
+```
+
+Replace `codex` with `claude` for Claude Code. `prc auth` shows whether each
+private scanner login is ready, and `prc logout codex` or `prc logout claude`
+removes it. A supported API-key environment variable remains an alternative.
+
+Remove `--review-control` to review every active control. The coordinator is
+required to assign each control to a separate subagent inside a sealed batch.
+Completed batches resume from private state outside the target. This full run can take a long time and use many
+tokens. The provider receives bounded, secret-screened excerpts but no target
+workspace path or source-reading, shell, write, install, web, browser, or MCP
+tools. Its result stays advisory and never turns a control into a verified
+Pass. A cited path and line are checked against the exact screened snapshot,
+but the claim remains `advisory_unverified` because a real line does not prove
+the AI understood it. `prc full` and `--ai` are also explicit permission to send
+those screened excerpts to the remote provider. Read [safe AI control review](ai-control-review.md) for
+one-control testing, cost warnings, result meanings, and stop conditions.
+
+## Preserve evidence and history
+
+```bash
+mkdir -m 0700 /safe/path/prc-state
+
+./prc scan \
+  --target /path/to/project \
+  --profile prc/core-repository \
+  --state-dir /safe/path/prc-state
+```
+
+`--state-dir` is optional. When supplied, evidence envelopes and complete runs
+are stored by digest, then indexed transactionally in an embedded SQLite
+database. The state root must be private and local; do not put it inside the
+target unless target-local scanner state is intentional. See
+[durable state and history](state-and-history.md) for the storage contract and
+`history` commands.
+
+After a later change, use [`prc diff`](diff-and-invalidation.md) with a canonical
+base run to see exactly which rule inputs were invalidated before rescanning.
+
+JSON is available for automation:
+
+```bash
+./prc scan . --format json --exit-policy never
+```
+
+Explicit machine formats write to stdout and do not also create the default HTML
+file. Add `--report /safe/path/readiness.html` when both forms are wanted.
+
+To let Codex, Claude Code, or another local agent request the same read-only
+plans, scans, and assertion explanations, use the
+[path-locked MCP server](mcp-agent-integration.md). It deliberately exposes no
+write, remediation, provider, adapter, process, network, or state tool.
+
+The same scan can emit a scoped Markdown report, self-contained accessible HTML,
+SARIF 2.1.0 failed findings, or JUnit XML with failures, execution errors, and
+manual/not-applicable skips kept distinct:
+
+```bash
+./prc scan . --format markdown --exit-policy never
+./prc scan . --format html --exit-policy never
+./prc scan . --format sarif --exit-policy never
+./prc scan . --format junit --exit-policy never
+```
+
+SARIF intentionally contains only failed assertions that can be represented as
+canonical, fingerprinted findings. Unknown, blocked, manual, and not-applicable
+results remain in the canonical JSON, Markdown, HTML, and JUnit reports instead
+of being mislabeled as source findings. Run v0.9 adds bounded source locations
+to assertion results so native analyses can feed exact file, line, and column
+data into canonical findings. It keeps a stable finding fingerprint separate
+from the content-addressed finding ID and embeds the reviewable v0.6 execution
+plan. Adapter executions bind their local or registry authorization provenance.
+Versioned run v0.1 through v0.8, plan v0.1 through v0.6, inventory v0.1
+through v0.3, adapter-execution v0.1 through v0.2, evidence v0.1, and finding
+v0.1 schemas remain available for archived consumers. Adapter-manifest v0.1
+through v0.3 are likewise frozen while v0.4 is the current executable contract.
+Their local dependency graphs use versioned filenames, so later unversioned
+aliases cannot change an archived contract.
+
+`--exit-policy profile` is the default and uses the [stable CLI exit-code
+contract](cli-contract.md): a failed active gate is `1`, while incomplete,
+blocked, or manual evidence is `2`. `no-go` never hides incomplete execution.
+`never` is an explicit report-generation override that returns `0` after a
+completed scan but does not change the terminal state in the report; do not use
+it as a release gate.
+
+## Fix eligible deterministic findings
+
+```bash
+./prc fix \
+  --target /path/to/project \
+  --catalog-root /path/to/production-readiness-checklist \
+  --candidate-root /safe/path/prc-remediation-run \
+  --format json
+```
+
+The command creates a new candidate per accepted R1 fix and rescans from fresh
+evidence after every attempt. It returns success only when the selected profile
+is satisfied. Read [bounded isolated remediation](remediation.md) for budgets,
+configuration policy, terminal states, and the machine-work-complete report.
+
+## Explain an assertion
+
+```bash
+./prc explain --catalog-root . PRC-A-CORE-008
+```
+
+## Current native checks
+
+- repository governance files and an immutable Git source identity;
+- detected dependency manifests, nonempty lock inputs, update configuration,
+  and runtime-version declarations;
+- GitHub Actions syntax, jobs, bounded runtimes, permissions, immutable action
+  references, and unsafe untrusted triggers;
+- discoverable tests, final line-feed bytes, merge-conflict markers, broad
+  file-write permissions, and committed private-key armor;
+- direct Go `net/http` package helpers backed by mutable global
+  `http.DefaultClient` state;
+- immutable container base identities and final-stage non-root users;
+- Terraform provider locks; and
+- Kubernetes non-root and container resource policies.
+
+The profile has 40 atomic assertions. Go, container, Terraform, Kubernetes, and
+OpenAPI assertions are planned as not applicable when their corresponding
+sourced inventory facts are absent.
+
+The engine rejects repository path and symlink escapes and detects a target file
+that changes between inventory and evidence collection. Missing evidence,
+invalid or unevaluable applicability expressions, unavailable adapters, and
+manual review are never converted into Pass.
+
+Read the [sandboxed adapter protocol](../architecture/adapters.md) to validate an
+adapter transcript, inspect an OCI execution plan, run an already-present
+digest-pinned adapter image, or understand live profile-authorized evidence
+consumption.
+
+## Optional offline infrastructure policy scan
+
+The focused `prc/iac@0.1` profile authorizes the exact checked-in Checkov 3.3.8
+manifest when Terraform, Kubernetes, or container definitions are inventoried.
+This is not part of the simple native scan because it launches a pinned OCI
+analyzer. Read the [infrastructure policy profile](infrastructure-policy.md),
+review the manifest, pre-pull its exact digest, and grant local verification
+explicitly:
+
+```bash
+docker pull docker.io/bridgecrew/checkov@sha256:c64ffb6d6fc8087c896341a2c697770a04a1cf558db04fa7b8129d8ca6bce336
+
+./prc scan /path/to/project \
+  --profile prc/iac \
+  --mode verify-local \
+  --adapter-manifest adapters/checkov-v3.3.8.yaml
+```
+
+The scanner mounts a sealed inventory read-only, denies network access, uses
+scanner-owned offline policy, and prevents target `.checkov.yml` settings from
+hiding results. A policy violation becomes a detailed finding. Parsing errors,
+inline suppressions, unsupported output, or unsafe metadata fail closed. The
+command still produces a report only and never applies an infrastructure
+change.
+
+Read [bounded isolated remediation](remediation.md) to run the deterministic R1
+loop, create and verify one R1 candidate, or apply one validated R2 provider
+proposal outside the source workspace.
+
+Read [read-only agent providers](../architecture/agent-providers.md) to inspect
+or explicitly run the experimental Codex and Claude Code `suggest` adapters.
+Provider proposals are never applied or treated as evidence of a passing check.

package/bin/docs/scanner/go-http-timeouts.md

@@ -0,0 +1,96 @@
+# Go HTTP timeout analysis
+
+The core profile contains two deliberately narrow, deterministic Go checks for
+HTTP timeout hazards in non-test `.go` files. Both inspect syntax without
+running, building, importing, or type-checking target code. Files ending in
+`_test.go` are excluded because production timeout gates should not classify
+test-only helpers as deployed network behavior.
+
+## Client package helpers
+
+`PRC-A-GO-001` checks direct calls to the Go `net/http` package functions
+`Get`, `Head`, `Post`, and `PostForm`. The Go documentation defines these
+functions as wrappers around `http.DefaultClient`; the default is a usable
+zero-value `http.Client`, and a zero `Client.Timeout` means no end-to-end
+timeout. See the official
+[`net/http` package documentation](https://pkg.go.dev/net/http) and
+[`DefaultClient` source](https://go.dev/src/net/http/client.go).
+
+The timeout decision must be visible at a bounded request or client boundary
+instead of depending on mutable process-global client state. A typical
+compliant call uses a reused `http.Client` with a positive `Timeout`:
+
+```go
+client := &http.Client{Timeout: 10 * time.Second}
+response, err := client.Get(endpoint)
+```
+
+For APIs that need a different deadline per operation, construct a request with
+`http.NewRequestWithContext` and use `Client.Do`. The scanner does not determine
+whether a particular numeric duration is suitable for the service; that remains
+a project-specific reliability decision.
+
+## Server package helpers
+
+`PRC-A-GO-002` checks direct calls to the `net/http` package functions
+`ListenAndServe`, `ListenAndServeTLS`, `Serve`, and `ServeTLS`. The official Go
+[`server.go` source](https://go.dev/src/net/http/server.go) shows that each
+helper constructs a new `http.Server` with only an address and/or handler before
+serving. The [`Server` documentation](https://pkg.go.dev/net/http#Server) states
+that zero or negative read, header, write, and idle timeout values can mean
+there is no timeout. The package's own
+[`doc.go` guidance](https://go.dev/src/net/http/doc.go) recommends constructing
+a custom `Server` when more control is required.
+
+A typical compliant server makes its request timeout policy explicit on a
+reused `http.Server` and calls a method on that value:
+
+```go
+server := &http.Server{
+    Addr:              ":8080",
+    Handler:           handler,
+    ReadHeaderTimeout: 5 * time.Second,
+    ReadTimeout:       30 * time.Second,
+    WriteTimeout:      30 * time.Second,
+    IdleTimeout:       60 * time.Second,
+}
+err := server.ListenAndServe()
+```
+
+This rule proves only the absence of the four package-level shortcuts. It does
+not claim that every field is populated, positive, or operationally suitable.
+
+## Syntax and evidence contract
+
+The implementations parse inventoried non-test `.go` files with Go's syntax
+tree parser. They recognize normal, aliased, and dot imports of `net/http`,
+while excluding locally shadowed identifiers. They never type-check, build,
+test, import, or execute the target. Scope evidence binds the content-addressed
+inventory; a failure also records hashes for affected files, never source text. The result
+summary reports a bounded file, line, column, and helper name; the structured
+assertion result and canonical finding identify the exact affected callsite.
+
+Each check returns Blocked/Unknown when more than 4,096 Go files or 256 MiB of
+Go source would need inspection, or when one file exceeds the native 4 MiB
+parser limit. A changed or unreadable inventoried file and invalid Go syntax
+return an execution error. None of those states can become Pass.
+
+## Deliberate limitations
+
+These rules are not a whole-program proof that every network operation has an
+appropriate timeout. In particular, they do not currently evaluate:
+
+- direct calls through `http.DefaultClient` or another client variable;
+- custom transports, generated clients, RPC libraries, databases, queues, or
+  other network stacks;
+- request contexts, data flow, build tags, generated code provenance, or whether
+  a configured duration is operationally appropriate;
+- whether a custom `http.Server` initializes every relevant timeout field,
+  whether later assignments change those fields, or how proxies affect request
+  bounds; or
+- dependency source, binaries, deployed configuration, and runtime behavior.
+
+Those broader claims require language-aware data flow and runtime evidence from
+separately benchmarked, digest-pinned adapters. These native rules cover two
+high-confidence hazards and must not be described as complete network-timeout
+validation.