@marinjursic/prc-linux-arm64 0.1.0

package/bin/docs/architecture/catalog-integrity.md

@@ -0,0 +1,85 @@
+# Catalog integrity
+
+The scanner treats the catalog as executable policy even though catalog files do
+not run code. A malformed objective, assertion, or profile can otherwise change
+what is assessed, what counts as evidence, or which result blocks a release.
+Catalog loading therefore fails closed before inventory planning begins.
+
+## Runtime loading contract
+
+The Go scanner accepts only one bounded YAML document per regular catalog file.
+Files larger than 4 MiB, symbolic links, unknown fields, trailing YAML documents,
+unsupported schema versions, and mixed catalog versions are rejected. The
+loader also checks the file identity and size while reading so a concurrent
+replacement cannot silently become policy.
+
+Every loaded definition is checked for:
+
+- valid and unique objective, assertion, implementation, and profile IDs;
+- positive revisions and supported catalog and profile versions;
+- nonempty bounded UTF-8 text without NUL bytes;
+- allowed automation classes, evidence authorities, severities, gates, and
+  remediation classes;
+- unique domains, evidence requirements, control links, profile members, and
+  terminal severities;
+- safe repository-relative Markdown source paths and exact source line text;
+- existing, bidirectional objective-to-assertion mappings; and
+- profile references to assertions that are present in the same catalog.
+
+Any violation is a CLI input error. The scanner does not partially load a
+catalog, ignore an invalid record, or continue with a weakened profile.
+
+## Repository-wide generation checks
+
+Runtime validation protects scanner consumers. The repository's Python catalog
+check additionally rebuilds and compares the complete 10,042-control registry,
+verifies source digests and revisions, validates every JSON Schema, and checks
+the generated core-profile documentation. Run both the scanner tests and the
+repository check after changing catalog policy:
+
+```bash
+go test ./scanner/catalog ./scanner/engine ./cmd/prc
+python3 scripts/catalog.py check
+python3 scripts/validate.py
+```
+
+The two layers are intentionally complementary. A released scanner must reject
+an unsafe catalog even when repository CI was skipped, while repository CI must
+detect drift across source controls and generated artifacts that a small runtime
+profile does not load.
+
+## Reproducible inspection and distribution
+
+Validate a catalog and print its path-independent identity before planning a
+scan:
+
+```bash
+prc catalog validate --catalog-root /path/to/catalog
+prc catalog validate --catalog-root /path/to/catalog --format json
+```
+
+`prc catalog bundle` emits `prc.catalog-bundle/v0.1` JSON containing the same
+manifest plus every validated objective, assertion, and profile in stable ID
+order:
+
+```bash
+prc catalog bundle --catalog-root /path/to/catalog > catalog-bundle.json
+```
+
+The bundle contains no build timestamp or absolute path, so two copies of the
+same definitions produce identical bytes. Its manifest records the semantic
+catalog version, exact catalog digest, and definition counts. The checked-in
+JSON Schemas validate both the manifest and bundle. Signing and publisher trust
+remain release-pipeline responsibilities; an unsigned bundle is not evidence of
+who published it.
+
+## Identity binding
+
+A successful load produces a deterministic digest over every parsed objective,
+assertion, profile, and catalog version. The plan records that digest together
+with the exact profile and assertion definitions. A catalog policy change can
+therefore invalidate earlier evidence even when the target repository did not
+change.
+
+The filesystem root is excluded from the digest. Identical trusted definitions
+have the same identity when installed at different absolute paths.

package/bin/docs/architecture/evidence-and-results.md

