Skip to content

Frappucc1no/recall-loom / skills/recallloom

recallloom

Flagged

Use when a task involves continuing a project, restoring project context, maintaining file-based project memory, updating current-state summaries, or recording meaningful progress across sessions. Works best for long-horizon, file-based projects and supports research writing, product document collaboration, software project coordination, and broader cross-functional project continuity.

FileKindSize
LICENSEother10.0 KB
NOTICEother190 B
SKILL.mdskill md24.5 KB
managed-assets.jsonconfig1.1 KB
native_commands/README.mdmarkdown1.2 KB
native_commands/claude-code/rl-init.md.tmplother323 B
native_commands/claude-code/rl-resume.md.tmplother290 B
native_commands/claude-code/rl-status.md.tmplother299 B
native_commands/claude-code/rl-validate.md.tmplother277 B
native_commands/gemini-cli/rl-init.toml.tmplother295 B
native_commands/gemini-cli/rl-resume.toml.tmplother262 B
native_commands/gemini-cli/rl-status.toml.tmplother271 B
native_commands/gemini-cli/rl-validate.toml.tmplother249 B
native_commands/opencode/rl-init.md.tmplother286 B
native_commands/opencode/rl-resume.md.tmplother253 B
native_commands/opencode/rl-status.md.tmplother262 B
native_commands/opencode/rl-validate.md.tmplother240 B
package-metadata.jsonconfig1.0 KB
profiles/general-project-continuity.mdmarkdown2.4 KB
profiles/product-doc-collaboration.mdmarkdown2.2 KB
profiles/research-writing.mdmarkdown2.1 KB
profiles/software-project-coordination.mdmarkdown2.8 KB
references/anti-patterns.mdmarkdown2.5 KB
references/contract-registry.jsonconfig7.7 KB
references/contract-schema.jsonconfig7.7 KB
references/file-contracts.mdmarkdown23.4 KB
references/operation-playbooks.mdmarkdown26.5 KB
references/package-support-policy.mdmarkdown9.4 KB
references/profiles.mdmarkdown2.0 KB
references/protocol.mdmarkdown20.5 KB
references/recording-workflow.mdmarkdown9.9 KB
scripts/_common.pyscript87.8 KB
scripts/append_daily_log_entry.pyscript40.4 KB
scripts/archive_logs.pyscript17.6 KB
scripts/commit_context_file.pyscript31.6 KB
scripts/core/__init__.pyscript39 B
scripts/core/bridge/__init__.pyscript30 B
scripts/core/bridge/blocks.pyscript6.9 KB
scripts/core/coldstart/__init__.pyscript26 B
scripts/core/coldstart/sources.pyscript22.4 KB
scripts/core/coldstart/structured.pyscript5.4 KB
scripts/core/continuity/__init__.pyscript34 B
scripts/core/continuity/daily_log.pyscript16.1 KB
scripts/core/continuity/freshness.pyscript15.3 KB
scripts/core/continuity/preflight.pyscript41.0 KB
scripts/core/continuity/quick_summary.pyscript10.9 KB
scripts/core/continuity/workday.pyscript12.3 KB
scripts/core/errors.pyscript838 B
scripts/core/failure/__init__.pyscript47 B
scripts/core/failure/context.pyscript5.6 KB
scripts/core/failure/contracts.pyscript108.6 KB
scripts/core/output/__init__.pyscript35 B
scripts/core/output/confirmation_material.pyscript15.0 KB
scripts/core/output/privacy.pyscript10.5 KB
scripts/core/output/user_status.pyscript5.8 KB
scripts/core/protocol/__init__.pyscript60 B
scripts/core/protocol/contracts.pyscript8.3 KB
scripts/core/protocol/markers.pyscript4.9 KB
scripts/core/protocol/sections.pyscript3.4 KB
scripts/core/protocol/templates.pyscript6.5 KB
scripts/core/provenance/__init__.pyscript67 B
scripts/core/provenance/bindings.pyscript13.2 KB
scripts/core/provenance/evidence.pyscript58.2 KB
scripts/core/provenance/inconsistent_review.pyscript85.6 KB
scripts/core/provenance/receipts.pyscript20.2 KB
scripts/core/provenance/state.pyscript38.0 KB
scripts/core/provenance/store.pyscript43.8 KB
scripts/core/recording/__init__.pyscript1.6 KB
scripts/core/recording/contracts.pyscript31.7 KB
scripts/core/recording/daily_log_append.pyscript30.2 KB
scripts/core/recording/managed_write.pyscript52.8 KB
scripts/core/recording/planner.pyscript20.6 KB
scripts/core/recording/privacy.pyscript1.7 KB
scripts/core/recording/suggestions.pyscript8.6 KB
scripts/core/recording/transaction.pyscript93.3 KB
scripts/core/registry/__init__.pyscript58 B
scripts/core/registry/loader.pyscript18.8 KB
scripts/core/safety/__init__.pyscript30 B
scripts/core/safety/attached_text.pyscript6.9 KB
scripts/core/safety/input_transport.pyscript61.0 KB
scripts/core/safety/prepared_input.pyscript24.4 KB
scripts/core/safety/scratch_residue.pyscript18.8 KB
scripts/core/support/__init__.pyscript53 B
scripts/core/support/cache.pyscript19.4 KB
scripts/core/support/policy.pyscript8.8 KB
scripts/core/trust/__init__.pyscript42 B
scripts/core/trust/state.pyscript4.1 KB
scripts/core/workspace/__init__.pyscript33 B
scripts/core/workspace/atomic_io.pyscript12.2 KB
scripts/core/workspace/runtime.pyscript54.7 KB
scripts/detect_project_root.pyscript3.4 KB
scripts/generate_coldstart_proposal.pyscript7.5 KB
scripts/init_context.pyscript37.8 KB
scripts/install_native_commands.pyscript31.5 KB
scripts/manage_entry_bridge.pyscript20.8 KB
scripts/preflight_context_check.pyscript10.1 KB
scripts/prepare_recovery_promotion.pyscript22.1 KB
scripts/query_continuity.pyscript84.1 KB
scripts/recallloom.pyscript233.7 KB
scripts/recommend_workday.pyscript17.6 KB
scripts/record_recovery_review.pyscript50.9 KB
scripts/remove_context.pyscript13.9 KB
scripts/repair_daily_log_cursor.pyscript33.7 KB
scripts/stage_recovery_proposal.pyscript17.5 KB
scripts/summarize_continuity_status.pyscript43.7 KB
scripts/sync_contract_docs.pyscript11.3 KB
scripts/unlock_write_lock.pyscript8.1 KB
scripts/validate_context.pyscript54.9 KB

