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/continuity/preflight.py

View on GitHub
#!/usr/bin/env python3
"""Callable preflight/readiness evaluation over a consistent workspace snapshot.

Extracted from ``preflight_context_check.py::main`` (T050-03A, frozen landing map
§7.8 packet 03A): snapshot loading, freshness/revision reasoning,
write-readiness/tier computation, and digest computation. Pure decision code — no
CLI, no argparse, no subprocess, no persistent writes, no printing. The CLI helper
delegates here and projects the returned payload into its legacy JSON/human output
unchanged.
"""

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass
from datetime import date, datetime
from pathlib import Path

from core.continuity.daily_log import (
    invalid_iso_like_daily_log_files,
    latest_active_daily_log,
    latest_active_daily_log_cursor,
    parse_daily_log_entry_line,
    validate_state_entry_bearing_latest_daily_log,
)
from core.continuity.freshness import (
    continuity_digest_bundle,
    continuity_state_for_workspace,
    evaluate_continuity_freshness,
    freshness_risk_summary,
    is_effectively_empty_summary_next_step,
)
from core.continuity.workday import (
    DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
    build_workday_decision,
    build_write_tier_judgment,
    detect_closure_signal,
)
from core.output.privacy import public_project_path, public_project_root_label
from core.output.user_status import preflight_user_summary
from core.protocol.contracts import DAILY_LOGS_DIRNAME, FILE_KEYS
from core.protocol.markers import parse_daily_log_scaffold_marker, parse_file_state_marker
from core.protocol.sections import (
    detect_update_protocol_time_policy_cues,
    extract_section_text,
)
from core.provenance.evidence import (
    strict_gate_current_receipts_verified,
    strict_sidecar_integrity_gate,
    strict_sidecar_integrity_gate_public_summary,
    strict_sidecar_no_write_failure_extra,
)
from core.provenance.state import (
    build_provenance_report,
    expected_revisions_payload,
    provenance_contract_identity,
    provenance_facts_from_state,
)
from core.trust.state import evaluate_trust_state
from core.workspace.runtime import WorkspaceInfo, load_workspace_state, read_text


class PreflightSnapshotError(Exception):
    """Structured refusal for malformed managed files during preflight snapshot loading."""

    failure_reason = "malformed_managed_file"


@dataclass(frozen=True)
class PreflightEvaluation:
    """Pure preflight/readiness outcome; adapters project it into output."""

    payload: dict
    append_date_review_required: bool


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


def latest_daily_log_marker_summary(path: Path | None) -> tuple[object | None, int, bool]:
    if path is None:
        return None, 0, False
    text = read_text(path)
    latest_entry = None
    entry_count = 0
    for line in text.splitlines():
        entry = parse_daily_log_entry_line(line)
        if entry is not None:
            latest_entry = entry
            entry_count += 1
    return latest_entry, entry_count, parse_daily_log_scaffold_marker(text)


def latest_daily_log_entry_text_digest(text: str, latest_entry) -> str | None:
    if latest_entry is None:
        return None
    lines = text.splitlines()
    start_index = None
    end_index = len(lines)
    for index, line in enumerate(lines):
        entry = parse_daily_log_entry_line(line)
        if entry is None:
            continue
        if start_index is None:
            if (
                entry.entry_id == latest_entry.entry_id
                and entry.entry_seq == latest_entry.entry_seq
                and entry.created_at == latest_entry.created_at
            ):
                start_index = index
        else:
            end_index = index
            break
    if start_index is None:
        return None
    entry_text = "\n".join(lines[start_index:end_index]).rstrip("\n") + "\n"
    return sha256_text_digest(entry_text)


def file_state_marker_from_path(path: Path):
    with path.open("r", encoding="utf-8") as handle:
        for index, line in enumerate(handle):
            state = parse_file_state_marker(line)
            if state is not None:
                return state
            if index >= 24:
                break
    return None


def recommended_actions_for_preflight(
    *,
    continuity_confidence: str,
    continuity_state: str,
    update_protocol_exists: bool,
    context_brief_exists: bool,
    latest_daily_log_exists: bool,
    workspace_is_newer: bool,
) -> list[str]:
    actions: list[str] = []
    if continuity_state == "initialized_empty_shell":
        actions.append("seed_initial_continuity")
    elif workspace_is_newer:
        actions.append("update_rolling_summary")
    else:
        actions.append("resume_from_summary")
    if update_protocol_exists:
        actions.append("review_update_protocol")
    if context_brief_exists:
        actions.append("review_context_brief")
    if latest_daily_log_exists:
        actions.append("review_latest_daily_log")
    if (
        continuity_state != "initialized_empty_shell"
        and continuity_confidence == "medium"
        and "update_rolling_summary" not in actions
    ):
        actions.append("consider_refresh_summary")
    return actions