@@ -0,0 +1,154 @@
+# Evidence and result model
+
+Production readiness is a set of proof obligations, not a count of checked boxes.
+The scanner keeps normative intent, executable assertions, observations, evidence,
+and policy decisions as separate versioned records.
+
+## Core records
+
+| Record | Purpose |
+| --- | --- |
+| Control objective | Human-readable outcome and rationale |
+| Assertion | Atomic proof obligation with explicit applicability and evidence requirements |
+| Implementation | Versioned producer and evaluator for an assertion |
+| Observation | Fact reported by a producer before assertion evaluation |
+| Evidence | Immutable bytes or external reference supporting an observation |
+| Assertion result | Applicability, execution, and assessment for one assertion |
+| Finding | Prioritized consequence and remediation eligibility |
+| Gate | Policy decision derived from results |
+| Exception | Scoped, owned, expiring risk acceptance |
+| Fix contract | Authorized change scope and independent acceptance criteria |
+
+One control objective can map to multiple assertions. Multiple implementations
+can support an assertion for different ecosystems. An implementation version is
+part of result identity.
+
+## Proof obligation
+
+An assertion declares before execution:
+
+- the property to prove;
+- applicability conditions;
+- acceptable evidence types and minimum authority;
+- target, artifact, release, and environment scope;
+- freshness and invalidation rules;
+- evaluation logic;
+- failure severity and gate behavior;
+- whether human or external evidence is required; and
+- remediation class, if any.
+
+`evidence_required` and `evidence_observed` are distinct fields. Missing evidence
+does not prove that a property is absent, and a located file does not prove that
+the file's intended behavior occurred.
+
+## Independent result axes
+
+Applicability:
+
+- `applicable`
+- `not_applicable`
+- `undetermined`
+
+Execution:
+
+- `not_run`
+- `completed`
+- `blocked`
+- `error`
+
+Assessment:
+
+- `pass`
+- `fail`
+- `unknown`
+- `manual_review`
+- `stale`
+- `conflicting`
+
+This prevents an adapter error, missing evidence, manual decision, and verified
+failure from collapsing into the same label.
+
+## Canonical findings and correlation
+
+Run result v0.6 emits a `prc.finding/v0.1` record for every failed assertion.
+It does not create findings for missing access, execution errors, manual review,
+unknown applicability, or Not Applicable results; those remain visible on their
+independent assertion-result axes.
+
+Each finding records:
+
+- a content-addressed ID for the exact inventory, summary, evidence, and policy
+  classification;
+- a stable fingerprint over the assertion, logical subject, and normalized
+  source locations;
+- the mapped assertion and control IDs;
+- the exact repository or declared-project subject and inventory digest;
+- severity, gate, and remediation class;
+- only validated repository-relative locations; and
+- the complete set of evidence IDs from its failed assertion result.
+
+The fingerprint survives new evidence and explanatory wording changes so a
+failure can be correlated across scans. The content ID changes when the exact
+finding envelope changes. A declared project ID supplies stable cross-checkout
+subject identity; without project configuration, correlation is scoped to the
+scanner's repository target name.
+
+The state database indexes both identities, normalized locations, and evidence
+links while immutable run JSON remains authoritative. SARIF is derived from
+these canonical findings. It no longer guesses findings or file locations from
+arbitrary evidence source strings.
+
+Version-specific `prc.run/v0.1` through `prc.run/v0.8` schemas remain
+available for archived results. Each pins its complete local schema dependency
+graph instead of following mutable aliases.
+
+## Evidence envelope
+
+Every evidence item records:
+
+- schema version and evidence identifier;
+- target, commit, artifact digest, release, and environment as applicable;
+- producer, implementation, tool, and policy versions;
+- collection time, validity interval, and invalidation keys;
+- source authority and collection method;
+- media type, content digest, location, and optional redacted preview;
+- sensitivity, retention, and access classification;
+- scope, limitations, and assumptions;
+- verification method and outcome; and
+- relationships to supporting or contradictory observations.
+
+Evidence content is stored by digest. Reports refer to evidence identifiers and
+redacted previews rather than copying sensitive content indiscriminately.
+
+The durable state layer keeps immutable JSON as the canonical record and adds a
+transactional SQLite query index for runs, results, evidence metadata, inventory
+files, sourced facts, relationships, and audit events. It verifies canonical
+identities before indexing, uses strict tables and foreign keys, and repairs
+derived rows by re-indexing an immutable run. Indexed record paths are relative
+and must resolve inside the state root. See [durable state and run
+history](../scanner/state-and-history.md).
+
+The [diff-aware invalidation model](../scanner/diff-and-invalidation.md) binds
+new plans to exact profile and assertion definitions, maps native
+implementations to their repository inputs, and refuses to carry evidence to a
+different target identity without revalidation.
+
+## Authority is assertion-specific
+
+Authority is not a universal numeric confidence score. A repository configuration
+may be authoritative for declared configuration syntax while remaining weak
+evidence of what is deployed. A signed production observation may prove deployed
+state without proving recovery or user-visible behavior.
+
+The evaluator compares the evidence's authority, scope, identity, and freshness
+to the assertion's declared proof obligation. Model confidence cannot replace
+this comparison.
+
+## Exceptions and gates
+
+An exception contains an owner, rationale, affected assertion and target scope,
+compensating controls, approval identity, creation time, expiry, and invalidation
+conditions. Expired or out-of-scope exceptions do not suppress findings.
+
+Gates consume explicit assertion results and exceptions. They do not consume a
+readiness percentage.