scripts/core/provenance/state.py

View on GitHub
"""Stable provenance state labels and write-readiness routing helpers."""

from __future__ import annotations

import hashlib
import json
from collections.abc import Mapping
from typing import Any

from core.provenance.receipts import receipt_contract_identity


PROVENANCE_CONTRACT_VERSION = "0.4.2-mvp.2"
PROVENANCE_METADATA_SCHEMA_VERSION = "0.4.2-mvp.1"

PROVENANCE_STATE_LABELS = (
    "structurally_valid",
    "helper_evidenced",
    "review_imported_baseline",
    "unproven_sidecar_state",
    "inconsistent_or_tampered_evidence",
)

TRANSIT_ONLY_LEGACY_PROVENANCE_STATES = (
    "structurally_valid_legacy",
    "review_required",
)

NON_RECEIPT_BACKED_STRUCTURAL_REPAIR_KINDS = (
    "daily_log_cursor_repair",
)

CURSOR_REPAIR_BLOCKING_REASON_CODES = (
    "legacy_import_review_required",
    "provenance_evidence_inconsistent",
    "receipt_evidence_mismatch",
    "direct_state_or_config_edit_detected",
    "metadata_state_review_required",
)

PROVENANCE_ACTION_MATRIX = {
    "structurally_valid": {
        "allowed_actions": [
            "read_continuity",
            "run_preflight",
            "prepare_revision_checked_helper_write",
            "run_existing_revision_checked_helper_write_after_preflight",
        ],
        "blocked_actions": [
            "claim_receipt_backed_provenance",
            "skip_preflight",
            "write_receipt_store",
            "finalize_mutating_receipt",
        ],
        "write_readiness": "structural_only",
        "ux_gate": "warn",
        "ux_gate_requires_confirmation": False,
        "ux_gate_waivable": True,
        "ux_gate_reason": "structural_only_state",
        "note": (
            "Managed files and cursors are structurally readable, but no helper receipt "
            "chain has been verified."
        ),
    },
    "helper_evidenced": {
        "allowed_actions": [
            "read_continuity",
            "run_preflight",
            "prepare_revision_checked_helper_write",
            "run_existing_revision_checked_helper_write_after_preflight",
            "claim_helper_evidenced",
        ],
        "blocked_actions": [
            "skip_preflight",
            "write_receipt_store_without_redaction_contract",
        ],
        "write_readiness": "helper_evidenced",
        "ux_gate": "allow",
        "ux_gate_requires_confirmation": False,
        "ux_gate_waivable": True,
        "ux_gate_reason": "helper_evidenced_state",
        "note": "Structural state is backed by helper receipt evidence.",
    },
    "review_imported_baseline": {
        "allowed_actions": [
            "read_continuity",
            "run_preflight",
            "review_imported_baseline",
            "run_existing_revision_checked_helper_write_after_preflight",
        ],
        "blocked_actions": [
            "claim_receipt_backed_provenance_from_import",
            "run_mutating_helper_write_without_fresh_preflight",
            "finalize_import_receipt_as_helper_evidence",
        ],
        "write_readiness": "review_first",
        "ux_gate": "ask",
        "ux_gate_requires_confirmation": True,
        "ux_gate_waivable": True,
        "ux_gate_reason": "review_imported_baseline",
        "note": (
            "Imported baseline was reviewed; a later revision-checked helper write may "
            "claim helper evidence only after its own receipt finalizes."
        ),
    },
    "unproven_sidecar_state": {
        "allowed_actions": [
            "read_continuity",
            "run_preflight",
            "refresh_or_validate_sidecar_state",
            "run_existing_revision_checked_helper_write_after_preflight",
        ],
        "blocked_actions": [
            "claim_receipt_backed_provenance",
            "skip_preflight",
            "run_mutating_helper_write_without_fresh_preflight",
            "finalize_mutating_receipt",
        ],
        "write_readiness": "unproven",
        "ux_gate": "warn",
        "ux_gate_requires_confirmation": False,
        "ux_gate_waivable": True,
        "ux_gate_reason": "unproven_sidecar_state",
        "note": "Sidecar state is readable but not currently proven enough for evidence-sensitive writes.",
    },
    "inconsistent_or_tampered_evidence": {
        "allowed_actions": [
            "read_diagnostic_output",
            "run_validate",
            "prepare_repair_review",
        ],
        "blocked_actions": [
            "claim_receipt_backed_provenance",
            "run_preflight_as_write_authority",
            "run_mutating_helper_write",
            "finalize_mutating_receipt",
        ],
        "write_readiness": "blocked",
        "ux_gate": "block",
        "ux_gate_requires_confirmation": False,
        "ux_gate_waivable": False,
        "ux_gate_reason": "inconsistent_or_tampered_evidence",
        "note": "Evidence or structural state is inconsistent; repair and validate before writing.",
    },
    "structurally_valid_legacy": {
        "allowed_actions": ["read_continuity", "run_preflight"],
        "blocked_actions": [
            "persist_legacy_state_label",
            "claim_receipt_backed_provenance",
            "finalize_mutating_receipt",
            "run_mutating_helper_write_without_review_import",
        ],
        "write_readiness": "readable_legacy",
        "ux_gate": "warn",
        "ux_gate_requires_confirmation": False,
        "ux_gate_waivable": True,
        "ux_gate_reason": "readable_legacy_state",
        "note": (
            "Legacy sidecar is structurally readable, but write authority requires "
            "explicit review or repair import."
        ),
    },
    "review_required": {
        "allowed_actions": ["read_continuity", "run_preflight", "manual_review"],
        "blocked_actions": [
            "persist_legacy_state_label",
            "claim_receipt_backed_provenance",
            "run_mutating_helper_write_without_review",
        ],
        "write_readiness": "review_required",
        "ux_gate": "ask",
        "ux_gate_requires_confirmation": True,
        "ux_gate_waivable": True,
        "ux_gate_reason": "legacy_review_required",
        "note": "Legacy or imported state must be reviewed before any mutating helper write.",
    },
}

