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/support/policy.py

View on GitHub
"""Package support state and action-gating policy."""

from __future__ import annotations

from pathlib import Path
import re


PACKAGE_SUPPORT_STATES = {
    "supported",
    "upgrade_recommended",
    "readonly_only",
    "diagnostic_only",
    "unknown_offline",
}

ACTION_LEVELS = {"diagnostic", "readonly", "mutating"}

SCRIPT_ACTION_LEVELS = {
    "detect_project_root.py": "diagnostic",
    "validate_context.py": "diagnostic",
    "summarize_continuity_status.py": "diagnostic",
    "unlock_write_lock.py": "diagnostic",
    "sync_contract_docs.py": "mutating",
    "query_continuity.py": "readonly",
    "preflight_context_check.py": "readonly",
    "recommend_workday.py": "readonly",
    "generate_coldstart_proposal.py": "readonly",
    "prepare_recovery_promotion.py": "readonly",
    "init_context.py": "mutating",
    "manage_entry_bridge.py": "mutating",
    "commit_context_file.py": "mutating",
    "append_daily_log_entry.py": "mutating",
    "archive_logs.py": "mutating",
    "stage_recovery_proposal.py": "mutating",
    "record_recovery_review.py": "mutating",
    "remove_context.py": "mutating",
    "install_native_commands.py": "mutating",
    "repair_daily_log_cursor.py": "readonly",
}

DISPATCHER_ACTION_LEVELS = {
    "validate": "diagnostic",
    "status": "diagnostic",
    "resume": "readonly",
    "quick-summary": "diagnostic",
    "record": "readonly",
    "init": "mutating",
    "bridge": "mutating",
    "append": "mutating",
    "write": "mutating",
    "sync-current-state-after-append": "mutating",
    "repair-daily-log-cursor": "readonly",
}

SEMVER_RE = re.compile(r"^[0-9]+\.[0-9]+(?:\.[0-9]+)*$")


def parse_version(value: str | None) -> tuple[int, ...]:
    if not isinstance(value, str) or not SEMVER_RE.match(value):
        raise ValueError(f"Invalid version string: {value!r}")
    return tuple(int(part) for part in value.split("."))


def compare_versions(left: str | None, right: str | None) -> int:
    left_parts = parse_version(left)
    right_parts = parse_version(right)
    max_len = max(len(left_parts), len(right_parts))
    left_parts = left_parts + (0,) * (max_len - len(left_parts))
    right_parts = right_parts + (0,) * (max_len - len(right_parts))
    if left_parts < right_parts:
        return -1
    if left_parts > right_parts:
        return 1
    return 0


def version_lt(left: str | None, right: str | None) -> bool:
    if not right:
        return False
    return compare_versions(left, right) < 0


def normalize_advisory(raw: dict) -> dict:
    if not isinstance(raw, dict):
        raise ValueError("Package support advisory must be a JSON object.")
    advisory = dict(raw)
    for field in ("latest_version", "minimum_mutating_version", "minimum_readonly_version"):
        value = advisory.get(field)
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"{field} must be a non-empty string.")
        try:
            parse_version(value)
        except ValueError as exc:
            raise ValueError(f"{field} must use dotted numeric version form such as '0.3.4'.") from exc
    advisory_level = advisory.get("advisory_level", "supported")
    if advisory_level not in {
        "supported",
        "upgrade_recommended",
        "readonly_only",
        "diagnostic_only",
        "upgrade_required",
    }:
        raise ValueError(f"Unsupported advisory_level: {advisory_level}")
    update_hints = advisory.get("update_hints")
    if update_hints is not None and not isinstance(update_hints, dict):
        raise ValueError("update_hints must be an object when present.")
    return advisory


def support_state_from_advisory(package_version: str, advisory: dict) -> str:
    advisory = normalize_advisory(advisory)
    if version_lt(package_version, advisory.get("minimum_readonly_version")):
        return "diagnostic_only"
    if version_lt(package_version, advisory.get("minimum_mutating_version")):
        return "readonly_only"

    advisory_level = advisory.get("advisory_level", "supported")
    below_latest = version_lt(package_version, advisory.get("latest_version"))
    if advisory_level == "diagnostic_only":
        return "diagnostic_only"
    if advisory_level == "readonly_only":
        return "readonly_only"
    if advisory_level in {"upgrade_recommended", "upgrade_required"} and below_latest:
        return "upgrade_recommended"
    return "supported"