package/bin/docs/architecture/execution-plans.md

@@ -0,0 +1,61 @@
+# Execution plans and capability policy
+
+`prc plan` produces a content-addressed `prc.plan/v0.6` artifact before any
+external adapter can run. The artifact records both what should be evaluated and
+which capabilities the selected execution mode permits.
+
+## Dependency graph
+
+The `nodes` array is a deterministic topological ordering:
+
+1. one inventory node binds the complete target inventory;
+2. zero or more immutable adapter nodes depend on that inventory;
+3. one assertion node per profile assertion depends on the inventory and any
+   adapter evidence it requires; and
+4. one gate node depends on every assertion node.
+
+Every dependency must name an earlier node. Duplicate IDs, forward references,
+missing assertion nodes, and unavailable implementation IDs fail closed. The
+engine evaluates assertion nodes in this recorded order; it does not reconstruct
+an implicit execution order at scan time.
+
+The `implementations` array is a deduplicated registry view. It records the exact
+implementation ID, implementation kind, all assertions that use it, required
+capabilities, and whether the scanner has that exact version available. The
+`adapters` array similarly records immutable adapter IDs and manifest digests,
+observation kinds, capabilities, and plan-time authorization. Runtime and image
+availability are checked separately before launch.
+
+## Execution modes
+
+The current vertical slice supports two modes:
+
+| Mode | Workspace | Scratch | Process | Network | Secrets |
+| --- | --- | --- | --- | --- | --- |
+| `inspect` | Read-only | Denied | Denied | Denied | Denied |
+| `verify-local` | Read-only | Isolated only | Rootless OCI only | Denied | Denied |
+
+`inspect` is the default for `plan` and ordinary native scans. A live adapter
+scan requires the operator to pass `--mode verify-local` explicitly. The adapter
+must still be bound by an applicable assertion using its exact ID and manifest
+SHA-256 digest, and its manifest must pass the stricter OCI runner validation.
+Selecting a mode never authorizes an unbound adapter.
+
+Unsupported execution modes are configuration errors. An adapter requirement
+that exceeds the selected capability policy produces a blocked plan node and is
+denied before the OCI runtime is invoked. The current modes never grant target
+writes, general subprocess execution, network access, secret handles, production
+access, or external mutation.
+
+## Blocked work remains visible
+
+A plan is still useful when some nodes are blocked. Examples include an
+unregistered implementation, an applicable analysis assertion without an
+immutable adapter binding, or an adapter that requires a higher mode. The gate
+node is then marked blocked, and a scan records an explicit unknown/blocked
+assertion result. Missing execution never becomes Pass or Not Applicable.
+
+Version-specific plan v0.1 through v0.6 and run v0.1 through v0.8 schemas
+remain frozen for archived consumers. Plans before v0.6 do not contain the
+execution DAG or capability policy and therefore require conservative
+re-evaluation when compared with current plans.

