MarcoPorcellato · MarcoPorcellato · Aug 28, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,8 @@ Semantic Versioning after its first public release.
   exactly-once admission release, and fail-closed release-error precedence.
   Deterministic coverage includes watchdog, journal, and cache-pin ordering;
   native guard-exec qualification remains separate and NOT_RUN.
+- Documented the Matrix-only `matrix-v2-legacy-v1` compatibility profile;
+  default operation remains `current-v2`.
 - Matrix v2 `doctor` and `dry-run` now inspect every declared runtime using
   lexically ordered, digest-labeled reports. Doctor performs one bounded
   runtime probe per entry; dry-run renders each explicit workspace and command

diff --git a/docs/ADOPTION_GUIDE.md b/docs/ADOPTION_GUIDE.md
@@ -329,3 +329,13 @@ remote jobs. Preserve receipts and configurations for incident analysis. See
 - [ ] GitHub status is observed on the latest PR head.
 - [ ] Review, secrets, deployments, and uncovered native gates remain remote.
 - [ ] Rollback path is documented and tested.
+## Matrix V2 legacy adoption boundary
+
+This boundary does not perform policy inference; it records Matrix-only evidence.
+
+Adopters using the Matrix-only `matrix-v2-legacy-v1` profile must preserve the
+producer suffix and command parity (`plan`, `doctor`, `dry-run`, `run`). The
+operator copies reviewed digests into Matrix policy v2, never from a completed
+receipt. Legacy and current cache namespaces are separate; `verify` has no
+profile flag. Require acceptance by an old trusted historical verifier before
+policy migration. This guidance does not infer policy or general trust.
diff --git a/docs/CACHE_AND_WORKSPACE.md b/docs/CACHE_AND_WORKSPACE.md
@@ -204,3 +204,11 @@ introduced. The declaration is cooperative and non-attesting: undeclared
 paths are not pinned, and manual or non-cooperative replacement is unsupported.
 Pinning does not initialize, repair, delete, quarantine, publish, or attest
 cache contents.
+## Compatibility cache boundary
+
+This Matrix-only boundary does not perform policy inference.
+
+The Matrix-only `matrix-v2-legacy-v1` profile has a separate legacy cache
+namespace from current-v2. Preserve command parity for `plan`, `doctor`,
+`dry-run`, and `run`; `verify` has no profile flag. Cache identity and the
+producer suffix are evidence fields, not policy inference or general trust.
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -222,3 +222,20 @@ and artifact contracts. It uses the same CCP canonical JSON v1 profile
 described in `docs/RECEIPT_SPEC.md`.
 
 The digest is integrity evidence, not a signature or identity attestation.
+## Matrix V2 compatibility profile
+
+The `matrix-v2-legacy-v1` profile is Matrix-only compatibility for the legacy
+producer suffix. It does not widen the schema or infer policy. Review the plan
+and copy its digests into Matrix policy v2; never copy them from a completed
+receipt. Use the same command parity sequence for each selected source:
+
+```console
+commit-ci-preflight plan --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight doctor --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight dry-run --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight run --matrix-plan-profile matrix-v2-legacy-v1 --generation N --json
+```
+
+Legacy and current cache identities are separate. `verify` has no profile flag.
+An old trusted historical verifier must accept the exact receipt before policy
+migration; this is evidence acceptance, not a general trust claim.
diff --git a/docs/GITHUB_GATE.md b/docs/GITHUB_GATE.md
@@ -170,3 +170,12 @@ The only cold remote compilation is the small trusted verifier. Project tests,
 Docker checks, and local dependency caches remain off GitHub. A future signed
 release can replace this bootstrap build with a pinned verifier download after
 release publication is separately authorized and qualified.