_STRUCTURAL_SIDECAR_STATES = {"structurally_valid"}
_INCONSISTENT_SIDECAR_STATES = {"damaged", "conflicting", "security_blocked"}


def normalize_provenance_state(label: str | None) -> str:
    if label == "structurally_valid_legacy":
        return "structurally_valid"
    if label == "review_required":
        return "unproven_sidecar_state"
    if label in PROVENANCE_STATE_LABELS:
        return label
    return "unproven_sidecar_state"


def initial_provenance_metadata(*, timestamp: str) -> dict:
    return {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "structurally_valid",
        "baseline_kind": "helper_initialized",
        "updated_at": timestamp,
    }


def review_imported_baseline_metadata(
    *,
    timestamp: str,
    review_action: str,
    proposal_digest: str | None = None,
    review_digest: str | None = None,
) -> dict:
    payload = {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "review_imported_baseline",
        "baseline_kind": "review_import",
        "review_action": review_action,
        "updated_at": timestamp,
        "receipt_backed": False,
    }
    if proposal_digest is not None:
        payload["proposal_digest"] = proposal_digest
    if review_digest is not None:
        payload["review_digest"] = review_digest
    return payload


def inconsistent_review_imported_baseline_metadata(
    *,
    timestamp: str,
    review_action: str,
    source_reason_code: str,
    inconsistent_review_binding: Mapping[str, Any],
    inconsistent_review_binding_digest: str,
    proposal_digest: str,
    review_digest: str,
) -> dict:
    if review_action != "accept":
        raise ValueError("D5 reviewed-baseline metadata requires an accept review action.")
    if source_reason_code not in {"post_hash_read_failed", "post_hash_mismatch"}:
        raise ValueError("D5 reviewed-baseline metadata has an invalid source reason.")
    if not (
        isinstance(inconsistent_review_binding_digest, str)
        and len(inconsistent_review_binding_digest) == 71
        and inconsistent_review_binding_digest.startswith("sha256:")
        and all(
            character in "0123456789abcdef"
            for character in inconsistent_review_binding_digest[7:]
        )
    ):
        raise ValueError("D5 reviewed-baseline metadata has an invalid binding digest.")
    if not isinstance(inconsistent_review_binding, Mapping):
        raise ValueError("D5 reviewed-baseline metadata requires the exact binding object.")
    binding_payload = dict(inconsistent_review_binding)
    canonical_binding_digest = "sha256:" + hashlib.sha256(
        json.dumps(
            binding_payload,
            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
            allow_nan=False,
        ).encode("utf-8")
    ).hexdigest()
    if canonical_binding_digest != inconsistent_review_binding_digest:
        raise ValueError("D5 reviewed-baseline metadata binding does not match its digest.")
    for field_name, digest in (
        ("proposal_digest", proposal_digest),
        ("review_digest", review_digest),
    ):
        if not (
            isinstance(digest, str)
            and len(digest) == 64
            and all(character in "0123456789abcdef" for character in digest)
        ):
            raise ValueError(
                f"D5 reviewed-baseline metadata has an invalid {field_name}."
            )
    return {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "review_imported_baseline",
        "baseline_kind": "review_import",
        "review_action": review_action,
        "updated_at": timestamp,
        "receipt_backed": False,
        "proposal_digest": proposal_digest,
        "review_digest": review_digest,
        "source_state_label": "inconsistent_or_tampered_evidence",
        "source_reason_code": source_reason_code,
        "inconsistent_review_binding": binding_payload,
        "inconsistent_review_binding_digest": inconsistent_review_binding_digest,
    }