package/bin/docs/architecture/product-contract.md

@@ -0,0 +1,76 @@
+# Scanner product contract
+
+The Production Readiness Checklist is an evidence and policy engine for a declared
+target. It does not claim that a nontrivial system has no defects, certify an
+organization, or make a release decision for an accountable owner.
+
+## Verifiable promise
+
+Given a declared target, release, readiness profile, evidence scope, policy, and
+capability budget, the scanner will:
+
+1. create an immutable plan of applicable and unresolved assertions;
+2. collect observations through versioned, policy-authorized evidence producers;
+3. evaluate each planned assertion without upgrading an inference into a fact;
+4. preserve unknown, blocked, stale, conflicting, and manual-review results;
+5. expose the evidence and reasoning behind every result;
+6. remediate only findings whose fix contract and capability class permit it;
+7. independently verify every candidate change; and
+8. stop in an explicit terminal state.
+
+The scanner may say that a profile is satisfied for a particular target and
+evidence set. It must not reduce that scoped result to the unqualified statement
+that a project is "production ready."
+
+## Completion states
+
+A scan or remediation run ends in exactly one of these states:
+
+| State | Meaning |
+| --- | --- |
+| `profile_satisfied` | Every applicable required assertion in the selected profile has current passing evidence and no gate blocks the result. Advisory findings remain visible without changing this state. |
+| `machine_work_complete_manual_evidence_remaining` | Every policy-eligible automated fix is exhausted, but human or external evidence remains. |
+| `assessment_incomplete` | Required evidence or applicability context is unavailable. |
+| `no_go` | One or more configured blocking gates failed. |
+| `policy_stopped` | A requested action exceeded the run's capability policy. |
+| `budget_exhausted` | The attempt, time, cost, or change budget was reached. |
+| `environment_blocked` | A required tool or evidence source could not be used safely. |
+
+No aggregate percentage overrides these states. One no-go result can block a
+release regardless of how many unrelated assertions pass.
+
+## Truth ownership
+
+The engine owns control selection, evidence verification, assertion evaluation,
+gates, policy, and patch acceptance. Tools and connectors produce observations.
+Coding agents produce untrusted patch candidates and explanations.
+
+An agent response, model confidence, filename, README statement, configuration
+file, or source-code comment is not proof of runtime or production behavior.
+Evidence authority is determined by the assertion's proof obligation and the
+environment and artifact to which the evidence applies.
+
+## Non-goals
+
+The scanner will not:
+
+- prove the absence of every defect;
+- infer production state from repository intent alone;
+- treat provenance, an SBOM, a test file, or a policy file as proof that all
+  associated behavior is correct;
+- make legal, regulatory, accessibility, safety, risk-acceptance, or release
+  decisions for accountable humans;
+- let a target repository, adapter, or agent change scanner policy during a run;
+- deploy from the general remediation loop; or
+- weaken checks, thresholds, tests, baselines, or suppressions to manufacture a
+  passing result.
+
+## Compatibility promise
+
+Catalog, profile, result, evidence, adapter, and provider formats are versioned
+independently. Until a format is declared stable, consumers must pin a supported
+version. Breaking changes require a migration path and explicit release notes.
+
+The process interface follows the [stable CLI and exit-code
+contract](../scanner/cli-contract.md); child-tool exit statuses never become
+assessment truth without protocol mapping and engine evaluation.

package/bin/docs/architecture/publisher-trust.md

