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/protocol/contracts.py

View on GitHub
#!/usr/bin/env python3
"""Protocol-level constants derived from the RecallLoom contract registry."""

from __future__ import annotations

from pathlib import Path, PurePosixPath
import re

from core.registry.loader import (
    load_contract_registry,
    load_contract_schema,
    resolve_contract_registry_path,
    resolve_contract_schema_path,
)

CONTRACT_REGISTRY_PATH = resolve_contract_registry_path()
CONTRACT_SCHEMA_PATH = resolve_contract_schema_path()
CONTRACT_BOOTSTRAP_ERROR: RuntimeError | None = None


def _install_fallback_contracts(exc: RuntimeError) -> None:
    global CONTRACT_BOOTSTRAP_ERROR
    global CONTRACT_SCHEMA
    global CONTRACT_REGISTRY
    global CURRENT_PROTOCOL_VERSION
    global SUPPORTED_PROTOCOL_VERSIONS
    global DEFAULT_WORKSPACE_LANGUAGE
    global SUPPORTED_WORKSPACE_LANGUAGES
    global SUPPORTED_STORAGE_MODES
    global SUPPORTED_DYNAMIC_ASSET_RULE_KINDS
    global FILE_KEYS
    global DAILY_LOG_PATH_PATTERN
    global DAILY_LOGS_DIRNAME
    global SECTION_KEYS
    global OPTIONAL_SECTION_KEYS
    global CONTEXT_BRIEF_RENDER_ORDER
    global LABELS
    global FILE_MARKER_TEMPLATE
    global FILE_STATE_MARKER_TEMPLATE
    global DAILY_LOG_ENTRY_MARKER_TEMPLATE
    global DAILY_LOG_SCAFFOLD_MARKER_TEMPLATE
    global LAST_WRITER_MARKER_TEMPLATE
    global LAST_WRITER_RE
    global FILE_STATE_RE
    global DAILY_LOG_ENTRY_RE
    global DAILY_LOG_SCAFFOLD_RE
    global FILE_MARKER_RE
    global SECTION_MARKER_RE
    global BRIDGE_START
    global BRIDGE_END
    global EXCLUDE_BLOCK_START
    global EXCLUDE_BLOCK_END
    global ROOT_ENTRY_CANDIDATES
    global ROOT_ENTRY_CANDIDATE_STRINGS

    CONTRACT_BOOTSTRAP_ERROR = exc
    CONTRACT_SCHEMA = {}
    CONTRACT_REGISTRY = {}
    CURRENT_PROTOCOL_VERSION = "1.0"
    SUPPORTED_PROTOCOL_VERSIONS = {"1.0"}
    DEFAULT_WORKSPACE_LANGUAGE = "en"
    SUPPORTED_WORKSPACE_LANGUAGES = {"en", "zh-CN"}
    SUPPORTED_STORAGE_MODES = {"hidden", "visible"}
    SUPPORTED_DYNAMIC_ASSET_RULE_KINDS = set()
    FILE_KEYS = {
        "config": "config.json",
        "state": "state.json",
        "context_brief": "context_brief.md",
        "rolling_summary": "rolling_summary.md",
        "update_protocol": "update_protocol.md",
    }
    DAILY_LOG_PATH_PATTERN = "daily_logs/{date}.md"
    DAILY_LOGS_DIRNAME = "daily_logs"
    SECTION_KEYS = {}
    OPTIONAL_SECTION_KEYS = {}
    CONTEXT_BRIEF_RENDER_ORDER = []
    LABELS = {}
    FILE_MARKER_TEMPLATE = "<!-- recallloom:file={file_key} version={version} lang={lang} -->"
    FILE_STATE_MARKER_TEMPLATE = (
        "<!-- file-state: revision={revision} | updated-at={updated_at} | writer-id={writer_id} "
        "| base-workspace-revision={base_workspace_revision} -->"
    )
    DAILY_LOG_ENTRY_MARKER_TEMPLATE = (
        "<!-- daily-log-entry: entry-id={entry_id} | created-at={created_at} | writer-id={writer_id} "
        "| entry-seq={entry_seq} -->"
    )
    DAILY_LOG_SCAFFOLD_MARKER_TEMPLATE = "<!-- daily-log-scaffold: true -->"
    LAST_WRITER_MARKER_TEMPLATE = "<!-- last-writer: [{tool}] | {date} -->"
    LAST_WRITER_RE = re.compile(
        r"^<!-- last-writer: \[(?P<tool>[^\]]+)\] \| (?P<date>\d{4}-\d{2}-\d{2}) -->$"
    )
    FILE_STATE_RE = re.compile(
        r"^<!-- file-state: revision=(?P<revision>\d+) \| updated-at=(?P<updated_at>[^ ]+) "
        r"\| writer-id=(?P<writer_id>[^|]+?) \| base-workspace-revision=(?P<base_workspace_revision>\d+) -->$"
    )
    DAILY_LOG_ENTRY_RE = re.compile(
        r"^<!-- daily-log-entry: entry-id=(?P<entry_id>[^ ]+) \| created-at=(?P<created_at>[^ ]+) "
        r"\| writer-id=(?P<writer_id>[^|]+?) \| entry-seq=(?P<entry_seq>\d+) -->$"
    )
    DAILY_LOG_SCAFFOLD_RE = re.compile(r"^<!-- daily-log-scaffold: true -->$")
    FILE_MARKER_RE = re.compile(
        r"^<!-- recallloom:file=(?P<file_key>[a-z_]+) version=(?P<version>[0-9]+\.[0-9]+(?:\.[0-9]+)*) "
        r"lang=(?P<lang>[^ ]+) -->$"
    )
    SECTION_MARKER_RE = re.compile(r"^<!-- section: (?P<section_key>[a-z_]+) -->$")
    BRIDGE_START = "<!-- RecallLoom managed bridge start -->"
    BRIDGE_END = "<!-- RecallLoom managed bridge end -->"
    EXCLUDE_BLOCK_START = "# RecallLoom managed block start"
    EXCLUDE_BLOCK_END = "# RecallLoom managed block end"
    ROOT_ENTRY_CANDIDATES = [
        Path("AGENTS.md"),
        Path("CLAUDE.md"),
        Path("GEMINI.md"),
        Path(".github/copilot-instructions.md"),
    ]
    ROOT_ENTRY_CANDIDATE_STRINGS = {path.as_posix() for path in ROOT_ENTRY_CANDIDATES}


