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/evidence.py

View on GitHub
"""Bounded current evidence checks for structural repair helpers."""

from __future__ import annotations

from dataclasses import dataclass, field
import hashlib
import json
from pathlib import Path
from typing import Any

from core.continuity.daily_log import (
    DailyLogCursor,
    DailyLogCursorError,
    daily_log_cursor_is_empty_scaffold,
    daily_log_cursor_is_legacy_empty,
    daily_log_cursor_state_fields,
    daily_log_cursors_equivalent,
    latest_active_daily_log_cursor,
    sorted_active_daily_log_files,
)
from core.errors import ConfigContractError
from core.protocol.contracts import (
    DAILY_LOGS_DIRNAME,
    FILE_KEYS,
    SUPPORTED_PROTOCOL_VERSIONS,
    SUPPORTED_STORAGE_MODES,
    SUPPORTED_WORKSPACE_LANGUAGES,
)
from core.protocol.markers import parse_file_marker, parse_file_state_marker
from core.provenance.inconsistent_review import (
    REVIEW_IMPORTED_BASELINE_MATERIAL_FAILURE_REASONS,
    evaluate_review_imported_baseline_materials,
)
from core.provenance.store import (
    RECEIPT_STORE_RELATIVE_PATH,
    ReceiptStoreError,
    ReceiptStoreSnapshot,
    receipt_store_summary,
)
from core.provenance import store as provenance_store
from core.provenance.state import provenance_facts_from_state
from core.workspace.runtime import load_workspace_state


RECEIPT_VERIFIED_FILE_KEYS = (
    "context_brief",
    "daily_log",
    "rolling_summary",
    "update_protocol",
)

_ACTUAL_DAILY_LOG_CURSOR_EVIDENCE_TOKEN = object()


@dataclass(frozen=True)
class ActualDailyLogCursorEvidence:
    """Internal proof that a cursor came from a specific on-disk snapshot."""

    storage_root: str
    workspace_revision: int
    state_digest: str
    cursor: DailyLogCursor
    latest_file_identity: tuple[int, int, int, int, int] | None
    _construction_token: object = field(repr=False, compare=False)


def _sha256_text_digest(text: str) -> str:
    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()


def _read_text(path: Path) -> str:
    return path.read_bytes().decode("utf-8")


def _normalized_path(path: Path) -> str:
    return str(path.expanduser().absolute())


def _strict_json_equal(left: Any, right: Any) -> bool:
    if type(left) is not type(right):
        return False
    if type(left) is dict:
        if left.keys() != right.keys():
            return False
        return all(_strict_json_equal(left[key], right[key]) for key in left)
    if type(left) is list:
        return len(left) == len(right) and all(
            _strict_json_equal(left_item, right_item)
            for left_item, right_item in zip(left, right)
        )
    return left == right


def _exact_state_snapshot_digest(*, state_text: str, state: dict) -> str | None:
    try:
        parsed_state = json.loads(state_text)
    except json.JSONDecodeError:
        return None
    if not isinstance(parsed_state, dict) or not _strict_json_equal(parsed_state, state):
        return None
    return _sha256_text_digest(state_text)


def _daily_log_cursor_has_strict_json_types(cursor: dict[str, object]) -> bool:
    latest_file = cursor.get("latest_file")
    latest_entry_id = cursor.get("latest_entry_id")
    latest_entry_seq = cursor.get("latest_entry_seq")
    entry_count = cursor.get("entry_count")
    return (
        (latest_file is None or type(latest_file) is str)
        and (latest_entry_id is None or type(latest_entry_id) is str)
        and (
            latest_entry_seq is None
            or (_is_json_int(latest_entry_seq) and latest_entry_seq >= 0)
        )
        and _is_json_int(entry_count)
        and entry_count >= 0
    )


def _daily_log_file_identity(path: Path) -> tuple[int, int, int, int, int]:
    stat_result = path.stat()
    return (
        stat_result.st_dev,
        stat_result.st_ino,
        stat_result.st_size,
        stat_result.st_mtime_ns,
        stat_result.st_ctime_ns,
    )


def _stable_actual_daily_log_cursor_snapshot(
    storage_root: Path,
) -> tuple[
    DailyLogCursor,
    tuple[int, int, int, int, int] | None,
    bool,
]:
    logs_dir = storage_root / DAILY_LOGS_DIRNAME
    try:
        before_files = sorted_active_daily_log_files(logs_dir)
        before_path = before_files[-1] if before_files else None
        before_identity = (
            _daily_log_file_identity(before_path) if before_path is not None else None
        )
        actual_cursor = latest_active_daily_log_cursor(storage_root)
        after_files = sorted_active_daily_log_files(logs_dir)
        after_path = after_files[-1] if after_files else None
        after_identity = (
            _daily_log_file_identity(after_path) if after_path is not None else None
        )
    except OSError as exc:
        raise DailyLogCursorError(
            reason_code="unreadable_latest_daily_log",
            message="Could not read a stable latest daily-log snapshot.",
            path=logs_dir,
        ) from exc

    parsed_path = actual_cursor.latest_path
    stable = (
        (before_path is None and parsed_path is None and after_path is None)
        or (
            before_path is not None
            and parsed_path is not None
            and after_path is not None
            and _normalized_path(before_path) == _normalized_path(parsed_path)
            and _normalized_path(parsed_path) == _normalized_path(after_path)
            and before_identity == after_identity
        )
    )
    return actual_cursor, after_identity, stable


def _bind_actual_daily_log_cursor_evidence(
    *,
    storage_root: Path,
    state: dict,
    state_text: str,
    actual_cursor: DailyLogCursor,
    latest_file_identity: tuple[int, int, int, int, int] | None,
) -> ActualDailyLogCursorEvidence | None:
    workspace_revision = state.get("workspace_revision")
    if not _is_json_int(workspace_revision) or workspace_revision < 1:
        return None
    state_digest = _exact_state_snapshot_digest(state_text=state_text, state=state)
    if state_digest is None:
        return None
    actual_cursor_fields = actual_cursor.as_state_fields()
    state_cursor_fields = daily_log_cursor_state_fields(state)
    if not (
        _daily_log_cursor_has_strict_json_types(state_cursor_fields)
        and _daily_log_cursor_has_strict_json_types(actual_cursor_fields)
    ):
        return None
    if not daily_log_cursors_equivalent(
        state_cursor_fields,
        actual_cursor_fields,
        actual_cursor=actual_cursor_fields,
    ):
        return None

    if actual_cursor.latest_file is None:
        if actual_cursor.latest_path is not None or latest_file_identity is not None:
            return None
    else:
        expected_path = storage_root / actual_cursor.latest_file
        if actual_cursor.latest_path is None or (
            _normalized_path(actual_cursor.latest_path) != _normalized_path(expected_path)
        ):
            return None
        if latest_file_identity is None:
            return None

    return ActualDailyLogCursorEvidence(
        storage_root=_normalized_path(storage_root),
        workspace_revision=workspace_revision,
        state_digest=state_digest,
        cursor=actual_cursor,
        latest_file_identity=latest_file_identity,
        _construction_token=_ACTUAL_DAILY_LOG_CURSOR_EVIDENCE_TOKEN,
    )


