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

View on GitHub
#!/usr/bin/env python3
"""Summarize current continuity status, confidence, and workday recommendation."""

from __future__ import annotations

import argparse
import json
import os
import sys
from datetime import datetime
from pathlib import Path


_BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION = "3.10"


def _bootstrap_failure_language() -> str:
    lang = os.environ.get("LC_ALL") or os.environ.get("LC_MESSAGES") or os.environ.get("LANG") or ""
    return "zh-CN" if lang.lower().startswith("zh") else "en"


def _bootstrap_minimum_python_version() -> tuple[tuple[int, ...], str]:
    fallback_parts = tuple(int(part) for part in _BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION.split("."))
    metadata_path = Path(__file__).resolve().parent.parent / "package-metadata.json"
    try:
        payload = json.loads(metadata_path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
        raw = _BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION
    else:
        raw = payload.get("minimum_python_version", _BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION)
        if not isinstance(raw, str) or not raw.strip():
            raw = _BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION
    parts = raw.strip().split(".")
    if not parts or any(not part.isdigit() for part in parts):
        return fallback_parts, _BOOTSTRAP_DEFAULT_MINIMUM_PYTHON_VERSION
    normalized = tuple(int(part) for part in parts)
    return normalized, ".".join(str(part) for part in normalized)


def _bootstrap_runtime_contract(minimum_text: str) -> dict:
    return {
        "blocked": True,
        "blocked_reason": "python_runtime_unavailable",
        "recoverability": "retryable",
        "surface_level": "user_safe",
        "trust_effect": "none",
        "next_actions": ["find_compatible_python", "report_blocked_runtime"],
        "user_message": {
            "en": (
                "RecallLoom cannot start yet because this environment does not provide "
                f"Python {minimum_text} or newer."
            ),
            "zh-CN": f"当前环境还不能启动 RecallLoom,因为这里没有可用的 Python {minimum_text}+ 运行时。",
        },
        "operator_note": {
            "en": f"Find or point the host at a compatible Python {minimum_text}+ interpreter before retrying.",
            "zh-CN": f"请先找到或指定兼容的 Python {minimum_text}+ 解释器,再重试。",
        },
    }


def _bootstrap_runtime_payload(message: str, minimum_text: str) -> dict:
    language = _bootstrap_failure_language()
    contract = _bootstrap_runtime_contract(minimum_text)
    script_name = Path(__file__).name
    recovery_command = {
        "en": f"Use a Python {minimum_text}+ interpreter to run {script_name} --json",
        "zh-CN": f"请使用 Python {minimum_text}+ 解释器运行 {script_name} --json",
    }
    suggestion = {
        "en": (
            "Repair the RecallLoom bootstrap/runtime files or switch to a compatible Python "
            f"{minimum_text}+ interpreter before retrying."
        ),
        "zh-CN": f"请先修复 RecallLoom 的 bootstrap/runtime 文件,或切换到兼容的 Python {minimum_text}+ 解释器后再重试。",
    }
    return {
        "ok": False,
        "schema_version": "1.1",
        "blocked": contract["blocked"],
        "blocked_reason": contract["blocked_reason"],
        "recoverability": contract["recoverability"],
        "surface_level": contract["surface_level"],
        "trust_effect": contract["trust_effect"],
        "failure_stage": "runtime_bootstrap",
        "next_actions": list(contract["next_actions"]),
        "user_message": contract["user_message"][language],
        "suggestion": suggestion[language],
        "recovery_command": recovery_command[language],
        "operator_note": contract["operator_note"][language],
        "error": message,
    }


def _exit_if_runtime_unsupported() -> None:
    minimum_parts, minimum_text = _bootstrap_minimum_python_version()
    current = sys.version_info[: len(minimum_parts)]
    if current >= minimum_parts:
        return
    message = (
        "RecallLoom helper scripts require "
        f"Python {minimum_text}+; current interpreter is "
        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
    )
    if "--json" in sys.argv[1:]:
        print(json.dumps(_bootstrap_runtime_payload(message, minimum_text), ensure_ascii=False, indent=2))
    else:
        print(message, file=sys.stderr)
    raise SystemExit(2)


_exit_if_runtime_unsupported()

from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

from core.continuity.freshness import (
    continuity_digest_bundle,
    continuity_state_for_workspace as shared_continuity_state_for_workspace,
    evaluate_continuity_freshness,
    freshness_risk_summary,
    summary_matches_empty_shell_template as shared_summary_matches_empty_shell_template,
)
from core.continuity.workday import (
    DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
    RECOMMENDATION_TYPES,
    build_workday_decision,
    describe_workday_guidance,
    detect_closure_signal,
)
from core.failure.contracts import canonical_detail_reason_contract
from core.output.user_status import print_user_summary, read_surface_user_summary
from core.trust.state import evaluate_trust_state
from core.provenance.evidence import (
    strict_gate_current_receipts_verified,
    strict_sidecar_no_write_failure_extra,
    strict_sidecar_integrity_gate,
    strict_sidecar_integrity_gate_public_summary,
)
from core.provenance.state import (
    build_provenance_report,
    expected_revisions_payload,
    provenance_facts_from_state,
    provenance_contract_identity,
)
from core.provenance.inconsistent_review import (
    INCONSISTENT_REVIEW_EVIDENCE_KEY,
    evaluate_current_inconsistent_review_orphan,
)
from core.protocol.contracts import FILE_KEYS
from core.protocol.markers import parse_file_state_marker
from core.protocol.sections import extract_section_text

from _common import (
    ConfigContractError,
    DailyLogCursorError,
    cli_failure_payload,
    cli_failure_payload_for_exception,
    detect_update_protocol_time_policy_cues,
    EnvironmentContractError,
    enforce_package_support_gate,
    ensure_supported_python_version,
    exit_with_cli_error,
    find_recallloom_root,
    load_workspace_state,
    parse_daily_log_entry_line,
    parse_iso_date,
    public_project_path,
    public_project_root_label,
    read_text,
    StorageResolutionError,
    validate_state_entry_bearing_latest_daily_log,
)


def summary_matches_empty_shell_template(summary_text: str) -> bool:
    return shared_summary_matches_empty_shell_template(summary_text)


def continuity_state_for_workspace(
    *,
    state: dict,
    summary_text: str,
    latest_daily_log_exists: bool,
) -> tuple[str, bool]:
    return shared_continuity_state_for_workspace(
        state=state,
        summary_text=summary_text,
        latest_daily_log_exists=latest_daily_log_exists,
    )


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Summarize continuity confidence, recommended actions, and workday guidance."
    )
    parser.add_argument("path", nargs="?", default=".", help="Project path or a descendant path.")
    parser.add_argument(
        "--timezone",
        help="Optional IANA timezone such as Asia/Shanghai. Defaults to the host local timezone.",
    )
    parser.add_argument(
        "--now",
        help=(
            "Current time in ISO 8601 format. If omitted, the helper uses the host's current local time. "
            "If the value is naive, it is interpreted in --timezone or the host local timezone."
        ),
    )
    parser.add_argument(
        "--rollover-hour",
        type=int,
        default=DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR,
        help="Logical day rollover hour in 24-hour form. Defaults to 3.",
    )
    parser.add_argument(
        "--preferred-date",
        help="Optional explicit append target date in YYYY-MM-DD form for workday guidance.",
    )
    parser.add_argument(
        "--session-intent",
        choices=sorted(RECOMMENDATION_TYPES),
        help="Optional explicit session-intent hint using one of the recommendation types.",
    )
    parser.add_argument(
        "--expanded",
        action="store_true",
        help=(
            "Opt into reading context_brief.md, update_protocol.md, and latest daily-log "
            "content. Defaults to the bounded fast lane from state.json and rolling_summary.md."
        ),
    )
    parser.add_argument("--json", action="store_true", help="Print structured JSON output.")
    return parser


