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

View on GitHub
#!/usr/bin/env python3
"""Archive old RecallLoom daily logs."""

from __future__ import annotations

import argparse
import json
from pathlib import Path
import shutil

from core.provenance.state import helper_write_gate_from_state

from _common import (
    cli_failure_payload,
    cli_failure_payload_for_exception,
    ConfigContractError,
    DAILY_LOGS_DIRNAME,
    daily_log_cursor_from_text,
    DailyLogCursorError,
    EnvironmentContractError,
    enforce_package_support_gate,
    exit_with_cli_error,
    LockBusyError,
    rollback_moved_files,
    StorageResolutionError,
    dump_json,
    ensure_supported_python_version,
    find_recallloom_root,
    invalid_iso_like_daily_log_files,
    load_workspace_state,
    now_iso_timestamp,
    parse_iso_date,
    public_json_payload,
    sorted_active_daily_log_files,
    sorted_daily_log_files,
    workspace_write_lock,
)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description=(
            "Preview candidates for archiving old RecallLoom daily logs. Archive apply is "
            "currently unsupported and blocked."
        )
    )
    parser.add_argument("path", nargs="?", default=".", help="Project path or a descendant path.")
    parser.add_argument(
        "--max-active",
        type=int,
        default=None,
        help="Maximum number of active daily logs to keep before archiving older ones.",
    )
    parser.add_argument(
        "--before",
        help="Archive logs older than this ISO date (YYYY-MM-DD).",
    )
    parser.add_argument(
        "--yes",
        action="store_true",
        help=(
            "Legacy archive-apply confirmation flag. It is currently unsupported and blocked; "
            "the script remains preview-only."
        ),
    )
    parser.add_argument("--json", action="store_true", help="Print structured JSON output.")
    return parser