def strict_gate_preflight_actions(actions: list[str], *, strict_gate_allows_write: bool) -> list[str]:
    if strict_gate_allows_write:
        return actions
    blocked_write_actions = {
        "seed_initial_continuity",
        "update_rolling_summary",
        "consider_refresh_summary",
    }
    return [
        "review_or_repair_sidecar_before_write",
        *(action for action in actions if action not in blocked_write_actions),
    ]


def strict_gate_preflight_failure_extra(workspace) -> dict[str, object]:
    return strict_sidecar_no_write_failure_extra(
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
        continuity_confidence="broken",
    )


def managed_body_digest(text: str) -> str:
    """Digest managed markdown body excluding RecallLoom header metadata."""

    lines = text.splitlines()
    if (
        len(lines) >= 3
        and lines[0].strip().startswith("<!-- recallloom:file=rolling_summary ")
        and lines[1].strip().startswith("<!-- last-writer:")
        and lines[2].strip().startswith("<!-- file-state:")
    ):
        body = "\n".join(lines[3:]).lstrip("\n").rstrip("\n") + "\n"
    else:
        body = text.rstrip("\n") + "\n"
    return "sha256:" + hashlib.sha256(body.encode("utf-8")).hexdigest()


def post_append_assertion_binding_seed(
    *,
    expected_workspace_revision: int,
    expected_file_revision: int,
    summary_base_workspace_revision: int | None,
    latest_daily_log_entry,
    latest_daily_log_digest: str | None,
    latest_daily_log_entry_hash: str | None,
    body_digest_before: str,
) -> dict:
    latest_created_at = latest_daily_log_entry.created_at if latest_daily_log_entry else None
    return {
        "assertion_kind": "post_append_summary_metadata_only_semantic_unchanged",
        "expected_workspace_revision": expected_workspace_revision,
        "expected_file_revision": expected_file_revision,
        "summary_base_workspace_revision": summary_base_workspace_revision,
        "latest_daily_log_entry_id": (
            latest_daily_log_entry.entry_id if latest_daily_log_entry else None
        ),
        "latest_daily_log_entry_seq": (
            latest_daily_log_entry.entry_seq if latest_daily_log_entry else None
        ),
        "latest_daily_log_entry_created_at": latest_created_at,
        "latest_daily_log_entry_date": latest_created_at[:10] if latest_created_at else None,
        "latest_daily_log_entry_hash": latest_daily_log_entry_hash,
        "latest_daily_log_digest": latest_daily_log_digest,
        "body_digest_before": body_digest_before,
    }