def action_level_for_script(script_name: str) -> str:
    return SCRIPT_ACTION_LEVELS.get(script_name, "readonly")


def _normalize_dispatcher_command(command: str) -> str:
    if command.startswith("recallloom.py "):
        return command.split(None, 1)[1]
    return command


def action_level_for_dispatcher(command: str, *, apply: bool = False) -> str:
    command = _normalize_dispatcher_command(command)
    if command == "repair-daily-log-cursor":
        return "mutating" if apply else "readonly"
    return DISPATCHER_ACTION_LEVELS.get(command, "readonly")


def action_allowed(state: str, action_level: str) -> bool:
    if action_level not in ACTION_LEVELS:
        action_level = "readonly"
    if state not in PACKAGE_SUPPORT_STATES:
        return action_level == "diagnostic"
    if state in {"supported", "upgrade_recommended"}:
        return True
    if state == "unknown_offline":
        return True
    if state == "readonly_only":
        return action_level in {"diagnostic", "readonly"}
    if state == "diagnostic_only":
        return action_level == "diagnostic"
    return True


def install_topology_reason(package_root: Path, *, source: str | None = None) -> str:
    if source in {"stale_cache", "offline_fallback"}:
        return "offline_cached_state_used"
    if package_root.is_symlink():
        return "wrapper_may_be_outdated"

    parts = [part.lower() for part in package_root.parts]
    looks_like_package_root = (
        (package_root / "scripts" / "recallloom.py").is_file()
        or (package_root / "package-metadata.json").is_file()
    )
    if package_root.name != "recallloom" and (
        looks_like_package_root
        or any(marker in parts for marker in (".agents", ".codex", "skills", "node_modules"))
    ):
        return "wrapper_may_be_outdated"
    for marker in (".agents", ".codex"):
        if marker not in parts:
            continue
        marker_index = parts.index(marker)
        owner_segment = parts[marker_index - 1] if marker_index > 0 else ""
        if owner_segment in {"home", "user", "users", Path.home().name.lower()}:
            return "user_install_outdated"
        return "project_copy_outdated"
    if "node_modules" in parts:
        return "wrapper_may_be_outdated"
    return "unknown_install_topology"


def invalid_support_advisory_user_message() -> str:
    return (
        "RecallLoom received an invalid package support advisory, so only diagnostic actions are "
        "available until the advisory is corrected or refreshed."
    )


def invalid_support_advisory_update_hints() -> dict[str, str]:
    return {
        "support_diagnostic": "Run a read-only support diagnostic before retrying.",
        "refresh_support_advisory": "Correct or refresh the configured package support advisory, then retry.",
    }


def invalid_support_cache_user_message() -> str:
    return (
        "The local package support cache is invalid, so offline use is limited to diagnostics. "
        "Refresh support while online so RecallLoom can replace the cache, or remove the invalid "
        "package-scoped local support cache and retry."
    )


def invalid_support_cache_update_hints() -> dict[str, str]:
    return {
        "support_diagnostic": "Run a read-only support diagnostic before retrying.",
        "refresh_support_cache": (
            "Reconnect and rerun the support check so RecallLoom can atomically replace the invalid local cache."
        ),
        "remove_invalid_support_cache": (
            "Remove the invalid package-scoped local support cache, then rerun the support check."
        ),
    }


def support_cache_repair_failed_user_message() -> str:
    return (
        "The online support advisory was applied, but the invalid local support cache could not be replaced. "
        "Retry the support check while online or remove the invalid package-scoped local support cache before "
        "relying on offline support state."
    )


def user_message_for_state(state: str) -> str:
    if state == "readonly_only":
        return "This RecallLoom package needs an upgrade before mutating actions can continue."
    if state == "diagnostic_only":
        return "This RecallLoom package is only allowed to run diagnostic actions until it is upgraded."
    if state == "upgrade_recommended":
        return "A newer RecallLoom package is available, but this action is still allowed."
    if state == "unknown_offline":
        return "RecallLoom could not refresh package support status today; local actions remain available."
    return "This RecallLoom package is currently supported."
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