def enforce_provenance_write_gate(parser, *, json_mode: bool, state: dict) -> None:
    gate = helper_write_gate_from_state(
        state,
        helper_name="archive_logs.py",
        operation_class="daily_log_archive",
        require_preflight_for_review_imported_baseline=True,
    )
    if gate["allowed"]:
        return
    message = (
        "Refusing to archive daily logs because archive apply is outside the v0.4.2 "
        "dispatcher-issued receipt-backed mutating surface. Use preview mode only until "
        "archive receipt support is added."
    )
    exit_with_cli_error(
        parser,
        json_mode=json_mode,
        exit_code=3,
        message=message,
        payload=cli_failure_payload(
            "unsupported_mutating_surface",
            error=message,
            details={
                "reason_code": "archive_apply_not_receipt_backed",
                "helper_name": gate["helper_name"],
                "operation_class": gate["operation_class"],
                "provenance_state": gate["provenance_state"],
                "provenance_metadata_status": gate["provenance_metadata_status"],
                "write_readiness": gate["write_readiness"],
                "side_effect": "none",
                "next_actions": ["run_archive_preview", "wait_for_archive_receipt_support"],
            },
        ),
    )


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)

    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"),
        )
    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."),
        )

    try:
        with workspace_write_lock(workspace.project_root, "archive_logs.py"):
            logs_dir = workspace.storage_root / DAILY_LOGS_DIRNAME
            archive_dir = logs_dir / "archive"
            update_protocol_path = workspace.storage_root / "update_protocol.md"
            state_path = workspace.storage_root / "state.json"
            try:
                state = load_workspace_state(state_path)
            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"),
                )
            if args.yes:
                enforce_provenance_write_gate(parser, json_mode=args.json, state=state)
            invalid_daily_logs = invalid_iso_like_daily_log_files(logs_dir)
            if invalid_daily_logs:
                invalid_paths = [str(path) for path in invalid_daily_logs]
                message = (
                    "Refusing to archive because one or more daily log filenames match the date pattern but are invalid ISO dates:\n"
                    + "\n".join(invalid_paths)
                )
                exit_with_cli_error(
                    parser,
                    json_mode=args.json,
                    exit_code=2,
                    message=message,
                    payload=cli_failure_payload(
                        "malformed_managed_file",
                        error=message,
                        details={"invalid_paths": invalid_paths},
                    ),
                )
            candidates = sorted_daily_log_files(logs_dir)

            to_archive: set[Path] = set()
            effective_max_active = args.max_active if args.max_active is not None else (10 if not args.before else None)

            if args.before:
                try:
                    cutoff = parse_iso_date(args.before)
                except ValueError:
                    message = f"Invalid --before date: {args.before}"
                    exit_with_cli_error(
                        parser,
                        json_mode=args.json,
                        exit_code=2,
                        message=message,
                        payload=cli_failure_payload(
                            "invalid_date",
                            error=message,
                            details={
                                "command": "archive",
                                "operation": "daily_log_archive",
                                "reason_code": "archive_before_date_invalid",
                                "before": args.before,
                                "side_effect": "none",
                            },
                        ),
                    )
                for path in candidates:
                    if parse_iso_date(path.stem) < cutoff:
                        to_archive.add(path)

            if effective_max_active is not None and effective_max_active < 0:
                message = "--max-active must be >= 0"
                exit_with_cli_error(
                    parser,
                    json_mode=args.json,
                    exit_code=2,
                    message=message,
                    payload=cli_failure_payload(
                        "invalid_prepared_input",
                        error=message,
                        details={
                            "command": "archive",
                            "operation": "daily_log_archive",
                            "reason_code": "archive_max_active_invalid",
                            "max_active": effective_max_active,
                            "side_effect": "none",
                        },
                    ),
                )

            if effective_max_active is not None and len(candidates) > effective_max_active:
                excess = len(candidates) - effective_max_active
                to_archive.update(candidates[:excess])

            ordered = sorted(to_archive, key=lambda path: path.stem)
            archived_targets: list[str] = []

            target_map = [(source, archive_dir / source.name) for source in ordered]
            existing_targets = [str(target) for _, target in target_map if target.exists()]
            if existing_targets:
                message = (
                    "Refusing to archive because one or more archive targets already exist:\n"
                    + "\n".join(existing_targets)
                )
                exit_with_cli_error(
                    parser,
                    json_mode=args.json,
                    exit_code=3,
                    message=message,
                    payload=cli_failure_payload(
                        "malformed_managed_file",
                        error=message,
                        details={"existing_targets": existing_targets},
                    ),
                )

            remaining_after_archive = [path for path in candidates if path not in to_archive]
            remaining_active = [path for path in sorted_active_daily_log_files(logs_dir) if path not in to_archive]
            latest_remaining = remaining_active[-1] if remaining_active else None
            latest_entry_id = None
            latest_entry_seq = 0
            entry_count = 0
            if latest_remaining is not None:
                latest_file = latest_remaining.relative_to(
                    workspace.storage_root
                ).as_posix()
                latest_text = latest_remaining.read_text(encoding="utf-8")
                try:
                    latest_cursor = daily_log_cursor_from_text(
                        latest_text,
                        path=latest_remaining,
                        latest_file=latest_file,
                    )
                except DailyLogCursorError as exc:
                    message = (
                        "Refusing to archive because the newest remaining daily log is damaged: "
                        f"{latest_remaining}. {exc}"
                    )
                    exit_with_cli_error(
                        parser,
                        json_mode=args.json,
                        exit_code=2,
                        message=message,
                        payload=cli_failure_payload(
                            "malformed_managed_file",
                            error=message,
                            details=exc.details,
                        ),
                    )
                latest_entry_id = latest_cursor.latest_entry_id
                latest_entry_seq = latest_cursor.latest_entry_seq
                entry_count = latest_cursor.entry_count

            previous_daily_state = state.get("daily_logs", {})
            next_latest_file = (
                latest_remaining.relative_to(workspace.storage_root).as_posix()
                if latest_remaining
                else None
            )
            cursor_changed = (
                previous_daily_state.get("latest_file") != next_latest_file
                or previous_daily_state.get("latest_entry_id") != latest_entry_id
                or previous_daily_state.get("latest_entry_seq") != latest_entry_seq
                or previous_daily_state.get("entry_count") != entry_count
            )

            if ordered and args.yes:
                archive_dir.mkdir(parents=True, exist_ok=True)
                applied_moves: list[tuple[Path, Path]] = []
                for source, target in target_map:
                    try:
                        shutil.move(str(source), str(target))
                    except OSError as exc:
                        if applied_moves:
                            try:
                                rollback_moved_files(applied_moves)
                            except OSError as rollback_exc:
                                message = (
                                    f"Filesystem error while archiving {source} to {target}: {exc}. "
                                    f"Rollback also failed: {rollback_exc}. Workspace may be partially updated."
                                )
                                exit_with_cli_error(
                                    parser,
                                    json_mode=args.json,
                                    exit_code=2,
                                    message=message,
                                    payload=cli_failure_payload("damaged_sidecar", error=message),
                                )
                        message = (
                            f"Filesystem error while archiving {source} to {target}: {exc}. "
                            "Any earlier moved daily logs were restored to their original locations."
                        )
                        exit_with_cli_error(
                            parser,
                            json_mode=args.json,
                            exit_code=2,
                            message=message,
                            payload=cli_failure_payload("damaged_sidecar", error=message),
                        )
                    applied_moves.append((source, target))
                    archived_targets.append(str(target))
                if cursor_changed:
                    state["workspace_revision"] += 1
                state["daily_logs"]["latest_file"] = next_latest_file
                state["daily_logs"]["latest_entry_id"] = latest_entry_id
                state["daily_logs"]["latest_entry_seq"] = latest_entry_seq
                state["daily_logs"]["entry_count"] = entry_count
                state["daily_logs"]["updated_at"] = now_iso_timestamp()
                try:
                    dump_json(state_path, state)
                except OSError as exc:
                    try:
                        rollback_moved_files(applied_moves)
                    except OSError as rollback_exc:
                        message = (
                            f"Failed to update state after archiving daily logs: {exc}. "
                            f"Rollback also failed: {rollback_exc}. Workspace may be partially updated."
                        )
                        exit_with_cli_error(
                            parser,
                            json_mode=args.json,
                            exit_code=2,
                            message=message,
                            payload=cli_failure_payload("damaged_sidecar", error=message),
                        )
                    message = (
                        f"Failed to update state after archiving daily logs: {exc}. "
                        "Moved daily logs were restored to their original locations."
                    )
                    exit_with_cli_error(
                        parser,
                        json_mode=args.json,
                        exit_code=2,
                        message=message,
                        payload=cli_failure_payload("damaged_sidecar", error=message),
                    )
            else:
                archived_targets = [str(target) for _, target in target_map]

            payload = {
                "project_root": str(workspace.project_root),
                "storage_root": str(workspace.storage_root),
                "storage_mode": workspace.storage_mode,
                "dry_run": not args.yes,
                "effective_max_active": effective_max_active,
                "update_protocol": str(update_protocol_path) if update_protocol_path.is_file() else None,
                "override_review_required": update_protocol_path.is_file(),
                "archived_count": len(ordered),
                "archived_targets": archived_targets,
                "workspace_revision_bumped": bool(ordered and args.yes and cursor_changed),
            }
    except LockBusyError as exc:
        exit_with_cli_error(
            parser,
            json_mode=args.json,
            exit_code=3,
            message=str(exc),
            payload=cli_failure_payload("write_lock_busy", error=str(exc)),
        )
    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"),
        )
    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),
        )

    if args.json:
        print(
            json.dumps(
                public_json_payload(payload, project_root=workspace.project_root),
                ensure_ascii=False,
                indent=2,
            )
        )
    else:
        action = "Would archive" if not args.yes else "Archived"
        print(f"{action} {len(ordered)} daily log(s).")
        if update_protocol_path.is_file():
            print(
                "Project-local override review required: "
                f"{update_protocol_path} may narrow archive behavior. "
                "v1 helpers do not parse natural-language override prose automatically."
            )
        for item in archived_targets:
            print(f"  - {item}")


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