def helper_evidenced_metadata(
    *,
    timestamp: str,
    previous_state_label: str | None = None,
) -> dict:
    payload = {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "helper_evidenced",
        "baseline_kind": "helper_receipt_finalized",
        "updated_at": timestamp,
        "receipt_backed": True,
    }
    if previous_state_label is not None:
        payload["previous_state_label"] = previous_state_label
    return payload


def unproven_sidecar_metadata(
    *,
    timestamp: str,
    reason_code: str,
    previous_state_label: str | None = None,
) -> dict:
    payload = {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "unproven_sidecar_state",
        "baseline_kind": "receipt_evidence_incomplete",
        "updated_at": timestamp,
        "receipt_backed": False,
        "reason_code": reason_code,
    }
    if previous_state_label is not None:
        payload["previous_state_label"] = previous_state_label
    return payload


def inconsistent_evidence_metadata(
    *,
    timestamp: str,
    reason_code: str,
    previous_state_label: str | None = None,
) -> dict:
    payload = {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "inconsistent_or_tampered_evidence",
        "baseline_kind": "receipt_evidence_inconsistent",
        "updated_at": timestamp,
        "receipt_backed": False,
        "reason_code": reason_code,
    }
    if previous_state_label is not None:
        payload["previous_state_label"] = previous_state_label
    return payload


def _state_provenance_metadata(state: Mapping[str, Any] | None) -> Mapping[str, Any] | None:
    if not isinstance(state, Mapping):
        return None
    metadata = state.get("provenance")
    return metadata if isinstance(metadata, Mapping) else None


def _copy_current_provenance_metadata(
    state: Mapping[str, Any] | None,
    *,
    fallback_state_label: str,
    fallback_baseline_kind: str,
    fallback_receipt_backed: bool,
) -> dict:
    metadata = _state_provenance_metadata(state)
    if (
        metadata is not None
        and metadata.get("schema_version") == PROVENANCE_METADATA_SCHEMA_VERSION
        and metadata.get("state_label") in PROVENANCE_STATE_LABELS
    ):
        return dict(metadata)
    return {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": fallback_state_label,
        "baseline_kind": fallback_baseline_kind,
        "receipt_backed": fallback_receipt_backed,
    }


def _with_structural_repair_marker(
    metadata: Mapping[str, Any],
    *,
    timestamp: str,
    repair_kind: str,
    previous_state_label: str | None,
    reason_code: str | None,
    trust_effect: str,
) -> dict:
    payload = dict(metadata)
    payload["updated_at"] = timestamp
    payload["last_structural_repair"] = {
        "repair_kind": repair_kind,
        "receipt_backed": False,
        "finalizes_mutating_receipt": False,
        "updated_at": timestamp,
        "trust_effect": trust_effect,
    }
    if previous_state_label is not None:
        payload["last_structural_repair"]["previous_state_label"] = previous_state_label
    if reason_code is not None:
        payload["last_structural_repair"]["reason_code"] = reason_code
        payload["reason_code"] = reason_code
    return payload


def structural_repair_metadata(
    *,
    timestamp: str,
    repair_kind: str,
    previous_state_label: str | None = None,
    reason_code: str | None = None,
) -> dict:
    """Return non receipt-backed metadata for a structural sidecar repair."""

    payload = {
        "schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_label": "structurally_valid",
        "baseline_kind": "structural_repair",
        "updated_at": timestamp,
        "receipt_backed": False,
    }
    if previous_state_label is not None:
        payload["previous_state_label"] = previous_state_label
    if reason_code is not None:
        payload["reason_code"] = reason_code
    return _with_structural_repair_marker(
        payload,
        timestamp=timestamp,
        repair_kind=repair_kind,
        previous_state_label=previous_state_label,
        reason_code=reason_code,
        trust_effect="structural_only",
    )