def resolve_now(now_raw: str | None, timezone_name: str | None) -> tuple[datetime, str]:
    tzinfo = None
    if timezone_name:
        try:
            tzinfo = ZoneInfo(timezone_name)
        except ZoneInfoNotFoundError as exc:
            raise ValueError(f"Unknown timezone: {timezone_name}") from exc

    if now_raw:
        try:
            now = datetime.fromisoformat(now_raw)
        except ValueError as exc:
            raise ValueError(f"Invalid --now value: {now_raw}") from exc
        if now.tzinfo is None:
            if tzinfo is None:
                tzinfo = datetime.now().astimezone().tzinfo
            now = now.replace(tzinfo=tzinfo)
        elif tzinfo is not None:
            now = now.astimezone(tzinfo)
    else:
        now = datetime.now().astimezone()
        if tzinfo is not None:
            now = now.astimezone(tzinfo)

    zone_label = timezone_name or str(now.tzinfo)
    return now, zone_label


def latest_daily_log_entry_info(latest_daily_log: Path | None):
    if latest_daily_log is None:
        return None
    return latest_daily_log_entry_info_from_text(read_text(latest_daily_log))


def latest_daily_log_entry_info_from_text(text: str):
    latest_entry = None
    for line in text.splitlines():
        entry = parse_daily_log_entry_line(line)
        if entry is not None:
            latest_entry = entry
    return latest_entry