def capture_actual_daily_log_cursor_evidence(
    *,
    storage_root: Path,
    state: dict,
    state_text: str,
) -> tuple[DailyLogCursor, ActualDailyLogCursorEvidence | None]:
    """Capture a stable disk cursor and bind it to the exact state snapshot."""

    actual_cursor, latest_file_identity, stable = _stable_actual_daily_log_cursor_snapshot(
        storage_root
    )
    if not stable:
        raise DailyLogCursorError(
            reason_code="daily_log_cursor_mismatch",
            message="The latest daily-log snapshot changed while it was being read.",
            path=storage_root / DAILY_LOGS_DIRNAME,
        )
    return actual_cursor, _bind_actual_daily_log_cursor_evidence(
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        actual_cursor=actual_cursor,
        latest_file_identity=latest_file_identity,
    )


def _verified_actual_daily_log_cursor(
    *,
    storage_root: Path,
    state: dict,
    state_text: str | None,
    evidence: ActualDailyLogCursorEvidence | None,
) -> tuple[dict[str, object] | None, bool]:
    state_digest = (
        _exact_state_snapshot_digest(state_text=state_text, state=state)
        if isinstance(state_text, str)
        else None
    )
    if not isinstance(evidence, ActualDailyLogCursorEvidence):
        return None, False
    if (
        evidence._construction_token is not _ACTUAL_DAILY_LOG_CURSOR_EVIDENCE_TOKEN
        or evidence.storage_root != _normalized_path(storage_root)
        or evidence.workspace_revision != state.get("workspace_revision")
        or state_digest is None
        or evidence.state_digest != state_digest
    ):
        return None, True

    cursor = evidence.cursor.as_state_fields()
    state_cursor = daily_log_cursor_state_fields(state)
    if not (
        _daily_log_cursor_has_strict_json_types(state_cursor)
        and _daily_log_cursor_has_strict_json_types(cursor)
    ):
        return None, True
    if not daily_log_cursors_equivalent(
        state_cursor,
        cursor,
        actual_cursor=cursor,
    ):
        return None, True
    try:
        current_cursor, current_identity, stable = _stable_actual_daily_log_cursor_snapshot(
            storage_root
        )
    except DailyLogCursorError:
        return None, True
    evidence_path = evidence.cursor.latest_path
    current_path = current_cursor.latest_path
    if (
        not stable
        or evidence.latest_file_identity != current_identity
        or current_cursor.as_state_fields() != cursor
        or ((evidence_path is None) != (current_path is None))
        or (
            evidence_path is not None
            and current_path is not None
            and _normalized_path(evidence_path) != _normalized_path(current_path)
        )
    ):
        return None, True
    return cursor, False


def _is_json_int(value: Any) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def _managed_file_requires_current_receipt(state: dict, file_key: str) -> bool:
    files_state = state.get("files")
    if not isinstance(files_state, dict):
        return True
    state_entry = files_state.get(file_key)
    if not isinstance(state_entry, dict):
        return True
    return not (
        state_entry.get("file_revision") == 1
        and state_entry.get("base_workspace_revision") == 1
    )


def _receipt_store_result(summary: dict[str, Any], *, verified: bool = False) -> dict[str, object]:
    return {
        "store_file": summary["store_file"],
        "store_revision": summary["store_revision"],
        "receipt_count": summary["receipt_count"],
        "target_file_keys": summary["target_file_keys"],
        "verified": verified,
    }


def _daily_log_cursor_for_evidence(
    *,
    state: dict,
    daily_log_cursor: dict[str, object] | None = None,
) -> dict[str, object] | None:
    if daily_log_cursor is not None:
        return daily_log_cursor
    state_cursor = state.get("daily_logs")
    return state_cursor if isinstance(state_cursor, dict) else None


def _daily_log_required_without_actual_evidence(
    *,
    storage_root: Path,
    state: dict,
    daily_log_cursor: dict[str, object] | None,
) -> bool:
    state_daily_logs = state.get("daily_logs")
    if type(state_daily_logs) is not dict or type(daily_log_cursor) is not dict:
        return True
    state_cursor = daily_log_cursor_state_fields(state_daily_logs)
    caller_cursor = daily_log_cursor_state_fields(daily_log_cursor)
    if not (
        _daily_log_cursor_has_strict_json_types(state_cursor)
        and _daily_log_cursor_has_strict_json_types(caller_cursor)
    ):
        return True
    if not (
        daily_log_cursor_is_legacy_empty(state_cursor)
        and daily_log_cursor_is_legacy_empty(caller_cursor)
        and _strict_json_equal(state_cursor, caller_cursor)
    ):
        return True

    logs_dir = storage_root / DAILY_LOGS_DIRNAME
    try:
        if not logs_dir.is_dir():
            return True
        active_files = sorted_active_daily_log_files(logs_dir)
        if not logs_dir.is_dir():
            return True
    except OSError:
        return True
    return bool(active_files)


def current_receipt_required_file_keys(
    *,
    storage_root: Path,
    state: dict,
    state_text: str | None = None,
    daily_log_cursor: dict[str, object] | None = None,
    actual_daily_log_cursor_evidence: ActualDailyLogCursorEvidence | None = None,
) -> list[str]:
    required = []
    for file_key in ("rolling_summary", "context_brief", "update_protocol"):
        if (storage_root / FILE_KEYS[file_key]).is_file() and _managed_file_requires_current_receipt(
            state, file_key
        ):
            required.append(file_key)
    actual_daily_log_cursor, actual_evidence_changed = _verified_actual_daily_log_cursor(
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        evidence=actual_daily_log_cursor_evidence,
    )
    if actual_daily_log_cursor is not None:
        if (
            not daily_log_cursor_is_empty_scaffold(actual_daily_log_cursor)
            and actual_daily_log_cursor.get("latest_file") is not None
        ):
            required.append("daily_log")
    elif actual_evidence_changed or _daily_log_required_without_actual_evidence(
        storage_root=storage_root,
        state=state,
        daily_log_cursor=daily_log_cursor,
    ):
        required.append("daily_log")
    return sorted(required)