def provenance_facts_from_state(
    state: Mapping[str, Any] | None,
    *,
    review_intent: bool = False,
) -> dict:
    if not isinstance(state, Mapping):
        return {
            "metadata_status": "state_unavailable",
            "legacy_sidecar": False,
            "review_required": True,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }

    metadata = state.get("provenance")
    if not isinstance(metadata, Mapping):
        return {
            "metadata_status": "legacy_metadata_missing",
            "legacy_sidecar": not review_intent,
            "review_required": review_intent,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }

    schema_version = metadata.get("schema_version")
    state_label = metadata.get("state_label")
    if schema_version != PROVENANCE_METADATA_SCHEMA_VERSION:
        return {
            "metadata_status": "metadata_schema_review_required",
            "legacy_sidecar": False,
            "review_required": True,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }
    if state_label == "helper_evidenced":
        return {
            "metadata_status": "helper_evidenced",
            "legacy_sidecar": False,
            "review_required": False,
            "review_imported_baseline": False,
            "helper_evidenced": True,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }
    if state_label == "review_imported_baseline":
        return {
            "metadata_status": "review_imported_baseline",
            "legacy_sidecar": False,
            "review_required": False,
            "review_imported_baseline": True,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }
    if state_label == "structurally_valid":
        return {
            "metadata_status": "current_structural_baseline",
            "legacy_sidecar": False,
            "review_required": False,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": False,
        }
    if state_label == "unproven_sidecar_state":
        return {
            "metadata_status": "unproven_sidecar_state",
            "legacy_sidecar": False,
            "review_required": False,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": False,
            "unproven_sidecar_state": True,
        }
    if state_label == "inconsistent_or_tampered_evidence":
        return {
            "metadata_status": "inconsistent_or_tampered_evidence",
            "legacy_sidecar": False,
            "review_required": False,
            "review_imported_baseline": False,
            "helper_evidenced": False,
            "inconsistent_evidence": True,
            "unproven_sidecar_state": False,
        }
    return {
        "metadata_status": "metadata_state_review_required",
        "legacy_sidecar": False,
        "review_required": True,
        "review_imported_baseline": False,
        "helper_evidenced": False,
        "inconsistent_evidence": False,
        "unproven_sidecar_state": False,
    }


def bounded_evidence_supports_helper_evidenced(
    state: Mapping[str, Any] | None,
    *,
    bounded_receipt_evidence_verified: bool = False,
    receipt_store_available: bool = False,
) -> bool:
    """Return whether current bounded evidence can preserve helper evidence.

    This is a current-state check only. It is not a historical receipt-chain audit.
    """

    provenance_facts = provenance_facts_from_state(state, review_intent=True)
    return bool(
        provenance_facts["helper_evidenced"]
        and bounded_receipt_evidence_verified
        and receipt_store_available
    )


def cursor_repair_provenance_decision(
    state: Mapping[str, Any] | None,
    *,
    timestamp: str,
    bounded_evidence_supports_helper_evidenced: bool = False,
    repair_kind: str = "daily_log_cursor_repair",
    evidence_block_reason_code: str | None = None,
) -> dict:
    """Decide provenance metadata for non receipt-backed daily-log cursor repair.

    `evidence_block_reason_code` is for independent safety findings such as receipt
    mismatch, direct state/config edits, or tampered evidence. A plain cursor
    mismatch that this helper is repairing should not be passed as that reason.
    """

    if repair_kind not in NON_RECEIPT_BACKED_STRUCTURAL_REPAIR_KINDS:
        raise ValueError(f"Unsupported structural repair kind: {repair_kind}")

    metadata = _state_provenance_metadata(state)
    previous_state_label = (
        metadata.get("state_label")
        if isinstance(metadata, Mapping) and isinstance(metadata.get("state_label"), str)
        else None
    )
    provenance_facts = provenance_facts_from_state(state, review_intent=True)
    result = {
        "allowed": True,
        "repair_kind": repair_kind,
        "receipt_backed": False,
        "receipt_store_write_allowed": False,
        "finalizes_mutating_receipt": False,
        "requires_full_receipt_chain_audit": False,
        "bounded_evidence_supports_helper_evidenced": bounded_evidence_supports_helper_evidenced,
        "previous_state_label": previous_state_label,
        "metadata_status": provenance_facts["metadata_status"],
        "blocked_reason_code": None,
        "route": "apply_structural_repair",
    }

    if evidence_block_reason_code is not None:
        return {
            **result,
            "allowed": False,
            "blocked_reason_code": evidence_block_reason_code,
            "route": "validate_and_repair_review",
            "result_state_label": "inconsistent_or_tampered_evidence",
            "provenance_metadata": None,
            "trust_effect": "none",
            "note": (
                "Structural repair must not proceed while independent evidence checks "
                "report tampering, receipt mismatch, or direct state/config edits."
            ),
        }

    if provenance_facts["inconsistent_evidence"]:
        return {
            **result,
            "allowed": False,
            "blocked_reason_code": "provenance_evidence_inconsistent",
            "route": "validate_and_repair_review",
            "result_state_label": "inconsistent_or_tampered_evidence",
            "provenance_metadata": None,
            "trust_effect": "none",
            "note": "Inconsistent provenance evidence must be reviewed before repair.",
        }

    if provenance_facts["review_required"] or provenance_facts["legacy_sidecar"]:
        return {
            **result,
            "allowed": False,
            "blocked_reason_code": "legacy_import_review_required",
            "route": "review_or_repair_import",
            "result_state_label": "review_required",
            "provenance_metadata": None,
            "trust_effect": "none",
            "note": "Legacy or unknown provenance must route through review/repair import first.",
        }

    if provenance_facts["review_imported_baseline"]:
        preserved = _copy_current_provenance_metadata(
            state,
            fallback_state_label="review_imported_baseline",
            fallback_baseline_kind="review_import",
            fallback_receipt_backed=False,
        )
        preserved["state_label"] = "review_imported_baseline"
        preserved["receipt_backed"] = False
        metadata_payload = _with_structural_repair_marker(
            preserved,
            timestamp=timestamp,
            repair_kind=repair_kind,
            previous_state_label=previous_state_label,
            reason_code="review_imported_baseline_preserved",
            trust_effect="structural_only",
        )
        return {
            **result,
            "result_state_label": "review_imported_baseline",
            "provenance_metadata": metadata_payload,
            "trust_effect": "structural_only",
            "note": "Reviewed import baseline is preserved as non receipt-backed provenance.",
        }

    if provenance_facts["helper_evidenced"] and bounded_evidence_supports_helper_evidenced:
        preserved = _copy_current_provenance_metadata(
            state,
            fallback_state_label="helper_evidenced",
            fallback_baseline_kind="helper_receipt_finalized",
            fallback_receipt_backed=True,
        )
        preserved["state_label"] = "helper_evidenced"
        preserved["receipt_backed"] = True
        metadata_payload = _with_structural_repair_marker(
            preserved,
            timestamp=timestamp,
            repair_kind=repair_kind,
            previous_state_label=previous_state_label,
            reason_code="bounded_evidence_preserved_helper_evidenced",
            trust_effect="helper_evidence_preserved_by_bounded_check",
        )
        return {
            **result,
            "result_state_label": "helper_evidenced",
            "provenance_metadata": metadata_payload,
            "trust_effect": "helper_evidence_preserved_by_bounded_check",
            "note": (
                "Helper-evidenced provenance is preserved only because current bounded "
                "evidence independently supports it."
            ),
        }

    reason_code = (
        "bounded_evidence_missing_for_helper_evidenced"
        if provenance_facts["helper_evidenced"]
        else "non_receipt_backed_structural_repair"
    )
    metadata_payload = structural_repair_metadata(
        timestamp=timestamp,
        repair_kind=repair_kind,
        previous_state_label=previous_state_label,
        reason_code=reason_code,
    )
    return {
        **result,
        "result_state_label": "structurally_valid",
        "provenance_metadata": metadata_payload,
        "trust_effect": "structural_only",
        "note": (
            "Cursor repair restores structural cursor metadata only; it does not prove "
            "historical daily-log origin or finalize helper receipt evidence."
        ),
    }