+## Matrix V2 compatibility gate
+
+The `matrix-v2-legacy-v1` profile is Matrix-only. Preserve command parity across
+`plan`, `doctor`, `dry-run`, and `run`; `verify` has no profile flag. Review
+digests before copying them into Matrix policy v2, never from a completed
+receipt. Legacy/current cache namespaces are separate, and an old trusted
+historical verifier must accept the exact receipt before migration. This is not
+policy inference or a general trust claim.
+Rollback target is `current-v2`.
diff --git a/docs/INVARIANT_EVIDENCE_MATRIX.md b/docs/INVARIANT_EVIDENCE_MATRIX.md
@@ -16,7 +16,7 @@ deterministic source evidence from native qualification still pending.
 
 | Invariant | Implemented evidence | Residual gap | Proof artifact | Gate |
 | --- | --- | --- | --- | --- |
-| Exact commit bytes are isolated from the user's mutable working tree | `SourceSnapshot::materialize` reads the committed tree and blobs through Git, writes a CCP-owned tree, and `PreparedWorkspace::prepare_snapshot` mounts only that tree | Native runtime observation remains pending | `src/source_snapshot.rs`, `src/workspace.rs`, and the snapshot-backed run test | Deterministic isolation PASS; native qualification PENDING |
+| Exact commit bytes are isolated from the user's mutable working tree | `SourceSnapshot::materialize` reads the committed tree and blobs through Git, writes a CCP-owned tree, and `PreparedWorkspace::prepare_snapshot` mounts only that tree; source blobs use a dedicated 64 MiB ceiling while ordinary process output remains limited to 1 MiB | Native runtime observation remains pending | `src/source_snapshot.rs`, `src/process.rs`, and the real-Git large-blob snapshot test | Deterministic isolation PASS; native qualification PENDING |
 | Source identity is canonical and reproducible | `SourceManifestV1` sorts entries and binds commit, path, mode, object kind and object ID; canonical SHA-256 produces `manifest_digest` | Cross-platform native vectors remain pending | Source-snapshot unit tests and receipt v2 golden fixture | Repeated supported manifests have identical digest: PASS |
 | Unsupported Git states fail closed | Submodules, symlinks and LFS pointers are rejected; unsupported modes fail; executable entries are supported on Unix and rejected on unsupported platforms. Sparse working-tree shape is ignored because materialization reads the full committed tree; unavailable objects fail as Git errors | Windows-native executable-mode behavior is not qualified | Typed `SourceSnapshotError` variants and deterministic rejection tests | Deterministic policy PASS; Windows-native qualification PENDING |
 | Receipt evidence binds source identity | Snapshot-backed runs publish strict receipt v2 with strategy, manifest digest and entry count; historical v1 remains readable without implied snapshot assurance | Trusted producer identity and signing are later tranches | `schema/receipt-v2.schema.json`, `tests/fixtures/receipt-v2-pass.json`, and dual-version verifier dispatch | Tampered snapshot digest fails integrity: PASS |
@@ -39,3 +39,18 @@ The implemented source boundary is explicit:
 
 This closes T2 in deterministic source evidence. Native platform,
 crash/power-loss and release qualification remain separate gates.
+## Task 8 documentation evidence matrix
+
+| Invariant | Focused evidence |
+|---|---|
+| Projection reproducibility | `tests/matrix_contract.rs::legacy_profile_reproduces_historical_plan` |
+| Representability rejection | `tests/matrix_contract.rs::legacy_profile_rejects_each_non_representable_current_field` |
+| Command parity | `tests/plan_cli.rs::matrix_plan_profile_flag_is_exposed_only_by_configuration_commands` |
+| Cache separation | `tests/runtime_cli.rs::legacy_profile_uses_distinct_plan_cache_identity` |
+| Producer uniformity | `tests/matrix_contract.rs::legacy_receipt_provenance_is_uniform` |
+| Historical verifier acceptance | `tests/verification_contract.rs::historical_matrix_verifier_accepts_legacy_profile_receipt_and_rejects_mutations` (`#[ignore]`, `--ignored`, external verifier required) |
+| Mutation rejection | `tests/verification_contract.rs::current_matrix_verifier_accepts_legacy_profile_receipt_and_rejects_mutations` and historical verifier test |
+| Zero pre-admission mutation | `tests/runtime_cli.rs::legacy_profile_rejection_precedes_shared_state` and `tests/runtime_cli.rs::legacy_profile_rejects_current_only_matrix_syntax_before_shared_state` |
+
+All entries are Matrix-only evidence for `matrix-v2-legacy-v1`; they do not infer
+policy or establish general trust. Rollback target is `current-v2`.
diff --git a/docs/LOCAL_RUN.md b/docs/LOCAL_RUN.md
@@ -213,3 +213,21 @@ release. This declaration is cooperative and non-attesting: undeclared paths
 are not pinned, and manual or non-cooperative replacement is unsupported. The
 flags do not initialize, repair, delete, quarantine, publish, or attest cache
 contents. Legacy `guard exec` without these flags remains unchanged.