try:
    CONTRACT_SCHEMA = load_contract_schema(CONTRACT_SCHEMA_PATH)
    CONTRACT_REGISTRY = load_contract_registry(
        registry_path=CONTRACT_REGISTRY_PATH,
        schema_path=CONTRACT_SCHEMA_PATH,
    )

    CURRENT_PROTOCOL_VERSION = CONTRACT_REGISTRY["protocol"]["current"]
    SUPPORTED_PROTOCOL_VERSIONS = set(CONTRACT_REGISTRY["protocol"]["supported"])
    DEFAULT_WORKSPACE_LANGUAGE = CONTRACT_REGISTRY["workspace"]["languages"][0]
    SUPPORTED_WORKSPACE_LANGUAGES = set(CONTRACT_REGISTRY["workspace"]["languages"])
    SUPPORTED_STORAGE_MODES = set(CONTRACT_REGISTRY["workspace"]["storage_modes"])
    SUPPORTED_DYNAMIC_ASSET_RULE_KINDS = set(CONTRACT_REGISTRY["dynamic_asset_rule_kinds"])

    FILE_KEYS = {
        file_key: contract["path"]
        for file_key, contract in CONTRACT_REGISTRY["files"].items()
        if "path" in contract and file_key != "daily_log"
    }
    DAILY_LOG_PATH_PATTERN = CONTRACT_REGISTRY["files"]["daily_log"]["path_pattern"]
    DAILY_LOGS_DIRNAME = PurePosixPath(DAILY_LOG_PATH_PATTERN).parts[0]
    SECTION_KEYS = {
        file_key: list(contract["required_sections"])
        for file_key, contract in CONTRACT_REGISTRY["files"].items()
        if contract["required_sections"]
    }
    OPTIONAL_SECTION_KEYS = {
        file_key: list(contract["optional_sections"])
        for file_key, contract in CONTRACT_REGISTRY["files"].items()
        if contract["optional_sections"]
    }
    CONTEXT_BRIEF_RENDER_ORDER = list(CONTRACT_REGISTRY["files"]["context_brief"]["render_order"])
    LABELS = {
        language: {
            "context_brief": CONTRACT_REGISTRY["files"]["context_brief"]["labels"][language],
            "rolling_summary": CONTRACT_REGISTRY["files"]["rolling_summary"]["labels"][language],
            "daily_log": CONTRACT_REGISTRY["files"]["daily_log"]["labels"][language],
            "update_protocol": CONTRACT_REGISTRY["files"]["update_protocol"]["labels"][language],
        }
        for language in CONTRACT_REGISTRY["workspace"]["languages"]
    }

    FILE_MARKER_TEMPLATE = CONTRACT_REGISTRY["markers"]["file"]["template"]
    FILE_STATE_MARKER_TEMPLATE = CONTRACT_REGISTRY["markers"]["file_state"]["template"]
    DAILY_LOG_ENTRY_MARKER_TEMPLATE = CONTRACT_REGISTRY["markers"]["daily_log_entry"]["template"]
    DAILY_LOG_SCAFFOLD_MARKER_TEMPLATE = CONTRACT_REGISTRY["markers"]["daily_log_scaffold"]["template"]
    LAST_WRITER_MARKER_TEMPLATE = CONTRACT_REGISTRY["markers"]["last_writer"]["template"]

    LAST_WRITER_RE = re.compile(CONTRACT_REGISTRY["markers"]["last_writer"]["regex"])
    FILE_STATE_RE = re.compile(CONTRACT_REGISTRY["markers"]["file_state"]["regex"])
    DAILY_LOG_ENTRY_RE = re.compile(CONTRACT_REGISTRY["markers"]["daily_log_entry"]["regex"])
    DAILY_LOG_SCAFFOLD_RE = re.compile(CONTRACT_REGISTRY["markers"]["daily_log_scaffold"]["regex"])
    FILE_MARKER_RE = re.compile(CONTRACT_REGISTRY["markers"]["file"]["regex"])
    SECTION_MARKER_RE = re.compile(r"^<!-- section: (?P<section_key>[a-z_]+) -->$")

    BRIDGE_START = CONTRACT_REGISTRY["markers"]["bridge"]["start"]
    BRIDGE_END = CONTRACT_REGISTRY["markers"]["bridge"]["end"]
    EXCLUDE_BLOCK_START = CONTRACT_REGISTRY["markers"]["git_exclude"]["start"]
    EXCLUDE_BLOCK_END = CONTRACT_REGISTRY["markers"]["git_exclude"]["end"]

    ROOT_ENTRY_CANDIDATES = [
        Path(path_str) for path_str in CONTRACT_REGISTRY["workspace"]["bridge_targets"]
    ]
    ROOT_ENTRY_CANDIDATE_STRINGS = {path.as_posix() for path in ROOT_ENTRY_CANDIDATES}
except (RuntimeError, re.error) as exc:
    _install_fallback_contracts(exc)


def contract_bootstrap_error_message() -> str | None:
    if CONTRACT_BOOTSTRAP_ERROR is None:
        return None
    return f"RecallLoom contract registry bootstrap failed: {CONTRACT_BOOTSTRAP_ERROR}"


def validate_workspace_language(language: str) -> str:
    if language not in SUPPORTED_WORKSPACE_LANGUAGES:
        raise ValueError(f"Unsupported workspace_language: {language}")
    return language
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