@@ -0,0 +1,68 @@
+# Offline publisher trust
+
+Content digests prove identity, not authorship. The scanner therefore supports
+detached Ed25519 verification for pack, adapter-registry, and signed
+risk-exception artifacts through an operator-selected trust store. It never
+discovers keys, downloads trust metadata, or handles publisher private keys.
+
+The trust store is an explicit local root of trust. Each key has an ID, exact
+public key, artifact-kind scopes, validity interval, and active or revoked
+status. Revocation is fail-closed and applies even to a signature created
+before the key was revoked. A key authorized for a pack cannot sign an adapter
+registry or risk exception unless that additional scope is also present.
+
+The detached signature covers a domain-separated canonical payload containing:
+
+- signature schema and algorithm;
+- artifact kind and versioned artifact ID;
+- the artifact's canonical SHA-256 identity;
+- publisher key ID; and
+- UTC issuance time.
+
+Verification requires an explicit UTC time so historical automation remains
+reproducible. The issuance and verification times must both fall inside the
+key validity interval, and a future-issued signature is rejected. The output
+record binds the signature digest and canonical trust-store digest.
+
+## Verify a pack
+
+Pack verification first validates the catalog binding and reruns the pinned
+benchmark. Only then does it verify the detached signature against the
+resulting canonical pack digest:
+
+```bash
+prc pack verify \
+  --catalog-root . \
+  --file /path/to/pack.yaml \
+  --trust-store /path/to/trust-store.yaml \
+  --signature /path/to/pack.signature.yaml \
+  --verified-at 2026-08-23T13:00:00Z \
+  --format json
+```
+
+## Verify an adapter registry
+
+Registry verification first resolves every non-revoked manifest and checks its
+ID, publisher, lifecycle, engine compatibility, and digest pins:
+
+```bash
+prc adapter registry-verify \
+  --file /path/to/adapter-registry.yaml \
+  --trust-store /path/to/trust-store.yaml \
+  --signature /path/to/registry.signature.yaml \
+  --verified-at 2026-08-23T13:00:00Z \
+  --format json
+```
+
+The schemas are `trust-store.schema.json`, `signature.schema.json`, and
+`signature-verification.schema.json`. The current repository does not publish
+an official release trust store or signatures yet. Verification support is not
+itself a key ceremony, secure private-key service, transparency log,
+reproducible release, or revocation-distribution channel; those remain release
+engineering requirements.
+
+Risk-owner keys may also have the `risk-exception` scope. Those signatures are
+verified only through the stricter
+[risk-exception workflow](../scanner/risk-exceptions.md), which binds an
+immutable failed finding, accountable people, evidence, monitoring,
+remediation, and expiry without changing the scanner gate.

package/bin/docs/architecture/remediation-contract.md