+## Matrix V2 legacy operator sequence
+
+```console
+commit-ci-preflight plan --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight doctor --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight dry-run --matrix-plan-profile matrix-v2-legacy-v1 --json
+commit-ci-preflight run --matrix-plan-profile matrix-v2-legacy-v1 --generation N --json
+```
+
+For Matrix-only compatibility, use the exact `matrix-v2-legacy-v1` profile and
+preserve command parity: `plan`, `doctor`, `dry-run`, then `run` with generation
+`N`. The operator reviews and copies digests into Matrix policy v2, never from a
+completed receipt. The producer suffix is part of the reviewed evidence.
+
+`verify` has no profile flag. Legacy and current cache namespace identities are
+separate, and an old trusted historical verifier must accept the exact receipt
+before policy migration. These statements document boundaries and do not infer
+policy or general trust.
diff --git a/docs/MULTI_RUNTIME_RECEIPTS.md b/docs/MULTI_RUNTIME_RECEIPTS.md
@@ -164,3 +164,22 @@ project code.
 Regenerate all pinned contracts with `cargo run --locked --example
 generate_contract`. The v1 schema/fixture tests require historical v1 output
 to remain byte-for-byte stable.
+## Matrix-only legacy compatibility
+
+The historical verifier external test is
+`tests/verification_contract.rs::historical_matrix_verifier_accepts_legacy_profile_receipt_and_rejects_mutations`
+and is marked `#[ignore]`; run it with `--ignored` only when
+`CCP_HISTORICAL_VERIFIER_044697` points to the retained binary with SHA-256
+`5321ff4d291ec24db6a7a5919bc08fc00a9d63767b630a3469fc39318c400277`,
+built from provenance-pinned commit
+`044697dee9a0d678d30a4847d62ddf9b4970505b`.
+
+This is the outer-v2 / inner-v1 boundary: outer Matrix schema 2.0 and inner
+runtime schema 1.0, produced with version `0.1.0+matrix-v2-legacy-v1`.
+
+The `matrix-v2-legacy-v1` profile is Matrix-only and retains the producer suffix
+as reviewed evidence. Run `plan`, `doctor`, `dry-run`, and `run` with the profile
+for command parity; `verify` has no profile flag. Copy reviewed digests into
+Matrix policy v2, never from a completed receipt. Legacy and current cache
+namespaces remain separate. Historical verifier acceptance is required before
+migration and is not policy inference or a general trust statement.
diff --git a/docs/RECEIPT_SPEC.md b/docs/RECEIPT_SPEC.md
@@ -202,3 +202,14 @@ cargo test --test receipt_contract
 
 Regeneration is accepted only when the schema/fixture diff is intentionally
 reviewed. Tests require generated and pinned bytes to remain identical.
+## Compatibility-profile boundary
+
+The producer version is `0.1.0+matrix-v2-legacy-v1`. The receipt boundary is
+outer Matrix schema 2.0 with inner runtime schema 1.0. Reviewed digests are
+never from a completed receipt.
+
+Receipts produced under `matrix-v2-legacy-v1` are Matrix-only compatibility
+evidence and retain the producer suffix. The profile applies to `plan`,
+`doctor`, `dry-run`, and `run`; `verify` has no profile flag. A historical
+verifier must accept the exact receipt before Matrix policy v2 migration. This
+does not widen the schema, infer policy, or establish general trust.
diff --git a/docs/TESTING_AND_FAULT_INJECTION.md b/docs/TESTING_AND_FAULT_INJECTION.md
@@ -147,3 +147,24 @@ trusted configuration validation.
 6. Record platform-native evidence separately from deterministic tests.
 7. Keep fault fixtures free of secrets, personal data, network access, and the
    operator's real cache or repository state.
