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

View on GitHub
#!/usr/bin/env python3
"""Inspect or remove a RecallLoom project write lock."""

from __future__ import annotations

import argparse
import json

from _common import (
    cli_failure_payload,
    cli_failure_payload_for_exception,
    ConfigContractError,
    EnvironmentContractError,
    enforce_package_support_gate,
    LockBusyError,
    StorageResolutionError,
    ensure_supported_python_version,
    exit_with_cli_error,
    exit_with_failure_contract,
    find_recovery_project_root,
    pid_is_alive,
    public_json_payload,
    project_lock_path,
)
from core.workspace import runtime as workspace_runtime


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Inspect or remove a RecallLoom project write lock."
    )
    parser.add_argument(
        "path",
        nargs="?",
        default=".",
        help="Project path or a descendant path. Defaults to the current working directory.",
    )
    parser.add_argument(
        "--yes",
        action="store_true",
        help="Remove the lock file. Without this flag, the script only reports lock state.",
    )
    parser.add_argument(
        "--force",
        action="store_true",
        help="Allow lock removal even if the recorded pid still appears alive.",
    )
    parser.add_argument("--json", action="store_true", help="Print structured JSON output.")
    return parser


def resolve_project_root(path_arg: str):
    return find_recovery_project_root(path_arg)


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,
        action_name="unlock_write_lock.py",
        action_level="mutating" if args.yes else "diagnostic",
    )

    try:
        project_root = resolve_project_root(args.path)
        lock_path = project_lock_path(project_root)
    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"),
        )
    except (OSError, UnicodeDecodeError) as exc:
        message = f"Filesystem error: {exc}"
        exit_with_failure_contract(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=message,
            reason="damaged_sidecar",
        )

    # Manual unlock goes through the same internal guard and identity
    # verification as acquire/reclaim/finalizer (v0.5.0 plan §7.7): hold the
    # guard first, observe no-follow, and unlink only while the observed
    # identity+instance token still match. The guard never appears in output.
    try:
        with workspace_runtime.workspace_lock_guard(project_root):
            observation = workspace_runtime.observe_workspace_lock(lock_path)
            if observation.anomaly is not None:
                exit_with_failure_contract(
                    parser,
                    json_mode=args.json,
                    exit_code=2,
                    message=(
                        "Refusing to inspect or remove the write lock because the lock path "
                        f"is not a regular file: {lock_path}"
                    ),
                    reason="damaged_sidecar",
                )
            lock_exists = observation.exists
            lock_payload = observation.payload if lock_exists else {}
            lock_pid = lock_payload.get("pid")
            pid_alive = bool(isinstance(lock_pid, int) and pid_is_alive(lock_pid))

            if args.yes and lock_exists and pid_alive and not args.force:
                exit_with_failure_contract(
                    parser,
                    json_mode=args.json,
                    exit_code=3,
                    message=(
                        "Refusing to remove the write lock because the recorded pid still appears alive. "
                        "Re-run with --force only if you are sure the lock is stale."
                    ),
                    reason="write_lock_busy",
                    details={
                        "project_root": str(project_root),
                        "lock_path": str(lock_path),
                        "lock_payload": lock_payload,
                    },
                )

            removed = False
            if args.yes and lock_exists:
                try:
                    removed = workspace_runtime.remove_workspace_lock_if_unchanged(
                        lock_path,
                        expected_identity=observation.identity,
                        expected_token=lock_payload.get("instance_token"),
                    )
                except OSError as exc:
                    message = f"Filesystem error while removing write lock {lock_path}: {exc}"
                    exit_with_failure_contract(
                        parser,
                        json_mode=args.json,
                        exit_code=2,
                        message=message,
                        reason="damaged_sidecar",
                    )
            if args.yes and lock_exists and not removed:
                # The final identity+token re-check refused the unlink: never
                # report a false success.
                exit_with_failure_contract(
                    parser,
                    json_mode=args.json,
                    exit_code=3,
                    message=(
                        "Refusing to remove the write lock because it changed while removal "
                        "was being verified. Re-run to re-inspect the lock before retrying."
                    ),
                    reason="write_lock_busy",
                    details={
                        "project_root": str(project_root),
                        "lock_path": str(lock_path),
                        "lock_payload": lock_payload,
                    },
                )
    except LockBusyError as exc:
        # Guard unavailable (held by another operation, unsupported backend, or
        # a guard-identity anomaly): fail closed as lock-busy.
        exit_with_failure_contract(
            parser,
            json_mode=args.json,
            exit_code=3,
            message=str(exc),
            reason="write_lock_busy",
            details={
                "project_root": str(project_root),
                "lock_path": str(lock_path),
            },
        )
    except (OSError, UnicodeDecodeError) as exc:
        message = f"Filesystem error: {exc}"
        exit_with_failure_contract(
            parser,
            json_mode=args.json,
            exit_code=2,
            message=message,
            reason="damaged_sidecar",
        )

    payload = {
        "project_root": str(project_root),
        "lock_path": str(lock_path),
        "dry_run": not args.yes,
        "force": args.force,
        "lock_exists": lock_exists,
        "lock_payload": lock_payload if lock_payload else None,
        "pid_alive": pid_alive,
        "removed": removed,
    }

    if args.json:
        print(
            json.dumps(
                public_json_payload(payload, project_root=project_root),
                ensure_ascii=False,
                indent=2,
            )
        )
    else:
        if not lock_exists:
            print(f"No RecallLoom write lock found at {lock_path}.")
        elif args.yes:
            print(f"Removed RecallLoom write lock: {lock_path}")
        else:
            print(f"RecallLoom write lock found: {lock_path}")
            if lock_payload:
                print(f"  owner: {lock_payload.get('owner', 'unknown')}")
                print(f"  pid: {lock_payload.get('pid', 'unknown')}")
                print(f"  created_at: {lock_payload.get('created_at', 'unknown')}")
            print(f"  pid_alive: {'yes' if pid_alive else 'no'}")


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