def classify_provenance_state(
    *,
    sidecar_trust_state: str | None,
    continuity_state: str | None = None,
    receipt_chain_verified: bool = False,
    receipt_store_available: bool = False,
    imported_baseline_review_required: bool = False,
    helper_evidenced_baseline: bool = False,
    legacy_sidecar: bool = False,
    review_required: bool = False,
    review_imported_baseline: bool = False,
    unproven_sidecar_state: bool = False,
) -> str:
    if sidecar_trust_state in _INCONSISTENT_SIDECAR_STATES:
        return "inconsistent_or_tampered_evidence"
    if receipt_chain_verified and receipt_store_available:
        return "helper_evidenced"
    if imported_baseline_review_required or review_imported_baseline:
        return "review_imported_baseline"
    if unproven_sidecar_state:
        return "unproven_sidecar_state"
    if review_required or sidecar_trust_state == "review_required":
        return "review_required"
    if legacy_sidecar or sidecar_trust_state == "structurally_valid_legacy":
        return "structurally_valid_legacy"
    if sidecar_trust_state in _STRUCTURAL_SIDECAR_STATES:
        return "structurally_valid"
    if continuity_state == "initialized_empty_shell":
        return "unproven_sidecar_state"
    return "unproven_sidecar_state"


def provenance_contract_identity() -> dict:
    payload = {
        "contract_version": PROVENANCE_CONTRACT_VERSION,
        "metadata_schema_version": PROVENANCE_METADATA_SCHEMA_VERSION,
        "state_labels": PROVENANCE_STATE_LABELS,
        "transit_only_legacy_states": TRANSIT_ONLY_LEGACY_PROVENANCE_STATES,
        "action_matrix": PROVENANCE_ACTION_MATRIX,
        "receipt_contract": receipt_contract_identity(),
    }
    digest = hashlib.sha256(
        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
    ).hexdigest()
    return {
        "contract_name": "recallloom.provenance_core",
        "contract_version": PROVENANCE_CONTRACT_VERSION,
        "contract_hash": f"sha256:{digest}",
    }


def legacy_v046_pre_recording_provenance_contract_identity() -> dict:
    """Return the v0.4.6 pre-recording identity accepted for stored receipts."""

    return {
        "contract_name": "recallloom.provenance_core",
        "contract_version": PROVENANCE_CONTRACT_VERSION,
        "contract_hash": "sha256:48dfffb1deaa3d8421c93b22fa9af727658efc1bf9e153e52c18713b6411b0ba",
    }