def current_receipt_target_path(
    *,
    storage_root: Path,
    state: dict,
    file_key: str,
    daily_log_cursor: dict[str, object] | None = None,
) -> Path:
    if file_key == "daily_log":
        daily_state = _daily_log_cursor_for_evidence(
            state=state,
            daily_log_cursor=daily_log_cursor,
        )
        latest_file = daily_state.get("latest_file") if isinstance(daily_state, dict) else None
        return storage_root / latest_file if isinstance(latest_file, str) else storage_root
    return storage_root / FILE_KEYS[file_key]


def _incomplete_result(
    *,
    reason_code: str,
    required_file_keys: list[str] | None = None,
    verified_file_keys: list[str] | None = None,
    receipt_store_available: bool = False,
    receipt_store: dict[str, object] | None = None,
    missing_file_keys: list[str] | None = None,
    config_guard: dict[str, object] | None = None,
) -> dict[str, object]:
    return {
        "required": True,
        "verified": False,
        "receipt_store_available": receipt_store_available,
        "evidence_block_reason_code": None,
        "reason_code": reason_code,
        "required_current_file_keys": required_file_keys or [],
        "verified_current_file_keys": verified_file_keys or [],
        "missing_current_file_keys": missing_file_keys or [],
        **({"receipt_store": receipt_store} if receipt_store is not None else {}),
        **({"config_guard": config_guard} if config_guard is not None else {}),
    }


def _storage_mode_for_root(storage_root: Path) -> str | None:
    if storage_root.name == ".recallloom":
        return "hidden"
    if storage_root.name == "recallloom":
        return "visible"
    return None


def _is_positive_json_int(value: Any) -> bool:
    return _is_json_int(value) and value >= 1


def _daily_log_cursor_mismatch_result(
    *,
    state_cursor: dict[str, object],
    actual: DailyLogCursor,
) -> dict[str, object]:
    actual_cursor = actual.as_state_fields()
    reason_code = "daily_log_cursor_mismatch"
    if actual.latest_file is None and not daily_log_cursor_is_legacy_empty(state_cursor):
        reason_code = "unexpected_latest_daily_log_state"
    elif state_cursor.get("latest_file") is None:
        reason_code = "missing_latest_daily_log_state"
    elif state_cursor.get("latest_file") != actual_cursor.get("latest_file"):
        reason_code = "latest_daily_log_state_mismatch"
    return {
        "verified": False,
        "reason_code": reason_code,
        "state_cursor": state_cursor,
        "actual_cursor": actual_cursor,
        "path": str(actual.latest_path) if actual.latest_path is not None else None,
    }


def current_daily_log_cursor_consistency_check(
    *,
    storage_root: Path,
    state: dict,
) -> dict[str, object]:
    daily_state = state.get("daily_logs")
    if not isinstance(daily_state, dict):
        return {
            "verified": False,
            "reason_code": "invalid_daily_logs_state",
            "state_cursor": None,
        }

    state_cursor = daily_log_cursor_state_fields(daily_state)
    try:
        actual = latest_active_daily_log_cursor(storage_root)
    except DailyLogCursorError as exc:
        return {
            "verified": False,
            "reason_code": exc.reason_code,
            "state_cursor": state_cursor,
            "actual_cursor": exc.details,
            "path": str(exc.path) if exc.path is not None else None,
        }
    except OSError:
        return {
            "verified": False,
            "reason_code": "unreadable_latest_daily_log",
            "state_cursor": state_cursor,
            "actual_cursor": None,
            "path": str(storage_root / DAILY_LOGS_DIRNAME),
        }
    actual_cursor = actual.as_state_fields()

    if daily_log_cursors_equivalent(
        state_cursor,
        actual_cursor,
        actual_cursor=actual_cursor,
    ):
        return {
            "verified": True,
            "reason_code": "daily_log_cursor_verified",
            "state_cursor": state_cursor,
            "actual_cursor": actual_cursor,
            "path": str(actual.latest_path) if actual.latest_path is not None else None,
        }

    return _daily_log_cursor_mismatch_result(
        state_cursor=state_cursor,
        actual=actual,
    )


def _current_daily_log_cursor_consistency_snapshot(
    *,
    storage_root: Path,
    state: dict,
    state_text: str,
) -> tuple[dict[str, object], ActualDailyLogCursorEvidence | None]:
    daily_state = state.get("daily_logs")
    if not isinstance(daily_state, dict):
        return {
            "verified": False,
            "reason_code": "invalid_daily_logs_state",
            "state_cursor": None,
        }, None

    state_cursor = daily_log_cursor_state_fields(daily_state)
    try:
        actual, latest_file_identity, stable = _stable_actual_daily_log_cursor_snapshot(
            storage_root
        )
    except DailyLogCursorError as exc:
        return {
            "verified": False,
            "reason_code": exc.reason_code,
            "state_cursor": state_cursor,
            "actual_cursor": exc.details,
            "path": str(exc.path) if exc.path is not None else None,
        }, None

    actual_cursor = actual.as_state_fields()
    if not stable:
        return {
            "verified": False,
            "reason_code": "daily_log_cursor_mismatch",
            "state_cursor": state_cursor,
            "actual_cursor": {
                "reason_code": "daily_log_cursor_mismatch",
                "side_effect": "none",
                "path": str(storage_root / DAILY_LOGS_DIRNAME),
            },
            "path": str(storage_root / DAILY_LOGS_DIRNAME),
        }, None
    if not daily_log_cursors_equivalent(
        state_cursor,
        actual_cursor,
        actual_cursor=actual_cursor,
    ):
        return _daily_log_cursor_mismatch_result(
            state_cursor=state_cursor,
            actual=actual,
        ), None

    actual_evidence = _bind_actual_daily_log_cursor_evidence(
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        actual_cursor=actual,
        latest_file_identity=latest_file_identity,
    )
    if actual_evidence is None:
        return {
            "verified": False,
            "reason_code": "daily_log_cursor_mismatch",
            "state_cursor": state_cursor,
            "actual_cursor": actual_cursor,
            "path": str(actual.latest_path) if actual.latest_path is not None else None,
        }, None
    return {
        "verified": True,
        "reason_code": "daily_log_cursor_verified",
        "state_cursor": state_cursor,
        "actual_cursor": actual_cursor,
        "path": str(actual.latest_path) if actual.latest_path is not None else None,
    }, actual_evidence