def recommended_actions_for_status(
    *,
    continuity_confidence: str,
    continuity_state: str,
    update_protocol_exists: bool,
    context_brief_exists: bool,
    latest_daily_log_exists: bool,
    summary_stale: bool,
) -> list[str]:
    actions: list[str] = []
    if continuity_state == "initialized_empty_shell":
        actions.append("seed_initial_continuity")
    elif summary_stale:
        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_status_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_status_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 _project_relative_path(path: Path, project_root: Path) -> str:
    return path.relative_to(project_root).as_posix()


def _append_unique(items: list[str], value: str | None) -> None:
    if value and value not in items:
        items.append(value)


def _state_file_revision(state: dict, file_key: str) -> int | None:
    files = state.get("files")
    file_state = files.get(file_key) if isinstance(files, dict) else None
    revision = file_state.get("file_revision") if isinstance(file_state, dict) else None
    return revision if isinstance(revision, int) and not isinstance(revision, bool) else None


def _state_latest_entry_seq(state: dict) -> int | None:
    daily_logs = state.get("daily_logs")
    entry_seq = daily_logs.get("latest_entry_seq") if isinstance(daily_logs, dict) else None
    return entry_seq if isinstance(entry_seq, int) and not isinstance(entry_seq, bool) else None


def _state_latest_daily_log_path(state: dict, storage_root: Path) -> Path | None:
    daily_logs = state.get("daily_logs")
    if not isinstance(daily_logs, dict):
        return None
    entry_count = daily_logs.get("entry_count")
    latest_file = daily_logs.get("latest_file")
    if not isinstance(entry_count, int) or isinstance(entry_count, bool) or entry_count <= 0:
        return None
    if not isinstance(latest_file, str) or not latest_file:
        return None
    return storage_root / latest_file


