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

View on GitHub
#!/usr/bin/env python3
"""Sync registry-driven contract snippets into RecallLoom docs."""

from __future__ import annotations

import argparse
import json
from pathlib import Path
import re

from core.output.privacy import publicize_json_value
from core.protocol import contracts as protocol_contracts
from _common import enforce_package_support_gate


REPO_ROOT = Path(__file__).resolve().parents[3]
REPO_ROOT_RESOLVED = REPO_ROOT.resolve()
SKILL_ROOT = Path(__file__).resolve().parents[1]
README_PATH = REPO_ROOT / "README.md"
USAGE_PATH = REPO_ROOT / "USAGE.md"
SKILL_DOC_PATH = SKILL_ROOT / "SKILL.md"

_CJK_RE = re.compile(r"[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
_LATIN_RE = re.compile(r"[A-Za-z]")
_FENCED_CODE_RE = re.compile(r"```.*?```", re.DOTALL)
_INLINE_CODE_RE = re.compile(r"`[^`]*`")
_HTML_TAG_RE = re.compile(r"<[^>]+>")
_ACTIVE_ENGLISH_RE = re.compile(r"\*\*\s*English\s*\*\*", re.IGNORECASE)
_ACTIVE_CHINESE_RE = re.compile(r"\*\*\s*简体中文\s*\*\*")


def resolve_doc_target(path_str: str) -> Path:
    path = Path(path_str)
    candidate = path.resolve() if path.is_absolute() else (REPO_ROOT / path).resolve()
    try:
        candidate.relative_to(REPO_ROOT_RESOLVED)
    except ValueError as exc:
        raise RuntimeError(
            f"Doc sync target resolves outside the repository root and is not allowed: {path_str}"
        ) from exc
    return candidate


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Sync registry-driven contract snippets into RecallLoom docs."
    )
    parser.add_argument(
        "--check",
        action="store_true",
        help="Check whether docs are already in sync without writing files.",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Print structured JSON output.",
    )
    return parser


def infer_doc_language_from_text(text: str, *, fallback: str = "en") -> str:
    active_english = _ACTIVE_ENGLISH_RE.search(text) is not None
    active_chinese = _ACTIVE_CHINESE_RE.search(text) is not None
    if active_chinese and not active_english:
        return "zh-CN"
    if active_english and not active_chinese:
        return "en"

    sample = _FENCED_CODE_RE.sub("", text)
    sample = _INLINE_CODE_RE.sub("", sample)
    sample = _HTML_TAG_RE.sub(" ", sample)
    cjk_count = len(_CJK_RE.findall(sample))
    latin_count = len(_LATIN_RE.findall(sample))
    if cjk_count >= 8 and cjk_count >= max(1, latin_count) * 0.2:
        return "zh-CN"
    return fallback


def doc_language_for_path(path: Path) -> str:
    if path.name.endswith(".zh-CN.md"):
        return "zh-CN"
    if path.name.endswith(".en.md"):
        return "en"
    try:
        return infer_doc_language_from_text(path.read_text(encoding="utf-8"))
    except OSError:
        return "en"


def render_runtime_requirements_block(*, language: str) -> str:
    minimum_python_version = json.loads((SKILL_ROOT / "package-metadata.json").read_text(encoding="utf-8"))[
        "minimum_python_version"
    ]
    if language == "zh-CN":
        lines = [
            f"- Python 版本要求:`{minimum_python_version}` 及以上",
            "- 支持的工作区语言:",
        ]
    else:
        lines = [
            f"- minimum Python version: `{minimum_python_version}`",
            "- supported `workspace_language` values:",
        ]
    for workspace_language in protocol_contracts.CONTRACT_REGISTRY["workspace"]["languages"]:
        lines.append(f"  - `{workspace_language}`")
    lines.append("- 支持的入口桥接文件:" if language == "zh-CN" else "- supported root entry files for thin bridges:")
    for target in protocol_contracts.CONTRACT_REGISTRY["workspace"]["bridge_targets"]:
        lines.append(f"  - `{target}`")
    return "\n".join(lines)


def render_package_metadata_block(*, language: str) -> str:
    package_metadata = json.loads((SKILL_ROOT / "package-metadata.json").read_text(encoding="utf-8"))
    if language == "zh-CN":
        lines = [
            f"- 包版本:`{package_metadata['package_version']}`",
            f"- 协议版本:`{package_metadata['protocol_version']}`",
            "- 当前支持的协议版本:",
        ]
    else:
        lines = [
            f"- package version: `{package_metadata['package_version']}`",
            f"- protocol version: `{package_metadata['protocol_version']}`",
            "- supported protocol versions:",
        ]
    for version in package_metadata["supported_protocol_versions"]:
        lines.append(f"  - `{version}`")
    return "\n".join(lines)


def render_runtime_assumptions_block(*, language: str) -> str:
    package_metadata = json.loads((SKILL_ROOT / "package-metadata.json").read_text(encoding="utf-8"))
    if language == "zh-CN":
        lines = [
            f"- Python 版本要求:`{package_metadata['minimum_python_version']}` 及以上",
            "- 支持的工作区语言:",
        ]
    else:
        lines = [
            f"- Python {package_metadata['minimum_python_version']} or newer",
            "- supported workspace languages:",
        ]
    for workspace_language in package_metadata["supported_workspace_languages"]:
        lines.append(f"  - `{workspace_language}`")
    lines.append("- 支持的入口桥接文件:" if language == "zh-CN" else "- supported bridge targets:")
    for target in package_metadata["supported_bridge_targets"]:
        lines.append(f"  - `{target}`")
    return "\n".join(lines)