@@ -0,0 +1,113 @@
+# Bounded remediation contract
+
+Remediation is a separate, policy-controlled phase. A failed assertion does not
+automatically grant an agent permission to change a repository.
+
+## Remediation classes
+
+| Class | Capability | Default policy |
+| --- | --- | --- |
+| R0 | Explain or suggest only | Allowed |
+| R1 | Deterministic, behavior-preserving edit | Allowed when the implementation is trusted |
+| R2 | Agent-authored repository change | Experimental and isolated |
+| R3 | Dependency or build behavior change | Explicit opt-in and stronger verification |
+| R4 | Infrastructure or deployment-definition change | Human authorization required |
+| R5 | External staging-system mutation | Separate connector policy and approval |
+| R6 | Production, destructive, legal, financial, or risk decision | Prohibited in the general loop |
+
+## Fix contract
+
+Every attempt is bound to a signed or hashed contract containing:
+
+- exact finding content ID, stable finding fingerprint, assertion, target, and
+  baseline result identifiers;
+- desired postcondition;
+- permitted and protected paths;
+- permitted commands, tools, network, secrets, and external systems;
+- maximum changed files, lines, bytes, attempts, time, and cost;
+- required new or updated regression tests;
+- invariant and regression checks;
+- policy and scanner inputs that must remain unchanged; and
+- the deterministic acceptance sequence.
+
+The agent receives the minimum context needed for this contract. Unrelated source,
+evidence, credentials, and previous agent memory are excluded.
+
+## Candidate lifecycle
+
+1. Capture an immutable baseline and reproduce the finding.
+2. Create a fresh isolated workspace or worktree.
+3. Apply one deterministic fix or run one provider task.
+4. Parse the result as untrusted structured output.
+5. Reject path, capability, policy, threshold, baseline, or suppression violations.
+6. Run contract-specific tests and the original finding implementation.
+7. Run impacted regression checks and anti-gaming validation.
+8. Rescan affected assertions from fresh evidence.
+9. Accept only when the original finding closes and no protected result regresses.
+10. Preserve the candidate, transcript, evidence, and rejection or acceptance reason.
+
+The current v0.8 remediation-run record adds a scanner-validated attempt chain,
+binds any launched R2 test verification to its exact candidate inventory, and
+records the scanner-owned wall-clock ceiling for the complete loop.
+An accepted attempt must link to exactly one content-addressed candidate; an
+agent attempt must link to exactly one successful provider execution or failed
+provider invocation; a pre-candidate
+policy rejection records its exact safe scanner reason without inventing a
+candidate; and the accepted digest chain must end at the reported final
+inventory. Missing, duplicate, reordered, or cross-linked records invalidate
+the run before its content ID is computed.
+
+An agent does not validate its own patch. A second model can challenge a candidate,
+but only the independent deterministic acceptance sequence can approve it.
+
+## Termination
+
+The loop stops when:
+
+- the selected profile is satisfied;
+- only manual, external, prohibited, or inapplicable work remains;
+- a no-go finding cannot be remediated within policy;
+- an attempt makes no measurable improvement;
+- the same root cause repeats without progress;
+- any capability, change, attempt, or duration budget is exhausted; or
+- the environment cannot execute the verifier safely.
+
+The general loop never deploys and never accepts residual risk.
+
+## Implemented R1 pilot
+
+The current CLI implements this lifecycle for final-newline and restrictive-mode
+R1 assertions. Its trusted fixers make exact byte or mode transformations in a
+new external workspace. The acceptance audit verifies the raw tree, content
+hashes, permission modes, protected paths, budgets, target result, and baseline
+passing results. The bounded `fix` loop can repeat these registered operations in
+sibling candidates, rescan after every accepted attempt, enforce cumulative
+attempt, file, and line limits, and report why every unresolved item remains.
+See the [R1 remediation guide](../scanner/remediation.md) for the exact commands
+and limitations.
+
+## Implemented R2 proposal pilot
+
+The [read-only provider layer](agent-providers.md) can produce bounded Codex or
+Claude Code proposals. The separate `remediate-proposal` command validates and
+parses one proposal, applies it to a fresh external candidate without invoking
+the provider, and runs raw-tree, exact-byte, mode, budget, target-result,
+regression, and source-integrity audits. The provider never approves its own
+work. Both one-shot remediation paths bind the exact verified baseline finding,
+project configuration, protected paths, and file, line, and attempt ceilings
+into a v0.3 fix contract. The default loop does not invoke providers. When
+explicitly enabled,
+`fix --provider` composes the read-only provider and scanner-owned proposal
+paths only for a missing-test assertion with one bounded source input and new
+test-file allowlist. The R2 contract also preserves the exact triggering
+finding ID from the sealed provider task and requires both its content ID and
+stable fingerprint to match a freshly reproduced failure. An R2 candidate cannot
+be accepted without a separate digest-pinned OCI verifier. The scanner, not the
+provider or repository, selects the Go, Python, or plain-JavaScript test argv;
+the read-only
+candidate runs without network, privileges, secrets, or host-write access and
+with bounded resources and output. Before the candidate exists, a separate
+language-aware payload audit rejects new tests that request process, network,
+environment, filesystem-mutation, absolute-path, dynamic-evaluation, or encoded
+payload capabilities that the focused task does not need. General R2 repair planning, TypeScript
+verification, merges, deployments, and releases remain unimplemented.

package/bin/docs/architecture/trust-model.md