def build_post_append_summary_sync_contract(
    *,
    workspace,
    state: dict,
    summary_path: Path,
    summary_state,
    latest_daily_log: Path | None,
    latest_daily_log_entry,
    latest_daily_log_entry_count: int,
    latest_daily_log_digest: str | None,
    continuity_seeded: bool,
    summary_revision_is_stale: bool,
    summary_stale: bool,
    workspace_is_newer: bool,
    allowed_operation_level: str,
    rolling_summary_handoff: dict,
) -> dict:
    safe_rolling_summary_handoff = {
        "active_task_digest": rolling_summary_handoff.get("active_task_digest"),
        "blocked_digest": rolling_summary_handoff.get("blocked_digest"),
        "latest_daily_log_digest_available": bool(
            rolling_summary_handoff.get("latest_relevant_log_digest")
        ),
        "latest_relevant_log_digest_redacted": bool(
            rolling_summary_handoff.get("latest_relevant_log_digest")
        ),
        "suggested_handoff_sections": rolling_summary_handoff.get("suggested_handoff_sections", []),
    }
    target_path = summary_path.relative_to(workspace.project_root).as_posix()
    summary_text = read_text(summary_path) if summary_path.is_file() else ""
    body_digest_before = managed_body_digest(summary_text) if summary_text else None
    latest_daily_log_path = (
        latest_daily_log.relative_to(workspace.project_root).as_posix()
        if latest_daily_log is not None
        else None
    )
    read_set = [target_path]
    if latest_daily_log_path is not None:
        read_set.append(latest_daily_log_path)

    daily_state = state.get("daily_logs")
    latest_file_from_state = daily_state.get("latest_file") if isinstance(daily_state, dict) else None
    latest_daily_log_storage_path = (
        latest_daily_log.relative_to(workspace.storage_root).as_posix()
        if latest_daily_log is not None
        else None
    )
    cursor_matches_latest_log = (
        isinstance(daily_state, dict)
        and latest_daily_log_entry is not None
        and latest_file_from_state == latest_daily_log_storage_path
        and daily_state.get("latest_entry_id") == latest_daily_log_entry.entry_id
        and daily_state.get("latest_entry_seq") == latest_daily_log_entry.entry_seq
        and daily_state.get("entry_count") == latest_daily_log_entry_count
    )
    workspace_revision = state["workspace_revision"]
    summary_base_workspace_revision = summary_state.base_workspace_revision if summary_state else None
    single_revision_append_delta = (
        isinstance(summary_base_workspace_revision, int)
        and workspace_revision == summary_base_workspace_revision + 1
    )
    provenance = state.get("provenance")
    review_imported_baseline_plus_append_delta = (
        isinstance(summary_base_workspace_revision, int)
        and workspace_revision == summary_base_workspace_revision + 2
        and isinstance(provenance, dict)
        and provenance.get("state_label") == "helper_evidenced"
        and provenance.get("previous_state_label") == "review_imported_baseline"
        and provenance.get("receipt_backed") is True
    )
    single_append_delta = (
        single_revision_append_delta or review_imported_baseline_plus_append_delta
    )
    non_summary_writes_after_summary_base: list[str] = []
    files_state = state.get("files")
    if isinstance(files_state, dict) and isinstance(summary_base_workspace_revision, int):
        for file_key, file_state in sorted(files_state.items()):
            if file_key == "rolling_summary" or not isinstance(file_state, dict):
                continue
            base_revision = file_state.get("base_workspace_revision")
            if isinstance(base_revision, int) and base_revision > summary_base_workspace_revision:
                non_summary_writes_after_summary_base.append(file_key)
    latest_daily_log_newer_than_summary = (
        latest_daily_log is not None
        and latest_daily_log.stat().st_mtime > summary_path.stat().st_mtime
    )
    latest_daily_log_not_older_than_summary = (
        latest_daily_log is not None
        and latest_daily_log.stat().st_mtime >= summary_path.stat().st_mtime
    )

    reason_code = None
    if not summary_stale or not workspace_is_newer:
        reason_code = "summary_not_stale"
    elif not summary_revision_is_stale:
        reason_code = "summary_revision_not_stale"
    elif not isinstance(summary_base_workspace_revision, int):
        reason_code = "missing_summary_base_workspace_revision"
    elif non_summary_writes_after_summary_base:
        reason_code = "stale_cause_not_append_only"
    elif not single_append_delta:
        reason_code = "stale_not_single_append_delta"
    elif not continuity_seeded:
        reason_code = "continuity_not_seeded"
    elif latest_daily_log is None:
        reason_code = "missing_latest_daily_log"
    elif latest_daily_log_entry is None:
        reason_code = "missing_latest_daily_log_entry"
    elif not isinstance(daily_state, dict):
        reason_code = "invalid_daily_log_cursor"
    elif not cursor_matches_latest_log:
        reason_code = "daily_log_cursor_mismatch"
    elif not latest_daily_log_not_older_than_summary:
        reason_code = "stale_cause_not_append_only"

    latest_entry_created_at = latest_daily_log_entry.created_at if latest_daily_log_entry else None
    latest_daily_log_entry_hash = (
        latest_daily_log_entry_text_digest(
            read_text(latest_daily_log) if latest_daily_log is not None else "",
            latest_daily_log_entry,
        )
        if latest_daily_log_entry is not None
        else None
    )
    append_cursor = {
        "latest_file": latest_file_from_state if isinstance(daily_state, dict) else None,
        "latest_entry_id": latest_daily_log_entry.entry_id if latest_daily_log_entry else None,
        "latest_entry_seq": latest_daily_log_entry.entry_seq if latest_daily_log_entry else None,
        "latest_entry_created_at": latest_entry_created_at,
        "latest_entry_date": latest_entry_created_at[:10] if latest_entry_created_at else None,
        "latest_entry_hash": latest_daily_log_entry_hash,
        "entry_count": latest_daily_log_entry_count if latest_daily_log is not None else None,
        "latest_file_digest": latest_daily_log_digest,
    }
    assertion_binding_seed = (
        post_append_assertion_binding_seed(
            expected_workspace_revision=workspace_revision,
            expected_file_revision=summary_state.revision,
            summary_base_workspace_revision=summary_base_workspace_revision,
            latest_daily_log_entry=latest_daily_log_entry,
            latest_daily_log_digest=latest_daily_log_digest,
            latest_daily_log_entry_hash=latest_daily_log_entry_hash,
            body_digest_before=body_digest_before,
        )
        if summary_state is not None and body_digest_before is not None
        else None
    )

    contract = {
        "contract_type": "post_append_summary_sync",
        "allowed": reason_code is None,
        "requires_repair_command_first": True,
        "write_type": "current-state",
        "file_key": "rolling_summary",
        "input_format": "json",
        "target_path": target_path,
        "expected_file_revision": summary_state.revision if summary_state else None,
        "expected_workspace_revision": workspace_revision,
        "append_cursor": append_cursor,
        "managed_body_digest_before": body_digest_before,
        "metadata_only_refresh": {
            "allowed_assertion_sources": [
                "record_plan_output_id",
                "explicit_operator_confirmation",
            ],
            "requires_semantic_unchanged_assertion": True,
            "assertion_binding_seed": assertion_binding_seed,
            "assertion_binding_seed_digest": (
                "sha256:"
                + hashlib.sha256(
                    json.dumps(
                        assertion_binding_seed,
                        sort_keys=True,
                        separators=(",", ":"),
                        ensure_ascii=False,
                    ).encode("utf-8")
                ).hexdigest()
                if assertion_binding_seed is not None
                else None
            ),
        },
        "provenance_guard": {
            "summary_base_workspace_revision": summary_base_workspace_revision,
            "workspace_revision": workspace_revision,
            "expected_workspace_revision_delta": (
                2 if review_imported_baseline_plus_append_delta else 1
            ),
            "single_revision_append_delta": single_revision_append_delta,
            "review_imported_baseline_plus_append_delta": (
                review_imported_baseline_plus_append_delta
            ),
            "single_append_delta": single_append_delta,
            "cursor_matches_latest_log": cursor_matches_latest_log,
            "non_summary_writes_after_summary_base": non_summary_writes_after_summary_base,
            "latest_daily_log_newer_than_summary": latest_daily_log_newer_than_summary,
            "latest_daily_log_not_older_than_summary": latest_daily_log_not_older_than_summary,
        },
        "rolling_summary_handoff": safe_rolling_summary_handoff,
        "read_set": read_set,
        "ordinary_write_gate_preserved": True,
        "ordinary_write_gate": {
            "allowed_operation_level": allowed_operation_level,
            "summary_stale": summary_stale,
            "gate_condition": (
                "recallloom.py write requires allowed_operation_level="
                "write_current_state_after_preflight and summary_stale=false"
            ),
            "contract_does_not_authorize_recallloom_write": True,
        },
    }
    if reason_code is not None:
        contract["reason_code"] = reason_code
    return contract