def render_protocol_registry_summary_block() -> str:
    lines = [
        "- current protocol version:",
        f"  - `{protocol_contracts.CURRENT_PROTOCOL_VERSION}`",
        "- supported protocol versions:",
    ]
    for version in sorted(protocol_contracts.SUPPORTED_PROTOCOL_VERSIONS):
        lines.append(f"  - `{version}`")
    lines.extend(
        [
            "- supported `workspace_language` values:",
        ]
    )
    for language in sorted(protocol_contracts.SUPPORTED_WORKSPACE_LANGUAGES):
        lines.append(f"  - `{language}`")
    lines.append("- allowed `storage_mode` values:")
    for mode in sorted(protocol_contracts.SUPPORTED_STORAGE_MODES):
        lines.append(f"  - `{mode}`")
    lines.append("- supported root entry files for thin bridges:")
    for target in protocol_contracts.CONTRACT_REGISTRY["workspace"]["bridge_targets"]:
        lines.append(f"  - `{target}`")
    lines.append("- supported dynamic asset rule kinds:")
    for kind in sorted(protocol_contracts.SUPPORTED_DYNAMIC_ASSET_RULE_KINDS):
        lines.append(f"  - `{kind}`")
    return "\n".join(lines)


def render_file_contract_registry_summary_block() -> str:
    lines = ["Generated from `references/contract-registry.json`.", ""]
    for file_key, contract in protocol_contracts.CONTRACT_REGISTRY["files"].items():
        path_label = contract.get("path", contract.get("path_pattern", "(dynamic)"))
        lines.append(f"### `{file_key}`")
        lines.append("")
        lines.append(f"- path: `{path_label}`")
        required = contract.get("required_sections", [])
        optional = contract.get("optional_sections", [])
        render_order = contract.get("render_order", [])
        lines.append("- required sections:")
        if required:
            for item in required:
                lines.append(f"  - `{item}`")
        else:
            lines.append("  - none")
        lines.append("- optional sections:")
        if optional:
            for item in optional:
                lines.append(f"  - `{item}`")
        else:
            lines.append("  - none")
        lines.append("- render order:")
        if render_order:
            for item in render_order:
                lines.append(f"  - `{item}`")
        else:
            lines.append("  - none")
        lines.append("")
    return "\n".join(lines).rstrip()


def render_block(block_name: str, *, language: str) -> str:
    if block_name == "package-metadata":
        return render_package_metadata_block(language=language)
    if block_name == "runtime-assumptions":
        return render_runtime_assumptions_block(language=language)
    if block_name == "runtime-requirements":
        return render_runtime_requirements_block(language=language)
    if block_name == "protocol-registry-summary":
        return render_protocol_registry_summary_block()
    if block_name == "file-contract-registry-summary":
        return render_file_contract_registry_summary_block()
    raise KeyError(block_name)


def replace_sync_block(text: str, block_name: str, rendered: str) -> str:
    start_marker = f"<!-- RecallLoom metadata sync start: {block_name} -->"
    end_marker = f"<!-- RecallLoom metadata sync end: {block_name} -->"
    if start_marker not in text or end_marker not in text:
        raise RuntimeError(
            f"Missing sync markers for block '{block_name}'. "
            "Add start/end markers before running sync."
        )
    start_idx = text.index(start_marker) + len(start_marker)
    end_idx = text.index(end_marker)
    middle = "\n" + rendered.rstrip() + "\n"
    return text[:start_idx] + middle + text[end_idx:]


def main() -> None:
    parser = build_parser()
    args = parser.parse_args()
    enforce_package_support_gate(
        parser,
        json_mode=args.json,
        action_name="sync_contract_docs.py",
        action_level="diagnostic" if args.check else "mutating",
    )

    changed_files: list[str] = []
    checked_files: list[str] = []
    seen_changed: set[str] = set()
    seen_checked: set[str] = set()

    sync_blocks = protocol_contracts.CONTRACT_REGISTRY["doc_sync_blocks"]
    for block_name, block in sync_blocks.items():
        for target in block["targets"]:
            path = resolve_doc_target(target)
            rendered = render_block(block_name, language=doc_language_for_path(path))
            original = path.read_text(encoding="utf-8")
            updated = replace_sync_block(original, block_name, rendered)
            path_str = str(path)
            if path_str not in seen_checked:
                seen_checked.add(path_str)
                checked_files.append(path_str)
            if updated != original:
                if path_str not in seen_changed:
                    seen_changed.add(path_str)
                    changed_files.append(path_str)
                if not args.check:
                    path.write_text(updated, encoding="utf-8")

    if args.check and changed_files:
        payload = {
            "ok": False,
            "changed_files": changed_files,
            "checked_files": checked_files,
        }
        if args.json:
            public_payload = publicize_json_value(payload, project_root=REPO_ROOT)
            print(json.dumps(public_payload, ensure_ascii=False, indent=2))
        raise SystemExit(1)

    payload = {
        "ok": True,
        "changed_files": changed_files,
        "checked_files": checked_files,
        "mode": "check" if args.check else "write",
    }
    if args.json:
        public_payload = publicize_json_value(payload, project_root=REPO_ROOT)
        print(json.dumps(public_payload, ensure_ascii=False, indent=2))
    else:
        if changed_files:
            action = "Would update" if args.check else "Updated"
            print(f"{action} {len(changed_files)} doc file(s).")
            for path in changed_files:
                print(f"- {path}")
        else:
            print("Docs already in sync.")


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