def legacy_v0462_v047_recording_provenance_contract_identity() -> dict:
    """Return the v0.4.6.2-v0.4.7 recording identity accepted for stored receipts."""

    return {
        "contract_name": "recallloom.provenance_core",
        "contract_version": PROVENANCE_CONTRACT_VERSION,
        "contract_hash": "sha256:32dc910571669b3ae3097968b879a9ea7b75dc0f141dd0f7ea8b415e4f363c5e",
    }


def accepted_preflight_contract_identities_for_receipts() -> tuple[dict, ...]:
    """Return preflight identities accepted for already-finalized receipts."""

    return (
        provenance_contract_identity(),
        legacy_v046_pre_recording_provenance_contract_identity(),
        legacy_v0462_v047_recording_provenance_contract_identity(),
    )


def preflight_write_binding_hash(binding: Mapping[str, Any]) -> str:
    payload = {
        key: value
        for key, value in binding.items()
        if key != "preflight_contract_hash"
    }
    digest = hashlib.sha256(
        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
    ).hexdigest()
    return f"sha256:{digest}"


def action_matrix_for_state(state_label: str | None) -> dict:
    matrix_label = (
        state_label
        if state_label in PROVENANCE_ACTION_MATRIX
        else normalize_provenance_state(state_label)
    )
    matrix = PROVENANCE_ACTION_MATRIX[matrix_label]
    return {
        "allowed_actions": list(matrix["allowed_actions"]),
        "blocked_actions": list(matrix["blocked_actions"]),
        "write_readiness": matrix["write_readiness"],
        "ux_gate": matrix["ux_gate"],
        "ux_gate_requires_confirmation": matrix["ux_gate_requires_confirmation"],
        "ux_gate_waivable": matrix["ux_gate_waivable"],
        "ux_gate_reason": matrix["ux_gate_reason"],
        "note": matrix["note"],
        "stable_state_label": normalize_provenance_state(matrix_label),
    }


def expected_revisions_payload(
    *,
    workspace_revision: int | None,
    rolling_summary_revision: int | None,
    context_brief_revision: int | None = None,
    update_protocol_revision: int | None = None,
) -> dict:
    return {
        "workspace_revision": workspace_revision,
        "rolling_summary_revision": rolling_summary_revision,
        "context_brief_revision": context_brief_revision,
        "update_protocol_revision": update_protocol_revision,
    }


def build_write_readiness(
    *,
    provenance_state: str,
    allowed_operation_level: str | None,
    summary_stale: bool | None,
    expected_revisions: Mapping[str, Any] | None = None,
    receipt_chain_verified: bool = False,
    receipt_store_available: bool = False,
) -> dict:
    state_label = (
        provenance_state
        if provenance_state in PROVENANCE_ACTION_MATRIX
        else normalize_provenance_state(provenance_state)
    )
    matrix = action_matrix_for_state(state_label)
    preflight_gate_open = (
        allowed_operation_level == "write_current_state_after_preflight"
        and summary_stale is False
    )

    if state_label == "inconsistent_or_tampered_evidence":
        readiness = "blocked"
        next_action = "Run validation or repair review before any mutating helper write."
    elif state_label == "review_required":
        readiness = "review_required"
        next_action = (
            "Review or repair-import the legacy sidecar through the recovery proposal, "
            "review, and promotion helpers before any mutating helper write."
        )
    elif state_label == "structurally_valid_legacy":
        readiness = "readable_legacy"
        next_action = (
            "Read continuity normally, then run preflight/recovery review before any "
            "mutating helper write."
        )
    elif preflight_gate_open and state_label in {
        "structurally_valid",
        "unproven_sidecar_state",
    }:
        readiness = "structural_only_ready_after_preflight"
        next_action = (
            "Use the existing revision-checked helper write path with the expected revisions; "
            "do not claim receipt-backed provenance."
        )
    elif preflight_gate_open and state_label == "helper_evidenced":
        readiness = "helper_evidenced_ready_after_preflight"
        next_action = "Use the revision-checked helper write path with verified receipt evidence."
    elif (
        allowed_operation_level == "write_current_state_after_preflight"
        and state_label == "review_imported_baseline"
    ):
        readiness = "review_imported_baseline_ready_after_preflight"
        next_action = (
            "Use the revision-checked helper write path; claim helper evidence only if "
            "that write finalizes its own receipt."
        )
    else:
        readiness = matrix["write_readiness"]
        next_action = "Refresh preflight context or review current continuity before writing."

    payload = {
        "state_label": state_label,
        "stable_state_label": normalize_provenance_state(state_label),
        "readiness": readiness,
        "allowed_operation_level": allowed_operation_level,
        "summary_stale": summary_stale,
        "allowed_actions": matrix["allowed_actions"],
        "blocked_actions": matrix["blocked_actions"],
        "ux_gate": matrix["ux_gate"],
        "ux_gate_requires_confirmation": matrix["ux_gate_requires_confirmation"],
        "ux_gate_waivable": matrix["ux_gate_waivable"],
        "ux_gate_reason": matrix["ux_gate_reason"],
        "next_action": next_action,
        "receipt_chain_verified": receipt_chain_verified,
        "receipt_store_available": receipt_store_available,
        "receipt_finalization_enabled": False,
        "note": matrix["note"],
    }
    if expected_revisions is not None:
        payload["expected_revisions"] = dict(expected_revisions)
    return payload