def _state_file_entry_issue(entry: Any, *, file_key: str) -> str | None:
    if not isinstance(entry, dict):
        return f"{file_key}_state_entry_missing"
    if not _is_positive_json_int(entry.get("file_revision")):
        return f"{file_key}_state_file_revision_invalid"
    if not isinstance(entry.get("updated_at"), str) or not entry["updated_at"].strip():
        return f"{file_key}_state_updated_at_invalid"
    if not isinstance(entry.get("writer_id"), str) or not entry["writer_id"].strip():
        return f"{file_key}_state_writer_id_invalid"
    if not _is_positive_json_int(entry.get("base_workspace_revision")):
        return f"{file_key}_state_base_workspace_revision_invalid"
    return None


def current_managed_file_state_consistency_check(
    *,
    storage_root: Path,
    state: dict,
    required_file_keys: list[str],
) -> dict[str, object]:
    files_state = state.get("files")
    if not isinstance(files_state, dict):
        return {
            "verified": False,
            "reason_code": "invalid_state_files",
            "checked_file_keys": [],
        }

    checked: list[str] = []
    for file_key in ("rolling_summary", "context_brief", "update_protocol"):
        path = storage_root / FILE_KEYS[file_key]
        should_check = path.is_file() or file_key in required_file_keys or file_key in files_state
        if not should_check:
            continue
        checked.append(file_key)
        if not path.is_file():
            return {
                "verified": False,
                "reason_code": f"{file_key}_managed_file_missing",
                "checked_file_keys": checked,
                "path": str(path),
            }
        try:
            text = _read_text(path)
        except (OSError, UnicodeDecodeError):
            return {
                "verified": False,
                "reason_code": f"{file_key}_managed_file_unreadable",
                "checked_file_keys": checked,
                "path": str(path),
            }
        marker = parse_file_marker(text)
        if marker is None or marker.file_key != file_key:
            return {
                "verified": False,
                "reason_code": f"{file_key}_managed_file_marker_mismatch",
                "checked_file_keys": checked,
                "path": str(path),
                "actual_file_key": marker.file_key if marker is not None else None,
            }
        file_state = parse_file_state_marker(text)
        if file_state is None:
            return {
                "verified": False,
                "reason_code": f"{file_key}_file_state_marker_missing",
                "checked_file_keys": checked,
                "path": str(path),
            }
        state_entry = files_state.get(file_key)
        state_issue = _state_file_entry_issue(state_entry, file_key=file_key)
        if state_issue is not None:
            return {
                "verified": False,
                "reason_code": state_issue,
                "checked_file_keys": checked,
                "path": str(storage_root / FILE_KEYS["state"]),
            }
        mismatches = []
        if state_entry.get("file_revision") != file_state.revision:
            mismatches.append("file_revision")
        if state_entry.get("updated_at") != file_state.updated_at:
            mismatches.append("updated_at")
        if state_entry.get("writer_id") != file_state.writer_id:
            mismatches.append("writer_id")
        if state_entry.get("base_workspace_revision") != file_state.base_workspace_revision:
            mismatches.append("base_workspace_revision")
        if (
            file_key == "update_protocol"
            and state.get("update_protocol_revision") != file_state.revision
        ):
            mismatches.append("update_protocol_revision")
        if mismatches:
            reason_code = (
                "update_protocol_workspace_revision_mismatch"
                if file_key == "update_protocol" and mismatches == ["update_protocol_revision"]
                else f"{file_key}_state_marker_mismatch"
            )
            return {
                "verified": False,
                "reason_code": reason_code,
                "failed_checks": mismatches,
                "checked_file_keys": checked,
                "path": str(path),
            }

    return {
        "verified": True,
        "reason_code": "managed_file_state_consistency_verified",
        "checked_file_keys": checked,
    }


def _managed_marker_targets(
    *,
    storage_root: Path,
    state: dict,
    required_file_keys: list[str],
    daily_log_cursor: dict[str, object] | None = None,
) -> list[tuple[str, Path]]:
    targets: list[tuple[str, Path]] = []
    for file_key in ("rolling_summary", "context_brief", "update_protocol"):
        path = storage_root / FILE_KEYS[file_key]
        if path.is_file() or file_key in required_file_keys:
            targets.append((file_key, path))
    logs_dir = storage_root / DAILY_LOGS_DIRNAME
    if logs_dir.is_dir():
        for path in sorted(logs_dir.glob("*.md")):
            if path.is_file():
                targets.append(("daily_log", path))
    elif "daily_log" in required_file_keys:
        targets.append(
            (
                "daily_log",
                current_receipt_target_path(
                    storage_root=storage_root,
                    state=state,
                    file_key="daily_log",
                    daily_log_cursor=daily_log_cursor,
                ),
            )
        )
    return targets


def current_config_marker_consistency_check(
    *,
    storage_root: Path,
    state: dict,
    required_file_keys: list[str],
    daily_log_cursor: dict[str, object] | None = None,
) -> dict[str, object]:
    config_path = storage_root / FILE_KEYS["config"]
    if not config_path.is_file():
        return {
            "verified": False,
            "reason_code": "missing_config",
            "path": str(config_path),
        }
    try:
        config = json.loads(_read_text(config_path))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
        return {
            "verified": False,
            "reason_code": "invalid_config",
            "path": str(config_path),
        }
    if not isinstance(config, dict):
        return {
            "verified": False,
            "reason_code": "invalid_config",
            "path": str(config_path),
        }

    protocol_version = config.get("protocol_version")
    storage_mode = config.get("storage_mode")
    workspace_language = config.get("workspace_language")
    if storage_mode not in SUPPORTED_STORAGE_MODES:
        return {
            "verified": False,
            "reason_code": "unsupported_storage_mode",
            "path": str(config_path),
        }
    implied_storage_mode = _storage_mode_for_root(storage_root)
    if implied_storage_mode is not None and storage_mode != implied_storage_mode:
        return {
            "verified": False,
            "reason_code": "storage_mode_path_mismatch",
            "path": str(config_path),
        }
    if workspace_language not in SUPPORTED_WORKSPACE_LANGUAGES:
        return {
            "verified": False,
            "reason_code": "unsupported_workspace_language",
            "path": str(config_path),
        }
    if protocol_version not in SUPPORTED_PROTOCOL_VERSIONS:
        return {
            "verified": False,
            "reason_code": "unsupported_protocol_version",
            "path": str(config_path),
        }

    for file_key, path in _managed_marker_targets(
        storage_root=storage_root,
        state=state,
        required_file_keys=required_file_keys,
        daily_log_cursor=daily_log_cursor,
    ):
        if not path.is_file():
            continue
        try:
            marker = parse_file_marker(_read_text(path))
        except (OSError, UnicodeDecodeError):
            return {
                "verified": False,
                "reason_code": "managed_file_unreadable",
                "path": str(path),
            }
        if marker is None:
            return {
                "verified": False,
                "reason_code": "managed_file_marker_missing",
                "path": str(path),
            }
        if marker.file_key != file_key:
            return {
                "verified": False,
                "reason_code": "managed_file_marker_mismatch",
                "path": str(path),
                "file_key": file_key,
                "actual_file_key": marker.file_key,
            }
        if marker.language != workspace_language:
            return {
                "verified": False,
                "reason_code": "workspace_language_mismatch",
                "path": str(path),
                "workspace_language": workspace_language,
                "marker_language": marker.language,
            }
        if marker.version != protocol_version:
            return {
                "verified": False,
                "reason_code": "protocol_marker_version_mismatch",
                "path": str(path),
                "protocol_version": protocol_version,
                "marker_version": marker.version,
            }
    return {
        "verified": True,
        "reason_code": "config_marker_consistency_verified",
        "path": str(config_path),
    }


def bounded_current_helper_evidence_check(
    *,
    project_root: str | Path,
    storage_root: str | Path,
    state: dict,
    state_text: str,
    helper_evidenced_only: bool = True,
    require_receipt_store: bool = False,
    require_config_guard: bool = False,
    daily_log_cursor: dict[str, object] | None = None,
    actual_daily_log_cursor_evidence: ActualDailyLogCursorEvidence | None = None,
    receipt_store_snapshot: ReceiptStoreSnapshot | None = None,
) -> dict[str, object]:
    """Verify whether current receipt-store evidence can preserve helper_evidenced.

    The check is intentionally bounded to current managed files and the current
    state digest. It does not claim to audit historical receipt chains.
    """

    project_root = Path(project_root)
    storage_root = Path(storage_root)
    facts = provenance_facts_from_state(state, review_intent=True)
    required_file_keys = current_receipt_required_file_keys(
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        daily_log_cursor=daily_log_cursor,
        actual_daily_log_cursor_evidence=actual_daily_log_cursor_evidence,
    )
    config_guard = None
    if require_config_guard:
        config_guard = current_config_marker_consistency_check(
            storage_root=storage_root,
            state=state,
            required_file_keys=required_file_keys,
            daily_log_cursor=daily_log_cursor,
        )
        if config_guard.get("verified") is not True:
            return {
                "required": True,
                "verified": False,
                "receipt_store_available": False,
                "evidence_block_reason_code": "direct_state_or_config_edit_detected",
                "reason_code": str(
                    config_guard.get("reason_code")
                    or "config_marker_consistency_mismatch"
                ),
                "required_current_file_keys": required_file_keys,
                "verified_current_file_keys": [],
                "missing_current_file_keys": [],
                "config_guard": config_guard,
            }

    if helper_evidenced_only and not facts["helper_evidenced"]:
        return {
            "required": False,
            "verified": False,
            "receipt_store_available": False,
            "evidence_block_reason_code": None,
            "reason_code": "helper_evidence_check_not_required",
            "required_current_file_keys": required_file_keys if require_config_guard else [],
            "verified_current_file_keys": [],
            **({"config_guard": config_guard} if config_guard is not None else {}),
        }

    store_path = storage_root / RECEIPT_STORE_RELATIVE_PATH
    try:
        summary = receipt_store_summary(
            storage_root=storage_root,
            project_root=project_root,
            require_exists=require_receipt_store,
            snapshot=receipt_store_snapshot,
        )
    except ReceiptStoreError as exc:
        return {
            "required": True,
            "verified": False,
            "receipt_store_available": store_path.exists(),
            "evidence_block_reason_code": "receipt_evidence_mismatch",
            "reason_code": exc.details.get("reason_code", "receipt_store_invalid"),
            "required_current_file_keys": [],
            "verified_current_file_keys": [],
            "missing_current_file_keys": [],
            **({"config_guard": config_guard} if config_guard is not None else {}),
        }

    receipt_store = _receipt_store_result(summary)
    latest_receipts = summary["latest_receipts_by_file_key"]
    if not latest_receipts:
        return _incomplete_result(
            reason_code="receipt_evidence_absent",
            receipt_store_available=store_path.is_file(),
            receipt_store=receipt_store,
            config_guard=config_guard,
        )

    missing = sorted(set(required_file_keys).difference(latest_receipts))
    unsupported = sorted(set(latest_receipts).difference(RECEIPT_VERIFIED_FILE_KEYS))
    if unsupported:
        return {
            "required": True,
            "verified": False,
            "receipt_store_available": True,
            "evidence_block_reason_code": "receipt_evidence_mismatch",
            "reason_code": "receipt_store_contains_unsupported_target",
            "required_current_file_keys": required_file_keys,
            "verified_current_file_keys": [],
            "missing_current_file_keys": missing,
            "receipt_store": receipt_store,
            **({"config_guard": config_guard} if config_guard is not None else {}),
        }
    if config_guard is None:
        config_guard = current_config_marker_consistency_check(
            storage_root=storage_root,
            state=state,
            required_file_keys=required_file_keys,
            daily_log_cursor=daily_log_cursor,
        )
    if config_guard.get("verified") is not True:
        return {
            "required": True,
            "verified": False,
            "receipt_store_available": True,
            "evidence_block_reason_code": "direct_state_or_config_edit_detected",
            "reason_code": str(
                config_guard.get("reason_code") or "config_marker_consistency_mismatch"
            ),
            "required_current_file_keys": required_file_keys,
            "verified_current_file_keys": [],
            "missing_current_file_keys": missing,
            "receipt_store": receipt_store,
            "config_guard": config_guard,
        }
    current_state_digest = _sha256_text_digest(state_text)
    current_workspace_revision = state.get("workspace_revision")
    verified_file_keys: list[str] = []

    for file_key, receipt in sorted(latest_receipts.items()):
        target_path = current_receipt_target_path(
            storage_root=storage_root,
            state=state,
            file_key=file_key,
            daily_log_cursor=daily_log_cursor,
        )
        if file_key not in required_file_keys:
            if receipt.get("revision") == summary["store_revision"]:
                state_digest_matches = receipt.get("state_digest") == current_state_digest
                workspace_revision_matches = (
                    receipt.get("result_workspace_revision") == current_workspace_revision
                )
                if not state_digest_matches or not workspace_revision_matches:
                    return {
                        "required": True,
                        "verified": False,
                        "receipt_store_available": True,
                        "evidence_block_reason_code": "direct_state_or_config_edit_detected",
                        "reason_code": "latest_receipt_state_binding_mismatch",
                        "required_current_file_keys": required_file_keys,
                        "verified_current_file_keys": verified_file_keys,
                        "missing_current_file_keys": missing,
                        "receipt_store": receipt_store,
                        "config_guard": config_guard,
                    }
            continue
        if not target_path.is_file():
            return {
                "required": True,
                "verified": False,
                "receipt_store_available": True,
                "evidence_block_reason_code": "receipt_evidence_mismatch",
                "reason_code": f"{file_key}_receipt_target_missing",
                "required_current_file_keys": required_file_keys,
                "verified_current_file_keys": verified_file_keys,
                "missing_current_file_keys": missing,
                "receipt_store": receipt_store,
                "config_guard": config_guard,
            }

        target_text = _read_text(target_path)
        checks = {
            "target_digest_matches_current_file": (
                receipt.get("target_digest") == _sha256_text_digest(target_text)
            ),
            "finalized": receipt.get("finalization_status") == "finalized",
        }
        if file_key == "daily_log":
            daily_state = _daily_log_cursor_for_evidence(
                state=state,
                daily_log_cursor=daily_log_cursor,
            )
            latest_entry_seq = (
                daily_state.get("latest_entry_seq") if isinstance(daily_state, dict) else None
            )
            checks["latest_entry_seq_matches_receipt"] = (
                receipt.get("result_file_revision") == latest_entry_seq
            )
        else:
            file_state = parse_file_state_marker(target_text)
            state_entry = state.get("files", {}).get(file_key)
            checks.update(
                {
                    "file_state_marker_present": file_state is not None,
                    "state_entry_present": isinstance(state_entry, dict),
                }
            )
            if file_state is not None and isinstance(state_entry, dict):
                checks.update(
                    {
                        "file_revision_matches_marker": (
                            receipt.get("result_file_revision") == file_state.revision
                        ),
                        "state_entry_revision_matches_marker": (
                            state_entry.get("file_revision") == file_state.revision
                        ),
                        "state_entry_updated_at_matches_marker": (
                            state_entry.get("updated_at") == file_state.updated_at
                        ),
                        "state_entry_writer_id_matches_marker": (
                            state_entry.get("writer_id") == file_state.writer_id
                        ),
                        "receipt_workspace_revision_matches_marker_base": (
                            receipt.get("result_workspace_revision")
                            == file_state.base_workspace_revision
                        ),
                        "state_entry_base_workspace_revision_matches_marker": (
                            state_entry.get("base_workspace_revision")
                            == file_state.base_workspace_revision
                        ),
                    }
                )
        if receipt.get("revision") == summary["store_revision"]:
            state_digest_matches = receipt.get("state_digest") == current_state_digest
            workspace_revision_matches = (
                receipt.get("result_workspace_revision") == current_workspace_revision
            )
            if not state_digest_matches or not workspace_revision_matches:
                return {
                    "required": True,
                    "verified": False,
                    "receipt_store_available": True,
                    "evidence_block_reason_code": "direct_state_or_config_edit_detected",
                    "reason_code": "latest_receipt_state_binding_mismatch",
                    "required_current_file_keys": required_file_keys,
                    "verified_current_file_keys": verified_file_keys,
                    "missing_current_file_keys": missing,
                    "receipt_store": receipt_store,
                    "config_guard": config_guard,
                }
            checks["latest_state_digest_matches_current_state"] = True
            checks["latest_workspace_revision_matches_state"] = True
        else:
            checks["workspace_revision_not_from_future"] = (
                _is_json_int(receipt.get("result_workspace_revision"))
                and _is_json_int(current_workspace_revision)
                and receipt["result_workspace_revision"] <= current_workspace_revision
            )

        failed_checks = [key for key, passed in checks.items() if not passed]
        if failed_checks:
            return {
                "required": True,
                "verified": False,
                "receipt_store_available": True,
                "evidence_block_reason_code": "receipt_evidence_mismatch",
                "reason_code": f"{file_key}_receipt_mismatch",
                "failed_checks": failed_checks,
                "required_current_file_keys": required_file_keys,
                "verified_current_file_keys": verified_file_keys,
                "missing_current_file_keys": missing,
                "receipt_store": receipt_store,
                "config_guard": config_guard,
            }
        verified_file_keys.append(file_key)

    if missing:
        return _incomplete_result(
            reason_code="receipt_evidence_incomplete",
            required_file_keys=required_file_keys,
            verified_file_keys=sorted(verified_file_keys),
            receipt_store_available=True,
            receipt_store=receipt_store,
            missing_file_keys=missing,
        )

    verified = set(verified_file_keys) == set(required_file_keys)
    receipt_store["verified"] = verified
    return {
        "required": True,
        "verified": verified,
        "receipt_store_available": True,
        "evidence_block_reason_code": None if verified else None,
        "reason_code": (
            "bounded_current_evidence_verified"
            if verified
            else "receipt_evidence_incomplete"
        ),
        "required_current_file_keys": required_file_keys,
        "verified_current_file_keys": sorted(verified_file_keys),
        "missing_current_file_keys": missing,
        "receipt_store": receipt_store,
        "config_guard": config_guard,
    }


def _safe_next_action_for_reason(reason_code: str) -> str:
    if reason_code in {
        "state_json_missing",
        "state_json_unreadable",
        "state_json_invalid",
        "state_json_not_object",
        "state_contract_invalid",
    }:
        return "Stop mutating and run damaged-sidecar recovery or validation before repair."
    if reason_code in {"provenance_review_required", "provenance_evidence_inconsistent"}:
        return "Keep the sidecar read-only and run provenance recovery or repair review before mutating."
    if "receipt" in reason_code:
        return "Stop mutating and review or repair helper receipt evidence before the next write."
    if "daily_log" in reason_code:
        return "Run daily-log cursor preview/repair before appending or syncing sidecar state."
    if "config" in reason_code or "marker" in reason_code:
        return "Stop mutating and use the managed repair path before changing sidecar files."
    return "Keep the sidecar read-only until the integrity mismatch is reviewed and repaired."


def _strict_gate_block(
    *,
    reason_code: str,
    evidence: dict[str, object],
    details: dict[str, object] | None = None,
) -> dict[str, object]:
    return {
        "allowed_for_mutation": False,
        "blocked_reason": "strict_sidecar_integrity_failed",
        "reason_code": reason_code,
        "safe_next_action": _safe_next_action_for_reason(reason_code),
        "evidence": evidence,
        "details": details or {},
    }


def strict_sidecar_integrity_gate_public_summary(gate: dict[str, object]) -> dict[str, object]:
    """Return a public-safe summary of a strict sidecar mutation gate result."""

    details = gate.get("details")
    summary: dict[str, object] = {
        "allowed_for_mutation": gate.get("allowed_for_mutation") is True,
        "blocked_reason": gate.get("blocked_reason"),
        "reason_code": gate.get("reason_code"),
        "safe_next_action": gate.get("safe_next_action"),
    }
    if isinstance(details, dict):
        if "receipt_store_required" in details:
            summary["receipt_store_required"] = details.get("receipt_store_required")
        verified_file_keys = details.get("verified_current_file_keys")
        if isinstance(verified_file_keys, list):
            summary["verified_current_file_keys"] = sorted(
                key for key in verified_file_keys if isinstance(key, str)
            )
        receipt_store = details.get("receipt_store")
        if isinstance(receipt_store, dict):
            target_file_keys = receipt_store.get("target_file_keys")
            summary["receipt_store"] = {
                "verified": receipt_store.get("verified") is True,
                "store_revision": receipt_store.get("store_revision"),
                "receipt_count": receipt_store.get("receipt_count"),
                "target_file_keys": (
                    sorted(key for key in target_file_keys if isinstance(key, str))
                    if isinstance(target_file_keys, list)
                    else []
                ),
            }
    return summary


def strict_gate_current_receipts_verified(gate: dict[str, object]) -> bool:
    """Return whether the strict gate verified current helper receipts."""

    if gate.get("allowed_for_mutation") is not True:
        return False
    details = gate.get("details")
    if not isinstance(details, dict):
        return False
    receipt_store = details.get("receipt_store")
    if not isinstance(receipt_store, dict) or receipt_store.get("verified") is not True:
        return False
    verified_file_keys = details.get("verified_current_file_keys")
    return isinstance(verified_file_keys, list) and any(
        isinstance(key, str) for key in verified_file_keys
    )


def strict_sidecar_no_write_failure_extra(
    *,
    project_root: str | Path | None = None,
    storage_root: str | Path | None = None,
    continuity_confidence: str | None = None,
    include_recovery_actions: bool = True,
) -> dict[str, object]:
    """Return public-safe failure fields for read paths that cannot trust writes."""

    if project_root is None or storage_root is None:
        gate_summary = {
            "allowed_for_mutation": False,
            "blocked_reason": "strict_sidecar_integrity_failed",
            "reason_code": "strict_gate_unavailable",
            "safe_next_action": (
                "Keep the sidecar read-only until the integrity mismatch is reviewed and repaired."
            ),
        }
    else:
        try:
            gate_summary = strict_sidecar_integrity_gate_public_summary(
                strict_sidecar_integrity_gate(
                    project_root=project_root,
                    storage_root=storage_root,
                )
            )
        except Exception:
            gate_summary = {
                "allowed_for_mutation": False,
                "blocked_reason": "strict_sidecar_integrity_failed",
                "reason_code": "strict_gate_unavailable",
                "safe_next_action": (
                    "Keep the sidecar read-only until the integrity mismatch is reviewed and repaired."
                ),
            }
    return strict_sidecar_no_write_failure_extra_from_summary(
        gate_summary,
        continuity_confidence=continuity_confidence,
        include_recovery_actions=include_recovery_actions,
    )


def strict_sidecar_no_write_failure_extra_from_summary(
    gate_summary: dict[str, object],
    *,
    continuity_confidence: str | None = None,
    include_recovery_actions: bool = True,
) -> dict[str, object]:
    """Return public-safe no-write fields from an existing strict gate summary."""

    write_context_blocked_reason = (
        "strict_sidecar_integrity_failed"
        if gate_summary.get("allowed_for_mutation") is not True
        else "read_failure_no_write_context"
    )
    strict_gate_summary = dict(gate_summary)
    if strict_gate_summary.get("allowed_for_mutation") is True:
        strict_gate_summary["safe_next_action"] = (
            "Keep the sidecar read-only until the reported read failure is reviewed."
        )
    extra: dict[str, object] = {
        "strict_sidecar_integrity_gate": strict_gate_summary,
        "write_context_blocked_reason": write_context_blocked_reason,
        "safe_write_context": None,
        "side_effect": "none",
        "write_effect": "none",
    }
    if include_recovery_actions:
        extra["next_actions"] = [
            "review_or_repair_sidecar_before_write",
            "run_integrity_validation",
            "stage_recovery_proposal_for_manual_review",
            "record_recovery_review_after_manual_confirmation",
            "prepare_recovery_promotion_after_review",
        ]
    if continuity_confidence is not None:
        extra["continuity_confidence"] = continuity_confidence
    return extra


def _load_current_state_for_gate(storage_root: Path) -> tuple[str | None, dict | None, dict[str, object]]:
    state_path = storage_root / FILE_KEYS["state"]
    if not state_path.is_file():
        return None, None, {
            "verified": False,
            "reason_code": "state_json_missing",
            "path": str(state_path),
        }
    try:
        state_text = _read_text(state_path)
    except (OSError, UnicodeDecodeError):
        return None, None, {
            "verified": False,
            "reason_code": "state_json_unreadable",
            "path": str(state_path),
        }
    try:
        state = load_workspace_state(state_path)
    except json.JSONDecodeError:
        return state_text, None, {
            "verified": False,
            "reason_code": "state_json_invalid",
            "path": str(state_path),
        }
    except ConfigContractError as exc:
        return state_text, None, {
            "verified": False,
            "reason_code": "state_contract_invalid",
            "path": str(state_path),
            "error": str(exc),
        }
    return state_text, state, {
        "verified": True,
        "reason_code": "state_json_loaded",
        "path": str(state_path),
        "state_digest": _sha256_text_digest(state_text),
        "workspace_revision": state.get("workspace_revision"),
    }


def strict_sidecar_integrity_gate(
    *,
    project_root: str | Path,
    storage_root: str | Path,
) -> dict[str, object]:
    """Return the shared strict mutation gate for the current sidecar snapshot.

    This gate deliberately rereads filesystem state and recomputes the bounded
    current evidence surface. It is not a historical receipt-chain audit.
    """

    project_root = Path(project_root)
    storage_root = Path(storage_root)
    state_text, state, state_snapshot = _load_current_state_for_gate(storage_root)
    evidence: dict[str, object] = {
        "state_snapshot": state_snapshot,
    }
    if state_text is None or state is None:
        return _strict_gate_block(
            reason_code=str(state_snapshot.get("reason_code") or "state_json_invalid"),
            evidence=evidence,
        )

    daily_log_cursor, actual_daily_log_cursor_evidence = (
        _current_daily_log_cursor_consistency_snapshot(
            storage_root=storage_root,
            state=state,
            state_text=state_text,
        )
    )
    evidence["daily_log_cursor"] = daily_log_cursor
    actual_daily_log_cursor = (
        daily_log_cursor.get("actual_cursor")
        if isinstance(daily_log_cursor.get("actual_cursor"), dict)
        else None
    )
    required_file_keys = current_receipt_required_file_keys(
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        daily_log_cursor=actual_daily_log_cursor,
        actual_daily_log_cursor_evidence=actual_daily_log_cursor_evidence,
    )
    evidence["required_current_file_keys"] = required_file_keys

    managed_file_state = current_managed_file_state_consistency_check(
        storage_root=storage_root,
        state=state,
        required_file_keys=required_file_keys,
    )
    evidence["managed_file_state"] = managed_file_state
    if managed_file_state.get("verified") is not True:
        return _strict_gate_block(
            reason_code=str(
                managed_file_state.get("reason_code")
                or "managed_file_state_consistency_mismatch"
            ),
            evidence=evidence,
            details=managed_file_state,
        )

    config_guard = current_config_marker_consistency_check(
        storage_root=storage_root,
        state=state,
        required_file_keys=required_file_keys,
        daily_log_cursor=actual_daily_log_cursor,
    )
    evidence["config_marker"] = config_guard
    if config_guard.get("verified") is not True:
        return _strict_gate_block(
            reason_code=str(config_guard.get("reason_code") or "config_marker_mismatch"),
            evidence=evidence,
            details=config_guard,
        )

    if daily_log_cursor.get("verified") is not True:
        return _strict_gate_block(
            reason_code=str(
                daily_log_cursor.get("reason_code")
                or "daily_log_cursor_consistency_mismatch"
            ),
            evidence=evidence,
            details=daily_log_cursor,
        )

    provenance_facts = provenance_facts_from_state(state, review_intent=True)
    evidence["provenance_facts"] = {
        "metadata_status": provenance_facts.get("metadata_status"),
        "helper_evidenced": provenance_facts.get("helper_evidenced"),
        "review_imported_baseline": provenance_facts.get("review_imported_baseline"),
        "review_required": provenance_facts.get("review_required"),
        "legacy_sidecar": provenance_facts.get("legacy_sidecar"),
        "inconsistent_evidence": provenance_facts.get("inconsistent_evidence"),
    }
    if provenance_facts.get("inconsistent_evidence") is True:
        return _strict_gate_block(
            reason_code="provenance_evidence_inconsistent",
            evidence=evidence,
            details=evidence["provenance_facts"],
        )
    if (
        provenance_facts.get("review_required") is True
        or provenance_facts.get("legacy_sidecar") is True
    ):
        return _strict_gate_block(
            reason_code="provenance_review_required",
            evidence=evidence,
            details=evidence["provenance_facts"],
        )

    if provenance_facts.get("review_imported_baseline") is True:
        reviewed_baseline = evaluate_review_imported_baseline_materials(
            project_root=project_root,
            storage_root=storage_root,
            state=state,
            state_text=state_text,
        )
        if reviewed_baseline.status != "not_applicable":
            route_reason_code = reviewed_baseline.reason_code
            material_reason_code = None
            if route_reason_code in REVIEW_IMPORTED_BASELINE_MATERIAL_FAILURE_REASONS:
                material_reason_code = route_reason_code
                route_reason_code = "review_imported_baseline_material_invalid"
            evidence["review_imported_baseline"] = {
                "verified": reviewed_baseline.status == "verified",
                "reason_code": route_reason_code,
                "receipt_backed": False,
            }
            if material_reason_code is not None:
                evidence["review_imported_baseline"][
                    "material_reason_code"
                ] = material_reason_code
        if reviewed_baseline.status == "invalid":
            return _strict_gate_block(
                reason_code=evidence["review_imported_baseline"]["reason_code"],
                evidence=evidence,
                details=evidence["review_imported_baseline"],
            )

    if provenance_facts.get("helper_evidenced") is not True:
        return {
            "allowed_for_mutation": True,
            "blocked_reason": None,
            "reason_code": "strict_sidecar_integrity_verified_structural",
            "safe_next_action": "Proceed through the existing revision-aware managed helper path; do not claim receipt-backed provenance unless the write finalizes its own receipt.",
            "evidence": evidence,
            "details": {
                "receipt_store_required": False,
                "provenance_metadata_status": provenance_facts.get("metadata_status"),
            },
        }

    try:
        receipt_store_snapshot = provenance_store.capture_receipt_store_snapshot(
            storage_root=storage_root,
            project_root=project_root,
        )
    except ReceiptStoreError as exc:
        return _strict_gate_block(
            reason_code=str(exc.details.get("reason_code") or exc.reason_code),
            evidence=evidence,
            details={"verified_current_file_keys": []},
        )

    helper_evidence = bounded_current_helper_evidence_check(
        project_root=project_root,
        storage_root=storage_root,
        state=state,
        state_text=state_text,
        helper_evidenced_only=False,
        require_receipt_store=True,
        require_config_guard=False,
        daily_log_cursor=actual_daily_log_cursor,
        actual_daily_log_cursor_evidence=actual_daily_log_cursor_evidence,
        receipt_store_snapshot=receipt_store_snapshot,
    )
    evidence["helper_evidence"] = helper_evidence
    if helper_evidence.get("verified") is not True:
        return _strict_gate_block(
            reason_code=str(helper_evidence.get("reason_code") or "receipt_evidence_mismatch"),
            evidence=evidence,
            details=helper_evidence,
        )

    return {
        "allowed_for_mutation": True,
        "blocked_reason": None,
        "reason_code": "strict_sidecar_integrity_verified",
        "safe_next_action": "Proceed through a revision-aware managed helper mutation path.",
        "evidence": evidence,
        "details": {
            "verified_current_file_keys": helper_evidence.get(
                "verified_current_file_keys",
                [],
            ),
            "receipt_store": helper_evidence.get("receipt_store"),
        },
        "_receipt_store_snapshot": receipt_store_snapshot,
    }
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