codd-dev 2.93.0__tar.gz → 2.95.0__tar.gz

{codd_dev-2.93.0 → codd_dev-2.95.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.93.0
+Version: 2.95.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.93.0 → codd_dev-2.95.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.93.0"
+__version__ = "2.95.0"

{codd_dev-2.93.0 → codd_dev-2.95.0}/codd/contracts_registry/registry.py

@@ -673,6 +673,11 @@ _COVERED: tuple[Contract, ...] = (
             "tests/repair/test_auto_repair_optin_and_scope.py (scope rejects failing-test edit / "
             "codd.yaml weaken / spec-doc edit; harness_contract_violation scaffold-fix allowed; "
             "max-files valve escalates)",
+            "tests/stack/test_stack_repair_governance.py (Contract Kernel v2.77f: scope-fence "
+            "rejects stack.lock / .codd/stack / declared codd/stack profile / codd.yaml stack-block "
+            "edits unconditionally, but allows real codd/stack source when CoDD is the SUT; "
+            "satisfy-source GREEN; defense-in-depth weaken/checker-delete/lock-refresh; "
+            "replace_with_proof GREEN only with executable behavioral-subsumption proof)",
         ),
         finding_ids=("F-greenfield-autorepair-optin-and-scope", "F-autorepair-test-command-unrepairable"),
     ),

{codd_dev-2.93.0 → codd_dev-2.95.0}/codd/repair/auto_scope_guard.py

@@ -136,6 +136,53 @@ _SPEC_DIR_MARKERS: frozenset[str] = frozenset(
     {"docs", "doc", "design", "designs", "specs", "spec", "requirements"}
 )
 
+# ── Stack contract artefacts (Contract Kernel v2.77f — Repair Governance) ────
+#
+# The STACK contract — the resolved framework/addon obligations, their checkers,
+# the composed command plan, the replace_with_proof witnesses, and the pinned
+# ``stack.lock`` — is the "definition of pass" for the framework layer. A repair MAY
+# fix SUT SOURCE to *satisfy* a stack obligation, but it must NEVER edit the stack
+# CONTRACT itself: weakening an obligation, deleting/unregistering a checker,
+# inserting a no-op command, refreshing the lock, or mutating a proof witness are
+# exactly how a repair would silence a red stack gate (false-green). These artefacts
+# are therefore OFF-LIMITS to ANY auto-repair edit — UNCONDITIONALLY (unlike the
+# oracle/doc fence above, which is gated on a code-addressable failure). Rationale: a
+# stack profile/obligation/checker/proof is the contract, never SUT source; the lock
+# is (re)generated ONLY on the explicit ``bootstrap_stack_lock`` first-generation
+# creation path, never by an unattended repair. There is no failure class for which an
+# auto-repair legitimately rewrites a stack contract artefact (a drift is cleared by
+# reverting the contract change or by an explicit proof-backed update, not by repair)
+# — so this fence does not carry the harness-contract exception the oracle fence does.
+#
+# Recognition (GPT-5.5 Pro consult 2026-06-21) is deliberately CONSERVATIVE about
+# false-positives, because CoDD ITSELF is a frequent SUT under repair (dogfood):
+#   * the ``stack.lock`` basename anywhere — unconditional. (A rare unrelated app file
+#     literally named ``stack.lock`` is an acceptable false-positive for this kernel
+#     layer: preventing an unattended lock refresh outweighs it; manual repair still
+#     works.)
+#   * any path under a ``.codd/stack/`` directory — unconditional, ~zero false-positive
+#     risk: anything under ``.codd`` is harness/contract STATE, never SUT source.
+#   * a path under ``codd/stack/`` is fenced ONLY when it is PROVENANCED as a
+#     project-local stack-contract file by the project's ``stack:`` declaration (a
+#     ``profiles:`` / ``proofs:`` / ``checkers:`` / ``obligations:`` / ``root:`` path it
+#     references) — NOT by a blind directory rule. A blind ``codd/stack/`` rule would
+#     wrongly fence real CoDD framework SOURCE (``codd/stack/compose.py``, ``lock.py``,
+#     ``command_plan.py``, …) whenever CoDD is the SUT, a genuine false-RED.
+#   * the ``stack:`` block of ``codd.yaml`` — fenced UNCONDITIONALLY when a patch to
+#     ``codd.yaml`` touches the ``stack:`` key (the existing whole-file oracle fence is
+#     gated on a code-addressable failure, leaving a non-code-addressable hole through
+#     which a repair could weaken the stack declaration; this closes it without
+#     disturbing the existing non-stack codd.yaml behaviour).
+_STACK_LOCK_BASENAME = "stack.lock"
+#: Canonical project-local stack-contract STATE root — always harness, never SUT.
+_STACK_STATE_DIR_MARKER: tuple[str, ...] = (".codd", "stack")
+#: ``codd.yaml`` keys whose declarations point at project-local stack-contract files
+#: (profiles / proof witnesses / checker / obligation sources / a contract root). A
+#: ``codd/stack/`` path is fenced only when it matches one of these declared paths.
+_STACK_DECL_PATH_KEYS: frozenset[str] = frozenset(
+    {"profiles", "proofs", "checkers", "obligations", "root", "roots", "profile_root", "proof_root"}
+)
+
 #: Test-file recognition (mirrors common conventions across stacks). Used to
 #: flag a patch that edits a TEST for a non-harness failure (B0 keeps those
 #: read-only; we enforce it against the actual proposal path even when the