def _estimated_tokens_for_files(files: list[str], text_by_path: dict[str, str]) -> int:
    total = 0
    for rel_path in files:
        text = text_by_path.get(rel_path, "")
        total += max(64, (len(text) + 3) // 4) if text else 64
    return total


def _read_plan_reason(
    base: str,
    *,
    summary_stale: bool,
    update_protocol_present: bool,
) -> str:
    review_notes: list[str] = []
    if summary_stale:
        review_notes.append("rolling_summary.md is stale against state.json")
    if update_protocol_present:
        review_notes.append("update_protocol.md may narrow project-local constraints")
    if not review_notes:
        return base
    return f"{base} review-before-write: {'; '.join(review_notes)}."


def build_status_read_plan(
    *,
    project_root: Path,
    storage_root: Path,
    state: dict,
    summary_path: Path,
    summary_text: str,
    context_brief_path: Path,
    context_brief_text: str,
    update_protocol_path: Path,
    update_protocol_text: str,
    latest_daily_log: Path | None,
    latest_daily_log_text: str,
    summary_stale: bool,
    continuity_state: str,
    expanded: bool,
) -> dict:
    state_rel = _project_relative_path(storage_root / FILE_KEYS["state"], project_root)
    summary_rel = _project_relative_path(summary_path, project_root)
    context_rel = (
        _project_relative_path(context_brief_path, project_root) if context_brief_path.is_file() else None
    )
    update_protocol_rel = (
        _project_relative_path(update_protocol_path, project_root) if update_protocol_path.is_file() else None
    )
    latest_daily_log_rel = (
        _project_relative_path(latest_daily_log, project_root) if latest_daily_log is not None else None
    )

    text_by_path = {
        state_rel: json.dumps(state, ensure_ascii=False, indent=2) + "\n",
        summary_rel: summary_text,
    }
    if context_rel:
        text_by_path[context_rel] = context_brief_text
    if update_protocol_rel:
        text_by_path[update_protocol_rel] = update_protocol_text
    if latest_daily_log_rel:
        text_by_path[latest_daily_log_rel] = latest_daily_log_text

    optional_expansion_files: list[str] = []
    _append_unique(optional_expansion_files, update_protocol_rel)
    _append_unique(optional_expansion_files, context_rel)
    if continuity_state != "initialized_empty_shell":
        _append_unique(optional_expansion_files, latest_daily_log_rel)

    minimal_files = [summary_rel, state_rel]
    standard_files = list(minimal_files)
    if expanded:
        _append_unique(standard_files, update_protocol_rel)
        _append_unique(standard_files, context_rel)

    comprehensive_files = list(standard_files)
    if expanded and continuity_state != "initialized_empty_shell":
        _append_unique(comprehensive_files, latest_daily_log_rel)

    read_plan = {
        "mode": "expanded" if expanded else "fast",
        "minimal": {
            "files": minimal_files,
            "reason": _read_plan_reason(
                "Smallest bounded continuity set for current-state orientation.",
                summary_stale=summary_stale,
                update_protocol_present=expanded and bool(update_protocol_rel),
            ),
            "estimated_tokens": _estimated_tokens_for_files(minimal_files, text_by_path),
        },
        "standard": {
            "files": standard_files,
            "reason": _read_plan_reason(
                (
                    "Expanded status read that adds stable framing when available."
                    if expanded
                    else "Default fast status read; stable framing is an opt-in expansion."
                ),
                summary_stale=summary_stale,
                update_protocol_present=expanded and bool(update_protocol_rel),
            ),
            "estimated_tokens": _estimated_tokens_for_files(standard_files, text_by_path),
        },
        "comprehensive": {
            "files": comprehensive_files,
            "reason": _read_plan_reason(
                (
                    "Highest-confidence continuity read for evidence-heavy follow-up."
                    if expanded
                    else "Default fast status avoids daily-log content; use --expanded when evidence text is needed."
                ),
                summary_stale=summary_stale,
                update_protocol_present=expanded and bool(update_protocol_rel),
            ),
            "estimated_tokens": _estimated_tokens_for_files(comprehensive_files, text_by_path),
        },
        "optional_expansion": {
            "files": optional_expansion_files,
            "reason": (
                "Available on demand through --expanded. The default fast lane reports paths "
                "without reading context/update-protocol/daily-log bodies."
            ),
            "estimated_tokens": _estimated_tokens_for_files(optional_expansion_files, text_by_path),
        },
        "default_reads_context_brief": expanded and bool(context_rel),
        "default_reads_update_protocol": expanded and bool(update_protocol_rel),
        "default_reads_daily_log_content": expanded and bool(latest_daily_log_rel),
    }
    return read_plan


def main() -> None:
    parser = build_parser()
    args = parser.parse_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)),
        )
    enforce_package_support_gate(parser, json_mode=args.json)
    if not 0 <= args.rollover_hour <= 23:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message="Invalid --rollover-hour value.",
            payload=cli_failure_payload("invalid_prepared_input", error="Invalid --rollover-hour value."),
        )

    preferred_date = None
    if args.preferred_date:
        try:
            preferred_date = parse_iso_date(args.preferred_date)
        except ValueError:
            exit_with_cli_error(
                parser,
                json_mode=args.json,
                exit_code=2,
                message=f"Invalid --preferred-date value: {args.preferred_date}",
                payload=cli_failure_payload(
                    "invalid_date",
                    error=f"Invalid --preferred-date value: {args.preferred_date}",
                    extra={"continuity_confidence": "broken"},
                ),
            )

    try:
        now, zone_label = resolve_now(args.now, args.timezone)
    except ValueError as exc:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=str(exc),
            payload=cli_failure_payload("invalid_prepared_input", error=str(exc)),
        )

    try:
        workspace = find_recallloom_root(args.path)
    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=strict_sidecar_no_write_failure_extra(continuity_confidence="broken"),
            ),
        )
    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.",
                details={"project_root": public_project_root_label(Path(args.path).expanduser().resolve())},
                extra=strict_sidecar_no_write_failure_extra(
                    continuity_confidence="broken",
                    include_recovery_actions=False,
                ),
            ),
        )
    startup_residue_report = None
    inconsistent_review_result = None
    inconsistent_review_target_file_key = None

    try:
        summary_path = workspace.storage_root / FILE_KEYS["rolling_summary"]
        if not summary_path.is_file():
            exit_with_cli_error(
                parser,
                json_mode=args.json,
                exit_code=2,
                message=f"Missing required file: {summary_path}",
                payload=cli_failure_payload(
                    "malformed_managed_file",
                    error=f"Missing required file: {summary_path}",
                    extra=strict_gate_status_failure_extra(workspace),
                ),
            )
        summary_text = read_text(summary_path)
        summary_state = parse_file_state_marker(summary_text)
        if summary_state is None:
            exit_with_cli_error(
                parser,
                json_mode=args.json,
                exit_code=2,
                message=f"Missing required file-state metadata marker: {summary_path}",
                payload=cli_failure_payload(
                    "malformed_managed_file",
                    error=f"Missing required file-state metadata marker: {summary_path}",
                    extra=strict_gate_status_failure_extra(workspace),
                ),
            )

        try:
            state = load_workspace_state(workspace.storage_root / FILE_KEYS["state"])
        except 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=strict_gate_status_failure_extra(workspace),
                ),
            )
        provenance_metadata = state.get("provenance") if isinstance(state, dict) else None
        if (
            args.json
            and isinstance(provenance_metadata, dict)
            and provenance_metadata.get("state_label")
            == "inconsistent_or_tampered_evidence"
            and INCONSISTENT_REVIEW_EVIDENCE_KEY in provenance_metadata
        ):
            inconsistent_review_evidence = provenance_metadata.get(
                INCONSISTENT_REVIEW_EVIDENCE_KEY
            )
            if isinstance(inconsistent_review_evidence, dict):
                target_file_key = inconsistent_review_evidence.get("target_file_key")
                if isinstance(target_file_key, str):
                    inconsistent_review_target_file_key = target_file_key
            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,
            )

        context_brief_path = workspace.storage_root / FILE_KEYS["context_brief"]
        update_protocol_path = workspace.storage_root / FILE_KEYS["update_protocol"]
        context_brief_state = None
        context_brief_text = ""
        context_brief_revision_seen = _state_file_revision(state, "context_brief")
        if args.expanded and context_brief_path.is_file():
            context_brief_text = read_text(context_brief_path)
            context_brief_state = parse_file_state_marker(context_brief_text)
            if context_brief_state is None:
                exit_with_cli_error(
                    parser,
                    json_mode=args.json,
                    exit_code=2,
                    message=f"Missing required file-state metadata marker: {context_brief_path}",
                    payload=cli_failure_payload(
                        "malformed_managed_file",
                        error=f"Missing required file-state metadata marker: {context_brief_path}",
                        extra=strict_gate_status_failure_extra(workspace),
                    ),
                )
        update_protocol_state = None
        update_protocol_text = ""
        update_protocol_revision_seen = _state_file_revision(state, "update_protocol")
        if args.expanded and update_protocol_path.is_file():
            update_protocol_text = read_text(update_protocol_path)
            update_protocol_state = parse_file_state_marker(update_protocol_text)
            if update_protocol_state is None:
                exit_with_cli_error(
                    parser,
                    json_mode=args.json,
                    exit_code=2,
                    message=f"Missing required file-state metadata marker: {update_protocol_path}",
                    payload=cli_failure_payload(
                        "malformed_managed_file",
                        error=f"Missing required file-state metadata marker: {update_protocol_path}",
                        extra=strict_gate_status_failure_extra(workspace),
                    ),
                )

        try:
            latest_daily_log_cursor = validate_state_entry_bearing_latest_daily_log(
                storage_root=workspace.storage_root,
                state=state,
            )
        except DailyLogCursorError as exc:
            exit_with_cli_error(
                parser,
                json_mode=args.json,
                exit_code=2,
                message=str(exc),
                payload=cli_failure_payload(
                    "malformed_managed_file",
                    error=str(exc),
                    details={
                        **exc.details,
                        "project_root": str(workspace.project_root),
                    },
                    extra=strict_gate_status_failure_extra(workspace),
                ),
            )
        latest_daily_log = (
            latest_daily_log_cursor.latest_path if latest_daily_log_cursor is not None else None
        )
        latest_daily_log_entry = None
        latest_daily_log_text = ""
        if args.expanded and latest_daily_log is not None:
            latest_daily_log_text = read_text(latest_daily_log)
            latest_daily_log_entry = latest_daily_log_entry_info_from_text(latest_daily_log_text)
        if args.expanded and latest_daily_log is not None and latest_daily_log_entry is None:
            exit_with_cli_error(
                parser,
                json_mode=args.json,
                exit_code=2,
                message=(
                    "Missing required daily-log-entry metadata marker in the latest ISO-dated daily log: "
                    f"{latest_daily_log}"
                ),
                payload=cli_failure_payload(
                    "malformed_managed_file",
                    error=(
                        "Missing required daily-log-entry metadata marker in the latest ISO-dated daily log: "
                        f"{latest_daily_log}"
                    ),
                    extra=strict_gate_status_failure_extra(workspace),
                ),
            )

        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 is not None,
            scan_mode="quick",
            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 is not None,
        )
        if continuity_state == "initialized_empty_shell":
            digests = {
                "active_task_digest": None,
                "blocked_digest": None,
                "latest_relevant_log_digest": None,
                "suggested_handoff_sections": [],
            }

        summary_stale = freshness["summary_stale"]
        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=confidence,
        )
        actions = recommended_actions_for_status(
            continuity_confidence=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 is not None,
            summary_stale=summary_stale,
        )

        latest_active_day = parse_iso_date(latest_daily_log.stem) if latest_daily_log is not None else None
        closure_detected, closure_keywords = detect_closure_signal(latest_daily_log_text)
        project_time_policy_cues = detect_update_protocol_time_policy_cues(update_protocol_text)
        workday = build_workday_decision(
            now=now,
            rollover_hour=args.rollover_hour,
            latest_active_day=latest_active_day,
            closure_detected=closure_detected,
            summary_next_step_is_empty=(
                continuity_state == "initialized_empty_shell"
                or digests["active_task_digest"] is None
            ),
            preferred_date=preferred_date,
            session_intent=args.session_intent,
            project_time_policy_cues=project_time_policy_cues,
            host_explicit=(
                args.timezone is not None
                or args.rollover_hour != DEFAULT_LOGICAL_WORKDAY_ROLLOVER_HOUR
            ),
        )
        workday.update(
            {
                "closure_keywords": closure_keywords,
                "project_time_policy_present": update_protocol_path.is_file(),
                "project_time_policy_cues": project_time_policy_cues,
                "project_time_policy_review_required": bool(
                    project_time_policy_cues
                    and (latest_active_day is None or latest_active_day.isoformat() != workday["logical_workday"])
                ),
                "preferred_date": args.preferred_date,
            }
        )
        provenance_facts = provenance_facts_from_state(state, review_intent=False)
        trust_state = evaluate_trust_state(
            continuity_confidence=confidence,
            continuity_state=continuity_state,
            summary_stale=summary_stale,
            workspace_newer_than_summary=freshness["workspace_newer_than_summary"],
            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,
            context_brief_revision=(
                context_brief_state.revision if context_brief_state else context_brief_revision_seen
            ),
            update_protocol_revision=(
                update_protocol_state.revision
                if update_protocol_state
                else update_protocol_revision_seen
            ),
        )
        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)
        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"
        write_expected_revisions = (
            expected_revisions if strict_gate_allows_write else None
        )
        actions = strict_gate_status_actions(
            actions,
            strict_gate_allows_write=strict_gate_allows_write,
        )
        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"],
        )
        read_plan = build_status_read_plan(
            project_root=workspace.project_root,
            storage_root=workspace.storage_root,
            state=state,
            summary_path=summary_path,
            summary_text=summary_text,
            context_brief_path=context_brief_path,
            context_brief_text=context_brief_text,
            update_protocol_path=update_protocol_path,
            update_protocol_text=update_protocol_text,
            latest_daily_log=latest_daily_log,
            latest_daily_log_text=latest_daily_log_text,
            summary_stale=summary_stale,
            continuity_state=continuity_state,
            expanded=args.expanded,
        )
        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_workspace_artifact = (
            public_project_path(freshness["latest_workspace_artifact"], project_root=workspace.project_root)
            if freshness["latest_workspace_artifact"] is not None
            else None
        )
        public_latest_daily_log = (
            public_project_path(latest_daily_log, project_root=workspace.project_root)
            if latest_daily_log is not None
            else None
        )
    except (OSError, UnicodeDecodeError) as exc:
        message = f"Filesystem error: {exc}"
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=message,
            payload=cli_failure_payload(
                "damaged_sidecar",
                error=message,
                extra=strict_gate_status_failure_extra(workspace),
            ),
        )

    fast_lane_contract = {
        "read_only": True,
        "attach_safe": True,
        "receipt_store_audit_performed": False,
        "receipt_chain_scan_performed": False,
        "daily_log_content_read": bool(args.expanded and latest_daily_log is not None),
        "context_brief_read": bool(args.expanded and context_brief_path.is_file()),
        "update_protocol_read": bool(args.expanded and update_protocol_path.is_file()),
        "startup_scratch_scan_performed": False,
    }
    if inconsistent_review_result is not None:
        fast_lane_contract["receipt_store_audit_performed"] = (
            inconsistent_review_result.receipt_store_snapshot_performed
        )
        fast_lane_contract["inconsistent_review_binding_evaluation_performed"] = True
        fast_lane_contract["inconsistent_review_target_read_performed"] = (
            inconsistent_review_result.target_read_performed
        )
        fast_lane_contract["inconsistent_review_material_scan_performed"] = (
            inconsistent_review_result.material_scan_performed
        )
        if inconsistent_review_result.target_read_performed:
            if inconsistent_review_target_file_key == "daily_log":
                fast_lane_contract["daily_log_content_read"] = True
            elif inconsistent_review_target_file_key == "context_brief":
                fast_lane_contract["context_brief_read"] = True
            elif inconsistent_review_target_file_key == "update_protocol":
                fast_lane_contract["update_protocol_read"] = True

    payload = {
        "schema_version": "1.1",
        "status_mode": "expanded" if args.expanded else "fast",
        "fast_lane_contract": fast_lane_contract,
        "project_root": public_project_root,
        "storage_root": public_storage_root,
        "timezone": zone_label,
        "now": now.isoformat(),
        "workspace_revision": state["workspace_revision"],
        "rolling_summary_revision": summary_state.revision,
        "workspace_artifact_scan_mode": freshness["workspace_artifact_scan_mode"],
        "workspace_artifact_scan_performed": freshness["workspace_artifact_scan_performed"],
        "latest_workspace_artifact": public_latest_workspace_artifact,
        "workspace_artifact_newer_than_summary": freshness["workspace_artifact_newer_than_summary"],
        "summary_revision_stale": freshness["summary_revision_stale"],
        "workspace_newer_than_summary": freshness["workspace_newer_than_summary"],
        "summary_stale": summary_stale,
        "continuity_confidence": 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_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": actions,
        "read_plan": read_plan,
        "estimated_tokens": read_plan["standard"]["estimated_tokens"],
        "latest_active_daily_log": public_latest_daily_log,
        "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,
            "context_brief_revision_seen": (
                context_brief_state.revision if context_brief_state else context_brief_revision_seen
            ),
            "update_protocol_revision_seen": (
                update_protocol_state.revision
                if update_protocol_state
                else update_protocol_revision_seen
            ),
            "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 is not None
                else _state_latest_entry_seq(state)
            ),
            "logical_workday_seen": workday["logical_workday"],
            "continuity_confidence": confidence,
            "continuity_state": continuity_state,
            "continuity_seeded": continuity_seeded,
            "task_type": "status_review",
        },
        "workday": workday,
    }
    user_summary = read_surface_user_summary(
        surface="Status",
        summary_stale=summary_stale,
        strict_sidecar_integrity_gate=strict_gate_summary,
        continuity_drift_risk_level=trust_state["continuity_drift_risk_level"],
        continuity_state=continuity_state,
    )
    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.json:
        if startup_residue_report is not None:
            payload["startup_residue_report"] = startup_residue_report
        print(json.dumps(payload, ensure_ascii=False, indent=2))
    else:
        print_user_summary("RecallLoom status", user_summary)
        print(f"RecallLoom root: {public_project_root}")
        print(f"Continuity confidence: {confidence}")
        if freshness_risk["note"]:
            print(f"Freshness risk: {freshness_risk['level']} - {freshness_risk['note']}")
        print(f"Continuity state: {continuity_state}")
        print("Recommended actions:")
        for action in actions:
            print(f"  - {action}")
        guidance = describe_workday_guidance(workday, always_show=False)
        if guidance:
            print(f"Workday guidance: {guidance}")


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