def evaluate_preflight(
    *,
    workspace: WorkspaceInfo,
    full: bool,
    startup_residue_report: dict | None = None,
) -> PreflightEvaluation:
    """Evaluate preflight/readiness over a consistent snapshot of ``workspace``.

    Pure: reads the workspace, computes the exact legacy preflight payload, and
    returns it with the flags the CLI adapter needs for human output. Raises
    ``PreflightSnapshotError`` for malformed managed files and lets
    ``DailyLogCursorError`` / ``ConfigContractError`` / ``OSError`` /
    ``UnicodeDecodeError`` propagate for the adapter's legacy failure projection.
    """
    summary_path = workspace.storage_root / FILE_KEYS["rolling_summary"]
    context_brief_path = workspace.storage_root / FILE_KEYS["context_brief"]
    state_path = workspace.storage_root / FILE_KEYS["state"]
    update_protocol_path = workspace.storage_root / FILE_KEYS["update_protocol"]
    logs_dir = workspace.storage_root / DAILY_LOGS_DIRNAME
    if not summary_path.is_file():
        raise PreflightSnapshotError(f"Missing required file: {summary_path}")

    invalid_daily_logs = invalid_iso_like_daily_log_files(logs_dir)
    if invalid_daily_logs:
        raise PreflightSnapshotError(
            "Refusing preflight because one or more daily log filenames match the date pattern but are invalid ISO dates:\n"
            + "\n".join(str(path) for path in invalid_daily_logs)
        )

    directory_latest_daily_log = latest_active_daily_log(logs_dir)
    state = load_workspace_state(state_path)
    state_latest_daily_log_cursor = validate_state_entry_bearing_latest_daily_log(
        storage_root=workspace.storage_root,
        state=state,
    )
    latest_daily_log = (
        state_latest_daily_log_cursor.latest_path
        if state_latest_daily_log_cursor is not None
        else directory_latest_daily_log
    )
    daily_log_selection_rule = (
        "state_entry_bearing_latest_daily_log"
        if state_latest_daily_log_cursor is not None
        else "latest_active_daily_log"
    )
    summary_state = parse_file_state_marker(read_text(summary_path))
    if summary_state is None:
        raise PreflightSnapshotError(
            f"Missing required file-state metadata marker: {summary_path}"
        )
    context_brief_state = None
    if context_brief_path.is_file():
        context_brief_state = file_state_marker_from_path(context_brief_path)
        if context_brief_state is None:
            raise PreflightSnapshotError(
                f"Missing required file-state metadata marker: {context_brief_path}"
            )
    update_protocol_state = None
    if update_protocol_path.is_file():
        update_protocol_state = file_state_marker_from_path(update_protocol_path)
        if update_protocol_state is None:
            raise PreflightSnapshotError(
                f"Missing required file-state metadata marker: {update_protocol_path}"
            )

    latest_daily_log_entry = None
    latest_daily_log_entry_count = 0
    latest_daily_log_has_entries = False
    if directory_latest_daily_log is not None:
        latest_active_daily_log_cursor(workspace.storage_root)
    if latest_daily_log is not None:
        (
            latest_daily_log_entry,
            latest_daily_log_entry_count,
            latest_daily_log_is_scaffold,
        ) = latest_daily_log_marker_summary(latest_daily_log)
        if latest_daily_log_entry is None and not latest_daily_log_is_scaffold:
            raise PreflightSnapshotError(
                "Missing required daily-log-entry metadata marker in the latest ISO-dated daily log: "
                f"{latest_daily_log}"
            )
        latest_daily_log_has_entries = latest_daily_log_entry_count > 0

    workspace_artifact_scan_mode = "full" if full else "quick"
    summary_text = read_text(summary_path)
    latest_daily_log_full_text = read_text(latest_daily_log) if latest_daily_log is not None else ""
    latest_daily_log_digest = (
        sha256_text_digest(latest_daily_log_full_text)
        if latest_daily_log is not None
        else None
    )
    latest_daily_log_text = latest_daily_log_full_text if full else ""
    freshness = evaluate_continuity_freshness(
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
        summary_path=summary_path,
        workspace_revision=state["workspace_revision"],
        summary_base_workspace_revision=summary_state.base_workspace_revision,
        latest_daily_log_exists=latest_daily_log_has_entries,
        scan_mode=workspace_artifact_scan_mode,
        state=state,
    )
    digests = continuity_digest_bundle(
        summary_text=summary_text,
        latest_daily_log_text=latest_daily_log_text,
        project_root=workspace.project_root,
    )
    continuity_state, continuity_seeded = continuity_state_for_workspace(
        state=state,
        summary_text=summary_text,
        latest_daily_log_exists=latest_daily_log_has_entries,
    )
    if continuity_state == "initialized_empty_shell":
        digests = {
            "active_task_digest": None,
            "blocked_digest": None,
            "latest_relevant_log_digest": None,
            "suggested_handoff_sections": [],
        }

    latest_active_day = (
        date.fromisoformat(latest_daily_log.stem) if latest_daily_log is not None else None
    )
    closure_detected, closure_keywords = (
        detect_closure_signal(latest_daily_log_text)
        if full
        else (False, [])
    )
    project_time_policy_cues = (
        detect_update_protocol_time_policy_cues(read_text(update_protocol_path))
        if full and update_protocol_path.is_file()
        else []
    )
    next_step_text = extract_section_text(summary_text, "next_step")
    next_step_empty = is_effectively_empty_summary_next_step(next_step_text)
    workday_decision = build_workday_decision(
        now=datetime.now().astimezone(),
        rollover_hour=DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
        latest_active_day=latest_active_day,
        closure_detected=closure_detected,
        summary_next_step_is_empty=next_step_empty,
        preferred_date=None,
        session_intent=None,
        project_time_policy_cues=project_time_policy_cues,
        host_explicit=False,
    )

    latest_workspace_artifact = freshness["latest_workspace_artifact"]
    workspace_artifact_scan_performed = freshness["workspace_artifact_scan_performed"]
    workspace_artifact_is_newer = freshness["workspace_artifact_newer_than_summary"]
    summary_revision_is_stale = freshness["summary_revision_stale"]
    workspace_is_newer = freshness["workspace_newer_than_summary"]
    summary_stale = freshness["summary_stale"]
    continuity_confidence = freshness["continuity_confidence"]
    freshness_risk = freshness_risk_summary(
        workspace_artifact_scan_mode=freshness["workspace_artifact_scan_mode"],
        workspace_artifact_scan_performed=freshness["workspace_artifact_scan_performed"],
        workspace_artifact_newer_than_summary=freshness["workspace_artifact_newer_than_summary"],
        summary_revision_stale=freshness["summary_revision_stale"],
        continuity_confidence=continuity_confidence,
    )
    recommended_actions = recommended_actions_for_preflight(
        continuity_confidence=continuity_confidence,
        continuity_state=continuity_state,
        update_protocol_exists=update_protocol_path.is_file(),
        context_brief_exists=context_brief_path.is_file(),
        latest_daily_log_exists=latest_daily_log_has_entries,
        workspace_is_newer=workspace_is_newer,
    )
    provenance_facts = provenance_facts_from_state(state, review_intent=True)
    trust_state = evaluate_trust_state(
        continuity_confidence=continuity_confidence,
        continuity_state=continuity_state,
        summary_stale=summary_stale,
        workspace_newer_than_summary=workspace_is_newer,
        conflict_state=None,
        legacy_sidecar=provenance_facts["legacy_sidecar"],
        legacy_review_required=provenance_facts["review_required"],
        review_imported_baseline=provenance_facts["review_imported_baseline"],
        helper_evidenced=provenance_facts["helper_evidenced"],
        inconsistent_evidence=provenance_facts["inconsistent_evidence"],
    )
    expected_revisions = expected_revisions_payload(
        workspace_revision=state["workspace_revision"],
        rolling_summary_revision=summary_state.revision if summary_state else None,
        context_brief_revision=context_brief_state.revision if context_brief_state else None,
        update_protocol_revision=(
            update_protocol_state.revision if update_protocol_state else None
        ),
    )
    strict_gate = strict_sidecar_integrity_gate(
        project_root=workspace.project_root,
        storage_root=workspace.storage_root,
    )
    strict_gate_summary = strict_sidecar_integrity_gate_public_summary(strict_gate)
    strict_gate_allows_write = strict_gate.get("allowed_for_mutation") is True
    strict_gate_receipts_verified = strict_gate_current_receipts_verified(strict_gate)
    provenance_write_context_blocked_by_state = trust_state["provenance_state"] in {
        "review_required",
        "structurally_valid_legacy",
        "inconsistent_or_tampered_evidence",
    }
    provenance_write_context_blocked = (
        provenance_write_context_blocked_by_state or not strict_gate_allows_write
    )
    effective_allowed_operation_level = trust_state["allowed_operation_level"]
    if (
        not strict_gate_allows_write
        and effective_allowed_operation_level == "write_current_state_after_preflight"
    ):
        effective_allowed_operation_level = "read_current_state"
    if provenance_write_context_blocked_by_state:
        write_context_blocked_reason = "provenance_review_required"
    elif not strict_gate_allows_write:
        write_context_blocked_reason = "strict_sidecar_integrity_failed"
    else:
        write_context_blocked_reason = None
    recommended_actions = strict_gate_preflight_actions(
        recommended_actions,
        strict_gate_allows_write=strict_gate_allows_write,
    )
    write_expected_revisions = None if provenance_write_context_blocked else expected_revisions
    provenance = build_provenance_report(
        sidecar_trust_state=trust_state["sidecar_trust_state"],
        continuity_state=continuity_state,
        allowed_operation_level=effective_allowed_operation_level,
        summary_stale=summary_stale,
        expected_revisions=write_expected_revisions,
        receipt_chain_verified=strict_gate_receipts_verified,
        receipt_store_available=strict_gate_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"],
        unproven_sidecar_state=provenance_facts["unproven_sidecar_state"],
        metadata_status=provenance_facts["metadata_status"],
    )

    append_date_review_required = workday_decision["recommendation_type"] == "review_date_before_append"
    recommended_write_targets = [summary_path.relative_to(workspace.project_root).as_posix()]
    suggested_read_set = [summary_path.relative_to(workspace.project_root).as_posix()]
    conditional_review_targets = []
    if latest_daily_log is not None:
        suggested_read_set.append(latest_daily_log.relative_to(workspace.project_root).as_posix())
        conditional_review_targets.append(
            {
                "path": latest_daily_log.relative_to(workspace.project_root).as_posix(),
                "reason": (
                    "Review only if this session creates a new milestone entry or end-of-day log. "
                    "Do not treat an existing daily log as a default current-state write target."
                ),
            }
        )
    if context_brief_path.is_file():
        suggested_read_set.append(context_brief_path.relative_to(workspace.project_root).as_posix())
        conditional_review_targets.append(
            {
                "path": context_brief_path.relative_to(workspace.project_root).as_posix(),
                "reason": (
                    "Review if mission, audience, scope, source of truth, workflow, "
                    "boundaries, or current phase changed."
                ),
            }
        )
    override_review_targets = []
    if update_protocol_path.is_file():
        suggested_read_set.append(update_protocol_path.relative_to(workspace.project_root).as_posix())
        override_review_targets.append(
            {
                "path": update_protocol_path.relative_to(workspace.project_root).as_posix(),
                "reason": (
                    "Review project-local continuity rules before applying default cold-start, "
                    "write-target, or archive guidance. v1 helpers do not parse natural-language "
                    "override prose automatically."
                ),
            }
        )

    logical_workday_seen = workday_decision["logical_workday"]
    project_time_policy_review_required = bool(
        project_time_policy_cues
        and (latest_active_day is None or latest_active_day.isoformat() != logical_workday_seen)
    )
    append_daily_log_entry_suggested_date = (
        None
        if append_date_review_required
        else workday_decision["suggested_date"]
    )
    public_project_root = public_project_root_label(workspace.project_root)
    public_storage_root = public_project_path(workspace.storage_root, project_root=workspace.project_root)
    public_latest_daily_log = (
        public_project_path(latest_daily_log, project_root=workspace.project_root)
        if latest_daily_log is not None
        else None
    )
    public_latest_workspace_artifact = (
        public_project_path(latest_workspace_artifact, project_root=workspace.project_root)
        if latest_workspace_artifact is not None
        else None
    )
    payload = {
        "project_root": public_project_root,
        "storage_root": public_storage_root,
        "storage_mode": workspace.storage_mode,
        "workspace_language": workspace.workspace_language,
        "context_brief": (
            public_project_path(context_brief_path, project_root=workspace.project_root)
            if context_brief_path.is_file()
            else None
        ),
        "state": public_project_path(state_path, project_root=workspace.project_root),
        "update_protocol": (
            public_project_path(update_protocol_path, project_root=workspace.project_root)
            if update_protocol_path.is_file()
            else None
        ),
        "workspace_revision": state["workspace_revision"],
        "update_protocol_revision": state["update_protocol_revision"],
        "rolling_summary": public_project_path(summary_path, project_root=workspace.project_root),
        "rolling_summary_revision": summary_state.revision if summary_state else None,
        "context_brief_revision": context_brief_state.revision if context_brief_state else None,
        "update_protocol_file_revision": update_protocol_state.revision if update_protocol_state else None,
        "latest_daily_log": public_latest_daily_log,
        "latest_daily_log_entry_id": latest_daily_log_entry.entry_id if latest_daily_log_entry else None,
        "latest_daily_log_entry_seq": latest_daily_log_entry.entry_seq if latest_daily_log_entry else None,
        "latest_daily_log_entry_count": latest_daily_log_entry_count,
        "daily_log_selection_rule": daily_log_selection_rule,
        "workspace_artifact_scan_mode": workspace_artifact_scan_mode,
        "workspace_artifact_scan_performed": workspace_artifact_scan_performed,
        "latest_workspace_artifact": public_latest_workspace_artifact,
        "workspace_artifact_newer_than_summary": workspace_artifact_is_newer,
        "summary_revision_stale": summary_revision_is_stale,
        "summary_stale": summary_stale,
        "workspace_newer_than_summary": workspace_is_newer,
        "continuity_confidence": continuity_confidence,
        "sidecar_trust_state": trust_state["sidecar_trust_state"],
        "provenance_state": provenance["state_label"],
        "provenance_metadata_status": provenance["metadata_status"],
        "provenance_contract": provenance["contract_identity"],
        "preflight_contract_identity": provenance_contract_identity(),
        "expected_revisions": write_expected_revisions,
        "write_context_authorized": not provenance_write_context_blocked,
        "write_context_blocked_reason": write_context_blocked_reason,
        "write_readiness": provenance["write_readiness"],
        "allowed_operation_level": effective_allowed_operation_level,
        "strict_sidecar_integrity_gate": strict_gate_summary,
        "continuity_drift_risk_level": trust_state["continuity_drift_risk_level"],
        "freshness_risk_level": freshness_risk["level"],
        "freshness_risk_note": freshness_risk["note"],
        "continuity_state": continuity_state,
        "continuity_seeded": continuity_seeded,
        "active_task_digest": digests["active_task_digest"],
        "blocked_digest": digests["blocked_digest"],
        "latest_relevant_log_digest": digests["latest_relevant_log_digest"],
        "suggested_handoff_sections": digests["suggested_handoff_sections"],
        "recommended_actions": recommended_actions,
        "continuity_snapshot": {
            "project_root": public_project_root,
            "storage_root": public_storage_root,
            "workspace_revision_seen": state["workspace_revision"],
            "rolling_summary_revision_seen": summary_state.revision if summary_state else None,
            "context_brief_revision_seen": context_brief_state.revision if context_brief_state else None,
            "update_protocol_revision_seen": update_protocol_state.revision if update_protocol_state else None,
            "latest_active_daily_log_seen": public_latest_daily_log,
            "latest_active_daily_log_entry_seq_seen": (
                latest_daily_log_entry.entry_seq if latest_daily_log_entry else None
            ),
            "latest_active_daily_log_entry_count_seen": latest_daily_log_entry_count,
            "logical_workday_seen": logical_workday_seen,
            "continuity_confidence": continuity_confidence,
            "continuity_state": continuity_state,
            "continuity_seeded": continuity_seeded,
            "task_type": "preflight_review",
        },
        "suggested_read_set": suggested_read_set,
        "recommended_write_targets": [] if provenance_write_context_blocked else recommended_write_targets,
        "conditional_review_targets": conditional_review_targets,
        "override_review_targets": override_review_targets,
        "write_tier_judgment": build_write_tier_judgment(
            project_root=workspace.project_root,
            storage_root=workspace.storage_root,
        ),
        "safe_write_context": None if provenance_write_context_blocked else {
            "workspace_revision": state["workspace_revision"],
            "rolling_summary_handoff": {
                "active_task_digest": digests["active_task_digest"],
                "blocked_digest": digests["blocked_digest"],
                "latest_relevant_log_digest": digests["latest_relevant_log_digest"],
                "suggested_handoff_sections": digests["suggested_handoff_sections"],
            },
            "commit_context_file": {
                "rolling_summary": {
                    "path": summary_path.relative_to(workspace.project_root).as_posix(),
                    "expected_file_revision": summary_state.revision if summary_state else None,
                    "expected_workspace_revision": state["workspace_revision"],
                },
                "context_brief": {
                    "path": context_brief_path.relative_to(workspace.project_root).as_posix(),
                    "expected_file_revision": context_brief_state.revision if context_brief_state else None,
                    "expected_workspace_revision": state["workspace_revision"],
                }
                if context_brief_path.is_file()
                else None,
                "update_protocol": {
                    "path": update_protocol_path.relative_to(workspace.project_root).as_posix(),
                    "expected_file_revision": update_protocol_state.revision if update_protocol_state else None,
                    "expected_workspace_revision": state["workspace_revision"],
                }
                if update_protocol_path.is_file()
                else None,
            },
            "append_daily_log_entry": {
                "latest_file": (
                    None
                    if append_date_review_required
                    else (
                        latest_daily_log.relative_to(workspace.storage_root).as_posix()
                        if latest_daily_log is not None
                        else None
                    )
                ),
                "latest_entry_id": latest_daily_log_entry.entry_id if latest_daily_log_entry else None,
                "latest_entry_seq": latest_daily_log_entry.entry_seq if latest_daily_log_entry else None,
                "entry_count": latest_daily_log_entry_count if latest_daily_log is not None else None,
                "latest_file_digest": None if append_date_review_required else latest_daily_log_digest,
                "logical_workday": None if append_date_review_required else logical_workday_seen,
                "suggested_date": append_daily_log_entry_suggested_date,
                "recommendation_type": workday_decision["recommendation_type"],
                "workday_state": workday_decision["workday_state"],
                "heuristic_suggested_date": (
                    None if append_date_review_required else workday_decision["heuristic_suggested_date"]
                ),
                "date_resolution_source": workday_decision["date_resolution_source"],
                "requires_user_confirmation": workday_decision["requires_user_confirmation"],
                "user_visible_prompt_level": workday_decision["user_visible_prompt_level"],
                "project_time_policy_cues": project_time_policy_cues,
                "project_time_policy_review_required": project_time_policy_review_required,
                "closure_detected": closure_detected,
                "closure_keywords": closure_keywords,
                "summary_next_step_empty": next_step_empty,
                "reasoning": workday_decision["reasoning"],
                "expected_workspace_revision": state["workspace_revision"],
            },
        },
    }
    if startup_residue_report is not None:
        payload["startup_residue_report"] = startup_residue_report

    safe_write_context = payload.get("safe_write_context")
    if isinstance(safe_write_context, dict):
        rolling_summary_handoff = safe_write_context["rolling_summary_handoff"]
        safe_write_context["post_append_summary_sync"] = build_post_append_summary_sync_contract(
            workspace=workspace,
            state=state,
            summary_path=summary_path,
            summary_state=summary_state,
            latest_daily_log=latest_daily_log,
            latest_daily_log_entry=latest_daily_log_entry,
            latest_daily_log_entry_count=latest_daily_log_entry_count,
            latest_daily_log_digest=latest_daily_log_digest,
            continuity_seeded=continuity_seeded,
            summary_revision_is_stale=summary_revision_is_stale,
            summary_stale=summary_stale,
            workspace_is_newer=workspace_is_newer,
            allowed_operation_level=effective_allowed_operation_level,
            rolling_summary_handoff=rolling_summary_handoff,
        )

    user_summary = preflight_user_summary(payload)
    payload["user_visible_category"] = user_summary["category"]
    payload["user_summary"] = user_summary

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