@@ -167,15 +214,19 @@ def evaluate_auto_patch_scope(
     caller (the repair loop, in auto mode only) escalates/rejects on
     ``allowed=False``.
     """
-    patch_paths = [_normalize(patch.file_path) for patch in proposal.patches]
-    patch_paths = [path for path in patch_paths if path]
-    if not patch_paths:
+    patches = [p for p in proposal.patches if _normalize(p.file_path)]
+    if not patches:
         # An empty proposal is rejected upstream; nothing to scope-check.
         return AutoScopeDecision(allowed=True, reason="no patch paths to validate")
 
     failure_class = str(getattr(failure, "failure_class", "") or "")
     code_addressable = bool(getattr(failure, "code_addressable", False))
     allowlist = _editable_allowlist(failure, rca)
+    # Stack-contract path provenance from the project's ``stack:`` declaration (so a
+    # ``codd/stack/`` path is fenced only when the project actually declares it as a
+    # contract file — never a blind directory rule that would wrongly fence real CoDD
+    # framework source when CoDD is the SUT). Empty for a non-stack project.
+    declared_stack_paths = _declared_stack_contract_paths(codd_yaml)
     # Containment is enforced strictly ONLY when the primary failure resolved a
     # CONCRETE editable path set (B0 attribution of an executed test/typecheck
     # failure). A purely structural DAG failure carries logical node IDs
@@ -187,13 +238,16 @@ def evaluate_auto_patch_scope(
 
     offending: list[str] = []
     reasons: list[str] = []
-    for path in patch_paths:
+    for patch in patches:
+        path = _normalize(patch.file_path)
         verdict = _classify_path(
             path,
             failure_class=failure_class,
             code_addressable=code_addressable,
             allowlist=allowlist,
             enforce_containment=has_resolved_targets,
+            declared_stack_paths=declared_stack_paths,
+            patch_content=getattr(patch, "content", "") or "",
         )
         if verdict is not None:
             offending.append(path)
@@ -285,11 +339,20 @@ def _classify_path(
     code_addressable: bool,
     allowlist: set[str],
     enforce_containment: bool,
+    declared_stack_paths: frozenset[str] = frozenset(),
+    patch_content: str = "",
 ) -> str | None:
     """Return a rejection reason for *path*, or ``None`` when it is in-scope.
 
     Role precedence (most-protected first):
 
+    0. Stack contract artefact (``stack.lock`` / a ``codd/stack/`` profile /
+       obligation / checker) → reject UNCONDITIONALLY (Contract Kernel v2.77f).
+       A repair fixes SUT source to *satisfy* a stack obligation; it never edits
+       the stack contract (weaken / delete checker / no-op / refresh lock = a
+       silenced gate = false-green). No failure-class exception (unlike the oracle
+       fence): a stack artefact is never the thing an auto-repair legitimately
+       rewrites.
     1. Oracle / spec / gate-control artefact + a code-addressable failure →
        reject, UNLESS the failure class explicitly identifies THIS artefact as
        the defect (a harness-contract violation whose attribution named it).
@@ -302,6 +365,38 @@ def _classify_path(
        since the oracle/test protections above already block the false-green
        vector and structural source/doc drift repair is legitimate.
     """
+    # (0) Stack contract artefact protection — UNCONDITIONAL (Contract Kernel v2.77f).
+    # Checked FIRST and independent of failure_class / code_addressable: a repair must
+    # never edit the framework-stack contract (the definition of "pass" for the stack
+    # layer). The SUT-source fix path (satisfy/strengthen) stays open; only the
+    # contract artefacts themselves are fenced. Recognition is provenance-aware so it
+    # does NOT false-RED real CoDD framework source when CoDD is the SUT.
+    if _is_stack_contract_artifact(path, declared_stack_paths=declared_stack_paths):
+        return (
+            f"'{path}' is a STACK CONTRACT artefact (stack.lock / a .codd/stack or "
+            "declared project-local stack profile, obligation, checker, or proof witness); "
+            "auto-repair may fix SUT source to SATISFY a stack obligation but must NEVER "
+            "edit the stack contract itself — weakening an obligation, deleting a checker, "
+            "inserting a no-op command, refreshing the lock, or mutating a proof witness "
+            "would silence a stack gate (false-green). A stack drift is cleared by reverting "
+            "the contract change or an explicit proof-backed update, never by an unattended "
+            "repair (Contract Kernel v2.77f)."
+        )
+
+    # (0b) The ``stack:`` block of codd.yaml — fenced UNCONDITIONALLY when a patch to
+    # codd.yaml touches it. The whole-file oracle fence (rule 1) only engages for a
+    # code-addressable failure; this closes the non-code-addressable hole through which
+    # a repair could weaken the stack declaration, WITHOUT changing the existing
+    # non-stack codd.yaml behaviour (a codd.yaml patch that does not touch ``stack:`` is
+    # still handled by the oracle fence exactly as before).
+    if _is_codd_yaml(path) and _patch_touches_stack_block(patch_content):
+        return (
+            f"'{path}' patch modifies the codd.yaml `stack:` block (the project's stack "
+            "contract declaration); auto-repair must not alter the declared stack contract "
+            "(language/frameworks/addons/obligations) to clear a failure — that is the "
+            "weaken-the-contract false-green vector (Contract Kernel v2.77f)."
+        )
+
     is_oracle = _is_oracle_artifact(path)
     is_test = _is_test_file(path)
     harness_contract = failure_class == "harness_contract_violation"
@@ -346,6 +441,92 @@ def _classify_path(
     )
 
 
+def _is_stack_contract_artifact(
+    path: str, *, declared_stack_paths: frozenset[str] = frozenset()
+) -> bool:
+    """True for a framework-stack CONTRACT artefact (Contract Kernel v2.77f).
+
+    Provenance-aware (GPT-5.5 Pro consult 2026-06-21) to avoid false-REDs:
+
+    * the ``stack.lock`` basename anywhere — unconditional;
+    * any path under a ``.codd/stack/`` directory — unconditional (harness state);
+    * a path under ``codd/stack/`` ONLY when it matches a stack-contract file the
+      project's ``stack:`` declaration references (``declared_stack_paths``) — NOT a
+      blind directory rule (which would wrongly fence real CoDD framework source when
+      CoDD is the SUT).
+
+    The curated profiles ship INSIDE the codd PACKAGE (never in a project's working
+    tree). The ``stack:`` block of ``codd.yaml`` is fenced separately (a hunk-aware
+    check on a codd.yaml patch), not here.
+    """
+    pure = PurePosixPath(path)
+    if pure.name.lower() == _STACK_LOCK_BASENAME:
+        return True
+    parts_lower = tuple(part.lower() for part in pure.parts)
+    if _contains_subsequence(parts_lower, _STACK_STATE_DIR_MARKER):
+        return True
+    # Provenanced project-local stack-contract file (declared in codd.yaml's stack:).
+    return path in declared_stack_paths
+
+
+def _declared_stack_contract_paths(codd_yaml: Mapping[str, Any] | None) -> frozenset[str]:
+    """Project-local stack-contract file/dir paths declared in codd.yaml's ``stack:``.
+
+    Reads the ``stack:`` block and collects any path-valued entries under the
+    contract-source keys (:data:`_STACK_DECL_PATH_KEYS` — ``profiles`` / ``proofs`` /
+    ``checkers`` / ``obligations`` / ``root`` …). These are the project's OWN
+    stack-contract files; a ``codd/stack/`` patch path is fenced only when it matches
+    one (so real CoDD framework source is never fenced). A directory entry fences
+    everything under it. Empty for a non-stack project (the fence then keys only on the
+    ``stack.lock`` basename + ``.codd/stack/`` — neither of which affects a non-stack
+    repair). Best-effort + defensive: any malformed shape yields no extra paths.
+    """
+    if not isinstance(codd_yaml, Mapping):
+        return frozenset()
+    stack = codd_yaml.get("stack")
+    if not isinstance(stack, Mapping):
+        return frozenset()
+    collected: set[str] = set()
+
+    def _add_path_values(value: Any) -> None:
+        if isinstance(value, str):
+            norm = _normalize(value)
+            if norm:
+                collected.add(norm)
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                _add_path_values(item)
+        elif isinstance(value, Mapping):
+            for item in value.values():
+                _add_path_values(item)
+
+    for key in _STACK_DECL_PATH_KEYS:
+        if key in stack:
+            _add_path_values(stack[key])
+    return frozenset(collected)
+
+
+def _is_codd_yaml(path: str) -> bool:
+    name = PurePosixPath(path).name.lower()
+    return name in {"codd.yaml", "codd.yml"}
+
+
+def _patch_touches_stack_block(patch_content: str) -> bool:
+    """True when a codd.yaml patch references the ``stack:`` mapping key.
+
+    Conservative + content-based (works for both a full-file replacement and a unified
+    diff): a top-level or diff-added ``stack:`` line means the patch is shaping the
+    stack declaration. Matching ``(^|\\n)\\s*[+]?\\s*stack:`` catches a YAML key at any
+    indentation and a diff ``+stack:`` line. False-positives (a codd.yaml that merely
+    keeps an unrelated ``stack:`` line) are acceptable — auto-repair editing codd.yaml is
+    already the discouraged path, and a stack-declaring project's codd.yaml edit is far
+    better escalated to a human than silently applied.
+    """
+    if not patch_content:
+        return False
+    return bool(re.search(r"(^|\n)\s*\+?\s*stack\s*:", patch_content))
+
+
 def _is_oracle_artifact(path: str) -> bool:
     """True for spec/design/requirements docs + test-harness/gate-control files."""
     pure = PurePosixPath(path)

{codd_dev-2.93.0 → codd_dev-2.95.0}/codd/stack/command_plan.py

@@ -42,7 +42,7 @@ import os
 import subprocess  # noqa: S404 — argv comes from the trusted resolved stack contract, shell=False.
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Mapping, Protocol, Sequence
+from typing import Any, Mapping, Protocol, Sequence
 
 from codd.languages.profile import CommandSpec
 
@@ -105,17 +105,32 @@ def stack_command_evidence_path(slot: "StackCommandSlot", project_root: Path) ->
     return project_root / STACK_COMMAND_EVIDENCE_DIR / f"{safe}.stdout"
 
 
-def assert_stack_contract_clean(contract: ResolvedStackContract) -> None:
-    """Conflict gate (v2.77c): red on ANY composition conflict / unclean state.
-
-    Anti-false-green: a command collision, an unproved replace (a layer replacing
-    another's command with different argv and no ``replace_with_proof`` — exactly a
-    command conflict today), a semantic weaken (an addon lowering a framework
-    obligation's severity), an exclusive conflict, a deny, or any future conflict
-    kind makes the contract NOT clean → :class:`StackContractConflictError`. The
-    composer already records these as ``Conflict`` entries (it refuses last-wins);
-    this turns that record into a gate. Defensive triple-check (``conflicts`` /
-    ``is_clean`` / ``strict_ok``) so a flag desync can never sneak to green.
+def assert_stack_contract_clean(
+    contract: ResolvedStackContract,
+    *,
+    replacement_proofs: Any = None,
+) -> None:
+    """Conflict gate (v2.77c) + proof gate (v2.77f): red on ANY unclean state.
+
+    Anti-false-green: a command collision, an unproved/malformed replace, a semantic
+    weaken (an addon lowering a framework obligation's severity), an exclusive conflict,
+    a deny, or any future conflict kind makes the contract NOT clean →
+    :class:`StackContractConflictError`. The composer records these as ``Conflict``
+    entries (it refuses last-wins); this turns that record into a gate. Defensive
+    triple-check (``conflicts`` / ``is_clean`` / ``strict_ok``) so a flag desync can never
+    sneak to green.
+
+    Contract Kernel v2.77f — proof-backed replacements: a WELL-FORMED ``replace_with_proof``
+    is NOT a conflict; the composer records it as a
+    :class:`~codd.stack.replacement_proof.PendingReplacementProof`. Such a contract is NOT
+    clean until its behavioral proof has been EXECUTED and PASSED. So:
+
+    * ``contract.pending_replacement_proofs`` is non-empty AND ``replacement_proofs is
+      None`` → RED ("proof not executed"): a call-site that skips the proof gate can never
+      accidentally treat a pending replacement as clean (declaration-only is RED).
+    * ``replacement_proofs`` present but does not approve EVERY pending proof (matched by
+      *fingerprint*, not id) → RED ("proof failed / not approved").
+    * every pending proof approved by a passing result → the replacement is clean.
     """
     if contract.conflicts or not contract.is_clean or not contract.strict_ok:
         reasons = (
@@ -124,13 +139,38 @@ def assert_stack_contract_clean(contract: ResolvedStackContract) -> None:
         )
         raise StackContractConflictError(
             f"stack composition conflict ({contract.stack_id}): {reasons}. "
-            "A command collision / unproved replace / weakened obligation / exclusive "
-            "conflict is RED — the composer does NOT silently last-wins-merge a "
+            "A command collision / unproved-or-malformed replace / weakened obligation / "
+            "exclusive conflict is RED — the composer does NOT silently last-wins-merge a "
             "collision, and the run will not materialize a command plan from a "
-            "conflicted contract. Resolve the conflict in the stack profiles (or "
-            "declare an explicit replace_with_proof once that mechanism exists)."
+            "conflicted contract. Resolve the conflict in the stack profiles, or declare a "
+            "well-formed, proof-backed replace_with_proof."
         )
 
+    pending = tuple(getattr(contract, "pending_replacement_proofs", ()) or ())
+    if pending:
+        if replacement_proofs is None:
+            raise StackContractConflictError(
+                f"stack replacement proof not executed ({contract.stack_id}): the contract "
+                f"declares {len(pending)} proof-backed replacement(s) "
+                f"({', '.join(p.id for p in pending)}) but the behavioral proof gate was not "
+                "run. A replace_with_proof is NOT clean by declaration alone — RED until the "
+                "proof is executed and passes (anti-false-green: never accept a replacement on "
+                "syntax)."
+            )
+        if not replacement_proofs.approves_all(pending):
+            unapproved = [
+                p.id for p in pending if p.fingerprint not in replacement_proofs.approved
+            ]
+            viol = "; ".join(
+                f"{v.id}: {v.reason}" for v in getattr(replacement_proofs, "violations", ())
+            )
+            raise StackContractConflictError(
+                f"stack replacement proof failed ({contract.stack_id}): proof did not approve "
+                f"replacement(s) {unapproved} [{viol}]. A proof-backed replacement is GREEN "
+                "ONLY when its behavioral subsumption proof passes (the replacement catches "
+                "what the original caught) — RED otherwise."
+            )
+
 
 @dataclass(frozen=True)
 class StackCommandSlot:

{codd_dev-2.93.0 → codd_dev-2.95.0}/codd/stack/compose.py

@@ -70,13 +70,73 @@ class ResolvedLayerRef:
 
 @dataclass(frozen=True)
 class Conflict:
-    """A composition conflict the strict gate must red on (design §衝突解決)."""
+    """A composition conflict the strict gate must red on (design §衝突解決).
 
-    kind: Literal["exclusive", "command", "semantic"]
+    ``replace_with_proof`` is the Contract Kernel v2.77f kind: a layer DECLARED a
+    proof-backed replacement but the declaration is MALFORMED (bad schema / kind /
+    missing witness / cross-id). A WELL-FORMED declaration is NOT a conflict — it is a
+    pending proof (:attr:`ResolvedStackContract.pending_replacement_proofs`).
+    """
+
+    kind: Literal["exclusive", "command", "semantic", "replace_with_proof"]
     detail: str
     layers: tuple[str, ...] = ()
 
 
+#: Sentinel returned by :func:`_classify_replacement` when a well-formed
+#: ``replace_with_proof`` was recorded as a pending proof (so the caller records neither a
+#: command nor a semantic conflict for it).
+_REPLACEMENT_PENDING = object()
+
+
+def _classify_replacement(
+    *,
+    kind: str,
+    cid: str,
+    original: Any,
+    replacement: Any,
+    owner: str,
+    replacer: str,
+    pending_proofs: list[Any],
+) -> Any:
+    """Classify a same-id redefinition that carries (or lacks) a ``replace_with_proof``.
+
+    Returns one of:
+    * :data:`_REPLACEMENT_PENDING` — a WELL-FORMED declaration was found and appended to
+      ``pending_proofs`` (the caller records NO conflict; the proof gate decides clean).
+    * a :class:`Conflict` (``kind="replace_with_proof"``) — a declaration was present but
+      MALFORMED (anti-false-green: a broken proof declaration is RED, never accepted).
+    * ``None`` — no declaration; the caller falls back to its ordinary conflict.
+
+    Imported lazily to keep the dataclass/module load free of an import cycle (the
+    replacement_proof module imports profile types from this package).
+    """
+    from .replacement_proof import (
+        PendingReplacementProof,
+        ReplacementProofError,
+        extract_proof_declaration,
+    )
+
+    try:
+        decl = extract_proof_declaration(replacement, kind=kind)
+    except ReplacementProofError as exc:
+        return Conflict(
+            kind="replace_with_proof",
+            detail=(
+                f"{kind} {cid!r} declares a malformed replace_with_proof on {replacer} "
+                f"(owner {owner}): {exc}. A proof-backed replacement is RED unless its "
+                "declaration is well-formed AND its behavioral proof passes."
+            ),
+            layers=(owner, replacer),
+        )
+    if decl is None:
+        return None
+    pending_proofs.append(
+        PendingReplacementProof.build(kind, original, replacement, decl)
+    )
+    return _REPLACEMENT_PENDING
+
+
 @dataclass(frozen=True)
 class ResolvedStackContract:
     """The single contract the harness consumes (design §1 ResolvedStackContract).
@@ -111,6 +171,17 @@ class ResolvedStackContract:
     command_observation_policies: Mapping[str, Any] = field(
         default_factory=lambda: MappingProxyType({})
     )
+    #: Proof-backed replacements (Contract Kernel v2.77f). A command/obligation that
+    #: REPLACES another layer's via a well-formed ``codd.replace_with_proof`` is recorded
+    #: here as a :class:`~codd.stack.replacement_proof.PendingReplacementProof` INSTEAD of
+    #: an ordinary command/semantic Conflict — the replacement is NOT clean-by-syntax: it
+    #: is pending an EXECUTED behavioral-subsumption proof. ``is_clean``/``strict_ok`` are
+    #: about ordinary conflicts only; the proof gate
+    #: (``codd.stack.command_plan.assert_stack_contract_clean`` with a
+    #: ``ReplacementProofGateResult``) is what turns a pending proof GREEN. Typed loosely
+    #: (``Any``) to keep ``compose`` import-cycle-free at the dataclass level. Empty for the
+    #: curated stacks (no profile declares a replacement yet).
+    pending_replacement_proofs: tuple[Any, ...] = ()
 
     @property
     def is_clean(self) -> bool:
@@ -142,6 +213,7 @@ def _content_hash(
     obligations: Sequence[Obligation],
     file_roles: Sequence[FileRole],
     source_sets: Sequence[SourceSet],
+    pending_proofs: Sequence[Any] = (),
 ) -> str:
     canonical = {
         "layers": [[l.kind, l.id, l.profile_version] for l in layers],
@@ -149,6 +221,13 @@ def _content_hash(
         "obligations": sorted([o.id, o.severity] for o in obligations),
         "file_roles": sorted([r.pattern, r.role] for r in file_roles),
         "source_sets": sorted([s.id, s.root] for s in source_sets),
+        # Proof-backed replacements (Contract Kernel v2.77f gaming-vector #5): the proof
+        # DECLARATION must affect the content hash, so a changed witness/proof drifts the
+        # lock (a proof cannot silently change under a stable lock). Each pending proof's
+        # fingerprint already hashes (original, replacement, declaration).
+        "replacement_proofs": sorted(
+            getattr(p, "fingerprint", "") for p in (pending_proofs or ())
+        ),
     }
     payload = json.dumps(canonical, sort_keys=True, ensure_ascii=False)
     return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
@@ -177,6 +256,7 @@ def compose(
         )
 
     conflicts: list[Conflict] = []
+    pending_proofs: list[Any] = []
 
     # -- commands (language base; frameworks/addons add their own slots) --------
     commands: dict[str, CommandSpec] = dict(language.commands)
@@ -189,11 +269,28 @@ def compose(
                 command_owners[cid] = f"{kind}:{prof.id}"
                 continue
             # Collision. Identical argv → harmless (same command). Different argv →
-            # a layer is replacing another's command. For a verification slot this
-            # is a hard conflict (no silent weakening); elsewhere too (must be an
-            # explicit replace_with_proof, which no profile declares yet).
+            # a layer is replacing another's command.
             if tuple(commands[cid].argv) == tuple(spec.argv):
                 continue
+            # A different-argv redefinition is a hard conflict UNLESS the replacing layer
+            # carries a well-formed ``replace_with_proof`` (Contract Kernel v2.77f). Then
+            # it is recorded as a PendingReplacementProof — NOT clean-by-syntax: the proof
+            # gate must execute the behavioral subsumption before the contract is clean. A
+            # MALFORMED declaration is its own RED (``replace_with_proof`` conflict kind).
+            proof_conflict = _classify_replacement(
+                kind="command",
+                cid=cid,
+                original=commands[cid],
+                replacement=spec,
+                owner=command_owners[cid],
+                replacer=f"{kind}:{prof.id}",
+                pending_proofs=pending_proofs,
+            )
+            if proof_conflict is _REPLACEMENT_PENDING:
+                continue  # recorded as a pending proof; do NOT also record a conflict
+            if proof_conflict is not None:
+                conflicts.append(proof_conflict)
+                continue
             conflicts.append(
                 Conflict(
                     kind="command",
@@ -255,6 +352,28 @@ def compose(
                     )
                 )
             elif _normalize_checker_ref(obl.checker) != _normalize_checker_ref(existing.checker):
+                # A same-severity, different-CHECKER redefinition. This may be a legitimate
+                # proof-backed replacement (a stronger/equivalent checker) IFF the new
+                # checker is REAL (non-empty) AND a well-formed replace_with_proof is
+                # declared. A null/empty new checker can NEVER be proof-rescued (you cannot
+                # prove subsumption with no checker — it would be an unenforced RED anyway),
+                # so that path stays a hard semantic conflict.
+                proof_outcome = None
+                if _normalize_checker_ref(obl.checker):  # new checker is non-empty
+                    proof_outcome = _classify_replacement(
+                        kind="obligation",
+                        cid=obl.id,
+                        original=existing,
+                        replacement=obl,
+                        owner=obligation_owners[obl.id],
+                        replacer=f"{kind}:{prof.id}",
+                        pending_proofs=pending_proofs,
+                    )
+                if proof_outcome is _REPLACEMENT_PENDING:
+                    continue  # recorded as a pending proof; no conflict
+                if proof_outcome is not None:
+                    conflicts.append(proof_outcome)
+                    continue
                 conflicts.append(
                     Conflict(
                         kind="semantic",
@@ -265,7 +384,8 @@ def compose(
                             "a same-id checker-ref change is a semantic conflict (it would "
                             "silently keep one checker and discard the other); two different "
                             "checks need two different obligation ids, the same check needs "
-                            "the same checker ref"
+                            "the same checker ref (or an explicit, proof-backed "
+                            "replace_with_proof)"
                         ),
                         layers=(obligation_owners[obl.id], f"{kind}:{prof.id}"),
                     )
@@ -308,7 +428,9 @@ def compose(
     }
 
     stack_id = "+".join(l.id for l in layers)
-    content_hash = _content_hash(layers, commands, obligations, file_roles, source_sets)
+    content_hash = _content_hash(
+        layers, commands, obligations, file_roles, source_sets, pending_proofs
+    )
 
     return ResolvedStackContract(
         stack_id=stack_id,
@@ -324,4 +446,5 @@ def compose(
         variants=MappingProxyType(dict(variants)),
         conflicts=tuple(conflicts),
         content_hash=content_hash,
+        pending_replacement_proofs=tuple(pending_proofs),
     )