@@ -0,0 +1,95 @@
+# Scanner trust and threat model
+
+The scanner processes repositories, build artifacts, tool output, model output,
+and external evidence that may be malformed, compromised, or intentionally
+hostile. Safe operation therefore starts from a default-deny capability model.
+
+## Trust zones
+
+| Zone | Contents | Default trust |
+| --- | --- | --- |
+| Control plane | Catalog, profiles, policy, schemas, tool registry, verifier | Trusted and immutable for the run |
+| Execution plane | Adapters, tools, builds, browsers, coding agents | Isolated and untrusted |
+| Target plane | Repository, dependencies, artifacts, configuration, logs | Untrusted evidence source |
+| External plane | CI, registry, cloud, cluster, telemetry, ticketing | Untrusted transport with explicitly configured authority |
+
+The execution and target planes must not be able to mutate the control plane.
+The verifier must consume immutable inputs captured before candidate remediation.
+Inventory-file and benchmark-fixture reads bind an opened file back to the
+root-scoped entry that was inspected. Git identity is read only through an
+`os.Root` rooted at the target: metadata paths and symlinks cannot escape it,
+and external `gitdir` indirection is rejected rather than followed.
+
+## Threats in scope
+
+- prompt injection in instructions, comments, documentation, fixtures, logs, test
+  names, generated files, issue text, dependency metadata, and tool output;
+- command injection through filenames, configuration, shell fragments, or adapter
+  fields;
+- path traversal, symlink escape, archive bombs, oversized output, and resource
+  exhaustion;
+- malicious build scripts, compilers, package-manager hooks, test runners, browser
+  targets, and language servers;
+- evidence forgery, replay, staleness, scope confusion, artifact substitution, and
+  contradictory sources;
+- an agent weakening tests, policies, thresholds, assertions, baselines, or
+  suppressions instead of fixing a defect;
+- poisoned tools, mutable tags, compromised dependencies, and unverified plugins;
+- credential theft, unintended network access, and cross-run state leakage; and
+- unsafe production actions caused by a repository scan or remediation request.
+
+## Capability policy
+
+Every executable unit receives an explicit capability manifest. Omitted
+capabilities are denied.
+
+The manifest covers at least:
+
+- readable and writable paths;
+- executable identities and arguments;
+- environment variables and secret handles;
+- network destinations and methods;
+- CPU, memory, process, file, output, and wall-clock budgets;
+- external systems and allowed operations;
+- remediation class and protected paths; and
+- whether a human authorization is required.
+
+Scanner policy is snapshotted and hashed before execution. A candidate that
+changes policy inputs is rejected and cannot validate itself.
+
+## Isolation tiers
+
+| Tier | Intended workload | Required boundary |
+| --- | --- | --- |
+| 0 | File parsing and metadata inspection | No target code execution |
+| 1 | Curated native read-only checks | OS sandbox, read-only target, no network |
+| 2 | Curated third-party tools | Rootless pinned container, read-only mounts, no socket, no network by default |
+| 3 | Untrusted builds, parsers, tests, and agents | Disposable gVisor, Kata, microVM, or VM-equivalent boundary |
+| 4 | Staging or production evidence | Separate read-only connector identity and explicit organization policy |
+
+A container is packaging and an isolation layer, not a universal hostile-code
+security boundary. Implementations must support a stronger Tier 3 runner rather
+than treating ordinary OCI isolation as sufficient.
+
+## Agent boundary
+
+Agent integrations receive a scanner-created context bundle and an isolated
+candidate workspace. Repository `AGENTS.md`, `CLAUDE.md`, hooks, MCP settings,
+plugins, and similar files are target data, not scanner instructions.
+
+Agents may propose changes only inside the fix contract. They cannot determine
+Pass, approve exceptions, alter policy, access unrelated files, or deploy.
+
+## Immediate stops
+
+Execution stops safely when the scanner observes:
+
+- a capability request outside policy;
+- a sandbox or path-boundary violation;
+- unexpected credential, network, or external-system access;
+- ambiguous mutation of a protected file;
+- evidence identity or digest mismatch;
+- a tool or provider version outside its supported contract; or
+- an unbounded or repeatedly non-improving remediation loop.
+
+The stop is recorded as evidence. It is never silently converted into a pass.