+## Matrix V2 compatibility test matrix
+
+Focused tests cover the Matrix-only `matrix-v2-legacy-v1` profile: projection
+`tests/matrix_contract.rs::legacy_profile_reproduces_historical_plan`,
+representability `tests/matrix_contract.rs::legacy_profile_rejects_each_non_representable_current_field`,
+command parity
+`tests/plan_cli.rs::matrix_plan_profile_flag_is_exposed_only_by_configuration_commands`,
+producer uniformity `tests/matrix_contract.rs::legacy_receipt_provenance_is_uniform`,
+mutation rejection
+`tests/verification_contract.rs::current_matrix_verifier_accepts_legacy_profile_receipt_and_rejects_mutations`,
+and zero pre-admission mutation
+`tests/runtime_cli.rs::legacy_profile_rejection_precedes_shared_state` and
+`tests/runtime_cli.rs::legacy_profile_rejects_current_only_matrix_syntax_before_shared_state`.
+The historical verifier is
+`tests/verification_contract.rs::historical_matrix_verifier_accepts_legacy_profile_receipt_and_rejects_mutations`,
+marked `#[ignore]` and run with `--ignored` only when
+`CCP_HISTORICAL_VERIFIER_044697` points to the retained verifier binary with
+SHA-256 `5321ff4d291ec24db6a7a5919bc08fc00a9d63767b630a3469fc39318c400277`,
+The ordinary suite does not prove historical acceptance. The retained binary
+was built from commit `044697dee9a0d678d30a4847d62ddf9b4970505b`. `verify` has no profile flag.
+Tests do not infer policy or general trust; rollback target is `current-v2`.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -100,6 +100,27 @@ commit-ci-preflight dry-run --config .commit-ci-preflight.toml --repository . --
 Reproduce only the failing explicit check in a deliberate diagnostic context.
 Do not synthesize a receipt or reinterpret an absent receipt as PASS.
 
+## Source snapshot fails before project checks
+
+Snapshot materialization reads the exact committed Git blobs before project
+checks start. Regular blobs up to 64 MiB are accepted by this producer through
+a snapshot-only capture path. The ordinary process stdout and stderr limit
+remains 1 MiB. A larger source blob fails closed before its contents are read
+and reports the path, observed size, and 64 MiB limit; the partial snapshot is
+removed.
+
+Older producers used the ordinary 1 MiB process limit for source blobs as well.
+They can therefore stop with code `70` and the generic message `bounded Git
+snapshot command failed` when an otherwise valid tracked file is only slightly
+larger than 1 MiB. `plan`, `doctor`, and `dry-run` do not materialize Git blobs,
+so their success does not establish compatibility with that older ceiling.
+
+Preserve the exact producer hash, source commit, failing repository commit, and
+terminal output. Inspect tracked blob sizes without changing the repository,
+then use a reviewed and qualified producer that supports the required bounded
+snapshot size. Do not delete scientific evidence, rewrite history, synthesize
+a receipt, or retry a consumed run authorization merely to bypass this failure.
+
 ## First Rust check fails only inside the read-only container
 
 The repository's own `.commit-ci-preflight.toml` uses schema `1.1` and derives
@@ -228,3 +249,13 @@ Include:
 Keep private source, raw logs, credentials, tokens, environment values, and
 personal paths out of public issues. Security findings belong in the private
 channel described by [SECURITY.md](../SECURITY.md).
+## Matrix V2 legacy troubleshooting
+
+Troubleshooting is Matrix-only and does not perform policy inference.
+
+For Matrix-only compatibility, confirm the exact `matrix-v2-legacy-v1` profile
+and the command parity sequence (`plan`, `doctor`, `dry-run`, `run`). Legacy and
+current cache namespaces must not be mixed. `verify` has no profile flag. Before
+policy migration, an old trusted historical verifier must accept the exact
+receipt. Review digests into Matrix policy v2 only from the reviewed plan, never
+from a completed receipt; do not infer policy or general trust.