def build_provenance_report(
    *,
    sidecar_trust_state: str | None,
    continuity_state: str | None,
    allowed_operation_level: str | None,
    summary_stale: bool | None,
    expected_revisions: Mapping[str, Any] | None = None,
    receipt_chain_verified: bool = False,
    receipt_store_available: bool = False,
    imported_baseline_review_required: bool = False,
    helper_evidenced_baseline: bool = False,
    legacy_sidecar: bool = False,
    review_required: bool = False,
    review_imported_baseline: bool = False,
    unproven_sidecar_state: bool = False,
    metadata_status: str | None = None,
) -> dict:
    state_label = classify_provenance_state(
        sidecar_trust_state=sidecar_trust_state,
        continuity_state=continuity_state,
        receipt_chain_verified=receipt_chain_verified,
        receipt_store_available=receipt_store_available,
        imported_baseline_review_required=imported_baseline_review_required,
        helper_evidenced_baseline=helper_evidenced_baseline,
        legacy_sidecar=legacy_sidecar,
        review_required=review_required,
        review_imported_baseline=review_imported_baseline,
        unproven_sidecar_state=unproven_sidecar_state,
    )
    return {
        "state_label": state_label,
        "stable_state_label": normalize_provenance_state(state_label),
        "metadata_status": metadata_status,
        "contract_identity": provenance_contract_identity(),
        "legacy_transit_only_states": list(TRANSIT_ONLY_LEGACY_PROVENANCE_STATES),
        "receipt_contract": receipt_contract_identity(),
        "action_matrix": action_matrix_for_state(state_label),
        "write_readiness": build_write_readiness(
            provenance_state=state_label,
            allowed_operation_level=allowed_operation_level,
            summary_stale=summary_stale,
            expected_revisions=expected_revisions,
            receipt_chain_verified=receipt_chain_verified,
            receipt_store_available=receipt_store_available,
        ),
    }


def helper_write_gate_from_state(
    state: Mapping[str, Any] | None,
    *,
    helper_name: str,
    operation_class: str,
    preflight_binding_present: bool = False,
    require_preflight_for_review_imported_baseline: bool = False,
    receipt_chain_verified: bool = False,
    receipt_store_available: bool = False,
) -> dict:
    """Return the provenance gate for a helper that is about to mutate sidecar state."""

    provenance_facts = provenance_facts_from_state(state, review_intent=True)
    sidecar_trust_state = (
        "security_blocked"
        if provenance_facts["inconsistent_evidence"]
        else "review_required"
        if provenance_facts["review_required"]
        else "structurally_valid"
    )
    state_label = classify_provenance_state(
        sidecar_trust_state=sidecar_trust_state,
        continuity_state=None,
        receipt_chain_verified=receipt_chain_verified,
        receipt_store_available=receipt_store_available,
        helper_evidenced_baseline=provenance_facts["helper_evidenced"],
        legacy_sidecar=provenance_facts["legacy_sidecar"],
        review_required=provenance_facts["review_required"],
        review_imported_baseline=provenance_facts["review_imported_baseline"],
        unproven_sidecar_state=provenance_facts["unproven_sidecar_state"],
    )
    write_readiness = build_write_readiness(
        provenance_state=state_label,
        allowed_operation_level=(
            "write_current_state_after_preflight" if preflight_binding_present else None
        ),
        summary_stale=False if preflight_binding_present else None,
        expected_revisions=None,
        receipt_chain_verified=receipt_chain_verified,
        receipt_store_available=receipt_store_available,
    )

    allowed = True
    blocked_reason_code = None
    if state_label in {"review_required", "structurally_valid_legacy"}:
        allowed = False
        blocked_reason_code = "legacy_import_review_required"
    elif state_label == "inconsistent_or_tampered_evidence":
        allowed = False
        blocked_reason_code = "provenance_evidence_inconsistent"
    elif (
        state_label == "review_imported_baseline"
        and require_preflight_for_review_imported_baseline
        and not preflight_binding_present
    ):
        allowed = False
        blocked_reason_code = "preflight_required_for_review_imported_baseline"
    elif not preflight_binding_present:
        allowed = False
        blocked_reason_code = "preflight_required_for_mutating_helper_write"

    return {
        "allowed": allowed,
        "helper_name": helper_name,
        "operation_class": operation_class,
        "blocked_reason_code": blocked_reason_code,
        "provenance_state": state_label,
        "stable_provenance_state": normalize_provenance_state(state_label),
        "provenance_metadata_status": provenance_facts["metadata_status"],
        "write_readiness": write_readiness,
        "preflight_binding_present": preflight_binding_present,
        "requires_preflight_for_review_imported_baseline": (
            require_preflight_for_review_imported_baseline
        ),
    }


def helper_write_gate_failure_reason(gate: Mapping[str, Any]) -> str:
    """Map a denied helper gate to its canonical public failure family."""

    blocked_reason_code = gate.get("blocked_reason_code")
    if isinstance(blocked_reason_code, str) and blocked_reason_code.startswith(
        "preflight_required_"
    ):
        return "stale_write_context"
    return "trust_review_required"
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall