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

View on GitHub
#!/usr/bin/env python3
"""Validate a RecallLoom workspace and its managed file contracts."""

from __future__ import annotations

import argparse
from datetime import datetime
import json
from pathlib import Path

from core.bridge.blocks import (
    bridge_block_integrity,
    exclude_block_integrity,
    managed_exclude_block_text,
)
from core.continuity.workday import (
    DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
    logical_workday_for,
)
from core.failure.contracts import canonical_detail_reason_contract
from core.output.privacy import (
    display_project_path,
    display_project_root_label,
    publicize_json_value,
    redact_public_text,
)
from core.output.user_status import print_user_summary, validate_user_summary
from core.provenance.inconsistent_review import (
    INCONSISTENT_REVIEW_EVIDENCE_KEY,
    REVIEW_IMPORTED_BASELINE_MATERIAL_FAILURE_REASONS,
    evaluate_current_inconsistent_review_orphan,
    evaluate_review_imported_baseline_materials,
)
from core.provenance.store import (
    RECEIPT_STORE_RELATIVE_PATH,
)
from core.provenance.evidence import (
    bounded_current_helper_evidence_check,
    capture_actual_daily_log_cursor_evidence,
    current_receipt_required_file_keys as evidence_current_receipt_required_file_keys,
    current_receipt_target_path as evidence_current_receipt_target_path,
)
from core.provenance.state import (
    build_provenance_report,
    provenance_facts_from_state,
)
from core.protocol.contracts import (
    BRIDGE_START,
    FILE_KEYS,
    LAST_WRITER_RE,
    OPTIONAL_SECTION_KEYS,
    ROOT_ENTRY_CANDIDATES,
    SECTION_KEYS,
    SUPPORTED_PROTOCOL_VERSIONS,
)
from core.protocol.markers import (
    parse_daily_log_scaffold_marker,
    parse_file_marker,
    parse_file_state_marker,
)
from core.protocol.sections import (
    duplicate_section_keys,
    missing_section_keys,
    unknown_section_keys,
)

from _common import (
    ConfigContractError,
    DAILY_LOGS_DIRNAME,
    EnvironmentContractError,
    cli_failure_payload,
    cli_failure_payload_for_exception,
    enforce_package_support_gate,
    exit_if_startup_scratch_residue,
    exit_with_cli_error,
    StorageResolutionError,
    ValidationFinding,
    CONTEXT_DIRNAME,
    ensure_supported_python_version,
    find_recallloom_root,
    invalid_iso_like_daily_log_files,
    DailyLogCursorError,
    daily_log_cursor_from_text,
    daily_log_cursor_is_empty_scaffold,
    daily_log_cursor_is_legacy_empty,
    latest_active_daily_log_cursor,
    load_workspace_state,
    is_optional_storage_file,
    is_required_storage_directory,
    is_required_storage_file,
    parse_daily_log_entry_line,
    unknown_storage_assets,
    parse_iso_date,
    read_text,
    sorted_active_daily_log_files,
    sorted_daily_log_files,
    validate_iso_date,
)

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Validate a RecallLoom workspace and its managed file contracts."
    )
    parser.add_argument(
        "path",
        nargs="?",
        default=".",
        help="Project path or a descendant path. Defaults to the current working directory.",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Print structured JSON output.",
    )
    parser.add_argument(
        "--require-provenance",
        action="store_true",
        help="Require explicit helper receipt evidence in addition to structural validation.",
    )
    scope = parser.add_mutually_exclusive_group()
    scope.add_argument(
        "--changed-only",
        action="store_true",
        help="With --require-provenance, verify bounded current receipt-store evidence.",
    )
    scope.add_argument(
        "--full",
        action="store_true",
        help=(
            "With --require-provenance, run the bounded current receipt-store audit. "
            "This MVP does not perform historical receipt-chain validation."
        ),
    )
    return parser


def validate_provenance_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
    scope_count = int(bool(args.changed_only)) + int(bool(args.full))
    if args.require_provenance:
        if scope_count != 1:
            parser.error("--require-provenance requires exactly one scope flag: --changed-only or --full.")
        return
    if scope_count:
        parser.error("--changed-only and --full require --require-provenance.")


def add_finding(findings: list[ValidationFinding], level: str, code: str, message: str, path: Path) -> None:
    findings.append(ValidationFinding(level=level, code=code, message=message, path=path))


def validate_marker(path: Path, text: str, expected_file_key: str, workspace, findings: list[ValidationFinding]):
    marker = parse_file_marker(text)
    if marker is None:
        add_finding(findings, "error", "missing_file_marker", "Missing RecallLoom file marker", path)
        return None
    if marker.file_key != expected_file_key:
        add_finding(
            findings,
            "error",
            "wrong_file_marker",
            f"Expected file marker '{expected_file_key}', found '{marker.file_key}'",
            path,
        )
    if marker.version not in SUPPORTED_PROTOCOL_VERSIONS:
        add_finding(
            findings,
            "error",
            "unsupported_protocol_marker_version",
            (
                f"Unsupported file marker version '{marker.version}'. "
                f"Supported protocol versions: {sorted(SUPPORTED_PROTOCOL_VERSIONS)}"
            ),
            path,
        )
    elif (
        workspace.protocol_version is not None
        and workspace.protocol_version_supported
        and marker.version != workspace.protocol_version
    ):
        add_finding(
            findings,
            "error",
            "protocol_marker_version_mismatch",
            (
                f"File marker version '{marker.version}' does not match "
                f"config protocol_version '{workspace.protocol_version}'"
            ),
            path,
        )
    return marker


def validate_language_match(
    path: Path,
    detected_language: str | None,
    expected_language: str,
    findings: list[ValidationFinding],
) -> None:
    if detected_language is None:
        return
    if detected_language != expected_language:
        add_finding(
            findings,
            "error",
            "workspace_language_mismatch",
            (
                f"File marker language '{detected_language}' does not match "
                f"workspace_language '{expected_language}'"
            ),
            path,
        )


def validate_file_state_marker(path: Path, text: str, findings: list[ValidationFinding]) -> None:
    state = parse_file_state_marker(text)
    if state is None:
        add_finding(
            findings,
            "error",
            "missing_file_state_marker",
            "Missing required file-state metadata marker",
            path,
        )


def validate_state_file_entry(
    state: dict | None,
    *,
    file_key: str,
    state_path: Path,
    findings: list[ValidationFinding],
) -> dict | None:
    if state is None:
        return None
    files_state = state.get("files", {})
    entry = files_state.get(file_key)
    if not isinstance(entry, dict):
        add_finding(
            findings,
            "error",
            "missing_state_file_entry",
            f"state.json is missing the required files.{file_key} entry",
            state_path,
        )
        return None
    if not isinstance(entry.get("file_revision"), int) or entry["file_revision"] < 1:
        add_finding(
            findings,
            "error",
            "invalid_state_file_revision",
            f"state.json files.{file_key}.file_revision must be a positive integer",
            state_path,
        )
    if not isinstance(entry.get("updated_at"), str) or not entry["updated_at"].strip():
        add_finding(
            findings,
            "error",
            "invalid_state_file_updated_at",
            f"state.json files.{file_key}.updated_at must be a non-empty string",
            state_path,
        )
    if not isinstance(entry.get("writer_id"), str) or not entry["writer_id"].strip():
        add_finding(
            findings,
            "error",
            "invalid_state_file_writer_id",
            f"state.json files.{file_key}.writer_id must be a non-empty string",
            state_path,
        )
    if (
        not isinstance(entry.get("base_workspace_revision"), int)
        or entry["base_workspace_revision"] < 1
    ):
        add_finding(
            findings,
            "error",
            "invalid_state_file_base_workspace_revision",
            f"state.json files.{file_key}.base_workspace_revision must be a positive integer",
            state_path,
        )
    return entry


def validate_file_state_against_snapshot(
    path: Path,
    *,
    file_key: str,
    file_state,
    state: dict | None,
    findings: list[ValidationFinding],
) -> None:
    if state is None or file_state is None:
        return
    state_path = path.parent / FILE_KEYS["state"]
    expected = validate_state_file_entry(state, file_key=file_key, state_path=state_path, findings=findings)
    if not expected:
        return
    if expected.get("file_revision") != file_state.revision:
        add_finding(
            findings,
            "error",
            f"{file_key}_revision_mismatch",
            f"{file_key} file-state revision does not match state.json",
            path,
        )
    if expected.get("updated_at") != file_state.updated_at:
        add_finding(
            findings,
            "error",
            f"{file_key}_updated_at_mismatch",
            f"{file_key} file-state updated-at does not match state.json",
            path,
        )
    if expected.get("writer_id") != file_state.writer_id:
        add_finding(
            findings,
            "error",
            f"{file_key}_writer_id_mismatch",
            f"{file_key} file-state writer-id does not match state.json",
            path,
        )
    if expected.get("base_workspace_revision") != file_state.base_workspace_revision:
        add_finding(
            findings,
            "error",
            f"{file_key}_base_workspace_revision_mismatch",
            f"{file_key} file-state base-workspace-revision does not match state.json",
            path,
        )


def validate_section_semantics(
    path: Path,
    text: str,
    required_keys: list[str],
    optional_keys: list[str],
    findings: list[ValidationFinding],
    missing_level: str = "error",
) -> None:
    allowed = [*required_keys, *optional_keys]

    missing = missing_section_keys(text, required_keys)
    for key in missing:
        add_finding(
            findings,
            missing_level,
            "missing_required_section",
            f"Missing required section marker: {key}",
            path,
        )

    duplicates = duplicate_section_keys(text)
    for key in duplicates:
        add_finding(
            findings,
            "error",
            "duplicate_section_marker",
            f"Duplicate section marker detected: {key}",
            path,
        )

    unknown = unknown_section_keys(text, allowed)
    for key in unknown:
        add_finding(
            findings,
            "warning",
            "unknown_section_marker",
            f"Unknown section marker detected: {key}",
            path,
        )


def validate_context_brief(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    path = workspace.storage_root / FILE_KEYS["context_brief"]
    if not path.is_file():
        level = "error" if is_required_storage_file(FILE_KEYS["context_brief"]) else "warning"
        add_finding(findings, level, "missing_context_brief", "Missing required file: context_brief.md", path)
        return
    text = read_text(path)
    marker = validate_marker(path, text, "context_brief", workspace, findings)
    validate_language_match(path, marker.language if marker else None, workspace.workspace_language, findings)
    validate_file_state_marker(path, text, findings)
    file_state = parse_file_state_marker(text)
    validate_file_state_against_snapshot(
        path,
        file_key="context_brief",
        file_state=file_state,
        state=state,
        findings=findings,
    )
    validate_section_semantics(
        path,
        text,
        SECTION_KEYS["context_brief"],
        OPTIONAL_SECTION_KEYS.get("context_brief", []),
        findings,
    )


def validate_rolling_summary(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    path = workspace.storage_root / FILE_KEYS["rolling_summary"]
    if not path.is_file():
        level = "error" if is_required_storage_file(FILE_KEYS["rolling_summary"]) else "warning"
        add_finding(findings, level, "missing_rolling_summary", "Missing required file: rolling_summary.md", path)
        return

    text = read_text(path)
    marker = validate_marker(path, text, "rolling_summary", workspace, findings)
    validate_language_match(path, marker.language if marker else None, workspace.workspace_language, findings)
    validate_file_state_marker(path, text, findings)
    file_state = parse_file_state_marker(text)
    validate_file_state_against_snapshot(
        path,
        file_key="rolling_summary",
        file_state=file_state,
        state=state,
        findings=findings,
    )
    lines = text.splitlines()
    if len(lines) < 3:
        add_finding(findings, "error", "invalid_rolling_summary", "rolling_summary.md is too short", path)
    else:
        match = LAST_WRITER_RE.match(lines[1].strip())
        if not match:
            add_finding(
                findings,
                "error",
                "invalid_last_writer",
                "rolling_summary.md second line must be a valid last-writer marker",
                path,
            )
        elif not validate_iso_date(match.group("date")):
            add_finding(
                findings,
                "error",
                "invalid_last_writer_date",
                "rolling_summary.md contains an invalid last-writer date",
                path,
            )

    validate_section_semantics(
        path,
        text,
        SECTION_KEYS["rolling_summary"],
        OPTIONAL_SECTION_KEYS.get("rolling_summary", []),
        findings,
    )
    if (
        state is not None
        and file_state is not None
        and state.get("workspace_revision", 0) > file_state.base_workspace_revision
    ):
        add_finding(
            findings,
            "warning",
            "rolling_summary_workspace_revision_behind",
            (
                "rolling_summary.md was last committed against an older workspace revision. "
                "Rerun preflight and review it before treating it as the current state."
            ),
            path,
        )


def validate_daily_logs(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    logs_dir = workspace.storage_root / DAILY_LOGS_DIRNAME
    if not logs_dir.is_dir():
        level = "error" if is_required_storage_directory("daily_logs") else "warning"
        add_finding(findings, level, "missing_daily_logs", "Missing required directory: daily_logs", logs_dir)
        return

    for log_path in invalid_iso_like_daily_log_files(logs_dir):
        add_finding(
            findings,
            "error",
            "invalid_daily_log_date",
            "Daily log filename matches the date pattern but is not a valid ISO date",
            log_path,
        )

    dated_logs = sorted_daily_log_files(logs_dir)
    active_logs = sorted_active_daily_log_files(logs_dir)
    latest_log_path = active_logs[-1] if active_logs else None
    logical_workday = logical_workday_for(
        datetime.now().astimezone(),
        DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
    )

    for log_path in active_logs:
        if parse_iso_date(log_path.stem) > logical_workday:
            add_finding(
                findings,
                "error",
                "future_dated_active_daily_log",
                (
                    "Future-dated active daily log is ahead of the current logical workday "
                    f"{logical_workday.isoformat()}."
                ),
                log_path,
            )

    for log_path in dated_logs:
        text = read_text(log_path)
        marker = validate_marker(log_path, text, "daily_log", workspace, findings)
        validate_language_match(log_path, marker.language if marker else None, workspace.workspace_language, findings)
        try:
            daily_log_cursor_from_text(
                text,
                path=log_path,
                latest_file=log_path.relative_to(workspace.storage_root).as_posix(),
            )
        except DailyLogCursorError as exc:
            add_finding(
                findings,
                "error",
                exc.reason_code,
                str(exc),
                log_path,
            )
            continue
        scaffold = parse_daily_log_scaffold_marker(text)
        entry_markers = []
        entry_lines: list[list[str]] = []
        current_entry_lines: list[str] = []
        for line in text.splitlines()[1:]:
            entry = parse_daily_log_entry_line(line)
            if entry is not None:
                if current_entry_lines:
                    entry_lines.append(current_entry_lines)
                    current_entry_lines = []
                entry_markers.append(entry)
                continue
            if entry_markers:
                current_entry_lines.append(line)
        if current_entry_lines:
            entry_lines.append(current_entry_lines)

        if scaffold:
            validate_section_semantics(
                log_path,
                text,
                SECTION_KEYS["daily_log"],
                OPTIONAL_SECTION_KEYS.get("daily_log", []),
                findings,
            )
            continue

        if len(entry_markers) != len(entry_lines):
            add_finding(
                findings,
                "error",
                "invalid_daily_log_entry_structure",
                "Daily log entry blocks are malformed or incomplete",
                log_path,
            )
            continue

        for idx, entry in enumerate(entry_markers):
            block_text = "\n".join(entry_lines[idx])
            expected_seq = idx + 1
            if entry.entry_seq != expected_seq:
                add_finding(
                    findings,
                    "error",
                    "invalid_daily_log_entry_sequence",
                    (
                        f"Daily log entry sequence is not contiguous. Expected entry_seq={expected_seq}, "
                        f"found {entry.entry_seq}."
                    ),
                    log_path,
                )
            if entry.entry_id != f"entry-{entry.entry_seq}":
                add_finding(
                    findings,
                    "error",
                    "noncanonical_daily_log_entry_id",
                    (
                        f"Daily log entry id '{entry.entry_id}' does not match the canonical "
                        f"'entry-{entry.entry_seq}' shape."
                    ),
                    log_path,
                )
            validate_section_semantics(
                log_path,
                block_text,
                SECTION_KEYS["daily_log"],
                OPTIONAL_SECTION_KEYS.get("daily_log", []),
                findings,
            )

        if state is not None and log_path == latest_log_path:
            daily_state = state.get("daily_logs", {})
            latest_entry = entry_markers[-1] if entry_markers else None
            if daily_state.get("entry_count") != len(entry_markers):
                add_finding(
                    findings,
                    "error",
                    "daily_log_entry_count_mismatch",
                    "Latest daily log entry count does not match state.json",
                    log_path,
                )
            if latest_entry is not None:
                if daily_state.get("latest_entry_id") != latest_entry.entry_id:
                    add_finding(
                        findings,
                        "error",
                        "daily_log_entry_id_mismatch",
                        "Latest daily-log entry id does not match state.json",
                        log_path,
                    )
                if daily_state.get("latest_entry_seq") != latest_entry.entry_seq:
                    add_finding(
                        findings,
                        "error",
                        "daily_log_entry_seq_mismatch",
                        "Latest daily-log entry sequence does not match state.json",
                        log_path,
                    )
                updated_at = daily_state.get("updated_at")
                if updated_at is None:
                    add_finding(
                        findings,
                        "warning",
                        "legacy_optional_metadata_missing",
                        (
                            "state.json daily_logs.updated_at is absent; legacy protocol 1.0 "
                            "sidecars may omit this optional freshness annotation."
                        ),
                        workspace.storage_root / FILE_KEYS["state"],
                    )
                elif isinstance(updated_at, str) and updated_at.strip():
                    try:
                        updated_at_dt = datetime.fromisoformat(updated_at)
                        latest_entry_dt = datetime.fromisoformat(latest_entry.created_at)
                    except ValueError:
                        add_finding(
                            findings,
                            "warning",
                            "invalid_daily_logs_updated_at_freshness",
                            (
                                "state.json daily_logs.updated_at or latest daily-log entry "
                                "created-at is not ISO parseable."
                            ),
                            workspace.storage_root / FILE_KEYS["state"],
                        )
                    else:
                        if updated_at_dt < latest_entry_dt:
                            add_finding(
                                findings,
                                "warning",
                                "daily_logs_updated_at_stale",
                                "state.json daily_logs.updated_at is older than the latest daily-log entry.",
                                workspace.storage_root / FILE_KEYS["state"],
                            )


def validate_unknown_storage_assets(workspace, findings: list[ValidationFinding]) -> None:
    invalid_daily_logs = set(invalid_iso_like_daily_log_files(workspace.storage_root / DAILY_LOGS_DIRNAME))
    for path in unknown_storage_assets(workspace.storage_root):
        if path in invalid_daily_logs:
            continue
        add_finding(
            findings,
            "error",
            "unexpected_storage_asset",
            "Unexpected non-managed asset detected inside the RecallLoom storage root",
            path,
        )


def validate_update_protocol(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    path = workspace.storage_root / FILE_KEYS["update_protocol"]
    if not path.is_file():
        level = "warning" if is_optional_storage_file(FILE_KEYS["update_protocol"]) else "error"
        message = "Missing recommended file: update_protocol.md" if level == "warning" else "Missing required file: update_protocol.md"
        add_finding(findings, level, "missing_update_protocol", message, path)
        return
    text = read_text(path)
    marker = validate_marker(path, text, "update_protocol", workspace, findings)
    validate_language_match(path, marker.language if marker else None, workspace.workspace_language, findings)
    validate_file_state_marker(path, text, findings)
    file_state = parse_file_state_marker(text)
    validate_file_state_against_snapshot(
        path,
        file_key="update_protocol",
        file_state=file_state,
        state=state,
        findings=findings,
    )
    if state is not None and file_state is not None:
        if state.get("update_protocol_revision") != file_state.revision:
            add_finding(
                findings,
                "error",
                "update_protocol_workspace_revision_mismatch",
                "update_protocol_revision in state.json does not match update_protocol file-state revision",
                path,
            )
    validate_section_semantics(
        path,
        text,
        ["project_specific_overrides"],
        OPTIONAL_SECTION_KEYS.get("update_protocol", []),
        findings,
    )


def validate_config(workspace, findings: list[ValidationFinding]) -> None:
    if workspace.config_path is None or not workspace.config_path.is_file():
        level = "error" if is_required_storage_file(FILE_KEYS["config"]) else "warning"
        add_finding(
            findings,
            level,
            "missing_config",
            "Managed storage modes require config.json in the storage root",
            workspace.storage_root / FILE_KEYS["config"],
        )


def validate_state_file(workspace, findings: list[ValidationFinding]) -> None:
    path = workspace.storage_root / FILE_KEYS["state"]
    if not path.is_file():
        level = "error" if is_required_storage_file(FILE_KEYS["state"]) else "warning"
        add_finding(findings, level, "missing_state", "Missing required file: state.json", path)
        return
    try:
        state = load_workspace_state(path)
    except ConfigContractError as exc:
        add_finding(findings, "error", "invalid_state", str(exc), path)
        return
    if not isinstance(state.get("workspace_revision"), int) or state["workspace_revision"] < 1:
        add_finding(findings, "error", "invalid_workspace_revision", "state.json must contain a positive workspace_revision", path)
    if not isinstance(state.get("update_protocol_revision"), int) or state["update_protocol_revision"] < 1:
        add_finding(findings, "error", "invalid_update_protocol_revision", "state.json must contain a positive update_protocol_revision", path)
        return
    if state.get("git_exclude_mode") not in {"managed", "skipped", "not_applicable"}:
        add_finding(findings, "error", "invalid_git_exclude_mode", "state.json contains an invalid git_exclude_mode", path)
    if not isinstance(state.get("bridged_entries"), dict):
        add_finding(findings, "error", "invalid_bridged_entries", "state.json bridged_entries must be an object", path)
    else:
        for rel_target, bridge_state in state["bridged_entries"].items():
            if not isinstance(rel_target, str) or not rel_target:
                add_finding(findings, "error", "invalid_bridged_entry_key", "state.json bridged_entries keys must be non-empty strings", path)
            if not isinstance(bridge_state, dict):
                add_finding(findings, "error", "invalid_bridged_entry_state", "state.json bridged_entries values must be objects", path)
    if not isinstance(state.get("files"), dict):
        add_finding(findings, "error", "invalid_state_files", "state.json files must be an object", path)
    else:
        for file_key in ("context_brief", "rolling_summary", "update_protocol"):
            validate_state_file_entry(state, file_key=file_key, state_path=path, findings=findings)
    if not isinstance(state.get("daily_logs"), dict):
        add_finding(findings, "error", "invalid_daily_logs_state", "state.json daily_logs must be an object", path)
    else:
        daily_state = state["daily_logs"]
        latest_file = daily_state.get("latest_file")
        if latest_file is not None and (not isinstance(latest_file, str) or not latest_file.strip()):
            add_finding(findings, "error", "invalid_latest_daily_log", "state.json daily_logs.latest_file must be null or a non-empty string", path)
        latest_entry_seq = daily_state.get("latest_entry_seq")
        if latest_entry_seq is not None and (
            not isinstance(latest_entry_seq, int) or latest_entry_seq < 0
        ):
            add_finding(findings, "error", "invalid_latest_daily_log_entry_seq", "state.json daily_logs.latest_entry_seq must be null or a non-negative integer", path)
        latest_entry_id = daily_state.get("latest_entry_id")
        if latest_entry_id is not None and (not isinstance(latest_entry_id, str) or not latest_entry_id.strip()):
            add_finding(findings, "error", "invalid_latest_daily_log_entry_id", "state.json daily_logs.latest_entry_id must be null or a non-empty string", path)
        if not isinstance(daily_state.get("entry_count"), int) or daily_state["entry_count"] < 0:
            add_finding(findings, "error", "invalid_daily_log_entry_count", "state.json daily_logs.entry_count must be a non-negative integer", path)
        latest_entry_seq_value = 0 if latest_entry_seq is None else latest_entry_seq
        if isinstance(latest_entry_seq_value, int) and daily_state.get("entry_count", 0) < latest_entry_seq_value:
            add_finding(findings, "error", "invalid_daily_log_entry_count_order", "state.json daily_logs.entry_count cannot be smaller than latest_entry_seq", path)
        if latest_file is None:
            if latest_entry_id is not None or latest_entry_seq not in {0, None} or daily_state.get("entry_count") != 0:
                add_finding(findings, "error", "invalid_daily_log_null_cursor", "state.json daily_logs must use the null/zero cursor shape when no active daily log exists", path)
        else:
            empty_scaffold_cursor = (
                latest_entry_id is None
                and latest_entry_seq in {0, None}
                and daily_state.get("entry_count") == 0
            )
            populated_cursor = (
                latest_entry_id is not None
                and isinstance(latest_entry_seq, int)
                and latest_entry_seq >= 1
                and daily_state.get("entry_count", 0) >= 1
            )
            if not empty_scaffold_cursor and not populated_cursor:
                add_finding(findings, "error", "invalid_daily_log_populated_cursor", "state.json daily_logs must record either an empty-scaffold cursor or a populated cursor when latest_file is set", path)

    if (
        workspace.protocol_version is not None
        and not workspace.protocol_version_supported
    ):
        add_finding(
            findings,
            "error",
            "unsupported_protocol_version",
            (
                f"Unsupported protocol_version '{workspace.protocol_version}'. "
                f"Supported protocol versions: {sorted(SUPPORTED_PROTOCOL_VERSIONS)}"
            ),
            workspace.config_path,
        )
    if not workspace.storage_mode_matches_path:
        add_finding(
            findings,
            "error",
            "storage_mode_path_mismatch",
            (
                f"Config declares storage_mode '{workspace.declared_storage_mode}', "
                f"but the detected storage root implies '{workspace.storage_mode}'"
            ),
            workspace.config_path,
        )


def load_state_snapshot(workspace, findings: list[ValidationFinding]) -> dict | None:
    path = workspace.storage_root / FILE_KEYS["state"]
    if not path.is_file():
        return None
    try:
        return load_workspace_state(path)
    except ConfigContractError as exc:
        if not any(f.code == "invalid_state" and f.path == path for f in findings):
            add_finding(findings, "error", "invalid_state", str(exc), path)
        return None


def validate_daily_log_state(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    if state is None:
        return
    daily_state = state.get("daily_logs", {})
    latest_file = daily_state.get("latest_file")
    actual_latest = sorted_active_daily_log_files(workspace.storage_root / DAILY_LOGS_DIRNAME)
    actual_latest_rel = (
        actual_latest[-1].relative_to(workspace.storage_root).as_posix()
        if actual_latest
        else None
    )
    if latest_file is None:
        if actual_latest_rel is not None:
            state_cursor = {
                "latest_file": None,
                "latest_entry_id": daily_state.get("latest_entry_id"),
                "latest_entry_seq": daily_state.get("latest_entry_seq"),
                "entry_count": daily_state.get("entry_count"),
            }
            try:
                actual_cursor = latest_active_daily_log_cursor(workspace.storage_root).as_state_fields()
            except DailyLogCursorError:
                actual_cursor = {}
            if (
                daily_log_cursor_is_legacy_empty(state_cursor)
                and daily_log_cursor_is_empty_scaffold(actual_cursor)
                and actual_cursor.get("latest_file") == actual_latest_rel
            ):
                return
            add_finding(
                findings,
                "error",
                "missing_latest_daily_log_state",
                "state.json does not record the latest daily log even though one exists",
                workspace.storage_root / FILE_KEYS["state"],
            )
        return
    if actual_latest_rel is None:
        add_finding(
            findings,
            "error",
            "unexpected_latest_daily_log_state",
            "state.json records a latest active daily log even though no active daily log currently exists",
            workspace.storage_root / FILE_KEYS["state"],
        )
        return
    latest_path = workspace.storage_root / latest_file
    if not latest_path.is_file():
        add_finding(
            findings,
            "error",
            "missing_latest_daily_log",
            "state.json points to a latest daily log file that does not exist",
            workspace.storage_root / FILE_KEYS["state"],
        )
    elif actual_latest_rel is not None and latest_file != actual_latest_rel:
        add_finding(
            findings,
            "error",
            "latest_daily_log_state_mismatch",
            "state.json latest daily log does not match the latest ISO-dated daily log",
            workspace.storage_root / FILE_KEYS["state"],
        )


def validate_bridge_blocks(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    bridged_entries = state.get("bridged_entries", {}) if state else {}
    for rel_path in ROOT_ENTRY_CANDIDATES:
        path = workspace.project_root / rel_path
        if not path.is_file():
            if state and rel_path.as_posix() in bridged_entries:
                add_finding(
                    findings,
                    "error",
                    "missing_bridged_entry_target",
                    "state.json records a bridged entry whose target file is missing",
                    workspace.project_root / rel_path,
                )
            continue
        ok, reason = bridge_block_integrity(read_text(path))
        if not ok:
            add_finding(
                findings,
                "error",
                reason or "bridge_block_invalid",
                "RecallLoom managed bridge block is malformed or incomplete",
                path,
            )
            continue

        has_bridge_block = BRIDGE_START in read_text(path)
        rel_key = rel_path.as_posix()
        state_records_entry = bool(state and rel_key in bridged_entries)
        if state_records_entry and not has_bridge_block:
            add_finding(
                findings,
                "error",
                "missing_bridged_entry_block",
                "state.json records a bridged entry but the target file has no managed bridge block",
                path,
            )
        if has_bridge_block and not state_records_entry:
            add_finding(
                findings,
                "error",
                "untracked_bridged_entry_block",
                "A managed bridge block exists in the target file but state.json does not record it",
                path,
            )


def validate_exclude_block(workspace, state: dict | None, findings: list[ValidationFinding]) -> None:
    if workspace.storage_mode != "hidden":
        return
    exclude_path = workspace.project_root / ".git" / "info" / "exclude"
    expected_mode = state.get("git_exclude_mode") if state else None
    if not exclude_path.is_file():
        if expected_mode == "managed":
            add_finding(
                findings,
                "error",
                "missing_git_exclude_block",
                "state.json expects a managed git exclude block, but .git/info/exclude is missing",
                exclude_path,
            )
        return
    exclude_text = read_text(exclude_path)
    ok, reason = exclude_block_integrity(exclude_text)
    if not ok:
        add_finding(
            findings,
            "error" if expected_mode == "managed" else "warning",
            reason or "exclude_block_invalid",
            "RecallLoom managed exclude block is malformed or incomplete",
            exclude_path,
        )
        return

    block_text = managed_exclude_block_text(exclude_text)
    has_block = block_text is not None
    if expected_mode == "managed":
        if not has_block:
            add_finding(
                findings,
                "error",
                "missing_git_exclude_block",
                "state.json expects a managed git exclude block, but none is present",
                exclude_path,
            )
        elif f"{CONTEXT_DIRNAME}/" not in block_text:
            add_finding(
                findings,
                "error",
                "git_exclude_entry_missing",
                f"state.json expects a managed git exclude entry for {CONTEXT_DIRNAME}/, but it is missing from the managed block",
                exclude_path,
            )
    elif has_block:
        add_finding(
            findings,
            "error",
            "unexpected_git_exclude_block",
            "A managed git exclude block exists, but state.json does not record git_exclude_mode=managed",
            exclude_path,
        )
def current_receipt_required_file_keys(workspace, state: dict) -> list[str]:
    return evidence_current_receipt_required_file_keys(
        storage_root=workspace.storage_root,
        state=state,
    )


def current_receipt_target_path(
    workspace,
    state: dict,
    file_key: str,
    *,
    daily_log_cursor: dict[str, object] | None = None,
) -> Path:
    return evidence_current_receipt_target_path(
        storage_root=workspace.storage_root,
        state=state,
        file_key=file_key,
        daily_log_cursor=daily_log_cursor,
    )


def validate_provenance_receipts(
    workspace,
    state: dict | None,
    findings: list[ValidationFinding],
    *,
    audit_scope: str,
) -> dict:
    store_path = workspace.storage_root / RECEIPT_STORE_RELATIVE_PATH
    result = {
        "required": True,
        "audit_scope": audit_scope,
        "historical_chain_audit": False,
        "receipt_store": {
            "store_file": RECEIPT_STORE_RELATIVE_PATH,
            "verified": False,
        },
        "required_current_file_keys": [],
        "verified_current_file_keys": [],
    }
    if state is None:
        add_finding(
            findings,
            "error",
            "provenance_state_unavailable",
            "state.json must be readable for explicit provenance validation.",
            workspace.storage_root / FILE_KEYS["state"],
        )
        return result

    try:
        state_text = read_text(workspace.storage_root / FILE_KEYS["state"])
    except (OSError, UnicodeDecodeError) as exc:
        add_finding(
            findings,
            "error",
            "provenance_state_unreadable",
            f"state.json must be readable for explicit provenance validation: {exc}",
            workspace.storage_root / FILE_KEYS["state"],
        )
        return result

    reviewed_baseline = evaluate_review_imported_baseline_materials(
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
        state=state,
        state_text=state_text,
    )
    if reviewed_baseline.status == "invalid":
        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"
        result["receipt_store"]["reason_code"] = (
            "review_imported_baseline_non_receipt_backed"
        )
        result["review_imported_baseline_validation"] = {
            "verified": False,
            "reason_code": route_reason_code,
            "receipt_backed": False,
        }
        if material_reason_code is not None:
            result["review_imported_baseline_validation"][
                "material_reason_code"
            ] = material_reason_code
        add_finding(
            findings,
            "error",
            f"provenance_{reviewed_baseline.reason_code}",
            "The exact reviewed-baseline binding or human review material is no longer current.",
            workspace.storage_root / FILE_KEYS["state"],
        )
        return result
    if reviewed_baseline.status == "verified":
        result["receipt_store"]["reason_code"] = (
            "review_imported_baseline_non_receipt_backed"
        )
        result["review_imported_baseline_validation"] = {
            "verified": True,
            "reason_code": reviewed_baseline.reason_code,
            "receipt_backed": False,
            "proposal_digest": reviewed_baseline.proposal_digest,
            "review_digest": reviewed_baseline.review_digest,
        }
        if reviewed_baseline.binding_digest is not None:
            result["review_imported_baseline_validation"][
                "inconsistent_review_binding_digest"
            ] = reviewed_baseline.binding_digest
        return result

    actual_daily_log_cursor = None
    actual_daily_log_cursor_evidence = None
    try:
        parsed_daily_log_cursor, actual_daily_log_cursor_evidence = (
            capture_actual_daily_log_cursor_evidence(
                storage_root=workspace.storage_root,
                state=state,
                state_text=state_text,
            )
        )
        actual_daily_log_cursor = parsed_daily_log_cursor.as_state_fields()
    except DailyLogCursorError as exc:
        result["receipt_store"]["reason_code"] = exc.reason_code
        add_finding(
            findings,
            "error",
            f"provenance_{exc.reason_code}",
            "The current daily-log cursor could not be captured as a stable on-disk snapshot.",
            exc.path or workspace.storage_root / DAILY_LOGS_DIRNAME,
        )
        return result
    if actual_daily_log_cursor_evidence is None:
        result["receipt_store"]["reason_code"] = "daily_log_cursor_mismatch"
        add_finding(
            findings,
            "error",
            "provenance_daily_log_cursor_mismatch",
            "The current daily-log cursor could not be bound to the exact state snapshot.",
            workspace.storage_root / FILE_KEYS["state"],
        )
        return result

    check = bounded_current_helper_evidence_check(
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
        state=state,
        state_text=state_text,
        helper_evidenced_only=False,
        require_receipt_store=True,
        daily_log_cursor=actual_daily_log_cursor,
        actual_daily_log_cursor_evidence=actual_daily_log_cursor_evidence,
    )
    result["required_current_file_keys"] = check.get("required_current_file_keys", [])
    result["verified_current_file_keys"] = check.get("verified_current_file_keys", [])
    if isinstance(check.get("receipt_store"), dict):
        result["receipt_store"] = check["receipt_store"]
    else:
        result["receipt_store"]["reason_code"] = check.get("reason_code")
    if isinstance(check.get("config_guard"), dict):
        result["config_guard"] = check["config_guard"]

    for file_key in check.get("missing_current_file_keys", []):
        if isinstance(file_key, str):
            add_finding(
                findings,
                "error",
                f"provenance_{file_key}_receipt_missing",
                "Current managed surface is missing finalized receipt-store evidence for this file.",
                current_receipt_target_path(
                    workspace,
                    state,
                    file_key,
                    daily_log_cursor=actual_daily_log_cursor,
                ),
            )

    if check.get("verified") is not True:
        reason_code = str(check.get("reason_code") or "receipt_evidence_mismatch")
        finding_path = store_path
        config_guard = check.get("config_guard")
        if isinstance(config_guard, dict) and isinstance(config_guard.get("path"), str):
            finding_path = Path(config_guard["path"])
        add_finding(
            findings,
            "error",
            f"provenance_{reason_code}",
            f"Bounded current receipt-store evidence was not verified ({reason_code}).",
            finding_path,
        )
    result["receipt_store"]["verified"] = check.get("verified") is True
    return result


def skipped_provenance_validation(*, audit_scope: str, reason_code: str) -> dict:
    return {
        "required": True,
        "audit_scope": audit_scope,
        "historical_chain_audit": False,
        "skipped": True,
        "reason_code": reason_code,
        "receipt_store": {
            "store_file": RECEIPT_STORE_RELATIVE_PATH,
            "verified": False,
        },
        "verified_current_file_keys": [],
    }


def main() -> None:
    parser = build_parser()
    args = parser.parse_args()
    validate_provenance_args(parser, args)
    try:
        ensure_supported_python_version()
    except EnvironmentContractError as exc:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=str(exc),
            payload=cli_failure_payload(
                "python_runtime_unavailable",
                error=str(exc),
                extra={"valid": False},
            ),
        )
    enforce_package_support_gate(parser, json_mode=args.json)

    try:
        workspace = find_recallloom_root(
            args.path,
            allow_unsupported_version=True,
            allow_storage_mode_mismatch=True,
        )
    except (StorageResolutionError, ConfigContractError) as exc:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=str(exc),
            payload=cli_failure_payload_for_exception(
                exc,
                default_reason="damaged_sidecar",
                extra={"valid": False},
            ),
        )
    if workspace is None:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=1,
            message="No RecallLoom project root found.",
            payload=cli_failure_payload(
                "no_project_root",
                error="No RecallLoom project root found.",
                extra={"valid": False},
            ),
        )
    startup_residue_report = exit_if_startup_scratch_residue(
        parser,
        json_mode=args.json,
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
    )

    findings: list[ValidationFinding] = []
    inconsistent_review_result = None
    try:
        validate_config(workspace, findings)
        validate_state_file(workspace, findings)
        state = load_state_snapshot(workspace, findings)
        validate_context_brief(workspace, state, findings)
        validate_rolling_summary(workspace, state, findings)
        validate_daily_logs(workspace, state, findings)
        validate_daily_log_state(workspace, state, findings)
        validate_update_protocol(workspace, state, findings)
        validate_bridge_blocks(workspace, state, findings)
        validate_exclude_block(workspace, state, findings)
        validate_unknown_storage_assets(workspace, findings)
        structural_errors = [finding for finding in findings if finding.level == "error"]
        provenance_metadata = state.get("provenance") if isinstance(state, dict) else None
        if (
            args.json
            and args.require_provenance
            and args.changed_only
            and not structural_errors
            and isinstance(provenance_metadata, dict)
            and provenance_metadata.get("state_label")
            == "inconsistent_or_tampered_evidence"
            and INCONSISTENT_REVIEW_EVIDENCE_KEY in provenance_metadata
        ):
            state_text = read_text(workspace.storage_root / FILE_KEYS["state"])
            inconsistent_review_result = evaluate_current_inconsistent_review_orphan(
                project_root=workspace.project_root,
                storage_root=workspace.storage_root,
                state=state,
                state_text=state_text,
            )
        provenance_validation = None
        if args.require_provenance:
            audit_scope = (
                "bounded_current_receipt_store"
                if args.full
                else "changed_only_current_receipt_store"
            )
            if structural_errors:
                provenance_validation = skipped_provenance_validation(
                    audit_scope=audit_scope,
                    reason_code="structural_validation_failed",
                )
            else:
                provenance_validation = validate_provenance_receipts(
                    workspace,
                    state,
                    findings,
                    audit_scope=audit_scope,
                )
    except (OSError, UnicodeDecodeError) as exc:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=f"Filesystem error: {exc}",
            payload=cli_failure_payload(
                "damaged_sidecar",
                error=f"Filesystem error: {exc}",
                extra={"valid": False},
            ),
        )

    errors = [f for f in findings if f.level == "error"]
    warnings = [f for f in findings if f.level == "warning"]
    provenance_receipts_verified = False
    if isinstance(provenance_validation, dict):
        receipt_store = provenance_validation.get("receipt_store")
        provenance_receipts_verified = bool(
            isinstance(receipt_store, dict)
            and receipt_store.get("verified") is True
            and provenance_validation.get("verified_current_file_keys")
        )
    provenance_facts = provenance_facts_from_state(state, review_intent=False)
    provenance = build_provenance_report(
        sidecar_trust_state=(
            "damaged"
            if errors
            else "security_blocked"
            if provenance_facts["inconsistent_evidence"]
            else "structurally_valid"
        ),
        continuity_state=None,
        allowed_operation_level=None,
        summary_stale=None,
        receipt_chain_verified=provenance_receipts_verified,
        receipt_store_available=provenance_receipts_verified,
        legacy_sidecar=provenance_facts["legacy_sidecar"],
        review_required=provenance_facts["review_required"],
        review_imported_baseline=provenance_facts["review_imported_baseline"],
        helper_evidenced_baseline=(
            provenance_facts["helper_evidenced"] if provenance_receipts_verified else False
        ),
        unproven_sidecar_state=provenance_facts["unproven_sidecar_state"],
        metadata_status=provenance_facts["metadata_status"],
    )

    payload = {
        "project_root": str(workspace.project_root),
        "storage_root": str(workspace.storage_root),
        "storage_mode": workspace.storage_mode,
        "declared_storage_mode": workspace.declared_storage_mode,
        "workspace_language": workspace.workspace_language,
        "protocol_version": workspace.protocol_version,
        "provenance_state": provenance["state_label"],
        "provenance_metadata_status": provenance["metadata_status"],
        "write_readiness": provenance["write_readiness"],
        "side_effect": "none",
        "valid": not errors,
        "error_count": len(errors),
        "warning_count": len(warnings),
        "findings": [
            {
                "level": finding.level,
                "code": finding.code,
                "message": finding.message,
                "path": str(finding.path),
            }
            for finding in findings
        ],
    }
    user_summary = validate_user_summary(
        error_count=len(errors),
        warning_count=len(warnings),
    )
    payload["user_visible_category"] = user_summary["category"]
    payload["user_summary"] = user_summary
    if inconsistent_review_result is not None:
        if inconsistent_review_result.status == "exact_orphan":
            diagnostic_reason = (
                "post_hash_inconsistent_review_promotion_not_committed"
            )
        elif inconsistent_review_result.status == "current_no_orphan":
            diagnostic_reason = "post_hash_inconsistent_review_eligible"
        else:
            diagnostic_reason = "post_hash_inconsistent_review_binding_changed"
        route = canonical_detail_reason_contract(diagnostic_reason, language="en") or {}
        diagnostic_details = {
            "reason_code": diagnostic_reason,
            "safe_to_retry": False,
            "side_effect": "none",
            "next_action": route.get("next_action"),
        }
        if inconsistent_review_result.status in {
            "current_no_orphan",
            "exact_orphan",
        }:
            diagnostic_details["inconsistent_review_binding"] = (
                inconsistent_review_result.binding
            )
            diagnostic_details["inconsistent_review_binding_digest"] = (
                inconsistent_review_result.binding_digest
            )
        payload["details"] = diagnostic_details
        payload["write_readiness"]["next_action"] = route.get(
            "suggestion",
            route.get("next_action"),
        )
    if args.require_provenance:
        payload["provenance_validation"] = provenance_validation

    if args.json:
        if startup_residue_report is not None:
            payload["startup_residue_report"] = startup_residue_report
        public_payload = publicize_json_value(payload, project_root=workspace.project_root)
        print(json.dumps(public_payload, ensure_ascii=False, indent=2))
    else:
        print_user_summary("RecallLoom validate", user_summary)
        print(f"RecallLoom root: {display_project_root_label(workspace.project_root)}")
        print(
            "Storage root: "
            f"{display_project_path(workspace.storage_root, project_root=workspace.project_root)}"
        )
        print(f"Storage mode: {workspace.storage_mode}")
        print(f"Workspace language: {workspace.workspace_language}")
        if findings:
            for finding in findings:
                message = redact_public_text(
                    finding.message,
                    project_root=workspace.project_root,
                )
                path = display_project_path(finding.path, project_root=workspace.project_root)
                print(f"[{finding.level.upper()}] {finding.code}: {message} ({path})")
        else:
            print("No findings.")
        print(f"Errors: {len(errors)} | Warnings: {len(warnings)}")

    raise SystemExit(1 if errors else 0)


if __name__ == "__main__":
    main()
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